Compare commits
5
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d5c58b5b0c | ||
|
|
73707dabbe | ||
|
|
5220c6b2a2 | ||
|
|
d7c2e13124 | ||
|
|
e7bc7f82b1 |
No files matched your search
@@ -1464,6 +1464,72 @@ parity 校验依赖 stage 的 stdout 标记来判断阶段是否跑到(如 `SC
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Native Road Parity
|
||||||
|
|
||||||
|
### 1. Scope / Trigger
|
||||||
|
|
||||||
|
拆分 native road compiler、移动其模块,或声称 native-road JSON / GeoJSON 未变化时,
|
||||||
|
用 `scripts/road-parity.js`。它独立于 build stage,只读现有 native-road 输出。
|
||||||
|
|
||||||
|
### 2. Signatures
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node scripts/road-parity.js --config config/areas/<area>.json --snapshot <out.json>
|
||||||
|
node scripts/road-parity.js --config config/areas/<area>.json --compare <baseline.json>
|
||||||
|
```
|
||||||
|
|
||||||
|
`--config` 必填,且 `--snapshot` 与 `--compare` 必须二选一。
|
||||||
|
|
||||||
|
### 3. Contracts
|
||||||
|
|
||||||
|
- 快照覆盖 `outputs/<area>/native-road/` 下全部文件和同级
|
||||||
|
`native-traffic-signals.json`。
|
||||||
|
- 普通 JSON 递归按对象 key 排序后生成 `contentHash`。
|
||||||
|
- GeoJSON 同时生成排序 feature 的 `contentHash` 与原序 `orderHash`;任一不同都算
|
||||||
|
parity 失败。
|
||||||
|
- 绝对路径归一化为 `<repo>/...` 或 `<external>/<basename>`,随机
|
||||||
|
`native-road-*` staging 名归一化为 `<staging>`。坐标不做容差或舍入。
|
||||||
|
|
||||||
|
### 4. Validation & Error Matrix
|
||||||
|
|
||||||
|
| 条件 | 结果 |
|
||||||
|
|---|---|
|
||||||
|
| 缺 `--config` 或同时/均未传 snapshot、compare | 打印 usage,退出非零 |
|
||||||
|
| native-road 输出目录不存在 | 抛出 `Native road output not found`,退出非零 |
|
||||||
|
| baseline 缺文件、出现额外文件或任一 hash/count/bytes 不同 | 每项打印 `ROAD_PARITY_DIFF`,退出非零 |
|
||||||
|
| 完全一致 | 打印 `ROAD_PARITY_OK`,退出 0 |
|
||||||
|
|
||||||
|
### 5. Good/Base/Bad Cases
|
||||||
|
|
||||||
|
- Good: 移动编译器前后,两个 hash 均一致。
|
||||||
|
- Base: 绝对 OSM 输入路径变化但归一化后内容一致。
|
||||||
|
- Bad: 只比较排序后的 GeoJSON 内容并忽略 `orderHash`,会掩盖输出顺序漂移。
|
||||||
|
|
||||||
|
### 6. Tests Required
|
||||||
|
|
||||||
|
- `npm run test:road-parity`:相等基线、顺序 hash 变化与缺文件都应被断言。
|
||||||
|
- `node --check scripts/road-parity.js`。
|
||||||
|
- 对每个受支持区域运行 `--compare` 对已提交基线自比对。
|
||||||
|
- 迁移前先连续编译两次;只有 control 实验全绿,基线才可作为 oracle。
|
||||||
|
|
||||||
|
### 7. Wrong vs Correct
|
||||||
|
|
||||||
|
Wrong:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// Sorting hides a changed feature order.
|
||||||
|
assert.equal(sortedContentHash, baseline.contentHash);
|
||||||
|
```
|
||||||
|
|
||||||
|
Correct:
|
||||||
|
|
||||||
|
```js
|
||||||
|
assert.equal(contentHash, baseline.contentHash);
|
||||||
|
assert.equal(orderHash, baseline.orderHash);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 反模式
|
## 反模式
|
||||||
|
|
||||||
| 反模式 | 后果 |
|
| 反模式 | 后果 |
|
||||||
|
|||||||
@@ -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,53 @@
|
|||||||
|
# Phase 1 Technical Design
|
||||||
|
|
||||||
|
## Boundary
|
||||||
|
|
||||||
|
`packages/road-compiler/` becomes the single implementation owner for native
|
||||||
|
road compilation. It is a CommonJS workspace package with explicit public
|
||||||
|
entrypoints for compiler APIs, traffic-signal schema, turn-lane helpers, OSM
|
||||||
|
parsing, reference conversion, and CLIs. It never imports `area-config`, reads
|
||||||
|
`config/areas`, or derives host paths.
|
||||||
|
|
||||||
|
The host owns `scripts/lib/area-config.js` and maps normalized configuration to
|
||||||
|
the v1 `RoadCompilerInput` shape using `toRoadCompilerInput(area)`. During P1,
|
||||||
|
`build-area.js` calls the package in-process; P2 is the only phase that changes
|
||||||
|
that call to a child process.
|
||||||
|
|
||||||
|
## Source Ownership and Compatibility
|
||||||
|
|
||||||
|
The following current `scripts/lib` implementations move into package `src`:
|
||||||
|
`native-road`, `complex-junction`, `turn-lane-arrows`, `lane-geometry`,
|
||||||
|
`gaode-junction-reference`, `native-traffic-signals`, and `osm`.
|
||||||
|
|
||||||
|
Some moved modules also serve legacy host paths: QGIS uses turn-lane arrows,
|
||||||
|
vehicle preview and reimport use OSM parsing, and preview tests use lane
|
||||||
|
geometry. Those consumers import the package entrypoints after the move. This
|
||||||
|
preserves one implementation while allowing host -> package dependency.
|
||||||
|
|
||||||
|
Traffic signal ownership follows the matrix in
|
||||||
|
`research/traffic-signals-split-matrix.md`: schema, geometry, validation, and
|
||||||
|
runtime construction move to the package. The host retains only two file-I/O
|
||||||
|
adapters, `readTrafficSignalFeatures()` and `readTrafficSignals()`, both
|
||||||
|
delegating to package exports. No duplicated schema code remains.
|
||||||
|
|
||||||
|
## Input and Path Handling
|
||||||
|
|
||||||
|
The package compiler API accepts only `RoadCompilerInput` from
|
||||||
|
`docs/native-road-package-v1.md`. Package CLI commands accept an explicit JSON
|
||||||
|
input file (`--input`) and never load area configuration. The compatibility
|
||||||
|
host CLI still accepts `--config`, but immediately maps it through
|
||||||
|
`toRoadCompilerInput()` before entering the package.
|
||||||
|
|
||||||
|
`junctionTemplates.*.referenceFile` changes to a path relative to its area
|
||||||
|
configuration. `readAreaConfig()` resolves it while normalizing configuration;
|
||||||
|
the package receives an absolute path and does no path resolution.
|
||||||
|
|
||||||
|
## Tests and Rollout
|
||||||
|
|
||||||
|
The package receives the required Fengshu OSM fixture plus migrated unit tests.
|
||||||
|
Its `npm test` must run from the package directory without reading host inputs
|
||||||
|
or outputs. After each source batch, run the two Phase 0 parity baselines. The
|
||||||
|
existing host command names remain compatibility wrappers through P1.
|
||||||
|
|
||||||
|
Rollback is a normal Git revert of the latest batch commit. No module has a
|
||||||
|
parallel host copy after its batch lands, preventing divergence.
|
||||||
@@ -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,118 @@
|
|||||||
|
# Phase 1 执行计划
|
||||||
|
|
||||||
|
分批搬迁,每批后跑 parity。**不要一次性大搬。**
|
||||||
|
|
||||||
|
## Step 0 — 前置
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 基线必须先绿
|
||||||
|
for a in fengshu-er-road 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
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] 两个有效区域基线全绿(否则回 Phase 0)
|
||||||
|
|
||||||
|
## Step 1 — K1 矩阵(动代码之前)
|
||||||
|
|
||||||
|
- [ ] 读 `scripts/lib/traffic-signals.js` 全文,列出所有 export
|
||||||
|
- [ ] 对每个 export `grep -rn` 找使用方
|
||||||
|
- [ ] 产出 `research/traffic-signals-split-matrix.md`:函数 × 使用方 × 归属判定
|
||||||
|
- [ ] `buildTrafficSignals`(`test-preview-assets.js`)归属定档
|
||||||
|
|
||||||
|
**门槛**:矩阵完成,无"待定"项。
|
||||||
|
|
||||||
|
## Step 2 — 建包骨架
|
||||||
|
|
||||||
|
```
|
||||||
|
packages/road-compiler/
|
||||||
|
package.json # CommonJS,无构建步骤(父任务 C2)
|
||||||
|
src/
|
||||||
|
bin/
|
||||||
|
test/fixtures/
|
||||||
|
docs/
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] `package.json` 名称、入口、`test` script
|
||||||
|
- [ ] 根 `package.json` 加 workspace 或 `file:` 依赖
|
||||||
|
|
||||||
|
## Step 3 — 分批搬迁(每批一个 commit + 一次 parity)
|
||||||
|
|
||||||
|
**批 1:纯函数,零风险**
|
||||||
|
- [ ] `lib/lane-geometry.js` → `src/geometry/lane-geometry.js`
|
||||||
|
- [ ] `lib/gaode-junction-reference.js` → `src/reference/gaode.js`
|
||||||
|
- [ ] 宿主侧改 require 指向包
|
||||||
|
- [ ] parity ✓
|
||||||
|
|
||||||
|
**批 2:几何模块**
|
||||||
|
- [ ] `lib/turn-lane-arrows.js`
|
||||||
|
- [ ] `lib/complex-junction.js`
|
||||||
|
- [ ] parity ✓
|
||||||
|
|
||||||
|
**批 3:信号(K1 执行)**
|
||||||
|
- [ ] 按 Step 1 矩阵拆 `lib/traffic-signals.js`
|
||||||
|
- [ ] `lib/native-traffic-signals.js` 与 schema 部分入包
|
||||||
|
- [ ] `lib/osm.js` 入包
|
||||||
|
- [ ] 宿主保留 legacy 读取器,从包 import schema
|
||||||
|
- [ ] parity ✓ + `npm run test:traffic-signals`(若存在)
|
||||||
|
|
||||||
|
**批 4:编译器核心**
|
||||||
|
- [ ] `lib/native-road.js` → `src/compile/native-road.js`
|
||||||
|
- [ ] parity ✓
|
||||||
|
|
||||||
|
**批 5:CLI + 窄契约(R1.2)**
|
||||||
|
- [ ] `compile-native-roads.js` → `bin/compile.js`,入参改 `RoadCompilerInput`
|
||||||
|
- [ ] `check-native-roads.js` → `bin/check.js`
|
||||||
|
- [ ] 宿主 `area-config.js` 加 `toRoadCompilerInput(area)`
|
||||||
|
- [ ] `build-area.js` 改为传 input 对象
|
||||||
|
- [ ] K3:`referenceFile` 改为宿主解析后传绝对路径,config 内改相对路径
|
||||||
|
- [ ] parity ✓
|
||||||
|
|
||||||
|
**批 6:workbench**
|
||||||
|
- [ ] `road-workbench.js` + `workbench/app.js` 入包
|
||||||
|
- [ ] OpenLayers 依赖暂沿用宿主 `node_modules`(同仓库内可行),记入 Phase 2 K4
|
||||||
|
- [ ] `npm run test:road-workbench` ✓
|
||||||
|
|
||||||
|
**批 7:测试 fixture(R1.5)**
|
||||||
|
- [ ] `inputs/osm/枫树二路.osm` 复制进 `test/fixtures/`
|
||||||
|
- [ ] `test-native-road.js` 改读包内 fixture
|
||||||
|
- [ ] 在包目录内独立跑 `npm test` ✓
|
||||||
|
|
||||||
|
## Step 4 — 清理与验证
|
||||||
|
|
||||||
|
- [ ] 删除 `scripts/lib/` 下所有搬迁文件的残留(AC1.6)
|
||||||
|
- [ ] `grep -rn "area-config\|config/areas" packages/road-compiler/` 必须为空(AC1.4)
|
||||||
|
- [ ] `grep -rn "\.\./\.\./scripts\|osm2streets-qgis-workflow" packages/road-compiler/` 检查反向依赖
|
||||||
|
|
||||||
|
## 验证命令汇总
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# parity
|
||||||
|
for a in fengshu-er-road 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
|
||||||
|
|
||||||
|
# 测试
|
||||||
|
npm run test:native-road
|
||||||
|
npm run test:road-workbench
|
||||||
|
(cd packages/road-compiler && npm test)
|
||||||
|
|
||||||
|
# 端到端(含 blender / cesium)
|
||||||
|
npm run build:area -- --config config/areas/fengshu-er-road.json
|
||||||
|
|
||||||
|
# 反向依赖为 0
|
||||||
|
grep -rn "area-config\|config/areas" packages/road-compiler/ && echo "VIOLATION"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Review Gate
|
||||||
|
|
||||||
|
AC1.1–AC1.8 全绿。**parity 有任何一项不绿都不得进 Phase 2** —— 那意味着搬迁改变了行为,
|
||||||
|
而在同一仓库内查因比拆仓库后查因便宜得多。
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
每批一个 commit,可逐批 `git revert`。
|
||||||
|
过渡期内若需紧急回退,宿主 require 改回 `scripts/lib/` 旧路径即可
|
||||||
|
(前提:该批尚未执行 Step 4 清理)。
|
||||||
@@ -0,0 +1,98 @@
|
|||||||
|
# Phase 1:包边界(不换仓库)
|
||||||
|
|
||||||
|
父任务:`.trellis/tasks/08-25-road-compiler-extraction/`
|
||||||
|
技术设计:父任务 `design.md` §2(模块清单 / K1 拆分建议)
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
在**当前仓库内**建立 `packages/road-compiler/`,移入编译器全部模块,
|
||||||
|
把对 `readAreaConfig` 的耦合换成窄输入契约,产物对 Phase 0 基线逐字节一致。
|
||||||
|
|
||||||
|
**本阶段不换仓库。** 目的是把"改坏了编译器"与"拆坏了仓库"分成两个可归因的步骤
|
||||||
|
(父任务 D4)。
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
### R1.1 目录与模块搬迁
|
||||||
|
|
||||||
|
在 `packages/road-compiler/` 内建立结构,移入父任务 `design.md` §2.1 列出的全部文件
|
||||||
|
(约 3400 行核心 + workbench)。
|
||||||
|
|
||||||
|
搬迁后 `scripts/lib/` 下不应再留下这些文件的副本 —— 并存会导致
|
||||||
|
"改了一份忘了另一份"的静默不一致。
|
||||||
|
|
||||||
|
### R1.2 窄输入契约
|
||||||
|
|
||||||
|
- 编译器入口只接受父任务 `design.md` §1.1 定义的 `RoadCompilerInput`
|
||||||
|
- 编译器内不得出现 `require("area-config")`、不得读 `config/areas/*.json`、
|
||||||
|
不得从 areaId 推导任何路径
|
||||||
|
- 宿主 `scripts/lib/area-config.js` 新增 `toRoadCompilerInput(area)` 做映射
|
||||||
|
- 三个 CLI(`compile` / `check` / `workbench`)改为接受显式参数或 input JSON
|
||||||
|
|
||||||
|
### R1.3 K1:`traffic-signals.js` 拆分 🔴
|
||||||
|
|
||||||
|
**全案唯一需要细读再动的地方。** 按父任务 `design.md` §2.3:
|
||||||
|
|
||||||
|
- 随编译器走:OSM 信号节点提取 + 信号文档 schema
|
||||||
|
- 留宿主:`readTrafficSignalFeatures`(`build-osm2streets-qgis.js`)、
|
||||||
|
`readTrafficSignals`(`build-area.js`)
|
||||||
|
- 待判定:`buildTrafficSignals`(`test-preview-assets.js`)—— 需读代码确认归属
|
||||||
|
- 拆完后宿主从编译器包 import schema(宿主→编译器是允许方向)
|
||||||
|
|
||||||
|
动手前必须先产出一份「函数 × 使用方」矩阵,确认无遗漏。
|
||||||
|
|
||||||
|
### R1.4 K3:参考文件路径约定
|
||||||
|
|
||||||
|
`config/areas/fengshu-er-road.json` 的
|
||||||
|
`junctionTemplates.clusters[].referenceFile` 是指向宿主仓库的绝对路径。
|
||||||
|
|
||||||
|
- 定义解析约定:相对 config 文件所在目录,或由宿主在 `toRoadCompilerInput()`
|
||||||
|
中解析为绝对路径后传入
|
||||||
|
- 倾向后者:**编译器只接受已解析的绝对路径,不做路径推导**(符合 R1.2)
|
||||||
|
- config 内改为相对路径,宿主负责解析
|
||||||
|
|
||||||
|
### R1.5 K5:自带测试 fixture
|
||||||
|
|
||||||
|
- `test-native-road.js:167` 读 `inputs/osm/枫树二路.osm`
|
||||||
|
- 该文件(或裁剪版)复制进 `packages/road-compiler/test/fixtures/`
|
||||||
|
- 测试改为读包内 fixture,不再访问宿主 `inputs/`
|
||||||
|
- 目标:编译器包 `npm test` 不依赖宿主任何目录
|
||||||
|
|
||||||
|
### R1.6 宿主侧接线保持不变
|
||||||
|
|
||||||
|
- `build-area.js` 本阶段继续 in-process `require`(子进程改造留到 Phase 2)
|
||||||
|
- `npm run road:compile` / `road:check` / `road:workbench` 行为对用户不变
|
||||||
|
- `blender/` 完全不改
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] AC1.1 两个有效区域 `road-parity --compare` 对 Phase 0 基线全绿
|
||||||
|
- [ ] AC1.2 `npm run test:native-road`、`npm run test:road-workbench` 通过
|
||||||
|
- [ ] AC1.3 `npm run build:area` 枫树二路完整跑通(含 blender / cesium 阶段)
|
||||||
|
- [ ] AC1.4 `grep -rn "area-config\|config/areas" packages/road-compiler/` 无命中
|
||||||
|
- [ ] AC1.5 `packages/road-compiler/` 内 `npm test` 不访问宿主 `inputs/` 或 `outputs/`
|
||||||
|
- [ ] AC1.6 `scripts/lib/` 下无搬迁文件的残留副本
|
||||||
|
- [ ] AC1.7 K1 的「函数 × 使用方」矩阵已产出并归档到 `research/`
|
||||||
|
- [ ] AC1.8 `compiled.json` 结构未变(父任务 AC7 / C1)
|
||||||
|
|
||||||
|
## 依赖与顺序
|
||||||
|
|
||||||
|
- **前置**:Phase 0 必须完成且基线可靠
|
||||||
|
- **阻塞**:Phase 2
|
||||||
|
- 与 Phase 3、4 无直接依赖,但它们都在 Phase 2 之后
|
||||||
|
|
||||||
|
## 风险
|
||||||
|
|
||||||
|
| 风险 | 缓解 |
|
||||||
|
|---|---|
|
||||||
|
| K1 拆分遗漏某个使用方 → 运行时才炸 | 先做矩阵,再动代码;`grep -rn` 全仓验证 |
|
||||||
|
| 搬迁过程中相对 require 路径改错 | 分小步 commit,每步跑 parity |
|
||||||
|
| `workbench/app.js` 的 OpenLayers import map 指向宿主 node_modules | 本阶段仍在同仓库,可暂不处理;记入 Phase 2(K4) |
|
||||||
|
| 一次性大搬迁难以归因 | 按模块分批:先纯函数(lane-geometry / gaode-reference),再 complex-junction,最后 native-road 与 CLI |
|
||||||
|
|
||||||
|
## Out of Scope
|
||||||
|
|
||||||
|
- 换仓库(Phase 2)
|
||||||
|
- layer manifest(Phase 3)
|
||||||
|
- IR / pass manager 重构(父任务 C1)
|
||||||
|
- 引入 TypeScript 或构建步骤(父任务 C2)
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
# Traffic Signals Split Matrix
|
||||||
|
|
||||||
|
Evidence gathered from `scripts/lib/traffic-signals.js` and repository-wide
|
||||||
|
call-site search on 2026-08-25.
|
||||||
|
|
||||||
|
| Export | Current users | Owner after P1 | Migration |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `SIGNAL_LAYOUT` | `buildTrafficSignalsFromFeatures` | compiler package | Export from `@osm-asset/road-compiler/traffic-signals` |
|
||||||
|
| `signalNodeKey` | `buildTrafficSignalsFromFeatures` | compiler package | No host caller today; preserve public export for runtime identity contract |
|
||||||
|
| `buildTrafficSignalFeatures` | `native-traffic-signals`, `readTrafficSignalFeatures` | compiler package | Host QGIS adapter imports it from the package |
|
||||||
|
| `validateTrafficSignalFeatures` | `native-traffic-signals`, signal tests | compiler package | Tests import package entrypoint |
|
||||||
|
| `validateTrafficSignalSourceReferences` | `native-traffic-signals`, `reimport-gpkg`, `readTrafficSignals` | compiler package | Reimport adapter imports package function |
|
||||||
|
| `buildTrafficSignalsFromFeatures` | `native-traffic-signals`, `readTrafficSignals`, `buildTrafficSignals` | compiler package | Host preview adapter imports package function |
|
||||||
|
| `buildTrafficSignals` | `test-preview-assets` | compiler package | Test imports package function; it is geometry/schema behavior, not host I/O |
|
||||||
|
| `readTrafficSignalFeatures` | `build-osm2streets-qgis` | host adapter | Keep a thin file-reading wrapper under `scripts/lib/traffic-signals.js`; it imports package functions |
|
||||||
|
| `readTrafficSignals` | `build-area` | host adapter | Keep a thin file-reading wrapper under `scripts/lib/traffic-signals.js`; it imports package functions |
|
||||||
|
|
||||||
|
`scripts/lib/traffic-signals.js` must not retain a second implementation of
|
||||||
|
the schema or geometry. Its only P1 responsibility is host file I/O for the
|
||||||
|
legacy QGIS / preview paths. This preserves the one-way dependency:
|
||||||
|
host -> compiler package; the package never imports the host.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "rc-p1-package-boundary",
|
||||||
|
"name": "rc-p1-package-boundary",
|
||||||
|
"title": "Phase 1:包边界(不换仓库)",
|
||||||
|
"description": "在本仓库内建 packages/road-compiler,移入编译器模块,用窄输入契约替换 readAreaConfig 耦合,产物对基线逐字节一致",
|
||||||
|
"status": "in_progress",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P1",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-25",
|
||||||
|
"completedAt": null,
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "main",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": "08-25-road-compiler-extraction",
|
||||||
|
"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 @@
|
|||||||
|
{"_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,74 @@
|
|||||||
|
# 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;新仓库留着不影响宿主
|
||||||
@@ -0,0 +1,80 @@
|
|||||||
|
# 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)
|
||||||
|
- 任何编译器内部逻辑改动 —— 本阶段代码内容不变,只换位置与消费方式
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "rc-p2-repo-split",
|
||||||
|
"name": "rc-p2-repo-split",
|
||||||
|
"title": "Phase 2:拆仓库",
|
||||||
|
"description": "保留 git 历史拆出独立仓库,宿主以锁版本依赖消费,子进程为主契约",
|
||||||
|
"status": "planning",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P1",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-25",
|
||||||
|
"completedAt": null,
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "main",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": "08-25-road-compiler-extraction",
|
||||||
|
"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 @@
|
|||||||
|
{"_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,85 @@
|
|||||||
|
# Phase 3 执行计划
|
||||||
|
|
||||||
|
## Step 1 — 枚举现有分流逻辑(定 schema 之前)
|
||||||
|
|
||||||
|
- [x] 读 `blender/generate_scene.py:796-834` 全部道路分支
|
||||||
|
- [x] 列出每个 `source` 的处理方式:直接渲染 / 按属性分流 / 跳过
|
||||||
|
- [ ] 已知分流:
|
||||||
|
- `center_lines`:`color != "white"` → `center_lines` 材质;
|
||||||
|
`color == "white"` → `native_center_line_white`
|
||||||
|
- `lane_separators`:`color != "yellow"` → `lane_separators`;
|
||||||
|
`color == "yellow"` → `native_lane_separator_yellow`
|
||||||
|
- [x] 确认 `lane_centerlines` / `connectors` 确实未被消费(→ `role: "semantic"`)
|
||||||
|
- [x] 产出 `research/native-layer-consumption-matrix.md`
|
||||||
|
|
||||||
|
**门槛**:manifest schema 能表达矩阵里的每一行,无"特例硬编码"残留。
|
||||||
|
|
||||||
|
## Step 2 — 定 manifest schema 并落契约
|
||||||
|
|
||||||
|
- [ ] 按父任务 `design.md` §3.2 定稿 schema
|
||||||
|
- [ ] 写入编译器仓库契约文档,版本标为 `native-road-package/v1.1`
|
||||||
|
- [ ] 记录:v1.1 起 `manifest.json` 为必需输出
|
||||||
|
|
||||||
|
## Step 3 — 编译器侧:生成 manifest
|
||||||
|
|
||||||
|
- [ ] 编译器内建立图层注册表(单一事实源),`compileGeometry` 的输出键与之对应
|
||||||
|
- [ ] 写 `manifest.json` 到 outDir
|
||||||
|
- [ ] 编译器自校验:manifest 声明的每个 `source` 都必须有对应 geojson 文件,
|
||||||
|
反之亦然(缺一即报错,不静默)
|
||||||
|
- [ ] parity:此步只**新增** manifest.json,其余文件应逐字节不变
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 只应多出 manifest.json
|
||||||
|
node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
|
||||||
|
--compare .../baseline/fengshu-er-road.json
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 4 — Blender 侧:抽模块 + 读 manifest
|
||||||
|
|
||||||
|
- [ ] 新建 `blender/osmassets/native_roads.py`
|
||||||
|
- [ ] 把 `generate_scene.py:796-834` 的道路分支迁入
|
||||||
|
- [ ] 改为读 manifest 遍历;`role == "semantic"` 跳过
|
||||||
|
- [ ] `splitBy` 通用化实现,替掉两处硬编码 lambda
|
||||||
|
- [ ] **加断言**:manifest 里的 `materialLayer` 若不在 `catalog.MATERIALS` /
|
||||||
|
`ROAD_LAYERS` 中,直接 raise,不静默跳过(风险表第二条)
|
||||||
|
- [ ] 删除 `catalog.NATIVE_ROAD_LAYERS`
|
||||||
|
- [ ] `generate_scene.py` 只保留一行调用
|
||||||
|
|
||||||
|
## Step 5 — 验证
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# .blend 结构摘要对基线
|
||||||
|
npm run build:area -- --config config/areas/fengshu-er-road.json
|
||||||
|
# 走 artifact-parity-guide 的结构摘要比对
|
||||||
|
|
||||||
|
# 三区域跑通
|
||||||
|
for a in fengshu-er-road hanyang-block nantaizi-lake-innovation-valley; do
|
||||||
|
npm run build:area -- --config config/areas/$a.json || echo "FAIL $a"
|
||||||
|
done
|
||||||
|
|
||||||
|
# 建筑/植被/水体未被改动
|
||||||
|
git diff --stat -- blender/osmassets/ | grep -vE "native_roads|catalog"
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] 渲染预览图人工对照(结构摘要粒度不足的兜底)
|
||||||
|
|
||||||
|
## Step 6 — AC3.4 实测(可扩展性证明)
|
||||||
|
|
||||||
|
这一步是整个 Phase 3 的价值证明,不可跳过。
|
||||||
|
|
||||||
|
- [ ] 编译器加一个 throwaway 图层 `debug_probe.geojson`(几个矩形即可)
|
||||||
|
+ manifest 声明 `role: "marking"`,复用现有材质槽
|
||||||
|
- [ ] **不改宿主任何代码**,跑 blender 阶段
|
||||||
|
- [ ] 确认 Blender 场景中出现该图层几何
|
||||||
|
- [ ] 截图/记录证据到任务 `research/`
|
||||||
|
- [ ] 回滚 throwaway 图层
|
||||||
|
|
||||||
|
## Review Gate
|
||||||
|
|
||||||
|
AC3.1–AC3.7 全绿,特别是 AC3.4 有实测证据。
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
- 恢复 `catalog.NATIVE_ROAD_LAYERS`,`generate_scene.py` 恢复内联分支
|
||||||
|
- `manifest.json` 可保留输出(无消费方时无害)
|
||||||
|
- 编译器侧图层注册表保留(它本身是改进)
|
||||||
@@ -0,0 +1,90 @@
|
|||||||
|
# Phase 3:道路与建筑渲染分离
|
||||||
|
|
||||||
|
父任务:`.trellis/tasks/08-25-road-compiler-extraction/`
|
||||||
|
技术设计:父任务 `design.md` §3(含 manifest 形状与 Blender 侧改造方案)
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
让编译器自声明图层,Blender 改为读 manifest 而非硬编码表;
|
||||||
|
道路渲染从 `generate_scene.py` 抽离为独立模块,建筑/植被/水体保持原位。
|
||||||
|
|
||||||
|
**这是全案价值最高的一步** —— 它把一张跨仓库重复的表变成生成物,
|
||||||
|
使"编译器加图层忘了改宿主"这类静默错误在结构上不可能。
|
||||||
|
|
||||||
|
## 背景:当前的静默错误风险
|
||||||
|
|
||||||
|
`blender/osmassets/catalog.py:53` 的 `NATIVE_ROAD_LAYERS` 有 10 项,
|
||||||
|
而编译器写 12 个 geojson —— `lane_centerlines` 与 `connectors` 是语义层不参与渲染。
|
||||||
|
|
||||||
|
**但这个事实只存在于这张表的省略里,编译器侧没有任何声明。**
|
||||||
|
拆仓库之后,这张表和它描述的对象分处两个仓库,漂移只是时间问题。
|
||||||
|
|
||||||
|
`.trellis/spec/pipeline/index.md` 首页已经把图层表标为「最容易出静默错误」。
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
### R3.1 编译器输出 layer manifest
|
||||||
|
|
||||||
|
`<outDir>/manifest.json`,形状见父任务 `design.md` §3.2。要点:
|
||||||
|
|
||||||
|
- 每个图层声明 `source`(geojson 文件名)、`role`、以及渲染角色所需的 `materialLayer`
|
||||||
|
- `role: "semantic"` 显式标记不渲染的图层 —— 把省略变成声明
|
||||||
|
- `splitBy` 表达按属性分流到不同材质的逻辑
|
||||||
|
(当前 `generate_scene.py:815-819` 硬编码的 `color != "white"` / `color == "yellow"`)
|
||||||
|
- 材质本体(颜色、z 高度、贴图)**仍归宿主** `catalog.py::MATERIALS`;
|
||||||
|
编译器不懂渲染,只声明"我有哪些图层、什么角色、该用哪个材质槽"
|
||||||
|
|
||||||
|
### R3.2 Blender 侧改造
|
||||||
|
|
||||||
|
- `generate_scene.py` 内道路分支抽为 `blender/osmassets/native_roads.py`
|
||||||
|
- 新模块读 manifest 遍历,不再查硬编码表
|
||||||
|
- 删除 `catalog.NATIVE_ROAD_LAYERS`
|
||||||
|
- 建筑(`handle_building` / `dispatch_ways`)、植被、水体**保持原位不动**
|
||||||
|
|
||||||
|
### R3.3 契约版本处理
|
||||||
|
|
||||||
|
新增 `manifest.json` 是**向后兼容的增量**(旧消费方忽略未知文件即可),
|
||||||
|
但 Blender 改为依赖它之后就成了必需项。
|
||||||
|
|
||||||
|
- 契约文档记录:`manifest.json` 自 v1.1 起为必需输出
|
||||||
|
- 宿主声明所需最低契约版本
|
||||||
|
|
||||||
|
### R3.4 跨层一致性检查
|
||||||
|
|
||||||
|
按 `.trellis/spec/guides/cross-layer-thinking-guide.md`:
|
||||||
|
本改动同时触碰 JS(编译器输出)、Python(Blender 消费)、契约文档三层,
|
||||||
|
必须走该指南的检查清单。
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] AC3.1 编译器输出 `manifest.json`,三区域均含全部 12 图层声明
|
||||||
|
- [ ] AC3.2 `catalog.NATIVE_ROAD_LAYERS` 已删除,Blender 无硬编码道路图层表
|
||||||
|
- [ ] AC3.3 `.blend` 结构摘要对 Phase 0 基线一致
|
||||||
|
(走 `.trellis/spec/guides/artifact-parity-guide.md`)
|
||||||
|
- [ ] AC3.4 **实测**:向编译器加一个 throwaway 图层 + manifest 声明,
|
||||||
|
不改宿主任何代码,跑 blender 阶段确认它被渲染出来;验证后回滚该图层
|
||||||
|
(父任务 AC5,见 design §3.4)
|
||||||
|
- [ ] AC3.5 `role: "semantic"` 的图层被 Blender 正确跳过(不产生几何)
|
||||||
|
- [ ] AC3.6 `center_lines` 的 white/非 white 与 `lane_separators` 的 yellow/非 yellow
|
||||||
|
分流行为与改造前一致
|
||||||
|
- [ ] AC3.7 建筑/植被/水体渲染代码未被修改(`git diff` 验证范围)
|
||||||
|
|
||||||
|
## 依赖与顺序
|
||||||
|
|
||||||
|
- **前置**:Phase 2 完成(编译器已独立,manifest 才有"跨仓库契约"的意义)
|
||||||
|
- 与 Phase 4 无依赖,可并行
|
||||||
|
- 完成本阶段后,父任务 Goal 中的「道路与建筑渲染分离」才算达成
|
||||||
|
|
||||||
|
## 风险
|
||||||
|
|
||||||
|
| 风险 | 缓解 |
|
||||||
|
|---|---|
|
||||||
|
| `splitBy` 表达力不足,覆盖不了现有分流逻辑 | 先枚举 `generate_scene.py` 里全部分流分支,再定 manifest schema |
|
||||||
|
| 材质槽名在两侧漂移 | manifest 里的 `materialLayer` 必须能被宿主校验:Blender 侧加断言,未知材质槽直接报错而非静默跳过 |
|
||||||
|
| `.blend` 结构摘要对比粒度不够,漏掉几何差异 | 除结构摘要外,加渲染预览图人工对照 |
|
||||||
|
|
||||||
|
## Out of Scope
|
||||||
|
|
||||||
|
- 材质定义搬去编译器(材质属渲染,归宿主)
|
||||||
|
- osm2streets legacy 图层表 `ROAD_LAYERS` 的改动
|
||||||
|
- 建筑/植被/水体渲染逻辑
|
||||||
+34
@@ -0,0 +1,34 @@
|
|||||||
|
# Native Road 图层消费矩阵
|
||||||
|
|
||||||
|
调研日期:2026-08-25
|
||||||
|
|
||||||
|
## 证据
|
||||||
|
|
||||||
|
- 编译器在 `scripts/compile-native-roads.js:57,65-76` 声明并写出 12 个图层。
|
||||||
|
- Blender 在 `blender/generate_scene.py:796-834` 遍历
|
||||||
|
`catalog.NATIVE_ROAD_LAYERS`,只消费其中 10 个图层。
|
||||||
|
- 当前映射及基础高度来自 `blender/osmassets/catalog.py:53-64` 与 `ROAD_LAYERS`。
|
||||||
|
|
||||||
|
## 当前消费与 manifest 目标
|
||||||
|
|
||||||
|
| 编译器 source | 当前 Blender 行为 | 当前材质槽 / z 来源 | manifest 目标 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `road_surface` | 直接渲染 | `road_surface` / `ROAD_LAYERS.road_surface` | `role: surface`, `materialLayer: road_surface` |
|
||||||
|
| `edge_lines` | 直接渲染 | `lane_separators` / `ROAD_LAYERS.lane_separators` | `role: marking`, `materialLayer: lane_separators` |
|
||||||
|
| `intersection_surface` | 直接渲染 | `intersection_surface` / `ROAD_LAYERS.intersection_surface` | `role: surface`, `materialLayer: intersection_surface` |
|
||||||
|
| `sidewalk_surface` | 直接渲染 | `sidewalks` / `ROAD_LAYERS.sidewalks` | `role: surface`, `materialLayer: sidewalks` |
|
||||||
|
| `lane_separators` | 按 `color` 分流 | 非 yellow: `lane_separators`; yellow: `native_lane_separator_yellow`; z 取 `lane_separators` | `role: marking`, `materialLayer: lane_separators`, `splitBy.color`(yellow 特例) |
|
||||||
|
| `center_lines` | 按 `color` 分流 | 非 white: `center_lines`; white: `native_center_line_white`; z 取 `center_lines` | `role: marking`, `materialLayer: center_lines`, `splitBy.color`(white 特例) |
|
||||||
|
| `direction_arrows` | 直接渲染 | `lane_arrows_webscale` / `ROAD_LAYERS.lane_arrows_webscale` | `role: marking`, `materialLayer: lane_arrows_webscale` |
|
||||||
|
| `turn_arrows` | 直接渲染 | `lane_arrows_webscale` / `ROAD_LAYERS.lane_arrows_webscale` | `role: marking`, `materialLayer: lane_arrows_webscale` |
|
||||||
|
| `crosswalks` | 直接渲染 | `crosswalks` / `ROAD_LAYERS.crosswalks` | `role: marking`, `materialLayer: crosswalks` |
|
||||||
|
| `vehicle_stop_lines` | 直接渲染 | `vehicle_stop_lines` / `ROAD_LAYERS.vehicle_stop_lines` | `role: marking`, `materialLayer: vehicle_stop_lines` |
|
||||||
|
| `lane_centerlines` | 不进入 Blender 遍历 | 无 | `role: semantic`,Blender 跳过 |
|
||||||
|
| `connectors` | 不进入 Blender 遍历 | 无 | `role: semantic`,Blender 跳过 |
|
||||||
|
|
||||||
|
## 结论与实施约束
|
||||||
|
|
||||||
|
- manifest 必须声明全部 12 个编译器图层,不能再用“未出现在列表中”表达不渲染。
|
||||||
|
- `role: semantic` 的两个图层不得读取 GeoJSON 或创建 Blender 几何。
|
||||||
|
- `splitBy` 至少需表达属性 `color` 的精确匹配与默认分支,且分流后沿用同一个基础材质槽的 z 值。
|
||||||
|
- Blender 消费 manifest 时,未知 `materialLayer`、缺失 source 文件、或 source 未在 manifest 声明都必须报错;不能静默跳过。
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "rc-p3-render-separation",
|
||||||
|
"name": "rc-p3-render-separation",
|
||||||
|
"title": "Phase 3:道路与建筑渲染分离",
|
||||||
|
"description": "编译器输出 layer manifest 自声明图层,Blender 改为读 manifest;道路渲染从 generate_scene.py 抽离,消除跨仓库重复图层表",
|
||||||
|
"status": "planning",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-25",
|
||||||
|
"completedAt": null,
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "main",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": "08-25-road-compiler-extraction",
|
||||||
|
"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 @@
|
|||||||
|
{"_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,96 @@
|
|||||||
|
# 后续计划:drawtonomy 扩展 PoC
|
||||||
|
|
||||||
|
前置任务:`08-25-road-compiler-extraction` 的 Phase 0-3 完成并完成验收。
|
||||||
|
评估依据:父任务归档前的 `design.md` §4 决策记录 D1 / D2 / D3。
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
在**编译器仓库内**实现一个 drawtonomy 扩展:把编译产物注入其浏览器编辑器,
|
||||||
|
回读快照后走其开源导出器产出 OpenDRIVE / Lanelet2。
|
||||||
|
|
||||||
|
定位是 **PoC,不进关键路径**。目的是验证「编译器当 scene generator +
|
||||||
|
drawtonomy 当编辑器与工业格式后端」这条链路是否值得投入。
|
||||||
|
|
||||||
|
## 前提认知(已核实)
|
||||||
|
|
||||||
|
必须先明确,否则会做错方向:
|
||||||
|
|
||||||
|
- **drawtonomy 编辑器闭源**,克隆仓库只有 SDK / dev-server / mcp-server。
|
||||||
|
README 卖点里的 topology-aware lanes、lane tool、intersection templates、
|
||||||
|
Map→lanes 全部不在开源代码内。
|
||||||
|
- **它不做 raw OSM 推导**。`exporter/osmParser.ts` 是 Lanelet2 解析器
|
||||||
|
(车道左右边界已显式)。整个 exporter 目录 grep `highway` 命中 1 次且是
|
||||||
|
车道类型字符串。→ **不能替代本编译器**,只能做下游。
|
||||||
|
- **junctionTools 不能做成扩展**:无 canvas/overlay 能力、无工具注册、
|
||||||
|
**无任何 change 事件推送**(`ExtensionClient.handleMessage` 入站只有
|
||||||
|
`ext:init` / 5 个 `*-response` / `ext:error`,读取全靠轮询)。
|
||||||
|
→ junction 编辑留在自有 workbench。
|
||||||
|
- **`drawtonomy-dev-server` 是 drawtonomy.com 的缓存代理**(TTL 1 小时),
|
||||||
|
非自托管。宿主协议会漂(manifest 有 `minHostVersion`)。→ 不进关键路径。
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
### R4.1 扩展:编译产物 → 编辑器
|
||||||
|
|
||||||
|
- manifest capabilities:`shapes:write`、`ui:panel`、`snapshot:read`、`ui:notify`
|
||||||
|
- 面板调编译器的本地 HTTP 服务(`road-workbench` 已经是一个 HTTP 服务)取产物
|
||||||
|
- 车道边界 → `createLaneWithBoundaries(leftPoints, rightPoints, opts)` → `addShapes()`
|
||||||
|
- 坐标转换:本项目 WGS84/ENU(米)→ drawtonomy 画布像素。
|
||||||
|
沿用其 `drawtonomy_origin_lat/lon` + `latLonToCanvas` 约定
|
||||||
|
- ⚠️ **借它的结构,不借它的坐标系**:其 `BaseShape.x/y` 是画布像素
|
||||||
|
(`z` 注释明确写 "world units — NOT canvas pixels like x/y")。
|
||||||
|
编译器内部坐标系不得因此改变
|
||||||
|
|
||||||
|
### R4.2 回读 → 工业格式导出
|
||||||
|
|
||||||
|
- `requestSnapshot()` 取回快照
|
||||||
|
- 本地跑其开源 `exportToOpenDrive` / `lanelet2`(Apache-2.0)
|
||||||
|
- 产出 `.xodr` / `.osm`(Lanelet2),用其 `validateOpenDrive` 自校验
|
||||||
|
- Lanelet2 是 Autoware 的输入格式 —— 对本项目 V2X 方向有实际价值
|
||||||
|
|
||||||
|
### R4.3 许可与依赖合规
|
||||||
|
|
||||||
|
- drawtonomy SDK 是 Apache-2.0:借用代码需保留 NOTICE / 署名
|
||||||
|
- 若依赖 drawtonomy.com 托管服务,需查其服务条款(app 非 Apache-2.0)
|
||||||
|
- ESM/CJS 互操作:SDK 是 ESM+TS,编译器是 CJS。
|
||||||
|
本阶段可**局部**引入构建步骤,但仅限扩展目录,不得污染编译器核心
|
||||||
|
(父任务 C2 的边界)
|
||||||
|
|
||||||
|
### R4.4 归属
|
||||||
|
|
||||||
|
扩展代码放**编译器仓库**,不放宿主 —— 符合父任务「独立维护」目标。
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] AC4.1 扩展能把一个区域的编译产物注入 drawtonomy 编辑器并正确显示车道
|
||||||
|
- [ ] AC4.2 编辑器内手改后回读快照,能导出通过 `validateOpenDrive` 的 `.xodr`
|
||||||
|
- [ ] AC4.3 能导出 Lanelet2 `.osm`
|
||||||
|
- [ ] AC4.4 编译器核心未引入构建步骤(构建仅限扩展目录)
|
||||||
|
- [ ] AC4.5 编译器内部坐标系未因适配画布像素而改变
|
||||||
|
- [ ] AC4.6 Apache-2.0 署名 / NOTICE 已按要求保留
|
||||||
|
- [ ] AC4.7 结论记录:这条链路是否值得继续投入,写入任务 `research/`
|
||||||
|
|
||||||
|
## 启动条件
|
||||||
|
|
||||||
|
- 道路编译器独立化父任务(Phase 0-3)已完成验收。
|
||||||
|
- 编译器仓库、稳定 CLI 与版本化输出契约已可用。
|
||||||
|
- 此任务不阻塞道路编译器抽离或渲染分离的交付。
|
||||||
|
|
||||||
|
## 明确不做
|
||||||
|
|
||||||
|
- junctionTools 做成扩展(API 不支持,见前提认知)
|
||||||
|
- 把 drawtonomy 放进生产构建链路
|
||||||
|
- 用 drawtonomy 替代编译器(D1 已否决)
|
||||||
|
- 自建通用白板编辑器
|
||||||
|
|
||||||
|
## 后续可能(不属本阶段)
|
||||||
|
|
||||||
|
父任务 design §4 的 D3 列了三项值得从 drawtonomy 借用的东西,
|
||||||
|
它们与本阶段独立,应各自开任务:
|
||||||
|
|
||||||
|
- `odrGeometryFit.ts` 的拟合器 → 替掉手调的
|
||||||
|
`approachWidthMultiplier=1.45` / `coreRadiusMeters=28`,改为对 `referenceFile`
|
||||||
|
拟合、残差作质量指标
|
||||||
|
- validator 的 mutation-proven 方法 → 给现有 31 条诊断规则建触发证明
|
||||||
|
- validator 的分层命名空间(`xml.*` / `ref.*` / `junction.*` / `geom.*`)
|
||||||
|
→ 替代当前平铺的 31 条规则
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
{
|
||||||
|
"id": "rc-p4-drawtonomy-ext",
|
||||||
|
"name": "rc-p4-drawtonomy-ext",
|
||||||
|
"title": "后续计划:drawtonomy 扩展 PoC",
|
||||||
|
"description": "道路编译器独立化完成后,评估在编译器仓库内实现 drawtonomy 扩展:编译产物注入编辑器,快照回读后走开源 OpenDRIVE/Lanelet2 导出",
|
||||||
|
"status": "planning",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P3",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-25",
|
||||||
|
"completedAt": null,
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "main",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "不属于道路编译器独立化父任务的完成条件。父任务验收完成后,将此任务作为下一项候选任务提示。",
|
||||||
|
"meta": {
|
||||||
|
"follow_up_after": "08-25-road-compiler-extraction"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
# Native Road Parity Baselines
|
||||||
|
|
||||||
|
Generated from commit `25cf82e7c75ea8d881639c4a80648121efbd39f6` on 2026-08-25.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run road:compile -- --config config/areas/fengshu-er-road.json
|
||||||
|
node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
|
||||||
|
--snapshot .trellis/tasks/08-25-road-compiler-extraction/baseline/fengshu-er-road.json
|
||||||
|
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
node scripts/road-parity.js --config config/areas/nantaizi-lake-innovation-valley.json \
|
||||||
|
--snapshot .trellis/tasks/08-25-road-compiler-extraction/baseline/nantaizi-lake-innovation-valley.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Both samples emit all twelve native-road layers. `fengshu-er-road` enables its
|
||||||
|
configured complex-junction template; `nantaizi-lake-innovation-valley` uses
|
||||||
|
the default, template-free compiler path. `hanyang-block` is an abandoned area
|
||||||
|
and deliberately excluded from this corpus.
|
||||||
|
|
||||||
|
The snapshot normalizes absolute source paths and random `native-road-*`
|
||||||
|
staging names. It does not round coordinates or ignore feature ordering.
|
||||||
@@ -0,0 +1,108 @@
|
|||||||
|
{
|
||||||
|
"contract": "native-road-package/v1",
|
||||||
|
"areaId": "fengshu-er-road",
|
||||||
|
"files": {
|
||||||
|
"../native-traffic-signals.json": {
|
||||||
|
"contentHash": "88e7f0ef4fc7bdb9ef202af018b3fb3179035ffc8ed5eeba03276c263e1f0476",
|
||||||
|
"bytes": 5886
|
||||||
|
},
|
||||||
|
"comparison.json": {
|
||||||
|
"contentHash": "651eb4000a44a7521a79c3e1429795b83d20f8899e0c67c4bb25b56cf4a6f75d",
|
||||||
|
"bytes": 1295
|
||||||
|
},
|
||||||
|
"compiled.json": {
|
||||||
|
"contentHash": "2ab82eafcdab70155078fae3559692ef1fde0645a52c6decbaea762a9ffeb24a",
|
||||||
|
"bytes": 159230
|
||||||
|
},
|
||||||
|
"diagnostics.json": {
|
||||||
|
"contentHash": "1d9fdae06ddcbc19b5262b797a4a35c494fc30a98a66dbfa111533b12c5fdfc7",
|
||||||
|
"bytes": 6862
|
||||||
|
},
|
||||||
|
"layers/center_lines.geojson": {
|
||||||
|
"contentHash": "04db66df5821b319d59297b8515502fabcad95faf083cae19edb338be2f6024b",
|
||||||
|
"orderHash": "04db66df5821b319d59297b8515502fabcad95faf083cae19edb338be2f6024b",
|
||||||
|
"features": 5,
|
||||||
|
"bytes": 6909
|
||||||
|
},
|
||||||
|
"layers/connectors.geojson": {
|
||||||
|
"contentHash": "e7979d4642c7c10f33fb23e92721f22533a851ae1a2b4d35f224d50927bf2fe9",
|
||||||
|
"orderHash": "c327b7b154d4d9ca04cd895523eb0d8ad67c37051ef1d2135b2b46c51e12df58",
|
||||||
|
"features": 90,
|
||||||
|
"bytes": 197885
|
||||||
|
},
|
||||||
|
"layers/crosswalks.geojson": {
|
||||||
|
"contentHash": "354cd4d7ed105a11b95904b44848dce567b3a3383f76755936d8c00691fe29af",
|
||||||
|
"orderHash": "d24376438ac956bde52fcbfa955dd72c2ba31a97995608aaed1c79f6fd3633ab",
|
||||||
|
"features": 152,
|
||||||
|
"bytes": 219286
|
||||||
|
},
|
||||||
|
"layers/direction_arrows.geojson": {
|
||||||
|
"contentHash": "7b8362ad4912c997a7661befde55ddfe58757c3c8d139c15867e1938ea8f6918",
|
||||||
|
"orderHash": "5274e8b433946410a7cdffdaa452c1750e04f53e73a86bf81d034cfb26d4c254",
|
||||||
|
"features": 686,
|
||||||
|
"bytes": 1053308
|
||||||
|
},
|
||||||
|
"layers/edge_lines.geojson": {
|
||||||
|
"contentHash": "ad37fe6278e0c7caf3b77c1c5068a56e18a6c87b78ed5a840ee22a0f961ea7a8",
|
||||||
|
"orderHash": "ad37fe6278e0c7caf3b77c1c5068a56e18a6c87b78ed5a840ee22a0f961ea7a8",
|
||||||
|
"features": 0,
|
||||||
|
"bytes": 52
|
||||||
|
},
|
||||||
|
"layers/intersection_surface.geojson": {
|
||||||
|
"contentHash": "b2022ca70339aa470f3be451bf3ba2f55b59c3900645c864538372173811309f",
|
||||||
|
"orderHash": "b2022ca70339aa470f3be451bf3ba2f55b59c3900645c864538372173811309f",
|
||||||
|
"features": 5,
|
||||||
|
"bytes": 13048
|
||||||
|
},
|
||||||
|
"layers/lane_centerlines.geojson": {
|
||||||
|
"contentHash": "19c550c794810c1071de55dee158295235106a56e3877a2ba10da920ee214593",
|
||||||
|
"orderHash": "67f8e7d33ec578644416e4837dd4aafef62a55aaeb4d438d07ab07eddfbb1df1",
|
||||||
|
"features": 84,
|
||||||
|
"bytes": 73294
|
||||||
|
},
|
||||||
|
"layers/lane_separators.geojson": {
|
||||||
|
"contentHash": "02fdf2c7b6e89c2850a60ea2ac72b9f62910259bdb2949681fcaa7e67d2b51f0",
|
||||||
|
"orderHash": "81782a059c4ff9f69fdf7de9107d20a8d6cf55d34bb0620ec28a9a8c5106c982",
|
||||||
|
"features": 3596,
|
||||||
|
"bytes": 4164106
|
||||||
|
},
|
||||||
|
"layers/road_surface.geojson": {
|
||||||
|
"contentHash": "5a2936a705e64338d0d79b395a13d761f1893dd72330a9b9ee4696ae75eab295",
|
||||||
|
"orderHash": "d8402ae6e772e0778b862b190abfa291de1b02a15537d455f7dcd8596245dfd8",
|
||||||
|
"features": 30,
|
||||||
|
"bytes": 49554
|
||||||
|
},
|
||||||
|
"layers/sidewalk_surface.geojson": {
|
||||||
|
"contentHash": "b6f8f876e9f18fd2ef6749125a09d654c73d986e916bd262ceb9967bca1a54c6",
|
||||||
|
"orderHash": "3fd42a67e18e3b8743fa538428e039ef66a1f44150a6881a7aaa18326607b5cb",
|
||||||
|
"features": 26,
|
||||||
|
"bytes": 54997
|
||||||
|
},
|
||||||
|
"layers/turn_arrows.geojson": {
|
||||||
|
"contentHash": "ad37fe6278e0c7caf3b77c1c5068a56e18a6c87b78ed5a840ee22a0f961ea7a8",
|
||||||
|
"orderHash": "ad37fe6278e0c7caf3b77c1c5068a56e18a6c87b78ed5a840ee22a0f961ea7a8",
|
||||||
|
"features": 0,
|
||||||
|
"bytes": 52
|
||||||
|
},
|
||||||
|
"layers/vehicle_stop_lines.geojson": {
|
||||||
|
"contentHash": "cb904550ab8eec011cf33e5edfa81044de6dfca0280dbfe488e77229055ed590",
|
||||||
|
"orderHash": "8a4b877a17a5af60adc8656465afad6756944736291664139e878d46c5a4f363",
|
||||||
|
"features": 4,
|
||||||
|
"bytes": 4191
|
||||||
|
},
|
||||||
|
"traffic-signal-assemblies.json": {
|
||||||
|
"contentHash": "1788026a0c8c531b2fc7dd49628f7fbadd809c7b2f7f8819cffb3ac7d30689ca",
|
||||||
|
"orderHash": "b409ea6b77b6c8639f63c33a156581f9b184a84fde34d265b5deb05705828251",
|
||||||
|
"features": 7,
|
||||||
|
"bytes": 5411
|
||||||
|
},
|
||||||
|
"traffic-signals.json": {
|
||||||
|
"contentHash": "625b79b6eb82b41f2099ba51960717c7f794fdfbd87310eb12e99da966540d89",
|
||||||
|
"bytes": 15491
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"volatileExcluded": [
|
||||||
|
"absolute paths -> <repo> or <external>",
|
||||||
|
"native-road-* staging directory -> <staging>"
|
||||||
|
]
|
||||||
|
}
|
||||||
+108
@@ -0,0 +1,108 @@
|
|||||||
|
{
|
||||||
|
"contract": "native-road-package/v1",
|
||||||
|
"areaId": "nantaizi-lake-innovation-valley",
|
||||||
|
"files": {
|
||||||
|
"../native-traffic-signals.json": {
|
||||||
|
"contentHash": "36cb9f069fb44a6e24f0af0d130ef8cb5b4a93250dc9fb0891191d1ba039a5b2",
|
||||||
|
"bytes": 28329
|
||||||
|
},
|
||||||
|
"comparison.json": {
|
||||||
|
"contentHash": "5aa11da443221a48288641ac6950c6e4d75d834713a93110bbf265859202a265",
|
||||||
|
"bytes": 1153
|
||||||
|
},
|
||||||
|
"compiled.json": {
|
||||||
|
"contentHash": "ea5ae4a04f1259b1ccec9fc1cca7ef8ba81426a77584a447480b6047b37f5e01",
|
||||||
|
"bytes": 184985
|
||||||
|
},
|
||||||
|
"diagnostics.json": {
|
||||||
|
"contentHash": "7e9327f0424dd612f389c560c114a4cafee1349bbfa36f49b2b4eab846e5ca91",
|
||||||
|
"bytes": 9755
|
||||||
|
},
|
||||||
|
"layers/center_lines.geojson": {
|
||||||
|
"contentHash": "2b2710fce06e75b0a3e4941c2da6119cea7b8bb7834345607bbee384de20ee6b",
|
||||||
|
"orderHash": "ea71a8841370689d6fc2b75d0b30ec7104638fb2904da6d707dc82ff3131e065",
|
||||||
|
"features": 511,
|
||||||
|
"bytes": 694102
|
||||||
|
},
|
||||||
|
"layers/connectors.geojson": {
|
||||||
|
"contentHash": "901a86bc6c536d38bb73ae4654ec1ce7d1c0790c2d6eba92543c48f584cd15ac",
|
||||||
|
"orderHash": "4df882ad59b65a97d892df64de0156b35beaf071b04eed671ef7b535e9e2a7b9",
|
||||||
|
"features": 76,
|
||||||
|
"bytes": 160866
|
||||||
|
},
|
||||||
|
"layers/crosswalks.geojson": {
|
||||||
|
"contentHash": "53fda76182c0d1db5f9e7ac284337ece62655d7fee8bb446fe170ea26abe8bbc",
|
||||||
|
"orderHash": "53fda76182c0d1db5f9e7ac284337ece62655d7fee8bb446fe170ea26abe8bbc",
|
||||||
|
"features": 48,
|
||||||
|
"bytes": 50536
|
||||||
|
},
|
||||||
|
"layers/direction_arrows.geojson": {
|
||||||
|
"contentHash": "38e80bbfe02d4f12ce40e7d0c8342e3bef6b602c64f81dd320b366b6a6b3d205",
|
||||||
|
"orderHash": "579aa6c37585bf4edf9d6b6b1e120f976b93ec2d0c303d82a154b75c114a45f5",
|
||||||
|
"features": 324,
|
||||||
|
"bytes": 493431
|
||||||
|
},
|
||||||
|
"layers/edge_lines.geojson": {
|
||||||
|
"contentHash": "ad37fe6278e0c7caf3b77c1c5068a56e18a6c87b78ed5a840ee22a0f961ea7a8",
|
||||||
|
"orderHash": "ad37fe6278e0c7caf3b77c1c5068a56e18a6c87b78ed5a840ee22a0f961ea7a8",
|
||||||
|
"features": 0,
|
||||||
|
"bytes": 52
|
||||||
|
},
|
||||||
|
"layers/intersection_surface.geojson": {
|
||||||
|
"contentHash": "7f79e57215e3fd07c5c0f703c71e516873db770cb869efdf18925a3184059ca3",
|
||||||
|
"orderHash": "d69df8d92d0fce8f7ee172959b978d941fd011e094857e9ab7304b3d1e98bf92",
|
||||||
|
"features": 12,
|
||||||
|
"bytes": 38528
|
||||||
|
},
|
||||||
|
"layers/lane_centerlines.geojson": {
|
||||||
|
"contentHash": "3fea4ebfe62e0d720c6977e2289f4e6517ed7b3c5ab361270d03378971aec780",
|
||||||
|
"orderHash": "69a8ebaa42a74da4f7d5940c5a81bd82ceb104efd3f858723dccfadbae12121e",
|
||||||
|
"features": 50,
|
||||||
|
"bytes": 43582
|
||||||
|
},
|
||||||
|
"layers/lane_separators.geojson": {
|
||||||
|
"contentHash": "dc0b50b53da191e65f3dba01162acb7561966d1796a9c0789527cebfd6ed06a4",
|
||||||
|
"orderHash": "0bfd873e5698869fb4855783fe30bb6db29456958e4d154b7264374a5fdb4a10",
|
||||||
|
"features": 731,
|
||||||
|
"bytes": 835933
|
||||||
|
},
|
||||||
|
"layers/road_surface.geojson": {
|
||||||
|
"contentHash": "81af19c71cf6fc8a3884488c00cfb590e1a7fe9ed9e4351fce65825ceadd50fa",
|
||||||
|
"orderHash": "f2ddec5258411fbdbc050b7ecefbb157b59e00b8226afcc30d2b772e1859e357",
|
||||||
|
"features": 25,
|
||||||
|
"bytes": 38275
|
||||||
|
},
|
||||||
|
"layers/sidewalk_surface.geojson": {
|
||||||
|
"contentHash": "bb8f4516e27b16238d753b112d18b8acfa5cfad2cea522a65b7972a609be9563",
|
||||||
|
"orderHash": "4fa773a6f39c5b6d23551e1338c6d99ef8a5ecd9ebfcafa16154c9765fef8c6e",
|
||||||
|
"features": 73,
|
||||||
|
"bytes": 122432
|
||||||
|
},
|
||||||
|
"layers/turn_arrows.geojson": {
|
||||||
|
"contentHash": "a65bb8fe079f27e00bf2e6208148fc6b73d2d07e76d48b1cd1bf8a610d7e2d66",
|
||||||
|
"orderHash": "66966ac2c65464f9c6715ca9cda5a3620520bf1d066cba2dee36114dc46af936",
|
||||||
|
"features": 108,
|
||||||
|
"bytes": 132536
|
||||||
|
},
|
||||||
|
"layers/vehicle_stop_lines.geojson": {
|
||||||
|
"contentHash": "4f45caf3c0bf13bbf10d9cac15fa80b1a9be3969ed84803ba48e56c4a0080992",
|
||||||
|
"orderHash": "4f45caf3c0bf13bbf10d9cac15fa80b1a9be3969ed84803ba48e56c4a0080992",
|
||||||
|
"features": 8,
|
||||||
|
"bytes": 8475
|
||||||
|
},
|
||||||
|
"traffic-signal-assemblies.json": {
|
||||||
|
"contentHash": "9f8d032c00784bb72bb1322238cd7b0a80e621d435b43c728da86f1e77ca352a",
|
||||||
|
"orderHash": "0b9cae13094dba1994faca4bf1d4d80e8bc5497daa46df5899bf5e6fc7f26d61",
|
||||||
|
"features": 35,
|
||||||
|
"bytes": 26398
|
||||||
|
},
|
||||||
|
"traffic-signals.json": {
|
||||||
|
"contentHash": "c4b68cc1cefeb0d393a18eef6c7eb79933fba28630826745165ed433c25779d0",
|
||||||
|
"bytes": 74151
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"volatileExcluded": [
|
||||||
|
"absolute paths -> <repo> or <external>",
|
||||||
|
"native-road-* staging directory -> <staging>"
|
||||||
|
]
|
||||||
|
}
|
||||||
@@ -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,294 @@
|
|||||||
|
# 道路编译器独立化 — 技术设计(parent)
|
||||||
|
|
||||||
|
本文件是 **契约的权威定义**,供所有子任务引用。
|
||||||
|
Phase 0 的交付物是把本节内容落成编译器仓库内的正式文档 + 校验脚本,
|
||||||
|
而不是重新发明契约。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 契约:`native-road-package/v1`
|
||||||
|
|
||||||
|
### 1.1 输入契约
|
||||||
|
|
||||||
|
现状:`compile-native-roads.js` 接收整个 normalized areaConfig,但**实际只用 9 个字段**。
|
||||||
|
|
||||||
|
```
|
||||||
|
area.id → areaId
|
||||||
|
area.input → osmFile (OSM XML 路径)
|
||||||
|
area.nativeRoad.edgeLines → options.edgeLines
|
||||||
|
area.nativeRoad.junctionTemplates → options.junctionTemplates
|
||||||
|
area.outputs.nativeRoadOverrides → overridesFile
|
||||||
|
area.outputs.nativeTrafficSignals → trafficSignalsFile
|
||||||
|
area.outputs.nativeRoadDir → outDir
|
||||||
|
area.outputs.pipelineDir → stagingDir
|
||||||
|
area.outputs.geojsonDir → comparisonDir (见 K2,倾向移除)
|
||||||
|
```
|
||||||
|
|
||||||
|
目标形状:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// RoadCompilerInput —— 编译器唯一入口参数
|
||||||
|
{
|
||||||
|
areaId: string,
|
||||||
|
osmFile: string, // 绝对路径
|
||||||
|
outDir: string, // native-road/ 的目标位置
|
||||||
|
stagingDir: string, // 原子提升用的临时目录父级
|
||||||
|
overridesFile: string,
|
||||||
|
trafficSignalsFile: string,
|
||||||
|
options: {
|
||||||
|
edgeLines: boolean,
|
||||||
|
junctionTemplates: {
|
||||||
|
enabled: boolean,
|
||||||
|
references: [],
|
||||||
|
clusters: [{ id, template, referenceFile, nodeIds, ...几何参数 }]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**宿主侧责任**:`scripts/lib/area-config.js` 把 areaConfig 映射成 `RoadCompilerInput`。
|
||||||
|
**编译器侧责任**:不认识 areaConfig,不读 `config/areas/*.json`,不推导任何路径。
|
||||||
|
|
||||||
|
### 1.2 输出契约
|
||||||
|
|
||||||
|
`compiled.json` 顶层键(已核实):
|
||||||
|
|
||||||
|
```
|
||||||
|
schema, areaId, source, model, movements, trafficSignals, diagnostics, layers
|
||||||
|
```
|
||||||
|
|
||||||
|
`source` 含 `{ osm, overrides, trafficSignals }` 三个路径 —— 是 parity 归一化的重点对象。
|
||||||
|
|
||||||
|
```
|
||||||
|
<outDir>/ # 原子提升:先写 staging 再 rename
|
||||||
|
manifest.json # ← Phase 3 新增,图层自声明
|
||||||
|
compiled.json # 单一读模型,含 model + movements
|
||||||
|
diagnostics.json # severity / subject / sourceIds / rule / message / geometry?
|
||||||
|
comparison.json # ← 见 K2,可能移除
|
||||||
|
layers/
|
||||||
|
road_surface.geojson
|
||||||
|
intersection_surface.geojson
|
||||||
|
sidewalk_surface.geojson
|
||||||
|
edge_lines.geojson
|
||||||
|
lane_separators.geojson
|
||||||
|
center_lines.geojson
|
||||||
|
crosswalks.geojson
|
||||||
|
vehicle_stop_lines.geojson
|
||||||
|
direction_arrows.geojson
|
||||||
|
turn_arrows.geojson
|
||||||
|
lane_centerlines.geojson # 语义层,不渲染
|
||||||
|
connectors.geojson # 语义层,不渲染
|
||||||
|
|
||||||
|
<trafficSignalsFile> # 兄弟文件,不在 outDir 内
|
||||||
|
```
|
||||||
|
|
||||||
|
**stdout 完成标记**(与宿主 `SCENE_DONE` / `CESIUM_EXPORT_DONE` 同约定):
|
||||||
|
|
||||||
|
```
|
||||||
|
NATIVE_ROAD_COMPILE_DONE {"areaId":…,"roads":N,"endpoints":N,"diagnostics":N,"output":…,"comparison":…}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.3 消费方式:子进程为主契约
|
||||||
|
|
||||||
|
| 方式 | 定位 |
|
||||||
|
|---|---|
|
||||||
|
| CLI 子进程 + 读 `outDir` + 解析 stdout 标记 | **主契约**。宿主 pipeline 层本就是唯一能启动外部进程的层 |
|
||||||
|
| `require()` in-process | 仅作性能优化,不得成为唯一路径 |
|
||||||
|
|
||||||
|
选子进程的理由:
|
||||||
|
1. 语言无关 —— 编译器将来若换 TS/Rust,宿主零改动。
|
||||||
|
2. 强制文件契约成为真契约,无法偷传对象绕过边界。
|
||||||
|
3. 与既有 QGIS / GDAL / Blender 调用方式一致。
|
||||||
|
|
||||||
|
`build-area.js:7` 现在是 in-process `require`。Phase 2 改为子进程调用。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 模块清单:什么搬、什么留
|
||||||
|
|
||||||
|
### 2.1 搬(约 3400 行核心 + workbench)
|
||||||
|
|
||||||
|
| 文件 | 行数 | 依赖 |
|
||||||
|
|---|---|---|
|
||||||
|
| `scripts/lib/native-road.js` | 1695 | fs, path, turn-lane-arrows, complex-junction |
|
||||||
|
| `scripts/lib/complex-junction.js` | 474 | fs, gaode-junction-reference |
|
||||||
|
| `scripts/lib/turn-lane-arrows.js` | 502 | fs, path, lane-geometry |
|
||||||
|
| `scripts/lib/gaode-junction-reference.js` | 231 | fs |
|
||||||
|
| `scripts/lib/lane-geometry.js` | 161 | 无(纯函数) |
|
||||||
|
| `scripts/lib/native-traffic-signals.js` | 49 | osm, traffic-signals ← **见 K1** |
|
||||||
|
| `scripts/lib/osm.js` | 102 | 无 |
|
||||||
|
| `scripts/compile-native-roads.js` | — | area-config ← **要换成窄契约** |
|
||||||
|
| `scripts/check-native-roads.js` | — | area-config ← 同上 |
|
||||||
|
| `scripts/road-workbench.js` + `scripts/workbench/app.js` | 173 + — | area-config ← 同上 |
|
||||||
|
| `scripts/test-native-road.js`、`scripts/test-road-workbench.js` | — | fixture ← **见 K5** |
|
||||||
|
|
||||||
|
依赖图(已核实,`native-road.js` 对宿主零耦合):
|
||||||
|
|
||||||
|
```
|
||||||
|
native-road.js ──→ turn-lane-arrows ──→ lane-geometry (纯)
|
||||||
|
└──────────→ complex-junction ──→ gaode-junction-reference
|
||||||
|
native-traffic-signals ──→ osm.js
|
||||||
|
└──→ traffic-signals.js ← 共用,需拆
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 留
|
||||||
|
|
||||||
|
- `scripts/lib/area-config.js` —— 宿主拥有,新增 `toRoadCompilerInput()` 映射
|
||||||
|
- `scripts/build-area.js` —— 改为子进程调用编译器
|
||||||
|
- `scripts/lib/traffic-signals.js` 的 legacy 读取器部分(见 K1)
|
||||||
|
- `blender/` 全部 —— Phase 3 内部重组,但不搬出仓库
|
||||||
|
- `scripts/lib/scene-layers.js`、osm2streets / QGIS legacy 链路 —— 完全不动
|
||||||
|
|
||||||
|
### 2.3 K1 的拆分建议(Phase 1 需细读确认)
|
||||||
|
|
||||||
|
`lib/traffic-signals.js` 当前混了两类东西:
|
||||||
|
|
||||||
|
| 类别 | 使用方 | 归属 |
|
||||||
|
|---|---|---|
|
||||||
|
| OSM 信号节点提取 + 信号文档 schema | `native-traffic-signals.js` | **随编译器走** —— 编译器生成该文档,就该拥有其契约 |
|
||||||
|
| `readTrafficSignalFeatures` | `build-osm2streets-qgis.js` | 留宿主 |
|
||||||
|
| `readTrafficSignals` | `build-area.js` | 留宿主 |
|
||||||
|
| `buildTrafficSignals` | `test-preview-assets.js` | 待判定 |
|
||||||
|
|
||||||
|
拆完后宿主从编译器包 import 信号文档 schema,反向依赖为 0 不受影响
|
||||||
|
(宿主依赖编译器是允许的方向)。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Phase 3:渲染分离的设计
|
||||||
|
|
||||||
|
### 3.1 现状问题
|
||||||
|
|
||||||
|
`blender/osmassets/catalog.py:53` 的 `NATIVE_ROAD_LAYERS` 是一张跨仓库重复表:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 注释自陈:"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"},
|
||||||
|
... 共 10 项
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
编译器写 12 个 geojson,这张表只列 10 项 —— `lane_centerlines` / `connectors`
|
||||||
|
是语义层不参与渲染。**但这个事实只存在于这张表的省略里,编译器侧没有任何声明。**
|
||||||
|
|
||||||
|
后果:编译器新增图层 → 必须有人记得去另一个仓库改 `catalog.py` → 忘了就静默少渲染一层。
|
||||||
|
这正是 `.trellis/spec/pipeline/index.md` 首页警告的「最容易出静默错误」。
|
||||||
|
|
||||||
|
### 3.2 目标:编译器自声明图层
|
||||||
|
|
||||||
|
`<outDir>/manifest.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"contract": "native-road-package/v1",
|
||||||
|
"areaId": "fengshu-er-road",
|
||||||
|
"layers": [
|
||||||
|
{ "source": "road_surface", "role": "surface",
|
||||||
|
"materialLayer": "road_surface" },
|
||||||
|
|
||||||
|
{ "source": "lane_centerlines", "role": "semantic" },
|
||||||
|
{ "source": "connectors", "role": "semantic" },
|
||||||
|
|
||||||
|
{ "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": "lane_separators", "role": "marking",
|
||||||
|
"materialLayer": "lane_separators",
|
||||||
|
"splitBy": { "prop": "color",
|
||||||
|
"cases": [ { "match": "yellow", "material": "native_lane_separator_yellow" },
|
||||||
|
{ "default": true, "material": "lane_separators" } ] } }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `role: "semantic"` 的图层 Blender 直接跳过 —— 把"不渲染"从省略变成显式声明。
|
||||||
|
- `splitBy` 表达当前 `generate_scene.py:815-819` 里硬编码的
|
||||||
|
`color != "white"` / `color == "yellow"` 分流逻辑。
|
||||||
|
- 材质本体(颜色、z 高度、贴图)仍归宿主 `catalog.py::MATERIALS` —— 编译器不懂渲染。
|
||||||
|
编译器只声明"我有这些图层、它们是什么角色、该用哪个材质槽"。
|
||||||
|
|
||||||
|
### 3.3 Blender 侧改造
|
||||||
|
|
||||||
|
- `generate_scene.py` 内道路分支抽为 `blender/osmassets/native_roads.py`,读 manifest 遍历。
|
||||||
|
- 建筑(`handle_building` / `dispatch_ways`)、植被、水体保持原位不动。
|
||||||
|
- `catalog.NATIVE_ROAD_LAYERS` 删除。
|
||||||
|
|
||||||
|
### 3.4 AC5 的验证方法
|
||||||
|
|
||||||
|
向编译器加一个 throwaway 图层(例如 `debug_probe.geojson` + manifest 声明),
|
||||||
|
不改宿主任何代码,跑 blender 阶段,确认它被渲染出来。验证完回滚该图层。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 决策记录
|
||||||
|
|
||||||
|
### D1 不用 drawtonomy 替代编译器 ❌
|
||||||
|
|
||||||
|
评估结论(2026-08-25):
|
||||||
|
|
||||||
|
- 克隆仓库内**没有编辑器本体**。`packages/` 只有 SDK / dev-server / mcp-server;
|
||||||
|
白板闭源,托管在 drawtonomy.com。README 卖点里的 topology-aware lanes、
|
||||||
|
lane tool、intersection/roundabout templates、Map→lanes **全部不在开源代码内**。
|
||||||
|
- **它完全不做 raw OSM 推导**。`exporter/osmParser.ts` 首行自陈是
|
||||||
|
"Lanelet2 OSM (.osm XML) parser" —— 读的是 Lanelet2(车道左右边界已显式)。
|
||||||
|
整个 `exporter/` 目录 grep `highway` 命中 1 次,是 `opendrive.ts:685` 的
|
||||||
|
车道类型字符串,不是 OSM 标签解析。从不读 `highway=*` / `lanes` / `turn:lanes`。
|
||||||
|
- 本编译器的核心能力恰是"从稀疏有歧义的中国 OSM 标签推导车道几何",方向垂直。
|
||||||
|
- 语义成熟度对比:本编译器有逐值 provenance
|
||||||
|
(`tag:lanes:forward` / `inferred:highway-default` / `override:<id>`)+ 31 条语义诊断规则;
|
||||||
|
drawtonomy SDK 两者皆无,其 25 条校验规则全是 OpenDRIVE 结构/XML 完整性检查。
|
||||||
|
|
||||||
|
### D2 drawtonomy 作为**下游后端 + 编辑器**(后续独立 PoC)✅
|
||||||
|
|
||||||
|
可用能力(扩展 API,`types.ts:257` 8 个 capability):
|
||||||
|
`shapes:write` + `ui:panel` 足以把编译产物注入编辑器;
|
||||||
|
`snapshot:read` 回读后由本地跑其开源 `exportToOpenDrive` / `lanelet2`。
|
||||||
|
|
||||||
|
不可用能力(决定 junctionTools 不能做成扩展):
|
||||||
|
- 无 canvas / overlay 能力,UI 只能是侧栏 iframe
|
||||||
|
- 无工具注册,画布指针事件完全归宿主
|
||||||
|
- **无任何 change 事件推送** —— `ExtensionClient.handleMessage` 入站只有
|
||||||
|
`ext:init` / 按 requestId 匹配的 5 个 `*-response` / `ext:error`,所有读取靠轮询
|
||||||
|
|
||||||
|
结论:junctionTools 留在自有 workbench(画布自己的,可任意绘制)。
|
||||||
|
drawtonomy 承担场景编排 + 工业格式导出。二者是不同的活,不强行合并 UI。
|
||||||
|
|
||||||
|
依赖风险记录:`drawtonomy-dev-server` 是 `https://www.drawtonomy.com` 的
|
||||||
|
**缓存代理**(TTL 1 小时),非自托管。manifest 有 `minHostVersion` 字段,
|
||||||
|
说明宿主协议会漂。后续 PoC 不把它放进关键路径。
|
||||||
|
|
||||||
|
### D3 值得从 drawtonomy 借用的(Apache-2.0,需保留 NOTICE/署名)
|
||||||
|
|
||||||
|
| 来源 | 行数 | 用途 | 建议阶段 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `exporter/odrGeometryFit.ts` | 610 | 折线→解析曲线拟合(中位数去噪 + 贪心生长 + 最简原语优先 + 逐拟合回验 + G1 硬不变量)。可替掉手调的 `approachWidthMultiplier=1.45` / `coreRadiusMeters=28`,改为对 `referenceFile` 拟合、残差作质量指标 | 拆分后独立任务 |
|
||||||
|
| validator 的 mutation-proven 方法 | — | 故意破坏合法输入、断言校验器必须抓到。本编译器 31 条诊断规则目前无任何触发证明 | 拆分后独立任务,成本低 |
|
||||||
|
| validator 的分层 + 命名空间(`xml.*` → `ref.*` → `junction.*` → `geom.*`) | — | 替代当前 31 条平铺规则 | 同上 |
|
||||||
|
| OpenDRIVE + Lanelet2 导出器 | 3059 + 869 | 补齐工业格式输出(Lanelet2 是 Autoware 的输入格式) | 后续独立 PoC |
|
||||||
|
|
||||||
|
### D4 为什么 Phase 1 与 Phase 2 必须分开
|
||||||
|
|
||||||
|
Phase 1 只改"包边界与入口契约",仓库不变 → 若产物变化,成因必在代码改动。
|
||||||
|
Phase 2 只改"仓库位置与消费方式",代码不变 → 若产物变化,成因必在搬迁。
|
||||||
|
合并执行则两者混淆,parity oracle 失去诊断价值。
|
||||||
|
|
||||||
|
### D5 IR 重构推迟到拆分之后
|
||||||
|
|
||||||
|
见 prd.md C1。拆分的正确性完全建立在"产物逐字节不变"上,
|
||||||
|
同期改 IR 会同时摧毁 oracle 与归因能力。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 回滚形状
|
||||||
|
|
||||||
|
| Phase | 回滚方式 |
|
||||||
|
|---|---|
|
||||||
|
| 0 | 无代码改动,仅新增文档与基线,无需回滚 |
|
||||||
|
| 1 | `git revert`;`packages/road-compiler/` 与旧 `scripts/lib/*` 并存过渡期内可切回旧路径 |
|
||||||
|
| 2 | 宿主依赖回指本仓库内路径(`file:packages/road-compiler`),编译器仓库保留不动 |
|
||||||
|
| 3 | Blender 侧恢复 `catalog.NATIVE_ROAD_LAYERS`,manifest 保留但不消费 |
|
||||||
@@ -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,139 @@
|
|||||||
|
# 道路编译器独立化(parent)
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
把 native road compiler 从本仓库拆成可独立维护的项目,与本项目通过**版本化文件契约**相辅相成;
|
||||||
|
同时把道路渲染与 OSM 建筑渲染分离,使二者可各自演进。
|
||||||
|
|
||||||
|
本任务是 parent:它拥有源需求、契约定义、子任务地图、跨子任务验收标准和最终集成评审。
|
||||||
|
**它自身不承担实现工作**,所有可交付物在子任务中完成。
|
||||||
|
|
||||||
|
## 背景:为什么现在拆
|
||||||
|
|
||||||
|
- `scripts/lib/native-road.js` 已 1695 行,`compileGeometry()` 单函数编排 15+ 个 pass,
|
||||||
|
顺序依赖只由行号编码,每加一个特性就往既有函数尾部挂位置参数
|
||||||
|
(`compileLaneMarkings` 已 7 个位置参数)。
|
||||||
|
- 道路与建筑渲染纠缠在 `blender/generate_scene.py` 一个脚本内,
|
||||||
|
道路图层表 `NATIVE_ROAD_LAYERS` 硬编码在 `blender/osmassets/catalog.py:53`。
|
||||||
|
- 道路编译的迭代节奏(几何、路口、标线、V2X 语义)与建筑/植被/水体渲染完全不同,
|
||||||
|
放在一个仓库里互相牵制。
|
||||||
|
|
||||||
|
拆分的可行性前提(已核实):
|
||||||
|
- `native-road.js` 只 require `fs` / `path` / 两个同族道路模块,**对宿主项目零耦合**。
|
||||||
|
- 对宿主的唯一耦合是三个 CLI 入口里的 `readAreaConfig`。
|
||||||
|
- 输出侧 `native-road/` **已经是文件契约**,`blender/generate_scene.py:801` 按图层名读取。
|
||||||
|
- stdout 标记 `NATIVE_ROAD_COMPILE_DONE` 已存在,与 `SCENE_DONE` / `CESIUM_EXPORT_DONE`
|
||||||
|
同一约定 —— 子进程边界事实上已预留。
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
### R1 契约先行
|
||||||
|
|
||||||
|
- R1.1 输入输出契约必须在任何代码移动之前写死并版本化为 `native-road-package/v1`,
|
||||||
|
命名对齐既有 `osm-asset-package/v1` 约定。
|
||||||
|
- R1.2 契约的权威定义见本任务 `design.md`;Phase 0 负责把它落成仓库内文档 + 校验脚本。
|
||||||
|
|
||||||
|
### R2 可证明的等价性
|
||||||
|
|
||||||
|
- R2.1 拆分过程中每一步都必须对两个有效区域
|
||||||
|
(`fengshu-er-road` / `nantaizi-lake-innovation-valley`)
|
||||||
|
验证产物与基线一致。
|
||||||
|
- R2.2 任何差异必须逐条书面解释后才可接受,禁止"看起来差不多"。
|
||||||
|
- R2.3 验证方法沿用既有 `.trellis/spec/guides/artifact-parity-guide.md`。
|
||||||
|
|
||||||
|
### R3 独立可维护
|
||||||
|
|
||||||
|
- R3.1 拆出的项目必须能脱离宿主自测(自带 fixture,不读宿主 `inputs/` 或 `outputs/`)。
|
||||||
|
- R3.2 保留 git 历史(`git subtree split` 或 `git filter-repo`)——
|
||||||
|
1695 行几何逻辑的 blame 是踩坑记录,丢失后无人敢改。
|
||||||
|
- R3.3 编译器不得反向依赖宿主任何模块、配置或目录布局。
|
||||||
|
|
||||||
|
### R4 相辅相成(防漂移)
|
||||||
|
|
||||||
|
四个机制缺一不可:
|
||||||
|
|
||||||
|
| 机制 | 作用 | 落地于 |
|
||||||
|
|---|---|---|
|
||||||
|
| `native-road-package/v1` 版本号 | 破坏性变更必须升版本,宿主主动 opt-in | Phase 0 |
|
||||||
|
| 编译器自声明图层(layer manifest) | 加图层不需要改宿主代码 | Phase 3 |
|
||||||
|
| 两区域 parity 基线留在编译器仓库当测试语料 | 编译器无法静默弄坏宿主 | Phase 0 → Phase 2 |
|
||||||
|
| 宿主锁版本依赖,不用 `latest` | 升级是决定,不是意外 | Phase 2 |
|
||||||
|
|
||||||
|
### R5 渲染分离
|
||||||
|
|
||||||
|
- R5.1 道路图层表必须从宿主 `catalog.py` 的硬编码变为编译器输出的 manifest。
|
||||||
|
- R5.2 `blender/generate_scene.py` 内道路渲染分支抽离为独立模块;
|
||||||
|
建筑 / 植被 / 水体保持原位。
|
||||||
|
- R5.3 分离后,编译器新增图层不需要修改宿主任何代码即可被渲染。
|
||||||
|
|
||||||
|
## Constraints(硬约束)
|
||||||
|
|
||||||
|
### C1 不得在拆分过程中重构 IR 🔴
|
||||||
|
|
||||||
|
lane graph 提为一等 IR 是正确方向,但**必须在 Phase 2 完成之后作为独立任务**。
|
||||||
|
|
||||||
|
理由:拆分的正确性完全依赖"产物逐字节不变"这一 oracle。
|
||||||
|
一旦同时改 IR,oracle 失效,且无法判断产物变化来自搬迁还是重设计。
|
||||||
|
|
||||||
|
未来若做,形式是**新增输出**而非替换 `compiled.json`,
|
||||||
|
靠"解锁 drawtonomy / OpenDRIVE / Lanelet2 导出"赚取存在理由。
|
||||||
|
|
||||||
|
### C2 拆分期不引入构建步骤
|
||||||
|
|
||||||
|
编译器保持 CommonJS、无构建步骤,与宿主 pipeline 层运行时一致
|
||||||
|
(见 `.trellis/spec/pipeline/index.md`)。
|
||||||
|
TypeScript / ESM 是独立决策;若后续 drawtonomy PoC 需要 SDK 互操作,只能在其独立任务的扩展目录内处理。
|
||||||
|
|
||||||
|
### C3 Phase 1 必须先于 Phase 2
|
||||||
|
|
||||||
|
"包边界"与"换仓库"分两步做。合并执行时若产物变化,无法区分成因。
|
||||||
|
|
||||||
|
## 子任务地图
|
||||||
|
|
||||||
|
| Phase | 子任务 | 交付物 | 阻塞后续 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 0 | `08-25-rc-p0-contract-baseline` | 契约文档 + 两区域 checksum 基线 + 校验脚本 | 是 |
|
||||||
|
| 1 | `08-25-rc-p1-package-boundary` | 本仓库内 `packages/road-compiler/`,窄输入契约 | 是 |
|
||||||
|
| 2 | `08-25-rc-p2-repo-split` | 独立仓库 + 宿主锁版本消费 | 是 |
|
||||||
|
| 3 | `08-25-rc-p3-render-separation` | layer manifest + Blender 道路模块抽离 | 否 |
|
||||||
|
|
||||||
|
顺序约束:**0 → 1 → 2 必须串行**。3 依赖 2 完成。
|
||||||
|
|
||||||
|
## 跨子任务验收标准
|
||||||
|
|
||||||
|
- [ ] AC1 Phase 0 基线建立后,两区域每个输出文件的 checksum 已提交进版本控制
|
||||||
|
- [ ] AC2 Phase 1 结束时,`npm run build:area` 两区域产物对 AC1 基线逐字节一致
|
||||||
|
- [ ] AC3 Phase 2 结束时,宿主从打包依赖构建,两区域 parity 仍成立
|
||||||
|
- [ ] AC4 Phase 2 结束时,编译器仓库 `npm test` 在不访问宿主仓库的情况下通过
|
||||||
|
- [ ] AC5 Phase 3 结束时,向编译器新增一个图层,宿主**零代码改动**即可渲染出来(实测验证)
|
||||||
|
- [ ] AC6 Phase 3 结束时,`.blend` 结构摘要对基线一致(走 artifact-parity-guide)
|
||||||
|
- [ ] AC7 全程未修改 `compiled.json` 的结构(C1 未被违反)
|
||||||
|
- [ ] AC8 编译器仓库对宿主的反向依赖数为 0(grep 验证)
|
||||||
|
|
||||||
|
## 已识别风险(跨子任务,逐个必须有归属)
|
||||||
|
|
||||||
|
| # | 风险 | 归属 Phase | 处置 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| K1 | `lib/traffic-signals.js` 是真共用模块:`reimport-gpkg.js` / `build-osm2streets-qgis.js` / `build-area.js` / `test-preview-assets.js` 都在用,而 `native-traffic-signals.js` 也依赖它 | 1 | 需细读后拆分:信号文档 schema + OSM 信号节点提取随编译器走(编译器生成它就该拥有契约),legacy QGIS/预览读取器留宿主。**全案唯一需要细读再动的地方** |
|
||||||
|
| K2 | `comparison.json` 依赖宿主产物 —— `compile-native-roads.js:87` 读 `area.outputs.geojsonDir` 里 osm2streets 输出做对比,拆出后摸不到 | 0(决策)/ 1(执行) | osm2streets 已 legacy,倾向直接砍掉,用高德参考 + 规范校验取代。决策需在 Phase 0 定档 |
|
||||||
|
| K3 | config 内绝对路径指向宿主仓库:`config/areas/fengshu-er-road.json` 的 `referenceFile: "/Users/que01/osm2streets-qgis-workflow/inputs/osm/珠山湖大道(枫树二路)口.geojson"` | 1 | 需定参考文件解析约定(相对 config 目录 / 显式 basePath) |
|
||||||
|
| K4 | workbench 的 OpenLayers 来自宿主 `node_modules`(design.md 的 import map 方案) | 2 | 新仓库自带依赖 |
|
||||||
|
| K5 | 测试 fixture 依赖宿主:`test-native-road.js:167` 读 `inputs/osm/枫树二路.osm`,其余为内联合成 OSM | 1 | 该文件(或裁剪版)作为测试数据提交进编译器仓库 |
|
||||||
|
|
||||||
|
## Out of Scope
|
||||||
|
|
||||||
|
- lane graph IR 重构(见 C1,未来独立任务)
|
||||||
|
- pass manager / 显式依赖声明重构(同上,属编译器内部演进,不属本次拆分)
|
||||||
|
- 替换编译器为 drawtonomy 或 osm2streets —— 已评估否决:
|
||||||
|
drawtonomy 开源部分只读 Lanelet2(显式车道边界),不做 OSM `highway=*` 推导,
|
||||||
|
与本编译器的核心能力方向垂直
|
||||||
|
- osm2streets / QGIS legacy 链路的任何改动
|
||||||
|
- 宿主侧建筑 / 植被 / 水体渲染逻辑的改动(Phase 3 只抽离道路部分)
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- 评估结论与选型依据见 `design.md` 的「决策记录」一节。
|
||||||
|
- 时间估计:Phase 0-2 约 3 天(搬家 + 证明没搬坏),Phase 3 约 1-2 天。
|
||||||
|
拿到"道路与建筑渲染分离、可独立维护"是在 Phase 3 结束。
|
||||||
|
- 父任务验收完成后,下一项候选任务是独立的
|
||||||
|
`08-25-rc-p4-drawtonomy-ext`(drawtonomy 扩展 PoC);它不属于本任务完成条件。
|
||||||
@@ -0,0 +1,33 @@
|
|||||||
|
{
|
||||||
|
"id": "road-compiler-extraction",
|
||||||
|
"name": "road-compiler-extraction",
|
||||||
|
"title": "道路编译器独立化(parent)",
|
||||||
|
"description": "把 native road compiler 拆成可独立维护的项目,并与本项目通过版本化契约相辅相成;同时分离道路与 OSM 建筑渲染",
|
||||||
|
"status": "planning",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P1",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-25",
|
||||||
|
"completedAt": null,
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "main",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [
|
||||||
|
"08-25-rc-p0-contract-baseline",
|
||||||
|
"08-25-rc-p1-package-boundary",
|
||||||
|
"08-25-rc-p2-repo-split",
|
||||||
|
"08-25-rc-p3-render-separation"
|
||||||
|
],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {
|
||||||
|
"next_task": "08-25-rc-p4-drawtonomy-ext"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -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,81 @@
|
|||||||
|
# Phase 0 技术设计
|
||||||
|
|
||||||
|
契约本体见父任务 `design.md` §1,本文件只补 Phase 0 自身的实现设计。
|
||||||
|
|
||||||
|
## 1. 确定性核查的具体做法
|
||||||
|
|
||||||
|
编译器的潜在非确定性来源,按可疑度排序:
|
||||||
|
|
||||||
|
| 来源 | 表现 | 处置 |
|
||||||
|
|---|---|---|
|
||||||
|
| `fs.mkdtempSync(path.join(pipelineDir, "native-road-"))` | staging 目录名随机 | 若名字出现在 `compiled.json` 的 `source` 字段里,需归一化 |
|
||||||
|
| `compiled.json` 内的绝对路径 | `source.osm` / `source.overrides` / `source.trafficSignals` 是绝对路径 | 归一化为相对 repo root |
|
||||||
|
| 时间戳 | 未确认是否存在 | 核查 `compile-native-roads.js` 写入的 metadata |
|
||||||
|
| `Map` / `Set` 迭代顺序 | JS 保证插入序,若插入源本身有序则确定 | 观测两次运行 `orderHash` 是否一致即可暴露 |
|
||||||
|
| 浮点累加顺序 | 几何坐标末位抖动 | 若出现,说明存在顺序依赖,属真 bug,需修 |
|
||||||
|
| `crypto` 随机(`traffic-signals.js` require 了 `crypto`) | 信号 ID 可能含随机成分 | 重点核查 —— `native-traffic-signals.json` 是 `loadOrGenerate`,已存在则复用,首次生成可能不确定 |
|
||||||
|
|
||||||
|
**核查顺序**:
|
||||||
|
1. 备份两个有效区域的 `native-road/` 与 `native-traffic-signals.json`
|
||||||
|
2. 删除 `native-road/`(保留 signals,因为 `loadOrGenerate` 语义是已存在则复用)
|
||||||
|
3. 跑第一次 → snapshot A
|
||||||
|
4. 再删 `native-road/`,跑第二次 → snapshot B
|
||||||
|
5. diff A/B → volatile 字段清单
|
||||||
|
6. 额外一轮:删掉 signals 文件也重生成一次,确认 signal ID 是否确定
|
||||||
|
|
||||||
|
## 2. `scripts/road-parity.js` 设计
|
||||||
|
|
||||||
|
```
|
||||||
|
用法:
|
||||||
|
node scripts/road-parity.js --config <area-config> --snapshot <out.json>
|
||||||
|
node scripts/road-parity.js --config <area-config> --compare <baseline.json>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 归一化规则(写死在脚本里,并回写进契约文档)
|
||||||
|
|
||||||
|
1. **路径**:任何绝对路径 → 相对 repo root;staging 目录名 → 字面量 `<staging>`
|
||||||
|
2. **JSON**:递归按 key 排序后 `JSON.stringify`,再 hash
|
||||||
|
3. **GeoJSON**:
|
||||||
|
- `contentHash` = features 按 `properties.native_id`(缺失则按几何首坐标)排序后 hash
|
||||||
|
- `orderHash` = 原序 hash
|
||||||
|
- 两者都记录;比对时 `contentHash` 不一致 = 语义变化(严重),
|
||||||
|
仅 `orderHash` 不一致 = 顺序抖动(需解释但可能可接受)
|
||||||
|
4. **浮点**:不做舍入。坐标变化就是变化,不允许用容差掩盖
|
||||||
|
(拆分是纯搬迁,任何坐标位移都是 bug)
|
||||||
|
|
||||||
|
### 输出形状
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"contract": "native-road-package/v1",
|
||||||
|
"areaId": "fengshu-er-road",
|
||||||
|
"files": {
|
||||||
|
"compiled.json": { "contentHash": "…", "bytes": 12345 },
|
||||||
|
"diagnostics.json": { "contentHash": "…", "bytes": 678, "count": 42 },
|
||||||
|
"layers/road_surface.geojson": {
|
||||||
|
"contentHash": "…", "orderHash": "…", "features": 128 }
|
||||||
|
},
|
||||||
|
"volatileExcluded": ["source.osm", "source.overrides", "<staging>"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`count` / `features` 是冗余的人类可读字段 —— hash 变了但计数没变,
|
||||||
|
说明是内容变化;计数也变了,说明是增删。加速归因。
|
||||||
|
|
||||||
|
## 3. 基线目录布局
|
||||||
|
|
||||||
|
```
|
||||||
|
.trellis/tasks/08-25-road-compiler-extraction/baseline/
|
||||||
|
fengshu-er-road.json
|
||||||
|
nantaizi-lake-innovation-valley.json
|
||||||
|
README.md ← 记录生成时的 git commit、命令、volatile 字段清单
|
||||||
|
```
|
||||||
|
|
||||||
|
`README.md` 必须记录生成基线时的 commit hash,否则将来无法判断
|
||||||
|
"基线是在哪个代码状态下产生的"。
|
||||||
|
|
||||||
|
## 4. 为什么校验脚本放宿主而不是直接放未来的编译器仓库
|
||||||
|
|
||||||
|
Phase 0 时编译器仓库还不存在。脚本先落宿主 `scripts/`,
|
||||||
|
Phase 2 随编译器一起搬走,届时宿主保留一个薄封装(或直接调编译器包的 CLI)。
|
||||||
|
这样 Phase 1 的 parity 验证不需要等仓库拆分。
|
||||||
@@ -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,118 @@
|
|||||||
|
# Phase 0 执行计划
|
||||||
|
|
||||||
|
## 前置
|
||||||
|
|
||||||
|
- [ ] 分支:`experiment/road-compiler-rethink`(已在)
|
||||||
|
- [ ] 确认工作区干净(`.trellis/tmp-*.js` 五个未跟踪文件与本任务无关,可先清理或忽略)
|
||||||
|
- [ ] 阅读父任务 `design.md` §1 契约定义
|
||||||
|
|
||||||
|
## Step 1 — 摸清两区域当前状态
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ls config/areas/
|
||||||
|
for d in outputs/*/native-road/layers; do echo "$d: $(ls $d | wc -l)"; done
|
||||||
|
```
|
||||||
|
|
||||||
|
判定:`hanyang-block` 为废案,不纳入本阶段;只核查两个有效区域的配置与当前产物。
|
||||||
|
|
||||||
|
- [x] 逐区域检查 config 的 `nativeRoad.edgeLines` / `junctionTemplates.enabled`
|
||||||
|
- [x] 将两个有效区域的配置差异记录在基线 README
|
||||||
|
|
||||||
|
**门槛**:两个有效区域的图层差异有书面解释。
|
||||||
|
|
||||||
|
## Step 2 — 确定性核查
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 备份
|
||||||
|
cp -r outputs/<area>/native-road /tmp/rc-baseline-a
|
||||||
|
# 重编
|
||||||
|
rm -rf outputs/<area>/native-road
|
||||||
|
npm run road:compile -- --config config/areas/<area>.json
|
||||||
|
cp -r outputs/<area>/native-road /tmp/rc-baseline-b
|
||||||
|
# 比对
|
||||||
|
diff -r /tmp/rc-baseline-a /tmp/rc-baseline-b
|
||||||
|
```
|
||||||
|
|
||||||
|
- [x] 对两个有效区域各跑一遍
|
||||||
|
- [x] 记录所有差异字段 → volatile 清单
|
||||||
|
- [x] 额外一轮:删掉 `native-traffic-signals.json` 重生成,
|
||||||
|
确认信号 ID 是否确定(`traffic-signals.js` require 了 `crypto`,重点核查)
|
||||||
|
- [ ] 若发现**几何坐标级**的非确定性 → 停止本阶段,先开 bug 任务修掉
|
||||||
|
|
||||||
|
**门槛** 🔴:确定性已证明,或非确定性已定位并修复。这是全案的地基。
|
||||||
|
|
||||||
|
## Step 3 — 写 `scripts/road-parity.js`
|
||||||
|
|
||||||
|
按 `design.md` §2 实现。
|
||||||
|
|
||||||
|
- [x] `--snapshot` 生成归一化 checksum 清单
|
||||||
|
- [x] `--compare` 比对并逐文件报差异,不一致时非零退出
|
||||||
|
- [x] GeoJSON 双 hash(`contentHash` 排序后 / `orderHash` 原序)
|
||||||
|
- [x] volatile 字段按 Step 2 结论归一化
|
||||||
|
- [x] 自验:同一区域连跑两次 snapshot,`--compare` 必须通过
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node scripts/road-parity.js --config config/areas/fengshu-er-road.json --snapshot /tmp/s1.json
|
||||||
|
node scripts/road-parity.js --config config/areas/fengshu-er-road.json --compare /tmp/s1.json
|
||||||
|
echo "exit=$?" # 必须为 0
|
||||||
|
```
|
||||||
|
|
||||||
|
**门槛**:脚本对未改动的代码报告一致。
|
||||||
|
|
||||||
|
## Step 4 — 建立两区域基线
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p .trellis/tasks/08-25-road-compiler-extraction/baseline
|
||||||
|
for a in fengshu-er-road nantaizi-lake-innovation-valley; do
|
||||||
|
rm -rf outputs/$a/native-road
|
||||||
|
npm run road:compile -- --config config/areas/$a.json
|
||||||
|
node scripts/road-parity.js --config config/areas/$a.json \
|
||||||
|
--snapshot .trellis/tasks/08-25-road-compiler-extraction/baseline/$a.json
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
- [x] 两个基线 JSON 生成
|
||||||
|
- [x] 写 `baseline/README.md`:生成时的 git commit、命令、volatile 字段清单、
|
||||||
|
两个有效区域图层差异的解释
|
||||||
|
- [x] 反向自验:再跑一次 `--compare` 两个基线全部通过
|
||||||
|
|
||||||
|
## Step 5 — K2 决策
|
||||||
|
|
||||||
|
- [x] 检查 `comparison.json` 当前是否真被消费(grep 宿主与 workbench)
|
||||||
|
- [x] 若有 → 方案 B(可选注入),在契约里定义 `comparisonDir` 为 optional
|
||||||
|
|
||||||
|
## Step 6 — 落契约文档
|
||||||
|
|
||||||
|
- [x] 写 `docs/native-road-package-v1.md`,内容源自父任务 `design.md` §1
|
||||||
|
- [x] 补入 Step 2 的 volatile 字段清单
|
||||||
|
- [x] 补入 Step 5 的 K2 决策
|
||||||
|
- [x] 在 `docs/changelog.md` 记一行
|
||||||
|
|
||||||
|
## 验证命令汇总
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# parity 两区域全绿
|
||||||
|
for a in fengshu-er-road 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
|
||||||
|
|
||||||
|
# 既有测试未破
|
||||||
|
npm run test:native-road
|
||||||
|
npm run test:road-workbench
|
||||||
|
|
||||||
|
# 确认无生产代码改动
|
||||||
|
git diff --stat -- scripts/lib blender
|
||||||
|
```
|
||||||
|
|
||||||
|
最后一条必须为空输出 —— Phase 0 不碰生产代码。
|
||||||
|
|
||||||
|
## Review Gate
|
||||||
|
|
||||||
|
全部 AC0.1–AC0.6 打勾后,再进 Phase 1。**基线不可靠时不要前进。**
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
本阶段纯新增(文档 / 脚本 / 基线数据)。回滚 = 删除新增文件。
|
||||||
|
唯一例外:Step 2 若发现并修复了非确定性 bug,那部分是真实代码改动,
|
||||||
|
应拆成独立 commit 并单独保留。
|
||||||
@@ -0,0 +1,84 @@
|
|||||||
|
# Phase 0:冻结契约与 parity 基线
|
||||||
|
|
||||||
|
父任务:`.trellis/tasks/08-25-road-compiler-extraction/`
|
||||||
|
契约权威定义:父任务 `design.md` §1
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
在任何代码移动之前,把 `native-road-package/v1` 契约落成仓库内文档,
|
||||||
|
并为两个有效区域建立可复跑的逐文件 parity 基线,作为全案唯一 oracle。
|
||||||
|
|
||||||
|
**本阶段不移动、不重构任何生产代码。** 只新增文档、基线数据和一个校验脚本。
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
### R0.1 契约文档
|
||||||
|
|
||||||
|
- 把父任务 `design.md` §1(输入契约 / 输出契约 / 消费方式)落成
|
||||||
|
`docs/native-road-package-v1.md`。
|
||||||
|
- 文档必须列全 12 个图层名、`compiled.json` 顶层结构、`diagnostics.json` 记录形状、
|
||||||
|
stdout 标记格式。
|
||||||
|
- Phase 2 会把该文档搬进编译器仓库,此处先落在宿主。
|
||||||
|
|
||||||
|
### R0.2 确定性前置核查 🔴
|
||||||
|
|
||||||
|
**基线只有在编译器确定性的前提下才有意义。** 必须先证明这一点。
|
||||||
|
|
||||||
|
- 对同一输入连续跑两次 `road:compile`,比较全部输出文件。
|
||||||
|
- 识别并记录所有 volatile 字段(时间戳、绝对路径、staging 目录名、
|
||||||
|
任何来自 `mkdtemp` 的随机名、Map/Set 迭代顺序敏感的输出)。
|
||||||
|
- 校验脚本必须归一化或排除这些字段。
|
||||||
|
- 若发现真实的非确定性(相同输入产出不同几何),**必须先修掉再继续**,
|
||||||
|
否则整个拆分没有 oracle。
|
||||||
|
|
||||||
|
### R0.3 parity 校验脚本
|
||||||
|
|
||||||
|
- 新增 `scripts/road-parity.js`(宿主侧,Phase 2 随编译器搬走)。
|
||||||
|
- 能力:
|
||||||
|
- `--snapshot <out.json>` 遍历指定区域的 `native-road/` 全部文件 +
|
||||||
|
`native-traffic-signals.json`,归一化后输出排序稳定的 checksum 清单
|
||||||
|
- `--compare <baseline.json>` 与基线比对,差异逐文件报告
|
||||||
|
- 非零退出码表示不一致
|
||||||
|
- GeoJSON 需按稳定键排序后再 hash(避免 feature 顺序抖动造成假阳性),
|
||||||
|
但**顺序本身若变化必须被报告**——用两个 hash:`contentHash`(排序后)
|
||||||
|
与 `orderHash`(原序),分别报告。
|
||||||
|
|
||||||
|
### R0.4 两区域基线
|
||||||
|
|
||||||
|
- 区域:`fengshu-er-road`、`nantaizi-lake-innovation-valley`
|
||||||
|
- 从干净状态跑 `npm run road:compile`,产出基线 JSON 提交进版本控制
|
||||||
|
- 基线文件位置:`.trellis/tasks/08-25-road-compiler-extraction/baseline/<area>.json`
|
||||||
|
(Phase 2 搬进编译器仓库当测试语料,见父任务 R4)
|
||||||
|
|
||||||
|
`hanyang-block` 是废案,不纳入编译、快照或后续 parity 兼容范围。
|
||||||
|
|
||||||
|
### R0.5 K2 决策定档
|
||||||
|
|
||||||
|
`comparison.json` 依赖宿主 osm2streets 产物(`compile-native-roads.js:87` 读
|
||||||
|
`area.outputs.geojsonDir`),拆出后不可达。本阶段必须做出决策并写入契约文档:
|
||||||
|
|
||||||
|
- 方案 A:移除 `comparison.json`(osm2streets 已 legacy)
|
||||||
|
- 方案 B:保留,`comparisonDir` 作为可选输入注入
|
||||||
|
- 倾向 A。决策写入 `docs/native-road-package-v1.md` 的「已移除能力」一节。
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [x] AC0.1 `docs/native-road-package-v1.md` 存在,覆盖输入契约、输出契约、
|
||||||
|
12 图层清单、stdout 标记、已移除能力
|
||||||
|
- [x] AC0.2 连续两次编译的 parity 比对通过(确定性已证明),volatile 字段清单已记录在文档内
|
||||||
|
- [x] AC0.3 `scripts/road-parity.js` 可用,`--snapshot` / `--compare` 均工作,
|
||||||
|
不一致时非零退出
|
||||||
|
- [x] AC0.4 两个区域基线 JSON 已提交,且每个都能用 `--compare` 自比对通过
|
||||||
|
- [x] AC0.5 K2 决策已定档并写入契约文档
|
||||||
|
- [x] AC0.6 未修改任何生产代码(`git diff` 只含新增文档 / 脚本 / 基线)
|
||||||
|
|
||||||
|
## 依赖与顺序
|
||||||
|
|
||||||
|
- 无前置依赖,本阶段是全案入口
|
||||||
|
- **阻塞** Phase 1、2、3、4 —— 没有基线就没有 oracle
|
||||||
|
|
||||||
|
## Out of Scope
|
||||||
|
|
||||||
|
- 任何生产代码改动(含"顺手修一下")
|
||||||
|
- 目录结构调整
|
||||||
|
- `compiled.json` 结构变更
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "rc-p0-contract-baseline",
|
||||||
|
"name": "rc-p0-contract-baseline",
|
||||||
|
"title": "Phase 0:冻结契约与 parity 基线",
|
||||||
|
"description": "写死 native-road-package/v1 输入输出契约,并对两个有效区域建立逐文件 checksum 基线作为全案 oracle",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P1",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-25",
|
||||||
|
"completedAt": "2026-08-25",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "main",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": "08-25-road-compiler-extraction",
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
@@ -8,8 +8,8 @@
|
|||||||
|
|
||||||
<!-- @@@auto:current-status -->
|
<!-- @@@auto:current-status -->
|
||||||
- **Active File**: `journal-1.md`
|
- **Active File**: `journal-1.md`
|
||||||
- **Total Sessions**: 41
|
- **Total Sessions**: 42
|
||||||
- **Last Active**: 2026-08-24
|
- **Last Active**: 2026-08-25
|
||||||
<!-- @@@/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` | ~887 | Active |
|
| `journal-1.md` | ~908 | Active |
|
||||||
<!-- @@@/auto:active-documents -->
|
<!-- @@@/auto:active-documents -->
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -29,6 +29,7 @@
|
|||||||
<!-- @@@auto:session-history -->
|
<!-- @@@auto:session-history -->
|
||||||
| # | Date | Title | Commits | Branch |
|
| # | Date | Title | Commits | Branch |
|
||||||
|---|------|-------|---------|--------|
|
|---|------|-------|---------|--------|
|
||||||
|
| 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` |
|
||||||
| 39 | 2026-08-18 | Complete native-only pipeline replacement | `9e0e25a` | `feature/native-road-compiler` |
|
| 39 | 2026-08-18 | Complete native-only pipeline replacement | `9e0e25a` | `feature/native-road-compiler` |
|
||||||
|
|||||||
@@ -885,3 +885,24 @@ Replaced the Cesium preview's simulated vehicle route with authenticated OBU and
|
|||||||
### Status
|
### Status
|
||||||
|
|
||||||
[OK] **Completed**
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 42: Freeze native road parity baseline
|
||||||
|
|
||||||
|
**Date**: 2026-08-25
|
||||||
|
**Task**: Freeze native road parity baseline
|
||||||
|
**Branch**: `experiment/road-compiler-rethink`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Completed and archived Phase 0: documented native-road-package/v1, added strict road parity snapshots and two valid-area baselines, excluded abandoned hanyang-block, and verified deterministic recompilation including signal regeneration.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `e7bc7f8` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
@@ -33,7 +33,7 @@
|
|||||||
{
|
{
|
||||||
"id": "zhushanhu-fengshu-complex",
|
"id": "zhushanhu-fengshu-complex",
|
||||||
"template": "complex-junction-v1",
|
"template": "complex-junction-v1",
|
||||||
"referenceFile": "/Users/que01/osm2streets-qgis-workflow/inputs/osm/珠山湖大道(枫树二路)口.geojson",
|
"referenceFile": "../../inputs/osm/珠山湖大道(枫树二路)口.geojson",
|
||||||
"approachWidthMultiplier": 1.45,
|
"approachWidthMultiplier": 1.45,
|
||||||
"approachLengthMeters": 32,
|
"approachLengthMeters": 32,
|
||||||
"coreRadiusMeters": 28,
|
"coreRadiusMeters": 28,
|
||||||
|
|||||||
@@ -1,5 +1,15 @@
|
|||||||
# Changelog
|
# Changelog
|
||||||
|
|
||||||
|
## 2026-08-25
|
||||||
|
|
||||||
|
- Frozen the `native-road-package/v1` host/compiler contract in
|
||||||
|
`docs/native-road-package-v1.md`, added `scripts/road-parity.js`, and
|
||||||
|
committed checksum baselines for `fengshu-er-road` and
|
||||||
|
`nantaizi-lake-innovation-valley`. The control experiment covers two clean
|
||||||
|
compiles plus editable signal regeneration for each area; JSON key ordering,
|
||||||
|
absolute paths, and temporary staging names are normalized while geometry and
|
||||||
|
GeoJSON feature order remain strict.
|
||||||
|
|
||||||
## 2026-08-04
|
## 2026-08-04
|
||||||
|
|
||||||
- 重构区域构建入口的 preview 实现边界:`build-area.js` 现在只调度阶段、写 preview
|
- 重构区域构建入口的 preview 实现边界:`build-area.js` 现在只调度阶段、写 preview
|
||||||
|
|||||||
@@ -0,0 +1,98 @@
|
|||||||
|
# Native Road Package v1
|
||||||
|
|
||||||
|
`native-road-package/v1` defines the boundary between the host area pipeline
|
||||||
|
and the native road compiler. The compiler accepts only the input below; it
|
||||||
|
does not read `config/areas/*.json` or derive host paths.
|
||||||
|
|
||||||
|
## Input
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
areaId: string,
|
||||||
|
osmFile: string,
|
||||||
|
outDir: string,
|
||||||
|
stagingDir: string,
|
||||||
|
overridesFile: string,
|
||||||
|
trafficSignalsFile: string,
|
||||||
|
comparisonDir?: string,
|
||||||
|
options: {
|
||||||
|
edgeLines: boolean,
|
||||||
|
junctionTemplates: {
|
||||||
|
enabled: boolean,
|
||||||
|
references: [],
|
||||||
|
clusters: []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
All paths are absolute at the process boundary. `stagingDir` is the parent for
|
||||||
|
the compiler's temporary output and `outDir` is promoted atomically only after
|
||||||
|
all files are written. The host maps normalized area configuration to this
|
||||||
|
shape and owns all path derivation.
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
`outDir` contains these JSON documents:
|
||||||
|
|
||||||
|
- `compiled.json`: top-level keys are `schema`, `areaId`, `source`, `model`,
|
||||||
|
`movements`, `trafficSignals`, `diagnostics`, and `layers`. `source` has
|
||||||
|
`osm`, `overrides`, and `trafficSignals` paths.
|
||||||
|
- `diagnostics.json`: `{ schema: "native-road-diagnostics/v1", diagnostics: [] }`.
|
||||||
|
Each diagnostic has `id`, `severity`, `subjectId`, `sourceIds`, `rule`,
|
||||||
|
`message`, and `geometry` (a GeoJSON geometry or `null`).
|
||||||
|
- `comparison.json`: coverage counts for the road workbench.
|
||||||
|
- `traffic-signal-assemblies.json` and `traffic-signals.json`: compiler-owned
|
||||||
|
signal assembly and runtime views.
|
||||||
|
|
||||||
|
`layers/` always contains these twelve GeoJSON FeatureCollections:
|
||||||
|
|
||||||
|
1. `road_surface.geojson`
|
||||||
|
2. `intersection_surface.geojson`
|
||||||
|
3. `sidewalk_surface.geojson`
|
||||||
|
4. `edge_lines.geojson`
|
||||||
|
5. `lane_separators.geojson`
|
||||||
|
6. `center_lines.geojson`
|
||||||
|
7. `crosswalks.geojson`
|
||||||
|
8. `vehicle_stop_lines.geojson`
|
||||||
|
9. `direction_arrows.geojson`
|
||||||
|
10. `turn_arrows.geojson`
|
||||||
|
11. `lane_centerlines.geojson` (semantic, not rendered)
|
||||||
|
12. `connectors.geojson` (semantic, not rendered)
|
||||||
|
|
||||||
|
The editable signal source at `trafficSignalsFile` is a sibling of `outDir`.
|
||||||
|
It is included in the parity baseline because regeneration must be stable.
|
||||||
|
|
||||||
|
Successful CLI execution prints exactly one completion marker:
|
||||||
|
|
||||||
|
```text
|
||||||
|
NATIVE_ROAD_COMPILE_DONE {"areaId":...,"roads":N,"endpoints":N,"diagnostics":N,"output":...,"comparison":...}
|
||||||
|
```
|
||||||
|
|
||||||
|
Consumers use the CLI process plus files in `outDir` and parse this marker.
|
||||||
|
An in-process import may be an optimization, never the sole contract.
|
||||||
|
|
||||||
|
## Comparison Input Decision
|
||||||
|
|
||||||
|
`comparison.json` remains part of v1. The road workbench currently reads it,
|
||||||
|
so removing it would break a real consumer. `comparisonDir` is therefore an
|
||||||
|
optional compiler input for a future standalone package: when absent, the
|
||||||
|
compiler emits native-only counts and marks osm2streets coverage unavailable.
|
||||||
|
|
||||||
|
## Parity Rules
|
||||||
|
|
||||||
|
`scripts/road-parity.js` snapshots every file below `outDir` plus the sibling
|
||||||
|
editable signal document. JSON object keys are recursively sorted before
|
||||||
|
hashing. GeoJSON records both a sorted-feature `contentHash` and original-order
|
||||||
|
`orderHash`; either difference is reported.
|
||||||
|
|
||||||
|
The only normalization is intentional volatility removal:
|
||||||
|
|
||||||
|
- absolute paths below this repository become `<repo>/...`;
|
||||||
|
- other absolute paths become `<external>/<basename>`;
|
||||||
|
- `native-road-*` temporary directory names become `<staging>`.
|
||||||
|
|
||||||
|
No coordinates are rounded and no feature order changes are ignored. Control
|
||||||
|
experiments on 2026-08-25 compiled `fengshu-er-road` and
|
||||||
|
`nantaizi-lake-innovation-valley` twice, then regenerated their editable
|
||||||
|
signal documents. All 18 tracked files per area matched.
|
||||||
@@ -3,6 +3,9 @@
|
|||||||
"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",
|
||||||
"build:area": "node scripts/build-area.js",
|
"build:area": "node scripts/build-area.js",
|
||||||
@@ -18,6 +21,7 @@
|
|||||||
"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: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: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",
|
||||||
"test:build-stages": "node scripts/test-build-stages.js",
|
"test:build-stages": "node scripts/test-build-stages.js",
|
||||||
|
|||||||
@@ -0,0 +1,10 @@
|
|||||||
|
{
|
||||||
|
"name": "@osm-asset/road-compiler",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"private": true,
|
||||||
|
"type": "commonjs",
|
||||||
|
"main": "src/index.js",
|
||||||
|
"scripts": {
|
||||||
|
"test": "node test/index.js"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,27 @@
|
|||||||
|
"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 };
|
||||||
@@ -0,0 +1,141 @@
|
|||||||
|
#!/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
-1
@@ -1,7 +1,7 @@
|
|||||||
"use strict";
|
"use strict";
|
||||||
|
|
||||||
const fs = require("fs");
|
const fs = require("fs");
|
||||||
const { convertGeoJson, boundsOf } = require("./gaode-junction-reference");
|
const { convertGeoJson, boundsOf } = require("../reference/gaode");
|
||||||
const metricsCache = new WeakMap();
|
const metricsCache = new WeakMap();
|
||||||
const CORNER_FILLET_SEGMENTS = 12;
|
const CORNER_FILLET_SEGMENTS = 12;
|
||||||
// Must match DEFAULT_SIDEWALK_WIDTH_METERS in native-road.js so the corner band
|
// Must match DEFAULT_SIDEWALK_WIDTH_METERS in native-road.js so the corner band
|
||||||
File renamed without changes.
+2
-2
@@ -2,9 +2,9 @@
|
|||||||
|
|
||||||
const fs = require("fs");
|
const fs = require("fs");
|
||||||
const path = require("path");
|
const path = require("path");
|
||||||
const { laneCenterline } = require("./lane-geometry");
|
const { laneCenterline } = require("../geometry/lane-geometry");
|
||||||
|
|
||||||
const ASSET_MANIFEST = path.resolve(__dirname, "..", "..", "assets", "lane-icons", "manifest.json");
|
const ASSET_MANIFEST = path.resolve(__dirname, "..", "..", "..", "..", "assets", "lane-icons", "manifest.json");
|
||||||
const LANE_WIDTH_METERS = 3.2;
|
const LANE_WIDTH_METERS = 3.2;
|
||||||
const PLACEMENT_DISTANCE_METERS = 9;
|
const PLACEMENT_DISTANCE_METERS = 9;
|
||||||
const SPATIAL_MATCH_MAX_DISTANCE_METERS = 18;
|
const SPATIAL_MATCH_MAX_DISTANCE_METERS = 18;
|
||||||
File renamed without changes.
@@ -0,0 +1,14 @@
|
|||||||
|
"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"),
|
||||||
|
};
|
||||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,330 @@
|
|||||||
|
"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,
|
||||||
|
};
|
||||||
+11091
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,19 @@
|
|||||||
|
"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");
|
||||||
@@ -6,7 +6,7 @@ const os = require("os");
|
|||||||
const { execFileSync } = require("child_process");
|
const { execFileSync } = require("child_process");
|
||||||
const { JsStreetNetwork } = require("osm2streets-js-node");
|
const { JsStreetNetwork } = require("osm2streets-js-node");
|
||||||
const { qgisPaths } = require("./lib/tool-paths");
|
const { qgisPaths } = require("./lib/tool-paths");
|
||||||
const { buildCustomTurnLaneArrows } = require("./lib/turn-lane-arrows");
|
const { buildCustomTurnLaneArrows } = require("../packages/road-compiler/src/compile/turn-lane-arrows");
|
||||||
const { readTrafficSignalFeatures } = require("./lib/traffic-signals");
|
const { readTrafficSignalFeatures } = require("./lib/traffic-signals");
|
||||||
const {
|
const {
|
||||||
SCENE_LAYERS,
|
SCENE_LAYERS,
|
||||||
|
|||||||
@@ -1,34 +1,18 @@
|
|||||||
#!/usr/bin/env node
|
#!/usr/bin/env node
|
||||||
"use strict";
|
"use strict";
|
||||||
|
|
||||||
const fs = require("fs");
|
|
||||||
const path = require("path");
|
const path = require("path");
|
||||||
const { readAreaConfig } = require("./lib/area-config");
|
const { readAreaConfig } = require("./lib/area-config");
|
||||||
const { compileArea, parseArgs } = require("./compile-native-roads");
|
const { compileArea, parseArgs } = require("./compile-native-roads");
|
||||||
|
const { checkOutput } = require("../packages/road-compiler/src/check");
|
||||||
|
|
||||||
const repoRoot = path.resolve(__dirname, "..");
|
const repoRoot = path.resolve(__dirname, "..");
|
||||||
|
|
||||||
function checkArea(configPath, options = {}) {
|
function checkArea(configPath, options = {}) {
|
||||||
if (options.compile) compileArea(configPath);
|
if (options.compile) compileArea(configPath);
|
||||||
const area = readAreaConfig(configPath, { repoRoot });
|
const area = readAreaConfig(configPath, { repoRoot });
|
||||||
const root = area.outputs.nativeRoadDir;
|
return checkOutput({ areaId: area.id, outDir: area.outputs.nativeRoadDir });
|
||||||
const compiledPath = path.join(root, "compiled.json");
|
|
||||||
if (!fs.existsSync(compiledPath)) throw new Error(`Native road output is missing: ${compiledPath}`);
|
|
||||||
const compiled = readJson(compiledPath);
|
|
||||||
const connectors = readJson(path.join(root, "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: area.id, 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")); }
|
|
||||||
|
|
||||||
function main() {
|
function main() {
|
||||||
const args = parseArgs(process.argv.slice(2));
|
const args = parseArgs(process.argv.slice(2));
|
||||||
|
|||||||
@@ -1,11 +1,9 @@
|
|||||||
#!/usr/bin/env node
|
#!/usr/bin/env node
|
||||||
"use strict";
|
"use strict";
|
||||||
|
|
||||||
const fs = require("fs");
|
|
||||||
const path = require("path");
|
const path = require("path");
|
||||||
const { readAreaConfig } = require("./lib/area-config");
|
const { readAreaConfig, toRoadCompilerInput } = require("./lib/area-config");
|
||||||
const { compileRoadModel, compileGeometry, loadOverrides, validateOverrides, writeJsonAtomic } = require("./lib/native-road");
|
const { compileInput } = require("../packages/road-compiler/src/compile/compiler");
|
||||||
const { loadOrGenerate, runtime } = require("./lib/native-traffic-signals");
|
|
||||||
|
|
||||||
const repoRoot = path.resolve(__dirname, "..");
|
const repoRoot = path.resolve(__dirname, "..");
|
||||||
|
|
||||||
@@ -21,112 +19,8 @@ function parseArgs(argv) {
|
|||||||
|
|
||||||
function compileArea(configPath) {
|
function compileArea(configPath) {
|
||||||
const area = readAreaConfig(configPath, { repoRoot });
|
const area = readAreaConfig(configPath, { repoRoot });
|
||||||
const overrides = loadOverrides(area.outputs.nativeRoadOverrides);
|
const compiled = compileInput(toRoadCompilerInput(area));
|
||||||
const model = compileRoadModel(fs.readFileSync(area.input, "utf8"), overrides);
|
return { ...compiled, area };
|
||||||
// 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 = path.join(area.outputs.geojsonDir, "road_surface.geojson");
|
|
||||||
let featureCount = null;
|
|
||||||
if (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 main() {
|
function main() {
|
||||||
|
|||||||
@@ -3,7 +3,7 @@
|
|||||||
|
|
||||||
const fs = require("fs");
|
const fs = require("fs");
|
||||||
const path = require("path");
|
const path = require("path");
|
||||||
const { inspectReference, localReferenceSvg } = require("./lib/gaode-junction-reference");
|
const { inspectReference, localReferenceSvg } = require("../packages/road-compiler/src/reference/gaode");
|
||||||
|
|
||||||
function parseArgs(argv) {
|
function parseArgs(argv) {
|
||||||
const result = {};
|
const result = {};
|
||||||
|
|||||||
@@ -8,7 +8,7 @@ function readAreaConfig(file, options = {}) {
|
|||||||
if (!fs.existsSync(file)) {
|
if (!fs.existsSync(file)) {
|
||||||
throw new Error(`Config file not found: ${file}`);
|
throw new Error(`Config file not found: ${file}`);
|
||||||
}
|
}
|
||||||
return normalizeAreaConfig(JSON.parse(fs.readFileSync(file, "utf8")), options);
|
return normalizeAreaConfig(JSON.parse(fs.readFileSync(file, "utf8")), { ...options, configDir: path.dirname(path.resolve(file)) });
|
||||||
}
|
}
|
||||||
|
|
||||||
function normalizeAreaConfig(raw, options = {}) {
|
function normalizeAreaConfig(raw, options = {}) {
|
||||||
@@ -113,7 +113,7 @@ function normalizeAreaConfig(raw, options = {}) {
|
|||||||
},
|
},
|
||||||
nativeRoad: {
|
nativeRoad: {
|
||||||
edgeLines: booleanOption(raw.nativeRoad?.edgeLines, false, "nativeRoad.edgeLines"),
|
edgeLines: booleanOption(raw.nativeRoad?.edgeLines, false, "nativeRoad.edgeLines"),
|
||||||
junctionTemplates: normalizeJunctionTemplates(raw.nativeRoad?.junctionTemplates, repoRoot),
|
junctionTemplates: normalizeJunctionTemplates(raw.nativeRoad?.junctionTemplates, repoRoot, options.configDir || repoRoot),
|
||||||
},
|
},
|
||||||
osm2streets: raw.osm2streets || {
|
osm2streets: raw.osm2streets || {
|
||||||
debug_each_step: false,
|
debug_each_step: false,
|
||||||
@@ -154,7 +154,7 @@ function normalizeV2xPreviewConfig(raw) {
|
|||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
function normalizeJunctionTemplates(raw, repoRoot) {
|
function normalizeJunctionTemplates(raw, repoRoot, configDir) {
|
||||||
if (raw === undefined || raw === null) return { enabled: false, references: [] };
|
if (raw === undefined || raw === null) return { enabled: false, references: [] };
|
||||||
if (typeof raw !== "object" || Array.isArray(raw)) throw new Error("nativeRoad.junctionTemplates must be an object");
|
if (typeof raw !== "object" || Array.isArray(raw)) throw new Error("nativeRoad.junctionTemplates must be an object");
|
||||||
const enabled = booleanOption(raw.enabled, false, "nativeRoad.junctionTemplates.enabled");
|
const enabled = booleanOption(raw.enabled, false, "nativeRoad.junctionTemplates.enabled");
|
||||||
@@ -164,7 +164,7 @@ function normalizeJunctionTemplates(raw, repoRoot) {
|
|||||||
const nodeId = requireText(item.nodeId, `nativeRoad.junctionTemplates.references[${index}].nodeId`);
|
const nodeId = requireText(item.nodeId, `nativeRoad.junctionTemplates.references[${index}].nodeId`);
|
||||||
const template = item.template ?? "cross-v1";
|
const template = item.template ?? "cross-v1";
|
||||||
if (template !== "cross-v1") throw new Error(`nativeRoad.junctionTemplates.references[${index}].template must be \"cross-v1\"`);
|
if (template !== "cross-v1") throw new Error(`nativeRoad.junctionTemplates.references[${index}].template must be \"cross-v1\"`);
|
||||||
const referenceFile = item.referenceFile ? path.resolve(item.referenceFile) : null;
|
const referenceFile = item.referenceFile ? path.resolve(configDir, item.referenceFile) : null;
|
||||||
const coordinateSystem = item.coordinateSystem ?? "GCJ-02";
|
const coordinateSystem = item.coordinateSystem ?? "GCJ-02";
|
||||||
if (coordinateSystem !== "GCJ-02") throw new Error(`nativeRoad.junctionTemplates.references[${index}].coordinateSystem must be \"GCJ-02\"`);
|
if (coordinateSystem !== "GCJ-02") throw new Error(`nativeRoad.junctionTemplates.references[${index}].coordinateSystem must be \"GCJ-02\"`);
|
||||||
const cornerRadiusMultiplier = numberOption(item.cornerRadiusMultiplier, 1, `nativeRoad.junctionTemplates.references[${index}].cornerRadiusMultiplier`, 0.75, 1.25);
|
const cornerRadiusMultiplier = numberOption(item.cornerRadiusMultiplier, 1, `nativeRoad.junctionTemplates.references[${index}].cornerRadiusMultiplier`, 0.75, 1.25);
|
||||||
@@ -181,7 +181,7 @@ function normalizeJunctionTemplates(raw, repoRoot) {
|
|||||||
if (!Array.isArray(nodeIds) || nodeIds.length < 2 || nodeIds.some((value) => typeof value !== "string" && typeof value !== "number")) throw new Error(`nativeRoad.junctionTemplates.clusters[${index}].nodeIds must contain at least two node ids`);
|
if (!Array.isArray(nodeIds) || nodeIds.length < 2 || nodeIds.some((value) => typeof value !== "string" && typeof value !== "number")) throw new Error(`nativeRoad.junctionTemplates.clusters[${index}].nodeIds must contain at least two node ids`);
|
||||||
const template = item.template ?? "complex-junction-v1";
|
const template = item.template ?? "complex-junction-v1";
|
||||||
if (template !== "cross-cluster-v1" && template !== "complex-junction-v1") throw new Error(`nativeRoad.junctionTemplates.clusters[${index}].template must be \"cross-cluster-v1\" or \"complex-junction-v1\"`);
|
if (template !== "cross-cluster-v1" && template !== "complex-junction-v1") throw new Error(`nativeRoad.junctionTemplates.clusters[${index}].template must be \"cross-cluster-v1\" or \"complex-junction-v1\"`);
|
||||||
const referenceFile = item.referenceFile ? path.resolve(item.referenceFile) : null;
|
const referenceFile = item.referenceFile ? path.resolve(configDir, item.referenceFile) : null;
|
||||||
const approachWidthMultiplier = numberOption(item.approachWidthMultiplier, 1.45, `nativeRoad.junctionTemplates.clusters[${index}].approachWidthMultiplier`, 1, 1.8);
|
const approachWidthMultiplier = numberOption(item.approachWidthMultiplier, 1.45, `nativeRoad.junctionTemplates.clusters[${index}].approachWidthMultiplier`, 1, 1.8);
|
||||||
const approachLengthMeters = numberOption(item.approachLengthMeters, 32, `nativeRoad.junctionTemplates.clusters[${index}].approachLengthMeters`, 10, 50);
|
const approachLengthMeters = numberOption(item.approachLengthMeters, 32, `nativeRoad.junctionTemplates.clusters[${index}].approachLengthMeters`, 10, 50);
|
||||||
const coreRadiusMeters = numberOption(item.coreRadiusMeters, 28, `nativeRoad.junctionTemplates.clusters[${index}].coreRadiusMeters`, 12, 80);
|
const coreRadiusMeters = numberOption(item.coreRadiusMeters, 28, `nativeRoad.junctionTemplates.clusters[${index}].coreRadiusMeters`, 12, 80);
|
||||||
@@ -272,7 +272,24 @@ function booleanOption(value, fallback, label) {
|
|||||||
throw new Error(`${label} must be boolean`);
|
throw new Error(`${label} must be boolean`);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
function toRoadCompilerInput(area) {
|
||||||
|
return {
|
||||||
|
areaId: area.id,
|
||||||
|
osmFile: area.input,
|
||||||
|
outDir: area.outputs.nativeRoadDir,
|
||||||
|
stagingDir: area.outputs.pipelineDir,
|
||||||
|
overridesFile: area.outputs.nativeRoadOverrides,
|
||||||
|
trafficSignalsFile: area.outputs.nativeTrafficSignals,
|
||||||
|
comparisonDir: area.outputs.geojsonDir,
|
||||||
|
options: {
|
||||||
|
edgeLines: area.nativeRoad.edgeLines,
|
||||||
|
junctionTemplates: area.nativeRoad.junctionTemplates,
|
||||||
|
},
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
module.exports = {
|
module.exports = {
|
||||||
normalizeAreaConfig,
|
normalizeAreaConfig,
|
||||||
readAreaConfig,
|
readAreaConfig,
|
||||||
|
toRoadCompilerInput,
|
||||||
};
|
};
|
||||||
@@ -1,240 +1,12 @@
|
|||||||
"use strict";
|
"use strict";
|
||||||
|
|
||||||
const fs = require("fs");
|
const fs = require("fs");
|
||||||
const crypto = require("crypto");
|
const { parseOsm } = require("../../packages/road-compiler/src/osm");
|
||||||
const { parseOsm } = require("./osm");
|
const trafficSignals = require("../../packages/road-compiler/src/traffic-signals");
|
||||||
|
|
||||||
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) {
|
function readTrafficSignalFeatures(stopLinePath, intersectionPath, osmPath) {
|
||||||
const controls = parseOsm(fs.readFileSync(osmPath, "utf8")).trafficSignalControls;
|
const controls = parseOsm(fs.readFileSync(osmPath, "utf8")).trafficSignalControls;
|
||||||
return buildTrafficSignalFeatures(
|
return trafficSignals.buildTrafficSignalFeatures(
|
||||||
JSON.parse(fs.readFileSync(stopLinePath, "utf8")),
|
JSON.parse(fs.readFileSync(stopLinePath, "utf8")),
|
||||||
JSON.parse(fs.readFileSync(intersectionPath, "utf8")), controls,
|
JSON.parse(fs.readFileSync(intersectionPath, "utf8")), controls,
|
||||||
);
|
);
|
||||||
@@ -244,87 +16,9 @@ function readTrafficSignals(editablePath, osmPath = null) {
|
|||||||
const collection = JSON.parse(fs.readFileSync(editablePath, "utf8"));
|
const collection = JSON.parse(fs.readFileSync(editablePath, "utf8"));
|
||||||
if (osmPath) {
|
if (osmPath) {
|
||||||
const controls = parseOsm(fs.readFileSync(osmPath, "utf8")).trafficSignalControls;
|
const controls = parseOsm(fs.readFileSync(osmPath, "utf8")).trafficSignalControls;
|
||||||
validateTrafficSignalSourceReferences(collection, controls);
|
trafficSignals.validateTrafficSignalSourceReferences(collection, controls);
|
||||||
}
|
}
|
||||||
return buildTrafficSignalsFromFeatures(collection);
|
return trafficSignals.buildTrafficSignalsFromFeatures(collection);
|
||||||
}
|
}
|
||||||
|
|
||||||
function normalizeBoolean(value, label) {
|
module.exports = { ...trafficSignals, readTrafficSignalFeatures, readTrafficSignals };
|
||||||
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,
|
|
||||||
};
|
|
||||||
@@ -1,7 +1,7 @@
|
|||||||
"use strict";
|
"use strict";
|
||||||
|
|
||||||
const fs = require("fs");
|
const fs = require("fs");
|
||||||
const { parseOsm } = require("./osm");
|
const { parseOsm } = require("../../packages/road-compiler/src/osm");
|
||||||
const {
|
const {
|
||||||
appendCoordinates,
|
appendCoordinates,
|
||||||
haversineMeters,
|
haversineMeters,
|
||||||
@@ -10,7 +10,7 @@ const {
|
|||||||
orientPolyline,
|
orientPolyline,
|
||||||
polylineLength,
|
polylineLength,
|
||||||
polylineMidpoint,
|
polylineMidpoint,
|
||||||
} = require("./lane-geometry");
|
} = require("../../packages/road-compiler/src/geometry/lane-geometry");
|
||||||
|
|
||||||
const MAX_ROUTES = 5;
|
const MAX_ROUTES = 5;
|
||||||
const MAX_PATH_EDGES = 7;
|
const MAX_PATH_EDGES = 7;
|
||||||
|
|||||||
@@ -17,7 +17,7 @@ const path = require("path");
|
|||||||
const os = require("os");
|
const os = require("os");
|
||||||
const { execFileSync } = require("child_process");
|
const { execFileSync } = require("child_process");
|
||||||
const { qgisPaths } = require("./lib/tool-paths");
|
const { qgisPaths } = require("./lib/tool-paths");
|
||||||
const { parseOsm } = require("./lib/osm");
|
const { parseOsm } = require("../packages/road-compiler/src/osm");
|
||||||
const {
|
const {
|
||||||
validateTrafficSignalSourceReferences,
|
validateTrafficSignalSourceReferences,
|
||||||
} = require("./lib/traffic-signals");
|
} = require("./lib/traffic-signals");
|
||||||
|
|||||||
@@ -3,7 +3,7 @@
|
|||||||
|
|
||||||
const fs = require("fs");
|
const fs = require("fs");
|
||||||
const path = require("path");
|
const path = require("path");
|
||||||
const { templateFor } = require("./lib/turn-lane-arrows");
|
const { templateFor } = require("../packages/road-compiler/src/compile/turn-lane-arrows");
|
||||||
|
|
||||||
const output = path.resolve(process.argv[2] || path.join("outputs", "turn-lane-arrow-samples.svg"));
|
const output = path.resolve(process.argv[2] || path.join("outputs", "turn-lane-arrow-samples.svg"));
|
||||||
const DISPLAY_SCALE = 60;
|
const DISPLAY_SCALE = 60;
|
||||||
|
|||||||
@@ -0,0 +1,152 @@
|
|||||||
|
#!/usr/bin/env node
|
||||||
|
"use strict";
|
||||||
|
|
||||||
|
const crypto = require("crypto");
|
||||||
|
const fs = require("fs");
|
||||||
|
const path = require("path");
|
||||||
|
const { readAreaConfig } = require("./lib/area-config");
|
||||||
|
|
||||||
|
const repoRoot = path.resolve(__dirname, "..");
|
||||||
|
|
||||||
|
function parseArgs(argv) {
|
||||||
|
const result = {};
|
||||||
|
for (let index = 0; index < argv.length; index += 1) {
|
||||||
|
if (!argv[index].startsWith("--")) continue;
|
||||||
|
const key = argv[index].slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
|
||||||
|
result[key] = argv[index + 1] && !argv[index + 1].startsWith("--") ? argv[++index] : true;
|
||||||
|
}
|
||||||
|
return result;
|
||||||
|
}
|
||||||
|
|
||||||
|
function usage() {
|
||||||
|
return "Usage: node scripts/road-parity.js --config <area-config> (--snapshot <out.json> | --compare <baseline.json>)";
|
||||||
|
}
|
||||||
|
|
||||||
|
function hash(value) {
|
||||||
|
return crypto.createHash("sha256").update(value).digest("hex");
|
||||||
|
}
|
||||||
|
|
||||||
|
function stable(value) {
|
||||||
|
if (Array.isArray(value)) return value.map(stable);
|
||||||
|
if (!value || typeof value !== "object") return normalizeString(value);
|
||||||
|
return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
|
||||||
|
}
|
||||||
|
|
||||||
|
function normalizeString(value) {
|
||||||
|
if (typeof value !== "string") return value;
|
||||||
|
const normalized = value.replace(/([\\/])native-road-[^\\/]+/g, "$1<staging>");
|
||||||
|
if (!path.isAbsolute(normalized)) return normalized;
|
||||||
|
const relative = path.relative(repoRoot, normalized);
|
||||||
|
return relative && !relative.startsWith("..") && !path.isAbsolute(relative)
|
||||||
|
? `<repo>/${relative.split(path.sep).join("/")}`
|
||||||
|
: `<external>/${path.basename(normalized)}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
function encoded(value) {
|
||||||
|
return JSON.stringify(stable(value));
|
||||||
|
}
|
||||||
|
|
||||||
|
function featureKey(feature) {
|
||||||
|
const nativeId = feature?.properties?.native_id ?? feature?.properties?.nativeId ?? feature?.id;
|
||||||
|
if (nativeId !== undefined && nativeId !== null) return `id:${nativeId}`;
|
||||||
|
return `geometry:${encoded(feature?.geometry ?? null)}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
function geoJsonRecord(value, bytes) {
|
||||||
|
if (value?.type !== "FeatureCollection" || !Array.isArray(value.features)) return null;
|
||||||
|
const normalized = { ...value, features: value.features.map(stable) };
|
||||||
|
const ordered = encoded(normalized);
|
||||||
|
const content = encoded({ ...normalized, features: [...normalized.features].sort((left, right) => featureKey(left).localeCompare(featureKey(right))) });
|
||||||
|
return { contentHash: hash(content), orderHash: hash(ordered), features: value.features.length, bytes };
|
||||||
|
}
|
||||||
|
|
||||||
|
function jsonRecord(text, bytes) {
|
||||||
|
const value = JSON.parse(text);
|
||||||
|
return geoJsonRecord(value, bytes) || { contentHash: hash(encoded(value)), bytes };
|
||||||
|
}
|
||||||
|
|
||||||
|
function filesBelow(directory) {
|
||||||
|
const result = [];
|
||||||
|
for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
|
||||||
|
const full = path.join(directory, entry.name);
|
||||||
|
if (entry.isDirectory()) result.push(...filesBelow(full));
|
||||||
|
else if (entry.isFile()) result.push(full);
|
||||||
|
}
|
||||||
|
return result;
|
||||||
|
}
|
||||||
|
|
||||||
|
function snapshot(configPath) {
|
||||||
|
const area = readAreaConfig(configPath, { repoRoot });
|
||||||
|
if (!fs.existsSync(area.outputs.nativeRoadDir)) throw new Error(`Native road output not found: ${area.outputs.nativeRoadDir}`);
|
||||||
|
const files = {};
|
||||||
|
for (const file of filesBelow(area.outputs.nativeRoadDir).sort()) {
|
||||||
|
const relative = path.relative(area.outputs.nativeRoadDir, file).split(path.sep).join("/");
|
||||||
|
const text = fs.readFileSync(file, "utf8");
|
||||||
|
files[relative] = jsonRecord(text, Buffer.byteLength(text));
|
||||||
|
}
|
||||||
|
if (fs.existsSync(area.outputs.nativeTrafficSignals)) {
|
||||||
|
const text = fs.readFileSync(area.outputs.nativeTrafficSignals, "utf8");
|
||||||
|
files["../native-traffic-signals.json"] = jsonRecord(text, Buffer.byteLength(text));
|
||||||
|
}
|
||||||
|
return {
|
||||||
|
contract: "native-road-package/v1",
|
||||||
|
areaId: area.id,
|
||||||
|
files: Object.fromEntries(Object.keys(files).sort().map((file) => [file, files[file]])),
|
||||||
|
volatileExcluded: ["absolute paths -> <repo> or <external>", "native-road-* staging directory -> <staging>"],
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function compare(actual, baseline) {
|
||||||
|
const differences = [];
|
||||||
|
if (actual.contract !== baseline.contract) differences.push(`contract: expected ${baseline.contract}, got ${actual.contract}`);
|
||||||
|
if (actual.areaId !== baseline.areaId) differences.push(`areaId: expected ${baseline.areaId}, got ${actual.areaId}`);
|
||||||
|
const names = new Set([...Object.keys(baseline.files || {}), ...Object.keys(actual.files || {})]);
|
||||||
|
for (const name of [...names].sort()) {
|
||||||
|
const expected = baseline.files?.[name];
|
||||||
|
const received = actual.files?.[name];
|
||||||
|
if (!expected) { differences.push(`${name}: unexpected file`); continue; }
|
||||||
|
if (!received) { differences.push(`${name}: missing file`); continue; }
|
||||||
|
for (const field of ["contentHash", "orderHash", "features", "bytes"]) {
|
||||||
|
if ((expected[field] ?? null) !== (received[field] ?? null)) {
|
||||||
|
differences.push(`${name}: ${field} expected ${expected[field] ?? "<none>"}, got ${received[field] ?? "<none>"}`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return differences;
|
||||||
|
}
|
||||||
|
|
||||||
|
function writeJson(file, value) {
|
||||||
|
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||||
|
fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
|
||||||
|
}
|
||||||
|
|
||||||
|
function main() {
|
||||||
|
const args = parseArgs(process.argv.slice(2));
|
||||||
|
if (!args.config || Boolean(args.snapshot) === Boolean(args.compare)) throw new Error(usage());
|
||||||
|
const actual = snapshot(path.resolve(args.config));
|
||||||
|
if (args.snapshot) {
|
||||||
|
const output = path.resolve(args.snapshot);
|
||||||
|
writeJson(output, actual);
|
||||||
|
console.log(`ROAD_PARITY_SNAPSHOT ${JSON.stringify({ areaId: actual.areaId, output, files: Object.keys(actual.files).length })}`);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
const baseline = JSON.parse(fs.readFileSync(path.resolve(args.compare), "utf8"));
|
||||||
|
const differences = compare(actual, baseline);
|
||||||
|
if (differences.length) {
|
||||||
|
for (const difference of differences) console.error(`ROAD_PARITY_DIFF ${difference}`);
|
||||||
|
process.exitCode = 1;
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
console.log(`ROAD_PARITY_OK ${JSON.stringify({ areaId: actual.areaId, baseline: path.resolve(args.compare), files: Object.keys(actual.files).length })}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (require.main === module) {
|
||||||
|
try {
|
||||||
|
main();
|
||||||
|
} catch (error) {
|
||||||
|
console.error(error.message);
|
||||||
|
process.exitCode = 1;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
module.exports = { compare, snapshot };
|
||||||
@@ -6,10 +6,10 @@ const http = require("http");
|
|||||||
const path = require("path");
|
const path = require("path");
|
||||||
const { execFileSync } = require("child_process");
|
const { execFileSync } = require("child_process");
|
||||||
const { readAreaConfig } = require("./lib/area-config");
|
const { readAreaConfig } = require("./lib/area-config");
|
||||||
const { loadOverrides, validateOverrides, writeJsonAtomic } = require("./lib/native-road");
|
const { loadOverrides, validateOverrides, writeJsonAtomic } = require("../packages/road-compiler/src/compile/native-road");
|
||||||
const { generate, validateDocument, runtime } = require("./lib/native-traffic-signals");
|
const { generate, validateDocument, runtime } = require("../packages/road-compiler/src/native-traffic-signals");
|
||||||
const { compileArea, parseArgs } = require("./compile-native-roads");
|
const { compileArea, parseArgs } = require("./compile-native-roads");
|
||||||
const { convertGeoJson } = require("./lib/gaode-junction-reference");
|
const { convertGeoJson } = require("../packages/road-compiler/src/reference/gaode");
|
||||||
|
|
||||||
const repoRoot = path.resolve(__dirname, "..");
|
const repoRoot = path.resolve(__dirname, "..");
|
||||||
|
|
||||||
|
|||||||
@@ -5,7 +5,7 @@ const assert = require("assert");
|
|||||||
const fs = require("fs");
|
const fs = require("fs");
|
||||||
const os = require("os");
|
const os = require("os");
|
||||||
const path = require("path");
|
const path = require("path");
|
||||||
const { gcj02ToWgs84, convertGeoJson, inspectReference } = require("./lib/gaode-junction-reference");
|
const { gcj02ToWgs84, convertGeoJson, inspectReference } = require("../packages/road-compiler/src/reference/gaode");
|
||||||
|
|
||||||
const converted = gcj02ToWgs84([114.12864875054062, 30.460485279762146]);
|
const converted = gcj02ToWgs84([114.12864875054062, 30.460485279762146]);
|
||||||
assert.ok(Math.abs(converted[0] - 114.1229659) < 0.00001);
|
assert.ok(Math.abs(converted[0] - 114.1229659) < 0.00001);
|
||||||
|
|||||||
@@ -5,7 +5,7 @@ const assert = require("assert");
|
|||||||
const fs = require("fs");
|
const fs = require("fs");
|
||||||
const os = require("os");
|
const os = require("os");
|
||||||
const path = require("path");
|
const path = require("path");
|
||||||
const { compileRoadModel, compileGeometry, validateOverrides } = require("./lib/native-road");
|
const { compileRoadModel, compileGeometry, validateOverrides } = require("../packages/road-compiler/src/compile/native-road");
|
||||||
const { compileArea } = require("./compile-native-roads");
|
const { compileArea } = require("./compile-native-roads");
|
||||||
const { checkArea } = require("./check-native-roads");
|
const { checkArea } = require("./check-native-roads");
|
||||||
|
|
||||||
|
|||||||
@@ -22,8 +22,8 @@ const {
|
|||||||
uTurnConnector,
|
uTurnConnector,
|
||||||
} = require("./lib/vehicle-route");
|
} = require("./lib/vehicle-route");
|
||||||
const { buildTrafficSignals } = require("./lib/traffic-signals");
|
const { buildTrafficSignals } = require("./lib/traffic-signals");
|
||||||
const { haversineMeters, laneCenterline } = require("./lib/lane-geometry");
|
const { haversineMeters, laneCenterline } = require("../packages/road-compiler/src/geometry/lane-geometry");
|
||||||
const { parseOsm } = require("./lib/osm");
|
const { parseOsm } = require("../packages/road-compiler/src/osm");
|
||||||
|
|
||||||
const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "preview-assets-"));
|
const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "preview-assets-"));
|
||||||
const osmPath = path.join(tempDir, "fixture.osm");
|
const osmPath = path.join(tempDir, "fixture.osm");
|
||||||
|
|||||||
@@ -0,0 +1,30 @@
|
|||||||
|
#!/usr/bin/env node
|
||||||
|
"use strict";
|
||||||
|
|
||||||
|
const assert = require("assert/strict");
|
||||||
|
const { compare } = require("./road-parity");
|
||||||
|
|
||||||
|
const baseline = {
|
||||||
|
contract: "native-road-package/v1",
|
||||||
|
areaId: "fixture",
|
||||||
|
files: {
|
||||||
|
"layers/road_surface.geojson": {
|
||||||
|
contentHash: "content-a",
|
||||||
|
orderHash: "order-a",
|
||||||
|
features: 2,
|
||||||
|
bytes: 100,
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
assert.deepEqual(compare(baseline, baseline), []);
|
||||||
|
assert.match(
|
||||||
|
compare({ ...baseline, files: { "layers/road_surface.geojson": { ...baseline.files["layers/road_surface.geojson"], orderHash: "order-b" } } }, baseline).join("\n"),
|
||||||
|
/orderHash/,
|
||||||
|
);
|
||||||
|
assert.match(
|
||||||
|
compare({ ...baseline, files: {} }, baseline).join("\n"),
|
||||||
|
/missing file/,
|
||||||
|
);
|
||||||
|
|
||||||
|
console.log("road parity tests passed");
|
||||||
@@ -11,8 +11,8 @@ const {
|
|||||||
buildTrafficSignalsFromFeatures,
|
buildTrafficSignalsFromFeatures,
|
||||||
validateTrafficSignalFeatures,
|
validateTrafficSignalFeatures,
|
||||||
validateTrafficSignalSourceReferences,
|
validateTrafficSignalSourceReferences,
|
||||||
} = require("./lib/traffic-signals");
|
} = require("../packages/road-compiler/src/traffic-signals");
|
||||||
const { SCHEMA, loadOrGenerate } = require("./lib/native-traffic-signals");
|
const { SCHEMA, loadOrGenerate } = require("../packages/road-compiler/src/native-traffic-signals");
|
||||||
|
|
||||||
function rectangle(lon, lat, dx = 0.00003, dy = 0.000006) {
|
function rectangle(lon, lat, dx = 0.00003, dy = 0.000006) {
|
||||||
return { type: "Feature", geometry: { type: "Polygon", coordinates: [[
|
return { type: "Feature", geometry: { type: "Polygon", coordinates: [[
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
"use strict";
|
"use strict";
|
||||||
|
|
||||||
const assert = require("assert");
|
const assert = require("assert");
|
||||||
const { arrowRingsAt, buildCustomTurnLaneArrows, loadManifest, normalizeManeuver, supportedAssets, templateFor } = require("./lib/turn-lane-arrows");
|
const { arrowRingsAt, buildCustomTurnLaneArrows, loadManifest, normalizeManeuver, supportedAssets, templateFor } = require("../packages/road-compiler/src/compile/turn-lane-arrows");
|
||||||
|
|
||||||
function node(id, lon, lat) { return { id, lon, lat, tags: {} }; }
|
function node(id, lon, lat) { return { id, lon, lat, tags: {} }; }
|
||||||
function way(id, refs, tags) { return { id, refs, tags }; }
|
function way(id, refs, tags) { return { id, refs, tags }; }
|
||||||
|
|||||||
@@ -5,7 +5,7 @@ const assert = require("assert");
|
|||||||
const fs = require("fs");
|
const fs = require("fs");
|
||||||
const path = require("path");
|
const path = require("path");
|
||||||
const vm = require("vm");
|
const vm = require("vm");
|
||||||
const { gcj02ToWgs84: referenceGcj02ToWgs84 } = require("./lib/gaode-junction-reference");
|
const { gcj02ToWgs84: referenceGcj02ToWgs84 } = require("../packages/road-compiler/src/reference/gaode");
|
||||||
|
|
||||||
const source = fs.readFileSync(path.join(__dirname, "lib", "v2x-cesium-overlay.js"), "utf8");
|
const source = fs.readFileSync(path.join(__dirname, "lib", "v2x-cesium-overlay.js"), "utf8");
|
||||||
const context = {
|
const context = {
|
||||||
|
|||||||
Reference in new issue
Block a user