docs: design Local G2 diagnostic visualization
This commit is contained in:
梁薄云
@@ -0,0 +1,104 @@
|
||||
# Local G2 Diagnostic Visualization Design
|
||||
|
||||
## Goal
|
||||
|
||||
Extend the existing offline path-smoothing visualization flow so that a reviewer can see both the current published Local G2 result and the actual rejected Local G2 diagnostic candidate for the `single-turn` fixture. The output must make clear that the candidate was rejected for clearance and was not published as a path-smoothing result.
|
||||
|
||||
## Context And Evidence Boundary
|
||||
|
||||
The frozen Local G2 excursion measurement concluded `QUALITY_RED` with no authorization to change the evaluator. The selected evidence record is:
|
||||
|
||||
- Fixture: `single-turn`
|
||||
- Stable key: `single-turn/s0/r0/w5/seed2`
|
||||
- Candidate index: `5`
|
||||
- Window: `[1.92 m, 2.12 m]`
|
||||
- Observed stop gate: `Clearance`
|
||||
- Observed result: `InsufficientClearance`
|
||||
- Strict Local G2 publication state: `Unchanged`
|
||||
- Fixture SHA-256: `3d05daee5a211b3e7aa0b77193423b5fa07d3135e241a4413be3518fc7efe563`
|
||||
- Source measurement-batch SHA-256: `ac8166828813d85bf6f8b58f985839e5b2a049e75cb94186ed04f59d540e4eed`
|
||||
|
||||
The diagnostic geometry is evidence only. It must never enter `PathSmoothingResult.PublishLocalG2`, participate in recommendation ranking, or be reported as a feasible/successful smoothing result.
|
||||
|
||||
## Chosen Design
|
||||
|
||||
### 1. Add Local G2 To The Standard Offline Comparison
|
||||
|
||||
`PathSmoothingComparisonRequest` will include `SmoothingMethod.LocalG2Quintic` in its default ordered methods. The standard six figures and CSV will therefore include the normal Local G2 call alongside the existing three smoothers.
|
||||
|
||||
For this evidence set, the Local G2 entry is expected to carry `Unchanged`; its path is the strictly validated final path, which is geometrically the same as the raw baseline. The standard figures and CSV must retain that status rather than fabricate success metrics. Local G2 will be visible in the all-path and curvature comparisons using a dedicated color.
|
||||
|
||||
### 2. Export A Separate Rejected-Candidate Figure
|
||||
|
||||
A test/demo-only diagnostic route will reconstruct the selected rejected candidate from a compact, immutable evidence extract committed under `PathSmoothing/Test/Fixtures/`. The extract will contain the source measurement-batch SHA-256, fixture SHA-256, stable key, window, selected candidate points, and observed rejection fields. It is a provenance-preserving subset of the frozen measurement batch, not a new optimizer input.
|
||||
|
||||
The diagnostic route will:
|
||||
|
||||
1. Load and validate the evidence extract and its required identity/rejection fields.
|
||||
2. Load the matching `single-turn` fixture request and run the existing preprocessor.
|
||||
3. Recreate a `LocalG2CandidateGeometry` from the recorded sample points, splice it into the prepared coarse path, and run the existing geometry analyzer solely to provide renderable points and curvature samples.
|
||||
4. Build the normal comparison model, append one diagnostic-only series, and use the existing report exporter.
|
||||
|
||||
The exporter will publish the regular six figures plus `07-local-g2-diagnostic-candidate.{svg,png}`. The diagnostic figure will show:
|
||||
|
||||
- the Hybrid A* raw path, labelled as also representing the strict final `Unchanged` output;
|
||||
- the recorded Local G2 diagnostic candidate, labelled `净空拒绝，未发布`;
|
||||
- map context, start/goal markers, and the same point-only rendering convention as the existing figures.
|
||||
|
||||
The raw path and strict final output share the same coordinates, so they will be represented by one raw-path series with an explicit label instead of two perfectly overlapping series. The diagnostic candidate gets no collision marker because the evidence establishes a clearance rejection, not an occupied-cell collision. It gets no quality-metric CSV row; the CSV retains the actual normal Local G2 `Unchanged` row.
|
||||
|
||||
### 3. Keep Production Acceptance Behavior Untouched
|
||||
|
||||
No change is permitted to the Local G2 evaluator, validator, pipeline, publication semantics, recommendation ranker, or vehicle/map checks. The evidence loader and reconstruction code live under the offline `PathSmoothing/Test` boundary. A malformed, mismatched, non-finite, or non-clearance-rejected extract must fail export without publishing partial files.
|
||||
|
||||
## Components
|
||||
|
||||
- `Comparison/PathSmoothingComparisonRequest.cs`: add Local G2 to the default comparison order.
|
||||
- `Visualization/IeeeFigureStyle.cs`: add distinct normal Local G2 and rejected-diagnostic colors.
|
||||
- `Visualization/SmoothingFigureModelBuilder.cs`: add the normal Local G2 series and metric row.
|
||||
- `Visualization/SmoothingFigureModel.cs`: provide an internal immutable copy operation for appending one uniquely keyed diagnostic series without changing the standard model API.
|
||||
- `Visualization/SmoothingFigureKind.cs` and `Visualization/SmoothingFigureSetBuilder.cs`: append the seventh diagnostic figure only when the model contains the diagnostic series; preserve the existing six-file order for normal models.
|
||||
- `Test/Fixtures/local-g2-diagnostic-single-turn.json`: compact immutable evidence extract tied to the formal measurement batch.
|
||||
- `Test/LocalG2DiagnosticEvidenceLoader.cs`: parse and validate the extract.
|
||||
- `Test/LocalG2DiagnosticVisualizationDemo.cs`: reconstruct the visual-only candidate, build the augmented model, and export it.
|
||||
- `tests/PathSmoothingPngVerificationHost/Program.cs`: add explicit verification/export commands for this diagnostic report.
|
||||
- `tests/run_local_g2_diagnostic_visualization.ps1`: build and run the dedicated export into `ClumsyPilot/obj/path_smoothing_reports/local-g2-single-turn`.
|
||||
|
||||
## Visual Contract
|
||||
|
||||
- Continue rendering trajectories as discrete point samples; do not introduce joined paths or dashed strokes.
|
||||
- Use the existing fixed-size IEEE report layout and fonts.
|
||||
- Preserve the existing six stems for normal exports exactly: `01` through `06`.
|
||||
- Use `07-local-g2-diagnostic-candidate` only for the augmented diagnostic model.
|
||||
- Use unambiguous Chinese labels that distinguish raw/final `Unchanged` output from the rejected and unpublished diagnostic candidate.
|
||||
- The diagnostic figure title and legend, not a misleading success status or collision marker, communicate the reason for rejection.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. A normal default comparison contains Local G2 exactly once, in deterministic order after `PiecewiseQuintic`; its entry preserves the true pipeline status and cannot become a recommendation unless the existing ranker independently deems it eligible.
|
||||
2. Standard six-figure exports remain six files in the same ordered stems; all-path and curvature figures include the normal Local G2 series and CSV includes a `LocalG2Quintic` row.
|
||||
3. The dedicated diagnostic exporter validates the committed extract, reconstructs the specified `single-turn/s0/r0/w5/seed2` candidate, and exports a seventh PNG/SVG named `07-local-g2-diagnostic-candidate`.
|
||||
4. The seventh figure visibly contains the raw/final path and the diagnostic candidate, and its text states both `净空拒绝` and `未发布`; it does not state or imply that the candidate was successful or published.
|
||||
5. The diagnostic export rejects bad identity, bad fixture hash, missing candidate data, non-finite values, or a non-clearance rejection without leaving partial output files.
|
||||
6. Existing comparison, SVG/CSV, and PNG verification continue to pass. New diagnostic verification checks the seven-file export contract, selected provenance fields, SVG labels/series, valid PNG bytes, and the actual output image is inspected with the local image viewer.
|
||||
7. No files under `PathSmoothing/LocalG2/` or production acceptance/validation code are changed for this visualization work.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This work does not retry, tune, repair, or relax Local G2 candidate evaluation.
|
||||
- This work does not claim the diagnostic curve is drivable, collision-free, clearance-safe, or a substitute for the strict final output.
|
||||
- This work does not change the existing daily-work report conclusions; it only makes the measured candidate and its publication boundary inspectable.
|
||||
|
||||
## Invocation And Output
|
||||
|
||||
The dedicated script will produce the view requested in this task:
|
||||
|
||||
```powershell
|
||||
.\ClumsyPilot\tests\run_local_g2_diagnostic_visualization.ps1
|
||||
```
|
||||
|
||||
Its primary image will be:
|
||||
|
||||
```text
|
||||
ClumsyPilot/obj/path_smoothing_reports/local-g2-single-turn/07-local-g2-diagnostic-candidate.png
|
||||
```
|
||||
Reference in New Issue
Block a user