Author SHA1 Message Date
que01 f4a4d48e3f fix: correct participant simulation timing and queue key fallbacks
- Align signal phase evaluation with the Cesium simulation clock so speed
  control multipliers keep vehicles and traffic lights in sync
- Clamp long frame gaps instead of freezing all participants; short steps
  keep IDM deceleration clamps effective near stop lines
- Fall back to approachRoadId for lane grouping when movement.fromLaneId
  is missing, preventing side-by-side vehicle overlap on shared lanes
- Guard against a missing toggleVehicles DOM element inside the tick loop
- Use template.id as the pedestrian queue key for consistent Map lookups
- Report participant_route_too_short diagnostics instead of silently
  dropping pedestrian and bicycle templates shorter than 5 m
2026-10-10 16:07:53 +08:00
que01 7ce412e52e feat: add participant runtime simulation with traffic signal scheduling
- Implement deterministic participant simulation in cesium-preview.js with
  fixed-seed arrival, IDM car-following, stop-line constraints, and
  geometric conflict occupancy detection
- Build native traffic simulation participants from road package data
  including signal phase mapping, crosswalk centerlines, and lane routing
- Add participant runtime regression test covering 600 s simulation,
  green-only releases, and 2D bounding box overlap checks
- Update model URI prefix to _preview/ so simulation JSON resolves assets
  relative to area output directory
- Sync Trellis spec and task docs for participant scheduling contract
2026-10-10 16:07:00 +08:00
que01 c1277af16a Fix native island material rendering 2026-09-29 12:04:29 +08:00
que01 b6d30787cd chore: record journal 2026-09-22 14:17:53 +08:00
que01 5125e097af chore(task): archive 09-17-local-build-console 2026-09-22 14:16:31 +08:00
que01 3760650c70 feat: add local build console 2026-09-22 14:15:32 +08:00
que01 4ec4372b35 chore: record Cesium export optimization session 2026-09-17 17:15:43 +08:00
que01 7818e17d18 chore(task): archive 09-17-cesium-export-performance 2026-09-17 17:13:54 +08:00
que01 c6cce44f60 perf: batch Cesium export mesh preparation 2026-09-17 17:12:42 +08:00
que01 a4dfbf884a chore: remove deprecated native compiler commands 2026-08-26 13:24:31 +08:00
que01 82dcb83663 chore: keep ZIP import task active 2026-08-26 13:04:32 +08:00
que01 7e8fcd82ed chore: record ZIP artifact task completion 2026-08-26 12:59:31 +08:00
que01 eaa7c08f6a fix: finalize ZIP preview freshness and parity 2026-08-26 12:58:36 +08:00
que01 113ea54535 feat: import native road packages from ZIP 2026-08-26 12:51:58 +08:00
que01 009fe34f79 chore: record journal 2026-08-26 11:01:54 +08:00
que01 7883a451c5 chore(task): archive 08-25-rc-p3-render-separation 2026-08-26 10:58:41 +08:00
que01 620127031e feat: consume manifest-driven native roads 2026-08-26 10:55:47 +08:00
que01 5704b51315 chore: record journal 2026-08-26 09:32:22 +08:00
que01 969b57106f chore(task): archive 08-25-rc-p2-repo-split 2026-08-26 09:28:33 +08:00
que01 7d4b3b566a docs: specify external road compiler contract 2026-08-26 09:27:09 +08:00
que01 5cde08090e refactor: consume external road compiler 2026-08-26 09:23:46 +08:00
que01 b78cb6e990 chore: record journal 2026-08-25 17:28:26 +08:00
que01 b44c995457 chore(task): archive 08-25-rc-p1-package-boundary 2026-08-25 17:27:53 +08:00
que01 2469cfdbff test: make road compiler fixtures self contained 2026-08-25 17:27:19 +08:00
que01 284d3dbedb chore: remove migrated workbench sources 2026-08-25 17:22:50 +08:00
que01 f542a64924 refactor: move road workbench into compiler package 2026-08-25 17:18:49 +08:00
132 changed files with 3892 additions and 15974 deletions

No files matched your search

