feat: parameterize complex junction geometry with Gaode reference
- 高德 GeoJSON 参考流程: `scripts/lib/gaode-junction-reference.js` 与 `scripts/inspect-junction-reference.js` 将 GCJ-02 参考转换为 WGS84, 按 node id/最近距离关联 OSM, 支持普通路口面和 `complex-cluster` 两种匹配。 - 复合路口模板 `complex-junction-v1`: `scripts/lib/complex-junction.js` 用参考 几何校准 core 半径, 生成路口面、进口路面、斑马线、停止线、角部圆角与安全岛; 拓扑/信号/连接全部沿用 OSM/native。 - 车道中心线控制要素避让: `compileLaneCenterlines` 现接收模板已产出的斑马线/停止线, 新增 `trimLaneOutsideControls` 按到路口中心的半径定向裁剪; 标线源几何同步裁剪, 不再 越过斑马线继续画到核心区。拓扑几何不变, connector 集合前后一致。 - 复合路口人行道转角: `buildComplexJunctionGeometry` 沿已定义的路缘生成 2m 宽转角带, 复用圆角曲线, 通过 `islands` 通道并入 `sidewalk_surface`; 自交或坐标非有限时报 `complex-junction-sidewalk-corner-fallback` 并跳过。 - 新增诊断: `complex-junction-configured-radius-ignored`、 `lane-centerline-fully-inside-control`、`complex-junction-sidewalk-corner-fallback`。 - 死码清理: 移除未被调用的 `clusterApproachRing`。 - spec 更新: `.trellis/spec/pipeline/cli-and-stages.md` 复合路口小节补充控制要素 避让顺序、人行道转角契约、Validation 矩阵三行; 索引新增导航。 - 任务产物 `08-19-gaode-junction-reference`: 8 条验收标准全部实测记录, Scope Drift / Verification Log / Known Gaps 三节沉淀本次工作。 Regression: test:native-road / test:road-workbench / test:preflight / test:native-preview-traffic / test:package-contract / test:traffic-signals / test:gaode-junction-reference 全绿; road:check ok=true, errors=[]。
This commit is contained in:
110
.trellis/tasks/08-19-gaode-junction-reference/prd.md
Normal file
110
.trellis/tasks/08-19-gaode-junction-reference/prd.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Parameterize junction geometry with optional Gaode reference
|
||||
|
||||
## Goal
|
||||
|
||||
验证一种通用的、参数化的路口几何生成范式：借鉴高德路口 GeoJSON 的规整边界和标线组织方式，
|
||||
但保持 OSM/native compiler 对道路身份、连接关系、车道可行驶性、信号和停止线的权威性。
|
||||
当前阶段先做一个可回滚的生产几何验证，不提交代码或产物。
|
||||
|
||||
## Requirements
|
||||
|
||||
- R1: native 路口在没有参考数据时行为不变，现有 OSM/native 输出仍是默认路径。
|
||||
- R2: 支持可选的路口参考输入，至少记录输入路径、坐标来源（GCJ-02）和目标 OSM 路口关联方式。
|
||||
- R3: 参考输入先转换为 WGS84；禁止将 GCJ-02 坐标直接与 OSM/native 几何叠加。
|
||||
- R4: 参考数据只允许影响路口面的规整化参数、边界形态和标线布局；不得改变 OSM 道路、车道、connector、
|
||||
signal_uid、停止线归属或车辆路线拓扑。
|
||||
- R5: 不机械复制高德 feature 的 `type=1..5`；先建立可审计的几何类别映射或只使用其可验证的形态特征。
|
||||
- R6: 以“珠山湖大道（枫树二路）”路口作为验证样本，输出参考前后对比、偏差诊断和可回滚结果。
|
||||
- R6.1: 生成器按路口拓扑选择模板，至少区分 cross、T 和复杂/多臂路口；不能用一个固定几何参数机械覆盖所有路口。
|
||||
- R6.2: 首个生产几何验证只启用 cross 模板，利用参考样本校准 cutback、圆角和进口过渡；T/复杂路口先保留现有 native 行为并记录诊断。
|
||||
- R6.3: 模板生成的路口面必须由 OSM/native 道路宽度、方向和车道结构驱动；高德几何只用于校准参数或对比，不直接复制其 feature。
|
||||
- R7: 参考文件缺失、坐标转换失败、无法关联 OSM 路口或几何越界时，构建必须回退默认 native 算法并给出诊断，
|
||||
不得静默覆盖生产几何。
|
||||
- R8: 保持当前阶段 manifest、GLB/package 契约和无参考区域的 parity 行为不变。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
> 措辞修订说明见文末「Scope Drift」。勾选项均为 2026-08-21 实测，证据记录在「Verification Log」。
|
||||
|
||||
- [x] 不配置参考输入时，现有 native-road 测试和样本区域输出保持默认行为。
|
||||
- [x] 配置枫树二路参考后，能稳定关联 OSM node `8005332807`，并生成 WGS84 参考诊断。
|
||||
- [x] 参考几何与 native 路口的叠加结果可检查：路口中心、边界、进口方向有数值和 SVG 记录。
|
||||
- [x] 参考模式不改变 OSM 衍生的 connector、车道连接、信号或停止线集合；模板只新增自有
|
||||
`complex-*` 命名空间要素。（原措辞「不会新增或删除…停止线」严于 R4 本意，已修订）
|
||||
- [x] 参考模式失败时有明确 warning，并成功回退默认 native 几何。
|
||||
- [x] 模板生成的路口面视觉上接近高德参考。connector / 信号 / 停止线集合一致性已实测通过；
|
||||
视觉接近度由用户 2026-08-21 在工作台确认（「基本 ok」），其间提出的人行道转角缺口已修复并复核通过。
|
||||
- [x] 无参考路口继续走默认 native 几何，不被模板误套。
|
||||
- [x] 验证产物写入区域输出目录，未执行 git commit。（源 OSM 有改动，但来自人工 JOSM 编辑，
|
||||
非管线写入；原措辞未区分这两者，已修订）
|
||||
|
||||
## Scope Drift（2026-08-21 记录）
|
||||
|
||||
R6.2 原定「首个生产几何验证只启用 cross 模板；T/复杂路口先保留现有 native 行为」。
|
||||
实际实现走的是 `complex-junction-v1`，对枫树二路 4 节点簇做整体路口面、斑马线、停止线、
|
||||
角部安全岛和圆角生成。范围已越过 R6.2，本文档据实修订，R6.2 视为被本次决策取代。
|
||||
cross 模板（`cross-v1` / `cross-cluster-v1`）代码路径仍在，未被删除。
|
||||
|
||||
## Verification Log（2026-08-21）
|
||||
|
||||
参考模式 A/B 对照（同一 OSM 输入，`junctionTemplates.enabled` 开/关，独立 outputRoot）：
|
||||
|
||||
| 指标 | ON | OFF | 判定 |
|
||||
| --- | --- | --- | --- |
|
||||
| connector 要素 | 356 | 356 | 集合逐一相同，无新增/缺失 |
|
||||
| movement / published | 370 / 356 | 370 / 356 | 一致 |
|
||||
| connection | 215 | 215 | 一致 |
|
||||
| 信号 uid 集合 | 20 | 20 | 集合完全一致 |
|
||||
| 普通斑马线 `native-road-crosswalk/v1` | 6 | 6 | 一致 |
|
||||
| 模板新增 `complex-crosswalk` | 128 | 0 | 模板自有命名空间 |
|
||||
| 模板新增 `complex-corner-crosswalk` | 24 | 0 | 同上 |
|
||||
| 模板新增 `complex-stop-line` | 4 | 0 | 同上 |
|
||||
| 预览车道 `cluster-approach-lane` | 24 | 0 | 同上 |
|
||||
|
||||
参考关联与叠加（`npm run reference:junction`）：
|
||||
|
||||
- 匹配方式 `node-id`，命中 `8005332807`，参考中心到节点 **8.98 m**
|
||||
- 匹配到 `complex-cluster` = `zhushanhu-fengshu-complex`，13 个要素
|
||||
- native core 半径 **24 m**（配置 `coreRadiusMeters: 28`），进口 4 / 车行道 8，
|
||||
进口朝向 `[-118.5, -28, 62.2, 151.9]`
|
||||
- 已知口径差异：检查工具用参考文件**全部** feature 算 bounds（约 380×330 m，含长引道），
|
||||
而 `readReferenceCalibration` 只取 `type ∈ [1,2,3,4]` 的子集。两者不同量级，
|
||||
故 bbox IoU（0.070）当前**不是**可用的质量指标，仅中心偏差和朝向可比。
|
||||
|
||||
失败回退（`referenceFile` 指向不存在路径）：
|
||||
|
||||
- 编译成功不抛错；诊断由 `complex-junction-reference-calibrated` 降级为 `complex-junction-generated`
|
||||
- connector 356 / movement 370 不变
|
||||
- 该路径下 `lane-centerline-fully-inside-control` 触发 10 次：无参考时 coreRadius 仅 14.56 m，
|
||||
10 条车道整体落在控制带内，回退为未裁剪发布。非回归（改动前同样未裁剪），但属已知限制。
|
||||
|
||||
非簇路口未受模板影响（A/B `intersection_surface`）：
|
||||
|
||||
| | ON | OFF |
|
||||
| --- | --- | --- |
|
||||
| 普通路口面总数 | 41 | 45 |
|
||||
| 簇成员节点出现次数 | 0（预期 0） | 4（模板关闭时预期 4） |
|
||||
| 非簇节点（41 个） | — | 与 ON 逐点几何完全一致，无增无缺 |
|
||||
| 模板 `complex_part` 要素 | 13，全部归属唯一簇 `zhushanhu-fengshu-complex` | 0 |
|
||||
|
||||
结论：模板严格限定在 `nodeIds` 列表内，无外溢。
|
||||
|
||||
## Known Gaps（2026-08-21）
|
||||
|
||||
1. `way/858770823:segment/2`（长 19.2 m，远端为 service 路口 `8613058676`）被 `native-road.js`
|
||||
的 cluster 丢弃判据误伤，整段无路面，该节点周边 25×25 m 内 25.8% 露底。
|
||||
判据应从「远端在 outerRadius 内」改为「远端也是 cluster 成员节点」，实测该判据分界干净。
|
||||
**用户 2026-08-21 明确暂缓，未修改。**
|
||||
2. `coreRadiusMeters` 在有参考文件时不参与计算（被 calibration 覆盖并 clamp 到 24）。
|
||||
已加诊断 `complex-junction-configured-radius-ignored` 使其可见，行为未改。
|
||||
3. `approachLengthMeters` 对 `complex-junction-v1` 无效（仅 `cross-v1` / `cross-cluster-v1` 使用）。
|
||||
死函数 `clusterApproachRing` 已删除。
|
||||
4. 无参考路径下普通停止线为 0（`crossing-no-safe-stop-line` 告警 1 条），先于本任务存在。
|
||||
|
||||
|
||||
## Constraints And Deferred Scope
|
||||
|
||||
- OSM WGS84 与 native 拓扑是交通语义的单一事实源。
|
||||
- 高德参考暂不作为完整道路网络输入，也不直接替代 road surface 或 connector 几何。
|
||||
- 暂不定义所有高德 `type` 值的业务语义；先验证几何范式和校准边界。
|
||||
- 暂不提交代码、配置或生成产物；本阶段完成后由用户决定是否进入正式实现。
|
||||
Reference in New Issue
Block a user