ParkingRobot/docs/superpowers/specs/2026-08-09-movementtest-web-path-visualization-design.md

MovementTest 网页路径总览可视化优化设计

1. 背景与目标

当前 MovementTest 的网页“路径总览”已经接收占用栅格、粗路径、完整 Local G2 平滑路径、方向分段、当前 EM 轨迹、车辆位姿和边界标记，但现有绘制方式存在以下观察障碍：

• 车辆轮廓和描边使用世界坐标尺寸，描边宽度约为 0.7–0.8 m，会遮挡路径。
• 路径总览没有图例，无法直接辨认粗路径、平滑路径、活动方向段和 EM 规划路径。
• 鸟瞰图缺少米制坐标网格、坐标刻度和轴名称。
• 完整平滑路径只有终点或换向点标记，没有明确的平滑路径起点标记。
• 粗路径、平滑路径、方向段和 EM 路径可能重合，当前颜色、线宽和透明度层级不足以进行直观比较。

本次优化只改善网页路径总览的观察能力，不改变 EM 规划结果、MovementTest 状态机、轨迹发布策略或底盘安全边界。

2. 范围与非目标

2.1 范围

• 增加等比例米制网格、X/Y 刻度、坐标轴和单位。
• 增加根据当前实际数据生成的路径与标记图例。
• 将车辆改为固定屏幕像素尺寸的小车方向图标。
• 在完整 Local G2 平滑路径上明确显示起点和终点。
• 保留当前车辆位置、当前 EM 规划起点、换向点和终点语义。
• 调整路径绘制顺序、颜色、线型、线宽和透明度，使重合路径仍可辨认。
• 增加覆盖静态快照语义和网页绘制能力的自动化检查。

2.2 非目标

• 不修改粗路径、Local G2 或 EMPlanner 算法。
• 不修改 FullDirection、Rolling 或多段换向状态机。
• 不新增底盘控制、轨迹跟踪或执行闭环。
• 不更换前端框架，不引入第三方地图或图表库。
• 本轮不增加鸟瞰图拖动、缩放、全屏或图层开关。
• 不修改现有可视化 JSON 基本协议；仅在现有标记集合中补充平滑路径起点。

3. 方案选择

采用“增量增强现有 SVG 渲染器”方案。

现有 TrajectoryPlanningVisualization/Web/app.js 继续负责路径总览绘制，现有 Canvas 继续绘制占用栅格。SVG 增加网格、坐标、固定屏幕尺寸标记和明确的绘制层级，HTML/CSS 增加悬浮图例。MovementTest 静态快照构造器只补充一个平滑路径起点标记。

没有采用以下方案：

• 仅修改 CSS：无法可靠实现固定像素车辆、米制刻度和坐标标签。
• 更换地图或绘图库：改动和依赖范围明显超过当前观察需求。

4. 数据语义

现有数据继续按以下含义使用：

数据	来源	网页语义
coarse polyline	静态快照	粗路径
local-g2 polyline	静态快照	完整平滑路径
direction segments	静态快照	已完成、活动和未来方向段
current polyline	动态快照	当前发布的 EM 优化轨迹
previous polyline	动态快照	上一条 EM 轨迹，仅在存在时显示
vehicle marker + vehiclePose	动态快照	当前车辆位置和朝向
plan-start marker	动态快照	当前 EM 规划起点
gear-switch-end marker	静态或动态快照	换向停车边界
final-goal marker	静态或动态快照	完整平滑路径终点

静态快照新增 smooth-start 标记：位置取 bootstrap.SmoothedPath.Path 的首点，标签为“平滑路径起点”。该标记属于观察语义，不参与规划和状态机计算。

图例优先使用 polyline 已有的 LegendChinese 和 marker 的 LabelChinese，并按语义种类去重。某类数据不存在时，图例不显示该项，避免展示与当前画面不一致的固定说明。

5. 鸟瞰图坐标系统

5.1 几何约束

