695 lines
37 KiB
Markdown
695 lines
37 KiB
Markdown
# EM Observation Web Visualization Integration 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:** Upgrade `TrajectoryObservationMovementTest` into a complete multi-segment, observe-only EM planning experiment that publishes effective configuration, global/active path geometry, LS/ST and kinematic evidence to the reusable local scientific dashboard.
|
||
|
||
**Architecture:** A pure segment tracker advances only after a real stop and stable signed-speed confirmation. The controller owns one coordinator per active direction segment, while pure snapshot builders convert existing EM/map/smoothing data into the generic visualization contracts. A thin MovementTest host conditionally owns web and Painter sessions and isolates every visualization failure from planning.
|
||
|
||
**Tech Stack:** C# 10, `netstandard2.0`, existing EMPlanner/TrajectoryExecution/Map/PathSmoothing modules, `TrajectoryPlanningVisualization`, OSQP, MDCS read interfaces, existing console verification host.
|
||
|
||
## Prerequisite
|
||
|
||
Complete and review `docs/superpowers/plans/2026-08-05-trajectory-planning-visualization-library.md` first. This plan consumes its exact `PlanningVisualizationSession`, snapshot, chart, geometry, and configuration contracts.
|
||
|
||
## Global Constraints
|
||
|
||
- Continue `OBSERVE_ONLY`; do not call chassis, motor, steering, brake, wheel, gear, or controller write APIs.
|
||
- Use actual MDCS pose and signed longitudinal speed only as read inputs.
|
||
- Preserve user defaults exactly: solver timeout `5.0 s`, OSQP maximum iterations `100000`, ST horizon `2.0 s`, output step `0.10 s`.
|
||
- Default web visualization is off; default native Painter visualization is off.
|
||
- Web refresh defaults to `10 Hz`; history defaults to `60`; port defaults to `0`.
|
||
- Segment transitions are strictly `N -> N+1`; never skip, infer at zero speed, or reuse a previous-direction trajectory as an EM seed.
|
||
- Current and previous cycles may compare world position and shared direction-segment `ReferenceS`; never compare their independent local `PathS` origins.
|
||
- `j[i]` represents `[t_i, t_i+1)`; publish exactly `trajectory.Points.Count - 1` jerk samples and no synthetic terminal sample.
|
||
- Static geometry/configuration is built once after successful bootstrap. Dynamic snapshots are built at most at `WebRefreshRateHz`.
|
||
- Visualization exceptions are logged once and disable only the web output.
|
||
- Preserve unrelated worktree changes and stage only task files.
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
| File | Responsibility |
|
||
| --- | --- |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationContracts.cs` | Runtime, web and direction-confirmation settings with frozen validation. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationSegmentTracker.cs` | Pure stop/direction/projection state machine. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationPipeline.cs` | Active-segment controller and asynchronous loop integration. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs` | Map/global paths/direction segments/effective configuration. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationKinematicChartBuilder.cs` | LS/ST/curvature/v/a/j/yaw-rate generic charts. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationHandoffAnalyzer.cs` | Absolute-time interpolation and shared-segment handoff deltas. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationDynamicSnapshotBuilder.cs` | World overlays, status, charts and cycle summary. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationVisualizationPublisher.cs` | 10 Hz gating and exception fuse. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/MovementTest.TrajectoryObservationTest.cs` | Public fields, lifecycle, browser launch and conditional Painter/web ownership. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationPresentation.cs` | Lazily created optional native Painter fallback. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/README.md` | Operator workflow and chart interpretation. |
|
||
| `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationSettingsChecks.cs` | Defaults, validation and frozen-setting checks. |
|
||
| `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationSegmentChecks.cs` | Pure multi-segment transition checks. |
|
||
| `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs` | Static/dynamic adapter and web isolation checks. |
|
||
| `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs` | Existing regression entry; calls the new focused groups. |
|
||
| `ClumsyPilot/tests/EMPlannerVerificationHost/PluginPackagingChecks.cs` | New managed DLL packaging contract. |
|
||
| `ClumsyPilot/scripts/Publish-ClumsyPilotPlugin.ps1` | Copies the visualization class library beside `ClumsyPilot.dll`. |
|
||
| `ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md` | Updated plugin tree and observation link. |
|
||
|
||
---
|
||
|
||
### Task 1: Synchronize effective settings and visualization controls
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationContracts.cs`
|
||
- Modify: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/MovementTest.TrajectoryObservationTest.cs`
|
||
- Create: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationSettingsChecks.cs`
|
||
- Modify: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs`
|
||
- Modify: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/README.md`
|
||
|
||
**Interfaces:**
|
||
|
||
- Extends `TrajectoryObservationSettings` with web/Painter and direction-confirmation properties.
|
||
- `CreateValidatedSnapshot()` freezes every new property.
|
||
- MovementTest public fields map one-to-one into settings before background work begins.
|
||
|
||
- [ ] **Step 1: Write failing defaults, copy, and validation checks**
|
||
|
||
Add `TrajectoryObservationSettingsChecks.Run()` and invoke it from `TrajectoryObservationChecks.Run()`.
|
||
|
||
```csharp
|
||
var defaults = new TrajectoryObservationSettings();
|
||
Verification.NearlyEqual(5d, defaults.SolverTimeoutSeconds, "observer solver timeout default");
|
||
Verification.Equal(100000, defaults.MaximumOsqpIterations, "observer OSQP default");
|
||
Verification.NearlyEqual(2d, defaults.TimeHorizonSeconds, "observer ST horizon default");
|
||
Verification.True(!defaults.EnableWebVisualization, "web defaults off");
|
||
Verification.True(!defaults.EnableNativePainterVisualization, "Painter defaults off");
|
||
Verification.Equal(0, defaults.WebVisualizationPort, "dynamic port default");
|
||
Verification.NearlyEqual(10d, defaults.WebRefreshRateHz, "web refresh default");
|
||
Verification.Equal(60, defaults.VisualizationHistoryCycleLimit, "history default");
|
||
Verification.NearlyEqual(0.02d, defaults.DirectionConfirmationSpeedMetersPerSecond,
|
||
"direction speed threshold");
|
||
Verification.Equal(3, defaults.DirectionConfirmationSamples, "direction sample default");
|
||
Verification.NearlyEqual(0.50d, defaults.GearSwitchProjectionToleranceMeters,
|
||
"gear projection default");
|
||
Verification.NearlyEqual(0.20d, defaults.GearSwitchStopHoldSeconds, "gear stop hold default");
|
||
```
|
||
|
||
Mutate all source values after `CreateValidatedSnapshot()` and assert the snapshot retains the originals. Add invalid cases for port `-1/1/1023/65536`, refresh `0`, history `0`, speed threshold `0`, sample count `0`, projection tolerance `0`, and hold `0`.
|
||
|
||
- [ ] **Step 2: Run RED**
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
|
||
```
|
||
|
||
Expected: failure because settings still use `0.50 / 12000 / 6.0` and the new properties do not exist.
|
||
|
||
- [ ] **Step 3: Implement settings and MovementTest field mapping**
|
||
|
||
Add exact get/set defaults to settings and matching public fields to MovementTest:
|
||
|
||
```csharp
|
||
public bool EnableWebVisualization { get; set; } = false;
|
||
public bool AutoOpenWebVisualization { get; set; } = true;
|
||
public int WebVisualizationPort { get; set; } = 0;
|
||
public double WebRefreshRateHz { get; set; } = 10d;
|
||
public int VisualizationHistoryCycleLimit { get; set; } = 60;
|
||
public bool EnableNativePainterVisualization { get; set; } = false;
|
||
public double DirectionConfirmationSpeedMetersPerSecond { get; set; } = 0.02d;
|
||
public int DirectionConfirmationSamples { get; set; } = 3;
|
||
public double GearSwitchProjectionToleranceMeters { get; set; } = 0.50d;
|
||
public double GearSwitchStopHoldSeconds { get; set; } = 0.20d;
|
||
```
|
||
|
||
Use inclusive validation for port `0` and `1024..65535`. Update the Chinese XML summaries so the ST default says `2 s`, not `6 s`. Update the README configuration table with all solver, ST, web, Painter and direction-confirmation fields.
|
||
|
||
- [ ] **Step 4: Run GREEN**
|
||
|
||
Run `trajectory-observation`. Expected: PASS and no assertion still expects the superseded defaults.
|
||
|
||
- [ ] **Step 5: Commit settings**
|
||
|
||
```powershell
|
||
git add -- ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationContracts.cs ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/MovementTest.TrajectoryObservationTest.cs ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/README.md ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationSettingsChecks.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs
|
||
git commit -m "feat: configure observation visualization"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Pure sequential direction-segment tracker
|
||
|
||
**Files:**
|
||
|
||
- Create: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationSegmentTracker.cs`
|
||
- Create: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationSegmentChecks.cs`
|
||
- Modify: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs`
|
||
|
||
**Interfaces:**
|
||
|
||
- Produces: `TrajectoryObservationSegmentPhase`, `TrajectoryObservationSegmentState`, and `TrajectoryObservationSegmentTracker.Update(...)`.
|
||
- Consumes: frozen settings, ordered `DirectionSegmentView` list, EM stop tolerance, caller time, measured `VehicleMotionState`, and current published trajectory.
|
||
|
||
- [ ] **Step 1: Write failing state-machine checks**
|
||
|
||
Build a two-segment forward/reverse fixture with a duplicated world pose at the gear switch. Exercise this exact sequence:
|
||
|
||
```csharp
|
||
var tracker = new TrajectoryObservationSegmentTracker(segments, settings, stopSpeedTolerance: 0.01d);
|
||
Verification.Equal(0, tracker.State.ActiveSegmentIndex, "tracker begins on segment zero");
|
||
|
||
tracker.Update(t0, StateAtSwitch(0d, t0, 1L), GearTerminal(t0));
|
||
Verification.Equal(TrajectoryObservationSegmentPhase.WaitingForStop, tracker.State.Phase,
|
||
"first zero sample begins stop hold");
|
||
|
||
tracker.Update(t0.AddSeconds(0.21d), StateAtSwitch(0d, t0.AddSeconds(0.21d), 2L), GearTerminal(t0));
|
||
Verification.Equal(TrajectoryObservationSegmentPhase.WaitingForDirection, tracker.State.Phase,
|
||
"continuous stop arms next direction");
|
||
|
||
tracker.Update(t0.AddSeconds(0.25d), StateAtSwitch(-0.03d, t0.AddSeconds(0.25d), 3L), GearTerminal(t0));
|
||
tracker.Update(t0.AddSeconds(0.30d), StateAtSwitch(-0.03d, t0.AddSeconds(0.30d), 4L), GearTerminal(t0));
|
||
TrajectoryObservationSegmentUpdate advanced = tracker.Update(
|
||
t0.AddSeconds(0.35d), StateAtSwitch(-0.03d, t0.AddSeconds(0.35d), 5L), GearTerminal(t0));
|
||
Verification.True(advanced.Advanced && tracker.State.ActiveSegmentIndex == 1,
|
||
"three stable reverse samples advance exactly one segment");
|
||
```
|
||
|
||
Separate checks prove that wrong sign, a zero sample, a sequence-id repeat, excessive switch distance, a non-gear terminal, and a discontinuous timestamp reset confirmation. A one-segment path reaches `Completed` rather than indexing past the end.
|
||
|
||
- [ ] **Step 2: Run RED**
|
||
|
||
Run `trajectory-observation`. Expected: compile failure because tracker types do not exist.
|
||
|
||
- [ ] **Step 3: Implement the tracker**
|
||
|
||
Use these stable phases:
|
||
|
||
```csharp
|
||
public enum TrajectoryObservationSegmentPhase
|
||
{
|
||
Planning,
|
||
WaitingForStop,
|
||
WaitingForDirection,
|
||
Completed,
|
||
}
|
||
```
|
||
|
||
`Update` first validates strictly increasing `SequenceId` and nondecreasing caller time. It only leaves `Planning` when the current published trajectory has matching segment/direction, `TerminalType.GearSwitch`, and the caller time is at or beyond `trajectory.Metadata.EffectiveAtUtc + trajectory.Points[^1].TimeFromStart`. Use `FrenetProjector` to confirm the measured pose is within the configured tolerance of both the current-segment end and next-segment start.
|
||
|
||
The expected speed sign is positive for `Forward` and negative for `Reverse`. A successful update changes the active index once, resets counters/timers, and returns a Chinese transition diagnostic. It must not write to coordinator, browser, UI, or hardware.
|
||
|
||
- [ ] **Step 4: Run GREEN**
|
||
|
||
Run `trajectory-observation` twice. Expected: PASS both times with deterministic state transitions.
|
||
|
||
- [ ] **Step 5: Commit tracker**
|
||
|
||
```powershell
|
||
git add -- ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationSegmentTracker.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationSegmentChecks.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs
|
||
git commit -m "feat: track observed direction segments"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Active-segment rolling controller and loop
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationPipeline.cs`
|
||
- Modify: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationSegmentChecks.cs`
|
||
- Modify: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs`
|
||
|
||
**Interfaces:**
|
||
|
||
- `TrajectoryObservationController.ActiveSegment`, `SegmentState`, `PreviousTrajectoryForVisualization`, and `TryAdvanceSegment(...)` become the single active-segment source.
|
||
- `TrajectoryObservationController.CreateEffectiveConfigurationSnapshot()` returns `configuration.Copy()` so adapters never read mutable MovementTest fields or retain the controller's private configuration object.
|
||
- `StartCycle` builds a request for `ActiveSegment.SegmentIndex`.
|
||
- `TrajectoryObservationLoop.Tick` may call `TryAdvanceSegment` only when no planning task is in flight.
|
||
|
||
- [ ] **Step 1: Write failing controller integration checks**
|
||
|
||
Use a recording `IEmPlanningService` and two-segment bootstrap:
|
||
|
||
```csharp
|
||
controller.StartCycle(t0, forwardState, CancellationToken.None).GetAwaiter().GetResult();
|
||
Verification.Equal(0, service.Requests[0].SegmentIndex, "first request uses segment zero");
|
||
|
||
AdvanceTrackerThroughRealStopAndReverse(controller, gearTrajectory, t0);
|
||
controller.StartCycle(t0.AddSeconds(1d), reverseState, CancellationToken.None).GetAwaiter().GetResult();
|
||
Verification.Equal(1, service.Requests[1].SegmentIndex, "next request uses segment one");
|
||
Verification.True(service.Requests[1].PreviousTrajectory == null,
|
||
"new direction does not reuse old segment trajectory");
|
||
```
|
||
|
||
Also prove two cycles on the same segment retain the exact published previous trajectory reference and ID, and prove an in-flight task prevents a segment reset.
|
||
|
||
- [ ] **Step 2: Run RED**
|
||
|
||
Expected: checks fail because the controller hardcodes `segmentIndex = 0`.
|
||
|
||
- [ ] **Step 3: Refactor controller ownership**
|
||
|
||
Store the planning service and make coordinator/executor replaceable per segment:
|
||
|
||
```csharp
|
||
private readonly IEmPlanningService planningService;
|
||
private EmPlanningCoordinator coordinator;
|
||
private TrajectoryExecutor executor;
|
||
private readonly TrajectoryObservationSegmentTracker segmentTracker;
|
||
private EmTrajectory previousTrajectoryForVisualization;
|
||
```
|
||
|
||
Add:
|
||
|
||
```csharp
|
||
internal EmPlannerConfiguration CreateEffectiveConfigurationSnapshot()
|
||
{
|
||
return configuration.Copy();
|
||
}
|
||
```
|
||
|
||
On a confirmed transition, preserve the old published trajectory only in `previousTrajectoryForVisualization`, then construct a new coordinator and executor. Same-segment `StartCycle` uses `coordinator.PublishedTrajectory`; cross-segment starts with null. Continue monotonic session cycle IDs across coordinator replacement.
|
||
|
||
`Observe` supplies the tracker-confirmed current direction to `TrajectoryExecutor`. While waiting at a gear switch, desired direction is the next segment direction and `directionConfirmed=false`; after transition both current and desired are the new direction.
|
||
|
||
- [ ] **Step 4: Update the async loop**
|
||
|
||
In `Tick`, after consuming a completed task and before starting a new task:
|
||
|
||
```csharp
|
||
bool segmentAdvanced = planningTask == null && controller.TryAdvanceSegment(now, state);
|
||
if (segmentAdvanced)
|
||
latestCycle = null;
|
||
```
|
||
|
||
Expose `SegmentAdvanced` and the immutable segment state in `TrajectoryObservationLoopTick`. Never cancel a running planner solely to advance a segment.
|
||
|
||
- [ ] **Step 5: Run GREEN and existing coordinator/executor regressions**
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- coordinator
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- executor
|
||
```
|
||
|
||
Expected: all three PASS.
|
||
|
||
- [ ] **Step 6: Commit controller integration**
|
||
|
||
```powershell
|
||
git add -- ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationPipeline.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationSegmentChecks.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs
|
||
git commit -m "feat: observe EM planning across gear segments"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: Static world geometry and effective configuration adapter
|
||
|
||
**Files:**
|
||
|
||
- Create: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs`
|
||
- Create: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs`
|
||
- Modify: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs`
|
||
|
||
**Interfaces:**
|
||
|
||
- Produces: `PlanningVisualizationStaticSnapshot Build(bootstrap, effectiveConfiguration, settings, obstacleSnapshotVersion)`.
|
||
- Static polylines use metres; map source bounds/resolution remain named with their original millimetre units in configuration values.
|
||
|
||
- [ ] **Step 1: Write failing static snapshot checks**
|
||
|
||
Assert a forward/reverse bootstrap produces every segment and switch marker:
|
||
|
||
```csharp
|
||
PlanningVisualizationStaticSnapshot snapshot = builder.Build(bootstrap, configuration, settings, 17L);
|
||
Verification.Equal(bootstrap.Segments.Count, snapshot.DirectionSegments.Count,
|
||
"all direction segments exported");
|
||
Verification.Equal("Forward", snapshot.DirectionSegments[0].Direction, "forward direction exported");
|
||
Verification.Equal("Reverse", snapshot.DirectionSegments[1].Direction, "reverse direction exported");
|
||
Verification.True(snapshot.StaticMarkers.Any(x => x.Kind == "gear-switch"),
|
||
"gear switch marker exported");
|
||
Verification.Equal((bootstrap.GridMap.Rows * bootstrap.GridMap.Cols + 7) / 8,
|
||
Convert.FromBase64String(snapshot.OccupancyGrid.OccupancyBitsBase64).Length,
|
||
"occupancy bitset has exact compact length");
|
||
Verification.True(IsOccupiedBitSet(snapshot.OccupancyGrid, occupiedRow, occupiedColumn),
|
||
"occupied map cell uses row-major least-significant-bit-first encoding");
|
||
```
|
||
|
||
Flatten configuration entries by raw field name and assert exact values for `TimeHorizonSeconds=2`, `DistanceHorizonMeters=5`, `MaximumOsqpIterations=100000`, all solver tolerances, all LS/ST weights, vehicle fields, map snapshot/resolution/bounds, web settings, and direction-confirmation settings.
|
||
|
||
- [ ] **Step 2: Run RED**
|
||
|
||
Expected: compile failure because builder does not exist.
|
||
|
||
- [ ] **Step 3: Implement static conversion**
|
||
|
||
Build configuration groups in this stable order: `调度`, `OSQP`, `车辆与安全`, `纵向限制`, `ST 权重`, `横向限制`, `LS 权重`, `走廊与投影`, `地图`, `可视化与换向确认`.
|
||
|
||
Use raw field names exactly as C# properties and invariant values. Encode `PlanningGridMap.IsOccupied(row, column)` into the generic row-major occupancy bitset using bit index `row * map.Cols + column`; do not create one DTO, SVG element, or polyline per occupied cell. Build global coarse and Local G2 polylines once. Direction segments must retain segment index, direction and switch topology; dynamic state decides completed/current/future highlighting.
|
||
|
||
- [ ] **Step 4: Run GREEN**
|
||
|
||
Run `trajectory-observation`. Expected: PASS with all effective values read from the controller's frozen `EmPlannerConfiguration`, not editable MovementTest fields.
|
||
|
||
- [ ] **Step 5: Commit static adapter**
|
||
|
||
```powershell
|
||
git add -- ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs
|
||
git commit -m "feat: export EM observation configuration"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: Kinematic charts, rolling semantics, and handoff evidence
|
||
|
||
**Files:**
|
||
|
||
- Create: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationKinematicChartBuilder.cs`
|
||
- Create: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationHandoffAnalyzer.cs`
|
||
- Create: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationDynamicSnapshotBuilder.cs`
|
||
- Modify: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs`
|
||
|
||
**Interfaces:**
|
||
|
||
- Produces chart IDs `ls`, `st`, `curvature-s`, `curvature-t`, `velocity-t`, `acceleration-t`, `jerk-t`, `yaw-rate-t`.
|
||
- Produces `TrajectoryObservationHandoffMetrics` with availability, `DeltaPositionMeters`, `DeltaReferenceSMeters`, `DeltaVelocityMetersPerSecond`, and `DeltaAccelerationMetersPerSecondSquared`.
|
||
- Produces one `PlanningVisualizationDynamicSnapshot` per accepted publication tick.
|
||
|
||
- [ ] **Step 1: Write failing jerk and chart checks**
|
||
|
||
For a 21-point rolling trajectory:
|
||
|
||
```csharp
|
||
IReadOnlyList<VisualizationChart> charts = chartBuilder.Build(trajectory, segment, configuration);
|
||
VisualizationChart jerk = FindChart(charts, "jerk-t");
|
||
Verification.Equal(20, jerk.Series[0].Points.Count, "jerk has one real sample per interval");
|
||
Verification.True(jerk.NoteChinese.Contains("末点后无时间区间"), "jerk explains terminal interval");
|
||
Verification.Equal(21, FindChart(charts, "velocity-t").Series[0].Points.Count,
|
||
"velocity remains knot based");
|
||
Verification.Equal("ReferenceS (m)", FindChart(charts, "ls").XAxisLabel,
|
||
"LS uses shared segment station");
|
||
Verification.Equal("PathS (m)", FindChart(charts, "st").YAxisLabel,
|
||
"ST uses local planned PathS");
|
||
```
|
||
|
||
Assert acceleration, jerk, curvature and signed-speed limit series are present with `VisualizationLineStyle.Limit`. Do not invent a yaw-rate limit: the effective configuration has no independent maximum yaw-rate field.
|
||
|
||
- [ ] **Step 2: Write failing rolling/exact-stop semantic checks**
|
||
|
||
Build dynamic snapshots for `RollingContinuation` and `ExactStopAtBoundary`. Assert Chinese status values respectively contain `滚动末端停车硬约束：未启用` and `精确停车锚点`, and that the displayed terminal speed/acceleration equal the actual final point.
|
||
|
||
- [ ] **Step 3: Write failing handoff coordinate checks**
|
||
|
||
Create two trajectories whose local `PathS` both start at zero but whose world points project to different positions on the same full segment. Align at `current.Metadata.EffectiveAtUtc`; assert:
|
||
|
||
```csharp
|
||
Verification.NearlyEqual(expectedWorldDelta, metrics.DeltaPositionMeters, "handoff world delta");
|
||
Verification.NearlyEqual(expectedReferenceDelta, metrics.DeltaReferenceSMeters,
|
||
"handoff compares shared ReferenceS");
|
||
Verification.True(expectedReferenceDelta != current.Points[0].PathS - previous.Points[0].PathS,
|
||
"handoff does not compare local PathS origins");
|
||
```
|
||
|
||
Projection failure must return unavailable `DeltaReferenceS` while preserving world/velocity/acceleration deltas.
|
||
|
||
- [ ] **Step 4: Run RED**
|
||
|
||
Expected: compilation failure because builders and metrics do not exist.
|
||
|
||
- [ ] **Step 5: Implement chart and handoff builders**
|
||
|
||
For jerk, iterate only while `index + 1 < trajectory.Points.Count` and use the interval start time/value. For LS, project every world pose to the complete active `DirectionSegmentView` and use `segment.SourceStartArcLength + projection.ReferenceS`. For ST, retain `point.TimeFromStart` and the plan-local `point.PathS`.
|
||
|
||
Use `TrajectorySampler.TrySample` at:
|
||
|
||
```csharp
|
||
double previousTime = (current.Metadata.EffectiveAtUtc - previous.Metadata.EffectiveAtUtc).TotalSeconds;
|
||
```
|
||
|
||
Compare the sampled previous point with current point zero. Project both to the same full segment for `DeltaReferenceS`; never subtract local `PathS`.
|
||
|
||
- [ ] **Step 6: Implement dynamic snapshot composition**
|
||
|
||
Dynamic world overlays contain real pose, current trajectory, previous trajectory, active-segment highlight and current projected horizon. Status values include active segment/direction, planning status, mode, terminal type, elapsed, trajectory age, projection failures, rolling constraint semantics, terminal `v/a`, handoff deltas, and unmet gear-confirmation condition. Cycle summary contains no full point arrays.
|
||
|
||
- [ ] **Step 7: Run GREEN**
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- em-core-all
|
||
```
|
||
|
||
Expected: both commands PASS; the existing rolling service regression still has 21 knots and nonzero rolling terminal speed.
|
||
|
||
- [ ] **Step 8: Commit the visualization adapter**
|
||
|
||
```powershell
|
||
git add -- ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationKinematicChartBuilder.cs ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationHandoffAnalyzer.cs ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationDynamicSnapshotBuilder.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs
|
||
git commit -m "feat: visualize EM rolling kinematics"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 6: MovementTest web lifecycle and optional Painter fallback
|
||
|
||
**Files:**
|
||
|
||
- Create: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationVisualizationPublisher.cs`
|
||
- Modify: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/MovementTest.TrajectoryObservationTest.cs`
|
||
- Modify: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationPresentation.cs`
|
||
- Modify: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs`
|
||
- Modify: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs`
|
||
|
||
**Interfaces:**
|
||
|
||
- `TrajectoryObservationVisualizationPublisher.Start(...)` creates the generic session and returns the URI.
|
||
- Internal `ITrajectoryObservationVisualizationSink` defines `Start`, `Publish`, and `Stop`; the production adapter wraps `PlanningVisualizationSession`, while tests inject a throwing sink without mocking the library.
|
||
- `TryPublish(...)` enforces the configured cadence and fuses on the first adapter/server fault.
|
||
- `Stop()` is idempotent.
|
||
- Native Painter objects are constructed only when `EnableNativePainterVisualization=true`.
|
||
|
||
- [ ] **Step 1: Write failing lifecycle/isolation checks**
|
||
|
||
Add a fake visualization sink whose `Publish` throws. Verify the wrapper logs/disables once, later calls are no-ops, and the `TrajectoryObservationLoop` continues producing ticks. Add a source audit asserting the MovementTest has no static eager `new TrajectoryObservationPresentation()` and conditionally creates it only under the native Painter flag.
|
||
|
||
Add a cadence check: observer ticks at 20 Hz with web refresh at 10 Hz produce no more than 11 snapshots over one second, including the initial snapshot.
|
||
|
||
- [ ] **Step 2: Run RED**
|
||
|
||
Expected: failures because the publisher does not exist and Painter creation is eager.
|
||
|
||
- [ ] **Step 3: Implement publisher cadence and fuse**
|
||
|
||
Use this internal seam and facade surface:
|
||
|
||
```csharp
|
||
internal interface ITrajectoryObservationVisualizationSink
|
||
{
|
||
PlanningVisualizationSessionInfo Start(PlanningVisualizationOptions options,
|
||
PlanningVisualizationStaticSnapshot snapshot);
|
||
void Publish(PlanningVisualizationDynamicSnapshot snapshot);
|
||
void Stop();
|
||
}
|
||
|
||
internal sealed class TrajectoryObservationVisualizationPublisher
|
||
{
|
||
internal TrajectoryObservationVisualizationPublisher(TrajectoryObservationSettings settings,
|
||
ITrajectoryObservationVisualizationSink sink, Action<string> log);
|
||
internal PlanningVisualizationSessionInfo Start(PlanningVisualizationStaticSnapshot snapshot);
|
||
internal bool TryPublish(DateTimeOffset now,
|
||
Func<PlanningVisualizationDynamicSnapshot> snapshotFactory);
|
||
internal void Stop();
|
||
internal string FaultReason { get; }
|
||
}
|
||
```
|
||
|
||
The production sink constructs and disposes one `PlanningVisualizationSession`; the fake sink records calls or throws.
|
||
|
||
The publisher stores `nextPublishAtUtc`. When enabled and healthy:
|
||
|
||
```csharp
|
||
if (now < nextPublishAtUtc) return false;
|
||
nextPublishAtUtc = now + TimeSpan.FromSeconds(1d / settings.WebRefreshRateHz);
|
||
session.Publish(dynamicBuilder.Build(...));
|
||
return true;
|
||
```
|
||
|
||
Catch any exception from build/start/publish, call `session.Stop()`, set one immutable Chinese fault reason, invoke the supplied log callback once, and return false thereafter.
|
||
|
||
- [ ] **Step 4: Integrate successful bootstrap and browser launch**
|
||
|
||
After bootstrap succeeds and before the loop begins, build the static snapshot and start the web session only when enabled. Log the full tokenized URI. If auto-open is enabled, call:
|
||
|
||
```csharp
|
||
Process.Start(new ProcessStartInfo
|
||
{
|
||
FileName = sessionInfo.Uri.AbsoluteUri,
|
||
UseShellExecute = true,
|
||
});
|
||
```
|
||
|
||
Catch browser-launch exceptions separately and keep the web session running.
|
||
|
||
- [ ] **Step 5: Make Painter lazy and conditional**
|
||
|
||
Remove static eager `Presentation`. Create a session-local presentation only when enabled, pass null otherwise, and guard all `DrawWorld/DrawLs/DrawSt/ClearAll` calls. Stopping or replacing a session stops its web publisher and clears only an existing Painter. Bootstrap failure still logs through UI/console even when both visualization modes are off.
|
||
|
||
- [ ] **Step 6: Publish dynamic snapshots from real ticks**
|
||
|
||
Use `controller.ActiveSegment` for LS/ST building and world highlight. Pass the completed cycle, elapsed time, in-flight flag, segment state, current/previous trajectories, live state and current sample into `TryPublish`. Do not serialize or wait in the observer loop.
|
||
|
||
- [ ] **Step 7: Run GREEN and source audit**
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
|
||
rg -n "SendXYThSpeed|SendMotion|DriveStop|PredefinedDriveStop|AccumulateSpeed" ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest
|
||
```
|
||
|
||
Expected: check PASS and `rg` finds no actuator call in runtime observer sources.
|
||
|
||
- [ ] **Step 8: Commit MovementTest lifecycle**
|
||
|
||
```powershell
|
||
git add -- ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationVisualizationPublisher.cs ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/MovementTest.TrajectoryObservationTest.cs ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationPresentation.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs
|
||
git commit -m "feat: host EM observation dashboard"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 7: Plugin packaging and operator documentation
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ClumsyPilot/scripts/Publish-ClumsyPilotPlugin.ps1`
|
||
- Modify: `ClumsyPilot/tests/EMPlannerVerificationHost/PluginPackagingChecks.cs`
|
||
- Modify: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/README.md`
|
||
- Modify: `ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md`
|
||
|
||
**Interfaces:**
|
||
|
||
- Plugin output adds `plugins/TrajectoryPlanningVisualization.dll` beside `ClumsyPilot.dll`.
|
||
- The publisher resolves the visualization DLL only as a sibling of the explicit `ManagedDll`; it does not search `PATH` or current directory.
|
||
|
||
- [ ] **Step 1: Write failing package-tree check**
|
||
|
||
Change the expected sorted tree to:
|
||
|
||
```text
|
||
plugins/ClumsyPilot.dll|
|
||
plugins/TrajectoryPlanningVisualization.dll|
|
||
plugins/licenses/OSQP-LICENSE.txt|
|
||
plugins/licenses/OSQP-NOTICE.txt|
|
||
plugins/licenses/OSQP-VERSION.txt|
|
||
plugins/osqp.dll
|
||
```
|
||
|
||
Also use `AssemblyName.GetAssemblyName` to verify the new file is a managed assembly named `TrajectoryPlanningVisualization`.
|
||
|
||
- [ ] **Step 2: Run RED**
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- plugin-package
|
||
```
|
||
|
||
Expected: failure because the publish script omits the visualization DLL.
|
||
|
||
- [ ] **Step 3: Update the atomic publisher**
|
||
|
||
Resolve:
|
||
|
||
```powershell
|
||
$visualizationDll = Join-Path ([System.IO.Path]::GetDirectoryName($managedDllPath)) 'TrajectoryPlanningVisualization.dll'
|
||
if (-not [System.IO.File]::Exists($visualizationDll)) {
|
||
throw "Visualization DLL does not exist beside managed DLL: $visualizationDll"
|
||
}
|
||
```
|
||
|
||
Copy it into staging before the atomic directory swap. Keep all existing drive-root/workspace-root protections, OSQP hash validation and recovery behavior unchanged.
|
||
|
||
- [ ] **Step 4: Run package GREEN**
|
||
|
||
Run `plugin-package` twice. Expected: PASS both times and no stale staging/backup directories.
|
||
|
||
- [ ] **Step 5: Update both READMEs**
|
||
|
||
The MovementTest README must document:
|
||
|
||
- how to enable web/Painter modes;
|
||
- localhost/token URL behavior;
|
||
- Chinese scientific chart conventions;
|
||
- `ReferenceS` versus local `PathS`;
|
||
- jerk interval semantics;
|
||
- rolling/approach/exact-stop labels;
|
||
- active/completed/future segment colors;
|
||
- direction-confirmation conditions;
|
||
- browser closure and TestStop behavior.
|
||
|
||
The EM README plugin tree must include `TrajectoryPlanningVisualization.dll` and link to the observation README.
|
||
|
||
- [ ] **Step 6: Commit packaging and docs**
|
||
|
||
```powershell
|
||
git add -- ClumsyPilot/scripts/Publish-ClumsyPilotPlugin.ps1 ClumsyPilot/tests/EMPlannerVerificationHost/PluginPackagingChecks.cs ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/README.md ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md
|
||
git commit -m "docs: package EM observation dashboard"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 8: Full automated and manual acceptance
|
||
|
||
**Files:**
|
||
|
||
- No planned source changes. If a command fails, return to the owning task, add a focused failing regression there, implement the minimal correction, and rerun this acceptance task from Step 1.
|
||
|
||
**Interfaces:**
|
||
|
||
- Consumes: both verification hosts, the packaged plugin output, the deterministic smoke mode, and the deployed MovementTest entry.
|
||
- Produces: fresh automated evidence plus an explicit completed-or-pending vehicle checklist; it does not introduce a new runtime API.
|
||
|
||
- [ ] **Step 1: Run the complete automated suite**
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- em-all
|
||
dotnet build ClumsyPilot/ClumsyPilot.csproj -p:ExcludeLegacyAutoAvoidance=true
|
||
git diff --check
|
||
```
|
||
|
||
Expected: visualization host PASS; every `em-all` component PASS; main build exits `0`; no new whitespace errors. Record any pre-existing warnings separately rather than claiming they were introduced here.
|
||
|
||
- [ ] **Step 2: Run a local dashboard smoke session**
|
||
|
||
Run the deterministic smoke mode delivered by Plan 1:
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj -- --smoke-seconds 30
|
||
```
|
||
|
||
Open the printed tokenized URI during the 30-second window and verify:
|
||
|
||
- Chinese titles/status and English/scientific axes;
|
||
- thin white-background scientific plots;
|
||
- all four tabs and all required charts;
|
||
- active segment/world horizon highlight;
|
||
- effective configuration values;
|
||
- stale-state display after sample publication stops;
|
||
- port release after the host exits.
|
||
|
||
This smoke command must publish synthetic snapshots only and must not reference MDCS or hardware.
|
||
|
||
- [ ] **Step 3: Perform the deployed vehicle observation checklist**
|
||
|
||
In a supervised safe environment:
|
||
|
||
1. Enable web and leave native Painter disabled.
|
||
2. Confirm `OBSERVE_ONLY` appears in UI/console/page.
|
||
3. Observe rolling, approach and exact-stop modes; confirm no forced rolling parking label.
|
||
4. Confirm jerk has `N-1` interval samples and no point-21 successor interval or `JerkLimitExceeded`.
|
||
5. Confirm current/previous handoff uses `Δposition/ΔReferenceS/Δv/Δa`.
|
||
6. At a real gear switch, confirm stop hold and three signed-speed samples precede `N -> N+1` highlight.
|
||
7. Close the browser and confirm planning cadence continues.
|
||
8. Stop MovementTest and confirm server/port/Painter cleanup and no actuator output.
|
||
|
||
- [ ] **Step 4: Commit only acceptance-driven fixes**
|
||
|
||
If Step 1–3 required code changes, commit each regression and fix with exact file paths. If no changes were required, do not create an empty commit.
|
||
|
||
Plan 2 is complete only after automated evidence is fresh and the vehicle-only checklist is explicitly reported as completed or, if the vehicle is unavailable, explicitly reported as pending rather than silently treated as passed.
|