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

61 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 复杂路口形态与参数编辑设计
## 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 约束动态生成。