Files
road-compiler/.trellis/tasks/archive/2026-09/09-04-complex-junction-shapes/design.md
T

4.1 KiB
Raw Blame History

复杂路口形态与参数编辑设计

Architecture Boundary

形态识别和几何生成都位于编译层,避免前端根据显示结果猜测路口结构。服务层只负责传递 cluster 配置、识别摘要和诊断;JunctionTools 负责展示摘要和局部预览,不复制几何算法。

Shape Model

对每个 cluster 建立 junctionShape 投影:

  • arms: cluster 边界外的有效道路臂,每个臂包含代表方向、成员车道/方向道路、总宽度、车道数和是否双向。
  • corners: 按相邻 arms 的真实夹角生成的角部关系;只保留夹角在可安全构造范围内的相邻对。
  • throughPairs: 近似相反方向的臂对,用于判断是否存在贯通道路和中央结构。
  • shapeKind: cross、t-junction、offset-cross、multi-arm 或 unsupported。
  • layoutSummary: 面向 UI 的中文摘要,不暴露 OSM node ID。

形态判定规则:

  1. 先按 heading 将 carriageway 分组为 arms;同一方向的多条平行/相邻车道属于一个 arm。
  2. 过滤末端仍落在 cluster 内部短连接上的 approach,避免把 cluster 内部连接误算成外部道路。
  3. arms.length === 3 时,若存在一对夹角接近 180 度,标记为 t-junction;否则标记为 multi-arm。
  4. arms.length === 4 时,若存在两组近似相反臂对且相邻夹角合理,标记为 cross;若两组臂对存在明显位置错位,标记为 offset-cross。
  5. 其他 3 至 8 臂情况标记为 multi-arm;不足 3 臂或夹角/长度不可靠时标记为 unsupported 并回退普通路口。

2×2、2×1 等节点布局标签只作为 debug/高级信息,不参与上述最终形态命名。

Geometry Rules

  • 臂级元素:每个有效 arm 生成道路面边界、停止线和该臂对应的斑马线;停止线和斑马线挂在 arm 上,不从固定“四边”推导。
  • 角级元素:只对真实相邻角生成圆角、角部导流岛和人行道转角;T 字不闭合不存在的第四角。
  • 核心区:由所有 arm 的边界点构成非对称闭合区域;不使用固定矩形或固定四点顺序。若多边形自交,缩小到安全包络或回退普通路口。
  • 中央结构:只有存在真实 throughPairs 且道路方向/宽度支持时才生成中央分隔或车道分隔;单向臂、单车道臂不自动补双向中央结构。
  • 斑马线:按 arm 的道路包络宽度确定跨度;角部斑马线只在两臂夹角和人行空间均可用时生成。
  • 人行道:继续遵守 OSM sidewalk 标记;没有对应人行道的一侧不生成转角带。
  • 失败回退:任何关键环节无法得到有限、非自交几何时,返回普通路口图层并附带可读诊断,不输出半成品复杂几何。

UI Contract

JunctionTools 在复杂模式顶部展示:

  • “路口形态:4 臂十字 / 3 臂 T 字 / 4 臂偏置十字 / 多臂非规则”。
  • “组成结构:N 个内部节点,M 条有效外部道路臂”。
  • 每条 arm 的可读道路名;无名道路使用“道路 1/道路 2”等稳定编号。
  • 复杂参数第一阶段只读,并列出当前生成的元素数量:道路面、停止线、斑马线、中央结构、角部圆角、人行道转角。

Data Flow

编译层 cluster + junctionPlans + model → junctionShape → 复杂几何生成与 diagnostics → /api/state → localJunctionState → JunctionTools 摘要和局部地图。

前端不得根据 nodeIds.length 推断 T 字或十字;后端应将 shapeKind 和摘要作为诊断/调试状态的一部分返回。

Compatibility

  • 未启用复杂 cluster 时普通路口字节输出和交互保持不变。
  • 已有 complex-junction-v1 配置继续可编译;新 shape 投影只改变元素选择和几何安全性。
  • 无法分类的旧配置不删除,使用普通路口回退并保留 cluster 诊断,便于修正配置。

Deferred

核心半径、进口宽度、停止线距离、斑马线深度、圆角半径等编辑控件留到形态模型稳定后,届时按 shapeKind 和 arm/corner 约束动态生成。