docs: design MovementTest path visualization refresh
This commit is contained in:
梁薄云
@@ -0,0 +1,209 @@
|
||||
# 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 非有限计算。
|
||||
|
||||
最小自动化验证：
|
||||
|
||||
```powershell
|
||||
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` 安全边界保持不变。
|
||||
Reference in New Issue
Block a user