docs: align path smoothing design and execution plan
This commit is contained in:
梁薄云
@@ -11,7 +11,7 @@
|
||||
|
||||
粗路径由离散恒曲率运动原语拼接而成。它解决绕障拓扑、行驶方向和换向结构，但相邻原语之间的曲率可能跳变，不适合作为后续 SQP 的最终空间参考线。
|
||||
|
||||
本设计在 `CoarsePath` 之后增加独立的 `PathSmoothing` 模块。第一阶段先建设离线算法对比实验台，使用相同粗路径并行比较三次 B 样条、局部三次 Bézier 和分段五次多项式。实验台统一执行几何分析、安全复核、指标排序和 IEEE 风格绘图。算法成熟后，正式规划流程只调用选定的默认平滑方法。
|
||||
本设计在 `CoarsePath` 之后增加独立的 `PathSmoothing` 模块。第一阶段先建设离线算法对比实验台，使用相同粗路径独立比较三次 B 样条、局部三次 Bézier 和分段五次多项式；这里的“独立”不表示并发执行。实验台统一执行几何分析、安全复核、指标排序和 IEEE 风格绘图。算法成熟后，正式规划流程只调用选定的默认平滑方法。
|
||||
|
||||
## 2. 目标
|
||||
|
||||
@@ -233,9 +233,9 @@ EndsAtGearSwitch
|
||||
Method
|
||||
OutputSpacingMeters 默认 0.05
|
||||
MaximumCollisionCheckStepMeters 默认 0.025
|
||||
MinimumClearanceReserveMeters
|
||||
AllowFallbackToCoarsePath
|
||||
SmoothingStrength
|
||||
MinimumClearanceReserveMeters 默认 0.02
|
||||
AllowFallbackToCoarsePath 默认 true
|
||||
SmoothingStrength 默认 1.00
|
||||
RetryStrengthScales
|
||||
```
|
||||
|
||||
@@ -245,7 +245,20 @@ RetryStrengthScales
|
||||
1.00, 0.75, 0.50, 0.25
|
||||
```
|
||||
|
||||
每种算法拥有独立的强类型子配置，不能用无语义的字符串字典传参。
|
||||
每种算法拥有独立的强类型子配置，不能用无语义的字符串字典传参。第一版固定默认值如下：
|
||||
|
||||
```text
|
||||
CubicBSpline.EndpointTangentScale 1/3
|
||||
LocalCubicBezier.CornerHeadingThresholdRadians π/18
|
||||
LocalCubicBezier.MaximumWindowLengthMeters 0.60
|
||||
LocalCubicBezier.HandleLengthRatio 1/3
|
||||
PiecewiseQuintic.KnotSpacingMeters 0.50
|
||||
PiecewiseQuintic.MinimumKnotSpacingMeters 0.10
|
||||
```
|
||||
|
||||
公共请求在构造时复制这些配置；进入数值算法前再次转换成仅含只读标量的内部快照。算法不得硬编码或回读调用方可变配置。
|
||||
|
||||
所有配置数值必须有限；`OutputSpacingMeters`、`MaximumCollisionCheckStepMeters`、`SmoothingStrength`、控制比例及所有窗口/结点长度必须为正，`MinimumClearanceReserveMeters` 必须非负，转角阈值必须位于 `(0, π]`，且 `KnotSpacingMeters >= MinimumKnotSpacingMeters`。不满足时返回 `InvalidInput`，不得进入有限重试。
|
||||
|
||||
`MaximumCollisionCheckStepMeters` 默认值为当前粗路径默认安全精度 `0.025 m`。若上游粗规划采用了更小的检查步长，调用方必须传入相同或更小的值；平滑模块不能从未携带的粗规划配置中猜测该参数。
|
||||
|
||||
@@ -281,7 +294,9 @@ RetryStrengthScales
|
||||
|
||||
预处理器根据原路径的保守车体净空和 `MinimumClearanceReserveMeters` 计算每个样点允许的最大移动范围。该范围只用于减少平滑曲线切弯进入障碍物的概率，不构成安全证明。最终安全性只能由完整车体碰撞和扫掠复核确认。
|
||||
|
||||
算法生成候选时，每个求值输出点还必须相对同一参数处的原始插值参考点复核该范围：`max(0, reference.BodyClearance - MinimumClearanceReserveMeters)`。超限时该算法尝试必须失败并不得发布候选几何；禁止把单个求值点投影或硬裁剪回该范围，因为这会在原折点附近破坏曲线切线连续性。该候选可行性门槛不替代最终的完整车体碰撞和扫掠复核。
|
||||
算法生成候选时，每个求值输出点还必须相对同一原始弧长位置的插值参考点复核该范围：`max(0, reference.BodyClearance - MinimumClearanceReserveMeters)`。参数映射统一使用方向段局部原始弧长：完整方向段的归一化参数 `u∈[0,1]` 映射为 `s_ref=u×L_original`；局部窗口参数 `t∈[0,1]` 映射为 `s_ref=s_entry+t×(s_exit-s_entry)`；分段五次区间采用相同的结点弧长插值。禁止使用原始点索引比例代替弧长映射。
|
||||
|
||||
求值点超限属于可重试的几何不可行：该次尝试不得发布候选几何，但运行器必须继续下一个较低强度。禁止把单个求值点投影或硬裁剪回允许范围，因为这会在原折点附近破坏曲线切线连续性。该候选可行性门槛不替代最终的完整车体碰撞和扫掠复核。
|
||||
|
||||
## 9. 三种平滑方法
|
||||
|
||||
@@ -355,21 +370,25 @@ RetryStrengthScales
|
||||
|
||||
## 12. 有限安全回退
|
||||
|
||||
每种方法先按 `SmoothingStrength` 运行。候选不通过复核时，依次使用 `RetryStrengthScales` 降低平滑强度。
|
||||
每种方法先按 `SmoothingStrength` 运行。候选不通过复核或算法内的可动范围门槛时，依次使用 `RetryStrengthScales` 降低平滑强度。内部算法结果必须区分：
|
||||
|
||||
- `Success`：产生完整有限候选，进入统一分析和安全复核；
|
||||
- `RetryableInfeasible`：可动范围、局部几何约束或安全复核不满足，记录原因后尝试下一强度；
|
||||
- `Failed`：非法数值、奇异系数、输入契约错误或无法构造完整候选，立即停止该方法。
|
||||
|
||||
```text
|
||||
默认强度
|
||||
↓ 不可行
|
||||
↓ 可重试不可行
|
||||
0.75 倍
|
||||
↓ 不可行
|
||||
↓ 可重试不可行
|
||||
0.50 倍
|
||||
↓ 不可行
|
||||
↓ 可重试不可行
|
||||
0.25 倍
|
||||
↓ 不可行
|
||||
↓ 可重试不可行
|
||||
该方法标记 Infeasible
|
||||
```
|
||||
|
||||
重试次数、采用强度和每次失败原因必须进入诊断。达到有限次数后必须停止，不能无限调参。
|
||||
重试次数、采用强度和每次失败原因必须进入诊断。达到有限次数后必须停止，不能无限调参。算法返回 `Failed` 时不得用降低强度掩盖数值或契约错误。
|
||||
|
||||
正式单算法服务只有在 `AllowFallbackToCoarsePath = true` 且原粗路径重新通过完整安全复核时，才能返回 `FallbackToCoarsePath`。比较实验中的方法失败不能被回退结果伪装成该方法成功。
|
||||
|
||||
@@ -392,6 +411,10 @@ AcceptedStrength
|
||||
|
||||
曲率变化指标逐方向段计算后累加，不跨换向点产生虚假的曲率跳变。
|
||||
|
||||
正式单算法结果中的 `ComputationElapsed` 记录一次规范执行的耗时，不参与跨方法推荐。离线比较的耗时排序使用独立基准流程：每个场景和方法先预热 `1` 次，再计时 `5` 次；五次输出必须具有相同状态、路径点数和稳定几何摘要，否则该方法标记为非确定性诊断失败。稳定几何摘要按状态、方向段元数据和所有路径点字段的 IEEE 754 位模式顺序生成 SHA-256，不使用进程相关的 `GetHashCode()`。排名使用五次计时的中位数，预热和计时运行均不得改变正式比较结果。
|
||||
|
||||
比较条目另外保存 `MeasuredElapsedMilliseconds[5]`、`MedianElapsedMilliseconds`、`TimingSampleCount=5` 和 `IsDeterministic`；CSV 和排序使用 `MedianElapsedMilliseconds`，不能把正式单次 `ComputationElapsed` 混作基准中位数。
|
||||
|
||||
每个平滑结果还报告相对于原粗路径的：
|
||||
|
||||
```text
|
||||
@@ -472,7 +495,7 @@ forward-reverse-switch
|
||||
|
||||
路径图和曲率图使用相同的四方法顺序。某种方法产生完整但不可行的候选时，实验报告可以绘制其候选并在违规位置标记叉号，同时明确标注“不可行”。该候选只能存在于比较报告的只读调试数据中，不能进入正式 `PathSmoothingResult.Path`。
|
||||
|
||||
数值失败且没有完整候选时，保留图例和指标行，显示“无有效曲线”，不得伪造曲线。
|
||||
算法内可行性门槛或数值构造失败导致没有完整候选时，保留图例和指标行，显示“无有效曲线”，不得伪造曲线。
|
||||
|
||||
### 16.2 IEEE 风格版式
|
||||
|
||||
@@ -480,8 +503,8 @@ forward-reverse-switch
|
||||
|
||||
```text
|
||||
物理尺寸：7.16 × 5.2 in
|
||||
PNG：2148 × 1560 px
|
||||
分辨率：300 dpi
|
||||
PNG：4296 × 3120 px
|
||||
分辨率：600 dpi
|
||||
```
|
||||
|
||||
布局：
|
||||
@@ -543,19 +566,21 @@ IEEE 官方图形指南建议使用颜色和线型共同编码、保持字体和
|
||||
5. 字体缺失时返回明确的 `FontUnavailable` 导出失败，不能静默替换；
|
||||
6. SVG 使用 UTF-8 XML；
|
||||
7. CSV 使用带 BOM 的 UTF-8；
|
||||
8. PNG 写入并验证对应 300 dpi 的物理分辨率元数据；
|
||||
8. PNG 写入并验证对应 600 dpi 的物理分辨率元数据；
|
||||
9. 使用稳定英文文件名，中文只出现在图内和 CSV 内容中。
|
||||
|
||||
最终物理尺寸下建议：
|
||||
|
||||
```text
|
||||
坐标刻度：8 pt
|
||||
坐标刻度：9 pt
|
||||
坐标标题、图例和表格正文：9 pt
|
||||
分图编号：10 pt
|
||||
```
|
||||
|
||||
英文 Times New Roman 属于 IEEE 推荐字体。由于宋体不是 IEEE 通用英文字体清单的一部分，它只用于满足本项目中文图注需求；英文、数字和数学字符仍使用 Times New Roman。
|
||||
|
||||
字体检查只能保证生成机器正确渲染。文本型 SVG 是可编辑母版，仅保证在安装了 `SimSun` 和 `Times New Roman` 的环境中保持原排版；600 dpi PNG 是无需字体依赖的便携预览。若用于 IEEE 正式投稿，必须在模块外将已验证的 SVG 转换为 IEEE 接受的 PDF/EPS，并嵌入字体或将文字转换为轮廓；本阶段不把 SVG 声明为可直接投稿格式。
|
||||
|
||||
### 16.5 输出格式
|
||||
|
||||
每个场景输出：
|
||||
@@ -566,7 +591,7 @@ IEEE 官方图形指南建议使用颜色和线型共同编码、保持字体和
|
||||
<scenario-id>-metrics.csv
|
||||
```
|
||||
|
||||
SVG 是矢量母版，PNG 用于直接查看和现有工作流，CSV 保存每种方法的完整指标。报告输出属于生成产物，不提交到源码目录。
|
||||
SVG 是可编辑矢量母版，600 dpi PNG 用于无需字体依赖的直接查看和现有工作流，CSV 保存每种方法的完整指标。报告输出属于生成产物，不提交到源码目录。IEEE 投稿用 PDF/EPS 的字体嵌入或轮廓化转换属于显式发布步骤，不在本模块中静默完成。
|
||||
|
||||
绘图使用独立的不可变 `SmoothingFigureModel`。SVG 和 PNG 渲染器都消费该模型，以保证面板范围、曲线、颜色、字体和文本一致。
|
||||
|
||||
@@ -609,6 +634,9 @@ SVG 是矢量母版，PNG 用于直接查看和现有工作流，CSV 保存每
|
||||
- 换向点的位置、航向和顺序保持；
|
||||
- 输出点数和间距符合配置；
|
||||
- 重试强度严格递减且次数有限；
|
||||
- 可动范围超限进入下一强度，数值失败立即停止；
|
||||
- 非均匀原始采样仍按方向段局部弧长映射参考点；
|
||||
- 修改请求构造后的外部配置不影响内部算法快照；
|
||||
- 短段和退化控制点产生明确失败而非 NaN。
|
||||
|
||||
### 18.4 安全复核测试
|
||||
@@ -626,6 +654,7 @@ SVG 是矢量母版，PNG 用于直接查看和现有工作流，CSV 保存每
|
||||
- 三种方法接收同一份预处理输入；
|
||||
- 单个方法失败不影响其他方法；
|
||||
- 排序规则按固定字典序执行；
|
||||
- 每个方法预热一次、计时五次并使用中位数，非确定性输出不得参与推荐；
|
||||
- 没有可行方法时不推荐默认方法；
|
||||
- 快速夹具路径不调用 Hybrid A*；
|
||||
- 配置指纹变化会使夹具明确过期；
|
||||
@@ -639,7 +668,7 @@ SVG 是矢量母版，PNG 用于直接查看和现有工作流，CSV 保存每
|
||||
- `SimSun` 与 `Times New Roman` 检测；
|
||||
- `粗路径 κ(s) X (m) −π` 等代表性混合文本完整渲染；
|
||||
- SVG 为有效 UTF-8，包含预期字体和所有四种方法；
|
||||
- PNG 具有正确像素尺寸、PNG 结构、CRC 和 300 dpi 元数据；
|
||||
- PNG 具有 `4296 × 3120` 像素、正确 PNG 结构、CRC 和 600 dpi 元数据；
|
||||
- CSV 具有 UTF-8 BOM、稳定列顺序和不依赖区域设置的小数格式；
|
||||
- 不使用依赖平台抗锯齿细节的脆弱逐像素金图测试；
|
||||
- 至少对直线、绕障和换向三张代表图执行人工视觉检查，确认无乱码、遮挡、裁切和间距失衡。
|
||||
@@ -669,7 +698,7 @@ PathSmoothingService
|
||||
5. 不可行候选不会进入正式可执行路径。
|
||||
6. 八个快速夹具无需运行 Hybrid A* 即可完成三算法比较。
|
||||
7. 四个现有端到端场景能够从建图和 Hybrid A* 连接到平滑比较。
|
||||
8. 每个场景生成包含四路径、四曲率和指标表的 SVG、300 dpi PNG 与 UTF-8 CSV。
|
||||
8. 每个场景生成包含四路径、四曲率和指标表的 SVG、600 dpi PNG 与 UTF-8 CSV，并明确 SVG/PDF 的投稿边界。
|
||||
9. 图内中文使用宋体，英文、数字和数学字符使用 Times New Roman，代表性图无乱码、遮挡或裁切。
|
||||
10. 比较结果使用公开的字典序规则推荐方法；没有合格方法时明确不推荐。
|
||||
11. 输出可以作为后续 SQP 的空间参考路径输入，但不提前引入时间、速度或控制字段。
|
||||
|
||||
Reference in New Issue
Block a user