Files
ParkingRobot/docs/superpowers/specs/2026-07-28-coarse-path-live-amr-scenarios-design.md
T

4.4 KiB

粗路径固定案例使用实时 AMR 位姿设计

背景

当前 粗路径规划-显式空图粗路径规划-单矩形绕行粗路径规划-多来源障碍粗路径规划-缓存命中粗路径规划-倒车换向粗路径规划-无解 使用工厂中写死的起点、终点、地图边界和障碍物坐标。只有手动的 粗路径规划 测试读取当前 AMR 位姿。

这使固定案例无法从当前机器人位置和朝向验证规划,且 AMR 位于固定地图范围外时会直接得到无意义的越界失败。

目标

所有 粗路径规划-* 固定案例都以一次冻结的当前 AMR 位姿为起点。每个案例保留原有的相对地图、目标、障碍和方向约束,从而在现场位置验证相同的规划问题。

范围

本变更只调整 Clumsy MovementTest 中固定场景的输入创建方式、诊断显示、测试和文档。

不修改 Hybrid A* 搜索算法、车辆参数、碰撞模型、地图缓存实现或手动 粗路径规划 的交互流程。

方案选择

采用“固定案例模板化并整体平移”的方案。

不采用只替换起终点的方案,因为地图和障碍仍停留在原始世界坐标,AMR 可能位于地图外。

不为每个案例分别编写实时构造逻辑,避免重复坐标换算、地图边界和障碍创建代码。

工厂接口与坐标规则

保留现有的 Create(CoarsePathTestScenario scenario),使离线和自动化测试仍可创建可重复的基准案例。

新增接受 AMR 世界位姿的工厂入口:

Create(CoarsePathTestScenario scenario,
       double amrXMillimeters,
       double amrYMillimeters,
       double amrHeadingDegrees)

工厂将基准案例的起点映射到传入 AMR 位姿:

  • deltaX = amrX - baselineStartX
  • deltaY = amrY - baselineStartY
  • 起点位置为 amrX/amrY,起点航向为 amrHeading
  • 目标位置、地图边界、圆形障碍、轴对齐矩形障碍和 TwoLeg 位置均加上 deltaX/deltaY
  • 目标航向为 amrHeading + (baselineGoalHeading - baselineStartHeading),再规范化到规划器采用的标准角度范围。
  • TwoLeg 障碍自身的朝向保持基准值,只移动其位置;本变更是平移而非旋转场景几何。

所有固定案例都使用该规则,包含预期无解的障碍带案例。无解案例移动后仍必须保持无解。

UI 运行流程与错误处理

CoarsePathPlanningTestRunner.RunScenario 在开始时从 DetourInterface 读取一次 AMR 位姿,并将这份快照传给工厂。后续后台规划只使用冻结后的请求,定位更新不会改变正在执行的规划输入。

读取失败、空位姿或任一 X/Y/航向值为 NaN 或无穷值时,不提交规划请求。测试通过 Toast 和画布状态区显示 AMR 位姿不可用 及具体原因。

成功创建请求时,状态区额外显示冻结的 AMR 起点(世界 mm 和 deg),以便现场核对。既有的规划状态、路径搜索耗时、节点统计和失败原因显示继续保留。

手动 粗路径规划 测试不改变:它继续读取一次 AMR 起点,并要求用户输入终点、障碍和总超时。

缓存语义

缓存键继续由完整的地图输入决定。由于地图边界和障碍随 AMR 坐标平移,只有两次固定案例使用完全相同的 AMR 位姿时,粗路径规划-缓存命中 才会命中现有输入缓存。

AMR 已移动时显示缓存未命中是正确结果,而不是规划失败。UI 继续显示实际的缓存状态。

验证

自动化测试应验证:

  1. 新工厂入口将基准起点映射到实时 AMR 位姿,并正确保留目标相对位置与起终点航向差。
  2. 单矩形、多来源和无解案例的地图边界、目标及障碍按相同 deltaX/deltaY 移动。
  3. TwoLeg 的位置移动而朝向不变。
  4. 既有 Create(scenario) 的基准案例及其成功/无解预期继续通过。
  5. UI 运行器读取并冻结一次 AMR 位姿;无效位姿产生明确的未启动诊断。
  6. 文档准确说明实时 AMR 锚点、缓存命中条件和无解场景预期。

验收标准

  • 任一固定 MovementTest 从当前 AMR 坐标和航向开始规划,而不是从写死起点开始。
  • 目标、地图和障碍在当前 AMR 附近平移,起终点的相对方向要求保持不变。
  • 现场定位异常时用户可直接看到原因,且不会错误进入规划后台任务。
  • 离线固定案例和现有规划诊断能力不回归。