Files

que01 12aeda9a63 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=[]。

2026-08-21 11:59:03 +08:00

6.9 KiB

Raw Blame History

Pipeline：Node 构建管线

覆盖 scripts/*.js 与 scripts/lib/scene-layers.js。运行时：宿主机 Node（CommonJS，无构建步骤）。这是管线里唯一能启动外部进程的层。

先读哪一篇

你要做的事	读
改九个 osm2streets 图层（增/删/改顺序/改色）	图层表 ← 最容易出静默错误
调 QGIS / GDAL / Blender 子进程	外部工具调用
加阶段、加 CLI 参数、改配置字段	CLI 与阶段
改区域诊断/质量门命令或共享区域配置归一化	CLI 与阶段和质量门
改 stage manifest 写入、读取或 stale 判断	CLI 与阶段
改复合路口几何（`buildComplexJunctionGeometry`、车道控制避让、人行道转角）	CLI 与阶段的复合路口小节
改预览页生成	../preview/
声称"纯重构，产物不变"	产物一致性指南

数据流全景

config/areas/<id>.json
      │
      ▼  lib/area-config.js — normalizeAreaConfig() 推导全部输出路径
      │
      ▼  build-area.js — 阶段调度
   _pipeline/osm2streets-qgis.config.json          （派生配置）
      │
      ├─[intermediates]─▶ build-osm2streets-qgis.js（显式 legacy/reference）
      │                     osm2streets-js-node 解析 .osm
      │                     → splitLayers() 拆成九个图层
      │                     → normalize-lane-arrows.py（QGIS Python）
      │                     → osm2streets_web_out/*.geojson
      │                     → osm2streets_scene.geojson + _scene_style.json
      │                     → ogr2ogr 导入 <id>.gpkg
      │                     → QGIS 生成 .qgz + -preview.png
      │                     → _pipeline/stages/intermediates.manifest.json
      │
      ├─[reimport]──────▶ reimport-gpkg.js         （反向，与 intermediates 互斥）
      │                     ogr2ogr 从 .gpkg 导出 → 校验 → 覆写 *.geojson
      │                     → 重建 scene.geojson + scene_style.json
      │                     → _pipeline/stages/reimport.manifest.json
      │
      ├─[blender]───────▶ compile-native-roads.js + Blender + blender/generate_scene.py
      │                     默认读 .osm + native-road/
      │                     → <id>.blend + <id>.png
      │                     → _pipeline/stages/blender.manifest.json
      │
      ├─[cesium]────────▶ Blender + blender/export_cesium.py
      │                     读 .blend → _pipeline/package-staging/models/<id>.glb
      │                     + staged manifest，动态预览 GLB 写入 _preview/
      │                     → _pipeline/stages/cesium.manifest.json
      │
      ├─[compress]──────▶ 压缩 staging 内主 GLB 并更新 staged manifest
      │                     → _pipeline/stages/compress.manifest.json
      │
      ├─[package]───────▶ 校验 manifest 与全部静态模型，原子发布 package/
      │                     → package/manifest.json + package/models/*.glb
      │                     → _pipeline/stages/package.manifest.json
      │
      └─[preview]───────▶ 生成 <id>-cesium-preview.html（native 可无车辆路线）
      │                     + 拷贝 lib/cesium-preview.{js,css}
                            + _preview/ 车辆巡航路线、模型、动态信号
      │                     → _pipeline/stages/preview.manifest.json

阶段之间只通过磁盘产物耦合，不传内存状态。这是单跑任意阶段能work 的前提。

三条贯穿全层的约定

单一事实源优先于同步 九个图层的定义在 lib/scene-layers.js，四个派生函数覆盖了全部合法用法。看到第二处枚举这些图层，就是 bug 温床。详见图层表。
有副作用之前先把能验的都验完 数值参数 → 输入文件 → 外部可执行文件 → 才 mkdirSync。见 build-osm2streets-qgis.js:41-70。
外部工具的产物先落 staging，校验通过才覆盖 ogr2ogr 失败会留 0 字节文件。详见外部工具调用。

文件速查

文件	行数	职责
`build-area.js`	主入口：区域配置读取、阶段调度、package 发布、preview 文件写入和 stage manifest ownership
`diagnose-area.js`	36	快速诊断入口：调用共享 area diagnostics 并打印完整报告
`check-area.js`	74	区域质量门入口：调用共享 area diagnostics，输出 PASS/FAIL 并设置退出码
`lib/area-diagnostics.js`	776	共享区域诊断事实源：OSM、产物、metadata、stage manifest、GLB digest 和质量门分类
`lib/area-config.js`	135	区域配置归一化与输出路径推导，供 build / diagnose 复用
`lib/stage-manifest.js`	100	stage manifest 路径、文件记录、GLB budget warning 和原子 JSON 写入
`build-osm2streets-qgis.js`	1468	intermediates：osm2streets 解析、图层拆分、人行道转角合成、GeoPackage 与 QGIS 工程生成
`reimport-gpkg.js`	179	reimport：GeoPackage → GeoJSON 反向导出
`lib/scene-layers.js`	164	九个图层的单一事实源 + 四个派生函数
`lib/vehicle-route.js`	约 180	从 OSM 提取确定性预览巡航路线
`lib/vehicle-model.js`	约 150	生成内嵌 buffer 的预览车辆 glTF
`lib/area-preview.js`	约 110	复制 preview runtime、生成 HTML 与转义配置注入
`lib/package-contract.js`	package manifest 校验、相对 URI 与 SHA-256 完整性记录
`lib/cesium-preview.js` / `.css`	672 / 230	预览页运行时，见 ../preview/
`normalize-lane-arrows.py`	182	合并 osm2streets 的三角网箭头（跑在 QGIS Python 里）
`parity.js`	270	产物一致性校验驱动
`glb-digest.js`	132	GLB 结构摘要，CLI、build manifest 和诊断脚本共用

技术选型现状

CommonJS，无构建、无 TypeScript、无 lint 配置。保持现状；引入工具链是独立决定，不要夹带在功能改动里
零运行时依赖（osm2streets-js-node 是唯一 dependency）。加依赖前先确认标准库真的做不到
同步 API 优先（execFileSync / spawnSync / readFileSync）。这是一次性跑完的批处理工具，不是服务，异步只会增加错误处理复杂度
macOS 专用路径假设（.app/Contents/MacOS/...）。跨平台不在当前范围内

6.9 KiB Raw Blame History Unescape Escape

Pipeline：Node 构建管线

先读哪一篇

数据流全景

三条贯穿全层的约定

文件速查

技术选型现状

6.9 KiB

Raw Blame History