+2
View File
@@ -5,3 +5,5 @@ __pycache__/
assets/models/speedtree/ assets/models/speedtree/
assets/models/lyrog/ assets/models/lyrog/
inputs/osm inputs/osm
inputs/console/
.build-console/
+28
View File
@@ -307,6 +307,34 @@ npm run build:area -- --config config/areas/<area>.json --stages blender,cesium,
| 直接用 Cesium `Model.getMaterial().setValue()` 改普通 glTF PBR 材质 | 运行时数字仍保持原色,不能实现相位字色 | | 直接用 Cesium `Model.getMaterial().setValue()` 改普通 glTF PBR 材质 | 运行时数字仍保持原色,不能实现相位字色 |
| 每个信号灯各自生成 0-19 全套倒计时 mesh | 节点和几何按信号数量线性膨胀;应按两个 phase group 共享 | | 每个信号灯各自生成 0-19 全套倒计时 mesh | 节点和几何按信号数量线性膨胀;应按两个 phase group 共享 |
## Cesium 导出准备:依赖图更新边界
`export_cesium.py` 的 `prepare_independent_meshes(candidates)` 只优化可证明为对象局部的
准备工作。Blender 的 `bpy.ops` 调用前后会更新 view layer;对约 1,744 个对象逐个调用
选择、修改器及模式切换会重复评估整个场景。实测原导出 173 秒中绝大部分用于更新,
采用以下边界后约 16 秒;不能全局 monkey-patch 或禁用 `_view_layer_update`。
- `select_only(obj)` 用选择数据 API;空修改器栈在改变上下文前直接返回。
- 原有修改器仅允许已证明局部的 `BEVEL` 进入预处理;其他类型保持原顺序回退。
- `batch_triangulate_meshes` 使用真正的 Triangulate 修改器及当前 Blender 默认值,
一次评估后通过 `new_from_object(..., preserve_all_data_layers=True)` 获取结果。
必须先收集所有结果,再替换原网格;替换/删除修改器会使 evaluated 数据失效。
共享、形状键、自定义法线、库链接、fake-user 保留网格不进入这个复制路径。
- `mesh_has_multiple_users` 按 Blender `ID_REAL_USERS` 判断:`users - int(use_fake_user)`。
对多个真实用户的网格,原修改器应用本来就失败,提前跳过保持原拓扑与共享关系。
- 缺 UV 的已准备网格在临时小场景逐对象调用原 `smart_project`,通过 `window.scene`
保持编辑模式上下文一致;有 UV 的模型资产不重展。退出必须恢复窗口场景和 view layer,
删除临时场景。无法满足条件时使用原操作路径。
验证使用 `blender/tools/check_export_preparation.py -- --baseline <original_export_cesium.py>`
在真实 Blender 内比对 control、共享网格、形状键、自定义法线、fake user、Bevel 和
Boolean 依赖回退。真实区域还必须比全部主/分类/动态 GLB 的结构摘要、解码后的索引、
坐标、UV、法线、切线、材质与贴图哈希。不要只用顶点数相同证明视觉一致。
Blender 4.5 的 Triangulate 默认 quad method 是 shortest diagonal,并非 BEAUTY。
直接换成 BMesh BEAUTY 会改变拆面和后续 UV,不能称为等价提速。任何替代算法必须先
核对源码默认值和属性转换路径。详见任务 `09-17-cesium-export-performance/research/`。
## 第三方资产导入的源文件边界 ## 第三方资产导入的源文件边界
第三方 Blend 只属于一次性入库工具的输入,不能成为 `build:area` 或 Cesium 预览的运行时依赖。 第三方 Blend 只属于一次性入库工具的输入,不能成为 `build:area` 或 Cesium 预览的运行时依赖。
+5
View File
@@ -147,6 +147,11 @@ cp config/examples/template.json config/areas/my-area.json
| `junctionTemplates.clusters[].cornerRadiusMeters` | `12`(4–25) | 仅 `complex-junction-v1`:相邻进口夹角处路缘圆角的半径。圆角切于两侧最外道路边缘,只补齐夹角处的路面,不改变 connector、信号或停止线。 | | `junctionTemplates.clusters[].cornerRadiusMeters` | `12`(4–25) | 仅 `complex-junction-v1`:相邻进口夹角处路缘圆角的半径。圆角切于两侧最外道路边缘,只补齐夹角处的路面,不改变 connector、信号或停止线。 |
| `junctionTemplates.clusters[].outerRadiusExtraMeters` | `18`(18–35) | 仅 `complex-junction-v1`:路口中心到外部进口交接边界的额外半径。用于让圆角包住角部斑马线;未配置时保持原有 18 m。 | | `junctionTemplates.clusters[].outerRadiusExtraMeters` | `18`(18–35) | 仅 `complex-junction-v1`:路口中心到外部进口交接边界的额外半径。用于让圆角包住角部斑马线;未配置时保持原有 18 m。 |
`junctionTemplates.references[*].referenceFile` 与
`junctionTemplates.clusters[*].referenceFile` 是唯一允许相对写法的路径:相对当前
`config/areas/<id>.json` 解析。`readAreaConfig()` 会先将其规范化为绝对路径,再通过
`toRoadCompilerInput()` 传入 road compiler;包内不得自行解析相对路径或读取配置文件。
### `v2xPreview` ### `v2xPreview`
这是 Cesium 验证预览的可选实时叠加层,不进入发布的 `package/`。默认值: 这是 Cesium 验证预览的可选实时叠加层,不进入发布的 `package/`。默认值:
+3 -2
View File
@@ -18,6 +18,7 @@
| 改复合路口几何(`buildComplexJunctionGeometry`、车道控制避让、人行道转角) | [CLI 与阶段](./cli-and-stages.md#可编辑信号设施与运行时锚点的跨阶段消费) 的复合路口小节 | | 改复合路口几何(`buildComplexJunctionGeometry`、车道控制避让、人行道转角) | [CLI 与阶段](./cli-and-stages.md#可编辑信号设施与运行时锚点的跨阶段消费) 的复合路口小节 |
| 改预览页生成 | [../preview/](../preview/index.md) | | 改预览页生成 | [../preview/](../preview/index.md) |
| 声称"纯重构,产物不变" | [产物一致性指南](../guides/artifact-parity-guide.md) | | 声称"纯重构,产物不变" | [产物一致性指南](../guides/artifact-parity-guide.md) |
| Native road compiler CLI、输入或完成标记 | [编译器契约指针](./native-road-package.md) |
--- ---
@@ -46,8 +47,8 @@ config/areas/<id>.json
│ → 重建 scene.geojson + scene_style.json │ → 重建 scene.geojson + scene_style.json
│ → _pipeline/stages/reimport.manifest.json │ → _pipeline/stages/reimport.manifest.json
│ │
├─[blender]───────▶ compile-native-roads.js + Blender + blender/generate_scene.py ├─[blender]───────▶ native-road ZIP importer + Blender + blender/generate_scene.py
│ 默认读 .osm + native-road/ │ 默认读 .osm + validated ZIP cache/
│ → <id>.blend + <id>.png │ → <id>.blend + <id>.png
│ → _pipeline/stages/blender.manifest.json │ → _pipeline/stages/blender.manifest.json
│ │
@@ -0,0 +1,62 @@
# Native Road Package Contract
The native-road package is maintained in the private `road-compiler` repository:
`https://git.app.que01.top/que01/road-compiler`
The host consumes a read-only ZIP exported by the private `road-compiler` repository. The host never installs or invokes the compiler. `nativeRoadPackage` is resolved relative to the area config, hashed, validated, and extracted into `_pipeline/native-road-import/<sha256>/` before native consumers start.
The completion marker is `NATIVE_ROAD_COMPILE_DONE <json>`. `build-area.js` validates the marker's count, JSON payload, area id, output path, process status, and signal before starting Blender.
## Scope / Trigger
This contract applies to native-road consumption from `scripts/build-area.js`, diagnostics, parity, Blender, and native preview generation.
## Signatures
```text
road-compiler --input <RoadCompilerInput.json>
```
`RoadCompilerInput` contains `areaId`, absolute `osmFile`, `outDir`, `stagingDir`, `overridesFile`, `trafficSignalsFile`, optional `comparisonDir`, and `options`.
## Contracts
The compiler writes `compiled.json`, `diagnostics.json`, `comparison.json`, signal runtime files, `manifest.json`, and GeoJSON layers under `outDir`. Since `native-road-package/v1.1`, `manifest.json` is required: it declares every GeoJSON source, whether its role is renderable (`surface` / `marking`) or semantic, and the host material slot for renderable layers. The Blender adapter rejects a missing or invalid manifest, a declared/published GeoJSON mismatch, and an unknown material slot. On success stdout contains exactly one marker whose JSON includes `areaId`, `roads`, `endpoints`, `diagnostics`, and `output`.
## Validation & Error Matrix
| Condition | Required result |
|---|---|
| CLI cannot start | throw the spawn error |
| non-zero exit or signal | fail with status/signal |
| zero completion markers | fail |
| multiple completion markers | fail |
| malformed marker JSON | fail |
| marker `areaId` or `output` mismatch | fail |
## Good / Base / Bad Cases
- Good: host writes an absolute input JSON, runs the installed exact-tag CLI, validates one marker, then starts Blender.
- Base: compiler emits deterministic files and no optional comparison source exists.
- Bad: host imports compiler source, reads `config/areas` inside the package, or accepts a missing/duplicate marker.
## Tests Required
- `scripts/test-road-compiler-cli.js` asserts marker success, missing, duplicate, malformed, area mismatch, and output mismatch cases.
- `scripts/road-parity.js` compares `contentHash`, `orderHash`, feature counts, and byte counts for both supported areas.
- `npm run test:road-workbench` asserts the workbench is loaded from the installed package.
## Wrong vs Correct
Wrong:
```js
require("../packages/road-compiler/src/compile/compiler");
```
Correct:
```js
spawnSync(process.execPath, [compilerCli(), "--input", inputFile]);
```
+11
View File
@@ -100,6 +100,17 @@ if (oneway !== "-1") edges.push(makeEdge(way, refs, coords, "forward"));
if (!isOneWay(oneway)) edges.push(makeEdge(way, [...refs].reverse(), [...coords].reverse(), "backward")); if (!isOneWay(oneway)) edges.push(makeEdge(way, [...refs].reverse(), [...coords].reverse(), "backward"));
``` ```
## 本地参与者调度校验
`scripts/lib/cesium-preview.js:createParticipantSimulation()` 使用固定种子的间隔到达、IDM 跟驰、
进口停止线约束和几何冲突占用。排队及占用检测仅包含已到达且仍活动的参与者;首次放行必须
同时更新路程和 committed 状态。进入路口后不再服从出口方向的信号灯,但仍让行前方过街者。
行人及自行车仅在配对方向红灯且剩余时间足够完成过街时进入,启动全红不放行过街者。
回归命令:`npm run test:participant-runtime`。可传真实生成数据进行 600 秒的放行、通行完成
及二维包围盒重叠检查:`node scripts/test-participant-runtime.js outputs/fengshu-er-road/_preview/fengshu-er-road-traffic-simulation.json`。
这是展示级调度校验,不代替 GLB 模型实际外形、车身原点和浏览器渲染的检查。
## 信号动态 GLB 契约 ## 信号动态 GLB 契约
`traffic_signals.json` 的 `pose.*` 是 Blender 静态设施、动态灯珠和倒计时共享的锚点。Blender `traffic_signals.json` 的 `pose.*` 是 Blender 静态设施、动态灯珠和倒计时共享的锚点。Blender
@@ -184,6 +184,10 @@ registry.list() -> VehicleRecord[]
平滑:用 `Cesium.SampledPositionProperty` 按 `duration` 插值,替代当前的直接赋值跳变。 平滑:用 `Cesium.SampledPositionProperty` 按 `duration` 插值,替代当前的直接赋值跳变。
模型资产闭包:dashboard 的车辆模型已复制到本项目 `assets/models/v2x-vehicles/`,由
`scripts/lib/vehicle-library.js` 构建时复制到输出预览目录。运行时不访问
`/Users/que01/Project/wbza_web`;外部 dashboard 仅作为模型来源与契约参考。
### 4.5 宽松解析(R9) ### 4.5 宽松解析(R9)
源项目用 `saferEval`。浏览器端零依赖不能引入该库,也不应引入 `eval`。改为 源项目用 `saferEval`。浏览器端零依赖不能引入该库,也不应引入 `eval`。改为
@@ -59,7 +59,7 @@
### R8 车辆模型命名与资产对齐 ### R8 车辆模型命名与资产对齐
- OBU 数据层标记为 `car_obu.glb`,但 dashboard 的实际 `CrossCars` 模板固定渲染 `11.glb`;预览必须遵从该最终渲染契约。目标识别车辆使用 `${type}${subType}.glb`。 - OBU 数据层标记为 `car_obu.glb`,但 dashboard 的实际 `CrossCars` 模板固定渲染 `11.glb`;预览必须遵从该最终渲染契约。目标识别车辆使用 `${type}${subType}.glb`。
- 预览包必须携带 dashboard 实际使用的车辆模型;包内缺少未知车型时回退到 `11.glb`,并在面板提示,不得静默显示错误车型。 - 预览包必须携带已复制到本项目 `assets/models/v2x-vehicles/` 的 dashboard 实际使用车辆模型;构建和运行时不得读取 dashboard 外部路径。包内缺少未知车型时回退到 `11.glb`,并在面板提示,不得静默显示错误车型。
### R9 推送体解析健壮性 ### R9 推送体解析健壮性
- 源项目对两个车辆 socket 使用 `saferEval` 而非 `JSON.parse`,说明载荷不保证严格 JSON。 - 源项目对两个车辆 socket 使用 `saferEval` 而非 `JSON.parse`,说明载荷不保证严格 JSON。
@@ -1,74 +0,0 @@
# Phase 2 执行计划
## Step 1 — 前置
- [ ] Phase 1 的 AC1.1–AC1.8 全绿
- [ ] 定档 §「待决策」四项(仓库名 / 托管 / 分发 / 过渡期策略)
## Step 2 — 拆出仓库(保历史)
```bash
# 方案 A:subtree split
git subtree split --prefix=packages/road-compiler -b road-compiler-export
# 在新目录初始化并拉入该分支
# 方案 B:filter-repo(更彻底,推荐)
git clone --no-local . /tmp/road-compiler-split
cd /tmp/road-compiler-split
git filter-repo --path packages/road-compiler/ --path-rename packages/road-compiler/:
```
⚠️ 注意:Phase 1 的搬迁若用了 `git mv`,历史可 `--follow` 追溯;
若用了删除+新建,`filter-repo` 只能追到 Phase 1。
**Phase 1 搬迁时必须用 `git mv`** —— 这条已在 Phase 1 implement Step 3 隐含,
此处显式记录依赖。
- [ ] 拆出后验证:`git log --follow src/compile/native-road.js | tail -20`
能看到 08-13 native-road-compiler 的提交
## Step 3 — 新仓库自持化
- [ ] `package.json` 补全依赖(含 K4 的 OpenLayers)
- [ ] `npm install && npm test` 在新仓库独立通过
- [ ] 基线 JSON 迁入 `test/baseline/`
- [ ] 契约文档迁入 `docs/`
- [ ] README:契约摘要 + 与宿主项目关系说明
## Step 4 — 宿主改造
- [ ] `package.json` 依赖指向新仓库(开发期 `file:`)
- [ ] `build-area.js` 改子进程调用 + 解析 `NATIVE_ROAD_COMPILE_DONE`
- [ ] `area-config.js` 的 `toRoadCompilerInput()` 输出改为 CLI 参数或 input JSON 文件
- [ ] 删除 `packages/road-compiler/`(或按过渡期决策保留)
- [ ] `.trellis/spec/pipeline/` 加契约指针
## Step 5 — 验证
```bash
# 宿主端到端
npm run build:area -- --config config/areas/fengshu-er-road.json
# 三区域 parity
for a in fengshu-er-road hanyang-block nantaizi-lake-innovation-valley; do
node scripts/road-parity.js --config config/areas/$a.json \
--compare .trellis/tasks/08-25-road-compiler-extraction/baseline/$a.json || echo "FAIL $a"
done
# 反向依赖为 0(在新仓库内跑)
grep -rn "osm2streets-qgis-workflow\|area-config" . --exclude-dir=node_modules --exclude-dir=.git \
&& echo "VIOLATION"
# 锁版本检查
node -e 'const d=require("./package.json").dependencies;console.log(d)' | grep -i road
```
- [ ] 在一台未 clone 宿主的环境(或 `/tmp` 全新 clone)验证 AC2.2
## Review Gate
AC2.1–AC2.7 全绿。特别是 AC2.2(脱离宿主可自测)—— 这是"独立可维护"的实质。
## Rollback
- 宿主依赖改回 `file:packages/road-compiler`(若过渡期保留了该目录)
- 或 `git revert` 宿主侧改造 commit;新仓库留着不影响宿主
@@ -1,80 +0,0 @@
# Phase 2:拆仓库
父任务:`.trellis/tasks/08-25-road-compiler-extraction/`
技术设计:父任务 `design.md` §1.3(消费方式)、§2(模块清单)
## Goal
把 `packages/road-compiler/` 拆成保留 git 历史的独立仓库,
宿主改为锁版本依赖 + 子进程调用消费。
## Requirements
### R2.1 保留 git 历史 🔴
- 用 `git subtree split` 或 `git filter-repo` 拆出,**不得**用 `cp` + `git init`
- 理由(父任务 R3.2):1695 行几何逻辑的 blame 是踩坑记录,
丢了以后没人敢改 `compileGeometry` 里任何一行
- 验证:新仓库内 `git log --follow src/compile/native-road.js` 能看到
08-13 native-road-compiler 以来的完整历史
### R2.2 子进程为主契约
- 宿主 `build-area.js` 改为 `execFileSync` 调编译器 CLI,
解析 `NATIVE_ROAD_COMPILE_DONE` stdout 标记(父任务 design §1.3)
- in-process `require` 可保留为可选优化路径,但不得是唯一路径
- 与既有 QGIS / GDAL / Blender 调用方式一致
(见 `.trellis/spec/pipeline/external-tools.md`)
### R2.3 锁版本依赖
- 开发期:`file:` 或 workspace 依赖
- 稳定后:git tag / 私有 npm,宿主 `package.json` **锁具体版本,不用 `latest`**
- 契约版本 `native-road-package/v1` 与包版本分开演进:
包可以发 patch,契约版本只在破坏性变更时升
### R2.4 K4:workbench 依赖自持
- `road-workbench` 的 OpenLayers 从新仓库自己的 `node_modules` 提供
- import map 路径相应调整
### R2.5 基线迁移
- Phase 0 的三区域基线 JSON 搬进新仓库当测试语料(父任务 R4 第三条)
- 新仓库 CI/test 能独立跑 parity,无需宿主在场
- **同时**宿主保留一份,用于验证升级编译器版本后产物未变
### R2.6 契约文档迁移
- `docs/native-road-package-v1.md` 搬进新仓库
- 宿主 `.trellis/spec/pipeline/` 留指针,说明契约由编译器仓库拥有
## Acceptance Criteria
- [ ] AC2.1 新仓库 `git log --follow` 能追到搬迁前的历史
- [ ] AC2.2 新仓库 `npm test` 在**未 clone 宿主**的机器上通过
- [ ] AC2.3 宿主从锁版本依赖构建,三区域 parity 对基线全绿
- [ ] AC2.4 `build-area.js` 走子进程路径,`NATIVE_ROAD_COMPILE_DONE` 被正确解析
- [ ] AC2.5 宿主 `package.json` 依赖为具体版本,非 `latest` / 非 `*`
- [ ] AC2.6 编译器仓库对宿主反向依赖数为 0(父任务 AC8,grep 验证)
- [ ] AC2.7 `npm run road:workbench` 在新仓库内独立可跑
## 依赖与顺序
- **前置**:Phase 1 完成且 AC1.1–AC1.8 全绿
- **阻塞**:Phase 3、Phase 4
## 待决策(进入本阶段时定)
| 项 | 选项 |
|---|---|
| 仓库名 | `road-compiler` / `native-road-compiler` / `osm-road-compiler` |
| 托管 | GitHub 私有 / 公开 / 内部 git |
| 分发 | git tag 依赖 / 私有 npm registry |
| 宿主过渡期 | 是否保留 `packages/road-compiler/` 一段时间做双跑对照 |
## Out of Scope
- layer manifest(Phase 3)
- drawtonomy 扩展(Phase 4)
- 任何编译器内部逻辑改动 —— 本阶段代码内容不变,只换位置与消费方式
@@ -22,11 +22,12 @@
"08-25-rc-p0-contract-baseline", "08-25-rc-p0-contract-baseline",
"08-25-rc-p1-package-boundary", "08-25-rc-p1-package-boundary",
"08-25-rc-p2-repo-split", "08-25-rc-p2-repo-split",
"08-25-rc-p3-render-separation" "08-25-rc-p3-render-separation",
"08-26-rc-p5-artifact-consumption"
], ],
"parent": null, "parent": null,
"relatedFiles": [], "relatedFiles": [],
"notes": "", "notes": "P3 已完成。P5 artifact-only parent 已建立,P5A ZIP export 已在 road-compiler v0.3.0 完成;P5B 宿主 ZIP import 待实施。",
"meta": { "meta": {
"next_task": "08-25-rc-p4-drawtonomy-ext" "next_task": "08-25-rc-p4-drawtonomy-ext"
} }
@@ -0,0 +1,3 @@
{"file":".trellis/spec/blender/testing.md","reason":"P3 scene digest parity 是消费迁移的回归门槛。"}
{"file":".trellis/spec/pipeline/native-road-package.md","reason":"验证 ZIP 解压后的 v1.1 contract、areaId 和 source 集合。"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"验证导入迁移不改变 Blender 产物结构。"}
@@ -0,0 +1,23 @@
# P5 Artifact-Only Road Package Design
P5 replaces the current runtime dependency boundary with a file-only boundary:
```text
road-compiler Web editor
-> deterministic root-flat native-road-package/v1.1 ZIP
-> osmWorkflow config nativeRoadPackage
-> private verified extraction cache
-> Blender / Cesium / preview
```
The road-compiler repository owns export and all editing/compiler internals. osmWorkflow owns ZIP safety,
contract validation, Blender materials and downstream scene construction. Neither repository reads the
other's source, configuration, overrides or runtime implementation.
The ZIP is immutable input and the host's `_pipeline/native-road-import/<sha256>` is disposable cache.
The host rejects unsafe archive topology before writing files, then validates v1.1 `manifest.json` and
area identity before starting Blender. Stage manifests record the ZIP hash and resolved package records.
P5A publishes a fixture/exporter first. P5B uses that fixture to remove compiler CLI installation and
invocation from the host. The migration is intentionally a contract-preserving transport change: rendered
geometry and material behavior must remain at the P3 baseline.
@@ -0,0 +1,3 @@
{"file":".trellis/spec/pipeline/native-road-package.md","reason":"宿主与编译器之间的现有文件契约。"}
{"file":".trellis/spec/pipeline/external-tools.md","reason":"ZIP 导入必须在 Blender 副作用前完成安全校验。"}
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"导出、Node 导入、Blender 和 preview 的跨层数据流。"}
@@ -0,0 +1,14 @@
# P5 Integration Plan
1. Complete P5A in `road-compiler`: deterministic Web/CLI ZIP export plus supported-area fixtures and a
tagged compiler release.
2. Complete P5B in `osmWorkflow`: safe importer, config migration, CLI/dependency removal and downstream
descriptor migration.
3. Run the shared end-to-end gate on `fengshu-er-road` and `nantaizi-lake-innovation-valley`:
import ZIP -> Blender -> Cesium -> package -> preview -> area checks.
4. Compare Blender scene digests to P3 control; run negative ZIP tests and legacy provider tests.
5. Record contract docs in both repositories, commit each repository independently, then archive both
children and this integration parent.
Integration rollback: restore the host's previous tagged compiler dependency and compile adapter. ZIP export
is additive and its generated files remain valid standalone artifacts.
@@ -0,0 +1,95 @@
# 道路包导入与纯消费管线
父任务:`.trellis/tasks/08-25-road-compiler-extraction/`
本任务是集成 parent:导出与导入分别在 road-compiler 和宿主仓库实现,只有两个子任务的
端到端 ZIP 契约都通过后才完成。
## Goal
让 road-compiler Web 导出的 `native-road-package/v1.1` 成为 Blender 管线的唯一
native-road 输入。宿主只校验并消费完整道路包,不再安装、调用或理解道路编译器。
用户价值:人工在 road-compiler Web 编辑后,导出道路包即可稳定交给 Blender / Cesium
构建;编辑成果不再通过发布新的编译器代码版本传播。
## Confirmed Facts
- P3 已使 Blender 通过 `manifest.json` 消费 `layers/*.geojson`,并拒绝无效 manifest、
source/file 不一致和未知宿主材质槽。
- 宿主当前仍通过 `scripts/build-area.js` 调用 `scripts/lib/road-compiler-cli.js`;后者安装并
运行 `@osm-asset/road-compiler`,将 `RoadCompilerInput` 写入 `_pipeline/`。
- native Blender 构建当前强制使用 `outputs/<area>/native-road/`,并在每次构建前重新编译;
宿主还持有 `nativeRoad.edgeLines`、`junctionTemplates`、overrides 和 compiler runtime
路径等编译器内部概念。
- `osm2streets` 是显式 legacy/debug provider,应保持现有行为。
- 有效验证区域只有 `fengshu-er-road` 与 `nantaizi-lake-innovation-valley`;
`hanyang-block` 不参与。
## Requirements
### R1 纯产物边界
- native provider 只接收一个完整 `native-road-package/v1.1` 目录。
- 宿主不得依赖 `@osm-asset/road-compiler`,不得调用 compiler CLI,不得写
`RoadCompilerInput`,不得读取或解释 compiler overrides / junction templates。
- 宿主以 manifest 作为道路图层事实源,Blender 不增加 compiler 专用图层表。
### R2 ZIP 导入配置和校验
- 每个 native 区域配置一个道路包 ZIP 路径;路径相对于区域配置文件解析并可指向工作区外的
road-compiler Web 导出文件。
- ZIP 根目录必须直接包含 `manifest.json` 和契约定义的文件;不得接受多余顶层目录、绝对路径、
`..` 路径或符号链接。
- 在启动 Blender 前,宿主将 ZIP 安全解压到其私有 pipeline staging 目录,校验 manifest
契约版本、`areaId` 和当前区域一致,并记录 ZIP hash 和展开文件记录到 stage manifest。
- ZIP 永远只读:宿主不复制、覆盖或修改 road-compiler Web 的导出文件;成功或失败后仅清理
自己的临时解压目录。
- Blender 继续校验 manifest 的图层、source、semantic 角色、材质槽和 splitBy 规则。
### R3 后续阶段
- Cesium、package、preview 和区域诊断从导入道路包读取原生车道中心线、signals 和
其他既有 native-road 输入;不重新编译或复制道路包。
- build stage manifest 将道路包作为外部输入记录,而非宿主输出。
### R4 清理和迁移
- 删除宿主对 compiler npm 包、CLI 封装和编译脚本的生产依赖。
- 删除或替换只测试宿主编译行为的测试;保留 package-contract、Blender 和下游消费测试。
- 更新示例配置、README、pipeline spec 和道路包契约,明确 Web export -> host consume
的单向关系。
## Acceptance Criteria
- [ ] AC1 `package.json` / lockfile 和生产脚本不再引用 `@osm-asset/road-compiler` 或其 CLI。
- [ ] AC2 两个有效区域均可从配置指定的已导出 ZIP 道路包运行 Blender、Cesium、package 和 preview,
构建期间没有 compiler 子进程。
- [ ] AC3 宿主在 Blender 前拒绝缺失包、错误 contract、错误 areaId 和无效 manifest;错误说明
指向导入包和契约,而非 compiler 内部。
- [ ] AC4 Blender scene digest 与 P3 control 基线一致;native semantic 层仍不生成几何。
- [ ] AC5 stage manifest / diagnose / check area 将导入道路包记录为输入并能识别缺失或变更。
- [ ] AC6 `osm2streets` legacy provider 行为未变。
- [ ] AC7 文档和配置将人工编辑传播路径表述为 road-compiler Web export -> host consume。
## Out of Scope
- road-compiler Web 的编辑器功能、认证、部署或 UI 改造。
- 修改道路几何、材质、Blender 建筑/植被/水体渲染。
- 新的 manifest 破坏性版本或 lane graph IR。
- 将道路包上传到远程制品库或实现同步服务。
## Key Decision
- Web 导出的是标准 ZIP;宿主配置直接指向 ZIP 而不是目录。ZIP 是跨仓库的不可变交付物,
宿主只在私有 staging 目录中解压和消费,因而没有导出目录 ownership 或覆盖歧义。
## Subtask Map
| 子任务 | 仓库 | 交付物 | 依赖 |
|---|---|---|---|
| `rc-p5a-zip-export` | road-compiler | Web / CLI 可导出的 root-flat `native-road-package/v1.1` ZIP | 无 |
| `rc-p5b-zip-import` | osmWorkflow | 配置、受控解压、校验和纯消费管线 | p5a 的 ZIP fixture |
跨任务验收:同一个 ZIP fixture 必须被 p5b 的两个有效区域构建消费;宿主不得保留
compiler npm 或 CLI 耦合。
@@ -0,0 +1,29 @@
{
"id": "rc-p5-artifact-consumption",
"name": "rc-p5-artifact-consumption",
"title": "道路包导入与纯消费管线",
"description": "让宿主通过配置指向 road-compiler Web 导出的 ZIP 道路包,只校验和消费该版本化文件契约,不再安装或调用编译器。",
"status": "planning",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-26",
"completedAt": null,
"branch": null,
"base_branch": "experiment/road-compiler-rethink",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [
"08-26-rc-p5b-zip-import",
"08-26-rc-p5a-zip-export"
],
"parent": "08-25-road-compiler-extraction",
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1,22 @@
# P5A ZIP Export Design
The compiler owns a pure `exportNativeRoadPackage(result, destination)` function. It writes a
temporary root-flat directory from the already compiled Web/CLI state, validates it with the same
manifest/source validator used by compiler output, then writes a deterministic ZIP. The Web download
handler and CLI are thin callers of this function.
ZIP layout:
```text
manifest.json
compiled.json
diagnostics.json
comparison.json
traffic-signal-assemblies.json
traffic-signals.json
layers/<12 declared sources>.geojson
```
`manifest.generator` is informational only. The host accepts solely the `contract`, `areaId`, and
declared files. ZIP creation normalizes entry order and timestamps so the export is hash-stable.
Failure never replaces a chosen output file.
@@ -0,0 +1,10 @@
# P5A Execution Plan
1. Inspect workbench state ownership and compiler output writer; keep export sourced from the current
compiled state, not host paths.
2. Add deterministic root-flat ZIP writer plus validation and CLI entry point.
3. Add Web download action using the same writer.
4. Add fixtures for root layout, content determinism, manifest/source parity and edited-state export.
5. Export both supported-area fixtures for P5B, run compiler tests, then publish a compiler release.
Rollback: remove the export entry point; no host behavior changes in this subtask.
@@ -0,0 +1,34 @@
# Web 导出原生道路 ZIP 包
## Goal
让 road-compiler Web/CLI 以 root-flat native-road-package/v1.1 ZIP 导出人工编辑后的道路包。
## Requirements
- 从 Web 当前编辑状态导出完整道路包,而不是源代码、npm 包或仅 overrides。
- ZIP 根直接包含 `manifest.json`,并包含全部 manifest 声明的 `layers/<source>.geojson`、
`compiled.json`、`traffic-signals.json` 和 preview 所需的 signal / diagnostics 文档。
- `manifest.json` 的 `contract` 保持 `native-road-package/v1.1`;新增可选 `generator` 元数据
记录应用版本和 revision,但不得让宿主依赖该版本。
- Web 提供用户可见的下载操作;CLI 提供等价、可测试的 ZIP 导出入口。
- ZIP 条目顺序、JSON 序列化和压缩时间戳必须确定性,重复导出未编辑内容的文件 hash 一致。
## Acceptance Criteria
- [x] 从 Web 编辑后的区域可下载一个 root-flat ZIP,且无需宿主或 npm 发布。
- [x] CLI fixture 导出 ZIP 后,解压内容通过 compiler 的 `validatePublishedLayers()`。
- [x] ZIP 具有恰好一份 manifest 声明的 layer source,无额外 compiler source / overrides 文件。
- [ ] 两个有效区域导出的 ZIP 可被 p5b 导入并完成 Blender/Cesium/preview 构建。
- [x] 不修改 `compiled.json` 与 v1.1 manifest 的既有渲染语义。
## Out of Scope
- 远程存储、上传、项目历史或多用户协作。
- 修改道路编辑器交互、几何算法或 manifest 主版本。
## Key Decisions
- ZIP 是单个标准交付物,根目录平铺 package 文件,不包裹 area-id 顶层目录。
- ZIP 面向宿主消费,只携带已编译渲染/预览数据;编辑源、OSM 与 overrides 留在 road-compiler
项目中,不泄露为宿主依赖。
@@ -0,0 +1,26 @@
{
"id": "rc-p5a-zip-export",
"name": "rc-p5a-zip-export",
"title": "Web 导出原生道路 ZIP 包",
"description": "让 road-compiler Web/CLI 以 root-flat native-road-package/v1.1 ZIP 导出人工编辑后的道路包。",
"status": "in_progress",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-26",
"completedAt": null,
"branch": null,
"base_branch": "experiment/road-compiler-rethink",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-rc-p5-artifact-consumption",
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1,19 @@
# P5B ZIP Import Design
`scripts/lib/native-road-package.js` becomes the single host adapter. It resolves the config-relative
ZIP path, hashes it, validates central-directory entry names and metadata, and extracts only accepted
regular files to `_pipeline/native-road-import/<sha256>/`. It validates the unpacked manifest and
returns an immutable package descriptor:
```text
{ zipFile, zipRecord, rootDir, manifest, records }
```
The descriptor replaces `area.outputs.nativeRoadDir` as native input for Blender, native preview traffic,
diagnostics and stage manifests. The configured ZIP and unpacked cache are inputs, never published area
outputs. Cache invalidation is by ZIP SHA-256; cleanup only deletes importer-owned hash directories.
The importer rejects any non-root-flat layout, duplicate path, symlink, unsupported compression/error,
path traversal, invalid manifest, area mismatch or declared/published mismatch before Blender starts.
The native compiler CLI dependency and host-owned `nativeRoad` compilation options are removed. Legacy
`osm2streets` remains an explicit separate provider.
@@ -0,0 +1,12 @@
# P5B Execution Plan
1. Add config normalization for `nativeRoadPackage`, migrate two supported configs and the template.
2. Add the tested ZIP importer with bounded extraction, root-flat/path/symlink validation, SHA cache and
manifest/area validation.
3. Route Blender, preview traffic, stage manifests and diagnostics through the imported descriptor.
4. Delete compiler CLI/compile production paths and package dependency; replace their tests with ZIP fixture
and negative importer tests.
5. Update docs/specs, run native/legacy unit suites, build two exported packages, then run Blender parity.
Rollback: restore the old compiler dependency and native compile path in one revert; ZIP exports remain
non-destructive standalone files.
@@ -0,0 +1,40 @@
# ZIP 道路包安全导入与纯消费
## Goal
让 osmWorkflow 配置、校验、解压并消费 road-compiler Web 导出的 ZIP 道路包,移除 compiler runtime 耦合。
## Requirements
- 区域配置以 `nativeRoadPackage` 指向 ZIP,路径相对于该区域配置文件;native provider 不再
接受 compiler options、overrides 或输出目录作为输入。
- 宿主在任何 Blender / Cesium 副作用前,验证 ZIP 文件、条目数量/大小、root-flat 文件路径、
无重复路径、无符号链接、无绝对路径与 `..` 路径。
- 仅将已验证的文件解压至 `<area>/_pipeline/native-road-import/<zip-sha256>/`;解压目录是宿主
私有缓存,绝不写回 ZIP 或 road-compiler 导出目录。
- 共享 importer 为 Blender、preview traffic、diagnose/check 和 stage manifest 提供同一包路径与
文件记录;不能让下游自行按字符串拼接另一份 native-road 目录。
- 移除 compiler package、CLI wrapper、compile script、编译器输入配置、以及只覆盖旧调用链的测试。
## Acceptance Criteria
- [ ] 两个有效区域均从 ZIP 完成 `blender,cesium,package,preview`,构建日志没有 compiler CLI。
- [ ] 缺 ZIP、错误 ZIP、nested root、path traversal、symbolic link、错误 contract、错误 areaId 和
manifest/source 不匹配均在启动 Blender 前失败。
- [ ] stage manifest、`diagnose:area` 与 `check:area` 记录 ZIP hash 和已验证的导入目录;ZIP
修改后会被判 stale。
- [ ] `package.json`、lockfile、生产脚本与宿主测试不再引用 `@osm-asset/road-compiler`。
- [ ] Blender digest 对 P3 control 基线一致;legacy `osm2streets` 路径的单元测试不变。
## Out of Scope
- p5a 的 ZIP 生成与 Web 下载实现。
- ZIP 远程下载、解密、签名验证或制品库管理。
- 改道路内容、材质或 legacy QGIS 行为。
## Key Decisions
- ZIP 是只读输入;宿主缓存的生命周期和目录 ownership 完全属于 `_pipeline/`。
- ZIP 解码由明确声明的 Node ZIP 库完成,而不是依赖系统 `unzip`;这使路径/符号链接校验可控并
可在单元测试中覆盖。
- 只有 `native-road-package/v1.1` 可被导入;契约升级必须另开兼容任务。
@@ -0,0 +1,26 @@
{
"id": "rc-p5b-zip-import",
"name": "rc-p5b-zip-import",
"title": "ZIP 道路包安全导入与纯消费",
"description": "让 osmWorkflow 配置、校验、解压并消费 road-compiler Web 导出的 ZIP 道路包,移除 compiler runtime 耦合。",
"status": "in_progress",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-26",
"completedAt": null,
"branch": null,
"base_branch": "experiment/road-compiler-rethink",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-rc-p5-artifact-consumption",
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -66,14 +66,14 @@
## Acceptance Criteria ## Acceptance Criteria
- [ ] AC1.1 两个有效区域 `road-parity --compare` 对 Phase 0 基线全绿 - [x] AC1.1 两个有效区域 `road-parity --compare` 对 Phase 0 基线全绿
- [ ] AC1.2 `npm run test:native-road`、`npm run test:road-workbench` 通过 - [x] AC1.2 `npm run test:native-road`、`npm run test:road-workbench` 通过
- [ ] AC1.3 `npm run build:area` 枫树二路完整跑通(含 blender / cesium 阶段) - [x] AC1.3 `npm run build:area` 枫树二路完整跑通(含 blender / cesium 阶段)
- [ ] AC1.4 `grep -rn "area-config\|config/areas" packages/road-compiler/` 无命中 - [x] AC1.4 `grep -rn "area-config\|config/areas" packages/road-compiler/` 无命中
- [ ] AC1.5 `packages/road-compiler/` 内 `npm test` 不访问宿主 `inputs/` 或 `outputs/` - [x] AC1.5 `packages/road-compiler/` 内 `npm test` 不访问宿主 `inputs/` 或 `outputs/`
- [ ] AC1.6 `scripts/lib/` 下无搬迁文件的残留副本 - [x] AC1.6 `scripts/lib/` 下无搬迁文件的残留副本
- [ ] AC1.7 K1 的「函数 × 使用方」矩阵已产出并归档到 `research/` - [x] AC1.7 K1 的「函数 × 使用方」矩阵已产出并归档到 `research/`
- [ ] AC1.8 `compiled.json` 结构未变(父任务 AC7 / C1) - [x] AC1.8 `compiled.json` 结构未变(父任务 AC7 / C1)
## 依赖与顺序 ## 依赖与顺序
@@ -3,7 +3,7 @@
"name": "rc-p1-package-boundary", "name": "rc-p1-package-boundary",
"title": "Phase 1:包边界(不换仓库)", "title": "Phase 1:包边界(不换仓库)",
"description": "在本仓库内建 packages/road-compiler,移入编译器模块,用窄输入契约替换 readAreaConfig 耦合,产物对基线逐字节一致", "description": "在本仓库内建 packages/road-compiler,移入编译器模块,用窄输入契约替换 readAreaConfig 耦合,产物对基线逐字节一致",
"status": "in_progress", "status": "completed",
"dev_type": null, "dev_type": null,
"scope": null, "scope": null,
"package": null, "package": null,
@@ -11,7 +11,7 @@
"creator": "dingkang", "creator": "dingkang",
"assignee": "dingkang", "assignee": "dingkang",
"createdAt": "2026-08-25", "createdAt": "2026-08-25",
"completedAt": null, "completedAt": "2026-08-25",
"branch": null, "branch": null,
"base_branch": "main", "base_branch": "main",
"worktree_path": null, "worktree_path": null,
@@ -0,0 +1,4 @@
{"file":".trellis/spec/pipeline/external-tools.md","reason":"检查 CLI 子进程错误、signal 与日志处理是否符合宿主管线约定。"}
{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"检查编译阶段、完成标记和 stage manifest 的跨层影响。"}
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"检查配置、Node pipeline、Blender 消费链的边界没有漂移。"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"检查两个有效区域的严格基线 parity。"}
@@ -0,0 +1,44 @@
# Phase 2:独立仓库与 CLI 边界设计
## Architecture
P1 已将实现收敛到 `packages/road-compiler/`。P2 把该目录以保留历史的方式导出为独立 package 仓库,保留两个明确方向的边界:
```
宿主 area config
-> scripts/lib/area-config.js
-> RoadCompilerInput JSON(宿主 staging)
-> @osm-asset/road-compiler CLI(子进程)
-> native-road/ + NATIVE_ROAD_COMPILE_DONE
-> build-area.js / Blender / preview
```
编译器不知道区域配置、宿主仓库、Blender 或宿主输出目录约定以外的输入路径。宿主不知道 compiler 内部源文件;它只拥有输入 JSON、CLI 的完成标记和写出的契约文件。
## CLI Contract
- CLI 接收一个 JSON 文件中的 `RoadCompilerInput`,而不是宿主的 area config。
- `comparisonDir` 继续作为可选输入,以维持现有 `comparison.json` 产物和 P0 baseline 的可比性。
- 成功只打印一次 `NATIVE_ROAD_COMPILE_DONE <JSON>`。payload 必须至少含 `areaId`、`output`、`roads`、`endpoints` 和 `diagnostics`。
- `build-area.js` 保持同步批处理模式,子进程日志对用户可见;为了验证标记,输出同时被捕获或 tee。它对启动失败、非零状态、signal、缺失/重复/非法标记和 payload 与当前输入不一致都报错。
- 产物先由 compiler 的现有 staging/atomic promotion 逻辑写入目标 `native-road/`;宿主不接管这一写入过程。
## Repository Contents
独立仓库拥有:compiler source、public API、CLI、check、workbench、fixture、两个 parity baseline、契约文档、README、package lockfile 和 workbench 的 `ol` 依赖。测试和 workbench 均必须在没有宿主 checkout 的环境运行。
宿主保留:area-config 读取/归一化、`RoadCompilerInput` 映射、pipeline 阶段编排、Blender/preview、区域配置、运行产物和一份升级回归 baseline。宿主 spec 仅保留指针,契约正文随 compiler 仓库维护。
## History Extraction
导出只允许 `git subtree split` 或 `git filter-repo`。必须在独立仓库验证 `git log --follow src/compile/native-road.js`;验证的是迁移前的逻辑历史,而非仅 P1 的边界移动提交。导出和验证先在临时分支/clone 完成,外部远端创建和 push 必须使用用户给出的地址和授权范围。
## Dependency and Rollout
初始发布源定为私有 `https://git.app.que01.top/que01/road-compiler.git`。仓库以带注释 tag `v0.1.0` 首发,宿主以该精确 tag 作为依赖并写入 lockfile。开发临时形态可以指向独立 checkout 的本地 `file:` 依赖;它不能成为验收时的唯一消费方式。两个区域 parity 通过后删除 `packages/road-compiler/`;回滚由 revert 宿主消费改造实现,不能让 production host 继续直接 import 该目录。
## Compatibility and Risks
这是位置和调用方式迁移,不改变 compiler 行为。两个区域的 strict content/order hash 是主要 oracle;信号文档的确定性生成仍应通过 parity 覆盖。P2 不处理 `check:area` 的历史 stage-manifest freshness warning,也不把 Blender/Metal 沙箱问题归因为道路产物。
若外部 CLI 无法及时使用,回滚宿主消费 commit 即可;外部仓库历史和 tag 不需要删除。对于完整 Blender 构建,macOS Metal 初始化必须在提权的宿主环境运行。
@@ -0,0 +1,4 @@
{"file":".trellis/spec/pipeline/external-tools.md","reason":"CLI 子进程必须沿用管线的启动、日志和失败状态语义。"}
{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"编译是 Blender 前的 pipeline 输入阶段,需保持阶段与 stdout 契约。"}
{"file":".trellis/spec/config/index.md","reason":"宿主拥有区域配置归一化及 RoadCompilerInput 映射。"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"本阶段声称产物不变,必须用严格 parity 验证。"}
@@ -0,0 +1,55 @@
# Phase 2 执行计划
执行前提:用户已在最新 P2 规划摘要后明确批准。发布目标已定为私有 `https://git.app.que01.top/que01/road-compiler.git`,首发 tag 为 `v0.1.0`。
## 1. 导出并核验历史
- [ ] 创建临时 export 分支或临时 clone,使用 `git subtree split --prefix=packages/road-compiler` 或 `git filter-repo --path packages/road-compiler/ --path-rename packages/road-compiler/:` 导出。
- [ ] 在导出仓库验证 `git log --follow src/compile/native-road.js` 包含 2026-08-13 以来的 native compiler 历史。
- [ ] 在私有 `https://git.app.que01.top/que01/road-compiler.git` 创建并推送独立仓库;创建带注释的 `v0.1.0` tag。
## 2. 使编译器仓库自持
- [ ] 将 CLI 作为 package `bin` 入口,接受由宿主写出的 `RoadCompilerInput` JSON,并继续输出唯一的 `NATIVE_ROAD_COMPILE_DONE` JSON 标记。
- [ ] 补全 `package.json`、锁文件和 `ol` 依赖;workbench vendor 文件从自身安装目录提供。
- [ ] 迁入 `docs/native-road-package-v1.md`、两个 baseline 和它们的测试驱动,新增独立 README。
- [ ] 在不含宿主文件的临时 clone 内执行依赖安装、单元测试、两区域 parity 与 workbench 启动测试。
- [ ] grep 验证没有 `area-config`、`config/areas`、宿主项目名或宿主相对路径引用。
## 3. 宿主改为外部 CLI 消费
- [ ] 将 compiler 以精确 git tag `v0.1.0` 安装到宿主并记录 lockfile;禁止范围版本、`latest`、`*` 和裸分支。
- [ ] 将 `toRoadCompilerInput()` 序列化到每个区域的 pipeline staging 目录,传给 compiler CLI。
- [ ] 在 `build-area.js` 的 blender 前置阶段调用 CLI。沿用管线的 `spawnSync` / `runCommand` 失败语义(启动错误、exit status、signal)和直通日志;缓冲或 tee stdout 后,解析恰好一个完成标记并验证其 `areaId`、`output` 与当前区域匹配。
- [ ] 将 host workbench 的 fresh compile 回调切换到同一 CLI,不改变 fresh-process 行为。
- [ ] 把所有 host 对 `packages/road-compiler/**` 的直接 import 替换成已安装包的公开 API 或 CLI;两个区域 parity 均通过后删除 in-host 副本。
- [ ] 将宿主 pipeline spec 改为指向编译器仓库所拥有的契约文档。
## 4. 验证与发布门
新仓库(干净 clone):
```bash
npm ci
npm test
npm run test:road-parity
npm run road:workbench -- --config test/fixtures/fengshu-er-road.input.json --no-compile
```
宿主两个有效区域的逐字节 parity:
```bash
node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
--compare .trellis/tasks/08-25-road-compiler-extraction/baseline/fengshu-er-road.json
node scripts/road-parity.js --config config/areas/nantaizi-lake-innovation-valley.json \
--compare .trellis/tasks/08-25-road-compiler-extraction/baseline/nantaizi-lake-innovation-valley.json
```
- [ ] 为 CLI 标记成功、缺失、重复、非法 JSON、areaId 不匹配和 output 不匹配补测试。
- [ ] 跑 package 单测、宿主 native-road / workbench / traffic signals / turn-lane-arrows 测试,以及两个 parity 检查。
- [ ] 使用 `trellis-check` 做最终跨层检查;Blender 完整构建需以提权方式运行,原因是 macOS Metal 初始化不能在沙箱内启动。
## Rollback
- 外部仓库和已发布 tag 保留不动;在宿主 revert 消费改造即可回到 P1 边界。
- 若按决定临时保留 in-host 副本,可将依赖回指该副本以恢复;该退路不取代 host parity 验证。
@@ -0,0 +1,62 @@
# Phase 2:拆仓库
父任务:`.trellis/tasks/08-25-road-compiler-extraction/`
## Goal
把当前 `packages/road-compiler/` 拆为保留 git 历史、可脱离宿主独立测试和运行的仓库;宿主改为消费一个锁定版本的编译器 CLI。这样道路编译器可以独立演进,宿主依然通过版本化文件契约稳定构建场景。
## Confirmed Facts
- P1 已完成:编译器实现和 workbench 的所有权在 `packages/road-compiler/`;宿主负责将区域配置映射为 `RoadCompilerInput`。
- `git log --follow packages/road-compiler/src/compile/native-road.js` 已能追溯到 2026-08-13 的 native-road compiler 历史。
- 契约为 `native-road-package/v1`,完成标记为 `NATIVE_ROAD_COMPILE_DONE <json>`;`comparisonDir` 是可选输入,继续保留 `comparison.json`。
- 当前宿主远端为内部 Git 服务 `https://git.app.que01.top/que01/osmWorkflow.git`;P2 独立编译器仓库定为私有 `https://git.app.que01.top/que01/road-compiler.git`。
- 可维护范围只有 `fengshu-er-road` 和 `nantaizi-lake-innovation-valley`。`hanyang-block` 是废案,不参与基线、测试、验收或迁移语料。
## Requirements
### R2.1 保留 Git 历史
- 用 `git subtree split` 或 `git filter-repo` 导出,不得以复制目录再 `git init` 替代。
- 新仓库中 `git log --follow src/compile/native-road.js` 必须能追溯到 P1 之前的 native-road compiler 提交。
### R2.2 新仓库可独立运行
- 新仓库拥有 compiler、CLI、check、workbench、其测试 fixture、两个 parity baseline、契约文档和 README。
- 新仓库 own `ol` 及其 workbench 所需的运行依赖;workbench 不得从宿主 `node_modules` 提供浏览器资源。
- 新仓库不得引用宿主的 `area-config`、`config/areas`、`scripts/` 或本仓库绝对路径。
### R2.3 宿主的消费边界
- `scripts/lib/area-config.js` 继续是唯一的区域配置归一化与 `RoadCompilerInput` 映射位置。
- `scripts/build-area.js` 用已安装编译器的 CLI 子进程编译,继承 stdout/stderr,检查启动错误、退出状态和 signal,并解析且校验唯一的 `NATIVE_ROAD_COMPILE_DONE` 标记。
- 宿主只依赖 CLI、写入的文件和版本化输入 JSON;不再以相对路径 import 编译器内部模块。保留的宿主 signal 文件 I/O 适配层改为只调用公开包 API。
- `road-workbench` 保持每次编译均启动新进程的语义,但改为调用已安装 CLI。
### R2.4 版本与迁移
- 宿主依赖必须锁定一个具体编译器版本,禁止 `latest` 或 `*`;包版本与 `native-road-package/v1` 的契约版本独立演进。
- 初始分发使用带注释的 git tag `v0.1.0`;宿主锁定该 tag。完整 parity 验证后移除 `packages/road-compiler/`,不保留 in-host 副本作为正常消费路径。
- 宿主保留两份 baseline,用来验证今后升级编译器版本后没有产物漂移。
## Acceptance Criteria
- [ ] AC2.1 独立仓库的 `git log --follow src/compile/native-road.js` 可见 P1 前的 compiler 历史。
- [ ] AC2.2 在未 clone 宿主的干净目录中,新仓库 `npm ci`(或等价锁文件安装)和 `npm test` 均通过。
- [ ] AC2.3 新仓库的两区域 parity(`fengshu-er-road`、`nantaizi-lake-innovation-valley`)均与迁入 baseline 完全一致。
- [ ] AC2.4 宿主用锁版本依赖运行 CLI;`build-area.js` 成功解析一个有效的 `NATIVE_ROAD_COMPILE_DONE` 标记,缺失、重复或非法标记会失败。
- [ ] AC2.5 宿主的两个区域 parity 均对保留 baseline 全绿。
- [ ] AC2.6 宿主 `package.json` 的 compiler 依赖是具体、可复现版本,不是 `latest`、`*` 或裸分支。
- [ ] AC2.7 编译器仓库对宿主反向依赖为 0,且其 workbench 可独立启动。
## Out of Scope
- 编译器几何、规则或输出内容改动。
- 图层 manifest 和道路/建筑渲染分离(Phase 3)。
- drawtonomy 扩展(Phase 4)。
- `hanyang-block` 修复、迁移或作为验收样本。
## Release Decision
独立仓库为私有 `https://git.app.que01.top/que01/road-compiler.git`。首发以带注释 tag `v0.1.0` 发布,宿主依赖精确锁定该 tag;两个区域 parity 均通过后删除 `packages/road-compiler/`。该决定授权 P2 在该内部远端创建和推送仓库,但不授权发布到 npm 或其他托管平台。
@@ -3,7 +3,7 @@
"name": "rc-p2-repo-split", "name": "rc-p2-repo-split",
"title": "Phase 2:拆仓库", "title": "Phase 2:拆仓库",
"description": "保留 git 历史拆出独立仓库,宿主以锁版本依赖消费,子进程为主契约", "description": "保留 git 历史拆出独立仓库,宿主以锁版本依赖消费,子进程为主契约",
"status": "planning", "status": "completed",
"dev_type": null, "dev_type": null,
"scope": null, "scope": null,
"package": null, "package": null,
@@ -11,7 +11,7 @@
"creator": "dingkang", "creator": "dingkang",
"assignee": "dingkang", "assignee": "dingkang",
"createdAt": "2026-08-25", "createdAt": "2026-08-25",
"completedAt": null, "completedAt": "2026-08-26",
"branch": null, "branch": null,
"base_branch": "main", "base_branch": "main",
"worktree_path": null, "worktree_path": null,
@@ -0,0 +1,5 @@
{"file":".trellis/spec/blender/module-structure.md","reason":"检查道路 adapter 与建筑/植被/水体模块的边界没有漂移。"}
{"file":".trellis/spec/blender/testing.md","reason":"检查 Blender 结构摘要、纯 Python schema 测试和提权运行要求。"}
{"file":".trellis/spec/pipeline/index.md","reason":"检查 compiler 输出与 Blender 消费的 manifest 数据流。"}
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"检查三层契约、材质槽和 source 文件名一致性。"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"检查两个区域和 throwaway 图层验证后的产物差异。"}
@@ -0,0 +1,61 @@
# Phase 3:Manifest 驱动的道路渲染设计
## Boundary
道路编译器是图层事实源,输出 `<nativeRoadDir>/manifest.json`;Blender 是渲染适配器,读取 manifest 并用宿主 `catalog.MATERIALS` / `ROAD_LAYERS` 完成材质与高度映射。建筑、植被、水体、OSM legacy 图层不改变。
```
compiler CLI
-> native-road/manifest.json + 12 declared GeoJSON sources
-> generate_scene.py
-> osmassets/native_roads.py
-> catalog material/z lookup
-> roads.assemble_geojson_layer
```
## Manifest v1.1
`manifest.json` 顶层包含 `contract: "native-road-package/v1.1"`、`areaId` 和 `layers`。`layers` 必须恰好声明编译器输出的 12 个 source:
- `road_surface`, `intersection_surface`, `sidewalk_surface`, `edge_lines`, `lane_separators`, `center_lines`, `crosswalks`, `vehicle_stop_lines`, `direction_arrows`, `turn_arrows`
- `lane_centerlines`, `connectors`
每项字段:
```json
{
"source": "center_lines",
"role": "marking",
"materialLayer": "center_lines",
"splitBy": {
"prop": "color",
"cases": [
{"match": "white", "material": "native_center_line_white"},
{"default": true, "material": "center_lines"}
]
}
}
```
`role` 为 `surface` 或 `marking` 时必须有 `materialLayer`;`semantic` 不得有材质要求,Blender 必须跳过其 GeoJSON。`splitBy` 只支持精确属性匹配和一个 default 分支,避免把渲染表达式语言复制进编译器。
编译器在原子提升前校验:每个声明 source 都对应 `layers/<source>.geojson`,目录中没有未声明的 GeoJSON;manifest 自身必须是有效 JSON。新增 manifest 不改变已有文件内容。
## Blender Adapter
新建 `blender/osmassets/native_roads.py`,公开一个接收 `native_road_dir`, `projector`, `collection`, `road_mats`, `material_layers` 的装配函数。模块负责读取/校验 manifest、解析 split cases、调用既有 `roads.assemble_geojson_layer`;不拥有图层注册表、不创建材质、不维护场景总计数。
`generate_scene.py` 仅负责 native-road 目录存在性、catalog material lookup、调用 adapter 和合并 `road_counts`。删除 `catalog.NATIVE_ROAD_LAYERS`;保留 `catalog.ROAD_LAYERS` 作为宿主材质和 z 高度事实源。
未知 `materialLayer`、缺少 source 文件、重复/遗漏 source、非法 role 或非法 splitBy 必须抛出 `RuntimeError`,不能静默跳过。semantic 图层必须不读取 GeoJSON、不创建对象、不增加 road count。
## Compatibility and Rollback
编译器契约从 `native-road-package/v1` 增加到 `v1.1`;manifest 是 v1.1 的必需输出。Blender 不提供旧 manifest fallback,因为新消费边界必须尽早暴露旧 compiler;回滚时恢复 `NATIVE_ROAD_LAYERS` 内联分支即可。旧 v1 产物仍可由旧 compiler tag 生成,不被本阶段改写。
## Verification
- 两个支持区域的 native-road 文件 parity:除新增 `manifest.json` 外所有现有 hash、orderHash、bytes 不变。
- Blender 结构摘要和预览图与 Phase 0 基线一致;完整 Blender/Metal 运行需提权。
- 纯 Python schema/manifest 测试覆盖 12 source、semantic skip、splitBy white/yellow、未知材质、缺文件和额外文件。
- throwaway `debug_probe.geojson` + manifest 实测:不改宿主代码即可生成 Blender 几何;验证后删除 probe 并再次跑 parity。
@@ -0,0 +1,5 @@
{"file":".trellis/spec/blender/module-structure.md","reason":"native_roads.py 必须遵守 osmassets 的 bpy 依赖边界和 roads adapter 责任。"}
{"file":".trellis/spec/blender/testing.md","reason":"Blender 层以结构摘要/parity 为主要回归防线,纯 schema 逻辑需可用系统 Python 测试。"}
{"file":".trellis/spec/pipeline/index.md","reason":"native-road manifest 是跨 compiler/Blender 的 pipeline 文件契约。"}
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"改动同时触及 compiler JSON、Blender Python 和契约文档。"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"本阶段必须证明除新增 manifest 外渲染产物不变。"}
@@ -4,7 +4,7 @@
- [x] 读 `blender/generate_scene.py:796-834` 全部道路分支 - [x] 读 `blender/generate_scene.py:796-834` 全部道路分支
- [x] 列出每个 `source` 的处理方式:直接渲染 / 按属性分流 / 跳过 - [x] 列出每个 `source` 的处理方式:直接渲染 / 按属性分流 / 跳过
- [ ] 已知分流: - [x] 已知分流:
- `center_lines`:`color != "white"` → `center_lines` 材质; - `center_lines`:`color != "white"` → `center_lines` 材质;
`color == "white"` → `native_center_line_white` `color == "white"` → `native_center_line_white`
- `lane_separators`:`color != "yellow"` → `lane_separators`; - `lane_separators`:`color != "yellow"` → `lane_separators`;
@@ -16,17 +16,17 @@
## Step 2 — 定 manifest schema 并落契约 ## Step 2 — 定 manifest schema 并落契约
- [ ] 按父任务 `design.md` §3.2 定稿 schema - [x] 按父任务 `design.md` §3.2 定稿 schema
- [ ] 写入编译器仓库契约文档,版本标为 `native-road-package/v1.1` - [x] 写入编译器仓库契约文档,版本标为 `native-road-package/v1.1`
- [ ] 记录:v1.1 起 `manifest.json` 为必需输出 - [x] 记录:v1.1 起 `manifest.json` 为必需输出
## Step 3 — 编译器侧:生成 manifest ## Step 3 — 编译器侧:生成 manifest
- [ ] 编译器内建立图层注册表(单一事实源),`compileGeometry` 的输出键与之对应 - [x] 编译器内建立图层注册表(单一事实源),`compileGeometry` 的输出键与之对应
- [ ] 写 `manifest.json` 到 outDir - [x] 写 `manifest.json` 到 outDir
- [ ] 编译器自校验:manifest 声明的每个 `source` 都必须有对应 geojson 文件, - [x] 编译器自校验:manifest 声明的每个 `source` 都必须有对应 geojson 文件,
反之亦然(缺一即报错,不静默) 反之亦然(缺一即报错,不静默)
- [ ] parity:此步只**新增** manifest.json,其余文件应逐字节不变 - [x] parity:此步只**新增** manifest.json,其余文件应逐字节不变;hanyang-block 不参与
```bash ```bash
# 只应多出 manifest.json # 只应多出 manifest.json
@@ -36,14 +36,14 @@ node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
## Step 4 — Blender 侧:抽模块 + 读 manifest ## Step 4 — Blender 侧:抽模块 + 读 manifest
- [ ] 新建 `blender/osmassets/native_roads.py` - [x] 新建 `blender/osmassets/native_roads.py`
- [ ] 把 `generate_scene.py:796-834` 的道路分支迁入 - [x] 把 `generate_scene.py:796-834` 的道路分支迁入
- [ ] 改为读 manifest 遍历;`role == "semantic"` 跳过 - [x] 改为读 manifest 遍历;`role == "semantic"` 跳过
- [ ] `splitBy` 通用化实现,替掉两处硬编码 lambda - [x] `splitBy` 通用化实现,替掉两处硬编码 lambda
- [ ] **加断言**:manifest 里的 `materialLayer` 若不在 `catalog.MATERIALS` / - [x] **加断言**:manifest 里的 `materialLayer` 若不在 `catalog.MATERIALS` /
`ROAD_LAYERS` 中,直接 raise,不静默跳过(风险表第二条) `ROAD_LAYERS` 中,直接 raise,不静默跳过(风险表第二条)
- [ ] 删除 `catalog.NATIVE_ROAD_LAYERS` - [x] 删除 `catalog.NATIVE_ROAD_LAYERS`
- [ ] `generate_scene.py` 只保留一行调用 - [x] `generate_scene.py` 只保留一行调用
## Step 5 — 验证 ## Step 5 — 验证
@@ -52,8 +52,8 @@ node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
npm run build:area -- --config config/areas/fengshu-er-road.json npm run build:area -- --config config/areas/fengshu-er-road.json
# 走 artifact-parity-guide 的结构摘要比对 # 走 artifact-parity-guide 的结构摘要比对
# 三区域跑通 # 两个有效区域跑通(hanyang-block 为废案,不参与)
for a in fengshu-er-road hanyang-block nantaizi-lake-innovation-valley; do for a in fengshu-er-road nantaizi-lake-innovation-valley; do
npm run build:area -- --config config/areas/$a.json || echo "FAIL $a" npm run build:area -- --config config/areas/$a.json || echo "FAIL $a"
done done
@@ -61,18 +61,18 @@ done
git diff --stat -- blender/osmassets/ | grep -vE "native_roads|catalog" git diff --stat -- blender/osmassets/ | grep -vE "native_roads|catalog"
``` ```
- [ ] 渲染预览图人工对照(结构摘要粒度不足的兜底) - [x] 渲染预览图人工对照(结构摘要粒度不足的兜底)
## Step 6 — AC3.4 实测(可扩展性证明) ## Step 6 — AC3.4 实测(可扩展性证明)
这一步是整个 Phase 3 的价值证明,不可跳过。 这一步是整个 Phase 3 的价值证明,不可跳过。
- [ ] 编译器加一个 throwaway 图层 `debug_probe.geojson`(几个矩形即可) - [x] 编译器加一个 throwaway 图层 `debug_probe.geojson`(复用 road-surface 几何仅验证 wiring)
+ manifest 声明 `role: "marking"`,复用现有材质槽 + manifest 声明 `role: "marking"`,复用现有材质槽
- [ ] **不改宿主任何代码**,跑 blender 阶段 - [x] **不改宿主任何代码**,跑 blender 阶段
- [ ] 确认 Blender 场景中出现该图层几何 - [x] 确认 Blender 场景中出现该图层几何
- [ ] 截图/记录证据到任务 `research/` - [x] 截图/记录证据到任务 `research/`
- [ ] 回滚 throwaway 图层 - [x] 回滚 throwaway 图层
## Review Gate ## Review Gate
@@ -57,17 +57,17 @@
## Acceptance Criteria ## Acceptance Criteria
- [ ] AC3.1 编译器输出 `manifest.json`,三区域均含全部 12 图层声明 - [x] AC3.1 编译器输出 `manifest.json`,两个有效区域(`fengshu-er-road`、`nantaizi-lake-innovation-valley`)均含全部 12 图层声明
- [ ] AC3.2 `catalog.NATIVE_ROAD_LAYERS` 已删除,Blender 无硬编码道路图层表 - [x] AC3.2 `catalog.NATIVE_ROAD_LAYERS` 已删除,Blender 无硬编码道路图层表
- [ ] AC3.3 `.blend` 结构摘要对 Phase 0 基线一致 - [x] AC3.3 `.blend` 结构摘要对 Phase 0 基线一致
(走 `.trellis/spec/guides/artifact-parity-guide.md`) (走 `.trellis/spec/guides/artifact-parity-guide.md`)
- [ ] AC3.4 **实测**:向编译器加一个 throwaway 图层 + manifest 声明, - [x] AC3.4 **实测**:向编译器加一个 throwaway 图层 + manifest 声明,
不改宿主任何代码,跑 blender 阶段确认它被渲染出来;验证后回滚该图层 不改宿主任何代码,跑 blender 阶段确认它被渲染出来;验证后回滚该图层
(父任务 AC5,见 design §3.4) (父任务 AC5,见 design §3.4)
- [ ] AC3.5 `role: "semantic"` 的图层被 Blender 正确跳过(不产生几何) - [x] AC3.5 `role: "semantic"` 的图层被 Blender 正确跳过(不产生几何)
- [ ] AC3.6 `center_lines` 的 white/非 white 与 `lane_separators` 的 yellow/非 yellow - [x] AC3.6 `center_lines` 的 white/非 white 与 `lane_separators` 的 yellow/非 yellow
分流行为与改造前一致 分流行为与改造前一致
- [ ] AC3.7 建筑/植被/水体渲染代码未被修改(`git diff` 验证范围) - [x] AC3.7 建筑/植被/水体渲染代码未被修改(`git diff` 验证范围)
## 依赖与顺序 ## 依赖与顺序
@@ -0,0 +1,19 @@
# P3 Debug Probe Evidence
Date: 2026-08-26
A temporary, uncommitted compiler registry entry declared `debug_probe` as a
`marking` layer using the existing `road_surface` material slot. Its generated
GeoJSON reused the compiled road-surface collection only for this wiring test.
No host source was changed.
The compiler emitted 13 declared sources. Blender then generated
`/private/tmp/p3-debug-probe.blend`; `SCENE_DONE` reported
`"debug_probe": 30`. The Blender scene digest contains:
```json
{"name":"Road_debug_probe","vertices":274,"polygons":30}
```
The temporary registry entry was removed immediately after the proof. The
standard v0.2.0 compiler was then rerun to restore the normal 12-source output.
@@ -3,7 +3,7 @@
"name": "rc-p3-render-separation", "name": "rc-p3-render-separation",
"title": "Phase 3:道路与建筑渲染分离", "title": "Phase 3:道路与建筑渲染分离",
"description": "编译器输出 layer manifest 自声明图层,Blender 改为读 manifest;道路渲染从 generate_scene.py 抽离,消除跨仓库重复图层表", "description": "编译器输出 layer manifest 自声明图层,Blender 改为读 manifest;道路渲染从 generate_scene.py 抽离,消除跨仓库重复图层表",
"status": "planning", "status": "completed",
"dev_type": null, "dev_type": null,
"scope": null, "scope": null,
"package": null, "package": null,
@@ -11,7 +11,7 @@
"creator": "dingkang", "creator": "dingkang",
"assignee": "dingkang", "assignee": "dingkang",
"createdAt": "2026-08-25", "createdAt": "2026-08-25",
"completedAt": null, "completedAt": "2026-08-26",
"branch": null, "branch": null,
"base_branch": "main", "base_branch": "main",
"worktree_path": null, "worktree_path": null,
@@ -0,0 +1,4 @@
{"_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."}
{"file":".trellis/spec/blender/asset-generation.md","reason":"Asset compatibility"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"Parity acceptance"}
{"file":".trellis/tasks/09-17-cesium-export-performance/research/triangulation-semantics.md","reason":"Source-backed optimization correctness"}
@@ -0,0 +1,15 @@
# Design
## Evidence and theory
Baseline profiler: 179.6 s total, 166 s in 6,917 automatic view-layer updates; all eight exports 4.4 s. Blender `bpy/ops.py` updates the view layer before and after operators. Object-local mesh preparation should not repeatedly evaluate unrelated scene objects. Modifier evaluation may depend on scene relations, so disabling update globally is unacceptable.
A previous direct-BMesh experiment used BEAUTY for quads, unlike Blender's Triangulate modifier SHORTEDGE default. Both use BM_mesh_triangulate. Match parameters and mesh attribute conversion before accepting a direct path; retain original behavior for shared meshes and unsupported custom data. Research official modifier conversion code to explain residual differences.
## Implementation boundaries
Only exporter mesh preparation plus focused verification tools. Early-return for no-op work before selecting objects. Prefer public data APIs for object-local operations; preserve scene evaluation for actual dependent modifiers. Keep original triangulation modifier semantics via batched evaluation if direct BMesh cannot prove equivalence. No monkeypatching Blender internals in production.
## Compatibility and rollback
Same CLI, completion markers, GLB set, ordering, metadata, materials, and source blend. Validation uses temporary output directories. Reject alternatives that alter geometry/UV/normals without an explained contract. Each optimization separately measurable and removable. Existing user changes outside the exporter remain untouched.
@@ -0,0 +1,4 @@
{"_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."}
{"file":".trellis/spec/blender/asset-generation.md","reason":"Deterministic assets and shared mesh contract"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"Output parity and control requirements"}
{"file":".trellis/tasks/09-17-cesium-export-performance/research/triangulation-semantics.md","reason":"Official source proof and safe alternatives"}
@@ -0,0 +1,11 @@
# Execution
- [x] Preserve original exporter and repeat unmodified control on Nantaizi without profiler; baseline second real area.
- [x] Record Blender source/API proof for proposed replacement operations, including triangulation defaults and conversion flags.
- [x] Implement exporter optimization through Trellis implement agent; main agent owns measurement and independent artifact comparisons.
- [x] Validate all GLBs against baseline and control; compare decoded geometry/attributes/images when digest is insufficient.
- [x] Run real Blender edge fixtures and existing pure Python tests.
- [x] Run fresh final benchmarks and cross-agent check; fix any findings.
- [x] Record results/spec contracts and report measured gain plus limitations. No automatic commit.
User approval: previous turn proposed preserving assets while eliminating redundant updates/modifier work; current user explicitly approved, with theory required. This records that accepted scope rather than requesting approval again.
@@ -0,0 +1,25 @@
# Cesium 导出性能优化与产物一致性验证
## Goal
将 Cesium 导出阶段从约 150 秒降至接近 15–20 秒,保持全部资产与视觉语义。用户在性能诊断之后明确同意优化,并要求每项操作有理论依据。
## Requirements
- 每项优化对应测量热点、Blender API/源码依据及可证伪的验证。
- 保留主场景、分类资产、三个动态信号资产、材质、贴图、节点与地理锚点。
- 不全局关闭依赖图更新;保留涉及修改器依赖的正确评估。
- 不降低几何精度、不改材质、删资产或修改浏览器流程。
- 不覆盖用户现有工作区修改;性能及 parity 产物写临时目录。
## Acceptance Criteria
- [x] 同一输入、无 profiler 的前后基准,记录实际耗时与提升倍率;接近 10 倍是目标,不能牺牲正确性。
- [x] 全部 GLB 通过既有结构摘要契约;深入检查几何、UV、法线、切线及纹理,不能通过扩大忽略名单隐藏差异。
- [x] 至少两份真实区域输入及针对共享网格、无修改器、既有 UV 的 Blender 验证。
- [x] 未改动代码 control 复测;相关现有测试通过。
- [x] 理论依据、验证结果、限制记录到任务研究与长期规范。
## Results
Nantaizi 173.227 → 15.905 秒(10.89x);Fengshu 36.891–41.396 → 5.638 秒(6.54–7.34x)。全部结构摘要通过。Nantaizi 解码属性零差异;Fengshu 仅树冠切线存在未改代码 control 已复现的一个四位小数舍入步长波动。详见 `research/measurements.md`,未扩展项目忽略名单。
@@ -0,0 +1,74 @@
// Diagnostic: run from repository root with two export directory arguments.
// Strict 1e-6 comparison; known control noise is reported, never suppressed.
const fs = require('fs');
const path = require('path');
const assert = require('assert/strict');
const crypto = require('crypto');
const {digest} = require(path.join(process.cwd(), 'scripts/glb-digest'));
function glb(file) {
const data = fs.readFileSync(file);
let json, bin;
for (let i=12; i<data.length;) {
const len=data.readUInt32LE(i), type=data.readUInt32LE(i+4);
if(type===0x4e4f534a) json=JSON.parse(data.subarray(i+8,i+8+len));
if(type===0x004e4942) bin=data.subarray(i+8,i+8+len);
i+=8+len;
}
function accessor(id) {
const a=json.accessors[id];
assert(!a.sparse, 'sparse accessor unsupported');
const v=json.bufferViews[a.bufferView];
const n={SCALAR:1,VEC2:2,VEC3:3,VEC4:4,MAT4:16}[a.type];
const [bytes,fn]={5120:[1,'readInt8'],5121:[1,'readUInt8'],5122:[2,'readInt16LE'],5123:[2,'readUInt16LE'],5125:[4,'readUInt32LE'],5126:[4,'readFloatLE']}[a.componentType];
const out=[];
for(let i=0;i<a.count;i++) for(let j=0;j<n;j++) {
out.push(bin[fn]((v.byteOffset||0)+(a.byteOffset||0)+i*(v.byteStride||n*bytes)+j*bytes));
}
return out;
}
function imageHash(image) {
const v=json.bufferViews[image.bufferView];
return crypto.createHash('sha256').update(bin.subarray(v.byteOffset||0,(v.byteOffset||0)+v.byteLength)).digest('hex');
}
return {json, accessor, imageHash};
}
const [before,after]=process.argv.slice(2);
let failures=0;
for(const file of fs.readdirSync(before).filter(f=>f.endsWith('.glb')).sort()) {
const issues=[];
try {
const da=digest(path.join(before,file)), db=digest(path.join(after,file));
for(const d of [da,db]) {delete d.fileBytes;delete d.buffers;delete d.counts.accessors;}
try {assert.deepEqual(da,db);} catch {issues.push('structural digest differs');}
const a=glb(path.join(before,file)),b=glb(path.join(after,file));
for(const key of ['nodes','scenes','scene','materials','textures','samplers','animations','skins','extensions','extensionsUsed','extensionsRequired']) {
assert.deepEqual(a.json[key],b.json[key],key);
}
assert.equal(a.json.meshes.length,b.json.meshes.length);
let maxError=0;
for(let m=0;m<a.json.meshes.length;m++) {
const am=a.json.meshes[m],bm=b.json.meshes[m];
assert.equal(am.name,bm.name);
assert.equal(am.primitives.length,bm.primitives.length);
for(let p=0;p<am.primitives.length;p++) {
const ap=am.primitives[p],bp=bm.primitives[p];
assert.equal(ap.material,bp.material);
assert.deepEqual(Object.keys(ap.attributes),Object.keys(bp.attributes));
for(const key of ['indices',...Object.keys(ap.attributes)]) {
const av=a.accessor(key==='indices'?ap.indices:ap.attributes[key]);
const bv=b.accessor(key==='indices'?bp.indices:bp.attributes[key]);
if(av.length!==bv.length) {issues.push(`${am.name}/${p}/${key}: count ${av.length} -> ${bv.length}`);continue;}
let error=0;
for(let i=0;i<av.length;i++) error=Math.max(error,Math.abs(av[i]-bv[i]));
maxError=Math.max(maxError,error);
if(error>(key==='indices'?0:1e-6)) issues.push(`${am.name}/${p}/${key}: max delta ${error}`);
}
}
}
assert.equal(a.json.images?.length||0,b.json.images?.length||0);
for(let i=0;i<(a.json.images||[]).length;i++) assert.equal(a.imageHash(a.json.images[i]),b.imageHash(b.json.images[i]));
console.log(file, issues.length?'FAIL':'PASS', 'max attribute delta',maxError,issues.slice(0,12));
} catch(e) {issues.push(e.message);console.log(file,'ERROR',e.message.slice(0,500));}
if(issues.length) failures++;
}
process.exitCode=failures?1:0;
@@ -0,0 +1,48 @@
# Performance and parity evidence (2026-09-17)
Environment: local Blender 4.5.12, same existing `.blend` per region, serial runs, all outputs in `/private/tmp/cesium-profile.9ODFNa`. Original exporter preserved there as `original_export_cesium.py`. No source scene or existing output overwritten.
## Measurements
| Input / implementation | Export function wall time |
| --- | ---: |
| Nantaizi original cProfile | 179.596 s |
| Nantaizi original control without profiler | 173.227 s |
| Nantaizi initial production candidate | 33.389 s |
| Nantaizi candidate with shared-mesh guards | 15.337 s |
| Nantaizi final fake-user guard correction | 15.905 s |
| Fengshu original | 41.396 s |
| Fengshu original second control | 36.891 s |
| Fengshu optimized | 5.527 s |
| Fengshu final fake-user guard correction | 5.638 s |
Time excludes Blender process startup; `measure.py` uses perf_counter around export() and per-function timing wrappers, no cProfile. Inputs/outputs and eight/seven export calls unchanged. Final Nantaizi speedup 10.89x; Fengshu 6.54–7.34x. Final Nantaizi eight GLBs again pass with zero decoded attribute delta. Both regions' metadata matches after normalizing output directory prefixes.
## Nantaizi parity
Unchanged control compared with original profiler output: all eight GLBs have identical project structural digests (existing unstable fields excluded), decoded indices/positions/UVs/normals/tangents/other attributes, full nodes/scenes/materials/textures/samplers and embedded image hashes. Maximum numeric delta 0. Initial and shared-guard production candidates both pass these exact comparisons.
## Fengshu control noise
All seven project structural digests match. Six GLBs' decoded attributes also match exactly. `vegetation.glb`, mesh `Tree_Natural_Crowns_DarkMesh`, TANGENT values vary by at most 0.00010001659393310547 between two **unmodified** runs. Optimized versus first baseline has the same maximum; versus second baseline 0.00010000169277191162. Positions, UVs, normals, indices, other meshes and embedded images match. This is not a broad tolerance waiver.
Installed `io_scene_gltf2/blender/exp/primitive_extract.py:1507` rounds tangents to `ROUNDING_DIGIT`, defined as 4 in `io/com/constants.py:159`. A 0.0001 difference is one exporter quantization step. Existing project digest ignores accessor/buffer layout noise, but no project ignore list was expanded for this work.
## Edge fixtures
`blender/tools/check_export_preparation.py` passed in real Blender using original exporter as reference and an unchanged control. Includes asymmetric quad/ngon triangle counts, authored UVs, shared meshes, custom normals, shape keys, Bevel, dependent Boolean, and fake retention user. Compares topology/vertex order/UV/normals/material slots/mesh names/custom properties/sharing/remaining modifiers. Uses 1e-6 numerical tolerance.
Independent review moved edit-mode selection into the cleanup try/finally and added an injected UV failure fixture asserting restoration of original scene/view layer/collection links and no scene leak. Expanded fixture passed after review. All 64 existing pure Python tests, Python compilation and `git diff --check` pass. No project Python lint/type-check configuration exists. No UI screenshot claim: visual semantics checked through decoded render attributes and identical image bytes; no browser rendering code changed.
Reproducible strict comparison: from repo root run `node .trellis/tasks/09-17-cesium-export-performance/research/compare-glb.cjs <baseline-directory> <candidate-directory>`. It reports the Fengshu control tangent noise as a failure at 1e-6, deliberately not masking it. Classify that one known result using the unchanged control evidence above; all project structural digest checks pass.
## Source-backed choices
- Public selection data API avoids operator entry/exit graph updates.
- Empty modifier stack returns before any selection/update.
- Same Triangulate modifier is evaluated in a batch; evaluated meshes copied before mutating original data; preserve all data layers. No BMesh approximation.
- Same UV operator runs one object at a time in a small temporary scene, switched through actual window.scene; normal graph updates stay enabled.
- Shared triangulation skipped using `ID_REAL_USERS = users - fake_user`, matching Blender's failure precondition.
- Unknown modifier stacks retain original ordering; no global monkey patch.
Failed temp_override-only UV investigation was stopped because Blender edit-mode poll requires consistent window scene context; production uses a real temporary scene/window switch instead. Diagnostic global update suppression and mismatched direct-BMesh experiment are not in production.
@@ -0,0 +1,82 @@
# Research: Triangulation semantics and output-preserving optimization
- Query: Explain the temporary direct-BMesh experiment's different GLB vertex counts and identify source-backed faster alternatives.
- Scope: mixed (project source, installed exporter, official Blender 4.5.0 source)
- Date: 2026-09-17
## Findings
### Confirmed algorithm mismatch in the experiment
`blender/export_cesium.py:531` creates a Triangulate modifier and only overrides `min_vertices = 4`. The temporary `/private/tmp/cesium-profile.9ODFNa/profile_export.py:42` instead passes `quad_method='BEAUTY', ngon_method='BEAUTY'` to BMesh.
Blender **4.5.0** `source/blender/makesdna/DNA_modifier_defaults.h:643-649` defines the modifier defaults as:
```
flag = 0
quad_method = MOD_TRIANGULATE_QUAD_SHORTEDGE
ngon_method = MOD_TRIANGULATE_NGON_BEAUTY
min_vertices = 4
```
Thus the experiment is not algorithm-equivalent: quads use shortest diagonal in the baseline and beauty in the experiment. This is a concrete reason to correct the experiment, not speculative parameter tuning. Do not rely on older Blender documentation's defaults; read a temporary modifier's RNA properties on the actual running version if supporting multiple Blender versions.
Both routes ultimately call `BM_mesh_triangulate` (official `MOD_triangulate.cc`, `bmo_triangulate.cc:29-44`). The modifier passes `tag_only=false`; the BMesh operator tags its supplied faces and passes `tag_only=true`. Supplying all eligible faces and matching quad/ngon methods aligns the core algorithm.
### Why GLB vertex counts can differ with equal triangles
Installed `/Applications/Blender.app/Contents/Resources/4.5/scripts/addons_core/io_scene_gltf2/blender/exp/primitive_extract.py:336-344` explicitly explains that Blender corner attributes are packed into per-vertex records for glTF. Deduplication at lines 825 and 900-901 uses the attribute record, not position alone. Normals, tangents and UV discontinuities therefore split vertices without changing triangle count. Changing the quad diagonal can change subsequent normals and UV unwrap even when all positions and triangle totals remain unchanged.
Project preparation order (`blender/export_cesium.py:670-676`) is triangulate then unwrap. Hence changing topology before `smart_project` can also change UV islands. Counts alone do not establish visual parity or identify which attribute actually changed in the existing artifacts; inspect decoded attribute arrays per mesh to attribute the observed count difference definitively.
### Remaining BMesh conversion differences
Official `MOD_triangulate.cc` sets `calc_face_normal=true`, `calc_vert_normal=false` and carries original-index custom-data masks through conversion. Python `BMesh.from_mesh` (`bmesh_py_types.cc:1376-1414`) defaults both normal flags to true; pass `face_normals=True, vertex_normals=False` to match the modifier's inputs more closely.
Modifier `flag=0` means **keep_custom_normals is false by default in 4.5.0**. Therefore do not claim custom-normal preservation is the established reason for this scene's discrepancy. If enabled, the modifier explicitly copies evaluated corner normals into a temporary CD_NORMAL layer and restores normalized custom normals after triangulation. Direct BMesh does not reproduce that explicit procedure automatically.
Python `BMesh.to_mesh` (`bmesh_py_types.cc:1201-1240`) uses `BM_mesh_bm_to_me`, updates shape-key indices/object remaps and tags geometry dirty; modifier output uses `BKE_mesh_from_bmesh_for_eval_nomain`. These are distinct conversion paths. Matching triangulation settings does not constitute a proof of byte-identical mesh output, ordering or custom data. Preserve the baseline fallback for multi-user meshes (`modifier_apply` refuses them); do not change shared topology as a performance side effect.
### Strongest semantic route: keep the actual modifier, batch evaluation
For simple single-user meshes without pre-existing modifiers or shape keys, add the same Triangulate modifier through the data API for all eligible objects, evaluate the dependency graph once, then obtain persistent meshes with `bpy.data.meshes.new_from_object(obj.evaluated_get(depsgraph), preserve_all_data_layers=True, depsgraph=depsgraph)`. Stage every result before replacing source data/removing modifiers, because mutation can invalidate evaluated state. This executes the actual modifier implementation instead of duplicating it in Python.
Official `rna_main_api.cc:1103-1123` says an original object produces undeformed geometry while an evaluated object produces final geometry with all modifiers; preserving all data layers requires a dependency graph. Official `rna_ID.cc:2447-2452` says `evaluated_get` only retrieves the **last** evaluation and does **not** ensure the graph is up to date. An explicit graph evaluation barrier after adding modifiers is mandatory; repeated evaluation per object defeats the optimization.
Limit this fast path to proven equivalent cases. Existing modifier stacks, hidden modifiers, failing modifiers, shape keys, shared meshes and inter-object dependencies are not generally equivalent to the current sequential `modifier_apply` loop. Keep the existing operator fallback for those cases until separately justified. New datablocks must preserve material slots, required custom properties and semantic names; parity must detect unintended instance splitting or GLB naming differences.
### Recommended decision
1. Correct the demonstrated quad-method mismatch before drawing conclusions from direct-BMesh measurements.
2. Prefer batched evaluation of the original modifier if exact parity remains the requirement; its geometric semantics have a stronger equivalence basis.
3. Keep graph updates at real dependency boundaries; never ship the temporary global `_view_layer_update` monkey patch.
4. Require decoded triangle attributes and existing project structure parity, including UVs/normals/tangents and dynamic/shared assets. Do not accept matching counts as sufficient evidence.
## Files found
- `blender/export_cesium.py` — preparation order and baseline modifier/UV operations.
- `/private/tmp/cesium-profile.9ODFNa/profile_export.py` — temporary monkey-patch and direct-BMesh experiment.
- `/Applications/Blender.app/Contents/Resources/4.5/scripts/addons_core/io_scene_gltf2/blender/exp/primitive_extract.py` — glTF corner-attribute splitting and deduplication.
## External references
All source references pinned to Blender `v4.5.0`:
- https://github.com/blender/blender/blob/v4.5.0/source/blender/makesdna/DNA_modifier_defaults.h#L643
- https://github.com/blender/blender/blob/v4.5.0/source/blender/modifiers/intern/MOD_triangulate.cc
- https://github.com/blender/blender/blob/v4.5.0/source/blender/bmesh/operators/bmo_triangulate.cc
- https://github.com/blender/blender/blob/v4.5.0/source/blender/python/bmesh/bmesh_py_types.cc#L1376
- https://github.com/blender/blender/blob/v4.5.0/source/blender/makesrna/intern/rna_main_api.cc#L1103
- https://github.com/blender/blender/blob/v4.5.0/source/blender/makesrna/intern/rna_ID.cc#L2447
## Related specs
- `.trellis/spec/blender/index.md` — Blender/standard-Python boundary and parity requirements.
- `.trellis/spec/blender/asset-generation.md` — deterministic geometry, shared meshes and dynamic export assets.
- `.trellis/spec/blender/testing.md` — mathematical expectations and real Blender parity.
## Caveats / Not Found
- Research only: no Blender runs or changes to product code were performed.
- The algorithm mismatch is proven from source; the exact per-attribute cause of every previously observed vertex-count change is not measured here.
- Batch evaluated-mesh conversion is a source-backed candidate, not a claim of verified output parity or measured speedup.
@@ -0,0 +1,26 @@
{
"id": "cesium-export-performance",
"name": "cesium-export-performance",
"title": "Cesium 导出性能优化与产物一致性验证",
"description": "",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-17",
"completedAt": "2026-09-17",
"branch": null,
"base_branch": "experiment/road-compiler-rethink",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -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
新增 `npm run console` 启动的本机控制服务。服务只绑定 `127.0.0.1`,启动后打开默认浏览器;它以 Node 内置 `http` 提供 JSON API、Server-Sent Events(SSE)和无构建的静态 HTML/CSS/JS。首版不引入 React、Vite、Electron 或数据库。
```text
browser UI
│ HTTP / SSE, localhost only
▼
scripts/build-console.js
├─ configs + diagnostics + stage manifests → area/history cards
├─ import OSM/ZIP → inputs/console/<config-key>/ + ownership record
├─ spawn node scripts/build-area.js → streamed build log/job state
├─ serve outputs/<area-dir>/ as read-only preview assets
└─ validated cleanup target → macOS Trash
```
`build-area.js` continues to own all pipeline stages. The console does not import it in-process or duplicate its business logic; it starts it as a child process with `--config` and optional `--stages`, collecting stdout/stderr for the UI.
## Data and ownership
At startup the service enumerates `config/areas/*.json`, calls the existing `readAreaConfig()` / diagnostics APIs, and reads stage manifests. Those files are the history source of truth.
The import form copies selected OSM and ZIP files into `inputs/console/<config-key>/`. A local ignored ownership record under `.build-console/areas/<config-key>.json` records the configuration filename, managed input paths, ZIP hash, and output directory. It exists only to prove which files the console may clean; ordinary historical configs with external paths remain usable but do not grant deletion authority over those sources.
The ZIP `areaId` is immutable and becomes configuration `id`. Because an explicit Save As must not collide with its source config or generated output, the user-facing configuration key is a separate filesystem-safe slug; a saved copy gets a distinct config filename and explicit `outputs.areaDir` / `fileStem` derived from that key. The package contract keeps the original ZIP `areaId`.
## User flow
1. **Welcome / readiness**: display a short three-step guide and checks for Node, Blender, writable managed input directory, and existing areas. Explain that OSM supplies buildings/landscape while ZIP supplies authoritative roads.
2. **History**: show every `config/areas/*.json` as a card with input locations, tree style, output health, last successful stage and links to preview/package when present.
3. **Import / Save As**: choose OSM and ZIP, inspect ZIP contract and locked `areaId`, choose tree style, select a config key, then copy inputs and atomically write a new config. Existing config edits default to Save As; overwrite requires a typed/explicit confirmation.
4. **Build**: choose standard full build or individual existing stages. At most one build job may run; SSE reports stdout/stderr, named stage progression, completion marker and a concise actionable error summary.
5. **Preview**: link to a read-only `/artifacts/<config-key>/...` route that serves the generated preview HTML and its package-relative assets. Vehicle selection stays in the existing preview runtime, rather than changing build artifacts.
6. **Cleanup**: cards and multi-select provide (a) Clear build outputs and (b) Remove area. A confirmation screen lists regions, file counts and byte totals. Targets must be canonically located under allowed project roots. macOS Finder moves them to Trash; it never calls recursive shell deletion.
## API boundary
- `GET /api/health`, `/api/areas`, `/api/options`: readiness, history cards and supported tree styles.
- `POST /api/import/inspect`: multipart/selected file validation without promoting files; verifies ZIP root/contract/areaId via the shared native package validator.
- `POST /api/areas`: copy managed inputs, write ownership record and new config atomically.
- `POST /api/areas/:key/build`: create one build job; `GET /api/jobs/:id/events` streams SSE logs and terminal state.
- `POST /api/cleanup/preview` and `/api/cleanup/confirm`: separate target computation from confirmation, avoiding a stale/hidden destructive scope.
- `GET /artifacts/:key/*`: safely serve only the selected area output root; reject traversal and arbitrary filesystem paths.
Requests are same-origin, localhost-only and JSON validated. File names are normalized to generated safe names; filesystem writes use staging plus rename. Cleanup uses `realpath` containment checks immediately before moving targets to Trash.
## Compatibility and rollout
- Existing commands and hand-authored configurations remain unchanged.
- Existing configs are visible even when their input paths are external; they are never copied or marked owned until a user explicitly imports/saves a console-managed version.
- The console's new local state and managed imports are gitignored. Normal area config files remain reviewable JSON.
- Rollback is deleting the new console-specific files and npm script; it never changes pipeline output contracts.
## Validation strategy
- Unit tests for config/history discovery, ZIP inspection, ownership classification, safe path rejection, Save As collision handling, cleanup plan creation and destructive-target containment.
- HTTP tests for localhost binding, API validation, SSE job lifecycle and artifact traversal rejection.
- Manual smoke test: import OSM+ZIP, save, full build, preview, clear outputs, rebuild, remove area, restore from Trash if needed.
@@ -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,22 @@
# 本地构建控制台实施计划
1. Create a dependency-free console server and static UI shell; add `npm run console`, localhost-only binding, automatic browser launch and environment/readiness endpoint.
2. Extract/reuse small pipeline-facing helpers for area discovery, diagnostics summary, native ZIP inspection and supported tree-style options. Do not import `build-area.js` as a module.
3. Implement history cards and onboarding: config scanning, manifest/status summary, input descriptions, package/preview links and model option selection.
4. Implement safe import and Save As: upload/copy OSM+ZIP into ignored managed storage, inspect ZIP contract/areaId, atomically write a config with collision-safe output overrides, and record ownership.
5. Implement serialized build jobs with child-process log capture, SSE progress, completion/failure states, and links to the existing generated preview.
6. Implement cleanup planning and confirmation. Validate canonical paths, move only allowed targets to macOS Trash, and cover single/batch clear-output versus remove-area paths.
7. Add focused Node HTTP/unit tests, update README with launch/use/troubleshooting guidance, then manually run the actual imported-area build and preview flow.
## Validation commands
- `node --check` for each new Node entry/helper.
- focused console test command added to `package.json`.
- existing `npm run test:native-road-package`, `npm run test:build-stages`, `npm run test:preview-assets`, and `npm run test:package-contract`.
- `npm run console`, import a valid OSM/ZIP fixture, run a full build, open preview, and exercise both cleanup scopes.
## Risk controls and rollback
- Never bind beyond loopback; do not serve arbitrary paths or allow parallel builds.
- Validate cleanup targets after confirmation and immediately before Trash movement; no `rm -rf` implementation.
- If the UI path fails, existing CLI remains the supported fallback. Removing console files/script rolls back the feature without changing existing area data or output contracts.
@@ -0,0 +1,45 @@
# 本地构建控制台
## Goal
提供一个在本机 localhost 运行的图形控制台,使用户无需记忆命令行即可选择或导入道路构建输入、执行现有构建管线、查看进度并打开 Cesium 预览。
## Confirmed facts
- 当前唯一的交互入口是 `scripts/interactive-build.js`:它枚举 `config/areas/*.json`、选择阶段后调用 `scripts/build-area.js`。
- `build-area.js` 是构建、Blender/Cesium 子进程、package 发布和 preview 写入的唯一所有者;控制台必须调用它,不能复制阶段实现。
- native 区域配置通过 `nativeRoadPackage` 引用 `native-road-package/v1.1` ZIP;导入器会验证 ZIP 契约和 `areaId`,并将其安全解压到私有 pipeline cache。
- Blender 与本地文件系统不能由纯静态浏览器页面直接访问,因此入口必须由本机服务配合浏览器 UI 组成。
- 现有配置及其 `outputs/<area>/_pipeline/stages/*.manifest.json` 是历史输入和构建历史的可读取事实源,不能另建会漂移的重复数据库。
## Requirements
- R1: 以 localhost 页面作为首版交付方式;命令行入口继续可用。
- R2: 首页自动枚举并导入 `config/areas/*.json`,以区域卡片呈现可复用配置、输入摘要、最近构建状态、预览与发布包入口。
- R3: 用户可从界面选择 OSM 与 native-road ZIP,读取 ZIP 的 `areaId` 和契约信息,并在构建前给出 OSM/ZIP/区域 ID 的明确校验反馈。
- R3.1: 成功导入的 OSM 与道路 ZIP 复制到项目托管输入目录;新配置引用托管副本,保证可复现且不依赖 `/tmp` 或用户外部路径。
- R4: 保持首版简单:构建前仅可选择项目已有的植被/树木风格;Cesium 预览中可选择车辆模型。两者分别影响静态场景与演示运行时。
- R5: 用户可选构建阶段并启动现有 build-area 管线,看到实时阶段状态、日志、产物链接与可行动的失败说明。
- R6: 对历史配置的修改默认另存为新配置;覆盖已有配置必须是显式确认操作。
- R6.1: 控制台提供单项清理与批量清理,仅处理它创建的托管输入和本项目生成的区域输出;绝不删除用户在项目外选择的原始文件。首版清理统一移入系统废纸篓,保留恢复机会。
- R6.2: 清理范围分为两级,且单项、批量均适用:`清理构建产物` 仅移除区域输出并保留配置和托管输入;`移除区域` 将区域配置、控制台托管输入和区域输出一并移入废纸篓。批量操作必须先展示受影响区域和文件数,再允许确认。
- R7: 产品内置首次使用引导:说明 OSM、道路 ZIP、模型选项、构建阶段、预览入口和 Blender/Node 环境检查,不以外部 README 代替。
## Out of scope
- 改写道路编译器、ZIP 契约、Blender 几何或 Cesium 预览运行时。
- 远程部署、多用户协作、云端构建或将本机文件上传到第三方服务。
- 第一阶段打包为 macOS `.app`;待 localhost 工作流验证后再评估。
## Acceptance criteria
- [ ] 用户可在浏览器中启动、选择历史区域并重新执行一次已有构建,无需手写 CLI 参数。
- [ ] 用户可导入 OSM 与有效道路 ZIP,且在启动 Blender 前看到 ZIP contract / areaId / 文件缺失的校验结果。
- [ ] 用户可保存为新的区域配置而不改变原配置;显式覆盖有确认保护。
- [ ] 页面可展示构建阶段、实时日志、成功后的 preview URL 与 `package/manifest.json`。
- [ ] 首次使用者可仅依照页面引导完成一次输入、构建和预览,并理解失败时下一步怎么做。
## Technical notes
- native-road ZIP 的 `areaId` 与区域配置 `id` 必须相等;控制台应从 ZIP 读取并锁定该 ID,避免提供必然失败的可编辑字段。
- 控制台管理的输入需要有可判定 ownership 的目录/记录,才能安全实施区域级清理;历史配置引用的外部路径始终视为只读、非托管输入。
@@ -0,0 +1,26 @@
{
"id": "local-build-console",
"name": "local-build-console",
"title": "本地构建控制台",
"description": "",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-17",
"completedAt": "2026-09-22",
"branch": null,
"base_branch": "experiment/road-compiler-rethink",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [],
"notes": "",
"meta": {}
}
+8 -3
View File
@@ -8,8 +8,8 @@
<!-- @@@auto:current-status --> <!-- @@@auto:current-status -->
- **Active File**: `journal-1.md` - **Active File**: `journal-1.md`
- **Total Sessions**: 42 - **Total Sessions**: 47
- **Last Active**: 2026-08-25 - **Last Active**: 2026-09-22
<!-- @@@/auto:current-status --> <!-- @@@/auto:current-status -->
--- ---
@@ -19,7 +19,7 @@
<!-- @@@auto:active-documents --> <!-- @@@auto:active-documents -->
| File | Lines | Status | | File | Lines | Status |
|------|-------|--------| |------|-------|--------|
| `journal-1.md` | ~908 | Active | | `journal-1.md` | ~1022 | Active |
<!-- @@@/auto:active-documents --> <!-- @@@/auto:active-documents -->
--- ---
@@ -29,6 +29,11 @@
<!-- @@@auto:session-history --> <!-- @@@auto:session-history -->
| # | Date | Title | Commits | Branch | | # | Date | Title | Commits | Branch |
|---|------|-------|---------|--------| |---|------|-------|---------|--------|
| 47 | 2026-09-22 | 完成本地构建控制台 | `3760650` | `experiment/road-compiler-rethink` |
| 46 | 2026-09-17 | Cesium 导出性能优化与一致性验证 | `c6cce44` | `experiment/road-compiler-rethink` |
| 45 | 2026-08-26 | Complete manifest-driven native road rendering | `6201270` | `experiment/road-compiler-rethink` |
| 44 | 2026-08-26 | Complete external road compiler split | `5cde080`, `7d4b3b5` | `experiment/road-compiler-rethink` |
| 43 | 2026-08-25 | Extract road compiler package boundary | `73707da`, `d5c58b5`, `f542a64`, `284d3db`, `2469cfd` | `experiment/road-compiler-rethink` |
| 42 | 2026-08-25 | Freeze native road parity baseline | `e7bc7f8` | `experiment/road-compiler-rethink` | | 42 | 2026-08-25 | Freeze native road parity baseline | `e7bc7f8` | `experiment/road-compiler-rethink` |
| 41 | 2026-08-24 | Use live V2X vehicle streams only | `b7031f1` | `fengshu-er-road` | | 41 | 2026-08-24 | Use live V2X vehicle streams only | `b7031f1` | `fengshu-er-road` |
| 40 | 2026-08-24 | Stabilize Fengshu native road compilation | `f1f829c` | `fengshu-er-road` | | 40 | 2026-08-24 | Stabilize Fengshu native road compilation | `f1f829c` | `fengshu-er-road` |
+114
View File
@@ -906,3 +906,117 @@ Completed and archived Phase 0: documented native-road-package/v1, added strict
### Status ### Status
[OK] **Completed** [OK] **Completed**
## Session 43: Extract road compiler package boundary
**Date**: 2026-08-25
**Task**: Extract road compiler package boundary
**Branch**: `experiment/road-compiler-rethink`
### Summary
Completed and archived Phase 1: moved native road compiler, checks, workbench, signal schema, OSM parser, and fixtures into packages/road-compiler; introduced RoadCompilerInput mapping; verified two-area parity and a privileged full Fengshu build.
### Git Commits
| Hash | Message |
|------|---------|
| `73707da` | (see git log) |
| `d5c58b5` | (see git log) |
| `f542a64` | (see git log) |
| `284d3db` | (see git log) |
| `2469cfd` | (see git log) |
### Status
[OK] **Completed**
## Session 44: Complete external road compiler split
**Date**: 2026-08-26
**Task**: Complete external road compiler split
**Branch**: `experiment/road-compiler-rethink`
### Summary
Split road compiler into private road-compiler repository with history, pushed v0.1.2, migrated host to exact-tag CLI consumption, removed in-host package, passed regression tests and two-area parity.
### Git Commits
| Hash | Message |
|------|---------|
| `5cde080` | (see git log) |
| `7d4b3b5` | (see git log) |
### Status
[OK] **Completed**
## Session 45: Complete manifest-driven native road rendering
**Date**: 2026-08-26
**Task**: Complete manifest-driven native road rendering
**Branch**: `experiment/road-compiler-rethink`
### Summary
Published compiler v0.2.2, switched Blender to validated native-road manifests, proved debug-probe extensibility, and verified Blender parity for fengshu-er-road.
### Git Commits
| Hash | Message |
|------|---------|
| `6201270` | (see git log) |
### Status
[OK] **Completed**
## Session 46: Cesium 导出性能优化与一致性验证
**Date**: 2026-09-17
**Task**: Cesium 导出性能优化与一致性验证
**Branch**: `experiment/road-compiler-rethink`
### Summary
基于 Blender 依赖图机制批量三角化并隔离 UV 操作;南太子湖 173.2→15.9 秒,枫树二路 36.9–41.4→5.6 秒。保留全部资产;任务已归档。
### Git Commits
| Hash | Message |
|------|---------|
| `c6cce44` | (see git log) |
### Testing
- [OK] 64 项 Python 测试、真实 Blender 特殊网格与异常清理测试通过;两区域 GLB 结构一致,南太子湖逐属性零差异;枫树树冠切线 0.0001 波动由未改代码 control 复现。
### Status
[OK] **Completed**
## Session 47: 完成本地构建控制台
**Date**: 2026-09-22
**Task**: 完成本地构建控制台
**Branch**: `experiment/road-compiler-rethink`
### Summary
提交本地构建控制台及预览逻辑改动,归档 09-17-local-build-console;通过 preview-assets 与 native-preview-traffic 测试。
### Git Commits
| Hash | Message |
|------|---------|
| `3760650` | (see git log) |
### Status
[OK] **Completed**
+138 -11
View File
@@ -496,6 +496,14 @@ def make_export_material(material):
return result return result
def select_only(obj):
"""Change selection without an operator's scene-evaluation barriers."""
for selected in bpy.context.selected_objects:
selected.select_set(False)
obj.select_set(True)
bpy.context.view_layer.objects.active = obj
def unwrap_mesh(obj): def unwrap_mesh(obj):
if obj.type != "MESH" or not obj.data.polygons: if obj.type != "MESH" or not obj.data.polygons:
return return
@@ -504,23 +512,19 @@ def unwrap_mesh(obj):
# meshes arrive without a UV layer, so that is the reliable discriminator. # meshes arrive without a UV layer, so that is the reliable discriminator.
if obj.data.uv_layers: if obj.data.uv_layers:
return return
bpy.ops.object.select_all(action="DESELECT") select_only(obj)
obj.select_set(True)
bpy.context.view_layer.objects.active = obj
bpy.ops.object.mode_set(mode="EDIT") bpy.ops.object.mode_set(mode="EDIT")
bpy.ops.mesh.select_all(action="SELECT")
try: try:
bpy.ops.mesh.select_all(action="SELECT")
bpy.ops.uv.smart_project(island_margin=0.025, area_weight=0.0) bpy.ops.uv.smart_project(island_margin=0.025, area_weight=0.0)
finally: finally:
bpy.ops.object.mode_set(mode="OBJECT") bpy.ops.object.mode_set(mode="OBJECT")
def apply_mesh_modifiers(obj): def apply_mesh_modifiers(obj):
if obj.type != "MESH": if obj.type != "MESH" or not obj.modifiers:
return return
bpy.ops.object.select_all(action="DESELECT") select_only(obj)
obj.select_set(True)
bpy.context.view_layer.objects.active = obj
for modifier in list(obj.modifiers): for modifier in list(obj.modifiers):
try: try:
bpy.ops.object.modifier_apply(modifier=modifier.name) bpy.ops.object.modifier_apply(modifier=modifier.name)
@@ -528,6 +532,11 @@ def apply_mesh_modifiers(obj):
pass pass
def mesh_has_multiple_users(mesh):
# modifier_apply uses ID_REAL_USERS, excluding the fake retention user.
return mesh.users - int(mesh.use_fake_user) > 1
def triangulate_mesh(obj): def triangulate_mesh(obj):
"""Split n-gons into triangles ahead of the exporter. """Split n-gons into triangles ahead of the exporter.
@@ -544,11 +553,14 @@ def triangulate_mesh(obj):
""" """
if obj.type != "MESH" or not obj.data.polygons: if obj.type != "MESH" or not obj.data.polygons:
return return
# modifier_apply rejects multi-user data before evaluating geometry. Avoid
# creating a modifier and evaluating the whole scene only to remove it in
# the failure handler below; keeping this mesh unchanged is intentional.
if mesh_has_multiple_users(obj.data):
return
if all(len(polygon.vertices) <= 3 for polygon in obj.data.polygons): if all(len(polygon.vertices) <= 3 for polygon in obj.data.polygons):
return return
bpy.ops.object.select_all(action="DESELECT") select_only(obj)
obj.select_set(True)
bpy.context.view_layer.objects.active = obj
modifier = obj.modifiers.new("ExportTriangulate", "TRIANGULATE") modifier = obj.modifiers.new("ExportTriangulate", "TRIANGULATE")
modifier.min_vertices = 4 modifier.min_vertices = 4
try: try:
@@ -559,6 +571,120 @@ def triangulate_mesh(obj):
obj.modifiers.remove(modifier) obj.modifiers.remove(modifier)
def batch_triangulate_meshes(candidates):
"""Evaluate independent Triangulate modifiers in one dependency graph pass.
This uses the actual modifier (including the running Blender version's
defaults), not a BMesh reimplementation. new_from_object on an evaluated
object copies its final geometry; preserve_all_data_layers retains UVs and
other mesh attributes. Stage every result before editing original objects:
assigning data or removing a modifier invalidates evaluated state.
Existing stacks can depend on other objects' unmodified geometry. Leave
their sequential application order untouched, including stacks outside the
export subset. Multi-user meshes, shape keys and custom normals retain the
original operator path, whose restrictions are part of the export behavior.
"""
if any(obj.modifiers for obj in bpy.context.scene.objects):
return
pending = []
for obj in candidates:
mesh = obj.data
if (mesh.users != 1 or mesh.use_fake_user or mesh.shape_keys
or mesh.has_custom_normals or mesh.library or obj.library
or not any(len(p.vertices) > 3 for p in mesh.polygons)):
continue
modifier = obj.modifiers.new("ExportTriangulate", "TRIANGULATE")
modifier.min_vertices = 4
pending.append((obj, mesh, modifier))
if not pending:
return
staged = []
try:
# evaluated_get itself does not update the graph. This explicit barrier
# is required after adding all modifiers, and is intentionally not
# repeated for each object.
depsgraph = bpy.context.evaluated_depsgraph_get()
depsgraph.update()
for obj, source, modifier in pending:
mesh = bpy.data.meshes.new_from_object(
obj.evaluated_get(depsgraph), preserve_all_data_layers=True,
depsgraph=depsgraph)
staged.append((obj, source, modifier, mesh))
for key in source.keys():
mesh[key] = source[key]
except Exception:
for _, _, _, mesh in staged:
bpy.data.meshes.remove(mesh)
for obj, _, modifier in pending:
obj.modifiers.remove(modifier)
raise
for obj, source, modifier, mesh in staged:
name = source.name
obj.data = mesh
obj.modifiers.remove(modifier)
bpy.data.meshes.remove(source)
mesh.name = name
def unwrap_meshes_in_work_scene(candidates):
"""Run the unchanged per-object UV operator against a small scene.
UV projection operates on the original mesh in edit mode, not evaluated
scene geometry. Link the original object into a temporary scene one at a
time so operator barriers do not reevaluate every unrelated scene object.
Switch the window's scene, not just context object overrides: edit-mode
operators require a consistent window/scene/view-layer context.
"""
window = bpy.context.window
if window is None or any(obj.modifiers for obj in bpy.context.scene.objects):
return
# A later fallback triangulation must precede UV projection. Shared meshes
# are also safe here: modifier_apply refuses them, so their topology stays
# unchanged in the original preparation loop.
pending = [obj for obj in candidates if not obj.modifiers
and not obj.data.uv_layers and obj.data.polygons
and (mesh_has_multiple_users(obj.data)
or all(len(p.vertices) <= 3 for p in obj.data.polygons))]
if not pending:
return
original_scene = window.scene
original_layer = window.view_layer
work_scene = bpy.data.scenes.new("Cesium UV work scene")
try:
window.scene = work_scene
for obj in pending:
# Shared mesh UVs are already prepared by their first instance.
if obj.data.uv_layers:
continue
work_scene.collection.objects.link(obj)
try:
unwrap_mesh(obj)
finally:
work_scene.collection.objects.unlink(obj)
finally:
window.scene = original_scene
window.view_layer = original_layer
bpy.data.scenes.remove(work_scene)
def prepare_independent_meshes(candidates):
"""Keep dependency-bearing modifier stacks on the sequential legacy path."""
# Bevel reads this object's geometry and vertex groups. Unlike Boolean,
# Shrinkwrap or Geometry Nodes it cannot read another object's mesh. Apply
# it with the original operator before batching independent triangulation.
# Unknown stack types deliberately keep the original preparation order.
if any(modifier.type != "BEVEL"
for obj in bpy.context.scene.objects for modifier in obj.modifiers):
return
for obj in candidates:
apply_mesh_modifiers(obj)
batch_triangulate_meshes(candidates)
unwrap_meshes_in_work_scene(candidates)
def export_glb(filepath, meshes): def export_glb(filepath, meshes):
"""Export a prepared object subset without changing authoring visibility.""" """Export a prepared object subset without changing authoring visibility."""
bpy.ops.object.select_all(action="DESELECT") bpy.ops.object.select_all(action="DESELECT")
@@ -654,6 +780,7 @@ def export(args):
and not obj.hide_viewport and not obj.hide_render] and not obj.hide_viewport and not obj.hide_render]
total_candidates = max(1, len(candidates)) total_candidates = max(1, len(candidates))
progress.update("prepare scene", 3, "%d mesh objects" % len(candidates)) progress.update("prepare scene", 3, "%d mesh objects" % len(candidates))
prepare_independent_meshes(candidates)
for index, obj in enumerate(candidates, 1): for index, obj in enumerate(candidates, 1):
if any(c.name == "06_TrafficSignalsDynamic" for c in obj.users_collection): if any(c.name == "06_TrafficSignalsDynamic" for c in obj.users_collection):
groups = {slot.material.name for slot in obj.material_slots if slot.material} groups = {slot.material.name for slot in obj.material_slots if slot.material}
+6 -24
View File
@@ -57,6 +57,7 @@ from osmassets import fountain as _fountain # noqa: E402
from osmassets import water as _water # noqa: E402 from osmassets import water as _water # noqa: E402
from osmassets import grass as _grass # noqa: E402 from osmassets import grass as _grass # noqa: E402
from osmassets import roads as _roads # noqa: E402 from osmassets import roads as _roads # noqa: E402
from osmassets import native_roads as _native_roads # noqa: E402
from osmassets import scrub as _scrub # noqa: E402 from osmassets import scrub as _scrub # noqa: E402
from osmassets import tree as _tree # noqa: E402 from osmassets import tree as _tree # noqa: E402
from osmassets import traffic_signals as _traffic_signals # noqa: E402 from osmassets import traffic_signals as _traffic_signals # noqa: E402
@@ -667,6 +668,8 @@ def build(args):
catalog.MATERIALS["native_center_line_white"]) catalog.MATERIALS["native_center_line_white"])
road_mats["native_lane_separator_yellow"] = material_from_spec( road_mats["native_lane_separator_yellow"] = material_from_spec(
catalog.MATERIALS["native_lane_separator_yellow"]) catalog.MATERIALS["native_lane_separator_yellow"])
road_mats["native_island_green"] = material_from_spec(
catalog.MATERIALS["native_island_green"])
traffic_signal_mats = { traffic_signal_mats = {
"metal": material_from_spec(catalog.MATERIALS["traffic_signal_metal"]), "metal": material_from_spec(catalog.MATERIALS["traffic_signal_metal"]),
"housing": material_from_spec(catalog.MATERIALS["traffic_signal_housing"]), "housing": material_from_spec(catalog.MATERIALS["traffic_signal_housing"]),
@@ -798,30 +801,9 @@ def build(args):
if native_road_dir: if native_road_dir:
if not os.path.isdir(native_road_dir): if not os.path.isdir(native_road_dir):
raise RuntimeError("--native-road directory does not exist: " + native_road_dir) raise RuntimeError("--native-road directory does not exist: " + native_road_dir)
material_layers = {layer["id"]: layer for layer in catalog.ROAD_LAYERS} material_layers = {layer["id"]: road_mats.get(layer["id"]) for layer in catalog.ROAD_LAYERS}
for source in catalog.NATIVE_ROAD_LAYERS: material_layers.update({"native_center_line_white": road_mats["native_center_line_white"], "native_lane_separator_yellow": road_mats["native_lane_separator_yellow"], "native_island_green": road_mats["native_island_green"]})
target = source["material_layer"] road_counts.update(_native_roads.assemble(native_road_dir, projector, roads_c, material_layers))
layer = material_layers[target]
source_path = os.path.join(native_road_dir, "layers", source["source"] + ".geojson")
if not os.path.isfile(source_path):
raise RuntimeError("Native road layer is missing: " + source_path)
if source["source"] == "center_lines":
count = _roads.assemble_geojson_layer(
source_path, source["source"], projector, roads_c,
road_mats[target], layer["z"],
lambda props: props.get("color") != "white")
count += _roads.assemble_geojson_layer(
source_path, source["source"] + "_white", projector, roads_c,
road_mats["native_center_line_white"], layer["z"],
lambda props: props.get("color") == "white")
elif source["source"] == "lane_separators":
count = _roads.assemble_geojson_layer(source_path, source["source"], projector, roads_c, road_mats[target], layer["z"], lambda props: props.get("color") != "yellow")
count += _roads.assemble_geojson_layer(source_path, source["source"] + "_yellow", projector, roads_c, road_mats["native_lane_separator_yellow"], layer["z"], lambda props: props.get("color") == "yellow")
else:
count = _roads.assemble_geojson_layer(
source_path, source["source"], projector, roads_c,
road_mats[target], layer["z"])
road_counts[source["source"]] = count
elif geojson_dir and os.path.isdir(geojson_dir): elif geojson_dir and os.path.isdir(geojson_dir):
for problem in catalog.check_layers(geojson_dir): for problem in catalog.check_layers(geojson_dir):
print("Layer catalog warning:", problem) print("Layer catalog warning:", problem)
+5 -14
View File
@@ -50,20 +50,6 @@ SCENE_STYLE_FILE = "osm2streets_scene_style.json"
# Native-road output intentionally maps into existing scene material layers. # Native-road output intentionally maps into existing scene material layers.
# It is a provider adapter, not a second scene-layer registry. # It is a provider adapter, not a second scene-layer registry.
NATIVE_ROAD_LAYERS = (
{"source": "road_surface", "material_layer": "road_surface"},
{"source": "edge_lines", "material_layer": "lane_separators"},
{"source": "intersection_surface", "material_layer": "intersection_surface"},
{"source": "sidewalk_surface", "material_layer": "sidewalks"},
{"source": "lane_separators", "material_layer": "lane_separators"},
{"source": "center_lines", "material_layer": "center_lines"},
{"source": "direction_arrows", "material_layer": "lane_arrows_webscale"},
{"source": "turn_arrows", "material_layer": "lane_arrows_webscale"},
{"source": "crosswalks", "material_layer": "crosswalks"},
{"source": "vehicle_stop_lines", "material_layer": "vehicle_stop_lines"},
)
# Material specs. `kind` selects the builder: # Material specs. `kind` selects the builder:
# solid — flat base colour # solid — flat base colour
# textured — Poly Haven diffuse + normal, optionally tinted # textured — Poly Haven diffuse + normal, optionally tinted
@@ -208,6 +194,11 @@ MATERIALS = {
"native_lane_separator_yellow": {"kind": "solid", "name": "Native Lane Separator Yellow", "native_lane_separator_yellow": {"kind": "solid", "name": "Native Lane Separator Yellow",
"color": (0.94, 0.58, 0.06), "roughness": 0.52, "color": (0.94, 0.58, 0.06), "roughness": 0.52,
"cesium": {"base_color": (0.94, 0.58, 0.06)}}, "cesium": {"base_color": (0.94, 0.58, 0.06)}},
# Safety-island planting follows the neutral green-grey map fill and is
# intentionally opaque so it does not blend with the asphalt below.
"native_island_green": {"kind": "solid", "name": "Native Island Green",
"color": (0.0382, 0.4793, 0.1441), "roughness": 0.92,
"cesium": {"base_color": (0.0382, 0.4793, 0.1441)}},
} }
+95
View File
@@ -0,0 +1,95 @@
"""Pure-Python validation for native-road package manifests."""
import json
import os
CONTRACT = "native-road-package/v1.1"
RENDERABLE_ROLES = ("surface", "marking")
VALID_ROLES = RENDERABLE_ROLES + ("semantic",)
def _error(message):
raise RuntimeError("Invalid native road manifest: " + message)
def _source_name(value):
return (isinstance(value, str) and value
and value == os.path.basename(value)
and value not in (".", ".."))
def _validate_split(source, split):
if not isinstance(split, dict):
_error("layer '%s' splitBy must be an object" % source)
prop = split.get("prop")
cases = split.get("cases")
if not isinstance(prop, str) or not prop or not isinstance(cases, list) or not cases:
_error("layer '%s' has an invalid splitBy" % source)
matches = set()
defaults = 0
for case in cases:
if not isinstance(case, dict) or not isinstance(case.get("material"), str):
_error("layer '%s' has an invalid splitBy case" % source)
is_default = case.get("default") is True
has_match = "match" in case
if is_default == has_match:
_error("layer '%s' splitBy cases need exactly one of match/default" % source)
if is_default:
defaults += 1
else:
match = case["match"]
if match in matches:
_error("layer '%s' has a duplicate splitBy match" % source)
matches.add(match)
if defaults != 1:
_error("layer '%s' splitBy needs exactly one default case" % source)
def load(native_road_dir):
"""Load a v1.1 manifest and ensure it declares exactly its GeoJSON files."""
manifest_path = os.path.join(native_road_dir, "manifest.json")
if not os.path.isfile(manifest_path):
raise RuntimeError("Native road manifest is missing: " + manifest_path)
try:
with open(manifest_path, "r", encoding="utf-8") as handle:
manifest = json.load(handle)
except (OSError, ValueError) as error:
raise RuntimeError("Could not read native road manifest: " + str(error)) from error
if not isinstance(manifest, dict) or manifest.get("contract") != CONTRACT:
_error("unsupported contract")
layers = manifest.get("layers")
if not isinstance(layers, list) or not layers:
_error("layers must be a non-empty array")
declared = set()
for spec in layers:
if not isinstance(spec, dict):
_error("layer entries must be objects")
source = spec.get("source")
role = spec.get("role")
if not _source_name(source) or source in declared or role not in VALID_ROLES:
_error("layer source or role is invalid")
declared.add(source)
if role in RENDERABLE_ROLES:
if not isinstance(spec.get("materialLayer"), str) or not spec["materialLayer"]:
_error("renderable layer '%s' needs materialLayer" % source)
if "splitBy" in spec:
_validate_split(source, spec["splitBy"])
elif "materialLayer" in spec or "splitBy" in spec:
_error("semantic layer '%s' must not declare rendering" % source)
layers_dir = os.path.join(native_road_dir, "layers")
if not os.path.isdir(layers_dir):
raise RuntimeError("Native road layers directory is missing: " + layers_dir)
published = {
name[:-8] for name in os.listdir(layers_dir)
if name.endswith(".geojson") and os.path.isfile(os.path.join(layers_dir, name))
}
if published != declared:
missing = sorted(declared - published)
extra = sorted(published - declared)
_error("declared GeoJSON mismatch (missing=%s, extra=%s)" % (missing, extra))
return manifest
+55
View File
@@ -0,0 +1,55 @@
"""Manifest-driven native road layer adapter."""
import os
from osmassets import catalog
from osmassets import native_road_manifest
from osmassets import roads
def _material(material_layers, name):
if name not in material_layers:
raise RuntimeError("Native road manifest references unknown materialLayer: " + name)
return material_layers[name]
def _split_filter(split, case):
if not split:
return None
prop = split["prop"]
if "match" in case:
return lambda props: props.get(prop) == case["match"]
matches = {item["match"] for item in split["cases"] if "match" in item}
return lambda props: props.get(prop) not in matches
def assemble(native_road_dir, projector, collection, material_layers):
manifest = native_road_manifest.load(native_road_dir)
z_by_material_layer = {layer["id"]: layer["z"] for layer in catalog.ROAD_LAYERS}
counts = {}
for spec in manifest["layers"]:
source = spec["source"]
role = spec["role"]
source_path = os.path.join(native_road_dir, "layers", source + ".geojson")
if role == "semantic":
continue
material_name = spec["materialLayer"]
if material_name not in z_by_material_layer:
raise RuntimeError("Native road manifest references unknown materialLayer: " + material_name)
_material(material_layers, material_name)
count = 0
split = spec.get("splitBy")
cases = split.get("cases", []) if split else [{"default": True, "material": material_name}]
for case in cases:
case_material_name = case.get("material", material_name)
case_material = _material(material_layers, case_material_name)
suffix = "_" + str(case["match"]) if "match" in case else ""
# Split cases may be inset overlays (for example the green
# planting inside a grey safety-island base). Keep the geometry
# unchanged, but lift matched overlays slightly to avoid z-fighting.
case_z = z_by_material_layer[material_name] + (0.001 if "match" in case else 0.0)
count += roads.assemble_geojson_layer(
source_path, source + suffix, projector, collection, case_material,
case_z, _split_filter(split, case))
counts[source] = count
return counts
+77 -19
View File
@@ -10,6 +10,7 @@ The expected values are derived from the geometry, not captured from the
implementation — a test that just records current output would ratify a bug. implementation — a test that just records current output would ratify a bug.
""" """
import json
import math import math
import os import os
import sys import sys
@@ -30,7 +31,8 @@ from osmassets.geom import (
sample_tree_row, sample_tree_row,
signed_polygon_area, signed_polygon_area,
) )
from osmassets.catalog import NATIVE_ROAD_LAYERS, ROAD_LAYERS from osmassets.catalog import MATERIALS, ROAD_LAYERS
from osmassets.native_road_manifest import CONTRACT, load as load_native_road_manifest
from osmassets.osm import Projector, parse_height, parse_osm, tags from osmassets.osm import Projector, parse_height, parse_osm, tags
@@ -38,6 +40,13 @@ SQUARE = [(0.0, 0.0), (10.0, 0.0), (10.0, 10.0), (0.0, 10.0)]
class RoadLayerCatalogTest(unittest.TestCase): class RoadLayerCatalogTest(unittest.TestCase):
def test_native_island_material_is_registered(self):
material = MATERIALS["native_island_green"]
self.assertEqual(material["kind"], "solid")
self.assertEqual(material["color"], (0.0382, 0.4793, 0.1441))
self.assertGreater(material["color"][1], material["color"][0])
self.assertGreater(material["color"][1], material["color"][2])
def test_intersection_and_road_asphalt_share_the_same_colour(self): def test_intersection_and_road_asphalt_share_the_same_colour(self):
layers = {layer["id"]: layer for layer in ROAD_LAYERS} layers = {layer["id"]: layer for layer in ROAD_LAYERS}
self.assertEqual(layers["road_surface"]["color"], self.assertEqual(layers["road_surface"]["color"],
@@ -46,24 +55,6 @@ class RoadLayerCatalogTest(unittest.TestCase):
self.assertNotEqual(layers["road_surface"]["z"], self.assertNotEqual(layers["road_surface"]["z"],
layers["intersection_surface"]["z"]) layers["intersection_surface"]["z"])
def test_native_provider_maps_to_existing_material_layers(self):
layers = {layer["id"] for layer in ROAD_LAYERS}
self.assertEqual(
[(entry["source"], entry["material_layer"])
for entry in NATIVE_ROAD_LAYERS],
[("road_surface", "road_surface"),
("edge_lines", "lane_separators"),
("intersection_surface", "intersection_surface"),
("sidewalk_surface", "sidewalks"),
("lane_separators", "lane_separators"),
("center_lines", "center_lines"),
("direction_arrows", "lane_arrows_webscale"),
("turn_arrows", "lane_arrows_webscale"),
("crosswalks", "crosswalks"),
("vehicle_stop_lines", "vehicle_stop_lines")])
self.assertTrue(all(entry["material_layer"] in layers
for entry in NATIVE_ROAD_LAYERS))
def test_cesium_export_keeps_signal_assets_optional(self): def test_cesium_export_keeps_signal_assets_optional(self):
exporter = os.path.join(os.path.dirname(os.path.abspath(__file__)), exporter = os.path.join(os.path.dirname(os.path.abspath(__file__)),
"..", "export_cesium.py") "..", "export_cesium.py")
@@ -72,6 +63,73 @@ class RoadLayerCatalogTest(unittest.TestCase):
self.assertIn('if not args.get(key):\n continue', source) self.assertIn('if not args.get(key):\n continue', source)
class NativeRoadManifestTest(unittest.TestCase):
def setUp(self):
self.root = tempfile.TemporaryDirectory()
self.layers_dir = os.path.join(self.root.name, "layers")
os.mkdir(self.layers_dir)
def tearDown(self):
self.root.cleanup()
def write_manifest(self, layers):
with open(os.path.join(self.root.name, "manifest.json"), "w", encoding="utf-8") as handle:
json.dump({"contract": CONTRACT, "areaId": "test", "layers": layers}, handle)
for layer in layers:
with open(os.path.join(self.layers_dir, layer["source"] + ".geojson"), "w",
encoding="utf-8") as handle:
json.dump({"type": "FeatureCollection", "features": []}, handle)
def test_accepts_semantic_and_split_layers(self):
layers = [
{"source": "road_surface", "role": "surface", "materialLayer": "road_surface"},
{"source": "center_lines", "role": "marking", "materialLayer": "center_lines",
"splitBy": {"prop": "color", "cases": [
{"match": "white", "material": "native_center_line_white"},
{"default": True, "material": "center_lines"},
]}},
{"source": "connectors", "role": "semantic"},
]
self.write_manifest(layers)
self.assertEqual(load_native_road_manifest(self.root.name)["layers"], layers)
def test_rejects_undeclared_or_missing_geojson(self):
layers = [{"source": "road_surface", "role": "surface",
"materialLayer": "road_surface"}]
self.write_manifest(layers)
with open(os.path.join(self.layers_dir, "extra.geojson"), "w", encoding="utf-8") as handle:
handle.write("{}")
with self.assertRaisesRegex(RuntimeError, "mismatch"):
load_native_road_manifest(self.root.name)
os.unlink(os.path.join(self.layers_dir, "extra.geojson"))
os.unlink(os.path.join(self.layers_dir, "road_surface.geojson"))
with self.assertRaisesRegex(RuntimeError, "mismatch"):
load_native_road_manifest(self.root.name)
def test_rejects_invalid_semantic_and_split_definitions(self):
self.write_manifest([{"source": "connectors", "role": "semantic",
"materialLayer": "road_surface"}])
with self.assertRaisesRegex(RuntimeError, "semantic"):
load_native_road_manifest(self.root.name)
def test_split_overlay_has_a_separate_z_layer(self):
native_roads = os.path.join(os.path.dirname(os.path.abspath(__file__)),
"..", "osmassets", "native_roads.py")
with open(native_roads, encoding="utf-8") as handle:
source = handle.read()
self.assertIn('0.001 if "match" in case else 0.0', source)
self.write_manifest([{"source": "center_lines", "role": "marking",
"materialLayer": "center_lines", "splitBy": {
"prop": "color", "cases": [
{"match": "white", "material": "native_center_line_white"},
{"default": True, "material": "center_lines"},
{"default": True, "material": "center_lines"},
]}}])
with self.assertRaisesRegex(RuntimeError, "exactly one default"):
load_native_road_manifest(self.root.name)
class GeometryRingsTest(unittest.TestCase): class GeometryRingsTest(unittest.TestCase):
def test_polygon_keeps_only_the_exterior_ring(self): def test_polygon_keeps_only_the_exterior_ring(self):
geometry = {"type": "Polygon", "coordinates": [["outer"], ["hole"]]} geometry = {"type": "Polygon", "coordinates": [["outer"], ["hole"]]}
+177
View File
@@ -0,0 +1,177 @@
"""Compare exporter preparation against a supplied original in real Blender.
blender --background --factory-startup --python this_file.py -- \
--baseline /absolute/path/to/original_export_cesium.py
The fixture combines asymmetric quads, n-gons, authored UVs, shared meshes,
custom normals, shape keys and Bevel. A separate Boolean scenario exercises
the dependency-bearing fallback. Expected triangle totals follow n - 2;
attribute/ordering comparisons use the original exporter as an independent
reference, including an unchanged-code control run.
"""
import argparse
import importlib.util
import math
from pathlib import Path
import sys
import bpy
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
def load_exporter(name, path):
spec = importlib.util.spec_from_file_location(name, path)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
def fixture(dependent):
bpy.ops.wm.read_factory_settings(use_empty=True)
material = bpy.data.materials.new("Fixture material")
objects = []
def mesh_object(name, vertices, faces):
mesh = bpy.data.meshes.new(name + " mesh")
mesh.from_pydata(vertices, [], faces)
mesh.materials.append(material)
mesh["fixture_property"] = "preserved"
obj = bpy.data.objects.new(name, mesh)
bpy.context.scene.collection.objects.link(obj)
objects.append(obj)
return obj
quad = [(0, 0, 0), (3, 0, 0), (2, 1, 0), (0, 2, 0)]
mesh_object("quad", quad, [(0, 1, 2, 3)])
mesh_object("ngon", quad + [(-1, 1, 0)], [(0, 1, 2, 3, 4)])
authored = mesh_object("authored", quad, [(0, 1, 2, 3)])
uv = authored.data.uv_layers.new(name="Authored UV")
for loop, value in zip(uv.data, [(0, 0), (.9, .1), (.6, .8), (.1, 1)]):
loop.uv = value
shared = mesh_object("shared", quad, [(0, 1, 2, 3)])
instance = bpy.data.objects.new("shared instance", shared.data)
bpy.context.scene.collection.objects.link(instance)
objects.append(instance)
mesh_object("triangle", quad[:3], [(0, 1, 2)])
custom = mesh_object("custom normals", quad, [(0, 1, 2, 3)])
custom.data.normals_split_custom_set([(0, .2, 1)] * 4)
keyed = mesh_object("shape keys", quad, [(0, 1, 2, 3)])
keyed.shape_key_add(name="Basis")
keyed.shape_key_add(name="Raised").data[0].co.z = .25
bevel = mesh_object("bevel", quad, [(0, 1, 2, 3)])
modifier = bevel.modifiers.new("Fixture bevel", "BEVEL")
modifier.width = .16
modifier.segments = 2
retained = mesh_object("fake user", quad, [(0, 1, 2, 3)])
retained.data.use_fake_user = True
if dependent:
boolean = objects[0].modifiers.new("Dependent Boolean", "BOOLEAN")
boolean.object = authored
return objects
def digest(objects):
return [{
"name": obj.name,
"mesh": obj.data.name,
"users": obj.data.users,
"properties": dict(obj.data.items()),
"vertices": [tuple(v.co) for v in obj.data.vertices],
"polygons": [tuple(p.vertices) for p in obj.data.polygons],
"smooth": [p.use_smooth for p in obj.data.polygons],
"normals": [tuple(n.vector) for n in obj.data.corner_normals],
"uv": {uv.name: [tuple(v.uv) for v in uv.data]
for uv in obj.data.uv_layers},
"materials": [m.name if m else None for m in obj.data.materials],
"modifiers": [(m.name, m.type) for m in obj.modifiers],
"shape_keys": ([key.name for key in obj.data.shape_keys.key_blocks]
if obj.data.shape_keys else []),
} for obj in objects]
def prepare(module, dependent, optimized):
objects = fixture(dependent)
if optimized:
module.prepare_independent_meshes(objects)
seen = set()
for obj in objects:
module.apply_mesh_modifiers(obj)
if obj.data.name not in seen:
seen.add(obj.data.name)
module.triangulate_mesh(obj)
module.unwrap_mesh(obj)
assert objects[3].data is objects[4].data, "shared mesh was split"
if not dependent:
assert len(objects[0].data.polygons) == 2, "quad must give n - 2 triangles"
assert len(objects[1].data.polygons) == 3, "pentagon must give n - 2 triangles"
return digest(objects)
def compare(expected, actual, path="root"):
if isinstance(expected, dict):
assert expected.keys() == actual.keys(), path
for key in expected:
compare(expected[key], actual[key], path + "." + str(key))
elif isinstance(expected, (list, tuple)):
assert len(expected) == len(actual), (path, len(expected), len(actual))
for index, (left, right) in enumerate(zip(expected, actual)):
compare(left, right, path + "[%d]" % index)
elif isinstance(expected, float):
assert math.isclose(expected, actual, rel_tol=0, abs_tol=1e-6), (
path, expected, actual)
else:
assert expected == actual, (path, expected, actual)
def check_work_scene_cleanup(module):
objects = fixture(False)
triangle = objects[5]
original_scene = bpy.context.window.scene
original_layer = bpy.context.window.view_layer
scene_names = set(bpy.data.scenes.keys())
collections = tuple(triangle.users_collection)
unwrap = module.unwrap_mesh
def fail_unwrap(obj):
assert bpy.context.scene != original_scene
assert obj == triangle
raise RuntimeError("fixture UV failure")
module.unwrap_mesh = fail_unwrap
# Remove the Bevel so this specifically exercises the scratch-scene path.
objects[8].modifiers.clear()
try:
try:
module.unwrap_meshes_in_work_scene([triangle])
except RuntimeError as error:
assert str(error) == "fixture UV failure"
else:
raise AssertionError("fixture failure was swallowed")
finally:
module.unwrap_mesh = unwrap
assert bpy.context.window.scene == original_scene
assert bpy.context.window.view_layer == original_layer
assert set(bpy.data.scenes.keys()) == scene_names
assert tuple(triangle.users_collection) == collections
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--baseline", required=True)
args = parser.parse_args(sys.argv[sys.argv.index("--") + 1:])
original = load_exporter("original_exporter", args.baseline)
optimized = load_exporter("optimized_exporter", ROOT / "export_cesium.py")
for dependent in (False, True):
reference = prepare(original, dependent, False)
compare(reference, prepare(original, dependent, False), "control")
compare(reference, prepare(optimized, dependent, True), "optimized")
check_work_scene_cleanup(optimized)
print("EXPORT_PREPARATION_CHECK_OK: control, independent and dependent fixtures")
if __name__ == "__main__":
main()
+1 -25
View File
@@ -1,6 +1,7 @@
{ {
"id": "fengshu-er-road", "id": "fengshu-er-road",
"input": "/Users/que01/osm2streets-qgis-workflow/inputs/osm/枫树二路.osm", "input": "/Users/que01/osm2streets-qgis-workflow/inputs/osm/枫树二路.osm",
"nativeRoadPackage": "../../inputs/native-road-packages/fengshu-er-road.zip",
"outputRoot": "/Users/que01/osm2streets-qgis-workflow/outputs", "outputRoot": "/Users/que01/osm2streets-qgis-workflow/outputs",
"qgisApp": "/Applications/QGIS.app", "qgisApp": "/Applications/QGIS.app",
"blenderApp": "/Applications/Blender.app", "blenderApp": "/Applications/Blender.app",
@@ -24,31 +25,6 @@
"turnLaneArrows": { "turnLaneArrows": {
"enabled": false "enabled": false
}, },
"nativeRoad": {
"edgeLines": false,
"junctionTemplates": {
"enabled": true,
"references": [],
"clusters": [
{
"id": "zhushanhu-fengshu-complex",
"template": "complex-junction-v1",
"referenceFile": "../../inputs/osm/珠山湖大道(枫树二路)口.geojson",
"approachWidthMultiplier": 1.45,
"approachLengthMeters": 32,
"coreRadiusMeters": 28,
"cornerRadiusMeters": 25,
"outerRadiusExtraMeters": 24,
"nodeIds": [
"8005332807",
"8024512135",
"8024512145",
"8024512147"
]
}
]
}
},
"osm2streets": { "osm2streets": {
"debug_each_step": false, "debug_each_step": false,
"dual_carriageway_experiment": false, "dual_carriageway_experiment": false,
-32
View File
@@ -1,32 +0,0 @@
{
"id": "hanyang-block",
"input": "/Users/que01/Desktop/汉阳区区块.osm",
"outputRoot": "/Users/que01/osm2streets-qgis-workflow/outputs",
"qgisApp": "/Applications/QGIS.app",
"blenderApp": "/Applications/Blender.app",
"stages": {
"intermediates": false,
"blender": true,
"cesium": true
},
"qgis": {
"arrowScale": 0.8,
"clipPad": 0.002,
"canvasPad": 0.001,
"previewPad": 0.0007,
"canvasExtent": null,
"previewExtent": null,
"layerPrefix": "osm2streets"
},
"osm2streets": {
"debug_each_step": false,
"dual_carriageway_experiment": false,
"sidepath_zipping_experiment": false,
"inferred_sidewalks": true,
"osm2lanes": true
},
"blender": {
"treeStyle": "natural",
"officeOverrides": ""
}
}
@@ -1,6 +1,7 @@
{ {
"id": "nantaizi-lake-innovation-valley", "id": "nantaizi-lake-innovation-valley",
"input": "/Users/que01/Desktop/南台子湖创新谷OSM.osm", "input": "/Users/que01/Desktop/南台子湖创新谷OSM.osm",
"nativeRoadPackage": "../../inputs/native-road-packages/nantaizi-lake-innovation-valley.zip",
"outputRoot": "/Users/que01/osm2streets-qgis-workflow/outputs", "outputRoot": "/Users/que01/osm2streets-qgis-workflow/outputs",
"qgisApp": "/Applications/QGIS.app", "qgisApp": "/Applications/QGIS.app",
"blenderApp": "/Applications/Blender.app", "blenderApp": "/Applications/Blender.app",
@@ -24,9 +25,6 @@
"turnLaneArrows": { "turnLaneArrows": {
"enabled": true "enabled": true
}, },
"nativeRoad": {
"edgeLines": false
},
"osm2streets": { "osm2streets": {
"debug_each_step": false, "debug_each_step": false,
"dual_carriageway_experiment": false, "dual_carriageway_experiment": false,
+16
View File
@@ -0,0 +1,16 @@
{
"id": "osm-g5Yjf1",
"input": "/Users/que01/Desktop/南台子湖创新谷OSM.osm",
"nativeRoadPackage": "/tmp/osm-g5Yjf1.native-road.zip",
"outputRoot": "/Users/que01/osm2streets-qgis-workflow/outputs",
"stages": {
"intermediates": false,
"blender": true,
"cesium": true
},
"blender": {
"treeStyle": "natural",
"officeOverrides": "",
"roadProvider": "native"
}
}
+1 -8
View File
@@ -1,6 +1,7 @@
{ {
"id": "my-area", "id": "my-area",
"input": "/absolute/path/to/input.osm", "input": "/absolute/path/to/input.osm",
"nativeRoadPackage": "/absolute/path/to/exported-native-road-package.zip",
"outputRoot": "/absolute/path/to/outputs", "outputRoot": "/absolute/path/to/outputs",
"qgisApp": "/Applications/QGIS.app", "qgisApp": "/Applications/QGIS.app",
"blenderApp": "/Applications/Blender.app", "blenderApp": "/Applications/Blender.app",
@@ -24,14 +25,6 @@
"turnLaneArrows": { "turnLaneArrows": {
"enabled": false "enabled": false
}, },
"nativeRoad": {
"edgeLines": false,
"junctionTemplates": {
"enabled": false,
"references": [],
"clusters": []
}
},
"osm2streets": { "osm2streets": {
"debug_each_step": false, "debug_each_step": false,
"dual_carriageway_experiment": false, "dual_carriageway_experiment": false,
+10 -2
View File
@@ -1,6 +1,6 @@
# Native Road Package v1 # Native Road Package v1.1
`native-road-package/v1` defines the boundary between the host area pipeline `native-road-package/v1.1` defines the boundary between the host area pipeline
and the native road compiler. The compiler accepts only the input below; it and the native road compiler. The compiler accepts only the input below; it
does not read `config/areas/*.json` or derive host paths. does not read `config/areas/*.json` or derive host paths.
@@ -60,6 +60,14 @@ shape and owns all path derivation.
11. `lane_centerlines.geojson` (semantic, not rendered) 11. `lane_centerlines.geojson` (semantic, not rendered)
12. `connectors.geojson` (semantic, not rendered) 12. `connectors.geojson` (semantic, not rendered)
`manifest.json` is required. It declares the same twelve sources in published
order using `{ source, role, materialLayer?, splitBy? }`. `surface` and
`marking` layers declare a host material slot; `semantic` layers are published
but Blender must not read or render them. A `splitBy` entry has one exact-match
case or more plus exactly one default case, so the legacy white center-line and
yellow lane-separator material routing remains declarative. Consumers reject a
missing/invalid manifest, a source/file mismatch, and unknown material slots.
The editable signal source at `trafficSignalsFile` is a sibling of `outDir`. The editable signal source at `trafficSignalsFile` is a sibling of `outDir`.
It is included in the parity baseline because regeneration must be stable. It is included in the parity baseline because regeneration must be stable.
Binary file not shown.
+12
View File
@@ -9,6 +9,8 @@
"version": "0.3.0", "version": "0.3.0",
"dependencies": { "dependencies": {
"@inquirer/prompts": "^8.5.2", "@inquirer/prompts": "^8.5.2",
"@osm-asset/road-compiler": "git+https://git.app.que01.top/que01/road-compiler.git#v0.2.2",
"fflate": "0.8.3",
"ol": "^10.10.0", "ol": "^10.10.0",
"osm2streets-js-node": "0.1.4" "osm2streets-js-node": "0.1.4"
} }
@@ -341,6 +343,16 @@
} }
} }
}, },
"node_modules/@osm-asset/road-compiler": {
"version": "0.2.2",
"resolved": "git+https://git.app.que01.top/que01/road-compiler.git#3b4befb02550c524ae83831e77959423e3bb40bf",
"dependencies": {
"ol": "10.10.0"
},
"bin": {
"road-compiler": "bin/road-compiler.js"
}
},
"node_modules/@petamoriken/float16": { "node_modules/@petamoriken/float16": {
"version": "3.9.3", "version": "3.9.3",
"resolved": "http://172.16.1.86:4873/@petamoriken/float16/-/float16-3.9.3.tgz", "resolved": "http://172.16.1.86:4873/@petamoriken/float16/-/float16-3.9.3.tgz",
+5 -7
View File
@@ -3,24 +3,19 @@
"version": "0.3.0", "version": "0.3.0",
"private": true, "private": true,
"type": "commonjs", "type": "commonjs",
"workspaces": [
"packages/road-compiler"
],
"scripts": { "scripts": {
"build": "node scripts/interactive-build.js", "build": "node scripts/interactive-build.js",
"console": "node scripts/build-console.js",
"build:area": "node scripts/build-area.js", "build:area": "node scripts/build-area.js",
"build:qgis": "node scripts/build-osm2streets-qgis.js", "build:qgis": "node scripts/build-osm2streets-qgis.js",
"check:area": "node scripts/check-area.js", "check:area": "node scripts/check-area.js",
"compress:glb": "node scripts/compress-glb.js", "compress:glb": "node scripts/compress-glb.js",
"diagnose:area": "node scripts/diagnose-area.js", "diagnose:area": "node scripts/diagnose-area.js",
"preflight:area": "node scripts/preflight-area.js", "preflight:area": "node scripts/preflight-area.js",
"road:compile": "node scripts/compile-native-roads.js",
"reference:junction": "node scripts/inspect-junction-reference.js", "reference:junction": "node scripts/inspect-junction-reference.js",
"road:check": "node scripts/check-native-roads.js",
"road:workbench": "node scripts/road-workbench.js",
"serve:v2x-preview": "node scripts/v2x-preview-server.js", "serve:v2x-preview": "node scripts/v2x-preview-server.js",
"test:road-workbench": "node scripts/test-road-workbench.js",
"test:native-road": "node scripts/test-native-road.js", "test:native-road": "node scripts/test-native-road.js",
"test:native-road-package": "node scripts/test-native-road-package.js",
"test:road-parity": "node scripts/test-road-parity.js", "test:road-parity": "node scripts/test-road-parity.js",
"test:gaode-junction-reference": "node scripts/test-gaode-junction-reference.js", "test:gaode-junction-reference": "node scripts/test-gaode-junction-reference.js",
"test:preflight": "node scripts/test-area-preflight.js", "test:preflight": "node scripts/test-area-preflight.js",
@@ -33,12 +28,15 @@
"test:turn-lane-arrows": "node scripts/test-turn-lane-arrows.js", "test:turn-lane-arrows": "node scripts/test-turn-lane-arrows.js",
"test:traffic-signals": "node scripts/test-traffic-signals.js", "test:traffic-signals": "node scripts/test-traffic-signals.js",
"test:native-preview-traffic": "node scripts/test-native-preview-traffic.js", "test:native-preview-traffic": "node scripts/test-native-preview-traffic.js",
"test:participant-runtime": "node scripts/test-participant-runtime.js",
"test:v2x-preview-server": "node scripts/test-v2x-preview-server.js", "test:v2x-preview-server": "node scripts/test-v2x-preview-server.js",
"test:v2x-cesium-preview": "node scripts/test-v2x-cesium-overlay.js", "test:v2x-cesium-preview": "node scripts/test-v2x-cesium-overlay.js",
"render:turn-lane-arrow-samples": "node scripts/render-turn-lane-arrow-samples.js" "render:turn-lane-arrow-samples": "node scripts/render-turn-lane-arrow-samples.js"
}, },
"dependencies": { "dependencies": {
"@inquirer/prompts": "^8.5.2", "@inquirer/prompts": "^8.5.2",
"@osm-asset/road-compiler": "git+https://git.app.que01.top/que01/road-compiler.git#v0.2.2",
"fflate": "0.8.3",
"ol": "^10.10.0", "ol": "^10.10.0",
"osm2streets-js-node": "0.1.4" "osm2streets-js-node": "0.1.4"
} }
-10
View File
@@ -1,10 +0,0 @@
{
"name": "@osm-asset/road-compiler",
"version": "0.1.0",
"private": true,
"type": "commonjs",
"main": "src/index.js",
"scripts": {
"test": "node test/index.js"
}
}
-27
View File
@@ -1,27 +0,0 @@
"use strict";
const fs = require("fs");
const path = require("path");
function checkOutput({ areaId, outDir }) {
if (typeof areaId !== "string" || !areaId) throw new Error("RoadCompilerCheckInput.areaId must be a non-empty string");
if (typeof outDir !== "string" || !outDir) throw new Error("RoadCompilerCheckInput.outDir must be a non-empty string");
const compiledPath = path.join(outDir, "compiled.json");
if (!fs.existsSync(compiledPath)) throw new Error(`Native road output is missing: ${compiledPath}`);
const compiled = readJson(compiledPath);
const connectors = readJson(path.join(outDir, "layers", "connectors.geojson"));
const published = new Set(connectors.features.map((feature) => feature.properties.movement_id));
const failures = [];
for (const movement of compiled.movements || []) {
if (movement.geometryPublished && !published.has(movement.id)) failures.push(`Published movement has no connector: ${movement.id}`);
if (!movement.geometryPublished && published.has(movement.id)) failures.push(`Non-published movement has a connector: ${movement.id}`);
if (!movement.geometryStatus) failures.push(`Movement has no geometry status: ${movement.id}`);
}
const errors = (compiled.diagnostics || []).filter((item) => item.severity === "error");
const warnings = (compiled.diagnostics || []).filter((item) => item.severity === "warning");
return { schema: "native-road-check/v1", areaId, ok: failures.length === 0 && errors.length === 0, movementCount: (compiled.movements || []).length, connectorCount: connectors.features.length, errors: errors.map((item) => ({ id: item.id, rule: item.rule, message: item.message })), warningCount: warnings.length, failures };
}
function readJson(file) { return JSON.parse(fs.readFileSync(file, "utf8")); }
module.exports = { checkOutput };
@@ -1,141 +0,0 @@
#!/usr/bin/env node
"use strict";
const fs = require("fs");
const path = require("path");
const { compileRoadModel, compileGeometry, loadOverrides, validateOverrides, writeJsonAtomic } = require("./native-road");
const { loadOrGenerate, runtime } = require("../native-traffic-signals");
function compileInput(input) {
validateInput(input);
const area = {
id: input.areaId,
input: input.osmFile,
nativeRoad: input.options,
outputs: {
nativeRoadOverrides: input.overridesFile,
nativeTrafficSignals: input.trafficSignalsFile,
nativeRoadDir: input.outDir,
pipelineDir: input.stagingDir,
geojsonDir: input.comparisonDir || null,
},
};
const overrides = loadOverrides(area.outputs.nativeRoadOverrides);
const model = compileRoadModel(fs.readFileSync(area.input, "utf8"), overrides);
// Editing the source OSM retires the ids some overrides point at. Those
// entries can no longer match anything, so drop them with a diagnostic rather
// than aborting the whole compile — otherwise every OSM edit blocks the
// pipeline until the file is hand-pruned, one error message at a time.
const validated = validateOverrides(overrides, model, { skipStaleTargets: true });
for (const item of validated.stale) console.warn(`[warning] 忽略失效的 override(目标已不存在):${item.id} -> ${item.target}`);
fs.mkdirSync(area.outputs.pipelineDir, { recursive: true });
const compiled = compileGeometry(model, overrides, { edgeLines: area.nativeRoad.edgeLines, junctionTemplates: area.nativeRoad.junctionTemplates });
compiled.diagnostics.push(...validated.stale.map((item) => ({
id: `diagnostic:stale-override:${item.id}`,
severity: "warning",
subjectId: item.id,
sourceIds: [],
rule: "stale-override-target",
message: `该设置指向的 ${item.kind} 目标 ${item.target} 已不存在(OSM 改动后 id 失效),本次编译已忽略。可在工作台重新设置,或从 native-road-overrides.json 中删除。`,
geometry: null,
})));
const signalDocument = loadOrGenerate(area.outputs.nativeTrafficSignals, fs.readFileSync(area.input, "utf8"), compiled.vehicleStopLines, compiled.intersectionSurface);
const signalRuntime = runtime(signalDocument);
// Persist validation normalization, including one-time legacy heading migration.
writeJsonAtomic(area.outputs.nativeTrafficSignals, signalDocument);
const staging = fs.mkdtempSync(path.join(area.outputs.pipelineDir, "native-road-"));
try {
const result = {
schema: "native-road-compiled/v1",
areaId: area.id,
source: { osm: area.input, overrides: area.outputs.nativeRoadOverrides, trafficSignals: area.outputs.nativeTrafficSignals },
model: { roads: model.roads, endpoints: model.endpoints, connections: model.connections },
movements: compiled.movements,
trafficSignals: { assemblies: "traffic-signal-assemblies.json", runtime: "traffic-signals.json", count: signalRuntime.signals.length },
diagnostics: compiled.diagnostics,
layers: { roadSurface: "layers/road_surface.geojson", edgeLines: "layers/edge_lines.geojson", sidewalkSurface: "layers/sidewalk_surface.geojson", intersectionSurface: "layers/intersection_surface.geojson", laneCenterlines: "layers/lane_centerlines.geojson", laneSeparators: "layers/lane_separators.geojson", centerLines: "layers/center_lines.geojson", directionArrows: "layers/direction_arrows.geojson", turnArrows: "layers/turn_arrows.geojson", crosswalks: "layers/crosswalks.geojson", vehicleStopLines: "layers/vehicle_stop_lines.geojson", connectors: "layers/connectors.geojson" },
};
const comparison = compareOsm2Streets(area, result.model, compiled);
writeJsonAtomic(path.join(staging, "compiled.json"), result);
writeJsonAtomic(path.join(staging, "diagnostics.json"), { schema: "native-road-diagnostics/v1", diagnostics: compiled.diagnostics });
writeJsonAtomic(path.join(staging, "comparison.json"), comparison);
writeJsonAtomic(path.join(staging, "traffic-signal-assemblies.json"), signalDocument.assemblies);
writeJsonAtomic(path.join(staging, "traffic-signals.json"), signalRuntime);
writeJsonAtomic(path.join(staging, "layers", "road_surface.geojson"), compiled.roadSurface);
writeJsonAtomic(path.join(staging, "layers", "edge_lines.geojson"), compiled.edgeLines);
writeJsonAtomic(path.join(staging, "layers", "sidewalk_surface.geojson"), compiled.sidewalkSurface);
writeJsonAtomic(path.join(staging, "layers", "intersection_surface.geojson"), compiled.intersectionSurface);
writeJsonAtomic(path.join(staging, "layers", "lane_centerlines.geojson"), compiled.laneCenterlines);
writeJsonAtomic(path.join(staging, "layers", "lane_separators.geojson"), compiled.laneSeparators);
writeJsonAtomic(path.join(staging, "layers", "center_lines.geojson"), compiled.centerLines);
writeJsonAtomic(path.join(staging, "layers", "direction_arrows.geojson"), compiled.directionArrows);
writeJsonAtomic(path.join(staging, "layers", "turn_arrows.geojson"), compiled.turnArrows);
writeJsonAtomic(path.join(staging, "layers", "crosswalks.geojson"), compiled.crosswalks);
writeJsonAtomic(path.join(staging, "layers", "vehicle_stop_lines.geojson"), compiled.vehicleStopLines);
writeJsonAtomic(path.join(staging, "layers", "connectors.geojson"), compiled.connectors);
fs.rmSync(area.outputs.nativeRoadDir, { recursive: true, force: true });
fs.renameSync(staging, area.outputs.nativeRoadDir);
return { area, result, comparison };
} catch (error) {
fs.rmSync(staging, { recursive: true, force: true });
throw error;
}
}
function compareOsm2Streets(area, model, compiled) {
const source = area.outputs.geojsonDir ? path.join(area.outputs.geojsonDir, "road_surface.geojson") : null;
let featureCount = null;
if (source && fs.existsSync(source)) {
const collection = JSON.parse(fs.readFileSync(source, "utf8"));
featureCount = Array.isArray(collection.features) ? collection.features.length : null;
}
const diagnosticsBySeverity = {};
const diagnosticsByRule = {};
for (const item of compiled.diagnostics) {
diagnosticsBySeverity[item.severity] = (diagnosticsBySeverity[item.severity] || 0) + 1;
diagnosticsByRule[item.rule] = (diagnosticsByRule[item.rule] || 0) + 1;
}
const dangling = compiled.diagnostics.filter((item) => item.rule === "unconnected-interior-road-end");
const junctions = compiled.intersectionSurface.features;
const fallbackJunctions = junctions.filter((feature) => feature.properties.boundary_mode === "connector-convex-fallback");
return {
schema: "native-road-comparison/v2",
nativeRoadCount: model.roads.length,
nativeRoadSurfaceFeatures: compiled.roadSurface.features.length,
nativeSidewalkSurfaceFeatures: compiled.sidewalkSurface.features.length,
nativeJunctionSurfaceFeatures: compiled.intersectionSurface.features.length,
nativeApproachEnvelopeJunctions: junctions.length - fallbackJunctions.length,
nativeFallbackJunctions: fallbackJunctions.length,
nativeMaxJunctionExpansionRatio: junctions.reduce((maximum, feature) => Math.max(maximum, Number(feature.properties.expansion_ratio) || 0), 0),
nativeLaneCenterlineFeatures: compiled.laneCenterlines.features.length,
nativeLaneSeparatorFeatures: compiled.laneSeparators.features.length,
nativeCenterLineFeatures: compiled.centerLines.features.length,
nativeDirectionArrowFeatures: compiled.directionArrows.features.length,
nativeTurnArrowFeatures: compiled.turnArrows.features.length,
nativeCrosswalkFeatures: compiled.crosswalks.features.length,
nativeVehicleStopLineFeatures: compiled.vehicleStopLines.features.length,
nativeConnectorFeatures: compiled.connectors.features.length,
nativeMovementCount: compiled.movements.length,
nativePublishedMovementCount: compiled.movements.filter((movement) => movement.geometryPublished).length,
nativeConnectionCount: model.connections.length,
unconnectedInteriorRoadEnds: dangling.length,
unconnectedEndsWithManualCandidates: dangling.filter((item) => item.manualCandidates?.length).length,
diagnosticsBySeverity,
diagnosticsByRule,
osm2streetsRoadSurfaceFeatures: featureCount,
osm2streetsAvailable: featureCount !== null,
note: "Counts are coverage evidence only; geometry quality requires diagnostic and visual review.",
};
}
function validateInput(input) {
if (!input || typeof input !== "object") throw new Error("RoadCompilerInput must be an object");
for (const key of ["areaId", "osmFile", "outDir", "stagingDir", "overridesFile", "trafficSignalsFile"]) {
if (typeof input[key] !== "string" || input[key].trim() === "") throw new Error(`RoadCompilerInput.${key} must be a non-empty string`);
}
if (!input.options || typeof input.options !== "object") throw new Error("RoadCompilerInput.options must be an object");
if (typeof input.options.edgeLines !== "boolean") throw new Error("RoadCompilerInput.options.edgeLines must be a boolean");
if (!input.options.junctionTemplates || typeof input.options.junctionTemplates !== "object") throw new Error("RoadCompilerInput.options.junctionTemplates must be an object");
}
module.exports = { compileInput, validateInput };
@@ -1,474 +0,0 @@
"use strict";
const fs = require("fs");
const { convertGeoJson, boundsOf } = require("../reference/gaode");
const metricsCache = new WeakMap();
const CORNER_FILLET_SEGMENTS = 12;
// Must match DEFAULT_SIDEWALK_WIDTH_METERS in native-road.js so the corner band
// lines up with the straight strips it joins.
const SIDEWALK_WIDTH_METERS = 2;
// The straight strips are trimmed against the cluster boundary using the road
// centerline, so they stop a little beyond the carriageway end. Run the corner
// past that end and let the two overlap rather than chase an exact seam.
const SIDEWALK_CORNER_OVERRUN_METERS = 6;
function buildComplexJunctionGeometry(model, cluster, helpers) {
const nodeIds = new Set(cluster.nodeIds.map(String));
const nodes = cluster.nodeIds.map((id) => helpers.junctionPlans.get(String(id))?.node).filter(Boolean);
if (nodes.length < 2) return { features: [], diagnostics: [helpers.diagnostic("warning", `junction-cluster:${cluster.id}`, [...nodeIds], "complex-junction-insufficient-nodes", "复合路口至少需要两个有效节点。", null)] };
const center = nodes.reduce((sum, point) => [sum[0] + point[0] / nodes.length, sum[1] + point[1] / nodes.length], [0, 0]);
const approaches = [];
const carriageways = [];
for (const [nodeId, plan] of helpers.junctionPlans) {
if (!nodeIds.has(String(nodeId))) continue;
for (const approach of plan.approaches) {
const endpoint = approach.line.at(-1);
if (nodes.some((node) => node !== plan.node && helpers.distanceMeters(endpoint, node) < 4)) continue;
const heading = helpers.headingAtEndpoint(approach.line);
const length = helpers.lineLengthMeters(approach.line);
carriageways.push({ nodeId, approach, plan, heading, length });
if (approaches.some((item) => Math.abs(normalizeHeading(item.heading - heading)) < 20)) continue;
approaches.push({ nodeId, approach, plan, heading, length });
}
}
if (approaches.length < 3) return { features: [], diagnostics: [helpers.diagnostic("warning", `junction-cluster:${cluster.id}`, [...nodeIds], "complex-junction-insufficient-approaches", "复合路口无法识别足够的外部进口。", center)] };
const { calibration, coreRadius } = complexJunctionMetrics(cluster);
const sorted = [...approaches].sort((a, b) => a.heading - b.heading);
const arms = sorted.map((representative) => ({
representative,
heading: averageHeading(carriageways.filter((candidate) => Math.abs(normalizeHeading(candidate.heading - representative.heading)) < 20).map((candidate) => candidate.heading)),
members: carriageways.filter((candidate) => Math.abs(normalizeHeading(candidate.heading - representative.heading)) < 20),
}));
const outerRadius = complexJunctionMetrics(cluster).approachOuterRadius;
const boundaryParts = [];
const crosswalks = [];
const stopLines = [];
const islands = [];
const armCrosswalkRadius = coreRadius * .68;
for (const item of carriageways) {
const outer = pointOnCarriagewayRadius(item, center, outerRadius, helpers);
const inner = pointOnCarriagewayRadius(item, center, coreRadius * .7, helpers);
const outerHalf = item.approach.widthMeters / 2;
const innerHalf = outerHalf;
boundaryParts.push({ item, outer, inner, outerHalf, innerHalf });
const incomingRoad = item.approach.roadIds.map((roadId) => model.roads.find((road) => road.id === roadId)).find((road) => String(road?.sourceNodeIds.at(-1)) === String(item.nodeId));
if (incomingRoad) {
// Keep the stop bar just outside the road crosswalk. The previous fixed
// core-radius offset placed it nearly ten metres beyond the crossing.
const stopCenter = pointOnCarriagewayRadius(item, center, armCrosswalkRadius + 3, helpers);
const ring = [
helpers.offsetCoordinate(helpers.offsetCoordinate(stopCenter, item.heading + 90, -outerHalf), item.heading, -.24),
helpers.offsetCoordinate(helpers.offsetCoordinate(stopCenter, item.heading + 90, outerHalf), item.heading, -.24),
helpers.offsetCoordinate(helpers.offsetCoordinate(stopCenter, item.heading + 90, outerHalf), item.heading, .24),
helpers.offsetCoordinate(helpers.offsetCoordinate(stopCenter, item.heading + 90, -outerHalf), item.heading, .24),
helpers.offsetCoordinate(helpers.offsetCoordinate(stopCenter, item.heading + 90, -outerHalf), item.heading, -.24),
];
stopLines.push({ type: "Feature", properties: { native_id: `complex-stop-line:${cluster.id}:${item.approach.segmentId}`, cluster_id: cluster.id, kind: "complex-stop-line", road_id: incomingRoad.id, node_id: item.nodeId, direction: item.heading, provenance: "native-road-complex-junction-stop-line/v1" }, geometry: { type: "Polygon", coordinates: [ring] } });
}
}
// The four support lines provide a common corner frame, but each long
// crossing remains clipped to its OSM-derived road envelope. Corner islands
// fill the remaining frame gaps; crossings must never do that job.
for (const arm of arms) {
const envelope = armEnvelopeAtRadius(arm, armCrosswalkRadius, center, helpers);
if (!envelope) continue;
arm.crosswalkFrame = {
center: envelope.center,
groupDepth: 3.4,
supportHeading: normalizeHeading(arm.heading + 90),
envelopeWidthMeters: envelope.widthMeters,
};
}
const frameCorners = arms.map((arm, index) => {
const next = arms[(index + 1) % arms.length];
const delta = positiveHeadingDelta(arm.heading, next.heading);
if (delta < 45 || delta > 135 || !arm.crosswalkFrame || !next.crosswalkFrame) return null;
return supportLineIntersection(arm.crosswalkFrame, next.crosswalkFrame, center);
});
for (let index = 0; index < arms.length; index += 1) {
const arm = arms[index];
if (!arm.crosswalkFrame) continue;
const item = arm.representative;
const roadEdgeInset = .35;
const usableSpan = Math.max(.42, arm.crosswalkFrame.envelopeWidthMeters - roadEdgeInset * 2);
const endpoints = [
helpers.offsetCoordinate(arm.crosswalkFrame.center, arm.heading + 90, -usableSpan / 2),
helpers.offsetCoordinate(arm.crosswalkFrame.center, arm.heading + 90, usableSpan / 2),
];
const groupDepth = arm.crosswalkFrame.groupDepth;
const stripeWidth = .42;
const stripeCount = Math.max(6, Math.floor((usableSpan - stripeWidth) / .82) + 1);
const stripeSpacing = stripeCount > 1 ? (usableSpan - stripeWidth) / (stripeCount - 1) : 0;
arm.crosswalkFrame.center = midpoint(...endpoints);
arm.crosswalkFrame.endpoints = endpoints;
arm.crosswalkFrame.spanMeters = usableSpan;
arm.crosswalkFrame.roadEdgeInsetMeters = roadEdgeInset;
for (let stripe = 0; stripe < stripeCount; stripe += 1) {
const along = stripeWidth / 2 + stripe * stripeSpacing;
const centerPoint = helpers.offsetCoordinate(endpoints[0], bearing(...endpoints), along);
const ring = [
helpers.offsetCoordinate(helpers.offsetCoordinate(centerPoint, arm.heading, -groupDepth / 2), arm.heading + 90, -stripeWidth / 2),
helpers.offsetCoordinate(helpers.offsetCoordinate(centerPoint, arm.heading, groupDepth / 2), arm.heading + 90, -stripeWidth / 2),
helpers.offsetCoordinate(helpers.offsetCoordinate(centerPoint, arm.heading, groupDepth / 2), arm.heading + 90, stripeWidth / 2),
helpers.offsetCoordinate(helpers.offsetCoordinate(centerPoint, arm.heading, -groupDepth / 2), arm.heading + 90, stripeWidth / 2),
helpers.offsetCoordinate(helpers.offsetCoordinate(centerPoint, arm.heading, -groupDepth / 2), arm.heading + 90, -stripeWidth / 2),
];
crosswalks.push({ type: "Feature", properties: { native_id: `complex-crosswalk:${cluster.id}:${item.nodeId}:${item.approach.segmentId}:${stripe + 1}`, cluster_id: cluster.id, kind: "complex-crosswalk", crossing_node_id: item.nodeId, road_id: item.approach.roadIds[0], direction: arm.heading, radial_distance_m: armCrosswalkRadius, span_m: usableSpan, road_envelope_span_m: arm.crosswalkFrame.envelopeWidthMeters, road_edge_inset_m: roadEdgeInset, group_depth_m: groupDepth, stripe_width_m: stripeWidth, stripe_spacing_m: stripeSpacing, frame_center: arm.crosswalkFrame.center, frame_support_heading: arm.crosswalkFrame.supportHeading, provenance: "native-road-complex-junction-crosswalk/v6-road-clipped" }, geometry: { type: "Polygon", coordinates: [ring] } });
}
}
// The four arm groups are the sides of one pedestrian frame. Each diagonal
// group is anchored at the intersection of its adjacent side support lines,
// so all eight groups stay one composition when the OSM arms are skewed.
for (let index = 0; index < arms.length; index += 1) {
const first = arms[index];
const second = arms[(index + 1) % arms.length];
const delta = positiveHeadingDelta(first.heading, second.heading);
if (delta < 45 || delta > 135) continue;
if (!first.crosswalkFrame || !second.crosswalkFrame) continue;
const bisector = normalizeHeading(first.heading + delta / 2);
const frameCorner = frameCorners[index];
if (!frameCorner) continue;
const cornerStripeSpacing = .62;
const cornerStripeWidth = .4;
const cornerGroupHalfDepth = (5 * cornerStripeSpacing + cornerStripeWidth) / 2;
const endpointForCorner = (arm) => [...arm.crosswalkFrame.endpoints].sort((a, b) => helpers.distanceMeters(a, frameCorner) - helpers.distanceMeters(b, frameCorner))[0];
const outerEdgeAtCorner = (arm) => {
const endpoint = endpointForCorner(arm);
return [arm.heading, arm.heading + 180]
.map((heading) => helpers.offsetCoordinate(endpoint, heading, arm.crosswalkFrame.groupDepth / 2))
.sort((a, b) => directionalProjectionMeters(center, b, bisector) - directionalProjectionMeters(center, a, bisector))[0];
};
const islandBaseGap = .05;
const islandApexOffset = 1.5;
const islandBase = [outerEdgeAtCorner(first), outerEdgeAtCorner(second)].map((point) => helpers.offsetCoordinate(point, bisector, islandBaseGap));
const islandApex = helpers.offsetCoordinate(frameCorner, bisector, islandApexOffset);
const islandCrossingClearance = .2;
const cornerCrossingOffset = islandApexOffset + islandCrossingClearance + cornerGroupHalfDepth;
const islandInnerRadius = Math.min(...islandBase.map((point) => directionalProjectionMeters(center, point, bisector)));
const islandOuterRadius = directionalProjectionMeters(center, islandApex, bisector);
const cornerCrossingCenter = helpers.offsetCoordinate(frameCorner, bisector, cornerCrossingOffset);
const islandRing = roundedPolygonRing([islandBase[0], islandApex, islandBase[1]], .24);
islands.push({ type: "Feature", properties: { native_id: `complex-corner-island:${cluster.id}:${index + 1}`, cluster_id: cluster.id, kind: "complex-corner-island", corner_index: index + 1, from_heading: first.heading, to_heading: second.heading, frame_corner: frameCorner, base_points: islandBase, apex_point: islandApex, inner_radius_m: islandInnerRadius, outer_radius_m: islandOuterRadius, base_width_m: helpers.distanceMeters(...islandBase), crossing_clearance_m: islandCrossingClearance, corner_rounding_ratio: .24, provenance: "native-road-complex-junction-corner/v7-road-gap-fill" }, geometry: { type: "Polygon", coordinates: [islandRing] } });
let cornerCrossingHalfSpan = .4;
for (let stripe = 0; stripe < 6; stripe += 1) {
const stripeOffset = (stripe - 2.5) * cornerStripeSpacing;
const stripeCenter = helpers.offsetCoordinate(cornerCrossingCenter, bisector, stripeOffset);
const stripeRadius = directionalProjectionMeters(center, stripeCenter, bisector);
const curbPair = limitedCornerPair(first, second, stripeRadius, bisector, center, 6.5, helpers);
if (!curbPair) continue;
const halfSpan = Math.max(.4, Math.min(6.5, helpers.distanceMeters(...curbPair)) / 2);
cornerCrossingHalfSpan = Math.max(cornerCrossingHalfSpan, halfSpan);
const stripePair = [
helpers.offsetCoordinate(stripeCenter, bisector - 90, halfSpan),
helpers.offsetCoordinate(stripeCenter, bisector + 90, halfSpan),
];
const ring = [
helpers.offsetCoordinate(stripePair[0], bisector, -cornerStripeWidth / 2),
helpers.offsetCoordinate(stripePair[1], bisector, -cornerStripeWidth / 2),
helpers.offsetCoordinate(stripePair[1], bisector, cornerStripeWidth / 2),
helpers.offsetCoordinate(stripePair[0], bisector, cornerStripeWidth / 2),
helpers.offsetCoordinate(stripePair[0], bisector, -cornerStripeWidth / 2),
];
crosswalks.push({ type: "Feature", properties: { native_id: `complex-corner-crosswalk:${cluster.id}:${index + 1}:${stripe + 1}`, cluster_id: cluster.id, kind: "complex-corner-crosswalk", corner_index: index + 1, direction: bisector, radial_distance_m: stripeRadius, frame_corner: frameCorner, from_heading: first.heading, to_heading: second.heading, provenance: "native-road-complex-junction-corner-crosswalk/v3" }, geometry: { type: "Polygon", coordinates: [ring] } });
}
}
// Each carriageway ends in its own rectangle, so adjacent arms meet at a
// sharp notch instead of a curb. A real corner is one tangent-continuous
// sweep between the two outermost road edges, so fit a fixed-radius fillet
// into the wedge those edges form and fill the sector behind it.
const cornerFills = [];
const sidewalkCorners = [];
const cornerDiagnostics = [];
const cornerRadius = Math.max(4, Math.min(25, Number(cluster.cornerRadiusMeters) || 12));
for (let index = 0; index < arms.length; index += 1) {
const first = arms[index];
const second = arms[(index + 1) % arms.length];
const delta = positiveHeadingDelta(first.heading, second.heading);
if (delta < 45 || delta > 135) continue;
const bisector = normalizeHeading(first.heading + delta / 2);
const edges = [first, second].map((arm) => cornerEdgeAt(arm, coreRadius + 6, bisector, center, helpers));
if (!edges.every(Boolean)) continue;
const apex = rayIntersection(edges[0], edges[1], center);
const apexReach = apex ? directionalProjectionMeters(center, apex, bisector) : null;
// The wedge apex has to sit ahead of the core and inside the arm handoff;
// outside that band the two edges are near parallel and any fillet fitted
// to them would sweep across the carriageways instead of the corner.
if (apexReach === null || apexReach < 1 || apexReach > outerRadius) {
cornerDiagnostics.push(helpers.diagnostic("warning", `junction-cluster:${cluster.id}`, [...nodeIds], "complex-junction-corner-fillet-fallback", "该夹角的道路边缘切线无法安全构造圆角,已保留直角过渡。", center));
continue;
}
// Tangent distance for a circle of `cornerRadius` inscribed in a wedge of
// opening `delta`, clamped so the tangent points stay on the built arms.
const tangentDistance = Math.min(cornerRadius / Math.tan(delta * Math.PI / 360), Math.max(2, outerRadius - apexReach));
const tangents = edges.map((edge) => helpers.offsetCoordinate(apex, edge.heading, tangentDistance));
const curve = quadraticCurve(tangents[0], apex, tangents[1], CORNER_FILLET_SEGMENTS);
const ring = [...curve, center, curve[0]];
if (!ring.every((point) => point.every(Number.isFinite))) continue;
cornerFills.push({ type: "Feature", properties: { native_id: `complex-corner-fillet:${cluster.id}:${index + 1}`, cluster_id: cluster.id, kind: "complex-corner-fillet", complex_part: "corner-fillet", corner_index: index + 1, from_heading: first.heading, to_heading: second.heading, bisector_heading: bisector, corner_radius_m: cornerRadius, tangent_distance_m: Math.round(tangentDistance * 100) / 100, apex_reach_m: Math.round(apexReach * 100) / 100, provenance: "native-road-complex-junction-corner-fillet/v1" }, geometry: { type: "Polygon", coordinates: [ring] } });
// The straight pedestrian strips are trimmed at the cluster boundary, so
// two arms that both carry a footway still meet as two loose ends across
// an empty wedge. Bridge them along the curb the fillet already defines.
// The corner faces clockwise from `first` and counter-clockwise from
// `second`, so each arm must carry the footway on that facing side.
if (!armCarriesSidewalk(first, model, true) || !armCarriesSidewalk(second, model, false)) continue;
const curb = [
...edgeRunToRadius(apex, edges[0], tangentDistance, outerRadius + SIDEWALK_CORNER_OVERRUN_METERS, center, helpers).reverse(),
...curve.slice(1, -1),
...edgeRunToRadius(apex, edges[1], tangentDistance, outerRadius + SIDEWALK_CORNER_OVERRUN_METERS, center, helpers),
];
const outerEdge = offsetPolylineAwayFromCenter(curb, center, SIDEWALK_WIDTH_METERS, helpers);
const sidewalkRing = [...curb, ...outerEdge.slice().reverse(), curb[0]];
if (!sidewalkRing.every((point) => point.every(Number.isFinite)) || ringSelfIntersects(sidewalkRing)) {
cornerDiagnostics.push(helpers.diagnostic("warning", `junction-cluster:${cluster.id}`, [...nodeIds], "complex-junction-sidewalk-corner-fallback", "该夹角的人行道转角几何自交或无效,已跳过,两侧步行带保持断开。", center));
continue;
}
sidewalkCorners.push({ type: "Feature", properties: { native_id: `complex-sidewalk-corner:${cluster.id}:${index + 1}`, cluster_id: cluster.id, kind: "complex-sidewalk-corner", corner_index: index + 1, from_heading: first.heading, to_heading: second.heading, bisector_heading: bisector, width_m: SIDEWALK_WIDTH_METERS, overrun_m: SIDEWALK_CORNER_OVERRUN_METERS, provenance: "native-road-complex-junction-sidewalk-corner/v1" }, geometry: { type: "Polygon", coordinates: [sidewalkRing] } });
}
const corePoints = boundaryParts.flatMap(({ item, inner, innerHalf }) => [helpers.offsetCoordinate(inner, item.heading + 90, innerHalf), helpers.offsetCoordinate(inner, item.heading - 90, innerHalf)]).sort((first, second) => angleAround(center, first) - angleAround(center, second));
const coreRing = roundedPolygonRing(corePoints, .16);
const features = [{ type: "Feature", properties: { native_id: `complex-junction:${cluster.id}:core`, cluster_id: cluster.id, kind: "complex-core", complex_part: "core", center, radius_m: coreRadius, configured_radius_m: cluster.coreRadiusMeters, approach_count: approaches.length, carriageway_count: carriageways.length, approach_headings: sorted.map((item) => Math.round(item.heading * 10) / 10), corner_rounding_ratio: .16, provenance: "native-road-complex-junction/v6-rounded-core" }, geometry: { type: "Polygon", coordinates: [coreRing] } }];
for (const { item, outer, inner, outerHalf, innerHalf } of boundaryParts) {
const ring = [helpers.offsetCoordinate(outer, item.heading + 90, outerHalf), helpers.offsetCoordinate(inner, item.heading + 90, innerHalf), helpers.offsetCoordinate(inner, item.heading - 90, innerHalf), helpers.offsetCoordinate(outer, item.heading - 90, outerHalf), helpers.offsetCoordinate(outer, item.heading + 90, outerHalf)];
features.push({ type: "Feature", properties: { native_id: `complex-junction:${cluster.id}:carriageway:${item.approach.segmentId}`, cluster_id: cluster.id, kind: "complex-approach", complex_part: "carriageway", heading_deg: item.heading, lane_count: item.approach.roadIds.reduce((sum, roadId) => sum + (model.roads.find((road) => road.id === roadId)?.laneCount || 0), 0), width_m: item.approach.widthMeters, provenance: "native-road-complex-junction/v5" }, geometry: { type: "Polygon", coordinates: [ring] } });
}
// Corner fills come last so they overlay the rectangular carriageway ends
// they are smoothing; they never replace an OSM-derived road surface.
features.push(...cornerFills);
// `coreRadiusMeters` is only consulted when there is no reference geometry.
// Under calibration the radius comes from the reference span, so a configured
// value that silently does nothing has to be reported, not swallowed.
const configuredRadiusIgnored = calibration && Number.isFinite(cluster.coreRadiusMeters) && Math.abs(coreRadius - cluster.coreRadiusMeters) > .5;
const configurationDiagnostics = configuredRadiusIgnored
? [helpers.diagnostic("info", `junction-cluster:${cluster.id}`, [...nodeIds], "complex-junction-configured-radius-ignored", `已按参考几何校准核心半径为 ${Math.round(coreRadius * 10) / 10} 米,配置的 coreRadiusMeters=${cluster.coreRadiusMeters} 在有参考文件时不生效。`, center)]
: [];
return { features, islands: [...islands, ...sidewalkCorners], crosswalks, stopLines, center, approaches, diagnostics: [...cornerDiagnostics, ...configurationDiagnostics, helpers.diagnostic("info", `junction-cluster:${cluster.id}`, [...nodeIds], calibration ? "complex-junction-reference-calibrated" : "complex-junction-generated", calibration ? `已使用参考几何校准参数后,由 OSM/native 重新生成 ${approaches.length} 个进口、道路面、中央分隔带、斑马线和停止线。` : `已独立生成 ${approaches.length} 个进口、道路面、中央分隔带、斑马线和停止线。`, center)] };
}
function readReferenceCalibration(cluster) {
if (!cluster.referenceFile || !fs.existsSync(cluster.referenceFile)) return null;
try {
const converted = convertGeoJson(JSON.parse(fs.readFileSync(cluster.referenceFile, "utf8")));
const bounds = boundsOf({ features: converted.features.filter((feature) => [1, 2, 3, 4].includes(Number(feature.properties?.type))) });
const lonScale = 111320 * Math.cos(((bounds.minLat + bounds.maxLat) / 2) * Math.PI / 180);
return { longSpanMeters: (bounds.maxLon - bounds.minLon) * lonScale, shortSpanMeters: (bounds.maxLat - bounds.minLat) * 111320 };
} catch (_) {
return null;
}
}
function complexJunctionMetrics(cluster) {
if (metricsCache.has(cluster)) return metricsCache.get(cluster);
const calibration = readReferenceCalibration(cluster);
// Without a reference geometry `coreRadiusMeters` is the only size input the
// template has, so honour it literally within the schema's own 12..80 range.
// It used to be scaled by .52 and clamped to 17, which silently capped every
// unreferenced junction at a core far smaller than its own approach envelope
// — a 24 m dual-carriageway arm was being fitted into a 16.6 m core no matter
// what the config asked for. The calibrated branch is unchanged.
const coreRadius = calibration
? Math.max(12, Math.min(24, calibration.shortSpanMeters * .14))
: Math.max(12, Math.min(80, Number(cluster.coreRadiusMeters) || 28));
const metrics = { calibration, coreRadius, approachOuterRadius: coreRadius + (Number(cluster.outerRadiusExtraMeters) || 18) };
metricsCache.set(cluster, metrics);
return metrics;
}
function normalizeHeading(value) { return ((value + 180) % 360 + 360) % 360 - 180; }
// `arm.heading` points outward from the junction, so the corner clockwise from
// it sits at heading+90 and the one counter-clockwise at heading-90. A road's
// own sidewalk flags are relative to its digitisation direction, so flip them
// whenever the arm runs against that direction.
function armCarriesSidewalk(arm, model, cornerIsClockwise) {
return arm.members.some((member) => member.approach.roadIds
.map((roadId) => model.roads.find((road) => road.id === roadId))
.filter(Boolean)
.some((road) => {
const outwardIsForward = String(road.sourceNodeIds[0]) === String(member.nodeId);
const onClockwiseSide = outwardIsForward ? road.sidewalkRight : road.sidewalkLeft;
const onCounterClockwiseSide = outwardIsForward ? road.sidewalkLeft : road.sidewalkRight;
return Boolean(cornerIsClockwise ? onClockwiseSide : onCounterClockwiseSide);
}));
}
// Walk outward along a wedge edge from its tangent point until the curb reaches
// `targetRadius`, so the corner band overlaps the straight strip it joins.
function edgeRunToRadius(apex, edge, tangentDistance, targetRadius, center, helpers) {
const points = [];
for (let extra = 0; extra <= 40; extra += 2) {
const point = helpers.offsetCoordinate(apex, edge.heading, tangentDistance + extra);
points.push(point);
if (helpers.distanceMeters(point, center) >= targetRadius) break;
}
return points;
}
// Offset each vertex along the polyline normal that increases distance from the
// junction centre. The curb is star-shaped around that centre, so "farther from
// the centre" is a reliable stand-in for "on the pedestrian side".
function offsetPolylineAwayFromCenter(points, center, meters, helpers) {
return points.map((point, index) => {
const previous = points[Math.max(0, index - 1)];
const next = points[Math.min(points.length - 1, index + 1)];
const tangent = previous === next ? 0 : bearing(previous, next);
return [tangent + 90, tangent - 90]
.map((heading) => helpers.offsetCoordinate(point, heading, meters))
.sort((first, second) => helpers.distanceMeters(second, center) - helpers.distanceMeters(first, center))[0];
});
}
function ringSelfIntersects(ring) {
const cross = (a, b, c) => (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
const straddles = (p1, p2, p3, p4) => {
const d1 = cross(p3, p4, p1); const d2 = cross(p3, p4, p2);
const d3 = cross(p1, p2, p3); const d4 = cross(p1, p2, p4);
return ((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0));
};
for (let first = 0; first < ring.length - 1; first += 1) {
for (let second = first + 2; second < ring.length - 1; second += 1) {
if (first === 0 && second === ring.length - 2) continue;
if (straddles(ring[first], ring[first + 1], ring[second], ring[second + 1])) return true;
}
}
return false;
}
function angleAround(center, point) { return Math.atan2(point[1] - center[1], point[0] - center[0]); }
function signedLateralMeters(origin, point, heading) {
const east = (point[0] - origin[0]) * 111320 * Math.cos(origin[1] * Math.PI / 180);
const north = (point[1] - origin[1]) * 111320;
const radians = (heading + 90) * Math.PI / 180;
return east * Math.sin(radians) + north * Math.cos(radians);
}
function bearing(first, second) {
const east = (second[0] - first[0]) * Math.cos(first[1] * Math.PI / 180);
const north = second[1] - first[1];
return Math.atan2(east, north) * 180 / Math.PI;
}
function midpoint(first, second) { return [(first[0] + second[0]) / 2, (first[1] + second[1]) / 2]; }
function averageHeading(headings) {
const vector = headings.reduce((sum, heading) => {
const radians = heading * Math.PI / 180;
return [sum[0] + Math.sin(radians), sum[1] + Math.cos(radians)];
}, [0, 0]);
return Math.atan2(vector[0], vector[1]) * 180 / Math.PI;
}
function positiveHeadingDelta(first, second) { return ((second - first) % 360 + 360) % 360; }
function pointOnCarriagewayRadius(item, center, radius, helpers) {
const start = item.approach.line[0];
const startRadius = directionalProjectionMeters(center, start, item.heading);
return helpers.pointAlongLine(item.approach.line, Math.max(0, Math.min(item.length, radius - startRadius)));
}
function armEnvelopeAtRadius(arm, radius, center, helpers) {
if (!arm.members.length) return null;
const centers = arm.members.map((member) => pointOnCarriagewayRadius(member, center, radius, helpers));
const reference = centers[0];
let minimum = Infinity;
let maximum = -Infinity;
centers.forEach((point, index) => {
const lateral = signedLateralMeters(reference, point, arm.heading);
const halfWidth = arm.members[index].approach.widthMeters / 2;
minimum = Math.min(minimum, lateral - halfWidth);
maximum = Math.max(maximum, lateral + halfWidth);
});
if (!Number.isFinite(minimum) || maximum - minimum < 1) return null;
return { center: helpers.offsetCoordinate(reference, arm.heading + 90, (minimum + maximum) / 2), widthMeters: maximum - minimum };
}
function supportLineIntersection(first, second, origin) {
const lonScale = 111320 * Math.cos(origin[1] * Math.PI / 180);
const toLocal = (point) => [(point[0] - origin[0]) * lonScale, (point[1] - origin[1]) * 111320];
const firstPoint = toLocal(first.center);
const secondPoint = toLocal(second.center);
const direction = (heading) => {
const radians = heading * Math.PI / 180;
return [Math.sin(radians), Math.cos(radians)];
};
const firstDirection = direction(first.supportHeading);
const secondDirection = direction(second.supportHeading);
const denominator = firstDirection[0] * secondDirection[1] - firstDirection[1] * secondDirection[0];
if (Math.abs(denominator) < 1e-6) return null;
const delta = [secondPoint[0] - firstPoint[0], secondPoint[1] - firstPoint[1]];
const distanceAlongFirst = (delta[0] * secondDirection[1] - delta[1] * secondDirection[0]) / denominator;
const intersection = [firstPoint[0] + firstDirection[0] * distanceAlongFirst, firstPoint[1] + firstDirection[1] * distanceAlongFirst];
return [origin[0] + intersection[0] / lonScale, origin[1] + intersection[1] / 111320];
}
function limitedCornerPair(first, second, radius, bisector, center, maxWidth, helpers) {
const pair = [cornerEdgeAtRadius(first, radius, bisector, center, helpers), cornerEdgeAtRadius(second, radius, bisector, center, helpers)];
if (!pair.every(Boolean)) return null;
const width = helpers.distanceMeters(pair[0], pair[1]);
const middle = midpoint(pair[0], pair[1]);
const halfWidth = Math.max(.4, Math.min(width, maxWidth) / 2);
const acrossHeading = width > .1 ? bearing(pair[0], pair[1]) : bisector + 90;
return [helpers.offsetCoordinate(middle, acrossHeading + 180, halfWidth), helpers.offsetCoordinate(middle, acrossHeading, halfWidth)];
}
function cornerEdgeAtRadius(arm, radius, bisector, center, helpers) {
return cornerEdgeAt(arm, radius, bisector, center, helpers)?.point || null;
}
function cornerEdgeAt(arm, radius, bisector, center, helpers) {
const candidates = arm.members.flatMap((member) => {
const point = pointOnCarriagewayRadius(member, center, radius, helpers);
const halfWidth = member.approach.widthMeters / 2;
return [90, -90].map((side) => ({ point: helpers.offsetCoordinate(point, member.heading + side, halfWidth), heading: member.heading }));
});
return candidates.sort((first, second) => directionalProjectionMeters(center, second.point, bisector) - directionalProjectionMeters(center, first.point, bisector))[0] || null;
}
function rayIntersection(first, second, origin) {
const lonScale = 111320 * Math.cos(origin[1] * Math.PI / 180);
const toLocal = (point) => [(point[0] - origin[0]) * lonScale, (point[1] - origin[1]) * 111320];
const direction = (heading) => {
const radians = heading * Math.PI / 180;
return [Math.sin(radians), Math.cos(radians)];
};
const firstPoint = toLocal(first.point);
const secondPoint = toLocal(second.point);
const firstDirection = direction(first.heading);
const secondDirection = direction(second.heading);
const denominator = firstDirection[0] * secondDirection[1] - firstDirection[1] * secondDirection[0];
if (Math.abs(denominator) < 1e-4) return null;
const delta = [secondPoint[0] - firstPoint[0], secondPoint[1] - firstPoint[1]];
const distanceAlongFirst = (delta[0] * secondDirection[1] - delta[1] * secondDirection[0]) / denominator;
const local = [firstPoint[0] + firstDirection[0] * distanceAlongFirst, firstPoint[1] + firstDirection[1] * distanceAlongFirst];
if (!local.every(Number.isFinite)) return null;
return [origin[0] + local[0] / lonScale, origin[1] + local[1] / 111320];
}
function quadraticCurve(start, control, end, segments) {
const result = [];
for (let index = 0; index <= segments; index += 1) {
const t = index / segments;
const u = 1 - t;
result.push([u * u * start[0] + 2 * u * t * control[0] + t * t * end[0], u * u * start[1] + 2 * u * t * control[1] + t * t * end[1]]);
}
return result;
}
function directionalProjectionMeters(origin, point, heading) {
const east = (point[0] - origin[0]) * 111320 * Math.cos(origin[1] * Math.PI / 180);
const north = (point[1] - origin[1]) * 111320;
const radians = heading * Math.PI / 180;
return east * Math.sin(radians) + north * Math.cos(radians);
}
function smoothClosedRing(vertices) {
// Curb-edge candidates can arrive in opposite winding orders when an OSM
// carriageway bends slightly. Sort this local corner only around its own
// centroid before rounding, avoiding a self-crossing safety island while
// keeping the global junction boundary fully OSM-driven.
const centroid = vertices.reduce((sum, point) => [sum[0] + point[0] / vertices.length, sum[1] + point[1] / vertices.length], [0, 0]);
const ordered = [...vertices].sort((first, second) => Math.atan2(first[1] - centroid[1], first[0] - centroid[0]) - Math.atan2(second[1] - centroid[1], second[0] - centroid[0]));
const points = ordered.flatMap((point, index) => {
const next = ordered[(index + 1) % ordered.length];
return [interpolateCoordinate(point, next, .18), interpolateCoordinate(point, next, .82)];
});
return [...points, points[0]];
}
function roundedPolygonRing(vertices, ratio) {
const points = vertices.flatMap((point, index) => {
const previous = vertices[(index - 1 + vertices.length) % vertices.length];
const next = vertices[(index + 1) % vertices.length];
return [interpolateCoordinate(previous, point, 1 - ratio), interpolateCoordinate(point, next, ratio)];
});
return [...points, points[0]];
}
function interpolateCoordinate(first, second, ratio) { return [first[0] + (second[0] - first[0]) * ratio, first[1] + (second[1] - first[1]) * ratio]; }
module.exports = { buildComplexJunctionGeometry, complexJunctionMetrics };
File diff suppressed because it is too large. Load diff
@@ -1,502 +0,0 @@
"use strict";
const fs = require("fs");
const path = require("path");
const { laneCenterline } = require("../geometry/lane-geometry");
const ASSET_MANIFEST = path.resolve(__dirname, "..", "..", "..", "..", "assets", "lane-icons", "manifest.json");
const LANE_WIDTH_METERS = 3.2;
const PLACEMENT_DISTANCE_METERS = 9;
const SPATIAL_MATCH_MAX_DISTANCE_METERS = 18;
const SPATIAL_MATCH_MIN_ALIGNMENT = Math.cos(Math.PI / 6);
// Existing osm2streets lane arrows are approximately 1.4 m across. Keep the
// 25-unit upstream icon at the same on-road scale rather than at screen scale.
const SVG_METERS_PER_UNIT = 0.10;
function loadManifest(file = ASSET_MANIFEST) {
const manifest = JSON.parse(fs.readFileSync(file, "utf8"));
if (!Array.isArray(manifest.assets)) throw new Error("turn-lane asset manifest has no assets array");
return manifest;
}
function supportedAssets(manifest = loadManifest()) {
return new Map(manifest.assets
.filter((asset) => asset.supported === true && asset.tested === true)
.map((asset) => [asset.id, asset]));
}
function buildCustomTurnLaneArrows(osm, options = {}) {
const enabled = options.enabled === true;
const diagnostics = [];
if (!enabled) return { features: [], diagnostics: [{ reason: "disabled" }] };
const assets = supportedAssets(options.manifest);
const endpointRoadCounts = roadCountsByNode(osm);
const networkIntersectionNodes = new Set((options.network?.intersections || [])
.flatMap(([, intersection]) => intersection.osm_ids || []).map(Number));
const features = [];
const ways = [...osm.ways.values()].sort((a, b) => a.id - b.id);
for (const way of ways) {
for (const direction of ["forward", "backward"]) {
const tag = way.tags[`turn:lanes:${direction}`];
if (!tag) continue;
const laneCount = directionalLaneCount(way, direction);
if (!laneCount) {
diagnostics.push(skip(way, direction, "missing_lane_count"));
continue;
}
const endpoint = endpointGeometry(osm, way, direction, endpointRoadCounts, networkIntersectionNodes);
if (!endpoint) {
diagnostics.push(skip(way, direction, "indeterminate_intersection_endpoint"));
continue;
}
const maneuvers = String(tag).split("|").map((value) => normalizeManeuver(value));
for (let laneIndex = 0; laneIndex < maneuvers.length; laneIndex += 1) {
const maneuver = maneuvers[laneIndex];
const asset = assets.get(maneuver);
if (!asset) {
diagnostics.push(skip(way, direction, "unsupported_or_untested_maneuver", { lane_index: laneIndex, maneuver }));
continue;
}
if (laneIndex >= laneCount) {
diagnostics.push(skip(way, direction, "lane_index_exceeds_lane_count", { lane_index: laneIndex, maneuver }));
continue;
}
const resolvedPlacement = lanePlacement(way, direction, laneIndex, endpoint, options.lanePolygons, options.crosswalkStripes, options.stopLines);
if (resolvedPlacement?.blocked) {
diagnostics.push(skip(way, direction, "no_safe_turn_arrow_position", { lane_index: laneIndex, maneuver }));
continue;
}
const placement = resolvedPlacement || fallbackLanePlacement(endpoint, direction, laneIndex, options.crosswalkStripes, options.stopLines);
if (!placement) {
diagnostics.push(skip(way, direction, "no_safe_turn_arrow_position", { lane_index: laneIndex, maneuver }));
continue;
}
const parts = templateFor(asset.id, options.manifest);
for (let partIndex = 0; partIndex < parts.length; partIndex += 1) {
features.push(makeFeature(way, direction, laneIndex, maneuver, asset, partIndex, parts[partIndex], placement.center, placement));
}
}
}
}
return { features, diagnostics };
}
function normalizeManeuver(value) {
const parts = String(value || "").split(";").map((part) => part.trim()).filter(Boolean).sort();
const supported = new Map([
["through", "through"], ["left", "left"], ["right", "right"],
["left;through", "through;left"], ["right;through", "through;right"],
["left;right;through", "through;left;right"],
]);
return supported.get(parts.join(";")) || parts.join(";");
}
function directionalLaneCount(way, direction) {
const specific = Number(way.tags[`lanes:${direction}`]);
if (Number.isInteger(specific) && specific > 0) return specific;
const total = Number(way.tags.lanes);
if (Number.isInteger(total) && total > 0 && total % 2 === 0 && !isOneway(way)) return total / 2;
if (Number.isInteger(total) && total > 0 && isOneway(way)) return total;
return null;
}
function roadCountsByNode(osm) {
const out = new Map();
for (const way of osm.ways.values()) {
if (!way.tags.highway || way.tags.highway === "service") continue;
for (const ref of new Set(way.refs)) out.set(ref, (out.get(ref) || 0) + 1);
}
return out;
}
function endpointGeometry(osm, way, direction, roadCounts, networkIntersectionNodes) {
const forward = direction === "forward";
const endpointIndex = forward ? way.refs.length - 1 : 0;
const neighborIndex = forward ? endpointIndex - 1 : 1;
const node = osm.nodes.get(way.refs[endpointIndex]);
const neighbor = osm.nodes.get(way.refs[neighborIndex]);
if (!node || !neighbor) return null;
const networkSaysIntersection = networkIntersectionNodes && networkIntersectionNodes.size > 0 && networkIntersectionNodes.has(node.id);
if (!networkSaysIntersection && (roadCounts.get(node.id) || 0) < 3) return null;
const meters = metersForLat(node.lat);
// For both directions, point from the adjacent road node to the endpoint.
// At a forward endpoint this is the OSM-way direction; at a backward
// endpoint it is the reverse OSM-way direction, i.e. the actual travel
// direction used by turn:lanes:backward.
const raw = [node.lon - neighbor.lon, node.lat - neighbor.lat];
const axis = normalizeMetersVector(raw, meters);
if (!axis) return null;
return { node, axis, right: [axis[1], -axis[0]], meters };
}
function laneCenter(endpoint, direction, laneIndex, meters) {
const lateral = (laneIndex + 0.5) * LANE_WIDTH_METERS;
// The local axis always follows travel, so moving back from either endpoint
// places the marking on its approach lane before the intersection.
return addMeters([endpoint.node.lon, endpoint.node.lat], endpoint.axis, -PLACEMENT_DISTANCE_METERS, endpoint.right, lateral, meters);
}
function fallbackLanePlacement(endpoint, direction, laneIndex, crosswalkStripes, stopLines) {
const lateral = (laneIndex + 0.5) * LANE_WIDTH_METERS;
for (const distance of [PLACEMENT_DISTANCE_METERS, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42]) {
const center = addMeters([endpoint.node.lon, endpoint.node.lat], endpoint.axis, -distance, endpoint.right, lateral, endpoint.meters);
if (!nearIntersectionMarking(center, endpoint.axis, crosswalkStripes, stopLines, endpoint.meters)) {
return { center, axis: endpoint.axis, right: endpoint.right, meters: endpoint.meters, placementDistance: distance, placementSource: "osm_way_fallback" };
}
}
return null;
}
function lanePlacement(way, direction, laneIndex, endpoint, lanePolygons, crosswalkStripes, stopLines) {
if (!Array.isArray(lanePolygons)) return null;
const expectedDirection = direction === "forward" ? "Fwd" : "Back";
const directionalCandidates = lanePolygons.filter((feature) =>
feature.properties?.type === "Driving" &&
feature.properties.direction === expectedDirection
);
let candidates = directionalCandidates.filter((feature) =>
(feature.properties.osm_way_ids || []).map(Number).includes(way.id)
);
let placementSource = "driving_lane_centerline";
let spatialAnchors = null;
if (!candidates.length) {
const ranked = directionalCandidates
.map((feature) => ({ feature, anchor: spatialLaneAnchor(feature, endpoint) }))
.filter(({ anchor }) => anchor)
.filter(({ anchor }) => anchor.alignment >= SPATIAL_MATCH_MIN_ALIGNMENT && anchor.distance <= SPATIAL_MATCH_MAX_DISTANCE_METERS)
.sort((a, b) => a.anchor.distance - b.anchor.distance || a.anchor.lateral - b.anchor.lateral || Number(a.feature.properties.index) - Number(b.feature.properties.index));
if (ranked.length) {
// JOSM may split a tagged OSM way into temporary negative IDs. Those IDs
// are absent from osm2streets' rendered polygons, so associate the full
// physical approach by endpoint proximity and road-axis alignment.
candidates = ranked.map(({ feature }) => feature);
placementSource = "spatial_driving_lane_centerline";
spatialAnchors = new Map(ranked.map(({ feature, anchor }) => [feature, anchor]));
}
}
candidates.sort((a, b) => {
const lateralA = spatialAnchors?.get(a)?.lateral;
const lateralB = spatialAnchors?.get(b)?.lateral;
if (Number.isFinite(lateralA) && Number.isFinite(lateralB) && lateralA !== lateralB) return lateralA - lateralB;
return Number(a.properties.index) - Number(b.properties.index);
});
const lane = candidates[laneIndex];
const spatialAnchor = spatialAnchors?.get(lane);
if (spatialAnchor) {
const sampled = placementDistances().map((distance) => ({
center: sampleCenterlineAwayFromEndpoint(spatialAnchor, distance, endpoint.meters),
distance,
})).find(({ center }) => center && !nearIntersectionMarking(center, spatialAnchor.axis, crosswalkStripes, stopLines, endpoint.meters));
if (!sampled) return { blocked: true };
return { center: sampled.center, axis: spatialAnchor.axis, right: [spatialAnchor.axis[1], -spatialAnchor.axis[0]], meters: endpoint.meters, placementDistance: sampled.distance, placementSource };
}
const centerline = laneCenterline(lane);
if (!centerline) return null;
const startsAtEndpoint = direction === "backward";
const ordered = startsAtEndpoint ? centerline : [...centerline].reverse();
const sampled = [PLACEMENT_DISTANCE_METERS, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42]
.map((distance) => ({ center: samplePolyline(ordered, distance, endpoint.meters), distance }))
.find(({ center }) => center && !nearIntersectionMarking(center, axisForLane(ordered, endpoint.meters), crosswalkStripes, stopLines, endpoint.meters));
if (!sampled) return { blocked: true };
const axis = axisForLane(ordered, endpoint.meters);
if (!axis) return null;
return { center: sampled.center, axis, right: [axis[1], -axis[0]], meters: endpoint.meters, placementDistance: sampled.distance, placementSource };
}
function spatialLaneAnchor(lane, endpoint) {
const centerline = laneCenterline(lane);
if (!centerline) return null;
let best = null;
for (let index = 0; index < centerline.length - 1; index += 1) {
const start = centerline[index];
const end = centerline[index + 1];
const point = closestPointOnSegment([endpoint.node.lon, endpoint.node.lat], start, end, endpoint.meters);
const distance = Math.hypot((point[0] - endpoint.node.lon) * endpoint.meters.lon, (point[1] - endpoint.node.lat) * endpoint.meters.lat);
const tangent = normalizeMetersVector(subtractPoint(end, start), endpoint.meters);
if (!tangent || (best && distance >= best.distance)) continue;
const dot = tangent[0] * endpoint.axis[0] + tangent[1] * endpoint.axis[1];
const axis = dot >= 0 ? tangent : [-tangent[0], -tangent[1]];
const offset = subtractPoint(point, [endpoint.node.lon, endpoint.node.lat]);
best = {
point,
distance,
axis,
alignment: Math.abs(dot),
lateral: offset[0] * endpoint.right[0] * endpoint.meters.lon + offset[1] * endpoint.right[1] * endpoint.meters.lat,
centerline,
segmentIndex: index,
};
}
return best;
}
function placementDistances() {
return [PLACEMENT_DISTANCE_METERS, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42];
}
function sampleCenterlineAwayFromEndpoint(anchor, distanceMeters, meters) {
const { centerline, segmentIndex } = anchor;
const start = centerline[segmentIndex];
const end = centerline[segmentIndex + 1];
const tangent = normalizeMetersVector(subtractPoint(end, start), meters);
if (!tangent) return null;
// Walk away from the junction along the rendered centerline. This preserves
// curved or split lane geometry instead of approximating it with a tangent.
const towardEnd = tangent[0] * anchor.axis[0] + tangent[1] * anchor.axis[1] < 0;
const points = [anchor.point];
if (towardEnd) {
for (let index = segmentIndex + 1; index < centerline.length; index += 1) points.push(centerline[index]);
} else {
for (let index = segmentIndex; index >= 0; index -= 1) points.push(centerline[index]);
}
return samplePolyline(points, distanceMeters, meters);
}
function closestPointOnSegment(point, start, end, meters) {
const dx = (end[0] - start[0]) * meters.lon;
const dy = (end[1] - start[1]) * meters.lat;
const px = (point[0] - start[0]) * meters.lon;
const py = (point[1] - start[1]) * meters.lat;
const lengthSquared = dx * dx + dy * dy;
const ratio = lengthSquared ? Math.max(0, Math.min(1, (px * dx + py * dy) / lengthSquared)) : 0;
return [start[0] + ratio * (end[0] - start[0]), start[1] + ratio * (end[1] - start[1])];
}
function axisForLane(ordered, meters) {
return normalizeMetersVector(subtractPoint(ordered[0], ordered[1]), meters);
}
function nearIntersectionMarking(center, axis, stripes, stopLines, meters) {
if (!axis) return true;
const right = [axis[1], -axis[0]];
const samples = [];
for (const forward of [-0.2, 0.5, 1.2, 1.9, 2.2]) {
for (const lateral of [-1.6, -0.8, 0, 0.8, 1.6]) {
samples.push(addMeters(center, axis, forward, right, lateral, meters));
}
}
return [...(stripes || []), ...(stopLines || [])].some((feature) => samples.some((point) => nearFeature(point, feature, meters)));
}
function nearFeature(point, feature, meters) {
const ring = feature.geometry?.type === "Polygon" ? feature.geometry.coordinates?.[0] : null;
if (!ring?.length) return false;
const xs = ring.map((coordinate) => coordinate[0]);
const ys = ring.map((coordinate) => coordinate[1]);
const clearance = 0.7;
const dx = Math.max((Math.min(...xs) - point[0]) * meters.lon, 0, (point[0] - Math.max(...xs)) * meters.lon);
const dy = Math.max((Math.min(...ys) - point[1]) * meters.lat, 0, (point[1] - Math.max(...ys)) * meters.lat);
return Math.hypot(dx, dy) < clearance;
}
function subtractPoint([lon, lat], [otherLon, otherLat]) {
return [lon - otherLon, lat - otherLat];
}
function samplePolyline(points, distanceMeters, meters) {
let remaining = distanceMeters;
for (let index = 0; index < points.length - 1; index += 1) {
const start = points[index];
const end = points[index + 1];
const vector = normalizeMetersVector(subtractPoint(end, start), meters);
const length = Math.hypot((end[0] - start[0]) * meters.lon, (end[1] - start[1]) * meters.lat);
if (!vector || !length) continue;
if (remaining <= length) return addMeters(start, vector, remaining, [0, 0], 0, meters);
remaining -= length;
}
return null;
}
function makeFeature(way, direction, laneIndex, maneuver, asset, partIndex, template, center, endpoint) {
const ring = template.map(([rightMeters, forwardMeters]) => addMeters(center, endpoint.axis, forwardMeters, endpoint.right, rightMeters, endpoint.meters));
return {
type: "Feature",
properties: {
type: "lane arrow",
source: "osm_turn_lanes",
osm_way_id: way.id,
direction,
lane_index: laneIndex,
maneuver,
source_asset: asset.id,
source_asset_path: asset.source,
arrow_part: partIndex,
// SVG strokes and fills are expanded separately for GeoJSON validity.
// This stable key lets the QGIS normalizer restore one rendered arrow.
custom_arrow_id: `${way.id}:${direction}:${laneIndex}:${maneuver}`,
placement_distance_meters: endpoint.placementDistance ?? PLACEMENT_DISTANCE_METERS,
placement_source: endpoint.placementSource ?? "osm_way_fallback",
},
geometry: { type: "Polygon", coordinates: [ring] },
};
}
function skip(way, direction, reason, extra = {}) {
return { source: "osm_turn_lanes", osm_way_id: way.id, direction, reason, ...extra };
}
function isOneway(way) {
return ["yes", "true", "1"].includes(String(way.tags.oneway || "").toLowerCase());
}
function metersForLat(lat) {
return { lon: 111320 * Math.cos((lat * Math.PI) / 180), lat: 110540 };
}
function normalizeMetersVector([dxLon, dyLat], meters) {
const x = dxLon * meters.lon;
const y = dyLat * meters.lat;
const length = Math.hypot(x, y);
return length ? [x / length, y / length] : null;
}
function addMeters(center, axis, axisDistance, right, rightDistance, meters) {
return [
center[0] + (axis[0] * axisDistance + right[0] * rightDistance) / meters.lon,
center[1] + (axis[1] * axisDistance + right[1] * rightDistance) / meters.lat,
];
}
function arrowRingsAt(maneuver, center, axis, manifest = loadManifest()) {
const normalized = normalizeManeuver(maneuver);
if (!supportedAssets(manifest).has(normalized) || !Array.isArray(center) || !Array.isArray(axis)) return [];
const meters = metersForLat(center[1]);
const length = Math.hypot(axis[0], axis[1]);
if (!Number.isFinite(length) || length < 0.001) return [];
const forward = [axis[0] / length, axis[1] / length];
const right = [forward[1], -forward[0]];
return templateFor(normalized, manifest).map((template) => template.map(([rightMeters, forwardMeters]) =>
addMeters(center, forward, forwardMeters, right, rightMeters, meters)));
}
function templateFor(assetId, manifest = loadManifest()) {
const asset = supportedAssets(manifest).get(assetId);
if (!asset) throw new Error(`Unsupported or untested turn-lane asset: ${assetId}`);
return angularTemplate(assetId);
}
function angularTemplate(assetId) {
const shaftWidth = 0.30;
const shaftHalf = shaftWidth / 2;
const straightBase = 1.18;
const straightTip = 1.92;
const rectangle = (minX, minY, maxX, maxY) => [
[minX, minY], [maxX, minY], [maxX, maxY], [minX, maxY], [minX, minY],
];
const throughHead = () => [[0, straightTip], [-0.42, straightBase], [-shaftHalf, straightBase], [-shaftHalf, 0], [shaftHalf, 0], [shaftHalf, straightBase], [0.42, straightBase], [0, straightTip]];
const diagonalShaft = (side) => {
const start = [0, 0.56];
const end = [side * 0.72, 0.96];
const length = Math.hypot(end[0] - start[0], end[1] - start[1]);
const normal = [-(end[1] - start[1]) / length * shaftHalf, (end[0] - start[0]) / length * shaftHalf];
return [[start[0] + normal[0], start[1] + normal[1]], [end[0] + normal[0], end[1] + normal[1]], [end[0] - normal[0], end[1] - normal[1]], [start[0] - normal[0], start[1] - normal[1]], [start[0] + normal[0], start[1] + normal[1]]];
};
const diagonalHead = (side) => {
const base = [side * 0.60, 0.89];
const tip = [side * 1.22, 1.24];
const length = Math.hypot(tip[0] - base[0], tip[1] - base[1]);
const normal = [-(tip[1] - base[1]) / length * 0.36, (tip[0] - base[0]) / length * 0.36];
return [tip, [base[0] + normal[0], base[1] + normal[1]], [base[0] - normal[0], base[1] - normal[1]], tip];
};
const turnStem = (side) => {
const cutMidpoint = 0.73;
const cutRise = side * 0.084;
return [
[-shaftHalf, 0], [shaftHalf, 0],
[shaftHalf, cutMidpoint + cutRise], [-shaftHalf, cutMidpoint - cutRise],
[-shaftHalf, 0],
];
};
if (assetId === "through") return [throughHead()];
if (assetId === "right") return [turnStem(1), diagonalShaft(1), diagonalHead(1)];
if (assetId === "left") return [turnStem(-1), diagonalShaft(-1), diagonalHead(-1)];
if (assetId === "through;right") return [throughHead(), diagonalShaft(1), diagonalHead(1)];
if (assetId === "through;left") return [throughHead(), diagonalShaft(-1), diagonalHead(-1)];
if (assetId === "through;left;right") return [throughHead(), diagonalShaft(-1), diagonalHead(-1), diagonalShaft(1), diagonalHead(1)];
throw new Error(`No angular turn-lane template: ${assetId}`);
}
function sourceSvgTemplateFor(asset, assetId) {
const source = fs.readFileSync(path.resolve(__dirname, "..", "..", "assets", "lane-icons", asset.source), "utf8");
const mirrorX = asset.mirror_x === true;
const anchorX = Number(asset.anchor_x);
if (!Number.isFinite(anchorX)) throw new Error(`turn-lane asset has invalid anchor_x: ${assetId}`);
const shapes = [];
for (const match of source.matchAll(/<line\b([^>]*)\/>|<path\b([^>]*)\/>/g)) {
const attrs = parseSvgAttrs(match[1] || match[2]);
const strokeWidth = Number(attrs["stroke-width"] || 0);
if (match[1]) {
shapes.push(strokePolygon([[Number(attrs.x1), Number(attrs.y1)], [Number(attrs.x2), Number(attrs.y2)]], strokeWidth));
} else {
const points = parseSvgPath(attrs.d || "");
if (attrs.fill !== "none") shapes.push(points);
if (strokeWidth > 0) shapes.push(strokePolygon(points, strokeWidth));
}
}
return shapes.filter((ring) => ring.length >= 4).map((ring) => ring.map(([x, y]) => [
(mirrorX ? anchorX - x : x - anchorX) * SVG_METERS_PER_UNIT,
(23 - y) * SVG_METERS_PER_UNIT,
]));
}
function parseSvgAttrs(text) {
const attrs = {};
for (const match of text.matchAll(/([\w:-]+)=(['"])(.*?)\2/g)) attrs[match[1]] = match[3];
return attrs;
}
function parseSvgPath(value) {
const tokens = value.match(/[a-zA-Z]|[-+]?(?:\d*\.\d+|\d+\.?)(?:[eE][-+]?\d+)?/g) || [];
let index = 0;
let command = "";
let point = [0, 0];
let start = null;
const points = [];
const number = () => Number(tokens[index++]);
const lineTo = (x, y) => { point = [x, y]; points.push(point); };
while (index < tokens.length) {
if (/^[a-zA-Z]$/.test(tokens[index])) command = tokens[index++];
const relative = command === command.toLowerCase();
const op = command.toUpperCase();
if (op === "Z") { if (start) points.push(start); command = ""; continue; }
if (op === "M" || op === "L") {
const x = number(); const y = number();
const next = relative ? [point[0] + x, point[1] + y] : [x, y];
if (op === "M" && !start) { start = next; point = next; points.push(point); command = relative ? "l" : "L"; } else lineTo(...next);
continue;
}
if (op === "H") { lineTo(relative ? point[0] + number() : number(), point[1]); continue; }
if (op === "V") { lineTo(point[0], relative ? point[1] + number() : number()); continue; }
if (op === "C") {
const values = [number(), number(), number(), number(), number(), number()];
const controls = relative ? values.map((n, i) => n + point[i % 2]) : values;
const origin = point;
for (let step = 1; step <= 8; step += 1) {
const t = step / 8; const u = 1 - t;
lineTo(u ** 3 * origin[0] + 3 * u ** 2 * t * controls[0] + 3 * u * t ** 2 * controls[2] + t ** 3 * controls[4], u ** 3 * origin[1] + 3 * u ** 2 * t * controls[1] + 3 * u * t ** 2 * controls[3] + t ** 3 * controls[5]);
}
continue;
}
if (op === "A") { number(); number(); number(); number(); number(); const x = number(); const y = number(); lineTo(relative ? point[0] + x : x, relative ? point[1] + y : y); continue; }
throw new Error(`Unsupported SVG path command: ${command}`);
}
return points;
}
function strokePolygon(points, width) {
if (points.length < 2) return [];
const half = width / 2;
const left = []; const right = [];
for (let index = 0; index < points.length; index += 1) {
const prev = points[Math.max(0, index - 1)];
const next = points[Math.min(points.length - 1, index + 1)];
const dx = next[0] - prev[0]; const dy = next[1] - prev[1]; const length = Math.hypot(dx, dy) || 1;
const nx = -dy / length * half; const ny = dx / length * half;
left.push([points[index][0] + nx, points[index][1] + ny]);
right.unshift([points[index][0] - nx, points[index][1] - ny]);
}
return [...left, ...right, left[0]];
}
module.exports = { arrowRingsAt, buildCustomTurnLaneArrows, loadManifest, normalizeManeuver, supportedAssets, templateFor };
@@ -1,161 +0,0 @@
"use strict";
const EARTH_RADIUS_METERS = 6371008.8;
function laneCenterline(lane) {
const ring = lane?.geometry?.type === "Polygon" ? lane.geometry.coordinates?.[0] : null;
if (!Array.isArray(ring) || ring.length < 5 || !sameCoordinate(ring[0], ring.at(-1))) return null;
const vertices = ring.slice(0, -1);
if (!vertices.every(validCoordinate)) return null;
const half = vertices.length / 2;
if (!Number.isInteger(half) || half < 2) return null;
const centerline = vertices.slice(0, half).map((point, index) => [
(point[0] + vertices[vertices.length - 1 - index][0]) / 2,
(point[1] + vertices[vertices.length - 1 - index][1]) / 2,
]);
return polylineLength(centerline) > 0.01 ? centerline : null;
}
function orientPolyline(polyline, reference) {
if (!polyline?.length || !reference?.length) return null;
const forward = projectedDistanceAlong(reference, polyline.at(-1)) - projectedDistanceAlong(reference, polyline[0]);
if (Math.abs(forward) < 0.01) return null;
return forward > 0 ? polyline.map(copyCoordinate) : [...polyline].reverse().map(copyCoordinate);
}
function stitchPolylines(polylines, maxGapMeters) {
if (!polylines.length) return null;
const result = [];
for (const polyline of polylines) {
if (!polyline?.length) return null;
if (result.length && haversineMeters(result.at(-1), polyline[0]) > maxGapMeters) return null;
appendCoordinates(result, polyline);
}
return result;
}
function projectedDistanceAlong(polyline, point) {
let traversed = 0;
let best = { distance: Infinity, along: 0, lateral: 0 };
for (let index = 1; index < polyline.length; index += 1) {
const start = polyline[index - 1];
const end = polyline[index];
const meters = metersAt((start[1] + end[1]) / 2);
const dx = (end[0] - start[0]) * meters.lon;
const dy = (end[1] - start[1]) * meters.lat;
const px = (point[0] - start[0]) * meters.lon;
const py = (point[1] - start[1]) * meters.lat;
const length = Math.hypot(dx, dy);
if (length < 0.001) continue;
const ratio = Math.max(0, Math.min(1, (px * dx + py * dy) / (length * length)));
const offsetX = px - dx * ratio;
const offsetY = py - dy * ratio;
const distance = Math.hypot(offsetX, offsetY);
if (distance < best.distance) {
const rightX = dy / length;
const rightY = -dx / length;
best = {
distance,
along: traversed + length * ratio,
lateral: offsetX * rightX + offsetY * rightY,
};
}
traversed += length;
}
return best.along;
}
function lateralOffsetFrom(polyline, point) {
let best = null;
for (let index = 1; index < polyline.length; index += 1) {
const start = polyline[index - 1];
const end = polyline[index];
const meters = metersAt((start[1] + end[1]) / 2);
const dx = (end[0] - start[0]) * meters.lon;
const dy = (end[1] - start[1]) * meters.lat;
const px = (point[0] - start[0]) * meters.lon;
const py = (point[1] - start[1]) * meters.lat;
const length = Math.hypot(dx, dy);
if (length < 0.001) continue;
const ratio = Math.max(0, Math.min(1, (px * dx + py * dy) / (length * length)));
const offsetX = px - dx * ratio;
const offsetY = py - dy * ratio;
const distance = Math.hypot(offsetX, offsetY);
if (!best || distance < best.distance) {
best = { distance, lateral: offsetX * dy / length - offsetY * dx / length };
}
}
return best;
}
function polylineMidpoint(polyline) {
const target = polylineLength(polyline) / 2;
let traversed = 0;
for (let index = 1; index < polyline.length; index += 1) {
const length = haversineMeters(polyline[index - 1], polyline[index]);
if (traversed + length >= target) {
const ratio = length ? (target - traversed) / length : 0;
return [
polyline[index - 1][0] + (polyline[index][0] - polyline[index - 1][0]) * ratio,
polyline[index - 1][1] + (polyline[index][1] - polyline[index - 1][1]) * ratio,
];
}
traversed += length;
}
return polyline.length ? copyCoordinate(polyline.at(-1)) : null;
}
function polylineLength(polyline) {
let total = 0;
for (let index = 1; index < (polyline?.length || 0); index += 1) {
total += haversineMeters(polyline[index - 1], polyline[index]);
}
return total;
}
function haversineMeters(a, b) {
const lat1 = degreesToRadians(a[1]);
const lat2 = degreesToRadians(b[1]);
const dLat = degreesToRadians(b[1] - a[1]);
const dLon = degreesToRadians(b[0] - a[0]);
const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
return 2 * EARTH_RADIUS_METERS * Math.asin(Math.min(1, Math.sqrt(h)));
}
function appendCoordinates(target, coordinates) {
for (const coordinate of coordinates) {
if (!sameCoordinate(target.at(-1), coordinate)) target.push(copyCoordinate(coordinate));
}
}
function validCoordinate(value) {
return Array.isArray(value) && value.length >= 2 && Number.isFinite(value[0]) && Number.isFinite(value[1]);
}
function sameCoordinate(a, b) {
return Boolean(a && b && a[0] === b[0] && a[1] === b[1]);
}
function copyCoordinate(coordinate) {
return [coordinate[0], coordinate[1]];
}
function metersAt(latitude) {
return { lon: 111320 * Math.cos(degreesToRadians(latitude)), lat: 111320 };
}
function degreesToRadians(value) {
return value * Math.PI / 180;
}
module.exports = {
appendCoordinates,
haversineMeters,
laneCenterline,
lateralOffsetFrom,
orientPolyline,
polylineLength,
polylineMidpoint,
projectedDistanceAlong,
stitchPolylines,
};
-14
View File
@@ -1,14 +0,0 @@
"use strict";
module.exports = {
laneGeometry: require("./geometry/lane-geometry"),
gaodeReference: require("./reference/gaode"),
turnLaneArrows: require("./compile/turn-lane-arrows"),
complexJunction: require("./compile/complex-junction"),
osm: require("./osm"),
trafficSignals: require("./traffic-signals"),
nativeTrafficSignals: require("./native-traffic-signals"),
nativeRoad: require("./compile/native-road"),
compiler: require("./compile/compiler"),
check: require("./check"),
};
@@ -1,49 +0,0 @@
"use strict";
const fs = require("fs");
const { parseOsm } = require("./osm");
const {
buildTrafficSignalFeatures,
buildTrafficSignalsFromFeatures,
validateTrafficSignalFeatures,
validateTrafficSignalSourceReferences,
} = require("./traffic-signals");
const SCHEMA = "native-traffic-signals/v1";
function loadOrGenerate(file, osmText, stopLines, intersections) {
if (fs.existsSync(file)) {
const document = JSON.parse(fs.readFileSync(file, "utf8"));
try {
return validateDocument(document, osmText);
} catch (error) {
// OSM edits can invalidate the stable identities in a document that was
// itself generated from OSM. User-authored documents must remain strict.
if (document?.provenance === "generated:osm-controls" && isStaleSourceReferenceError(error)) {
return generate(osmText, stopLines, intersections);
}
throw error;
}
}
return generate(osmText, stopLines, intersections);
}
function isStaleSourceReferenceError(error) {
return error instanceof Error && /^traffic signal feature \d+: (approach_id .* is not present on OSM control|control_id .* is not present in the current OSM)/.test(error.message);
}
function generate(osmText, stopLines, intersections) {
const controls = parseOsm(osmText).trafficSignalControls;
return { schema: SCHEMA, provenance: "generated:osm-controls", assemblies: buildTrafficSignalFeatures(stopLines, intersections, controls) };
}
function validateDocument(value, osmText) {
if (value?.schema !== SCHEMA) throw new Error(`Expected ${SCHEMA} signal document`);
const assemblies = validateTrafficSignalFeatures(value.assemblies);
if (osmText) validateTrafficSignalSourceReferences(assemblies, parseOsm(osmText).trafficSignalControls);
return { schema: SCHEMA, provenance: value.provenance || "native", assemblies };
}
function runtime(document) { return buildTrafficSignalsFromFeatures(document.assemblies); }
module.exports = { SCHEMA, generate, loadOrGenerate, validateDocument, runtime };
-102
View File
@@ -1,102 +0,0 @@
"use strict";
function parseOsm(xml) {
const boundsMatch = xml.match(/<bounds\b([^>]*)\/?\s*>/);
const boundsAttrs = boundsMatch ? xmlAttrs(boundsMatch[1]) : {};
const candidateBounds = {
minLon: Number(boundsAttrs.minlon), minLat: Number(boundsAttrs.minlat),
maxLon: Number(boundsAttrs.maxlon), maxLat: Number(boundsAttrs.maxlat),
};
const bounds = Object.values(candidateBounds).every(Number.isFinite) ? candidateBounds : null;
const nodes = new Map();
const trafficSignalControls = [];
const nodePattern = /<node\b([^>]*?)(?:\/>|>([\s\S]*?)<\/node>)/g;
for (const match of xml.matchAll(nodePattern)) {
const attrs = xmlAttrs(match[1]);
if (attrs.action === "delete" || !attrs.id || attrs.lon === undefined || attrs.lat === undefined) continue;
const coordinate = [Number(attrs.lon), Number(attrs.lat)];
if (!coordinate.every(Number.isFinite)) continue;
nodes.set(attrs.id, coordinate);
const tags = parseTags(match[2] || "");
if (tags.highway === "traffic_signals") {
trafficSignalControls.push({ id: attrs.id, longitude: coordinate[0], latitude: coordinate[1], tags });
}
}
const ways = [];
for (const match of xml.matchAll(/<way\b([^>]*)>([\s\S]*?)<\/way>/g)) {
const attrs = xmlAttrs(match[1]);
if (attrs.action === "delete") continue;
const body = match[2];
const refs = [];
for (const ndMatch of body.matchAll(/<nd\b([^>]*)\/?\s*>/g)) {
const ref = xmlAttrs(ndMatch[1]).ref;
if (ref && nodes.has(ref)) refs.push(ref);
}
if (refs.length >= 2) ways.push({ id: attrs.id || `way-${ways.length + 1}`, refs, tags: parseTags(body) });
}
for (const control of trafficSignalControls) {
const arms = [];
for (const way of ways) {
if (!isMotorRoad(way.tags)) continue;
for (let index = 0; index < way.refs.length; index += 1) {
if (way.refs[index] !== control.id) continue;
for (const neighborIndex of [index - 1, index + 1]) {
const neighbor = way.refs[neighborIndex];
if (!neighbor || !nodes.has(neighbor)) continue;
const neighborPoint = nodes.get(neighbor);
arms.push({
headingDegrees: headingBetween(control, neighborPoint),
wayId: String(way.id),
neighborNodeId: String(neighbor),
});
}
}
}
control.arms = dedupeHeadings(arms);
control.junctionType = control.arms.length === 3 ? "T" : control.arms.length === 4 ? "cross" : "other";
}
return { bounds, nodes, ways, trafficSignalControls };
}
function isMotorRoad(tags) {
const highway = tags.highway || "";
return highway && tags.area !== "yes" && !new Set([
"footway", "path", "pedestrian", "steps", "cycleway", "service", "track",
"bridleway", "corridor", "elevator", "platform", "construction",
]).has(highway);
}
function headingBetween(from, to) {
const latitude = (from.latitude + to[1]) / 2 * Math.PI / 180;
return Math.atan2((to[0] - from.longitude) * Math.cos(latitude), to[1] - from.latitude) * 180 / Math.PI;
}
function dedupeHeadings(arms) {
const normalized = (value) => ((value % 360) + 360) % 360;
const distance = (a, b) => Math.abs(((a - b + 540) % 360) - 180);
const result = [];
for (const arm of arms) {
arm.headingDegrees = normalized(arm.headingDegrees);
if (!result.some((other) => distance(other.headingDegrees, arm.headingDegrees) <= 25)) result.push(arm);
}
return result.sort((a, b) => a.headingDegrees - b.headingDegrees);
}
function xmlAttrs(text) {
const attrs = {};
for (const match of text.matchAll(/([:\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
attrs[match[1]] = match[2] !== undefined ? match[2] : match[3];
}
return attrs;
}
function parseTags(body) {
const tags = {};
for (const match of body.matchAll(/<tag\b([^>]*)\/?\s*>/g)) {
const tag = xmlAttrs(match[1]);
if (tag.k) tags[tag.k] = tag.v || "";
}
return tags;
}
module.exports = { parseOsm };
@@ -1,231 +0,0 @@
"use strict";
const fs = require("fs");
const PI = Math.PI;
const EARTH_A = 6378245.0;
const EARTH_EE = 0.00669342162296594323;
function transformLat(x, y) {
let value = -100 + 2 * x + 3 * y + 0.2 * y * y + 0.1 * x * y + 0.2 * Math.sqrt(Math.abs(x));
value += (20 * Math.sin(6 * x * PI) + 20 * Math.sin(2 * x * PI)) * 2 / 3;
value += (20 * Math.sin(y * PI) + 40 * Math.sin(y / 3 * PI)) * 2 / 3;
value += (160 * Math.sin(y / 12 * PI) + 320 * Math.sin(y * PI / 30)) * 2 / 3;
return value;
}
function transformLon(x, y) {
let value = 300 + x + 2 * y + 0.1 * x * x + 0.1 * x * y + 0.1 * Math.sqrt(Math.abs(x));
value += (20 * Math.sin(6 * x * PI) + 20 * Math.sin(2 * x * PI)) * 2 / 3;
value += (20 * Math.sin(x * PI) + 40 * Math.sin(x / 3 * PI)) * 2 / 3;
value += (150 * Math.sin(x / 12 * PI) + 300 * Math.sin(x / 30 * PI)) * 2 / 3;
return value;
}
// This is the standard local inverse approximation used for GCJ-02 reference
// data. It is intentionally kept separate from native road geometry, whose
// source coordinates remain WGS84.
function gcj02ToWgs84(coordinate) {
const [longitude, latitude] = coordinate;
if (!Number.isFinite(longitude) || !Number.isFinite(latitude)) throw new Error("Reference coordinate must be finite");
const dLat = transformLat(longitude - 105, latitude - 35);
const dLon = transformLon(longitude - 105, latitude - 35);
const radLat = latitude / 180 * PI;
const magic = 1 - EARTH_EE * Math.sin(radLat) ** 2;
const sqrtMagic = Math.sqrt(magic);
return [
longitude - dLon * 180 / (EARTH_A / sqrtMagic * Math.cos(radLat) * PI),
latitude - dLat * 180 / (EARTH_A * (1 - EARTH_EE) / (magic * sqrtMagic) * PI),
];
}
function mapCoordinates(coordinates, mapper) {
if (typeof coordinates[0] === "number") return mapper(coordinates);
return coordinates.map((value) => mapCoordinates(value, mapper));
}
function convertGeoJson(document) {
if (!document || document.type !== "FeatureCollection" || !Array.isArray(document.features)) {
throw new Error("Reference must be a GeoJSON FeatureCollection");
}
return {
...document,
crs: undefined,
features: document.features.map((feature) => {
if (!feature || !feature.geometry || !feature.geometry.coordinates) throw new Error("Reference feature is missing geometry");
return { ...feature, geometry: { ...feature.geometry, coordinates: mapCoordinates(feature.geometry.coordinates, gcj02ToWgs84) } };
}),
};
}
function coordinatesOf(document) {
const points = [];
for (const feature of document.features || []) walkCoordinates(feature.geometry?.coordinates, points);
return points;
}
function walkCoordinates(value, points) {
if (!Array.isArray(value) || !value.length) return;
if (typeof value[0] === "number") {
points.push(value);
return;
}
for (const child of value) walkCoordinates(child, points);
}
function boundsOf(document) {
const points = coordinatesOf(document);
if (!points.length) throw new Error("Reference contains no coordinates");
return {
minLon: Math.min(...points.map((point) => point[0])),
minLat: Math.min(...points.map((point) => point[1])),
maxLon: Math.max(...points.map((point) => point[0])),
maxLat: Math.max(...points.map((point) => point[1])),
};
}
function centerOf(bounds) {
return [(bounds.minLon + bounds.maxLon) / 2, (bounds.minLat + bounds.maxLat) / 2];
}
function distanceMeters(first, second) {
const lonScale = 111320 * Math.cos(first[1] * PI / 180);
return Math.hypot((second[0] - first[0]) * lonScale, (second[1] - first[1]) * 111320);
}
function parseOsmNodes(xml) {
const nodes = [];
for (const match of xml.matchAll(/<node\b([^>]*?)(?:\/>|>([\s\S]*?)<\/node>)/g)) {
const attrs = {};
for (const item of match[1].matchAll(/([:\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) attrs[item[1]] = item[2] ?? item[3];
if (!attrs.id || !Number.isFinite(Number(attrs.lon)) || !Number.isFinite(Number(attrs.lat))) continue;
const tags = {};
for (const item of (match[2] || "").matchAll(/<tag\b([^>]*)\/?\s*>/g)) {
const tag = {};
for (const attr of item[1].matchAll(/([:\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) tag[attr[1]] = attr[2] ?? attr[3];
if (tag.k) tags[tag.k] = tag.v || "";
}
nodes.push({ id: String(attrs.id), coordinate: [Number(attrs.lon), Number(attrs.lat)], tags });
}
return nodes;
}
function nearestNode(nodes, coordinate, nodeId) {
if (nodeId) {
const exact = nodes.find((node) => node.id === String(nodeId));
if (!exact) throw new Error(`OSM node not found: ${nodeId}`);
return { ...exact, distanceMeters: distanceMeters(exact.coordinate, coordinate), match: "node-id" };
}
const candidates = nodes.map((node) => ({ ...node, distanceMeters: distanceMeters(node.coordinate, coordinate) }));
candidates.sort((first, second) => first.distanceMeters - second.distanceMeters);
if (!candidates[0]) throw new Error("OSM contains no usable nodes");
return { ...candidates[0], match: "nearest-node" };
}
function bboxIntersectionRatio(first, second) {
const width = Math.max(0, Math.min(first.maxLon, second.maxLon) - Math.max(first.minLon, second.minLon));
const height = Math.max(0, Math.min(first.maxLat, second.maxLat) - Math.max(first.minLat, second.minLat));
const intersection = width * height;
const firstArea = Math.max(0, first.maxLon - first.minLon) * Math.max(0, first.maxLat - first.minLat);
const secondArea = Math.max(0, second.maxLon - second.minLon) * Math.max(0, second.maxLat - second.minLat);
return intersection / Math.max(firstArea + secondArea - intersection, Number.EPSILON);
}
// A complex junction is compiled as one cluster of `complex_part` polygons in
// road_surface.geojson, not as a per-node feature in intersection_surface.
// Match it by cluster id, or by whichever cluster core sits nearest the node.
function complexClusterSurface(nativeRoadSurfaceFile, node, clusterId) {
if (!nativeRoadSurfaceFile || !fs.existsSync(nativeRoadSurfaceFile)) return null;
const surface = JSON.parse(fs.readFileSync(nativeRoadSurfaceFile, "utf8"));
const parts = (surface.features || []).filter((item) => item.properties?.cluster_id && item.properties?.complex_part);
const cores = parts.filter((item) => item.properties.complex_part === "core" && Array.isArray(item.properties.center));
if (!cores.length) return null;
const core = clusterId
? cores.find((item) => String(item.properties.cluster_id) === String(clusterId))
: [...cores].sort((first, second) => distanceMeters(first.properties.center, node.coordinate) - distanceMeters(second.properties.center, node.coordinate))[0];
if (!core) return null;
const features = parts.filter((item) => item.properties.cluster_id === core.properties.cluster_id);
return { clusterId: core.properties.cluster_id, core, features };
}
function inspectReference({ referenceFile, osmFile, nativeIntersectionFile, nativeRoadSurfaceFile, nodeId, clusterId }) {
const source = JSON.parse(fs.readFileSync(referenceFile, "utf8"));
const converted = convertGeoJson(source);
const referenceBounds = boundsOf(converted);
const referenceCenter = centerOf(referenceBounds);
const nodes = parseOsmNodes(fs.readFileSync(osmFile, "utf8"));
const matchedNode = nearestNode(nodes, referenceCenter, nodeId);
const native = JSON.parse(fs.readFileSync(nativeIntersectionFile, "utf8"));
const feature = (native.features || []).find((item) => item.properties?.osm_node_id === matchedNode.id);
const cluster = feature ? null : complexClusterSurface(nativeRoadSurfaceFile, matchedNode, clusterId);
const matchedFeatures = feature ? [feature] : cluster?.features || null;
const nativeBounds = matchedFeatures ? boundsOf({ features: matchedFeatures }) : null;
const diagnostics = [];
if (!matchedFeatures) diagnostics.push(nativeRoadSurfaceFile ? "No native intersection surface or complex cluster matched the OSM node" : "No native intersection surface matched the OSM node; pass --native-road-surface to also search complex junction clusters");
return {
schema: "gaode-junction-reference-comparison/v2",
source: { file: referenceFile, coordinateSystem: "GCJ-02", featureCount: converted.features.length },
conversion: { target: "WGS84", method: "gcj02-inverse-approximation" },
reference: { bounds: referenceBounds, center: referenceCenter },
matchedOsmNode: { id: matchedNode.id, coordinate: matchedNode.coordinate, tags: matchedNode.tags, match: matchedNode.match, centerDistanceMeters: matchedNode.distanceMeters },
nativeIntersection: nativeBounds ? {
kind: feature ? "junction-node" : "complex-cluster",
clusterId: cluster?.clusterId || null,
featureCount: matchedFeatures.length,
bounds: nativeBounds,
bboxIoU: bboxIntersectionRatio(referenceBounds, nativeBounds),
centerOffsetMeters: distanceMeters(referenceCenter, centerOf(nativeBounds)),
featureProperties: feature ? feature.properties : cluster.core.properties,
} : null,
diagnostics,
converted,
matchedFeatures,
};
}
function localReferenceSvg({ converted, nativeIntersection, center, radiusMeters = 180 }) {
const width = 1000;
const height = 1000;
const lonScale = 111320 * Math.cos(center[1] * PI / 180);
const project = (point) => [
width / 2 + (point[0] - center[0]) * lonScale * width / (radiusMeters * 2),
height / 2 - (point[1] - center[1]) * 111320 * height / (radiusMeters * 2),
];
const pathFor = (coordinates) => {
const parts = [];
const appendLine = (line, close) => {
if (!line?.length) return;
const [firstX, firstY] = project(line[0]);
parts.push(`M ${firstX.toFixed(1)} ${firstY.toFixed(1)}`);
for (const point of line.slice(1)) {
const [x, y] = project(point);
parts.push(`L ${x.toFixed(1)} ${y.toFixed(1)}`);
}
if (close) parts.push("Z");
};
const visit = (value) => {
if (!Array.isArray(value) || !value.length) return;
if (typeof value[0] === "number") return;
if (typeof value[0][0] === "number") appendLine(value, value.length > 2);
else value.forEach(visit);
};
visit(coordinates);
return parts.join(" ");
};
const color = { 1: "#2563eb", 2: "#0f766e", 3: "#7c3aed", 4: "#ea580c", 5: "#64748b" };
const references = converted.features.map((feature) => {
const type = feature.properties?.type || "unknown";
return `<path d="${pathFor(feature.geometry.coordinates)}" fill="${feature.geometry.type.includes("Polygon") ? `${color[type] || "#334155"}18` : "none"}" stroke="${color[type] || "#334155"}" stroke-width="1.2"/>`;
}).join("\n");
const nativePaths = (nativeIntersection?.features || []).map((feature) => `<path d="${pathFor(feature.geometry.coordinates)}" fill="#dc262655" stroke="#dc2626" stroke-width="3"/>`).join("\n");
return `<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
<rect width="100%" height="100%" fill="#f8fafc"/>
${references}
${nativePaths}
<circle cx="${width / 2}" cy="${height / 2}" r="5" fill="#111827"/>
<text x="20" y="35" font-family="sans-serif" font-size="22" fill="#111827">Gaode reference (type colors) / native intersection (red)</text>
</svg>`;
}
module.exports = { gcj02ToWgs84, convertGeoJson, boundsOf, parseOsmNodes, nearestNode, inspectReference, localReferenceSvg };
@@ -1,330 +0,0 @@
"use strict";
const fs = require("fs");
const crypto = require("crypto");
const { parseOsm } = require("./osm");
const EARTH_RADIUS = 6371008.8;
const CURB_OFFSET_METERS = 5.2;
const MAST_REACH_METERS = 4.5;
const SIGNAL_LAYOUT = Object.freeze({
poleHeightMeters: 6.7, poleRadiusMeters: 0.13, armWidthMeters: 0.21,
mastHeightMeters: 6.25, headCenterHeightMeters: 6.25,
headWidthMeters: 0.68, headDepthMeters: 0.30, headBodyHeightMeters: 1.62,
lensRadiusMeters: 0.22, lensDepthMeters: 0.07, lensFaceOffsetMeters: 0.18,
lensVerticalOffsetsMeters: [0.49, -0.01, -0.51],
countdownLateralMeters: 1.15, countdownFaceOffsetMeters: 0.05,
countdownWidthMeters: 0.82, countdownDepthMeters: 0.14,
countdownHeightMeters: 0.56, countdownVerticalOffsetMeters: 0.0,
});
function buildTrafficSignalFeatures(stopLines, intersections, controls = []) {
const centers = (intersections.features || []).map((feature, index) => {
const point = polygonCenter(feature.geometry);
return { id: `intersection-${index + 1}`, point, radius: polygonRadius(feature.geometry, point) };
}).filter((entry) => entry.point);
const clusteredStops = new Map();
for (const feature of stopLines.features || []) {
const clusterId = feature.properties?.cluster_id;
const point = polygonCenter(feature.geometry);
if (!clusterId || !point) continue;
if (!clusteredStops.has(clusterId)) clusteredStops.set(clusterId, []);
clusteredStops.get(clusterId).push(point);
}
for (const [clusterId, points] of clusteredStops) {
if (points.length < 3) continue;
const point = points.reduce((sum, item) => [sum[0] + item[0] / points.length, sum[1] + item[1] / points.length], [0, 0]);
centers.push({ id: `cluster-${clusterId}`, clusterId, point, radius: Math.max(...points.map((item) => metersBetween(point, item))) });
}
const candidates = [];
for (const feature of stopLines.features || []) {
const center = polygonCenter(feature.geometry);
if (!center) continue;
const clusterId = feature.properties?.cluster_id;
const intersection = clusterId ? centers.find((entry) => entry.clusterId === clusterId) : nearestCenter(center, centers);
if (!intersection || metersBetween(center, intersection.point) > 32) continue;
const axis = roadAxis(feature.geometry, center, intersection.point);
if (!axis) continue;
const right = [axis[1], -axis[0]];
candidates.push({
intersectionId: intersection.id, center, axis,
point: intersection.clusterId
? moveMeters(center, right, CURB_OFFSET_METERS)
: moveMeters(moveMeters(intersection.point, axis, intersection.radius + 3.2), right, CURB_OFFSET_METERS),
headingDegrees: normalizeDegrees(Math.atan2(axis[0], axis[1]) * 180 / Math.PI),
matchHeadingDegrees: intersection.clusterId
? normalizeDegrees(Math.atan2(-axis[0], -axis[1]) * 180 / Math.PI)
: null,
});
}
const features = [];
for (const control of controls) {
const controlPoint = [Number(control.longitude), Number(control.latitude)];
if (!controlPoint.every(Number.isFinite) || !Array.isArray(control.arms) || control.arms.length < 3) continue;
const intersection = nearestCenter(controlPoint, centers);
if (!intersection || metersBetween(controlPoint, intersection.point) > 32) continue;
const arms = matchOsmArms(candidates.filter((item) => item.intersectionId === intersection.id), controlPoint, control.arms);
const groups = phaseGroups(arms);
arms.forEach((candidate, index) => {
const fallbackArmId = `heading-${Math.round(normalizeDegrees(candidate.osmArm?.headingDegrees || 0) * 1000)}`;
const sourceWayId = String(candidate.osmArm?.wayId || "legacy");
const neighborNodeId = String(candidate.osmArm?.neighborNodeId || fallbackArmId);
const approachId = `${sourceWayId}:${neighborNodeId}`;
const signalUid = `osm-${String(control.id)}-${sourceWayId}-${neighborNodeId}`;
features.push({
type: "Feature",
geometry: { type: "Point", coordinates: candidate.point.slice() },
properties: {
signal_uid: signalUid, display_id: signalUid, control_id: String(control.id),
approach_id: approachId, source_way_id: sourceWayId,
// These are independent assembly controls. heading_deg remains a
// migration hint for older native documents only.
mast_heading_deg: normalizeDegrees(candidate.headingDegrees - 90),
face_heading_deg: normalizeDegrees(candidate.headingDegrees + 180),
phase_group: groups[index],
mast_reach_m: MAST_REACH_METERS,
stop_lon: candidate.center[0], stop_lat: candidate.center[1],
enabled: true, z_offset_m: 0,
},
});
});
}
return validateTrafficSignalFeatures({ type: "FeatureCollection", features });
}
function validateTrafficSignalFeatures(collection) {
if (collection?.type !== "FeatureCollection" || !Array.isArray(collection.features)) {
throw new Error("Traffic signal assemblies must be a FeatureCollection");
}
const uids = new Set();
const displayIds = new Set();
const features = collection.features.map((feature, index) => {
const label = `traffic signal feature ${index + 1}`;
if (feature?.geometry?.type !== "Point" || !Array.isArray(feature.geometry.coordinates) ||
feature.geometry.coordinates.length < 2 || !feature.geometry.coordinates.slice(0, 2).every(Number.isFinite)) {
throw new Error(`${label}: geometry must be a finite Point`);
}
const input = feature.properties || {};
const text = (key, required = true) => {
const value = input[key] == null ? "" : String(input[key]).trim();
if (required && !value) throw new Error(`${label}: missing ${key}`);
return value;
};
const number = (key, options = {}) => {
if (input[key] === null || input[key] === undefined || input[key] === "") {
throw new Error(`${label}: missing ${key}`);
}
const value = Number(input[key]);
if (!Number.isFinite(value) || (options.min != null && value < options.min) || (options.max != null && value > options.max)) {
throw new Error(`${label}: invalid ${key} '${input[key]}'`);
}
return value;
};
const signalUid = text("signal_uid");
if (!/^osm-[A-Za-z0-9_.:-]+$/.test(signalUid)) throw new Error(`${label}: invalid signal_uid '${signalUid}'`);
if (uids.has(signalUid)) throw new Error(`Duplicate signal_uid '${signalUid}'`);
uids.add(signalUid);
const displayId = text("display_id", false);
if (displayId && displayIds.has(displayId)) throw new Error(`Duplicate display_id '${displayId}'`);
if (displayId) displayIds.add(displayId);
const phaseGroup = number("phase_group", { min: 0, max: 1 });
if (!Number.isInteger(phaseGroup)) throw new Error(`${label}: phase_group must be 0 or 1`);
const enabled = normalizeBoolean(input.enabled, label);
const controlId = text("control_id");
const approachId = text("approach_id");
const sourceWayId = text("source_way_id");
if (!approachId.startsWith(`${sourceWayId}:`)) throw new Error(`${label}: approach_id does not match source_way_id`);
const expectedUid = `osm-${controlId}-${approachId.replace(":", "-")}`;
if (signalUid !== expectedUid) throw new Error(`${label}: signal_uid does not match source identity (expected '${expectedUid}')`);
const legacyHeading = input.heading_deg == null || input.heading_deg === "" ? null : normalizeDegrees(number("heading_deg"));
if (legacyHeading == null && (input.mast_heading_deg == null || input.mast_heading_deg === "")) {
throw new Error(`${label}: missing mast_heading_deg`);
}
if (legacyHeading == null && (input.face_heading_deg == null || input.face_heading_deg === "")) {
throw new Error(`${label}: missing face_heading_deg`);
}
const mastHeading = input.mast_heading_deg == null || input.mast_heading_deg === ""
? normalizeDegrees((legacyHeading == null ? 0 : legacyHeading) - 90)
: normalizeDegrees(number("mast_heading_deg"));
const faceHeading = input.face_heading_deg == null || input.face_heading_deg === ""
? normalizeDegrees((legacyHeading == null ? 0 : legacyHeading) + 180)
: normalizeDegrees(number("face_heading_deg"));
return {
type: "Feature",
geometry: { type: "Point", coordinates: feature.geometry.coordinates.slice(0, 2).map(Number) },
properties: {
...input, signal_uid: signalUid, display_id: displayId,
control_id: controlId, approach_id: approachId,
source_way_id: sourceWayId,
// Retain the legacy value only for migration compatibility. Runtime
// geometry is entirely defined by mast_heading_deg and face_heading_deg.
heading_deg: legacyHeading,
mast_heading_deg: mastHeading, face_heading_deg: faceHeading,
phase_group: phaseGroup, mast_reach_m: number("mast_reach_m", { min: 0.1, max: 30 }),
stop_lon: number("stop_lon", { min: -180, max: 180 }),
stop_lat: number("stop_lat", { min: -90, max: 90 }),
enabled, z_offset_m: number("z_offset_m", { min: -20, max: 100 }),
},
};
});
return { type: "FeatureCollection", features };
}
function buildTrafficSignalsFromFeatures(collection) {
const normalized = validateTrafficSignalFeatures(collection);
const signals = normalized.features.filter((feature) => feature.properties.enabled).map((feature) => {
const p = feature.properties;
const point = feature.geometry.coordinates;
const mastAxis = headingVector(p.mast_heading_deg);
return {
id: p.signal_uid, signalUid: p.signal_uid, displayId: p.display_id,
nodeKey: signalNodeKey(p.signal_uid),
controlId: p.control_id, approachId: p.approach_id, sourceWayId: p.source_way_id,
phaseGroup: p.phase_group, longitude: point[0], latitude: point[1],
stopLongitude: p.stop_lon, stopLatitude: p.stop_lat,
// Existing Blender readers require headingDegrees. It is a compatibility
// alias only; the independent mast/face fields below define all geometry.
headingDegrees: p.heading_deg == null ? p.mast_heading_deg : p.heading_deg,
mastHeadingDegrees: p.mast_heading_deg,
faceHeadingDegrees: p.face_heading_deg, mastReachMeters: p.mast_reach_m,
zOffsetMeters: p.z_offset_m,
pose: buildSignalPose(point, mastAxis, p.face_heading_deg, p.mast_reach_m, p.z_offset_m),
};
});
return { version: 3, layout: SIGNAL_LAYOUT, signals };
}
function signalNodeKey(signalUid) {
return `ts_${crypto.createHash("sha256").update(signalUid).digest("hex").slice(0, 16)}`;
}
function reconcileTrafficSignalSourceReferences(collection, controls) {
const normalized = validateTrafficSignalFeatures(collection);
const approachesByControl = new Map((controls || []).map((control) => [
String(control.id),
new Set((control.arms || []).map((arm) => `${String(arm.wayId)}:${String(arm.neighborNodeId)}`)),
]));
const kept = [];
const dropped = [];
for (const [index, feature] of normalized.features.entries()) {
const { control_id: controlId, approach_id: approachId, signal_uid: signalUid } = feature.properties;
const approaches = approachesByControl.get(controlId);
if (!approaches) {
dropped.push({ index: index + 1, signalUid, controlId, approachId, reason: "missing-control", message: `control_id '${controlId}' is not present in the current OSM` });
continue;
}
if (!approaches.has(approachId)) {
dropped.push({ index: index + 1, signalUid, controlId, approachId, reason: "missing-approach", message: `approach_id '${approachId}' is not present on OSM control '${controlId}'` });
continue;
}
kept.push(feature);
}
return { collection: { ...normalized, features: kept }, dropped };
}
function validateTrafficSignalSourceReferences(collection, controls) {
const { collection: reconciled, dropped } = reconcileTrafficSignalSourceReferences(collection, controls);
if (dropped.length) throw new Error(`traffic signal feature ${dropped[0].index}: ${dropped[0].message}`);
return reconciled;
}
function buildTrafficSignals(stopLines, intersections, controls = []) {
return buildTrafficSignalsFromFeatures(buildTrafficSignalFeatures(stopLines, intersections, controls));
}
function readTrafficSignalFeatures(stopLinePath, intersectionPath, osmPath) {
const controls = parseOsm(fs.readFileSync(osmPath, "utf8")).trafficSignalControls;
return buildTrafficSignalFeatures(
JSON.parse(fs.readFileSync(stopLinePath, "utf8")),
JSON.parse(fs.readFileSync(intersectionPath, "utf8")), controls,
);
}
function readTrafficSignals(editablePath, osmPath = null) {
const collection = JSON.parse(fs.readFileSync(editablePath, "utf8"));
if (osmPath) {
const controls = parseOsm(fs.readFileSync(osmPath, "utf8")).trafficSignalControls;
validateTrafficSignalSourceReferences(collection, controls);
}
return buildTrafficSignalsFromFeatures(collection);
}
function normalizeBoolean(value, label) {
if (value === true || value === 1 || value === "1" || String(value).toLowerCase() === "true" || String(value).toLowerCase() === "yes") return true;
if (value === false || value === 0 || value === "0" || String(value).toLowerCase() === "false" || String(value).toLowerCase() === "no") return false;
throw new Error(`${label}: invalid enabled '${value}'`);
}
function uniqueApproachArms(candidates, controlPoint) {
const sorted = candidates.map((candidate) => ({ ...candidate, armHeading: normalizeDegrees(headingBetween(controlPoint, candidate.center)), controlDistance: metersBetween(controlPoint, candidate.center) }))
.sort((a, b) => a.armHeading - b.armHeading || a.controlDistance - b.controlDistance);
const arms = [];
for (const candidate of sorted) if (!arms.some((arm) => angularDistance(arm.armHeading, candidate.armHeading) <= 25)) arms.push(candidate);
return arms;
}
function matchOsmArms(candidates, controlPoint, osmArms) {
const remaining = candidates.map((candidate) => ({ ...candidate, armHeading: candidate.matchHeadingDegrees ?? normalizeDegrees(headingBetween(controlPoint, candidate.center)) }));
if (!osmArms.length) return uniqueApproachArms(remaining, controlPoint);
return osmArms.map((osmArm) => {
let bestIndex = -1; let bestDistance = Infinity;
remaining.forEach((item, index) => {
const directedDistance = angularDistance(item.armHeading, osmArm.headingDegrees);
const distance = item.matchHeadingDegrees == null
? directedDistance
: Math.min(
angularDistance(item.matchHeadingDegrees, osmArm.headingDegrees),
angularDistance(item.matchHeadingDegrees + 180, osmArm.headingDegrees),
);
if (distance < bestDistance) { bestDistance = distance; bestIndex = index; }
});
const candidate = bestIndex >= 0 && bestDistance <= 45 ? remaining.splice(bestIndex, 1)[0] : fallbackCandidate(controlPoint, osmArm);
return { ...candidate, osmArm };
});
}
function fallbackCandidate(controlPoint, osmArm) {
const outward = headingVector(osmArm.headingDegrees); const axis = [-outward[0], -outward[1]];
const center = moveMeters(controlPoint, outward, 8); const farSide = moveMeters(controlPoint, axis, 3.2);
return { center, axis, point: moveMeters(farSide, [axis[1], -axis[0]], CURB_OFFSET_METERS), armHeading: normalizeDegrees(osmArm.headingDegrees), headingDegrees: normalizeDegrees(Math.atan2(axis[0], axis[1]) * 180 / Math.PI), fallback: true };
}
function phaseGroups(arms) {
const groups = Array(arms.length).fill(1); if (arms.length < 2) return groups;
let main = [0, 1]; let best = -1;
for (let a = 0; a < arms.length; a += 1) for (let b = a + 1; b < arms.length; b += 1) { const opposition = angularDistance(arms[a].armHeading, arms[b].armHeading); if (opposition > best) { best = opposition; main = [a, b]; } }
groups[main[0]] = 0; groups[main[1]] = 0; return groups;
}
function buildSignalPose(pole, mastAxis, faceHeadingDegrees, mastReach, zOffset = 0) {
const face = headingVector(faceHeadingDegrees);
const head = moveMeters(pole, mastAxis, mastReach);
const position = (point, height) => ({ longitude: point[0], latitude: point[1], height: height + zOffset });
const lensPoint = moveMeters(head, face, SIGNAL_LAYOUT.lensFaceOffsetMeters);
const faceRight = [-face[1], face[0]];
const board = moveMeters(moveMeters(head, faceRight, SIGNAL_LAYOUT.countdownLateralMeters), face, SIGNAL_LAYOUT.countdownFaceOffsetMeters);
return { pole: position(pole, 0), arm: { from: position(pole, SIGNAL_LAYOUT.mastHeightMeters), to: position(head, SIGNAL_LAYOUT.mastHeightMeters) }, head: { ...position(head, SIGNAL_LAYOUT.headCenterHeightMeters), faceHeadingDegrees }, lenses: ["red", "yellow", "green"].map((state, index) => ({ state, ...position(lensPoint, SIGNAL_LAYOUT.headCenterHeightMeters + SIGNAL_LAYOUT.lensVerticalOffsetsMeters[index]) })), countdown: { ...position(board, SIGNAL_LAYOUT.mastHeightMeters), faceHeadingDegrees } };
}
function polygonCenter(geometry) { const ring = geometry?.type === "Polygon" ? geometry.coordinates?.[0] : null; if (!ring || ring.length < 4) return null; const points = ring.slice(0, -1); return [points.reduce((s, p) => s + p[0], 0) / points.length, points.reduce((s, p) => s + p[1], 0) / points.length]; }
function polygonRadius(geometry, center) { const ring = geometry?.type === "Polygon" ? geometry.coordinates?.[0] : null; return ring && center ? Math.max(...ring.slice(0, -1).map((point) => metersBetween(center, point)), 0) : 0; }
function roadAxis(geometry, center, target) { const ring = geometry?.coordinates?.[0]; if (!ring || ring.length < 3) return null; let longest; for (let i = 0; i < ring.length - 1; i += 1) { const dx = (ring[i + 1][0] - ring[i][0]) * Math.cos(center[1] * Math.PI / 180); const dy = ring[i + 1][1] - ring[i][1]; const length = Math.hypot(dx, dy); if (!longest || length > longest.length) longest = { dx, dy, length }; } if (!longest?.length) return null; let axis = [-longest.dy / longest.length, longest.dx / longest.length]; const toward = [(target[0] - center[0]) * Math.cos(center[1] * Math.PI / 180), target[1] - center[1]]; if (axis[0] * toward[0] + axis[1] * toward[1] < 0) axis = [-axis[0], -axis[1]]; return axis; }
function nearestCenter(point, centers) { return centers.map((entry) => ({ ...entry, distance: metersBetween(point, entry.point) })).sort((a, b) => a.distance - b.distance)[0] || null; }
function metersBetween(a, b) { const lat = (a[1] + b[1]) / 2 * Math.PI / 180; return Math.hypot((a[0] - b[0]) * Math.cos(lat), a[1] - b[1]) * Math.PI / 180 * EARTH_RADIUS; }
function moveMeters(point, vector, meters) { const scale = 180 / Math.PI / EARTH_RADIUS; return [point[0] + vector[0] * meters * scale / Math.cos(point[1] * Math.PI / 180), point[1] + vector[1] * meters * scale]; }
function headingBetween(from, to) { const latitude = (from[1] + to[1]) / 2 * Math.PI / 180; return Math.atan2((to[0] - from[0]) * Math.cos(latitude), to[1] - from[1]) * 180 / Math.PI; }
function headingVector(degrees) { const radians = degrees * Math.PI / 180; return [Math.sin(radians), Math.cos(radians)]; }
function normalizeDegrees(value) { return ((value % 360) + 360) % 360; }
function angularDistance(a, b) { return Math.abs(((a - b + 540) % 360) - 180); }
module.exports = {
SIGNAL_LAYOUT,
signalNodeKey,
buildTrafficSignalFeatures,
validateTrafficSignalFeatures,
validateTrafficSignalSourceReferences,
buildTrafficSignalsFromFeatures,
buildTrafficSignals,
readTrafficSignalFeatures,
readTrafficSignals,
};
File diff suppressed because it is too large. Load diff
-19
View File
@@ -1,19 +0,0 @@
"use strict";
const assert = require("assert/strict");
const fs = require("fs");
const path = require("path");
const compiler = require("../src");
assert.equal(typeof compiler.laneGeometry.laneCenterline, "function");
assert.equal(typeof compiler.gaodeReference.convertGeoJson, "function");
assert.equal(typeof compiler.turnLaneArrows.buildCustomTurnLaneArrows, "function");
assert.equal(typeof compiler.complexJunction.buildComplexJunctionGeometry, "function");
assert.equal(typeof compiler.nativeRoad.compileRoadModel, "function");
assert.equal(typeof compiler.check.checkOutput, "function");
const fixture = path.join(__dirname, "fixtures", "fengshu-er-road.osm");
assert.ok(fs.existsSync(fixture));
assert.throws(() => compiler.compiler.validateInput({ id: "area" }), /RoadCompilerInput/);
const model = compiler.nativeRoad.compileRoadModel(fs.readFileSync(fixture, "utf8"), { schema: "native-road-overrides/v1", overrides: [] });
assert.equal(model.roads.length, 24);
console.log("road compiler package tests passed");
+27 -27
View File
@@ -4,7 +4,7 @@ const fs = require("fs");
const path = require("path"); const path = require("path");
const { spawnSync } = require("child_process"); const { spawnSync } = require("child_process");
const { readAreaConfig } = require("./lib/area-config"); const { readAreaConfig } = require("./lib/area-config");
const { compileArea: compileNativeRoads } = require("./compile-native-roads"); const { importNativeRoadPackage } = require("./lib/native-road-package");
const { resolveStages } = require("./lib/build-stages"); const { resolveStages } = require("./lib/build-stages");
const { validateManifest, addIntegrity } = require("./lib/package-contract"); const { validateManifest, addIntegrity } = require("./lib/package-contract");
const { blenderExecutable: resolveBlenderExecutable } = require("./lib/tool-paths"); const { blenderExecutable: resolveBlenderExecutable } = require("./lib/tool-paths");
@@ -16,6 +16,7 @@ const {
} = require("./lib/scene-layers"); } = require("./lib/scene-layers");
const { digest: glbDigest } = require("./glb-digest"); const { digest: glbDigest } = require("./glb-digest");
const { buildVehicleRoute: buildPreviewVehicleRoute } = require("./lib/vehicle-route"); const { buildVehicleRoute: buildPreviewVehicleRoute } = require("./lib/vehicle-route");
const { buildNativeTrafficSimulation } = require("./lib/native-preview-traffic-simulation");
const { writePreviewVehicleLibrary, writePreviewV2xVehicleLibrary } = require("./lib/vehicle-library"); const { writePreviewVehicleLibrary, writePreviewV2xVehicleLibrary } = require("./lib/vehicle-library");
const { readTrafficSignals } = require("./lib/traffic-signals"); const { readTrafficSignals } = require("./lib/traffic-signals");
const { const {
@@ -225,10 +226,7 @@ function buildBlenderScene(area, roadProvider) {
} }
fs.mkdirSync(path.dirname(area.outputs.blend), { recursive: true }); fs.mkdirSync(path.dirname(area.outputs.blend), { recursive: true });
fs.mkdirSync(path.dirname(area.outputs.render), { recursive: true }); fs.mkdirSync(path.dirname(area.outputs.render), { recursive: true });
if (roadProvider === "native") { const nativePackage = roadProvider === "native" ? importNativeRoadPackage(area) : null;
compileNativeRoads(configPath);
ensureNativeRoadLayers(area);
}
const blenderArgs = [ const blenderArgs = [
"--background", "--background",
@@ -246,8 +244,8 @@ function buildBlenderScene(area, roadProvider) {
area.blender.treeStyle, area.blender.treeStyle,
]; ];
if (roadProvider === "native") { if (roadProvider === "native") {
blenderArgs.push("--native-road", area.outputs.nativeRoadDir); blenderArgs.push("--native-road", nativePackage.rootDir);
blenderArgs.push("--traffic-signals", path.join(area.outputs.nativeRoadDir, "traffic-signals.json")); blenderArgs.push("--traffic-signals", path.join(nativePackage.rootDir, "traffic-signals.json"));
} else { } else {
blenderArgs.push("--geojson", area.outputs.geojsonDir); blenderArgs.push("--geojson", area.outputs.geojsonDir);
} }
@@ -270,7 +268,7 @@ function buildBlenderScene(area, roadProvider) {
inputs: { inputs: {
config: fileRecord(configPath), config: fileRecord(configPath),
osm: fileRecord(area.input), osm: fileRecord(area.input),
...(roadProvider === "native" ? nativeRoadRecords(area) : sceneGeojsonRecords(area)), ...(roadProvider === "native" ? nativeRoadRecords(nativePackage) : sceneGeojsonRecords(area)),
...(roadProvider === "osm2streets" ? { ...(roadProvider === "osm2streets" ? {
geojsonDir: fileRecord(area.outputs.geojsonDir), geojsonDir: fileRecord(area.outputs.geojsonDir),
trafficSignalAssemblies: fileRecord(area.outputs.trafficSignalAssemblies), trafficSignalAssemblies: fileRecord(area.outputs.trafficSignalAssemblies),
@@ -282,7 +280,7 @@ function buildBlenderScene(area, roadProvider) {
render: fileRecord(area.outputs.render), render: fileRecord(area.outputs.render),
}, },
summary: { summary: {
...(roadProvider === "native" ? { nativeRoad: nativeRoadFeatureCounts(area) } : { geojson: geojsonFeatureCounts(area) }), ...(roadProvider === "native" ? { nativeRoad: nativeRoadFeatureCounts(nativePackage) } : { geojson: geojsonFeatureCounts(area) }),
roadProvider, roadProvider,
blendBytes: fileRecord(area.outputs.blend).bytes, blendBytes: fileRecord(area.outputs.blend).bytes,
renderBytes: fileRecord(area.outputs.render).bytes, renderBytes: fileRecord(area.outputs.render).bytes,
@@ -291,17 +289,13 @@ function buildBlenderScene(area, roadProvider) {
}); });
} }
function ensureNativeRoadLayers(area) { function nativeRoadRecords(nativePackage) {
ensureFile(path.join(area.outputs.nativeRoadDir, "compiled.json"), "Native road compilation"); const root = path.join(nativePackage.rootDir, "layers");
for (const file of ["road_surface.geojson", "edge_lines.geojson", "intersection_surface.geojson", "sidewalk_surface.geojson", "lane_separators.geojson", "center_lines.geojson", "direction_arrows.geojson", "turn_arrows.geojson", "crosswalks.geojson", "vehicle_stop_lines.geojson"]) {
ensureFile(path.join(area.outputs.nativeRoadDir, "layers", file), `Native road layer ${file}`);
}
}
function nativeRoadRecords(area) {
const root = path.join(area.outputs.nativeRoadDir, "layers");
return { return {
nativeRoadCompiled: fileRecord(path.join(area.outputs.nativeRoadDir, "compiled.json")), nativeRoadZip: nativePackage.zipRecord,
nativeRoadImport: fileRecord(nativePackage.rootDir),
nativeRoadCompiled: fileRecord(path.join(nativePackage.rootDir, "compiled.json")),
nativeRoadSignals: fileRecord(path.join(nativePackage.rootDir, "traffic-signals.json")),
nativeRoadSurface: fileRecord(path.join(root, "road_surface.geojson")), nativeRoadSurface: fileRecord(path.join(root, "road_surface.geojson")),
nativeEdgeLines: fileRecord(path.join(root, "edge_lines.geojson")), nativeEdgeLines: fileRecord(path.join(root, "edge_lines.geojson")),
nativeIntersectionSurface: fileRecord(path.join(root, "intersection_surface.geojson")), nativeIntersectionSurface: fileRecord(path.join(root, "intersection_surface.geojson")),
@@ -315,8 +309,8 @@ function nativeRoadRecords(area) {
}; };
} }
function nativeRoadFeatureCounts(area) { function nativeRoadFeatureCounts(nativePackage) {
const root = path.join(area.outputs.nativeRoadDir, "layers"); const root = path.join(nativePackage.rootDir, "layers");
return { return {
roadSurface: featureCount(path.join(root, "road_surface.geojson")), roadSurface: featureCount(path.join(root, "road_surface.geojson")),
edgeLines: featureCount(path.join(root, "edge_lines.geojson")), edgeLines: featureCount(path.join(root, "edge_lines.geojson")),
@@ -487,8 +481,9 @@ function compressCesiumGlb(area) {
function publishPackage(area, roadProvider) { function publishPackage(area, roadProvider) {
ensureFile(area.outputs.packageStagingManifest, "Staged package manifest"); ensureFile(area.outputs.packageStagingManifest, "Staged package manifest");
const trafficSignalsSource = roadProvider === "native" const nativePackage = roadProvider === "native" ? importNativeRoadPackage(area) : null;
? path.join(area.outputs.nativeRoadDir, "traffic-signals.json") const trafficSignalsSource = nativePackage
? path.join(nativePackage.rootDir, "traffic-signals.json")
: area.outputs.trafficSignals; : area.outputs.trafficSignals;
ensureFile(trafficSignalsSource, "Traffic signal anchors"); ensureFile(trafficSignalsSource, "Traffic signal anchors");
const started = Date.now(); const started = Date.now();
@@ -574,10 +569,15 @@ function writeCesiumPreview(area, roadProvider) {
intersectionSurface: fileRecord(intersectionSurface), intersectionSurface: fileRecord(intersectionSurface),
}); });
} else { } else {
Object.assign(previewInputs, nativeRoadRecords(area)); const nativePackage = importNativeRoadPackage(area);
// This operational preview intentionally has no synthetic vehicle source. Object.assign(previewInputs, nativeRoadRecords(nativePackage));
// A stale descriptor from an older build must not resurrect simulated routes. // The simulation JSON is loaded by the preview HTML, so model URIs must
fs.rmSync(area.outputs.trafficSimulation, { force: true }); // be relative to the area output (where `_preview/` is the asset root),
// not relative to the repository's source asset directory.
const simulation = buildNativeTrafficSimulation(area, { nativePackage, modelPrefix: "_preview/" });
fs.mkdirSync(path.dirname(area.outputs.trafficSimulation), { recursive: true });
fs.writeFileSync(area.outputs.trafficSimulation, `${JSON.stringify(simulation, null, 2)}\n`);
routeArtifact = area.outputs.trafficSimulation;
} }
const htmlPath = area.outputs.cesiumPreview; const htmlPath = area.outputs.cesiumPreview;
const started = Date.now(); const started = Date.now();
+25
View File
@@ -0,0 +1,25 @@
#!/usr/bin/env node
"use strict";
const http = require("http"), fs = require("fs"), path = require("path"), crypto = require("crypto"), child = require("child_process");
const { unzipSync } = require("fflate");
const { readAreaConfig } = require("./lib/area-config");
const { STAGES } = require("./lib/build-stages");
const root = path.resolve(__dirname, ".."), configDir = path.join(root, "config", "areas"), managedRoot = path.join(root, "inputs", "console"), stateRoot = path.join(root, ".build-console", "areas"), uiFile = path.join(__dirname, "console", "index.html");
let active = null;
const send = (res, status, data) => { res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" }); res.end(JSON.stringify(data)); };
const safeKey = value => { const key = String(value || "").toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, ""); if (!key) throw Error("请输入只含字母、数字、- 或 _ 的配置名称"); return key; };
const under = (file, base) => { const resolved = path.resolve(file), parent = path.resolve(base); return resolved === parent || resolved.startsWith(`${parent}${path.sep}`); };
function areas() { return fs.readdirSync(configDir).filter(x => x.endsWith(".json")).sort().map(file => { const config = path.join(configDir, file); try { const a = readAreaConfig(config, { repoRoot: root }); const preview = a.outputs.cesiumPreview, manifest = a.outputs.packageManifest; return { key:path.basename(file,".json"), id:a.id, config, input:a.input, zip:a.nativeRoadPackage, treeStyle:a.blender.treeStyle, output:a.outputs.areaDir, preview:fs.existsSync(preview) ? `/artifacts/${path.basename(file,".json")}/${path.basename(preview)}` : null, manifest:fs.existsSync(manifest) ? `/artifacts/${path.basename(file,".json")}/package/manifest.json` : null }; } catch (e) { return { key:path.basename(file,".json"), error:e.message }; } }); }
function inspectZip(bytes) { let files; try { files = unzipSync(bytes); } catch (_) { throw Error("道路 ZIP 无法解压"); } if (!files["manifest.json"]) throw Error("道路 ZIP 缺少 manifest.json"); let manifest; try { manifest=JSON.parse(Buffer.from(files["manifest.json"]).toString("utf8")); } catch (_) { throw Error("道路 ZIP manifest.json 无效"); } if (manifest.contract !== "native-road-package/v1.1" || !manifest.areaId) throw Error("道路 ZIP 不是受支持的 native-road-package/v1.1"); return { areaId:manifest.areaId, contract:manifest.contract }; }
function body(req) { return new Promise((resolve,reject) => { let data=""; req.on("data", c=>{ data+=c; if(data.length>100*1024*1024) reject(Error("上传文件过大")); }); req.on("end",()=>{ try { resolve(JSON.parse(data||"{}")); } catch (_) { reject(Error("请求 JSON 无效")); } }); }); }
function trash(target) { if (!fs.existsSync(target)) return; if (!under(target, root)) throw Error("拒绝清理项目外文件"); child.execFileSync("osascript", ["-e", `tell application \"Finder\" to delete POSIX file ${JSON.stringify(target)}`]); }
function serve(req,res) { const url = new URL(req.url, "http://127.0.0.1"); if (req.method==="GET" && url.pathname==="/") { res.writeHead(200,{"content-type":"text/html; charset=utf-8"}); return res.end(fs.readFileSync(uiFile)); }
if(req.method==="GET"&&url.pathname==="/api/health") return send(res,200,{node:process.version, blender:fs.existsSync("/Applications/Blender.app/Contents/MacOS/Blender"), areas:areas().length});
if(req.method==="GET"&&url.pathname==="/api/areas") return send(res,200,{areas:areas(),stages:STAGES,treeStyles:["natural","procedural","shapespark"]});
if(req.method==="POST"&&url.pathname==="/api/inspect") return body(req).then(x=>send(res,200,inspectZip(Buffer.from(x.zip,"base64")))).catch(e=>send(res,400,{error:e.message}));
if(req.method==="POST"&&url.pathname==="/api/import") return body(req).then(x=>{ const key=safeKey(x.key), osm=Buffer.from(x.osm,"base64"), zip=Buffer.from(x.zip,"base64"), info=inspectZip(zip), dir=path.join(managedRoot,key); if(fs.existsSync(path.join(configDir,`${key}.json`))) throw Error("该配置名称已存在;请另存为新名称"); fs.mkdirSync(dir,{recursive:true}); const osmFile=path.join(dir,"source.osm"), zipFile=path.join(dir,"roads.zip"); fs.writeFileSync(osmFile,osm); fs.writeFileSync(zipFile,zip); const out=path.join(root,"outputs",key), config={id:info.areaId,input:osmFile,nativeRoadPackage:zipFile,outputRoot:path.join(root,"outputs"),outputs:{areaDir:out,fileStem:key},blender:{roadProvider:"native",treeStyle:x.treeStyle||"natural"}}; const file=path.join(configDir,`${key}.json`); fs.writeFileSync(file,JSON.stringify(config,null,2)+"\n"); fs.mkdirSync(stateRoot,{recursive:true}); fs.writeFileSync(path.join(stateRoot,`${key}.json`),JSON.stringify({key,config:file,managed:dir,output:out},null,2)); send(res,201,{key,id:info.areaId}); }).catch(e=>send(res,400,{error:e.message}));
if(req.method==="POST"&&url.pathname==="/api/build") return body(req).then(x=>{ if(active&&!active.done) throw Error("已有构建正在运行"); const key=safeKey(x.key), file=path.join(configDir,`${key}.json`); if(!fs.existsSync(file)) throw Error("配置不存在"); const args=[path.join(__dirname,"build-area.js"),"--config",file]; if(Array.isArray(x.stages)&&x.stages.length) args.push("--stages",x.stages.join(",")); const proc=child.spawn(process.execPath,args,{cwd:root}); const job=active={id:crypto.randomUUID(),key,logs:[],done:false}; for(const s of [proc.stdout,proc.stderr]) s.on("data",b=>job.logs.push(b.toString())); proc.on("close",code=>{job.logs.push(`\n构建结束:${code===0?"成功":"失败"} (${code})\n`);job.done=true;job.code=code;}); send(res,202,{id:job.id}); }).catch(e=>send(res,409,{error:e.message}));
if(req.method==="GET"&&url.pathname==="/api/job") return send(res,200,active||{done:true});
if(req.method==="POST"&&url.pathname==="/api/cleanup") return body(req).then(x=>{ const keys=Array.isArray(x.keys)?x.keys:[]; const known=new Map(areas().map(a=>[a.key,a])); for(const raw of keys){const key=safeKey(raw), area=known.get(key), config=path.join(configDir,`${key}.json`); if(!area||!fs.existsSync(config)) throw Error(`区域不存在:${key}`); trash(area.output||path.join(root,"outputs",key)); const rec=path.join(stateRoot,`${key}.json`); if(x.mode==="remove"){ if(fs.existsSync(rec)){const r=JSON.parse(fs.readFileSync(rec));trash(r.managed);trash(rec);} trash(config); } } send(res,200,{ok:true}); }).catch(e=>send(res,400,{error:e.message}));
if(req.method==="GET"&&url.pathname.startsWith("/artifacts/")){const [, ,key,...rest]=url.pathname.split("/");const a=areas().find(x=>x.key===key);const f=path.resolve(a?.output||"",...rest);if(!a||!under(f,a.output)||!fs.existsSync(f))return send(res,404,{error:"未找到产物"});return fs.createReadStream(f).pipe(res);} send(res,404,{error:"Not found"}); }
http.createServer((q,s)=>serve(q,s)).listen(8788,"127.0.0.1",()=>{const u="http://127.0.0.1:8788/";console.log(`Build console: ${u}`);child.spawn("open",[u],{detached:true,stdio:"ignore"}).unref();});
Loaded 100 of 132 files, more files were not shown because too many files have changed in this diff. Show more