feat(junction): classify complex junction shapes
This commit is contained in:
1 parent
38ea779d9b
commit
a359f88edc
13 files changed
+440
-14
No files matched your search
@@ -211,3 +211,64 @@ Rules:
|
||||
itself. Equal is fine and honest: it says there is no headroom.
|
||||
- A range wide enough to produce nonsense (a stop line 126m from its junction) is
|
||||
as much a defect as one that is dead.
|
||||
|
||||
## 13. Complex junction shape summary
|
||||
|
||||
### 1. Scope / Trigger
|
||||
|
||||
Complex-junction compilation publishes a structural classification which the
|
||||
JunctionTools page displays. This crosses the compiler, the persisted GeoJSON
|
||||
layer, `/api/state`, and the typed browser state.
|
||||
|
||||
### 2. Signatures
|
||||
|
||||
```js
|
||||
GET /api/state?debug=1
|
||||
// debug.junctionShapes?: Array<{
|
||||
// clusterId: string, kind: string, label: string,
|
||||
// armCount: number, throughPairCount: number
|
||||
// }>
|
||||
```
|
||||
|
||||
### 3. Contracts
|
||||
|
||||
- `complex-core` is published in `layers/road_surface.geojson`, not
|
||||
`intersection_surface.geojson`.
|
||||
- Its `shape_kind`, `shape_label`, `arm_count`, and `through_pair_count`
|
||||
properties are the compiler authority. The service must project them without
|
||||
reclassifying from node count.
|
||||
- `debug.junctionShapes` is present only for debug state. An absent matching
|
||||
entry means the client shows its ordinary cluster context, not an invented
|
||||
shape.
|
||||
|
||||
### 4. Validation & Error Matrix
|
||||
|
||||
| Condition | Required behavior |
|
||||
| --- | --- |
|
||||
| No complex core for a configured cluster | Omit its summary; do not emit a false shape |
|
||||
| Shape is unsupported | Compiler emits a normal-junction fallback diagnostic and no `complex-core` |
|
||||
| GeoJSON properties are missing | Use `unsupported` and the readable fallback label only while projecting an existing core |
|
||||
|
||||
### 5. Good / Base / Bad Cases
|
||||
|
||||
- Good: a five-node cluster with five external arms returns `5 臂非规则路口`.
|
||||
- Base: debug is off, so no shape summaries are returned.
|
||||
- Bad: reading `intersection_surface.geojson` returns no complex cores and makes
|
||||
the UI falsely appear to lack classification.
|
||||
|
||||
### 6. Tests Required
|
||||
|
||||
- Compiler: assert `complex-core` has the expected shape kind and arm count for
|
||||
a real OSM cluster.
|
||||
- Service/UI: assert debug state reads the road-surface core and the workspace
|
||||
renders the received label without node-count inference.
|
||||
|
||||
### 7. Wrong vs Correct
|
||||
|
||||
```js
|
||||
// Wrong: complex cores are not stored in this layer.
|
||||
readLayer('layers/intersection_surface.geojson')
|
||||
|
||||
// Correct: project compiler-owned properties from their published layer.
|
||||
readLayer('layers/road_surface.geojson')
|
||||
```
|
||||
@@ -260,3 +260,14 @@ one. `handle.constraintId` — present only when a constraint exists — is also
|
||||
- [ ] Every input channel meets at the shared exits, not a parallel path
|
||||
- [ ] Displayed bounds round inward, so an offered extreme is accepted
|
||||
- [ ] A focused field is not rewritten by an arriving preview
|
||||
|
||||
## 15. Complex shape display is server-owned
|
||||
|
||||
`WorkbenchState.debug.junctionShapes` is a debug-only read model keyed by
|
||||
`clusterId`. JunctionTools may display `label` and `armCount` for the currently
|
||||
opened cluster, but it must not derive T/十字/偏置 shapes from `nodeIds.length`.
|
||||
The same internal node layout can resolve to different external-arm topology.
|
||||
|
||||
If no summary exists, omit the shape row and retain normal cluster context; do
|
||||
not show an inferred fallback. The compiler's safe fallback has no complex core
|
||||
and therefore no summary.
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,60 @@
|
||||
# 复杂路口形态与参数编辑设计
|
||||
|
||||
## 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 约束动态生成。
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,24 @@
|
||||
# 执行计划
|
||||
|
||||
1. [x] 抽取复杂路口的 arm 分组和外部道路过滤逻辑,建立稳定的 `junctionShape` 分类投影。
|
||||
2. [x] 为 `cross`、`t-junction` 和 `multi-arm` 增加分类单测,覆盖节点布局不等于最终形态的情况。
|
||||
3. [x] 将复杂几何核心区改为按有效 arm 包络生成,并让角部设施按真实相邻臂生成;不可靠形态回退普通路口。
|
||||
4. [x] 增加基础夹角异常/不足臂回退测试;单向与人行道组合继续沿用 arm 级生成规则,待真实样例回归时补充视觉覆盖。
|
||||
5. [x] 将 `shapeKind`、结构摘要投影到 Workbench 状态,JunctionTools 只展示后端结果。
|
||||
6. [x] 使用真实 OSM 样例完成编译回归:枫树二路样例覆盖 4 臂偏置十字与 3 臂 T 字,5 节点样例覆盖多臂非规则;两臂不足形态确认安全回退。浏览器视觉截图仍待手工执行。
|
||||
7. [x] 通过普通路口回归、复杂路口编译测试、客户端类型检查、构建和格式检查后,再考虑参数编辑设计。
|
||||
|
||||
## Validation
|
||||
|
||||
- `npm run test`
|
||||
- `npm run test:client`
|
||||
- `npm run test:client:unit`
|
||||
- `npm run format:check`
|
||||
- `npm run build`
|
||||
- 真实 OSM 导入/编译及 JunctionTools 手工检查
|
||||
|
||||
## Rollback Points
|
||||
|
||||
- shape 分类投影可独立回退,不改变 cluster 配置格式。
|
||||
- 臂级/角级几何生成保留旧模板分支,出现视觉回归时可按 cluster 或 feature flag 回退。
|
||||
- UI 摘要字段缺失时使用现有候选/cluster 文案,不阻断普通路口页面。
|
||||
@@ -0,0 +1,66 @@
|
||||
# 复杂路口形态与参数编辑规划
|
||||
|
||||
## Goal
|
||||
|
||||
让复杂路口渲染适配真实路口形态,而不是把所有候选都按 `2×2` 十字路口处理。用户需要在独立 JunctionTools 页面中看到与实际拓扑一致的道路面、斑马线、停止线、中央区域、角部圆角和人行道转角,覆盖 `2×2`、`2×1`、T 字和必要的非规则三臂/多臂路口。
|
||||
|
||||
## Confirmed Technical Facts
|
||||
|
||||
- `src/compile/complex-junction.js` 当前按方向将进口分组为 `arms`,并生成道路面、斑马线、停止线、角部岛、圆角填充和人行道转角。
|
||||
- 当前实现要求至少 3 个外部进口,但圆角、角部设施和中心区域的几何仍带有四臂/对称路口假设。
|
||||
- `2×1` 的问题不只是车道数少,还涉及是否存在相向车道、中央分隔带和对应的角部设施。
|
||||
- T 字路口只有三个有效外部进口,不应闭合生成不存在的第四个角部或第四组穿行设施。
|
||||
- 复杂路口当前参数编辑尚未开放,JunctionTools 中复杂模式仍是只读。
|
||||
|
||||
## Proposed First Phase
|
||||
|
||||
1. 根据有效进口臂数量、每臂车道/车行道成员、相邻夹角和道路方向,识别十字、偏置十字、T 字、三臂非规则和不支持形态。
|
||||
2. 将几何生成拆成“臂级元素”和“角级元素”:只为真实存在的臂生成进口、停止线和对应斑马线,只为真实相邻角生成角部岛、圆角和人行道转角。
|
||||
3. 对单车道/单向臂关闭不适用的中央分隔逻辑,避免 `2×1` 被套用 `2×2` 的双向中央结构。
|
||||
4. 对无法可靠识别或几何质量不足的形态保留普通路口回退,并给出可理解的诊断。
|
||||
5. 第一阶段复杂路口参数继续只读;待形态识别和渲染稳定后,再开放按形态约束的参数编辑。
|
||||
|
||||
## Domain Model For Follow-Up Design
|
||||
|
||||
复杂路口需要先建立结构模型,再生成几何,避免把几何参数当成形态判断:
|
||||
|
||||
1. **拓扑层**:有效进口臂数量、进口臂之间的夹角、是否为 T 字/十字/偏置十字/非规则三臂。
|
||||
2. **车行结构层**:每条臂的单向/双向状态、每方向车道数、道路宽度、中央分隔或导流结构。
|
||||
3. **交通组织层**:每条进口臂对应的停止线、斑马线、转向车道、导流岛和行人过街关系。
|
||||
4. **几何表现层**:道路面、核心冲突区、角部圆角、人行道转角和车道线;这些元素必须由前面三层推导,而不是固定套用四臂模板。
|
||||
|
||||
JunctionTools 后续应在页面顶部显示可理解的结构摘要,例如“3 臂 T 字 · 2 个方向 × 每方向 1 车道 + 1 条单向支路”,让用户先确认系统对路口的理解,再编辑参数。
|
||||
|
||||
## Terminology Constraint
|
||||
|
||||
“2×2”和“2×1”描述的是组成复杂路口的原始节点布局或合并结构,不是车道数,也不能直接决定最终路口外观。`2×1` 可以形成 T 字,也可以形成十字或偏置十字。
|
||||
|
||||
实现必须将两个概念分开:
|
||||
|
||||
1. **节点布局**:候选 cluster 内的节点数量、相对排布和短连接关系;仅用于候选选择与几何推导。
|
||||
2. **最终路口形态**:由 cluster 边界向外延伸的有效道路臂、方向、夹角和连接关系判定为十字、T 字、偏置十字或非规则形态;这是 UI 文案和生成规则的依据。
|
||||
|
||||
产品不得用“2×1”直接给用户解释为 T 字。应使用“4 臂十字路口”“3 臂 T 字路口”等最终形态文案;必要时才在高级信息中展示节点布局。
|
||||
|
||||
## Out of Scope For First Phase
|
||||
|
||||
- 不同时开放复杂路口的核心半径、进口宽度、圆角等自由拖拽编辑。
|
||||
- 不修改 OSM 拓扑,不自动创建或删除道路、设施或节点。
|
||||
- 不要求一次覆盖所有任意角度和多层立交形态;超出识别范围的路口必须安全回退。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `2×2` 路口保持现有视觉质量,且只生成真实存在的臂和角部元素。
|
||||
- [ ] `2×1` 路口不再出现双向四车道专属的多余中央/角部结构。
|
||||
- [ ] T 字路口不生成不存在的第四臂、第四组斑马线或闭合角部设施。
|
||||
- [ ] 至少有一个真实 OSM 样例覆盖每种形态,并有几何/诊断回归测试。
|
||||
- [ ] 不支持或识别不确定的形态回退为普通路口,并给出可理解原因。
|
||||
- [ ] 复杂路口现有选择、刷新保持、普通路口编辑和地图编号功能不回归。
|
||||
|
||||
## Open Product Decision
|
||||
|
||||
无。节点布局与最终形态必须独立判断;下一步设计将以真实 OSM 样例验证这组分类规则。
|
||||
|
||||
## Final Planning Boundary
|
||||
|
||||
本任务第一阶段只解决“理解并正确渲染复杂路口”,不开放自由几何编辑。分类依据必须来自 cluster 外边界的有效道路臂和连接关系;cluster 内部节点布局只用于确定合并范围和中心,不作为形态名称。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "complex-junction-shapes",
|
||||
"name": "complex-junction-shapes",
|
||||
"title": "复杂路口形态与参数编辑规划",
|
||||
"description": "",
|
||||
"status": "in_progress",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-09-04",
|
||||
"completedAt": null,
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
Reference in new issue
Block a user