• X/Y 采用相同缩放比例，保持世界几何不变形。
• 坐标值单位为米。
• 视野边界继续由地图、路径、标记和车辆位置联合计算，并保留合理外边距。
• 网格间距根据当前可见跨度选择 1 / 2 / 5 × 10ⁿ 的易读步长，使单轴通常出现约 5–10 条主网格线。

5.2 绘制内容

• 主网格使用低对比度浅灰实线，位于全部路径下方。
• X/Y 零轴仅在零点处于当前视野内时显示，并使用略深颜色。
• 鸟瞰图边缘显示 X/Y 刻度值。
• 轴名称为 X (m) 和 Y (m)。
• 网格线描边使用非缩放描边；刻度文字换算为屏幕尺度，路径很长或很短时仍保持可读。

网格和坐标绘制在 SVG 中，不改变底层占用栅格的分辨率与编码方式。

6. 路径视觉层级

绘制顺序从下到上固定为：

1. Canvas 占用栅格。
2. SVG 米制网格、零轴和刻度。
3. 粗路径。
4. 完整 Local G2 平滑路径。
5. 方向段状态层。
6. 上一条 EM 轨迹。
7. 当前 EM 轨迹。
8. 起点、终点、换向点和车辆标记。
9. HTML 图例。

建议视觉参数：

元素	视觉形式	目的
粗路径	灰色虚线，约 40% 不透明度，约 2 px	提供原始路径参考但不抢占视觉焦点
平滑路径	青绿色实线，约 65% 不透明度，约 4 px	作为 EM 优化前的主要比较基线
非活动方向段	浅灰细线或虚线，约 25–35% 不透明度	保留多段结构但降低重复覆盖
活动方向段	蓝色细线，约 45–55% 不透明度	标识当前规划范围，不遮住平滑路径
上一条 EM 轨迹	灰紫色虚线，约 65% 不透明度，约 2 px	与当前轨迹区分
当前 EM 轨迹	橙色实线，约 95% 不透明度，约 2–2.5 px	始终置顶，明确展示 EM 输出

平滑路径使用比 EM 路径更宽的半透明线。当两者完全重合时，青绿色平滑路径仍会从橙色 EM 路径两侧露出；存在偏差时则能直接看到两条曲线的分离。粗路径使用不同线型，即使三条路径局部重合也能辨认。

所有路径描边使用 vector-effect: non-scaling-stroke，CSS 中的线宽按屏幕像素理解，不随世界范围变化。

7. 标记与图例

7.1 固定像素车辆图标

• 车辆采用约 18–20 px 的紧凑小车或方向箭头轮廓。
• 图标中心锚定真实车辆世界坐标，朝向来自 vehiclePose.headingRadians。
• 图标尺寸、描边和方向指示保持屏幕像素尺度，不随路径跨度缩放。
• 使用高对比轮廓和轻微半透明填充，不再绘制米制粗描边。
• 图标置于路径之上，但尺寸受限，避免覆盖局部规划几何。

实现时根据 SVG 当前 viewBox 与实际像素尺寸计算世界单位/像素比例，再对车辆局部图形应用平移、旋转和像素尺度换算。车辆中心仍使用真实世界坐标。

7.2 起终点和边界标记

• 平滑路径起点：绿色圆形或起点符号，标签“平滑路径起点”。
• 平滑路径终点：蓝色方形或终点符号，标签“终点 / s_end”。
• 当前 EM 规划起点：空心绿色圆，标签“计划起点”。
• 换向点：橙色菱形并保留顺序编号。
• 标记和标签同样保持近似固定屏幕尺寸，避免世界范围变化导致过大或不可见。

若平滑路径起点与当前 EM 规划起点重合，两个符号允许叠加，但使用实心/空心差异；标签布局应避免完全重复遮盖。后续如需自动标签避让，另立交互增强任务，本轮不扩展。

7.3 图例

