695 lines
36 KiB
Markdown
695 lines
36 KiB
Markdown
# MovementTest Web Path Visualization Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Improve the MovementTest web path overview so coarse, smoothed, and EM paths remain distinguishable, while adding a metric coordinate system, a data-driven legend, fixed-size vehicle rendering, and explicit smoothed-path endpoints.
|
||
|
||
**Architecture:** Keep the existing Canvas occupancy layer and SVG geometry layer. Extend the SVG renderer with world-to-screen metrics, metric grid/axis rendering, fixed-pixel marker transforms, and deterministic path layering; add one HTML legend overlay and one static `smooth-start` marker without changing the visualization JSON contract or planner behavior.
|
||
|
||
**Tech Stack:** C# 10, .NET `netstandard2.0` visualization library, .NET 10 Windows verification hosts, embedded HTML/CSS/vanilla JavaScript, SVG, Canvas.
|
||
|
||
## Global Constraints
|
||
|
||
- Do not modify coarse-path, Local G2, EMPlanner, FullDirection, Rolling, or multi-segment state-machine behavior.
|
||
- Do not add actuator calls, trajectory tracking, or any execution closed loop; `OBSERVE_ONLY` remains unchanged.
|
||
- Do not introduce third-party JavaScript, CSS, map, chart, CDN, or NuGet dependencies.
|
||
- Do not replace or version the visualization JSON contract; only add `smooth-start` to the existing static marker collection.
|
||
- Keep X and Y at equal world scale and label coordinates in meters.
|
||
- Keep all path strokes and marker geometry visually stable across world extents.
|
||
- Do not add overview pan, zoom, fullscreen, or layer toggles.
|
||
- Preserve unrelated dirty-worktree changes; stage only the files named by the current task.
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
- `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs`
|
||
- Owns MovementTest-to-generic-visualization static geometry conversion; it will add the smoothed-path start marker.
|
||
- `ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html`
|
||
- Owns overview DOM structure; it will add the screen-space legend container.
|
||
- `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js`
|
||
- Owns browser rendering; it will add coordinate ticks, world/screen metrics, fixed-size markers, ordered paths, and legend population.
|
||
- `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css`
|
||
- Owns semantic visual styling; it will define coordinate, path, marker, and legend appearance.
|
||
- `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs`
|
||
- Verifies MovementTest snapshot semantics, including the new `smooth-start` marker.
|
||
- `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs`
|
||
- Verifies embedded web assets expose coordinate, fixed-marker, layer, and legend capabilities.
|
||
- `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs`
|
||
- Supplies deterministic overlapping coarse, smoothed, and EM geometry for the local browser smoke test.
|
||
|
||
## Task 1: Export the Smoothed-Path Start Marker
|
||
|
||
**Files:**
|
||
- Modify: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs:56-76`
|
||
- Test: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs:82-110`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `TrajectoryObservationBootstrapResult.SmoothedPath.Path`, whose first element supplies `X` and `Y`.
|
||
- Produces: one existing-contract `VisualizationMarker` with `Id = "smooth-start"`, `Kind = "smooth-start"`, and `LabelChinese = "平滑路径起点"` when the smoothed path is non-empty.
|
||
|
||
- [ ] **Step 1: Write the failing snapshot assertions**
|
||
|
||
Add these assertions immediately after the existing `local-g2-path` assertion in `VerifiesStaticSnapshotExportsFrozenConfigurationAndGeometry`:
|
||
|
||
```csharp
|
||
VisualizationMarker smoothStart = snapshot.StaticMarkers.Single(x => x.Kind == "smooth-start");
|
||
Verification.Equal("平滑路径起点", smoothStart.LabelChinese,
|
||
"static snapshot labels the smoothed-path start");
|
||
Verification.NearlyEqual(bootstrap.SmoothedPath.Path[0].X, smoothStart.Position.X,
|
||
"smoothed-path start marker X matches the first smoothed point");
|
||
Verification.NearlyEqual(bootstrap.SmoothedPath.Path[0].Y, smoothStart.Position.Y,
|
||
"smoothed-path start marker Y matches the first smoothed point");
|
||
```
|
||
|
||
- [ ] **Step 2: Run the focused test and verify failure**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
|
||
```
|
||
|
||
Expected: FAIL in `VerifiesStaticSnapshotExportsFrozenConfigurationAndGeometry` because no marker has `Kind == "smooth-start"`.
|
||
|
||
- [ ] **Step 3: Add the minimal static marker**
|
||
|
||
Insert this block at the start of `CreateMarkers`, after `var markers = new List<VisualizationMarker>();` and before iterating direction segments:
|
||
|
||
```csharp
|
||
if (bootstrap.SmoothedPath.Path.Count > 0)
|
||
{
|
||
var start = bootstrap.SmoothedPath.Path[0];
|
||
markers.Add(new VisualizationMarker("smooth-start", "smooth-start",
|
||
"平滑路径起点", new VisualizationPoint(start.X, start.Y)));
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Run the focused test and verify success**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
|
||
```
|
||
|
||
Expected: `PASS trajectory-observation`.
|
||
|
||
- [ ] **Step 5: Commit the marker contract change**
|
||
|
||
```powershell
|
||
git add -- ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs
|
||
git commit -m "feat: mark smoothed path start in EM overview"
|
||
```
|
||
|
||
## Task 2: Add the Metric Coordinate System
|
||
|
||
**Files:**
|
||
- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js:40-94`
|
||
- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css:41-57`
|
||
- Test: `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs:21-43`
|
||
|
||
**Interfaces:**
|
||
- Consumes: the existing `getBounds()` result and `#world-overlay.getBoundingClientRect()`.
|
||
- Produces: `niceWorldStep(span, targetTicks)`, `worldMetrics(bounds)`, and `renderWorldCoordinates(bounds, metrics)`; later tasks consume `metrics.unitsPerPixel` for fixed-size markers.
|
||
|
||
- [ ] **Step 1: Write failing embedded-asset checks**
|
||
|
||
Add the following assertions in `WebAssetChecks.Run` after the existing `.world-current` check:
|
||
|
||
```csharp
|
||
Verification.True(css.Contains(".world-coordinate-grid"),
|
||
"overview exposes a metric grid semantic class");
|
||
Verification.True(css.Contains(".world-axis-zero"),
|
||
"overview exposes a zero-axis semantic class");
|
||
Verification.True(css.Contains(".world-axis-tick"),
|
||
"overview exposes coordinate tick semantics");
|
||
Verification.True(css.Contains(".world-axis-label"),
|
||
"overview exposes coordinate axis-label semantics");
|
||
Verification.True(js.Contains("function niceWorldStep("),
|
||
"overview selects readable metric tick steps");
|
||
Verification.True(js.Contains("function worldMetrics("),
|
||
"overview derives stable world-to-screen metrics");
|
||
Verification.True(js.Contains("function renderWorldCoordinates("),
|
||
"overview renders its own metric coordinate system");
|
||
Verification.True(js.Contains("X (m)") && js.Contains("Y (m)"),
|
||
"overview labels both metric axes");
|
||
```
|
||
|
||
- [ ] **Step 2: Run the web asset host and verify failure**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
|
||
```
|
||
|
||
Expected: FAIL with `overview exposes a metric grid semantic class`.
|
||
|
||
- [ ] **Step 3: Add world/screen metrics and coordinate rendering**
|
||
|
||
Insert the following functions after `drawOccupancy` and before `worldPath` in `app.js`:
|
||
|
||
```javascript
|
||
function niceWorldStep(span, targetTicks = 7) {
|
||
if (!finite(span) || span <= 0) return 1;
|
||
const rough = span / Math.max(2, targetTicks);
|
||
const magnitude = Math.pow(10, Math.floor(Math.log10(rough)));
|
||
const normalized = rough / magnitude;
|
||
const factor = normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10;
|
||
return factor * magnitude;
|
||
}
|
||
|
||
function worldMetrics(bounds) {
|
||
const box = overlay.getBoundingClientRect();
|
||
const pixelWidth = box.width > 0 ? box.width : 800;
|
||
const pixelHeight = box.height > 0 ? box.height : 520;
|
||
const spanX = Math.max(bounds.xMax - bounds.xMin, 1e-9);
|
||
const spanY = Math.max(bounds.yMax - bounds.yMin, 1e-9);
|
||
return {
|
||
pixelWidth,
|
||
pixelHeight,
|
||
spanX,
|
||
spanY,
|
||
unitsPerPixel: Math.max(spanX / pixelWidth, spanY / pixelHeight, 1e-9)
|
||
};
|
||
}
|
||
|
||
function renderWorldCoordinates(bounds, metrics) {
|
||
const group = svg("g", { class: "world-coordinate-system", "aria-hidden": "true" });
|
||
const xStep = niceWorldStep(metrics.spanX, 8);
|
||
const yStep = niceWorldStep(metrics.spanY, 8);
|
||
const epsilon = Math.max(xStep, yStep) * 1e-9;
|
||
let count = 0;
|
||
for (let x = Math.ceil(bounds.xMin / xStep) * xStep; x <= bounds.xMax + epsilon && count < 100; x += xStep, count += 1) {
|
||
const normalized = Math.abs(x) < epsilon ? 0 : x;
|
||
group.append(svg("line", { x1: normalized, y1: -bounds.yMax, x2: normalized, y2: -bounds.yMin, class: "world-coordinate-grid" }));
|
||
const tick = svg("text", { x: normalized, y: -bounds.yMin - 7 * metrics.unitsPerPixel, class: "world-axis-tick", "font-size": 11 * metrics.unitsPerPixel, "text-anchor": "middle" });
|
||
tick.textContent = formatTick(normalized);
|
||
group.append(tick);
|
||
}
|
||
count = 0;
|
||
for (let y = Math.ceil(bounds.yMin / yStep) * yStep; y <= bounds.yMax + epsilon && count < 100; y += yStep, count += 1) {
|
||
const normalized = Math.abs(y) < epsilon ? 0 : y;
|
||
group.append(svg("line", { x1: bounds.xMin, y1: -normalized, x2: bounds.xMax, y2: -normalized, class: "world-coordinate-grid" }));
|
||
const tick = svg("text", { x: bounds.xMin + 6 * metrics.unitsPerPixel, y: -normalized - 3 * metrics.unitsPerPixel, class: "world-axis-tick", "font-size": 11 * metrics.unitsPerPixel, "text-anchor": "start" });
|
||
tick.textContent = formatTick(normalized);
|
||
group.append(tick);
|
||
}
|
||
if (bounds.xMin <= 0 && bounds.xMax >= 0)
|
||
group.append(svg("line", { x1: 0, y1: -bounds.yMax, x2: 0, y2: -bounds.yMin, class: "world-axis-zero" }));
|
||
if (bounds.yMin <= 0 && bounds.yMax >= 0)
|
||
group.append(svg("line", { x1: bounds.xMin, y1: 0, x2: bounds.xMax, y2: 0, class: "world-axis-zero" }));
|
||
const xLabel = svg("text", { x: bounds.xMax - 8 * metrics.unitsPerPixel, y: -bounds.yMin - 8 * metrics.unitsPerPixel, class: "world-axis-label", "font-size": 12 * metrics.unitsPerPixel, "text-anchor": "end" });
|
||
xLabel.textContent = "X (m)";
|
||
const yLabel = svg("text", { x: bounds.xMin + 8 * metrics.unitsPerPixel, y: -bounds.yMax + 16 * metrics.unitsPerPixel, class: "world-axis-label", "font-size": 12 * metrics.unitsPerPixel, "text-anchor": "start" });
|
||
yLabel.textContent = "Y (m)";
|
||
group.append(xLabel, yLabel);
|
||
overlay.append(group);
|
||
}
|
||
```
|
||
|
||
Replace the first statement sequence in `renderWorld` with:
|
||
|
||
```javascript
|
||
const bounds = getBounds();
|
||
const metrics = worldMetrics(bounds);
|
||
drawOccupancy(bounds);
|
||
overlay.replaceChildren();
|
||
overlay.setAttribute("viewBox", `${bounds.xMin} ${-bounds.yMax} ${bounds.xMax - bounds.xMin} ${bounds.yMax - bounds.yMin}`);
|
||
overlay.setAttribute("preserveAspectRatio", "xMidYMid meet");
|
||
renderWorldCoordinates(bounds, metrics);
|
||
```
|
||
|
||
Add the following CSS after `.world-line`:
|
||
|
||
```css
|
||
.world-coordinate-grid { stroke: #dfe4e8; stroke-opacity: .62; stroke-width: .7; vector-effect: non-scaling-stroke; }
|
||
.world-axis-zero { stroke: #7c8791; stroke-opacity: .72; stroke-width: 1.1; vector-effect: non-scaling-stroke; }
|
||
.world-axis-tick { fill: #68737d; font-family: ui-monospace, Consolas, monospace; }
|
||
.world-axis-label { fill: #48535d; font-family: "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; font-weight: 600; }
|
||
```
|
||
|
||
- [ ] **Step 4: Run the web asset host and verify success**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
|
||
```
|
||
|
||
Expected: `PASS trajectory-planning-visualization`.
|
||
|
||
- [ ] **Step 5: Commit the coordinate system**
|
||
|
||
```powershell
|
||
git add -- ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs
|
||
git commit -m "feat: add metric axes to trajectory overview"
|
||
```
|
||
|
||
## Task 3: Fix Path Layering and Screen-Size Markers
|
||
|
||
**Files:**
|
||
- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js:52-93`
|
||
- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css:1-9,41-57`
|
||
- Test: `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs:21-43`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `worldMetrics(bounds).unitsPerPixel` from Task 2 and existing polyline/marker kinds.
|
||
- Produces: `lineKind(line)`, `markerTransform(position, unitsPerPixel, headingRadians)`, and `appendWorldMarker(marker, frame, metrics)`; the current EM trajectory is rendered after every static/reference layer.
|
||
|
||
- [ ] **Step 1: Add failing checks for fixed-size rendering and semantic layers**
|
||
|
||
Add these assertions after the coordinate checks in `WebAssetChecks.Run`:
|
||
|
||
```csharp
|
||
Verification.True(css.Contains("--world-smoothed-path"),
|
||
"overview defines a dedicated smoothed-path color");
|
||
Verification.True(css.Contains("--world-em-trajectory"),
|
||
"overview defines a dedicated EM-path color");
|
||
Verification.True(css.Contains(".world-marker-shape"),
|
||
"overview marker shapes use a shared screen-space class");
|
||
Verification.True(css.Contains(".marker-smooth-start"),
|
||
"overview styles the smoothed-path start marker");
|
||
Verification.True(js.Contains("function markerTransform("),
|
||
"overview anchors fixed-size markers in world coordinates");
|
||
Verification.True(js.Contains("function appendWorldMarker("),
|
||
"overview centralizes fixed-size marker rendering");
|
||
Verification.True(!js.Contains("const corners = [[.38, .18]"),
|
||
"vehicle marker no longer uses a large world-size rectangle");
|
||
Verification.True(!css.Contains(".marker-vehicle .vehicle-outline { fill: none; stroke: #20252b; stroke-width: .7; }"),
|
||
"vehicle outline no longer uses a world-scale heavy stroke");
|
||
Verification.True(!css.Contains(".marker-vehicle .vehicle-heading { stroke: #20252b; stroke-width: .8; }"),
|
||
"vehicle marker no longer uses world-scale heavy strokes");
|
||
```
|
||
|
||
- [ ] **Step 2: Run the web asset host and verify failure**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
|
||
```
|
||
|
||
Expected: FAIL with `overview defines a dedicated smoothed-path color`.
|
||
|
||
- [ ] **Step 3: Define path and marker visual variables**
|
||
|
||
Add these variables to `:root` without changing the chart color variables:
|
||
|
||
```css
|
||
--world-coarse-path: #7e8790;
|
||
--world-smoothed-path: #168b83;
|
||
--world-active-segment: #3f78a8;
|
||
--world-em-trajectory: #df6b1f;
|
||
```
|
||
|
||
Replace the existing world path and marker CSS rules with:
|
||
|
||
```css
|
||
.world-line { fill: none; vector-effect: non-scaling-stroke; }
|
||
.world-static { stroke: #8d959d; stroke-opacity: .38; stroke-width: 1.4; }
|
||
.world-future { stroke: #b6bec6; stroke-dasharray: 5 4; stroke-width: 1.2; }
|
||
.world-active { stroke: var(--world-active-segment); stroke-width: 1.5; }
|
||
.world-previous { stroke: #887493; stroke-opacity: .66; stroke-dasharray: 7 5; stroke-width: 2; }
|
||
.world-coarse { stroke: var(--world-coarse-path); stroke-opacity: .40; stroke-dasharray: 7 5; stroke-width: 2; }
|
||
.world-local-g2 { stroke: var(--world-smoothed-path); stroke-opacity: .65; stroke-width: 4; }
|
||
.world-segment-active { stroke: var(--world-active-segment); stroke-opacity: .50; stroke-width: 1.5; }
|
||
.world-direction-inactive { stroke: #aab2b9; stroke-opacity: .30; stroke-dasharray: 5 5; stroke-width: 1.1; }
|
||
.world-current { stroke: var(--world-em-trajectory); stroke-opacity: .96; stroke-width: 2.4; }
|
||
.world-marker-shape { vector-effect: non-scaling-stroke; }
|
||
.world-marker-label { fill: #20252b; font: 11px/1.2 "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; paint-order: stroke; stroke: rgba(255, 255, 255, .88); stroke-width: 3px; stroke-linejoin: round; }
|
||
.world-marker { fill: #d87918; stroke: #ffffff; stroke-width: 1.4; }
|
||
.marker-vehicle .vehicle-outline { fill: rgba(32, 37, 43, .16); stroke: #20252b; stroke-width: 1.5; }
|
||
.marker-vehicle .vehicle-heading { stroke: #20252b; stroke-width: 1.5; stroke-linecap: round; vector-effect: non-scaling-stroke; }
|
||
.marker-smooth-start { fill: #2f8f56; stroke: #ffffff; stroke-width: 1.5; }
|
||
.marker-plan-start { fill: #ffffff; stroke: #2f8f56; stroke-width: 2; }
|
||
.marker-gear-switch { fill: #d87918; stroke: #ffffff; stroke-width: 1.5; }
|
||
.marker-final-goal { fill: #1769aa; stroke: #ffffff; stroke-width: 1.5; }
|
||
.world-empty-state { fill: #66707a; font: 14px/1.2 "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; }
|
||
```
|
||
|
||
- [ ] **Step 4: Replace world marker and layer rendering**
|
||
|
||
Add the following functions after `worldPath`:
|
||
|
||
```javascript
|
||
function lineKind(line) { return String(line && line.kind || "").toLowerCase(); }
|
||
|
||
function markerTransform(position, unitsPerPixel, headingRadians = 0) {
|
||
const headingDegrees = (finite(headingRadians) ? headingRadians : 0) * 180 / Math.PI;
|
||
return `translate(${position.x} ${-position.y}) rotate(${-headingDegrees}) scale(${unitsPerPixel})`;
|
||
}
|
||
|
||
function appendWorldMarker(marker, frame, metrics) {
|
||
if (!marker.position || !finite(marker.position.x) || !finite(marker.position.y)) return;
|
||
const kind = String(marker.kind || "").toLowerCase();
|
||
const pose = frame.vehiclePose;
|
||
const heading = kind === "vehicle" && pose && finite(pose.headingRadians) ? pose.headingRadians : 0;
|
||
const group = svg("g", {
|
||
class: `world-marker-group marker-${kind || "generic"}`,
|
||
transform: markerTransform(marker.position, metrics.unitsPerPixel, heading)
|
||
});
|
||
if (kind === "vehicle") {
|
||
group.append(svg("path", { d: "M -9 -5 L 5 -5 L 9 0 L 5 5 L -9 5 Z", class: "world-marker-shape vehicle-outline" }));
|
||
group.append(svg("line", { x1: -4, y1: 0, x2: 7, y2: 0, class: "vehicle-heading" }));
|
||
} else if (kind === "smooth-start") {
|
||
group.append(svg("circle", { cx: 0, cy: 0, r: 5, class: "world-marker-shape marker-smooth-start" }));
|
||
} else if (kind === "plan-start") {
|
||
group.append(svg("circle", { cx: 0, cy: 0, r: 5, class: "world-marker-shape marker-plan-start" }));
|
||
} else if (kind === "gear-switch" || kind === "gear-switch-end") {
|
||
group.append(svg("path", { d: "M 0 -6 L 6 0 L 0 6 L -6 0 Z", class: "world-marker-shape marker-gear-switch" }));
|
||
} else if (kind === "final-goal") {
|
||
group.append(svg("path", { d: "M -6 -6 L 6 -6 L 6 6 L -6 6 Z", class: "world-marker-shape marker-final-goal" }));
|
||
} else {
|
||
group.append(svg("path", { d: "M 0 -6 L 6 0 L 0 6 L -6 0 Z", class: "world-marker-shape world-marker" }));
|
||
}
|
||
overlay.append(group);
|
||
const labelY = kind === "plan-start" ? 17 : -9;
|
||
const labelGroup = svg("g", { transform: `translate(${marker.position.x} ${-marker.position.y}) scale(${metrics.unitsPerPixel})` });
|
||
const label = svg("text", { x: 10, y: labelY, class: "world-marker-label" });
|
||
label.textContent = marker.labelChinese || "";
|
||
labelGroup.append(label);
|
||
overlay.append(labelGroup);
|
||
}
|
||
```
|
||
|
||
Replace the complete `renderWorld` function with:
|
||
|
||
```javascript
|
||
function renderWorld() {
|
||
const bounds = getBounds();
|
||
const metrics = worldMetrics(bounds);
|
||
drawOccupancy(bounds);
|
||
overlay.replaceChildren();
|
||
overlay.setAttribute("viewBox", `${bounds.xMin} ${-bounds.yMax} ${bounds.xMax - bounds.xMin} ${bounds.yMax - bounds.yMin}`);
|
||
overlay.setAttribute("preserveAspectRatio", "xMidYMid meet");
|
||
renderWorldCoordinates(bounds, metrics);
|
||
const snapshot = state.staticSnapshot || {};
|
||
const frame = state.frame || {};
|
||
const addLine = (line, css) => {
|
||
const path = worldPath(line.points);
|
||
if (path) overlay.append(svg("path", { d: path, class: "world-line " + css }));
|
||
};
|
||
const staticLines = safeArray(snapshot.staticPolylines);
|
||
staticLines.filter(line => lineKind(line) === "global" || lineKind(line) === "coarse")
|
||
.forEach(line => addLine(line, "world-coarse"));
|
||
staticLines.filter(line => lineKind(line).includes("local-g2") || lineKind(line).includes("g2"))
|
||
.forEach(line => addLine(line, "world-local-g2"));
|
||
staticLines.filter(line => lineKind(line) !== "global" && lineKind(line) !== "coarse" && !lineKind(line).includes("local-g2") && !lineKind(line).includes("g2"))
|
||
.forEach(line => addLine(line, "world-static"));
|
||
safeArray(snapshot.directionSegments).forEach(segment => addLine(segment,
|
||
segment.segmentIndex === frame.activeSegmentIndex ? "world-segment-active" : "world-direction-inactive"));
|
||
const dynamicLines = safeArray(frame.dynamicPolylines);
|
||
dynamicLines.filter(line => lineKind(line) === "active-segment")
|
||
.forEach(line => addLine(line, "world-segment-active"));
|
||
dynamicLines.filter(line => lineKind(line) === "previous" || line.lineStyle === 1)
|
||
.forEach(line => addLine(line, "world-previous"));
|
||
dynamicLines.filter(line => lineKind(line) !== "active-segment" && lineKind(line) !== "previous" && line.lineStyle !== 1)
|
||
.forEach(line => addLine(line, "world-current"));
|
||
const allLines = staticLines.concat(safeArray(snapshot.directionSegments), dynamicLines);
|
||
const hasPath = allLines.some(line => safeArray(line && line.points)
|
||
.some(point => point && finite(point.x) && finite(point.y)));
|
||
safeArray(snapshot.staticMarkers).concat(safeArray(frame.dynamicMarkers))
|
||
.forEach(marker => appendWorldMarker(marker, frame, metrics));
|
||
if (!hasPath) {
|
||
const emptyGroup = svg("g", { transform: `translate(${(bounds.xMin + bounds.xMax) / 2} ${-((bounds.yMin + bounds.yMax) / 2)}) scale(${metrics.unitsPerPixel})` });
|
||
const empty = svg("text", { x: 0, y: 0, class: "world-empty-state", "text-anchor": "middle" });
|
||
empty.textContent = "未收到 Local G2 路径";
|
||
emptyGroup.append(empty);
|
||
overlay.append(emptyGroup);
|
||
}
|
||
}
|
||
```
|
||
|
||
Add resize-aware redraw beside the existing window error listeners:
|
||
|
||
```javascript
|
||
let overviewResizeFrame = 0;
|
||
window.addEventListener("resize", () => {
|
||
if (overviewResizeFrame || state.activeTab !== "overview" || !state.redrawEnabled.overview) return;
|
||
overviewResizeFrame = window.requestAnimationFrame(() => {
|
||
overviewResizeFrame = 0;
|
||
renderWorld();
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 5: Run the web asset host and verify success**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
|
||
```
|
||
|
||
Expected: `PASS trajectory-planning-visualization`.
|
||
|
||
- [ ] **Step 6: Commit fixed markers and path layering**
|
||
|
||
```powershell
|
||
git add -- ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs
|
||
git commit -m "fix: clarify EM overview path layers"
|
||
```
|
||
|
||
## Task 4: Add a Data-Driven World Legend
|
||
|
||
**Files:**
|
||
- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html:21-26`
|
||
- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js:7-17,52-94`
|
||
- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css:22-24,41-70`
|
||
- Test: `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs:16-43`
|
||
- Test fixture: `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs:11-33`
|
||
|
||
**Interfaces:**
|
||
- Consumes: existing `LegendChinese`, `Kind`, `staticPolylines`, `directionSegments`, `dynamicPolylines`, `staticMarkers`, and `dynamicMarkers`.
|
||
- Produces: `renderWorldLegend(snapshot, frame)` and `#world-legend`; entries are deduplicated by semantic key and only emitted when corresponding data exists.
|
||
|
||
- [ ] **Step 1: Write failing legend asset checks**
|
||
|
||
Add these assertions in `WebAssetChecks.Run` after the `world-overlay` assertion:
|
||
|
||
```csharp
|
||
Verification.True(html.Contains("id=\"world-legend\""),
|
||
"overview contains a screen-space legend host");
|
||
Verification.True(html.Contains("aria-label=\"路径图例\""),
|
||
"overview legend has a Chinese accessible name");
|
||
Verification.True(css.Contains(".world-legend"),
|
||
"overview legend has a screen-space visual container");
|
||
Verification.True(css.Contains(".world-legend-swatch"),
|
||
"overview legend exposes semantic line and marker samples");
|
||
Verification.True(js.Contains("function renderWorldLegend("),
|
||
"overview builds legend entries from current snapshot data");
|
||
Verification.True(js.Contains("legendChinese"),
|
||
"overview reuses exported Chinese polyline legends");
|
||
```
|
||
|
||
Add these assertions in `BuildsDeterministicSmokeSnapshots` after creating `staticSnapshot`:
|
||
|
||
```csharp
|
||
Verification.True(staticSnapshot.StaticPolylines.Any(line => line.Kind == "coarse"),
|
||
"smoke snapshot exposes the coarse comparison path");
|
||
Verification.True(staticSnapshot.StaticPolylines.Any(line => line.Kind == "local-g2"),
|
||
"smoke snapshot exposes the smoothed comparison path");
|
||
Verification.True(staticSnapshot.StaticMarkers.Any(marker => marker.Kind == "smooth-start"),
|
||
"smoke snapshot exposes the smoothed-path start marker");
|
||
```
|
||
|
||
- [ ] **Step 2: Run the web asset host and verify failure**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
|
||
```
|
||
|
||
Expected: FAIL with `smoke snapshot exposes the coarse comparison path`; the legend assertions also remain red until Steps 3–6 are complete.
|
||
|
||
- [ ] **Step 3: Add the accessible legend host**
|
||
|
||
Add this element inside `.world-stack`, after `#world-overlay`:
|
||
|
||
```html
|
||
<aside id="world-legend" class="world-legend" aria-label="路径图例" hidden></aside>
|
||
```
|
||
|
||
- [ ] **Step 4: Expand the deterministic smoke snapshot**
|
||
|
||
Replace the single static `global` polyline in `SampleSnapshotFactory.CreateStaticSnapshot` with:
|
||
|
||
```csharp
|
||
new[]
|
||
{
|
||
new VisualizationPolyline("coarse-path", "粗路径", "coarse", VisualizationLineStyle.Dashed,
|
||
Points((0d, 1d), (3d, 1.2d), (6d, 1.85d), (8d, 4.2d), (11d, 6d))),
|
||
new VisualizationPolyline("local-g2-path", "完整 Local G2 路径", "local-g2", VisualizationLineStyle.Solid,
|
||
Points((0d, 1d), (3d, 1d), (6d, 2d), (8d, 4d), (11d, 6d)))
|
||
},
|
||
```
|
||
|
||
Add this marker as the first item in the static marker array:
|
||
|
||
```csharp
|
||
new VisualizationMarker("smooth-start", "smooth-start", "平滑路径起点", new VisualizationPoint(0d, 1d)),
|
||
```
|
||
|
||
- [ ] **Step 5: Implement data-driven legend population**
|
||
|
||
Add the legend reference after the existing overlay reference:
|
||
|
||
```javascript
|
||
const worldLegend = document.getElementById("world-legend");
|
||
```
|
||
|
||
Add this function after `appendWorldMarker`:
|
||
|
||
```javascript
|
||
function renderWorldLegend(snapshot, frame) {
|
||
if (!worldLegend) return;
|
||
worldLegend.replaceChildren();
|
||
const staticLines = safeArray(snapshot.staticPolylines);
|
||
const directionSegments = safeArray(snapshot.directionSegments);
|
||
const dynamicLines = safeArray(frame.dynamicPolylines);
|
||
const markers = safeArray(snapshot.staticMarkers).concat(safeArray(frame.dynamicMarkers));
|
||
const entries = [];
|
||
const seen = new Set();
|
||
const add = (key, label, swatchClass) => {
|
||
if (seen.has(key)) return;
|
||
seen.add(key);
|
||
entries.push({ label, swatchClass });
|
||
};
|
||
const coarse = staticLines.find(line => lineKind(line) === "global" || lineKind(line) === "coarse");
|
||
const smooth = staticLines.find(line => lineKind(line).includes("local-g2") || lineKind(line).includes("g2"));
|
||
const active = dynamicLines.find(line => lineKind(line) === "active-segment");
|
||
const previous = dynamicLines.find(line => lineKind(line) === "previous" || line.lineStyle === 1);
|
||
const current = dynamicLines.find(line => lineKind(line) !== "active-segment" && lineKind(line) !== "previous" && line.lineStyle !== 1);
|
||
if (coarse) add("coarse", coarse.legendChinese || "粗路径", "legend-line legend-coarse");
|
||
if (smooth) add("smooth", smooth.legendChinese || "完整 Local G2 路径", "legend-line legend-smooth");
|
||
if (active || directionSegments.length)
|
||
add("segment", active && active.legendChinese || "当前方向段", "legend-line legend-segment");
|
||
if (previous) add("previous", previous.legendChinese || "上一条 EM 轨迹", "legend-line legend-previous");
|
||
if (current) add("current", current.legendChinese || "当前 EM 轨迹", "legend-line legend-current");
|
||
if (markers.some(marker => lineKind(marker) === "smooth-start"))
|
||
add("smooth-start", "平滑路径起点", "legend-marker legend-smooth-start");
|
||
if (markers.some(marker => lineKind(marker) === "plan-start"))
|
||
add("plan-start", "EM 规划起点", "legend-marker legend-plan-start");
|
||
if (markers.some(marker => lineKind(marker) === "vehicle"))
|
||
add("vehicle", "当前车辆", "legend-marker legend-vehicle");
|
||
if (markers.some(marker => lineKind(marker) === "gear-switch" || lineKind(marker) === "gear-switch-end"))
|
||
add("gear", "换向点 / s_end", "legend-marker legend-gear");
|
||
if (markers.some(marker => lineKind(marker) === "final-goal"))
|
||
add("goal", "平滑路径终点", "legend-marker legend-goal");
|
||
entries.forEach(entry => {
|
||
const item = element("div", "world-legend-item");
|
||
item.append(element("span", "world-legend-swatch " + entry.swatchClass),
|
||
element("span", "world-legend-label", entry.label));
|
||
worldLegend.append(item);
|
||
});
|
||
worldLegend.hidden = entries.length === 0;
|
||
}
|
||
```
|
||
|
||
Add this call in `renderWorld` after all markers are appended and before the empty-state branch:
|
||
|
||
```javascript
|
||
renderWorldLegend(snapshot, frame);
|
||
```
|
||
|
||
- [ ] **Step 6: Style the legend with matching semantic samples**
|
||
|
||
Add this CSS after the world marker rules:
|
||
|
||
```css
|
||
.world-legend { position: absolute; top: 14px; right: 14px; z-index: 3; display: grid; gap: 6px; min-width: 154px; max-width: min(260px, calc(100% - 28px)); padding: 10px 12px; border: 1px solid rgba(112, 123, 133, .38); border-radius: 6px; background: rgba(255, 255, 255, .88); box-shadow: 0 2px 10px rgba(32, 37, 43, .08); color: #36404a; font-size: 12px; pointer-events: none; backdrop-filter: blur(2px); }
|
||
.world-legend[hidden] { display: none; }
|
||
.world-legend-item { display: grid; grid-template-columns: 30px minmax(0, 1fr); align-items: center; gap: 8px; min-height: 16px; }
|
||
.world-legend-swatch { display: block; justify-self: center; }
|
||
.legend-line { width: 28px; height: 0; border-top-style: solid; }
|
||
.legend-coarse { border-top: 2px dashed rgba(126, 135, 144, .62); }
|
||
.legend-smooth { border-top: 4px solid rgba(22, 139, 131, .65); }
|
||
.legend-segment { border-top: 2px solid rgba(63, 120, 168, .50); }
|
||
.legend-previous { border-top: 2px dashed rgba(136, 116, 147, .72); }
|
||
.legend-current { border-top: 3px solid rgba(223, 107, 31, .96); }
|
||
.legend-marker { width: 11px; height: 11px; border: 1.5px solid #ffffff; box-shadow: 0 0 0 1px rgba(32, 37, 43, .22); }
|
||
.legend-smooth-start { border-radius: 50%; background: #2f8f56; }
|
||
.legend-plan-start { border: 2px solid #2f8f56; border-radius: 50%; background: #ffffff; }
|
||
.legend-vehicle { width: 17px; height: 9px; border: 1.5px solid #20252b; border-radius: 2px; background: rgba(32, 37, 43, .16); }
|
||
.legend-gear { transform: rotate(45deg); background: #d87918; }
|
||
.legend-goal { background: #1769aa; }
|
||
.world-legend-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
|
||
```
|
||
|
||
Replace the existing mobile media query with the following complete rule:
|
||
|
||
```css
|
||
@media (max-width: 720px) {
|
||
header { align-items: start; flex-direction: column; gap: 10px; }
|
||
nav, main, header { padding-left: 14px; padding-right: 14px; }
|
||
.world-stack { min-height: 360px; }
|
||
.world-legend { top: 8px; right: 8px; min-width: 138px; padding: 8px 9px; font-size: 11px; }
|
||
.config-entry { grid-template-columns: 1fr 1fr; }
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 7: Run focused and integration verification**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
|
||
dotnet build ClumsyPilot/ClumsyPilot.csproj -p:ExcludeLegacyAutoAvoidance=true --no-restore
|
||
```
|
||
|
||
Expected output contains:
|
||
|
||
```text
|
||
PASS trajectory-planning-visualization
|
||
PASS trajectory-observation
|
||
Build succeeded.
|
||
```
|
||
|
||
- [ ] **Step 8: Run the local visual smoke test**
|
||
|
||
Run the sample server for 60 seconds:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj -- --smoke-seconds 60
|
||
```
|
||
|
||
Open the printed loopback URL and verify every item:
|
||
|
||
- the vehicle is approximately 18–20 screen pixels long and does not cover the route;
|
||
- X and Y retain equal spatial scale;
|
||
- metric ticks, grid, `X (m)`, and `Y (m)` are readable;
|
||
- coarse gray dashes, wide translucent teal smooth path, and narrow orange EM path remain visible where they overlap;
|
||
- the legend matches only elements visible in the snapshot;
|
||
- smoothed start, final goal, current vehicle, and EM plan-start markers are visible;
|
||
- no browser console error or “页面绘图异常” status appears.
|
||
|
||
- [ ] **Step 9: Check scoped diff hygiene and commit**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
git diff --check -- ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs
|
||
git status --short -- ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs
|
||
git add -- ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs
|
||
git commit -m "feat: add legend to EM path overview"
|
||
```
|
||
|
||
Expected: `git diff --check` emits no error, scoped status lists only the intended files before staging, and the commit contains only those five paths.
|
||
|
||
## Final Verification
|
||
|
||
After all task commits, run:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
|
||
dotnet build ClumsyPilot/ClumsyPilot.csproj -p:ExcludeLegacyAutoAvoidance=true --no-restore
|
||
git diff --check -- ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs
|
||
```
|
||
|
||
Expected: both verification hosts print their PASS lines, the main project reports `Build succeeded.`, and the scoped diff check produces no errors.
|