• 图例位于鸟瞰图右上角，使用白色半透明背景、细边框和紧凑中文文字。
• 图例不参与世界坐标缩放，始终保持屏幕像素尺寸。
• 每项使用与画面一致的线段或标记样例。
• 图例只显示当前快照中实际存在的语义种类。
• 图例不得遮挡右侧坐标刻度；鸟瞰图为图例保留内部安全边距。

8. 组件改动边界

预计修改范围：

• TrajectoryObservationStaticSnapshotBuilder.cs
  • 新增平滑路径起点标记。
• TrajectoryPlanningVisualization/Web/index.html
  • 增加图例容器及必要的无障碍语义。
• TrajectoryPlanningVisualization/Web/app.js
  • 增加 nice tick、网格/轴、屏幕尺度换算、固定尺寸标记、动态去重图例和新绘制层级。
• TrajectoryPlanningVisualization/Web/app.css
  • 增加坐标、图例和新路径/标记视觉样式，修正车辆描边。
• TrajectoryObservationVisualizationChecks.cs
  • 增加静态起点、图例、坐标和固定尺寸标记能力检查。

不修改可视化服务器、SSE 发布、EM 快照动态数据结构或规划核心。

9. 错误与退化行为

• 世界范围为空或无有效路径时，保留现有空状态提示，不生成无效刻度。
• 世界跨度极小或单点路径时，使用最小非零跨度，避免除零和无限缩放。
• SVG 容器尚未完成布局或像素尺寸为零时，使用安全默认比例；下一次渲染再按真实尺寸更新。
• 某类路径或标记缺失时，其图例项省略，其他内容继续绘制。
• 非有限坐标继续被过滤，不因单个坏点中止整个页面刷新。
• 可视化异常仍只影响网页输出，不改变 MovementTest 观察与 EM 规划行为。

10. 测试与验收

10.1 自动化检查

• 静态快照在平滑路径非空时恰好产生一个 smooth-start 标记，位置等于平滑路径首点。
• 现有 final-goal 和换向点语义不回归。
• 网页包含图例容器、米制 X/Y 坐标语义和网格绘制逻辑。
• 当前 EM 路径使用独立视觉类并在静态路径之后绘制。
• 车辆标记使用屏幕尺度换算，车辆路径不再使用 0.7–0.8 世界单位描边。
• CSS 路径线宽保持非缩放描边，粗路径、平滑路径和当前 EM 路径具有不同线型/颜色/透明度。
• 网页数据缺失时仍保留空状态，不产生 JavaScript 非有限计算。

最小自动化验证：

dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
dotnet build ClumsyPilot/ClumsyPilot.csproj -p:ExcludeLegacyAutoAvoidance=true --no-restore

10.2 人工视觉验收

1. 使用包含弯曲和局部重合的粗路径、平滑路径和 EM 轨迹启动 MovementTest 网页。
2. 确认车辆图标尺寸稳定且不会遮住全局路径。
3. 确认 X/Y 比例一致，网格、刻度和 X (m)、Y (m) 可读。
4. 确认图例颜色、线型和实际路径一致，且不存在的数据不出现在图例中。
5. 确认平滑路径起点、最终终点、车辆当前位置和 EM 规划路径同时可见。
6. 在平滑路径与 EM 路径完全重合处，仍能看到青绿色基线边缘和橙色 EM 中线。
7. 在两条路径存在偏差处，可直观看出偏移方向和大致米制距离。
8. 含换向点的多段路径仍显示全部换向标记和活动方向段，但不会压过当前 EM 路径。

11. 完成标准

• 路径总览具备明确的米制坐标系统和数据驱动图例。
• 车辆为固定屏幕尺寸，不再遮挡全局规划路径。
• 粗路径、完整平滑路径和当前 EM 路径的语义及层级清晰。
• 平滑路径起点、终点、当前车辆和 EM 路径均可直接观察。
• 重合路径通过线宽、线型、颜色和透明度组合保持可辨认。
• 自动化检查、主项目构建和人工视觉验收全部通过。
• EMPlanner、MovementTest 状态机和 OBSERVE_ONLY 安全边界保持不变。