Compare commits
64
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
25cf82e7c7 | ||
|
|
bc845444bb | ||
|
|
bb2a1449ac | ||
|
|
1c2d091ad2 | ||
|
|
e997ece188 | ||
|
|
b7031f145a | ||
|
|
ee273c5cd6 | ||
|
|
71ba536c7c | ||
|
|
903b34b5ae | ||
|
|
f1f829c2c6 | ||
|
|
a16400ff96 | ||
|
|
8ecd794633 | ||
|
|
12aeda9a63 | ||
|
|
9a8dbc1a74 | ||
|
|
5403936ae4 | ||
|
|
0bc949bc24 | ||
|
|
6a0437ff83 | ||
|
|
3cad384b25 | ||
|
|
9e0e25aadf | ||
|
|
e9ab1f03eb | ||
|
|
1154de3ba1 | ||
|
|
c057258085 | ||
|
|
41d32457f2 | ||
|
|
5accc0a4b1 | ||
|
|
7204c28161 | ||
|
|
a63a3ae0d8 | ||
|
|
f7e71cfe9c | ||
|
|
e41bfd13ec | ||
|
|
46542c5f4e | ||
|
|
1896884900 | ||
|
|
9bb97d4507 | ||
|
|
bd38aa55d3 | ||
|
|
b318f7b641 | ||
|
|
d065dcdaf3 | ||
|
|
472a83c670 | ||
|
|
bc045177a5 | ||
|
|
8409d2c6c3 | ||
|
|
5f59ad0ef0 | ||
|
|
47efb78f1e | ||
|
|
8bfc02e66e | ||
|
|
9d42181246 | ||
|
|
fb863dafb2 | ||
|
|
7dc5c947a3 | ||
|
|
866b59acf8 | ||
|
|
4c4f4534c0 | ||
|
|
ea8a3622b9 | ||
|
|
03a8d6159b | ||
|
|
1b9829d9ed | ||
|
|
822e6ef936 | ||
|
|
3eea12c6ea | ||
|
|
3d57655497 | ||
|
|
65cf8b96d9 | ||
|
|
e1f3fc10ca | ||
|
|
f43a122ff7 | ||
|
|
3e22a1872e | ||
|
|
1da985c932 | ||
|
|
817e361477 | ||
|
|
25287777f6 | ||
|
|
a556c0fc97 | ||
|
|
1876472bf8 | ||
|
|
707e7f82f9 | ||
|
|
850e9eb344 | ||
|
|
df81a22ce8 | ||
|
|
b5fa4482f0 |
No files matched your search
@@ -4,3 +4,4 @@ outputs/
|
|||||||
__pycache__/
|
__pycache__/
|
||||||
assets/models/speedtree/
|
assets/models/speedtree/
|
||||||
assets/models/lyrog/
|
assets/models/lyrog/
|
||||||
|
inputs/osm
|
||||||
@@ -8,14 +8,14 @@
|
|||||||
|
|
||||||
## 两层配置
|
## 两层配置
|
||||||
|
|
||||||
用户只写第一层,第二层是机器生成的中间产物:
|
用户只写第一层;legacy QGIS 链路需要时才生成第二层中间产物:
|
||||||
|
|
||||||
```
|
```
|
||||||
config/areas/<id>.json ← 你写的
|
config/areas/<id>.json ← 你写的
|
||||||
│ scripts/lib/area-config.js: normalizeAreaConfig()
|
│ scripts/lib/area-config.js: normalizeAreaConfig()
|
||||||
│ 补默认值 + 推导输出路径
|
│ 补默认值 + 推导输出路径
|
||||||
▼
|
▼
|
||||||
<areaDir>/_pipeline/osm2streets-qgis.config.json ← 生成的,不要手改
|
<areaDir>/_pipeline/osm2streets-qgis.config.json ← legacy 生成的,不要手改
|
||||||
│
|
│
|
||||||
▼ build-osm2streets-qgis.js / reimport-gpkg.js
|
▼ build-osm2streets-qgis.js / reimport-gpkg.js
|
||||||
```
|
```
|
||||||
@@ -54,6 +54,8 @@ cp config/examples/template.json config/areas/my-area.json
|
|||||||
| `turnLaneArrows` | | 见下 | 从 OSM `turn:lanes:*` 生成自定义车道箭头的发布开关 |
|
| `turnLaneArrows` | | 见下 | 从 OSM `turn:lanes:*` 生成自定义车道箭头的发布开关 |
|
||||||
| `osm2streets` | | 见下 | 透传给 osm2streets 的选项 |
|
| `osm2streets` | | 见下 | 透传给 osm2streets 的选项 |
|
||||||
| `blender` | | 见下 | Blender 侧选项 |
|
| `blender` | | 见下 | Blender 侧选项 |
|
||||||
|
| `nativeRoad` | | 见下 | 原生道路编译选项 |
|
||||||
|
| `v2xPreview` | | 见下 | 可选的 Cesium 预览实时 V2X 叠加设置 |
|
||||||
| `compress` | | 见下 | 默认交付压缩阶段的 GLB 压缩选项 |
|
| `compress` | | 见下 | 默认交付压缩阶段的 GLB 压缩选项 |
|
||||||
| `budget` | | 见下 | 区域 GLB 性能与体量预算 |
|
| `budget` | | 见下 | 区域 GLB 性能与体量预算 |
|
||||||
| `outputs` | | 从 `id` 推导 | 输出路径覆盖,逃生舱 |
|
| `outputs` | | 从 `id` 推导 | 输出路径覆盖,逃生舱 |
|
||||||
@@ -65,7 +67,7 @@ cp config/examples/template.json config/areas/my-area.json
|
|||||||
|
|
||||||
| 字段 | 默认 | 说明 |
|
| 字段 | 默认 | 说明 |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| `intermediates` | `true` | 旧名 `qgis` 仍被接受 |
|
| `intermediates` | `false` | native-only 默认;旧名 `qgis` 仍被接受,显式开启才运行 legacy |
|
||||||
| `blender` | `true` | |
|
| `blender` | `true` | |
|
||||||
| `cesium` | `true` | |
|
| `cesium` | `true` | |
|
||||||
| `compress` | `true` | 压缩 staged GLB,供随后发布使用 |
|
| `compress` | `true` | 压缩 staged GLB,供随后发布使用 |
|
||||||
@@ -132,6 +134,36 @@ cp config/examples/template.json config/areas/my-area.json
|
|||||||
|---|---|---|
|
|---|---|---|
|
||||||
| `treeStyle` | `"natural"` | 合法值见 `generate_scene.py` 的 `TREE_STYLES`(`natural`、`procedural`、`shapespark`) |
|
| `treeStyle` | `"natural"` | 合法值见 `generate_scene.py` 的 `TREE_STYLES`(`natural`、`procedural`、`shapespark`) |
|
||||||
| `officeOverrides` | `""` | 旧名 `office_overrides` 仍被接受 |
|
| `officeOverrides` | `""` | 旧名 `office_overrides` 仍被接受 |
|
||||||
|
| `roadProvider` | `"native"` | Blender 道路来源。`"native"` 时仅使用 `native-road/` 的道路、路口和人行道面;`"osm2streets"` 仅用于显式 legacy/debug 构建。 |
|
||||||
|
|
||||||
|
### `nativeRoad`
|
||||||
|
|
||||||
|
| 字段 | 默认 | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| `edgeLines` | `false` | 是否输出道路边缘线。 |
|
||||||
|
| `junctionTemplates.enabled` | `false` | 启用显式绑定的参数化路口模板。 |
|
||||||
|
| `junctionTemplates.references` | `[]` | 仅支持 `cross-v1`;每项必须给出 OSM `nodeId`,可带 GCJ-02 `referenceFile` 作校准与有效性检查。 |
|
||||||
|
| `junctionTemplates.clusters` | `[]` | `cross-cluster-v1` 的相邻 OSM 节点簇。输出各外部进口的参数化渐变道路面,簇内短段与节点级路口面保留;`approachWidthMultiplier` / `approachLengthMeters` 控制渐变。可选 `referenceFile` 记录 GCJ-02 校准来源,不合并节点级道路、connector、信号或停止线语义。 |
|
||||||
|
| `junctionTemplates.clusters[].cornerRadiusMeters` | `12`(4–25) | 仅 `complex-junction-v1`:相邻进口夹角处路缘圆角的半径。圆角切于两侧最外道路边缘,只补齐夹角处的路面,不改变 connector、信号或停止线。 |
|
||||||
|
| `junctionTemplates.clusters[].outerRadiusExtraMeters` | `18`(18–35) | 仅 `complex-junction-v1`:路口中心到外部进口交接边界的额外半径。用于让圆角包住角部斑马线;未配置时保持原有 18 m。 |
|
||||||
|
|
||||||
|
### `v2xPreview`
|
||||||
|
|
||||||
|
这是 Cesium 验证预览的可选实时叠加层,不进入发布的 `package/`。默认值:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"enabled": false,
|
||||||
|
"apiBaseUrl": "/api",
|
||||||
|
"wsBaseUrl": "/websocket",
|
||||||
|
"crossCode": ""
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`apiBaseUrl` 和 `wsBaseUrl` 应使用同源反向代理路径,不能写入私有上游主机、账号或令牌。
|
||||||
|
V2X 接口返回的地图数据是 GCJ-02;浏览器预览在创建 Cesium entity 前一次性转为 WGS84,
|
||||||
|
而 native package 的 WGS84/ENU 契约保持不变。详见
|
||||||
|
[`docs/v2x-cesium-preview.md`](../../../docs/v2x-cesium-preview.md)。
|
||||||
|
|
||||||
### `compress`
|
### `compress`
|
||||||
|
|
||||||
@@ -186,7 +218,8 @@ transcode,成功后替换**package staging** 中的主 GLB 与 manifest;未
|
|||||||
|
|
||||||
静态发布路径另有 `packageDir`、`packageStagingDir`、`packageManifest`、
|
静态发布路径另有 `packageDir`、`packageStagingDir`、`packageManifest`、
|
||||||
`packageStagingManifest`、`packageModelDir`、`packageStagingModelDir` 与
|
`packageStagingManifest`、`packageModelDir`、`packageStagingModelDir` 与
|
||||||
`packagePrimaryGlb`;预览路径另有 `previewDir` 与 `previewDescriptor`。除非在迁移旧调用,
|
`packagePrimaryGlb`;预览路径另有 `previewDir`、`previewDescriptor` 与
|
||||||
|
`trafficSimulation`(native preview 的可迁移仿真描述符)。除非在迁移旧调用,
|
||||||
不要覆盖 `glb` / `metadata`:它们是 staging 内部路径,不是下游资产入口。
|
不要覆盖 `glb` / `metadata`:它们是 staging 内部路径,不是下游资产入口。
|
||||||
|
|
||||||
**优先改 `fileStem` 或 `areaDir`**——它们能一次性影响全部派生路径。逐个覆盖容易漏。
|
**优先改 `fileStem` 或 `areaDir`**——它们能一次性影响全部派生路径。逐个覆盖容易漏。
|
||||||
|
|||||||
@@ -367,6 +367,341 @@ if (!networkSaysIntersection && (roadCounts.get(endpoint.id) || 0) < 3) return n
|
|||||||
fs.writeFileSync(diagnosticsPath, `${JSON.stringify(diagnostics, null, 2)}\n`);
|
fs.writeFileSync(diagnosticsPath, `${JSON.stringify(diagnostics, null, 2)}\n`);
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Native 道路标线
|
||||||
|
|
||||||
|
### 1. 范围与触发条件
|
||||||
|
|
||||||
|
`node scripts/compile-native-roads.js --config <area>` 将原生道路标线写入
|
||||||
|
`outputs/<area>/native-road/layers/`。它不读取 osm2streets 渲染几何;只复用
|
||||||
|
`turn-lane-arrows.js` 中已测试的箭头模板。工作台 `GET /api/state` 原样服务这些
|
||||||
|
GeoJSON,native Blender 构建通过 `catalog.NATIVE_ROAD_LAYERS` 消费它们。
|
||||||
|
|
||||||
|
### 2. 图层契约
|
||||||
|
|
||||||
|
| 文件 | 语义 | 必需 provenance | Blender material layer |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `lane_separators.geojson` | 同向相邻车道的分隔线 | `native-road-lane-separator/v1` | `lane_separators` |
|
||||||
|
| `direction_arrows.geojson` | 沿定向车道重复的直行方向箭头 | `native-road-direction-arrow/v1` | `lane_arrows_webscale` |
|
||||||
|
| `turn_arrows.geojson` | 明确 `turn:lanes` 的路口动作箭头 | `native-road-turn-arrow/v1` | `lane_arrows_webscale` |
|
||||||
|
|
||||||
|
方向箭头必须带 `road_id`、`lane_id`、`osm_way_ids`、`direction`、`lane_index`、
|
||||||
|
`sequence`、`distance_along_lane_meters` 和 `placement_interval_meters`。转向箭头
|
||||||
|
必须带 `maneuver` 与 `placement_distance_meters`。两者不能共用 provenance 或假装为
|
||||||
|
彼此:前者表达沿路行驶方向,后者表达路口处允许动作。
|
||||||
|
|
||||||
|
### 3. 放置与错误矩阵
|
||||||
|
|
||||||
|
| 条件 | 结果 |
|
||||||
|
|---|---|
|
||||||
|
| 车道长度不足以容纳两端 14m 缓冲 | 不生成道路方向箭头 |
|
||||||
|
| 可用车道长度 | 从 14m 起按 32m 间距生成 `through` 箭头 |
|
||||||
|
| OSM 未提供 `turn:lanes` | 不生成路口转向箭头 |
|
||||||
|
| `turn:lanes` 存在但动作不受已测试模板支持 | 记录诊断,不猜测动作 |
|
||||||
|
| native Blender 构建缺任一图层文件 | 在 `ensureNativeRoadLayers()` 失败,不能静默漏画 |
|
||||||
|
|
||||||
|
### 4. 必需测试
|
||||||
|
|
||||||
|
- `npm run test:native-road`:方向箭头的 Polygon、provenance、间距,以及无标签道路
|
||||||
|
不生成路口转向箭头。
|
||||||
|
- `npm run test:road-workbench`:方向箭头开关、选择溯源和概览标签。
|
||||||
|
- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender,cesium,preview --road-provider native`:日志必须列出
|
||||||
|
`direction_arrows` 与 `turn_arrows`,且不运行 `package`。
|
||||||
|
|
||||||
|
### 5. 错误与正确写法
|
||||||
|
|
||||||
|
错误:把默认 `through` 当作路口 `turn:lanes` 动作,统一写入 `turn_arrows.geojson`。
|
||||||
|
|
||||||
|
正确:道路方向箭头进入 `direction_arrows.geojson`;只有 OSM 明确标注的动作进入
|
||||||
|
`turn_arrows.geojson`。工作台用两个开关呈现,Blender 复用同一现有箭头材质。
|
||||||
|
|
||||||
|
## Native 普通路口圆角
|
||||||
|
|
||||||
|
### 1. 范围与触发条件
|
||||||
|
|
||||||
|
`compile-native-roads.js` 为普通 T / 十字路口生成 `intersection_surface.geojson`
|
||||||
|
和 `sidewalk_surface.geojson` 的路口边界。路口道路面必须在同一 cutback 处结束,不能
|
||||||
|
用未裁剪的道路矩形覆盖圆角边界。
|
||||||
|
|
||||||
|
### 2. 几何契约
|
||||||
|
|
||||||
|
- 相邻道路边缘使用两条支持切线的交点作为二次曲线控制点;采样段数由
|
||||||
|
`JUNCTION_CURVE_SEGMENTS` 统一控制。
|
||||||
|
- 机动车路口边界、人行道内侧路缘和人行道外侧边界都必须使用同一切线圆角规则;外侧
|
||||||
|
不能只对内侧采样点做线性偏移,避免内外曲率不一致。
|
||||||
|
- `boundary_mode` 使用 `rounded-approach-envelope`,无法安全构造的角保持确定性直线
|
||||||
|
回退,并写入 `junction-rounded-corner-fallback` warning。
|
||||||
|
- 已发布的 connector 必须包含在最终边界内,边界退化或 connector 越界时才允许使用
|
||||||
|
`connector-convex-fallback`。
|
||||||
|
|
||||||
|
### 3. 校验与错误矩阵
|
||||||
|
|
||||||
|
| 条件 | 结果 |
|
||||||
|
|---|---|
|
||||||
|
| 支持切线交点有限且曲线不过远 | 生成采样圆角 |
|
||||||
|
| 切线近似平行或交点退化 | 保留该角直线并记录 `junction-rounded-corner-fallback` |
|
||||||
|
| 边界自相交或 connector 越界 | 使用 connector 凸包兜底;仍自相交则不发布路口面 |
|
||||||
|
|
||||||
|
### 4. 必需测试
|
||||||
|
|
||||||
|
- `npm run test:native-road`:普通 T / 十字路口的圆角顶点数、内收方向、内外人行道
|
||||||
|
曲线和 continuation 语义。
|
||||||
|
- `npm run test:road-workbench`:工作台仍能加载 native 路口及人行道图层。
|
||||||
|
- `npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json`。
|
||||||
|
- `npm run road:check -- --config config/areas/nantaizi-lake-innovation-valley.json`。
|
||||||
|
|
||||||
|
### 5. 错误与正确写法
|
||||||
|
|
||||||
|
错误:先对路缘生成圆角,再把外侧边界按每个采样点线性平移;这会导致内外曲率不同,
|
||||||
|
在人行道角落留下不一致的折面。
|
||||||
|
|
||||||
|
正确:对内侧和外侧分别用相同的道路边缘支持切线规则生成曲线,仅在外侧切线退化时
|
||||||
|
使用确定性的偏移回退。
|
||||||
|
|
||||||
|
## Native 道路中心虚线
|
||||||
|
|
||||||
|
### 1. 范围与触发条件
|
||||||
|
|
||||||
|
`node scripts/compile-native-roads.js --config <area>` 为可确认的双向非 service
|
||||||
|
道路段写入 `native-road/layers/center_lines.geojson`。这是原生几何:只能依据
|
||||||
|
canonical OSM 中心线、native 双方向道路模型和 native 路口 cutback 生成,osm2streets
|
||||||
|
的 `center_lines.geojson` 只可作为视觉基准,绝不能作为输入。
|
||||||
|
|
||||||
|
### 2. 调用形式
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run road:workbench -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender,cesium,preview --road-provider native
|
||||||
|
```
|
||||||
|
|
||||||
|
工作台 `GET /api/state` 通过 `layers.centerLines` 返回该 FeatureCollection;native
|
||||||
|
Blender adapter 必须将 source `center_lines` 映射到既有 `center_lines` material layer。
|
||||||
|
|
||||||
|
### 3. 契约
|
||||||
|
|
||||||
|
- 每一 dash 均为 Polygon,长 `2m`、宽 `0.25m`、确定性间隔 `2m`,使用
|
||||||
|
`native-road-center-line/v1` provenance。
|
||||||
|
- 要素必须含有 `native_id`、`segment_id`、`road_id`、`directional_road_ids`、
|
||||||
|
`osm_way_ids`、`dash_index`、`dash_length_m`、`dash_gap_m` 与 `placement_rule`,以便
|
||||||
|
Workbench 用中文显示“道路中心虚线”并可回溯来源。
|
||||||
|
- 只有同一 `segment_id` 恰有一条 forward 和一条 backward native road 时才生成;单向、
|
||||||
|
`highway=service` 或退化中心线都不能伪造中心线。退化中心线须写
|
||||||
|
`invalid-center-line` diagnostic。
|
||||||
|
- 线段必须先经过 native junction cutback;再与 crosswalk、vehicle stop line 的控制面
|
||||||
|
求冲突,冲突 dash 直接略去。控制标线优先于中心虚线。
|
||||||
|
- `compiled.json.layers.centerLines`、`comparison.json.nativeCenterLineFeatures`、
|
||||||
|
`build-area.js` 的 native input records 与 required-layer 验证必须全部使用
|
||||||
|
`layers/center_lines.geojson`;缺失时在 Blender 启动前失败,不得静默漏画。
|
||||||
|
|
||||||
|
### 4. 校验与错误矩阵
|
||||||
|
|
||||||
|
| 条件 | 结果 |
|
||||||
|
|---|---|
|
||||||
|
| 可确认的双向普通道路段 | 生成 2m / 0.25m 黄虚线,固定 2m gap |
|
||||||
|
| 单向或 `highway=service` 道路 | 不生成中心虚线 |
|
||||||
|
| 中心线不足两点、长度不可用 | `invalid-center-line` diagnostic,不写畸形 Polygon |
|
||||||
|
| dash 进入 junction cutback | trim 后不生成该范围 dash |
|
||||||
|
| dash 与斑马线或停止线相交 | 不生成冲突 dash |
|
||||||
|
| native Blender 输入缺 `center_lines.geojson` | `ensureNativeRoadLayers()` 抛错 |
|
||||||
|
|
||||||
|
### 5. 正常、基础与错误示例
|
||||||
|
|
||||||
|
- 正常:一条有 forward/backward carriageway 的 residential 段在两个方向道路之间生成黄虚线。
|
||||||
|
- 基础:没有双向证据的道路仍可有车道分隔线,但不产生道路中心虚线。
|
||||||
|
- 错误:从 osm2streets 图层复制或裁剪中心线;这会将渲染器缺陷重新变成 native 数据依赖。
|
||||||
|
|
||||||
|
### 6. 必需测试
|
||||||
|
|
||||||
|
- `npm run test:native-road`:断言双向生成、provenance、2m 尺寸/间隔、单向和 service 跳过。
|
||||||
|
- `npm run test:road-workbench`:断言 `centerLines` API、中文开关、选择溯源和概览计数。
|
||||||
|
- `npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json`:输出合法图层,检查中心线与控制标线不重叠。
|
||||||
|
- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender,cesium,preview --road-provider native`:日志列出 `center_lines`,且不运行 `package`。
|
||||||
|
|
||||||
|
### 7. 错误与正确写法
|
||||||
|
|
||||||
|
错误:只按一条 directional road 生成中心线,或忽略控制标线。
|
||||||
|
|
||||||
|
```js
|
||||||
|
const line = road.centerline;
|
||||||
|
features.push(makeDash(line));
|
||||||
|
```
|
||||||
|
|
||||||
|
正确:先确认成对的双方向道路、做路口裁剪,再排除控制标线冲突。
|
||||||
|
|
||||||
|
```js
|
||||||
|
if (roads.length !== 2 || !forward || !backward || forward.highway === "service") continue;
|
||||||
|
const line = trimLineAtJunctions(forward.centerline, forward.sourceNodeIds, junctionPlans);
|
||||||
|
if (!ringsOverlapControl([ring], [...controls.crosswalks, ...controls.stopLines])) features.push(dash);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Native 道路中心线样式覆写
|
||||||
|
|
||||||
|
### 1. 范围与触发条件
|
||||||
|
|
||||||
|
Road Workbench 选中 `native-road-center-line/v1` 要素后,可为其 `segment_id`
|
||||||
|
保存样式覆写。覆写属于 `native-road-overrides.json`,不是对
|
||||||
|
`center_lines.geojson` 的手工编辑;重新编译必须从覆写重建图层。
|
||||||
|
|
||||||
|
### 2. 调用形式
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "道路中心线:segment:way/123/1",
|
||||||
|
"kind": "center-line-style",
|
||||||
|
"segmentId": "segment:way/123/1",
|
||||||
|
"color": "white",
|
||||||
|
"pattern": "solid"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 契约
|
||||||
|
|
||||||
|
- `color` 只能是 `yellow` 或 `white`;`pattern` 只能是 `dashed` 或 `solid`。
|
||||||
|
目标 `segmentId` 必须属于当前 native road model。
|
||||||
|
- `double: true` 只表示双黄实线,因此只能与 `color: "yellow"`、
|
||||||
|
`pattern: "solid"` 组合。编译器为每段的每个有效实线 mark 写两条相距 0.32m 的
|
||||||
|
平行 Polygon,并记录 `double: true`、`effective_style:
|
||||||
|
"double-yellow-solid"`;不得把它实现为可任意组合的双线开关。
|
||||||
|
- 未覆写段保持黄色虚线(2m dash、2m gap);`solid` 为 0 gap,但相邻的 2m
|
||||||
|
几何块须重叠 `0.04m`,避免投影精度造成可见裂缝。
|
||||||
|
- 每个生成面记录 `color`、`pattern` 和 `effective_style`。Workbench 以这些属性
|
||||||
|
着色;native Blender 将 white centre lines 分派至 `Native Center Line White`,
|
||||||
|
yellow 则继续复用 `Center Line`。
|
||||||
|
- 下拉框变化即暂存覆写,顶部“保存并重新生成”是唯一写盘/重编译动作;不要求用户
|
||||||
|
再点击一个容易遗漏的暂存按钮。
|
||||||
|
|
||||||
|
### 4. 校验与错误矩阵
|
||||||
|
|
||||||
|
| 条件 | 结果 |
|
||||||
|
|---|---|
|
||||||
|
| 合法颜色、图案和当前 segment | 保存后重新生成有效样式 |
|
||||||
|
| 非法颜色/图案或不存在 segment | `validateOverrides()` 拒绝整个请求 |
|
||||||
|
| 实线块触及控制标线 | 该块略去,不以连续性为由穿过控制标线 |
|
||||||
|
| 白色中心线进入 native Blender | 使用白线材质,不改变 legacy 图层材质 |
|
||||||
|
|
||||||
|
### 5. 正常、基础与错误示例
|
||||||
|
|
||||||
|
- 正常:点选任意 dash,选择“白色实线”,保存重编译后整段显示连续白线。
|
||||||
|
- 基础:选择“黄色虚线(默认)”仍是显式覆写,但几何与默认规则一致。
|
||||||
|
- 错误:只在 Workbench 改填充色;Blender/Cesium 会继续显示旧黄色。
|
||||||
|
|
||||||
|
### 6. 必需测试
|
||||||
|
|
||||||
|
- `npm run test:native-road`:合法/非法样式覆写、solid 属性、控制标线避让。
|
||||||
|
- `npm run test:road-workbench`:中文样式面板、下拉框自动暂存和 API payload。
|
||||||
|
- `python3 -m unittest discover blender/tests`:catalog 仍是可导入的纯 Python。
|
||||||
|
- Nantaizi native `blender,cesium,preview` 构建:既有 yellow centre lines 不回归。
|
||||||
|
|
||||||
|
### 7. 错误与正确写法
|
||||||
|
|
||||||
|
错误:实线块仅以零间隔精确相接,且每块使用高对比 outline。
|
||||||
|
|
||||||
|
正确:小幅重叠相邻块,并让 Workbench 实线 stroke 与 fill 同色。
|
||||||
|
|
||||||
|
## Native 道路外缘线样式覆写
|
||||||
|
|
||||||
|
`edge_lines.geojson` 是车行道最外侧边界标线,使用 `native-road-edge-line/v1`
|
||||||
|
provenance。单向道路生成左右两条外缘线;双向道路每个方向只生成远离道路中心的外缘
|
||||||
|
线,双向道路中间分界由 `center_lines.geojson` 负责。默认是白色实线,必须带
|
||||||
|
`road_id`、`side`(`left` / `right`)、`osm_way_ids`、`color`、`pattern` 与
|
||||||
|
`effective_style`。
|
||||||
|
|
||||||
|
区域配置中的 `nativeRoad.edgeLines` 默认是 `false`;因此 native Blender/Cesium 默认不
|
||||||
|
生成或显示该层。只有明确设置为 `true` 才会发布 `edge_lines.geojson` 并交给下游消费。
|
||||||
|
|
||||||
|
Road Workbench 点选外缘线后以中文显示其方向侧边,可暂存以下 area-local 覆写:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "道路外缘线:road:way/123:forward:left",
|
||||||
|
"kind": "edge-line-style",
|
||||||
|
"roadId": "road:way/123:forward",
|
||||||
|
"side": "left",
|
||||||
|
"color": "white",
|
||||||
|
"pattern": "solid"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`roadId` 必须是当前 directional native road 的精确 ID,`side` 必须为 `left` 或 `right`。
|
||||||
|
实线使用连续 offset line;虚线使用确定性
|
||||||
|
2m mark / 2m gap。工作台的暂存与“保存并重新生成”是唯一的写盘路径,不能只改浏览器填充色;
|
||||||
|
native Blender 将该层映射到既有 `lane_separators` material layer。
|
||||||
|
|
||||||
|
## Native 控制标线
|
||||||
|
|
||||||
|
### 1. 范围与触发条件
|
||||||
|
|
||||||
|
`node scripts/compile-native-roads.js --config <area>` 为 native road provider
|
||||||
|
生成 `crosswalks.geojson` 和 `vehicle_stop_lines.geojson`。这是原生道路的独立
|
||||||
|
产物,禁止读取 osm2streets 的渲染图层作为几何输入。
|
||||||
|
|
||||||
|
### 2. 调用形式
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run road:workbench -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
```
|
||||||
|
|
||||||
|
工作台 `GET /api/state` 通过 `layers.crosswalks` 和
|
||||||
|
`layers.vehicleStopLines` 返回两个 FeatureCollection。
|
||||||
|
|
||||||
|
### 3. 契约
|
||||||
|
|
||||||
|
- 只有 `highway=crossing` 且 `crossing:markings` 不是 `no`、`none` 或
|
||||||
|
`unmarked` 的 OSM 节点可以生成斑马线。每个安全匹配点生成六条 stripe,带
|
||||||
|
`crossing_node_id`、`road_id`、`lane_id`、`osm_way_ids`、`direction`、
|
||||||
|
`placement_method`、`junction_inset_m` 和 `native-road-crosswalk/v1` provenance。
|
||||||
|
- 停止线还必须对应一个启用的 native arrival endpoint,且过街节点位于该进口到
|
||||||
|
路口的安全距离内;其 provenance 是 `native-road-stop-line/v1`。不能确认进口
|
||||||
|
时保留斑马线并写 `crossing-no-safe-stop-line` diagnostic,不得猜测一条线。停止线
|
||||||
|
必须复用斑马线的 `junction_inset_m`,保持与斑马线的上游间距。
|
||||||
|
- 有安全进口且存在普通路口 plan 时,斑马线中心推进到 cutback 内约 1.5 米;单次
|
||||||
|
最大推进 4 米。`junction_inset_m` 记录实际推进量,避免远离路口的 crossing 被过度
|
||||||
|
移动。
|
||||||
|
- `catalog.NATIVE_ROAD_LAYERS` 将两个源层映射到现有的 `crosswalks` 和
|
||||||
|
`vehicle_stop_lines` 材质层。不得把它们加入 legacy `SCENE_LAYERS`。
|
||||||
|
- 控制标线优先于箭头:默认直行箭头与其相交时跳过;路口转向箭头依次尝试在距路口
|
||||||
|
6、10、14、18、22 米处放置,均冲突时记录 `turn-arrow-control-conflict`。
|
||||||
|
|
||||||
|
### 4. 校验与错误矩阵
|
||||||
|
|
||||||
|
| 条件 | 结果 |
|
||||||
|
|---|---|
|
||||||
|
| 标记过街没有可匹配 native lane | `crossing-no-native-lane`,不生成任何控制标线 |
|
||||||
|
| 有横道但没有安全进口方向 | 生成斑马线,记录 `crossing-no-safe-stop-line`,不生成停止线 |
|
||||||
|
| 箭头与任一控制标线相交 | 直行箭头跳过;转向箭头后移或记录冲突 diagnostic |
|
||||||
|
| native Blender 输入缺任一控制图层 | `ensureNativeRoadLayers()` 在启动 Blender 前失败 |
|
||||||
|
|
||||||
|
### 5. 正常、基础与错误示例
|
||||||
|
|
||||||
|
- 正常:一个靠近路口的 marked crossing 生成 6 条斑马线和 1 条进口停止线。
|
||||||
|
- 基础:一条孤立的 marked crossing 可以生成斑马线,但不能凭邻近道路方向臆造停止线。
|
||||||
|
- 错误:先生成箭头再叠加停止线,导致两者重叠;控制标线是道路控制语义,必须优先。
|
||||||
|
|
||||||
|
### 6. 必需测试
|
||||||
|
|
||||||
|
- `npm run test:native-road`:断言 marked / unmarked / 无 native lane 的输出,停止线的
|
||||||
|
provenance、斑马线与停止线共享 `junction_inset_m`,以及箭头遇控制标线时后移。
|
||||||
|
- `npm run test:road-workbench`:断言 controls 开关、两条 API layer 和中文选中溯源。
|
||||||
|
- `npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json`:核查两层
|
||||||
|
feature count 及每条停止线都是 native arrival direction。
|
||||||
|
- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender,cesium,preview --road-provider native`:不运行 `package`。
|
||||||
|
|
||||||
|
### 7. 错误与正确写法
|
||||||
|
|
||||||
|
错误:以最近任意方向车道和固定正向偏移生成停止线。
|
||||||
|
|
||||||
|
```js
|
||||||
|
const stopCenter = offsetByMeters(nearestLane.point, nearestLane.axis, 2.7);
|
||||||
|
```
|
||||||
|
|
||||||
|
正确:先确认该方向的终点是一个已启用的路口 arrival,再在人行横道的上游生成停止线。
|
||||||
|
|
||||||
|
```js
|
||||||
|
const approach = candidates.find((item) => arrivalEndpointIds.has(`endpoint:${item.road.id}:end`));
|
||||||
|
const stopCenter = offsetByMeters(laneCenterAtCrossing, approach.placement.axis, -2.7);
|
||||||
|
```
|
||||||
|
|
||||||
## 斑马线与停止线来源
|
## 斑马线与停止线来源
|
||||||
|
|
||||||
### 1. 范围与触发条件
|
### 1. 范围与触发条件
|
||||||
@@ -480,6 +815,32 @@ area.outputs.trafficSignals
|
|||||||
- `layout.mastHeightMeters` 与 `layout.headCenterHeightMeters` 必须相等,表示横杆与灯壳的
|
- `layout.mastHeightMeters` 与 `layout.headCenterHeightMeters` 必须相等,表示横杆与灯壳的
|
||||||
中心对齐;`lensVerticalOffsetsMeters` 以灯壳中心为基准,正值向上、负值向下。当前倒计时牌
|
中心对齐;`lensVerticalOffsetsMeters` 以灯壳中心为基准,正值向上、负值向下。当前倒计时牌
|
||||||
垂直偏移为 `0`,必须贴在横杆上而非悬挂。
|
垂直偏移为 `0`,必须贴在横杆上而非悬挂。
|
||||||
|
- 复合路口中,具有相同 `cluster_id` 的停止线按道路轴线匹配 OSM control arm;轴线的两个
|
||||||
|
极性必须视为等价,但每条候选停止线仍只能消费一次。普通路口继续使用有向进口匹配,不能
|
||||||
|
用复合路口的无向规则覆盖普通路口。
|
||||||
|
- 复合路口的中心绿化带/中央分隔带不由 native 复合模板伪造;模板只生成 OSM 道路和路口
|
||||||
|
内必要的安全岛。每条生成的复合进口车道须在停止线外侧上游约 `8m` 生成一支与车道拓扑
|
||||||
|
一致的左转、直行或右转箭头;不得额外叠加一套固定直行箭头。
|
||||||
|
- **控制要素避让顺序**:`buildComplexJunctionGeometry` 在 `compileLaneCenterlines` 之前生成,
|
||||||
|
产出的 `complex-crosswalk` / `complex-corner-crosswalk` / `complex-stop-line` 必须以
|
||||||
|
`{ crosswalks, stopLines }` 参数传入 `compileLaneCenterlines`。车道中心线、车道分隔线、
|
||||||
|
中心虚线、导向箭头都在这一裁剪之后才落地。这里的裁剪对象包括两类车道几何:一是簇
|
||||||
|
边界上的 OSM 车道,二是模板自造的 `cluster-approach-lane` 预览车道。裁剪必须先按到
|
||||||
|
路口中心的距离把线定向为“外向内”,再复用 `trimLineBeforeFirstControl`:因为 OSM 车道
|
||||||
|
由簇边缘向外指、预览车道由外圈向核心指,两种朝向都存在,直接裁会裁反。裁剪后的几何
|
||||||
|
同时喂给车道标线源(`markingLanes[i].coordinates`),否则分隔线/箭头会画到斑马线之外
|
||||||
|
继续侵入核心区。拓扑几何 `coordinates`(供 connector 使用)不得裁剪,否则 turn path
|
||||||
|
会断。发布几何 vs 拓扑几何的双轨在 `compileLaneCenterlines` 内并存,别合并。
|
||||||
|
- **复合路口人行道转角**:直步行带被 `trimLineAtComplexCluster` 裁在簇外圈,两条相邻的
|
||||||
|
臂之间会留一个楔形无覆盖区。转角带由 `buildComplexJunctionGeometry` 与 `complex-corner-fillet`
|
||||||
|
共用同一 `curve` / `tangents` / `edges` / `apex` 复用生成,不重新拟合曲线;宽度
|
||||||
|
`SIDEWALK_WIDTH_METERS = 2` 必须与 `native-road.js:DEFAULT_SIDEWALK_WIDTH_METERS` 保持
|
||||||
|
一致,法线方向按“离簇中心更远”选取(路缘相对中心是星形的)。判定两侧臂是否都带步行带
|
||||||
|
时必须按臂的外向方向翻转 road 自身的 `sidewalkLeft/Right`,因为那是相对数字化方向的。
|
||||||
|
端头以 `SIDEWALK_CORNER_OVERRUN_METERS = 6` 冗余越过簇边界,让转角带和直条带自然重叠,
|
||||||
|
不追求精确缝合。自交(`ringSelfIntersects`)或任一坐标非有限时跳过并报
|
||||||
|
`complex-junction-sidewalk-corner-fallback`;不允许硬塞坏几何。产物经 `islands` 通道
|
||||||
|
与安全岛一同并入 `generatedComplexSidewalks`,最终落入 `sidewalk_surface.geojson`。
|
||||||
|
|
||||||
### 4. Validation & Error Matrix
|
### 4. Validation & Error Matrix
|
||||||
|
|
||||||
@@ -489,6 +850,9 @@ area.outputs.trafficSignals
|
|||||||
| 直接运行 `blender` / `preview` 但锚点不存在 | 在启动外部工具前报 `Traffic signal anchors not found` |
|
| 直接运行 `blender` / `preview` 但锚点不存在 | 在启动外部工具前报 `Traffic signal anchors not found` |
|
||||||
| `signal_uid` 缺失/重复、非空 `display_id` 重复、字段或 Point 无效 | 重导入在替换任何输出前失败 |
|
| `signal_uid` 缺失/重复、非空 `display_id` 重复、字段或 Point 无效 | 重导入在替换任何输出前失败 |
|
||||||
| 用户仅修改 QGIS 后运行 `reimport` | 重新生成锚点,不沿用旧坐标 |
|
| 用户仅修改 QGIS 后运行 `reimport` | 重新生成锚点,不沿用旧坐标 |
|
||||||
|
| 复合路口车道整体落在斑马线/停止线内 | 报 `lane-centerline-fully-inside-control`,回退为未裁剪发布几何,不写空 LineString |
|
||||||
|
| 复合路口人行道转角自交或坐标非有限 | 报 `complex-junction-sidewalk-corner-fallback`,跳过该角,两侧步行带保持断开 |
|
||||||
|
| 有 `referenceFile` 时同时配置 `coreRadiusMeters` | 校准值胜出,报 `complex-junction-configured-radius-ignored` 记录被忽略的配置值 |
|
||||||
|
|
||||||
### 5. Good/Base/Bad Cases
|
### 5. Good/Base/Bad Cases
|
||||||
|
|
||||||
@@ -1029,9 +1393,9 @@ gpkg: path.resolve(outputOverrides.gpkg || path.join(areaDir, `${fileStem}.gpkg`
|
|||||||
|
|
||||||
| 阶段 | 做什么 | 读 | 写 |
|
| 阶段 | 做什么 | 读 | 写 |
|
||||||
|---|---|---|---|
|
|---|---|---|---|
|
||||||
| `intermediates` | OSM → osm2streets GeoJSON → GeoPackage → QGIS 工程 + 预览图 | `.osm` | `osm2streets_web_out/`、`.gpkg`、`.qgz`、`-preview.png` |
|
| `intermediates` |(显式 legacy)OSM → osm2streets GeoJSON → GeoPackage → QGIS 工程 + 预览图 | `.osm` | `osm2streets_web_out/`、`.gpkg`、`.qgz`、`-preview.png` |
|
||||||
| `reimport` | GeoPackage → GeoJSON(**反向**) | `.gpkg` | `osm2streets_web_out/` |
|
| `reimport` | GeoPackage → GeoJSON(**反向**) | `.gpkg` | `osm2streets_web_out/` |
|
||||||
| `blender` | OSM + GeoJSON → 场景 | `.osm`、`osm2streets_web_out/` | `.blend`、`.png` |
|
| `blender` | 默认 OSM → native road compiler → Blender 场景;legacy provider 时读取 GeoJSON | `.osm`、`native-road/`(legacy 为 `osm2streets_web_out/`) | `.blend`、`.png` |
|
||||||
| `cesium` | 场景 → static staging GLB + manifest | `.blend` | `_pipeline/package-staging/models/*.glb`、staged manifest;动态 GLB 到 `_preview/` |
|
| `cesium` | 场景 → static staging GLB + manifest | `.blend` | `_pipeline/package-staging/models/*.glb`、staged manifest;动态 GLB 到 `_preview/` |
|
||||||
| `compress` | 压缩 Cesium staging 主模型 | staged `.glb`、manifest | 压缩 staged `.glb`、manifest |
|
| `compress` | 压缩 Cesium staging 主模型 | staged `.glb`、manifest | 压缩 staged `.glb`、manifest |
|
||||||
| `package` | 校验并原子发布静态资产包 | staging manifest 与 models | `package/manifest.json`、`package/models/*.glb` |
|
| `package` | 校验并原子发布静态资产包 | staging manifest 与 models | `package/manifest.json`、`package/models/*.glb` |
|
||||||
@@ -1051,12 +1415,11 @@ gpkg: path.resolve(outputOverrides.gpkg || path.join(areaDir, `${fileStem}.gpkg`
|
|||||||
|
|
||||||
未知阶段名**抛错并列出合法值**(`:181`),不静默忽略。
|
未知阶段名**抛错并列出合法值**(`:181`),不静默忽略。
|
||||||
|
|
||||||
### `all` 不含 `reimport`
|
### `all` 是 native-only 完整构建
|
||||||
|
|
||||||
```js
|
```js
|
||||||
// 'reimport' is deliberately absent from 'all': it is a recovery step for
|
// Legacy intermediates/reimport are deliberately absent from 'all'.
|
||||||
// hand-edited GeoPackages, never part of a full build. build-area.js:159-160
|
all: ["blender", "cesium", "compress", "package", "preview"],
|
||||||
all: ["intermediates", "blender", "cesium", "compress", "package", "preview"],
|
|
||||||
```
|
```
|
||||||
|
|
||||||
`compress`、`package`、`preview` 均在 `all` 中,确保完整构建以压缩后的可复用静态 package
|
`compress`、`package`、`preview` 均在 `all` 中,确保完整构建以压缩后的可复用静态 package
|
||||||
|
|||||||
@@ -120,6 +120,56 @@ SCENE_LAYERS.forEach((layer, index) => {
|
|||||||
|
|
||||||
## Blender 调用
|
## Blender 调用
|
||||||
|
|
||||||
|
### macOS Blender 4.5 的 Metal 启动兼容
|
||||||
|
|
||||||
|
#### 1. Scope / Trigger
|
||||||
|
|
||||||
|
`export_cesium.py` 在 macOS 的 Blender 4.5.12 后台启动时,可能在 Python 脚本加载前的 Metal 扩展探测中崩溃;这不是场景或道路数据错误。
|
||||||
|
|
||||||
|
#### 2. Signatures
|
||||||
|
|
||||||
|
Cesium 阶段的调用参数必须包含:
|
||||||
|
|
||||||
|
```text
|
||||||
|
--background --factory-startup --debug-gpu-force-workarounds --python blender/export_cesium.py -- ...
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. Contracts
|
||||||
|
|
||||||
|
`--debug-gpu-force-workarounds` 是 Blender 的官方 CLI 参数。它只约束导出进程的 GPU 扩展探测,不改变 `.blend`、GeoJSON 或导出脚本的输入输出契约。
|
||||||
|
|
||||||
|
#### 4. Validation & Error Matrix
|
||||||
|
|
||||||
|
| 情况 | 结果 |
|
||||||
|
|---|---|
|
||||||
|
| 缺少该参数且启动时崩在 Metal 初始化 | 不应归因于道路数据;补齐参数后重跑 Cesium 阶段 |
|
||||||
|
| 参数存在且 `CESIUM_EXPORT_DONE` / stage manifest 写出 | 继续 GLB digest 与预览验证 |
|
||||||
|
|
||||||
|
#### 5. Good / Base / Bad Cases
|
||||||
|
|
||||||
|
- Good: 保留 `--factory-startup`,并在 Cesium 导出加入 workaround。
|
||||||
|
- Base: Blender 场景阶段未受影响时,不额外改变其启动参数。
|
||||||
|
- Bad: 为绕过启动崩溃删除 `--factory-startup`,这会重新引入本机偏好和 addon 的不确定性。
|
||||||
|
|
||||||
|
#### 6. Tests Required
|
||||||
|
|
||||||
|
- `npm run test:build-stages` 断言导出参数仍包含 workaround。
|
||||||
|
- 对目标区域运行 `--stages blender,cesium,preview`,并用 `glb-digest.js` 解析输出。
|
||||||
|
|
||||||
|
#### 7. Wrong vs Correct
|
||||||
|
|
||||||
|
Wrong:
|
||||||
|
|
||||||
|
```text
|
||||||
|
--background --python blender/export_cesium.py
|
||||||
|
```
|
||||||
|
|
||||||
|
Correct:
|
||||||
|
|
||||||
|
```text
|
||||||
|
--background --factory-startup --debug-gpu-force-workarounds --python blender/export_cesium.py
|
||||||
|
```
|
||||||
|
|
||||||
### 两种调用姿势
|
### 两种调用姿势
|
||||||
|
|
||||||
| 阶段 | 参数 | 出处 |
|
| 阶段 | 参数 | 出处 |
|
||||||
|
|||||||
@@ -15,6 +15,7 @@
|
|||||||
| 加阶段、加 CLI 参数、改配置字段 | [CLI 与阶段](./cli-and-stages.md) |
|
| 加阶段、加 CLI 参数、改配置字段 | [CLI 与阶段](./cli-and-stages.md) |
|
||||||
| 改区域诊断/质量门命令或共享区域配置归一化 | [CLI 与阶段](./cli-and-stages.md#区域诊断命令) 和 [质量门](./cli-and-stages.md#区域质量门命令) |
|
| 改区域诊断/质量门命令或共享区域配置归一化 | [CLI 与阶段](./cli-and-stages.md#区域诊断命令) 和 [质量门](./cli-and-stages.md#区域质量门命令) |
|
||||||
| 改 stage manifest 写入、读取或 stale 判断 | [CLI 与阶段](./cli-and-stages.md#stage-manifest-契约) |
|
| 改 stage manifest 写入、读取或 stale 判断 | [CLI 与阶段](./cli-and-stages.md#stage-manifest-契约) |
|
||||||
|
| 改复合路口几何(`buildComplexJunctionGeometry`、车道控制避让、人行道转角) | [CLI 与阶段](./cli-and-stages.md#可编辑信号设施与运行时锚点的跨阶段消费) 的复合路口小节 |
|
||||||
| 改预览页生成 | [../preview/](../preview/index.md) |
|
| 改预览页生成 | [../preview/](../preview/index.md) |
|
||||||
| 声称"纯重构,产物不变" | [产物一致性指南](../guides/artifact-parity-guide.md) |
|
| 声称"纯重构,产物不变" | [产物一致性指南](../guides/artifact-parity-guide.md) |
|
||||||
|
|
||||||
@@ -30,7 +31,7 @@ config/areas/<id>.json
|
|||||||
▼ build-area.js — 阶段调度
|
▼ build-area.js — 阶段调度
|
||||||
_pipeline/osm2streets-qgis.config.json (派生配置)
|
_pipeline/osm2streets-qgis.config.json (派生配置)
|
||||||
│
|
│
|
||||||
├─[intermediates]─▶ build-osm2streets-qgis.js
|
├─[intermediates]─▶ build-osm2streets-qgis.js(显式 legacy/reference)
|
||||||
│ osm2streets-js-node 解析 .osm
|
│ osm2streets-js-node 解析 .osm
|
||||||
│ → splitLayers() 拆成九个图层
|
│ → splitLayers() 拆成九个图层
|
||||||
│ → normalize-lane-arrows.py(QGIS Python)
|
│ → normalize-lane-arrows.py(QGIS Python)
|
||||||
@@ -45,8 +46,8 @@ config/areas/<id>.json
|
|||||||
│ → 重建 scene.geojson + scene_style.json
|
│ → 重建 scene.geojson + scene_style.json
|
||||||
│ → _pipeline/stages/reimport.manifest.json
|
│ → _pipeline/stages/reimport.manifest.json
|
||||||
│
|
│
|
||||||
├─[blender]───────▶ Blender + blender/generate_scene.py
|
├─[blender]───────▶ compile-native-roads.js + Blender + blender/generate_scene.py
|
||||||
│ 读 .osm + osm2streets_web_out/
|
│ 默认读 .osm + native-road/
|
||||||
│ → <id>.blend + <id>.png
|
│ → <id>.blend + <id>.png
|
||||||
│ → _pipeline/stages/blender.manifest.json
|
│ → _pipeline/stages/blender.manifest.json
|
||||||
│
|
│
|
||||||
@@ -62,7 +63,7 @@ config/areas/<id>.json
|
|||||||
│ → package/manifest.json + package/models/*.glb
|
│ → package/manifest.json + package/models/*.glb
|
||||||
│ → _pipeline/stages/package.manifest.json
|
│ → _pipeline/stages/package.manifest.json
|
||||||
│
|
│
|
||||||
└─[preview]───────▶ 生成 <id>-cesium-preview.html
|
└─[preview]───────▶ 生成 <id>-cesium-preview.html(native 可无车辆路线)
|
||||||
│ + 拷贝 lib/cesium-preview.{js,css}
|
│ + 拷贝 lib/cesium-preview.{js,css}
|
||||||
+ _preview/ 车辆巡航路线、模型、动态信号
|
+ _preview/ 车辆巡航路线、模型、动态信号
|
||||||
│ → _pipeline/stages/preview.manifest.json
|
│ → _pipeline/stages/preview.manifest.json
|
||||||
|
|||||||
@@ -307,6 +307,105 @@ npm run build:area -- --config config/areas/<area>.json --stages cesium
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 实时 V2X 车辆仅数据源
|
||||||
|
|
||||||
|
### 1. Scope / Trigger
|
||||||
|
|
||||||
|
适用于开启 `v2xPreview.enabled` 的 Cesium 运营预览。触发:修改
|
||||||
|
`v2x-cesium-overlay.js`、preview descriptor 的 `routeName`、或实时车辆展示。
|
||||||
|
|
||||||
|
### 2. Signatures
|
||||||
|
|
||||||
|
```text
|
||||||
|
WS /network/ws/network/signal?authorization=<token>
|
||||||
|
WS /network/ws/network/obuPosition?authorization=<token>
|
||||||
|
WS /network/ws/network/targetPosition?authorization=<token>
|
||||||
|
```
|
||||||
|
|
||||||
|
OBU 消息使用 `carCode|obuCode`、`lon`、`lat`、`angle`、`speed`;目标识别消息使用
|
||||||
|
`data[deviceId][]` 内的 `id`、`longitude`、`latitude`、`type`、`subType`、`angle`、`speed`。
|
||||||
|
两类车辆消息的根部还带 `interval`(推送间隔,`0` 视为 `500`)。
|
||||||
|
信号灯消息使用 `lamps[]` 内的 `phaseNo`、`status`、`countDown`。
|
||||||
|
|
||||||
|
### 3. Contracts
|
||||||
|
|
||||||
|
- 两条车辆流均为 GCJ-02,必须在实体创建前恰好调用一次 `gcj02ToWgs84`。
|
||||||
|
- 本预览的 `routeName` 必须为 `null`,且不得生成 `trafficSimulation` 描述符。
|
||||||
|
真正的不变量是**不得有生成路线或交通仿真**,而不是「没有车模型」——
|
||||||
|
实时 V2X 车辆需要打包的车模型才能渲染,故 `vehicleModelNames` 由
|
||||||
|
`writeVehicleModel(area)` 正常写出(`build-area.js:writeCesiumPreview`),
|
||||||
|
`vehicleModelName` 取其首项。早期版本靠清空模型列表来阻止仿真车辆,
|
||||||
|
该机制已不适用,不要再用它作为约束手段。
|
||||||
|
- 每辆实时车保留最多 24 个已转换的位置作为实际轨迹;轨迹不是推测路径。
|
||||||
|
- **灯色码字典只有一份**,取自源看板 `HologramCross/components/utils.ts`:
|
||||||
|
`11=灭 21=红 22=黄 23=绿 31=其他`,未知码归入「其他」,**不得**落到红色。
|
||||||
|
overlay 归一化为 `{nodeKeys, color, countDown}` 后单向传给 `cesium-preview.js`;
|
||||||
|
预览层不得自带第二份字典。
|
||||||
|
- **三条 socket 必须发心跳** `{"heartBeat":"ping"}` / 30000ms,并在断线后退避重连,
|
||||||
|
且**重连后重放订阅帧**(signal 发 `junctionId`,obu 发 bounds,target 发 `deviceId`)。
|
||||||
|
缺心跳会被服务端断开,画面在一分钟后静默变空。
|
||||||
|
- **相位到原生灯头靠几何绑定**:`traffic-signals.json` 无 `phaseNo`,用 link 末段停止线点与
|
||||||
|
航向匹配原生 `stopLongitude/stopLatitude` 与行车方向;行车方向 =
|
||||||
|
`faceHeadingDegrees + 180`(生成侧 `scripts/lib/traffic-signals.js` 定义
|
||||||
|
`mast = travel - 90`、`face = travel + 180`)。
|
||||||
|
一相位可点亮多条进口道,一条 link 可点亮同进口道多个灯头,两侧都取并集。
|
||||||
|
未绑定相位须计数上报,可用 `v2xPreview.phaseSignalMap` 显式覆盖。
|
||||||
|
- **车辆生命周期**:超过 `interval * 1.5` 未更新即隐藏(不删除),隐藏项作为同模型的可复用槽位;
|
||||||
|
socket 断开清空车辆。OBU 数据 hook 标记为 `car_obu.glb`,但 dashboard 的最终
|
||||||
|
`CrossCars` 模板实际渲染 `11.glb`,预览必须以 `11.glb` 为准;目标车为
|
||||||
|
`${type}${subType}.glb`。`11/12/13/14/15/16/17/31/221/222.glb` 必须打入
|
||||||
|
`_preview/v2x-vehicles/`。
|
||||||
|
- **可见性是运行时契约**:有效推送创建的模型必须在路口概览下至少为 `28px`,并允许最大
|
||||||
|
`8x` 放大;位置高度须高于静态道路表面。首次有效车辆推送应聚焦到车群附近,标签须不受
|
||||||
|
静态 GLB 的深度遮挡。仅验证 WS 收包或 registry 条数不算通过。
|
||||||
|
- 车辆推送体解析必须容忍非严格 JSON(源看板用 `saferEval`),失败须计数并在面板可见,
|
||||||
|
**不得**静默丢弃;实现不得使用 `eval` / `new Function`。
|
||||||
|
- 周流量比 `FlowTravelRatio/queryListWeek` **不属于**实时路口范围。
|
||||||
|
|
||||||
|
### 4. Validation & Error Matrix
|
||||||
|
|
||||||
|
| 条件 | 结果 |
|
||||||
|
|---|---|
|
||||||
|
| 未登录、令牌失效、REST/WS 不可用 | 静态路口继续显示,车辆层为空,并显示实时数据不可用状态 |
|
||||||
|
| 消息不是 JSON、心跳、坐标无效 | 忽略该消息,不创建车辆;非心跳的解析失败须计数 |
|
||||||
|
| 收到有效车辆坐标 | 创建或更新真实车辆与实际轨迹 |
|
||||||
|
| 车辆超过 `interval * 1.5` 未更新 | 隐藏该车并保留槽位,不得堆积幽灵车 |
|
||||||
|
| 相机视野变化 | 节流后向 obu socket 发送 GCJ-02 四角 `bounds` |
|
||||||
|
| 视野矩形不可用 | 发空帧(等于不过滤),不得跳过发送导致空场景 |
|
||||||
|
| 相位一个都没绑定 | 面板显性提示并建议配置 `phaseSignalMap` |
|
||||||
|
|
||||||
|
### 5. Good / Base / Bad Cases
|
||||||
|
|
||||||
|
- Good:OBU 和感知目标连续推送,页面只显示对应车辆的实际行驶轨迹。
|
||||||
|
- Base:服务无数据,页面没有车辆或线路。
|
||||||
|
- Bad:将旧路线 JSON 或 `native-preview-traffic-simulation` 用作回退展示。
|
||||||
|
|
||||||
|
### 6. Tests Required
|
||||||
|
|
||||||
|
- `npm run test:v2x-cesium-preview`:校验灯色字典(含 `2`/`3` 不再是黄/绿的回归断言)、
|
||||||
|
宽松解析、几何相位绑定(对真实 `traffic-signals.json` 须达成精确一对一)、
|
||||||
|
同相位多进口道并集、车辆超时与槽位复用、心跳间隔与重连重放订阅帧、bounds 报文。
|
||||||
|
- `npm run test:preview-assets`:断言三条 WebSocket 存在,runtime 不调用
|
||||||
|
`addVehicleCruises`、不显示 simulation 诊断,且预览层**不再自带** `lampColorName`
|
||||||
|
或 `Number(status) === 3` 判断;断言实时车辆最小像素尺寸和诊断可见数量读数存在。
|
||||||
|
- 对目标区域运行 `npm run build:area -- --config config/areas/<area>.json --stages preview`,
|
||||||
|
检查 descriptor 中 `routeName` 为空、不存在 traffic-simulation 文件,
|
||||||
|
且 `vehicleModelNames` 已写出(实时车辆渲染需要)。
|
||||||
|
|
||||||
|
### 7. Wrong vs Correct
|
||||||
|
|
||||||
|
错误:接口不可用时恢复构造路线。
|
||||||
|
|
||||||
|
```js
|
||||||
|
const cruise = addVehicleCruises(viewer, routeData, signalData, start);
|
||||||
|
```
|
||||||
|
|
||||||
|
正确:保持空车辆层,等待真实流。
|
||||||
|
|
||||||
|
```js
|
||||||
|
const cruise = createLiveVehicleState();
|
||||||
|
```
|
||||||
|
|
||||||
## 本地预览必须走 HTTP
|
## 本地预览必须走 HTTP
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|||||||
@@ -31,7 +31,7 @@ classifyConnection(incomingEdge, outgoingEdge) =>
|
|||||||
`maneuvers`、`edgeIds`、`laneSegments` 与 `connectors`。道路区间来自匹配的 Driving lane polygon 中轴。
|
`maneuvers`、`edgeIds`、`laneSegments` 与 `connectors`。道路区间来自匹配的 Driving lane polygon 中轴。
|
||||||
- 路线拓扑以 `network.json` 的 internal road 和 intersection 为准;禁止把整个 OSM way 直接当作一条不可分割 edge。
|
- 路线拓扑以 `network.json` 的 internal road 和 intersection 为准;禁止把整个 OSM way 直接当作一条不可分割 edge。
|
||||||
- connector 必须绑定同一个 internal intersection,并位于对应 `intersection_surface.geojson` 内或允许的边界容差内;越界时拒绝候选路线。
|
- connector 必须绑定同一个 internal intersection,并位于对应 `intersection_surface.geojson` 内或允许的边界容差内;越界时拒绝候选路线。
|
||||||
- preview 必须将 `lane_polygons.geojson`、`network.json` 和 `intersection_surface.geojson` 作为强制输入;缺失或无效时在写产物前失败。
|
- legacy osm2streets preview 必须将 `lane_polygons.geojson`、`network.json` 和 `intersection_surface.geojson` 作为强制输入;native preview 不读取这些文件,路线缺失时保留可用预览并省略车辆巡航。
|
||||||
- route 经纬度由 Cesium 按 WGS84 直接放置;最终道路 GLB 必须由 WGS84 ECEF→ENU
|
- route 经纬度由 Cesium 按 WGS84 直接放置;最终道路 GLB 必须由 WGS84 ECEF→ENU
|
||||||
`Projector` 生成。禁止以固定米/度近似投影道路,否则即使 route 与 lane polygon
|
`Projector` 生成。禁止以固定米/度近似投影道路,否则即使 route 与 lane polygon
|
||||||
完全一致,最终画面仍会随离锚点距离产生横向偏移。
|
完全一致,最终画面仍会随离锚点距离产生横向偏移。
|
||||||
|
|||||||
@@ -0,0 +1,4 @@
|
|||||||
|
{"file": ".trellis/spec/preview/index.md", "reason": "校验改动未违反预览层约束:零依赖、无构建步骤、浏览器原生语法、IIFE。"}
|
||||||
|
{"file": "docs/v2x-cesium-preview.md", "reason": "校验文档与实现一致:接口清单、坐标契约、配置项、回滚说明。"}
|
||||||
|
{"file": ".trellis/tasks/08-24-v2x-realtime-cross-fidelity/prd.md", "reason": "AC1-AC10 是验收依据,逐条核对。"}
|
||||||
|
{"file": ".trellis/tasks/08-24-v2x-realtime-cross-fidelity/design.md", "reason": "核对灯色字典、相位映射算法、心跳与订阅帧是否与源项目逐项对齐。"}
|
||||||
@@ -0,0 +1,235 @@
|
|||||||
|
# Design — 还原 V2X 实时路口信号灯与车辆展示
|
||||||
|
|
||||||
|
## 1. 现状与根因
|
||||||
|
|
||||||
|
`scripts/lib/v2x-cesium-overlay.js`(418 行,单个 IIFE)承担了登录、REST、三个 WS、坐标转换、
|
||||||
|
实体渲染的全部职责。REST 路径与登录契约与源项目一致,失真集中在数据处理与渲染层。
|
||||||
|
|
||||||
|
逐项根因(对应 PRD 的 R1–R10):
|
||||||
|
|
||||||
|
| # | 现象 | 根因位置 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| R1 | 连接几十秒后静默中断 | `openSocket()` 无心跳、无重连 |
|
||||||
|
| R2 | 灯永远红 | `lampColor()` 判 `2`/`3`;真实码是 `21/22/23` |
|
||||||
|
| R3 | 原生信号灯模型从不亮 | `signalByPhase` 回退 `signal.id`,与 `phaseNo` 永不相等 |
|
||||||
|
| R4 | 同相位只亮一条进口道 | `state.linkPhases` 是 `Map<phase, entity>`,后写覆盖 |
|
||||||
|
| R5 | 无倒计时 | `updateSignalPhases()` 丢弃 `countDown` |
|
||||||
|
| R6 | OBU 可能一辆车都没有 | `connectObuSocket()` 的 `onOpen` 传 `null`,未发订阅帧 |
|
||||||
|
| R7 | 幽灵车堆积 | `state.vehicles` 只增不删,未用推送 `interval` |
|
||||||
|
| R8 | 车型错配 | 按数组下标取模型,非 `${type}${subType}` 语义 |
|
||||||
|
| R9 | 推送可能整条被丢 | `JSON.parse` + 静默 `catch`,源项目用 `saferEval` |
|
||||||
|
| R10 | 多余请求 | `FlowTravelRatio/queryListWeek` 不属实时路口 |
|
||||||
|
|
||||||
|
## 2. 边界与不变量
|
||||||
|
|
||||||
|
保持不变:
|
||||||
|
- overlay 仍是**单文件零依赖 IIFE**,由 `build-area.js:561` 原样拷入产物。不新增文件,避免改动
|
||||||
|
`area-preview.js` 的 HTML 装配与包契约。
|
||||||
|
- 纯逻辑继续通过 `createV2xCesiumOverlay.utils` 导出,供 `scripts/test-v2x-cesium-overlay.js`
|
||||||
|
的 `vm.runInNewContext` 沙箱直接测试(无 DOM、无 Cesium)。
|
||||||
|
- 坐标契约不变:GCJ-02 → WGS84 只在建实体前转一次。
|
||||||
|
- 令牌只进 `sessionStorage`,页面始终从登录门进入。
|
||||||
|
|
||||||
|
新增的可测试纯函数一律**不触碰 `window` / `Cesium` / `document`**,副作用留在薄薄的适配层。
|
||||||
|
|
||||||
|
## 3. 模块内部分层
|
||||||
|
|
||||||
|
文件内按四层组织,自下而上:
|
||||||
|
|
||||||
|
```
|
||||||
|
L1 纯工具 gcj02ToWgs84 / joinUrl / md5 / toWebSocketUrl / getAngle / haversine
|
||||||
|
L2 纯解析 lampColorName / parseLoosePayload / normalizeObuVehicle /
|
||||||
|
normalizeTargetVehicles / normalizeSignalLamps
|
||||||
|
L3 纯状态机 createVehicleRegistry / createPhaseBinding / buildPhaseSignalMap
|
||||||
|
L4 副作用层 createSocket(心跳/重连) / 实体渲染 / UI 面板
|
||||||
|
```
|
||||||
|
|
||||||
|
L1–L3 全部导出到 `.utils`,测试只打 L1–L3。
|
||||||
|
|
||||||
|
## 4. 关键设计决策
|
||||||
|
|
||||||
|
### 4.1 灯色状态字典(R2)
|
||||||
|
|
||||||
|
直接采用源项目 `HologramCross/components/utils.ts` 的字典,语义化返回而非直接返回颜色,
|
||||||
|
使 overlay 与 `cesium-preview.js` 共用同一套判定:
|
||||||
|
|
||||||
|
```
|
||||||
|
11 -> "off" 灭灯
|
||||||
|
21 -> "red"
|
||||||
|
22 -> "yellow"
|
||||||
|
23 -> "green"
|
||||||
|
31 -> "other"
|
||||||
|
其他 -> "other" // 不再落到 red
|
||||||
|
```
|
||||||
|
|
||||||
|
`lampColorName(status)` 放在 overlay 的 L2 并导出。`cesium-preview.js` 中重复的
|
||||||
|
`lampColorName()` 删除,改为消费 overlay 通过 `setSignalState` 回调传入的**已归一化**灯态
|
||||||
|
(`{nodeKeys, color, countDown}`),避免两处字典漂移。
|
||||||
|
|
||||||
|
> 取舍:也可以把字典抽到共享文件让两边 require,但 overlay 必须是浏览器端零依赖 IIFE,
|
||||||
|
> `cesium-preview.js` 同样是浏览器端脚本,两者无模块系统。让数据流单向(overlay → preview)
|
||||||
|
> 比共享常量更简单,也消除了双字典。
|
||||||
|
|
||||||
|
### 4.2 相位 → 原生信号灯映射(R3,本任务最难的一处)
|
||||||
|
|
||||||
|
`traffic-signals.json` 的信号灯项只有 `phaseGroup: 0`,**不含 V2X `phaseNo`**,两侧没有公共 ID。
|
||||||
|
唯一可靠的连接是**几何**。
|
||||||
|
|
||||||
|
源项目的做法给了线索:`CrossTrafficLights3D.vue:96-104` 对每条 link 取 `geom.coordinates` 的
|
||||||
|
最后两点,末点即停止线位置,两点连线的方位角即进口道航向。原生信号灯项恰好也有
|
||||||
|
`stopLongitude/stopLatitude` 与 `headingDegrees`。
|
||||||
|
|
||||||
|
因此定义纯函数:
|
||||||
|
|
||||||
|
```
|
||||||
|
buildPhaseSignalMap(links, nativeSignals, options) -> {
|
||||||
|
byPhase: Map<phaseNo, string[]>, // nodeKey 列表
|
||||||
|
bound: number,
|
||||||
|
unbound: Array<{phaseNo, reason}>,
|
||||||
|
diagnostics: Array<{linkId, matchedNodeKeys, distanceMeters, headingDeltaDegrees}>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
算法:
|
||||||
|
1. 对每条 link:解析 `geom`,取末两点,**先 GCJ-02 → WGS84**,再算 `stopPoint` 与
|
||||||
|
`approachHeading = getAngle(prePoint, lastPoint)`。
|
||||||
|
2. 对每个原生 signal:取 `(stopLongitude, stopLatitude)` 与**行车方向**。
|
||||||
|
|
||||||
|
行车方向的语义由生成侧 `scripts/lib/traffic-signals.js` 定死,不是猜的:
|
||||||
|
- `:54` `headingDegrees = atan2(axis)`,而 `axis = roadAxis(stopLineCenter → intersectionCenter)`,
|
||||||
|
即**停止线指向路口中心的行车方向**。
|
||||||
|
- `:82` `mast_heading_deg = heading - 90`
|
||||||
|
- `:83` `face_heading_deg = heading + 180`
|
||||||
|
|
||||||
|
运行时 `traffic-signals.json` 中 `headingDegrees === mastHeadingDegrees`(实测 7/7 相等,
|
||||||
|
如 `150.658`),即存的是 **mast 值**;`faceHeadingDegrees` 比它小 90(`60.658`)。因此:
|
||||||
|
|
||||||
|
```
|
||||||
|
travelHeading = (faceHeadingDegrees + 180) % 360 // 首选
|
||||||
|
= (mastHeadingDegrees + 90) % 360 // face 缺失时的等价回退
|
||||||
|
```
|
||||||
|
|
||||||
|
实测对全部 7 个信号自洽。
|
||||||
|
3. 候选条件:`haversine(stopPoint, signalStop) <= maxDistanceMeters`
|
||||||
|
且 `angleDelta(approachHeading, travelHeading) <= maxHeadingDeltaDegrees`。
|
||||||
|
4. 一条 link **可匹配多个** signal(同一进口道的多个灯头),满足 R4 的一半。
|
||||||
|
5. link 的 `phaseList` 中每个 `phase` → 该 link 匹配到的全部 nodeKey,**并集累加**
|
||||||
|
(`Map<phaseNo, Set<nodeKey>>`),满足 R4 的另一半(同相位多进口道)。
|
||||||
|
6. 默认容差:`maxDistanceMeters = 30`、`maxHeadingDeltaDegrees = 45`。
|
||||||
|
7. 未匹配上的相位进入 `unbound`,面板显示「N 已绑定 / M 未绑定」。
|
||||||
|
|
||||||
|
**实现期修正**:设计初稿认为朝向语义不可判定,打算用「三字段 ± 180 的候选集,任一命中即可」。
|
||||||
|
实测该方案在凤树二路路口产生**严重误匹配** —— 一条 link 同时命中 3 条不同 `approachId` 的进口道
|
||||||
|
(距离 1.57 / 13.01 / 17.56 m,角差 3.8 / 7.8 / 5.4°),因为 ±180 × 三字段几乎放行任意 90° 朝向。
|
||||||
|
改为上述单一确定式后,7 条 link 对 7 个信号达成 **7/7 精确一对一**,误匹配为 0。
|
||||||
|
候选集方案已废弃。
|
||||||
|
|
||||||
|
|
||||||
|
**配置覆盖**:`v2xPreview.phaseSignalMap = { "<phaseNo>": ["<nodeKey>", …] }` 存在时,
|
||||||
|
该 phaseNo 直接用配置值,跳过几何匹配。这是几何匹配失败时的逃生舱,也让映射可人工固化。
|
||||||
|
|
||||||
|
> 取舍:不用 `approachId` / `sourceWayId` 匹配,因为那是 OSM 侧标识,V2X link 不携带;
|
||||||
|
> 不用最近邻唯一指派(匈牙利算法),因为一进口道多灯头是正常情况,强制一对一会漏灯。
|
||||||
|
> 容差可配是因为不同路口的停止线标注精度差异较大。
|
||||||
|
|
||||||
|
### 4.3 WebSocket 连接层(R1、R6)
|
||||||
|
|
||||||
|
新增 `createSocket({url, onOpen, onMessage, onClose, heartbeatMs, reconnect})` 副作用封装:
|
||||||
|
|
||||||
|
- 心跳:`setInterval(() => send('{"heartBeat":"ping"}'), 30000)`,与源项目一致。
|
||||||
|
- 重连:指数退避 `1s, 2s, 4s, 8s`,上限 `8s`,**重连成功后重新执行 `onOpen`**,
|
||||||
|
确保订阅帧(`junctionId` / `deviceId` / `bounds`)被重放。这是源项目 `onConnected` 的语义。
|
||||||
|
- `close()` 主动关闭时不触发重连;`dispose()` 清心跳与退避计时器。
|
||||||
|
- 计时器通过参数注入(`setIntervalFn` / `setTimeoutFn`),使重连与心跳逻辑可在测试中用假时钟驱动。
|
||||||
|
|
||||||
|
订阅帧内容严格对齐源项目:
|
||||||
|
|
||||||
|
| socket | 连接后首帧 | 来源 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| signal | `{"junctionId":"<crossCode>"}` | `CrossTrafficLights3D.vue:129` |
|
||||||
|
| obu | `bounds \|\| ""`(dashboard 传 `null` → 空串) | `useObuCars.ts:31` |
|
||||||
|
| target | `{"deviceId":"<ids>"}` 或 `{"deviceId":null}` | `useTargetCars.ts:50-53` |
|
||||||
|
|
||||||
|
OBU 的 bounds:源项目取 AMap 视野四角。本项目用 Cesium `camera.computeViewRectangle()`
|
||||||
|
换算成同格式 `lng,lat;lng,lat;lng,lat;lng,lat`(**WGS84 → GCJ-02 反向转换**,因为服务端按 GCJ-02
|
||||||
|
过滤),在 `camera.moveEnd` 时节流发送 `{"bounds": "<…>"}`。视野不可用时退回空串,等价于不过滤。
|
||||||
|
|
||||||
|
> 取舍:Cesium 是倾斜视角,`computeViewRectangle()` 在极端俯仰下可能返回 `undefined`;
|
||||||
|
> 此时退回空串而非跳过发送,保证仍能收到全量推送——宁可多收也不要空场景。
|
||||||
|
|
||||||
|
### 4.4 车辆注册表(R7、R8)
|
||||||
|
|
||||||
|
纯状态机 `createVehicleRegistry({now})`:
|
||||||
|
|
||||||
|
```
|
||||||
|
registry.ingest(vehicles, interval) -> {added, updated, hidden}
|
||||||
|
registry.sweep(nowMs) -> hiddenKeys
|
||||||
|
registry.list() -> VehicleRecord[]
|
||||||
|
```
|
||||||
|
|
||||||
|
- 复刻源项目:`interval = Number(payload.interval) === 0 ? 500 : Number(payload.interval)`。
|
||||||
|
- `sweep()`:`Math.abs(now - timeStamp) >= interval * 1.5` 时 `visible = false`。
|
||||||
|
- 槽位复用:新车优先占用同模型的 `visible === false` 记录(源项目 `useTargetCars.ts:110`),
|
||||||
|
减少 Cesium 实体的增删抖动。
|
||||||
|
- `now` 注入,测试用假时钟推进。
|
||||||
|
- socket `onClose` 时 `registry.clear()`,对齐源项目 `onDisconnected: cars.value = []`。
|
||||||
|
|
||||||
|
渲染适配层据 `visible` 切 `entity.show`,**不删实体**,与槽位复用配套。
|
||||||
|
|
||||||
|
模型选择(R8):OBU 的数据 hook 虽标记 `car_obu.glb`,但最终的 `CrossCars/index.vue` 模板固定
|
||||||
|
传入 `11.glb`,因此 `modelNameFor(vehicle)` 对 OBU 返回 `11.glb`;目标车辆返回
|
||||||
|
`${type}${subType}.glb`。预览阶段把 dashboard 的 `11/12/13/14/15/16/17/31/221/222.glb`
|
||||||
|
复制到 `_preview/v2x-vehicles/`,并在 `vehicleModelNames` 中按文件名匹配;未知车型回退 `11.glb`
|
||||||
|
并累加 `missingModels` 计数供面板展示。
|
||||||
|
|
||||||
|
平滑:用 `Cesium.SampledPositionProperty` 按 `duration` 插值,替代当前的直接赋值跳变。
|
||||||
|
|
||||||
|
### 4.5 宽松解析(R9)
|
||||||
|
|
||||||
|
源项目用 `saferEval`。浏览器端零依赖不能引入该库,也不应引入 `eval`。改为
|
||||||
|
`parseLoosePayload(text)`:先 `JSON.parse`;失败则做一次受限规范化(单引号→双引号、
|
||||||
|
裸键补引号、去尾逗号、`NaN`/`Infinity` → `null`)后重试;仍失败返回 `null` 并
|
||||||
|
`state.parseFailures += 1`,面板显示失败计数(R9 要求可见)。
|
||||||
|
|
||||||
|
> 取舍:不用 `new Function` 还原 `saferEval` 的完整语义——那等于在预览页开一个任意代码执行面。
|
||||||
|
> 受限规范化覆盖实际会遇到的非严格 JSON 形态,且失败可观测,比静默丢弃安全得多。
|
||||||
|
|
||||||
|
### 4.6 移除范围外请求(R10)
|
||||||
|
|
||||||
|
`loadLiveData()` 的 `Promise.allSettled` 去掉 `FlowTravelRatio/queryListWeek`,
|
||||||
|
`state.metrics` 及面板中的 `flow metrics` 文案一并移除。
|
||||||
|
|
||||||
|
## 5. 数据流
|
||||||
|
|
||||||
|
```
|
||||||
|
登录 → resolveCrossCode()
|
||||||
|
→ queryCrossLinkInfo / queryPoles / findDeviceByCrossCode / crossDeviceConfig
|
||||||
|
→ buildPhaseSignalMap(links, nativeSignals) [纯]
|
||||||
|
→ connectLiveSockets()
|
||||||
|
signal → normalizeSignalLamps → lampColorName → setSignalState({nodeKeys,color,countDown})
|
||||||
|
→ cesium-preview 点亮原生灯头 + 倒计时
|
||||||
|
obu → parseLoosePayload → normalizeObuVehicle ┐
|
||||||
|
target → parseLoosePayload → normalizeTargetVehicles ┴→ registry.ingest → 渲染适配
|
||||||
|
registry.sweep → entity.show
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. 兼容性与回滚
|
||||||
|
|
||||||
|
- `v2xPreview.enabled=false` 时 `createV2xCesiumOverlay()` 仍返回 `null`,生成页不含面板,
|
||||||
|
包产物字节不变(AC10)。
|
||||||
|
- 原生信号灯在**无 V2X 灯态时**的行为保持现状(`hideUnconfirmedSignalAssets` 语义不变),
|
||||||
|
只有收到实时灯态才点亮,不会退回模拟相位。
|
||||||
|
- 回滚点:本任务对 `cesium-preview.js` 的改动限于删除重复的 `lampColorName` 与调整
|
||||||
|
`setSignalState` 入参形状,可单独 revert 而不影响 overlay。
|
||||||
|
- 新增 `phaseSignalMap`、`maxDistanceMeters`、`maxHeadingDeltaDegrees` 均为可选配置,
|
||||||
|
缺省即当前默认行为。
|
||||||
|
|
||||||
|
## 7. 风险
|
||||||
|
|
||||||
|
| 风险 | 影响 | 缓解 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 几何匹配在实际路口全部落空 | 灯仍不亮 | 面板显性报「0 已绑定」;`phaseSignalMap` 配置覆盖兜底 |
|
||||||
|
| `computeViewRectangle()` 返回 undefined | OBU 过滤异常 | 退回空串=不过滤 |
|
||||||
|
| 宽松解析未覆盖真实非法形态 | 丢消息 | `parseFailures` 计数可见,便于按真实样本补规则 |
|
||||||
|
| 服务端心跳格式与源项目不符 | 仍被断开 | 心跳报文与间隔取自源项目源码,AC1 用模拟服务端验证 |
|
||||||
|
| 真实推送 `interval` 缺失 | 车辆过早隐藏 | 缺失时回退 500ms,与源项目一致 |
|
||||||
@@ -0,0 +1,4 @@
|
|||||||
|
{"file": ".trellis/spec/preview/index.md", "reason": "预览层契约:无构建步骤、零依赖 IIFE、参数经 window.OSM_ASSET_PREVIEW_CONFIG 注入。overlay 与 cesium-preview.js 的所有改动都受这些约束。"}
|
||||||
|
{"file": ".trellis/spec/pipeline/index.md", "reason": "确认 build-area.js 如何把 v2x-cesium-overlay.js 拷入产物,避免误增文件破坏包契约。"}
|
||||||
|
{"file": ".trellis/spec/config/index.md", "reason": "新增可选配置 v2xPreview.phaseSignalMap / maxDistanceMeters / maxHeadingDeltaDegrees 需符合区域配置约定。"}
|
||||||
|
{"file": "docs/v2x-cesium-preview.md", "reason": "现有 V2X 预览文档:配置项、坐标契约、代理要求、回滚方式。移除 FlowTravelRatio 与新增配置后需同步更新。"}
|
||||||
@@ -0,0 +1,171 @@
|
|||||||
|
# Implement — 还原 V2X 实时路口信号灯与车辆展示
|
||||||
|
|
||||||
|
## 参照实现(只读)
|
||||||
|
|
||||||
|
`/Users/que01/Project/v2x_web/applications/dashboard/src/views/dashboard/components/Content/Map/HologramCross/`
|
||||||
|
|
||||||
|
改动前先读对应源文件,不要凭记忆写契约。
|
||||||
|
|
||||||
|
## 改动文件
|
||||||
|
|
||||||
|
| 文件 | 性质 |
|
||||||
|
| --- | --- |
|
||||||
|
| `scripts/lib/v2x-cesium-overlay.js` | 主要改动,L1–L4 分层重写 |
|
||||||
|
| `scripts/lib/cesium-preview.js` | 删除重复 `lampColorName`,调整 `setSignalState` 入参 |
|
||||||
|
| `scripts/test-v2x-cesium-overlay.js` | 扩充单测,覆盖 AC2–AC7 |
|
||||||
|
| `.trellis/tasks/.../prd.md` `design.md` | 如实现中发现偏差需回写 |
|
||||||
|
|
||||||
|
不改:`build-area.js`、`area-preview.js`、包产物生成逻辑。
|
||||||
|
|
||||||
|
## 执行顺序
|
||||||
|
|
||||||
|
每步结束跑一次 `npm run test:v2x-cesium-preview`,保持绿色再进下一步。
|
||||||
|
|
||||||
|
### 步骤 1 — L2 灯色字典 + 宽松解析(R2、R9)
|
||||||
|
|
||||||
|
1. 在 overlay 加 `LAMP_STATUS`(`11/21/22/23/31`)与 `lampColorName(status)`,未知返回 `"other"`。
|
||||||
|
2. 删除旧 `lampColor()` 中 `Number(status)===3 / ===2` 的判断。
|
||||||
|
3. 加 `parseLoosePayload(text)`:`JSON.parse` → 受限规范化重试 → `null`。
|
||||||
|
4. 心跳报文 `pong` 短路判定保留(与源项目一致)。
|
||||||
|
5. 二者导出到 `.utils`。
|
||||||
|
|
||||||
|
验证:`node scripts/test-v2x-cesium-overlay.js`
|
||||||
|
- `lampColorName(21)==="red"`, `(22)==="yellow"`, `(23)==="green"`, `(11)==="off"`, `(31)==="other"`
|
||||||
|
- **`lampColorName(2)!=="yellow"` 且 `lampColorName(3)!=="green"`**(防回归,AC2)
|
||||||
|
- `parseLoosePayload("{'a':1,}")` 解析成功;`parseLoosePayload("{bad")===null`(AC7)
|
||||||
|
|
||||||
|
**审查点 A**:灯色字典必须与 `HologramCross/components/utils.ts` 的
|
||||||
|
`lightStatusColorDict` 逐项一致,不得增删码值。
|
||||||
|
|
||||||
|
### 步骤 2 — L1 几何工具(支撑 R3)
|
||||||
|
|
||||||
|
1. 加 `getAngle(start, end)`:直接对齐源项目 `utils.ts` 的实现(返回 0–360)。
|
||||||
|
2. 加 `haversineMeters(a, b)`、`angleDeltaDegrees(a, b)`(后者处理 350° vs 10° 的环绕)。
|
||||||
|
3. 导出到 `.utils`。
|
||||||
|
|
||||||
|
验证:正北 `getAngle([0,0],[0,1])≈0`;正东 `≈90`;
|
||||||
|
`angleDeltaDegrees(350,10)===20`;`haversineMeters` 对已知两点误差 < 0.5m。
|
||||||
|
|
||||||
|
### 步骤 3 — 相位映射(R3、R4)
|
||||||
|
|
||||||
|
1. 实现 `buildPhaseSignalMap(links, nativeSignals, options)`,返回
|
||||||
|
`{byPhase, bound, unbound, diagnostics}`,算法见 `design.md` §4.2。
|
||||||
|
2. link 末两点**先 GCJ-02→WGS84 再算角度与距离**(原生信号是 WGS84)。
|
||||||
|
3. 一 link 匹配多 signal;`Map<phaseNo, Set<nodeKey>>` 并集累加。
|
||||||
|
4. 支持 `options.phaseSignalMap` 配置覆盖,命中则跳过几何匹配。
|
||||||
|
5. 默认 `maxDistanceMeters=30`、`maxHeadingDeltaDegrees=45`。
|
||||||
|
6. 导出到 `.utils`。
|
||||||
|
|
||||||
|
验证(AC3、AC4):
|
||||||
|
- 用 `outputs/fengshu-er-road/package/runtime/traffic-signals.json` 的真实 7 条信号做夹具,
|
||||||
|
配一组构造的 link(末点取自 `stopLongitude/stopLatitude` 反算 GCJ-02、
|
||||||
|
航向取自 `headingDegrees`),断言 `bound > 0`。
|
||||||
|
- 构造两条不同 link 共用同一 `phaseNo`,断言 `byPhase.get(phaseNo)` 含**两条 link 的全部 nodeKey**。
|
||||||
|
- 构造一条远离所有信号的 link,断言其相位进入 `unbound` 且带 `reason`。
|
||||||
|
- 配置覆盖生效:`phaseSignalMap` 指定的 phaseNo 取配置值。
|
||||||
|
|
||||||
|
**审查点 B**:这是全任务最易做错的一步。合入前必须用真实 `traffic-signals.json` 跑出
|
||||||
|
非零绑定数,若为 0 则说明容差或坐标方向反了,**不得靠放大容差蒙混过关**——先打印
|
||||||
|
`diagnostics` 的实际距离/角差,确认量级合理(距离应是米级而非千米级)。
|
||||||
|
|
||||||
|
### 步骤 4 — 车辆注册表(R7、R8)
|
||||||
|
|
||||||
|
1. 实现 `createVehicleRegistry({now})`,含 `ingest / sweep / list / clear`。
|
||||||
|
2. `interval` 取自推送体,`0` 或缺失回退 `500`。
|
||||||
|
3. `sweep`:`|now - timeStamp| >= interval*1.5` → `visible=false`。
|
||||||
|
4. 槽位复用:优先占用同 `model` 的不可见记录。
|
||||||
|
5. `modelNameFor(vehicle)`:OBU → dashboard 最终模板使用的 `11.glb`;target → `${type}${subType}.glb`。把 dashboard 车辆 GLB 复制到预览包。
|
||||||
|
6. `normalizeTargetVehicles` 补上源项目的 `type==1 && isNil(subType) → subType=1`。
|
||||||
|
7. 导出 `createVehicleRegistry`、`modelNameFor`。
|
||||||
|
|
||||||
|
验证(AC5):
|
||||||
|
- 注入一次推送 → `list()` 一条 `visible=true`。
|
||||||
|
- 假时钟推进 `interval*1.5` 后 `sweep()` → 该车 `visible=false`。
|
||||||
|
- 再注入同 key → 复用原槽位,`list().length` 不变。
|
||||||
|
- `clear()` 后为空。
|
||||||
|
- `modelNameFor({kind:"obu"})==="11.glb"`;`{kind:"target",type:1,subType:2}` → `"12.glb"`。
|
||||||
|
|
||||||
|
### 步骤 5 — WebSocket 连接层(R1、R6)
|
||||||
|
|
||||||
|
1. 实现 `createSocket({url, onOpen, onMessage, onClose, heartbeatMs, reconnect, socketFactory, setIntervalFn, setTimeoutFn})`。
|
||||||
|
2. 心跳 `{"heartBeat":"ping"}` / 30000ms。
|
||||||
|
3. 退避重连 `1s→2s→4s→8s` 封顶,**重连成功重放 `onOpen`**。
|
||||||
|
4. 主动 `close()` 不重连;`dispose()` 清所有计时器。
|
||||||
|
5. 三个 socket 的订阅帧按 `design.md` §4.3 的表格实现。
|
||||||
|
6. OBU bounds:`camera.computeViewRectangle()` → WGS84→GCJ-02 → `"lng,lat;…"` 四角,
|
||||||
|
`camera.moveEnd` 节流发送;不可用时发空串。
|
||||||
|
7. 导出 `createSocket`、`buildBoundsMessage`。
|
||||||
|
|
||||||
|
验证(AC1、AC6):
|
||||||
|
- 假 socket + 假时钟:推进 30s 断言收到一帧 `{"heartBeat":"ping"}`;推进 90s 断言三帧。
|
||||||
|
- 模拟 `onclose` 后推进退避时间,断言重新建连**且订阅帧被重放**。
|
||||||
|
- signal 首帧 `{"junctionId":"<code>"}`;target 无配置首帧 `{"deviceId":null}`,
|
||||||
|
有配置 `{"deviceId":"1,2"}`;obu 首帧为空串。
|
||||||
|
- `dispose()` 后推进时钟不再产生任何发送。
|
||||||
|
|
||||||
|
**审查点 C**:心跳报文与间隔必须逐字节对齐源项目
|
||||||
|
(`useObuCars.ts:28-31`、`useTargetCars.ts:27-30`、`CrossTrafficLights3D.vue:122-130`)。
|
||||||
|
|
||||||
|
### 步骤 6 — 接线与渲染适配(R4、R5、R10)
|
||||||
|
|
||||||
|
1. `loadLiveData()` 移除 `FlowTravelRatio/queryListWeek`,删 `state.metrics` 与面板 flow 文案。
|
||||||
|
2. 用 `buildPhaseSignalMap` 结果替换 `state.linkPhases`(`Map<phase, entity>` 整体删除)。
|
||||||
|
3. `updateSignalPhases` → 归一化为 `{nodeKeys, color, countDown}` 列表后调
|
||||||
|
`context.setSignalState(...)`,同时给 link polyline 上色(同相位多 link 全部上色)。
|
||||||
|
4. 车辆渲染改为消费 `registry`:`visible` 切 `entity.show`,位置用
|
||||||
|
`SampledPositionProperty` 按 `duration` 插值。
|
||||||
|
5. 面板状态行补:已绑定/未绑定相位数、缺失模型数、解析失败数。
|
||||||
|
6. `dispose()` 清 socket、计时器、实体、registry。
|
||||||
|
|
||||||
|
### 步骤 7 — `cesium-preview.js` 对接(R2、R5)
|
||||||
|
|
||||||
|
1. 删除 `cesium-preview.js` 中的 `lampColorName()`(与 overlay 重复且映射错误)。
|
||||||
|
2. `createLiveTrafficSignals().update(lamps)` 改签名为
|
||||||
|
`update(entries)`,`entries = [{nodeKeys:string[], color:"red"|"yellow"|"green"|"off"|"other", countDown:number}]`。
|
||||||
|
3. 按 `nodeKeys` 直接点亮 `TrafficSignalDynamic_<nodeKey>_<color>` 节点,
|
||||||
|
删除失效的 `signalByPhase` 回退逻辑。
|
||||||
|
4. `countDown` 驱动 `category === "countdown"` 资产显示。
|
||||||
|
5. `color === "off" | "other"` 时三色节点全灭。
|
||||||
|
|
||||||
|
验证:`npm run test:preview-assets`
|
||||||
|
|
||||||
|
### 步骤 8 — 全量校验
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:v2x-cesium-preview
|
||||||
|
npm run test:v2x-preview-server
|
||||||
|
npm run test:preview-assets
|
||||||
|
npm run test:traffic-signals
|
||||||
|
npm run test:native-preview-traffic
|
||||||
|
npm run test:package-contract
|
||||||
|
```
|
||||||
|
|
||||||
|
AC10 校验:将区域配置 `v2xPreview.enabled` 置 `false` 重新生成,
|
||||||
|
确认生成页无 V2X 面板且 `package/` 下产物字节不变。
|
||||||
|
|
||||||
|
## 人工验收(AC9,需真实上游)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
V2X_UPSTREAM=http://<host>:<port> \
|
||||||
|
npm run serve:v2x-preview -- --root outputs/fengshu-er-road --host 0.0.0.0 --port 7862
|
||||||
|
```
|
||||||
|
|
||||||
|
登录后逐项确认:
|
||||||
|
- [ ] 信号灯随相位变色,颜色与 dashboard 实时路口一致
|
||||||
|
- [ ] 倒计时数字走动
|
||||||
|
- [ ] 车辆出现、移动平滑、离开视野后消失(无幽灵车堆积)
|
||||||
|
- [ ] 连接持续 5 分钟以上不掉线
|
||||||
|
- [ ] 车辆与路口位置无明显偏移(坐标未二次转换)
|
||||||
|
- [ ] 面板绑定数、失败数符合预期
|
||||||
|
|
||||||
|
## 回滚点
|
||||||
|
|
||||||
|
- 步骤 7 独立可 revert(只动 `cesium-preview.js`)。
|
||||||
|
- 步骤 1–6 全在 overlay 单文件内,`git checkout scripts/lib/v2x-cesium-overlay.js` 即回到当前状态。
|
||||||
|
- `v2xPreview.enabled=false` 是运行时总开关。
|
||||||
|
|
||||||
|
## 不做(留待后续任务)
|
||||||
|
|
||||||
|
- AMap 底图 / 矢量瓦片图层
|
||||||
|
- `CrossDevices/Model3D.vue` 3D 杆件模型(设备维持点位)
|
||||||
|
- `useV2XEvents` 事件气泡
|
||||||
@@ -0,0 +1,99 @@
|
|||||||
|
# 还原 V2X 实时路口信号灯与车辆展示
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
把 `v2x_web` dashboard「实时路口」(`HologramCross`) 的实时数据行为完整搬到本项目的 Cesium 预览中,使
|
||||||
|
`outputs/<area>/…-cesium-preview.html` 在登录后能持续、正确地显示 **信号灯相位灯色与倒计时** 和
|
||||||
|
**OBU / 目标识别车辆**。
|
||||||
|
|
||||||
|
当前实现(Codex 移植)接口地址是对的,但数据处理与渲染层基本失真,实际效果是:灯永远红、车可能一辆都不出现、
|
||||||
|
出现后也不消失、连接几十秒后被服务端断开。本任务修复这条链路。
|
||||||
|
|
||||||
|
## Source of Truth
|
||||||
|
|
||||||
|
参照实现(只读,不修改):
|
||||||
|
`/Users/que01/Project/v2x_web/applications/dashboard/src/views/dashboard/components/Content/Map/HologramCross/`
|
||||||
|
|
||||||
|
- `components/CrossTrafficLights3D.vue` — 信号灯:link 相位、WS 订阅、灯色/倒计时
|
||||||
|
- `components/utils.ts` — 灯色状态字典、航向角计算
|
||||||
|
- `components/CrossCars/hooks/useObuCars.ts` — OBU 车辆
|
||||||
|
- `components/CrossCars/hooks/useTargetCars.ts` — 目标识别车辆
|
||||||
|
- `components/CrossCars/type.ts` — 车辆数据结构
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
### R1 WebSocket 连接层对齐
|
||||||
|
- 三个 socket(`signal` / `obuPosition` / `targetPosition`)均按源项目发送心跳
|
||||||
|
`{"heartBeat":"ping"}`,间隔 30000ms。
|
||||||
|
- 断线自动重连,重连后重新发送各自的订阅消息(signal 发 `junctionId`,target 发 `deviceId`,obu 发 bounds)。
|
||||||
|
- 页面 `visibilitychange` 回到可见时行为不得导致重复连接堆积;`dispose()` 必须清掉心跳与重连计时器。
|
||||||
|
|
||||||
|
### R2 信号灯灯色映射修正
|
||||||
|
- 采用源项目 `utils.ts` 的状态字典:`11=灭灯 21=红 22=黄 23=绿 31=其他`。
|
||||||
|
- 现有 `lampColor()`(overlay)与 `lampColorName()`(`cesium-preview.js`)中基于 `2`/`3` 的判断必须移除。
|
||||||
|
- 未知状态码按「其他/灭灯」处理,不得静默落到红色。
|
||||||
|
|
||||||
|
### R3 相位到原生信号灯的映射
|
||||||
|
- `traffic-signals.json` 中不存在 V2X `phaseNo`(只有 `phaseGroup: 0`),当前回退到 `signal.id` 导致永不匹配。
|
||||||
|
必须建立一条真实可用的 V2X `phaseNo` → 原生信号灯头的映射。
|
||||||
|
- 映射结果必须可诊断:面板要能显示「N 个相位已绑定 / M 个未绑定」。
|
||||||
|
- 允许区域配置提供显式覆盖映射。
|
||||||
|
|
||||||
|
### R4 一个相位可点亮多条进口道
|
||||||
|
- 同一 `phaseNo` 对应的所有 link / 信号灯头都要被点亮,当前 `Map<phase, entity>` 的覆盖行为必须消除。
|
||||||
|
|
||||||
|
### R5 倒计时
|
||||||
|
- 使用推送中的 `countDown` 字段(源项目 `phaseValue['time'] = signal.countDown`),驱动预览中已有的
|
||||||
|
countdown 资产或等效显示。
|
||||||
|
|
||||||
|
### R6 车辆订阅正确建立
|
||||||
|
- OBU socket 连接后必须发送订阅消息(源项目 `send(bounds || '')`),相机视野变化时发送
|
||||||
|
`{"bounds": "<lng,lat;…>"}`。
|
||||||
|
- target socket 连接后发送 `{"deviceId": "<ids joined by comma>"}`,无配置时发送 `{"deviceId": null}`。
|
||||||
|
|
||||||
|
### R7 车辆生命周期
|
||||||
|
- 按源项目实现超时隐藏:超过 `interval * 1.5` 未更新的车辆隐藏并可复用槽位;`interval` 取自推送体,
|
||||||
|
`0` 时回退 `500`。
|
||||||
|
- socket 断开时清空车辆列表。
|
||||||
|
- 车辆位置更新使用推送间隔做平滑插值,避免逐帧跳变。
|
||||||
|
|
||||||
|
### R8 车辆模型命名与资产对齐
|
||||||
|
- OBU 数据层标记为 `car_obu.glb`,但 dashboard 的实际 `CrossCars` 模板固定渲染 `11.glb`;预览必须遵从该最终渲染契约。目标识别车辆使用 `${type}${subType}.glb`。
|
||||||
|
- 预览包必须携带 dashboard 实际使用的车辆模型;包内缺少未知车型时回退到 `11.glb`,并在面板提示,不得静默显示错误车型。
|
||||||
|
|
||||||
|
### R9 推送体解析健壮性
|
||||||
|
- 源项目对两个车辆 socket 使用 `saferEval` 而非 `JSON.parse`,说明载荷不保证严格 JSON。
|
||||||
|
- 解析必须容忍非严格 JSON,且解析失败要计数并在面板可见,不得整条静默丢弃。
|
||||||
|
|
||||||
|
### R10 范围纠正
|
||||||
|
- `/facilities/api/FlowTravelRatio/queryListWeek`(周流量比)不属于「实时路口」,从实时加载链路移除。
|
||||||
|
|
||||||
|
## Non-Goals
|
||||||
|
|
||||||
|
- 不移植 AMap 底图 / 矢量瓦片图层(`linkVectorHdMapTileUrl`)。
|
||||||
|
- 不移植 `CrossDevices/Model3D.vue` 的 3D 杆件模型;设备维持点位显示(可后续独立任务)。
|
||||||
|
- 不移植 `useV2XEvents` 的 V2X 事件气泡。
|
||||||
|
- 不改变原生包产物(GLB / metadata / traffic-signals.json 的生成逻辑)。
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
|
||||||
|
- 不得提交上游地址、账号、令牌、AMap key;`v2xPreview` 配置保持非敏感。
|
||||||
|
- 令牌只存 `sessionStorage`,页面始终从登录门进入。
|
||||||
|
- 坐标契约不变:V2X 数据 GCJ-02,进 Cesium 前转一次 WGS84;原生数据不得二次转换。
|
||||||
|
- `v2xPreview.enabled` 默认 `false`,关闭时生成页不含 V2X 面板。
|
||||||
|
- 生成的预览为静态页,无构建步骤,overlay 保持零依赖 IIFE。
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] AC1 三个 socket 均可见 30s 心跳;模拟服务端在 60s+ 后连接仍存活。
|
||||||
|
- [ ] AC2 单测覆盖灯色映射:`21→红 22→黄 23→绿 11→灭 31→其他`,且 `2`/`3` 不再被当作黄/绿。
|
||||||
|
- [ ] AC3 单测覆盖相位映射:给定 V2X link 相位与 `traffic-signals.json`,输出的绑定数 > 0,
|
||||||
|
未绑定项被明确列出。
|
||||||
|
- [ ] AC4 单测覆盖同相位多进口道:一个 `phaseNo` 对应 2 条 link 时,两条都被点亮。
|
||||||
|
- [ ] AC5 单测覆盖车辆超时:注入两次推送并推进时间超过 `interval*1.5`,车辆转为不可见。
|
||||||
|
- [ ] AC6 单测覆盖 OBU/target 订阅消息:连接后发出的首帧内容与源项目一致。
|
||||||
|
- [ ] AC7 单测覆盖非严格 JSON 推送体能被解析,且失败计数可读。
|
||||||
|
- [ ] AC8 `npm run test:v2x-cesium-preview`、`test:v2x-preview-server`、`test:preview-assets` 全绿。
|
||||||
|
- [ ] AC9 真机(`npm run serve:v2x-preview` 接真实上游)登录后可见:信号灯随相位变色并显示倒计时、
|
||||||
|
车辆出现并移动、离开后消失。此项由开发者人工确认。
|
||||||
|
- [ ] AC10 `v2xPreview.enabled=false` 重新生成后,页面不含 V2X 面板,包产物字节不变。
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "v2x-realtime-cross-fidelity",
|
||||||
|
"name": "v2x-realtime-cross-fidelity",
|
||||||
|
"title": "还原 V2X 实时路口信号灯与车辆展示",
|
||||||
|
"description": "",
|
||||||
|
"status": "in_progress",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-24",
|
||||||
|
"completedAt": null,
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "main",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,3 @@
|
|||||||
|
{"file":".trellis/spec/pipeline/index.md","reason":"Check command ownership, disk artifact boundaries, and legacy pipeline compatibility."}
|
||||||
|
{"file":".trellis/spec/preview/index.md","reason":"Check browser workbench state, error handling, and no-build browser constraints."}
|
||||||
|
{"file":".trellis/spec/config/index.md","reason":"Check new area output/config normalization and compatibility."}
|
||||||
@@ -0,0 +1,110 @@
|
|||||||
|
# Native Road Compiler Workbench Design
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
The native compiler is an additive pipeline path. It owns a separate output
|
||||||
|
directory under an area and never writes into `osm2streets_web_out/`.
|
||||||
|
|
||||||
|
```text
|
||||||
|
OSM XML + native-road-overrides.json
|
||||||
|
|
|
||||||
|
v
|
||||||
|
Canonical Road Model
|
||||||
|
roads / endpoints / junction candidates / provenance
|
||||||
|
|
|
||||||
|
v
|
||||||
|
Native Geometry Compiler
|
||||||
|
road surfaces / initial junction surfaces / diagnostics
|
||||||
|
|
|
||||||
|
+--> native-road/compiled.json
|
||||||
|
+--> native-road/layers/*.geojson
|
||||||
|
+--> native-road/diagnostics.json
|
||||||
|
+--> native-road/comparison.json
|
||||||
|
|
|
||||||
|
v
|
||||||
|
Road Workbench HTTP service
|
||||||
|
browser map + inspect/edit/save API
|
||||||
|
```
|
||||||
|
|
||||||
|
The canonical model is the authority. Render layers, browser display data, and
|
||||||
|
future Blender compatibility adapters are derived from it.
|
||||||
|
|
||||||
|
## Commands And Ownership
|
||||||
|
|
||||||
|
- `npm run road:compile -- --config <area-config>` performs no browser work.
|
||||||
|
It reads OSM plus the persisted override file, writes a staged native-road
|
||||||
|
result, validates it, and atomically promotes the result directory.
|
||||||
|
- `npm run road:workbench -- --config <area-config>` compiles first unless
|
||||||
|
`--no-compile` is supplied, then starts a local HTTP server scoped to that
|
||||||
|
one area.
|
||||||
|
- The server exposes read-only compiler artifacts and one explicit save API
|
||||||
|
for validated overrides. It does not expose arbitrary filesystem paths.
|
||||||
|
- Existing `build:area`, `intermediates`, QGIS, Blender, Cesium, and package
|
||||||
|
paths remain unchanged in the first iteration.
|
||||||
|
|
||||||
|
## Data Contracts
|
||||||
|
|
||||||
|
### Canonical road model
|
||||||
|
|
||||||
|
Each road direction carries a stable ID derived from OSM identifiers, source
|
||||||
|
way IDs, endpoint node IDs, centerline, explicit/inferred attributes, applied
|
||||||
|
override IDs, and diagnostics. Junction candidates likewise use their OSM node
|
||||||
|
ID when available. Values include provenance such as `tag:lanes:forward`,
|
||||||
|
`inferred:highway-default`, or `override:<id>`.
|
||||||
|
|
||||||
|
Each `Movement` is a stable semantic record joining a connection, source and
|
||||||
|
target road/lane, turn class, provenance, and an optional connector geometry.
|
||||||
|
`geometryStatus="connector"` publishes a connector curve;
|
||||||
|
`geometryStatus="continuous"` means the lane centerlines meet at the node and
|
||||||
|
does not invent a zero-length curve; `deferred-too-long` retains the movement
|
||||||
|
while withholding unsafe geometry.
|
||||||
|
|
||||||
|
### Override file
|
||||||
|
|
||||||
|
`<area>/native-road-overrides.json` is versioned and human-reviewable. It
|
||||||
|
contains an array of uniquely identified changes whose targets are stable road
|
||||||
|
or endpoint IDs. Supported v1 records are `road` parameter overrides and
|
||||||
|
`junction-connection` decisions. The save endpoint validates schema, target
|
||||||
|
existence, finite values, and duplicate/conflicting edits before atomic write.
|
||||||
|
|
||||||
|
### Compiler artifacts
|
||||||
|
|
||||||
|
`<area>/native-road/compiled.json` is the workbench's single read model and
|
||||||
|
contains the canonical `movements` list.
|
||||||
|
`layers/` contains generated GeoJSON with source/provenance properties.
|
||||||
|
`diagnostics.json` contains severity, stable subject ID, source IDs, rule,
|
||||||
|
message, and optional geometry. `comparison.json` reports counts and coverage
|
||||||
|
against available osm2streets layers; it does not claim quality solely from
|
||||||
|
visual differences.
|
||||||
|
|
||||||
|
## Browser Workbench
|
||||||
|
|
||||||
|
The browser uses OpenLayers as its sole GIS runtime, served directly from the
|
||||||
|
local allowlisted `node_modules` packages with a browser import map. The map
|
||||||
|
renders fit-to-data OSM centerlines, native surfaces, optional osm2streets
|
||||||
|
reference layers, diagnostics, selected-object provenance, movements, and
|
||||||
|
overrides. This provides mature map selection and hit detection without a
|
||||||
|
framework or bundler.
|
||||||
|
|
||||||
|
The user can select a road or endpoint, edit only v1 fields, inspect the
|
||||||
|
resulting override record, explicitly save it, and recompile/reload. Saved
|
||||||
|
state is visibly differentiated from unsaved state. The workbench must not
|
||||||
|
offer freehand final-polygon editing, since that would break reproducibility.
|
||||||
|
|
||||||
|
## Geometry And Validation
|
||||||
|
|
||||||
|
V1 produces road segments from projected centerline offsets and terminal
|
||||||
|
cross-sections. It only generates a junction surface when endpoints satisfy
|
||||||
|
the supported ordinary T/cross shape and geometry checks; otherwise it emits a
|
||||||
|
diagnostic rather than inventing an invalid polygon. Validation detects
|
||||||
|
dangling endpoints, unclosed/self-intersecting rings, non-finite coordinates,
|
||||||
|
unsupported multi-level intersections, and source/topology ambiguity. Small
|
||||||
|
numerical cleanup may be explicit and recorded; semantic failures are never
|
||||||
|
silently repaired.
|
||||||
|
|
||||||
|
## Compatibility And Rollout
|
||||||
|
|
||||||
|
The first compiler's layers use existing render-layer names where meaningful,
|
||||||
|
but are stored separately. A later, explicitly enabled Blender provider option
|
||||||
|
may consume native layers after comparison gates pass. Delete/replace behavior
|
||||||
|
is out of scope; rollback is selecting the existing osm2streets pipeline.
|
||||||
@@ -0,0 +1,3 @@
|
|||||||
|
{"file":".trellis/spec/pipeline/index.md","reason":"Native compiler commands, artifacts, and area config extend the Node pipeline while preserving legacy stages."}
|
||||||
|
{"file":".trellis/spec/preview/index.md","reason":"The browser workbench is a new DOM runtime and must follow local preview loading and state conventions where applicable."}
|
||||||
|
{"file":".trellis/spec/config/index.md","reason":"New native-road output paths and config behavior extend the normalized area contract."}
|
||||||
@@ -0,0 +1,32 @@
|
|||||||
|
# Implementation Plan
|
||||||
|
|
||||||
|
1. Add area output/config normalization and command entrypoints for the native
|
||||||
|
compiler, preserving existing stage behavior and paths.
|
||||||
|
2. Implement a shared OSM road parser and canonical road/endpoints model with
|
||||||
|
source provenance, explicit versus inferred properties, and stable IDs.
|
||||||
|
3. Implement v1 override schema, validation, load/apply behavior, atomic save,
|
||||||
|
and focused unit tests.
|
||||||
|
4. Implement projected road segment geometry, supported T/cross junction
|
||||||
|
detection, native GeoJSON artifact emission, diagnostics, and comparison
|
||||||
|
summary.
|
||||||
|
5. Implement a dependency-free local workbench server and browser UI with
|
||||||
|
selection, provenance display, v1 parameter/topology editing, explicit save,
|
||||||
|
compile/reload, and error states.
|
||||||
|
6. Add native compiler tests using focused fixtures plus nantaizi analysis;
|
||||||
|
run existing relevant Node tests to confirm legacy behavior remains intact.
|
||||||
|
7. Compare nantaizi and at least one supplied problematic OSM sample. Record
|
||||||
|
metrics, unsupported cases, and follow-up work in task research.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run road:workbench -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run test:build-stages
|
||||||
|
npm run test:preflight
|
||||||
|
npm run test:preview-assets
|
||||||
|
```
|
||||||
|
|
||||||
|
Browser validation includes loading the workbench, editing a road parameter,
|
||||||
|
saving, verifying the override file, recompiling, reloading, and confirming
|
||||||
|
provenance identifies the saved override.
|
||||||
@@ -0,0 +1,93 @@
|
|||||||
|
# Native road compiler workbench
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Build an incremental native road compiler for Chinese urban and campus OSM
|
||||||
|
data that can progressively exceed osm2streets in geometry quality,
|
||||||
|
explainability, and repeatable correction. The existing osm2streets pipeline
|
||||||
|
must remain usable while the native compiler is developed and compared.
|
||||||
|
|
||||||
|
The first deliverable is a browser-based Road Workbench. It must expose the
|
||||||
|
native compiler's source data, generated geometry, and diagnostics, allow
|
||||||
|
users to make small semantic/topology corrections, persist those corrections
|
||||||
|
as versionable overrides, and reload them automatically in later runs.
|
||||||
|
|
||||||
|
## Confirmed Facts
|
||||||
|
|
||||||
|
- Nantaizi currently works relatively well because its OSM data received
|
||||||
|
deliberate supplemental tagging; it still has missing boundaries and
|
||||||
|
polygons that cannot be closed.
|
||||||
|
- Other tested OSM inputs expose osm2streets sensitivity to input structure
|
||||||
|
and leave too much opaque, final-polygon repair work in QGIS.
|
||||||
|
- Existing Blender consumes the nine GeoJSON render layers from
|
||||||
|
`osm2streets_web_out/`; QGIS GeoPackage edits can currently be reimported
|
||||||
|
only as a whole batch.
|
||||||
|
- The repository has no existing interactive browser editing service. Existing
|
||||||
|
Cesium preview is a static, generated verification page.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- R1: Add a native-road-compiler path without replacing or regressing the
|
||||||
|
existing osm2streets path.
|
||||||
|
- R2: Parse OSM into a canonical, source-traceable road model with stable
|
||||||
|
references to OSM ways and nodes, explicit values versus inferred values,
|
||||||
|
and diagnostics.
|
||||||
|
- R3: Compile at least ordinary road segments and the initial supported
|
||||||
|
junction subset into the existing render-layer contract, allowing existing
|
||||||
|
Blender/Cesium consumers to be reused.
|
||||||
|
- R4: Provide a browser Road Workbench that overlays raw OSM topology,
|
||||||
|
generated geometry, osm2streets comparison geometry when available, and
|
||||||
|
compiler diagnostics.
|
||||||
|
- R5: The workbench must permit scoped user adjustments and save them to an
|
||||||
|
area-local, human-reviewable override file. Future compile and workbench
|
||||||
|
runs must load that file automatically.
|
||||||
|
- R6: Each generated object and diagnostic must be traceable to OSM source
|
||||||
|
IDs, compiler rule/inference evidence, and relevant override IDs.
|
||||||
|
- R7: Validate topology and geometry before publishing generated layers;
|
||||||
|
report unresolved semantic errors instead of silently disguising them as
|
||||||
|
geometric repair.
|
||||||
|
- R8: Develop against nantaizi plus problem inputs and report native versus
|
||||||
|
osm2streets comparison metrics.
|
||||||
|
|
||||||
|
## Scope Boundaries
|
||||||
|
|
||||||
|
- First implementation targets Chinese urban/campus roads, ordinary road
|
||||||
|
segments, T/cross junctions, directed/multi-lane roads, and data already
|
||||||
|
tagged in nantaizi where possible.
|
||||||
|
- Existing Blender, Cesium export, package format, building, vegetation, and
|
||||||
|
water generators are out of scope unless a compatibility adapter requires a
|
||||||
|
narrowly scoped change.
|
||||||
|
- Directly editing final render polygons is not the intended correction model;
|
||||||
|
generated layers remain derived output.
|
||||||
|
- Complex interchanges, arbitrary multilayer junctions, and full worldwide OSM
|
||||||
|
coverage are deferred until driven by concrete samples.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] A native compile command produces a canonical road model, generated
|
||||||
|
layers, diagnostics, and comparison artifacts for a configured area without
|
||||||
|
changing the osm2streets output path.
|
||||||
|
- [ ] A browser command serves a Road Workbench for an area and clearly shows
|
||||||
|
source topology, generated output, diagnostics, provenance, and saved
|
||||||
|
overrides.
|
||||||
|
- [ ] A user can make the agreed first-scope override edits in the browser,
|
||||||
|
save them explicitly, and receive a durable area-local override artifact.
|
||||||
|
- [ ] Re-running compile or reopening the workbench applies saved overrides
|
||||||
|
automatically and exposes their provenance.
|
||||||
|
- [ ] The compiler reports invalid/unclosed geometry, dangling road ends,
|
||||||
|
and unresolved junction/lane ambiguity with source IDs.
|
||||||
|
- [ ] Nantaizi and at least one known problematic area can run through the
|
||||||
|
native analysis/preview path, with comparison metrics captured rather than
|
||||||
|
a claim based only on visual inspection.
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
|
||||||
|
- The first browser editing surface supports road parameters (width, directed
|
||||||
|
lane counts, left/right sidewalk state) plus junction endpoint
|
||||||
|
connect/disconnect decisions.
|
||||||
|
- Turn restrictions, stop lines, and crosswalk placement are deferred until
|
||||||
|
the compiler has a validated road/junction editing loop.
|
||||||
|
- Overrides are a versioned, human-reviewable JSON artifact owned by the area,
|
||||||
|
not edits to generated polygon layers.
|
||||||
|
- Native output and osm2streets output remain parallel during development;
|
||||||
|
neither silently overwrites the other.
|
||||||
+50
@@ -0,0 +1,50 @@
|
|||||||
|
# Two-Area Native Road Comparison
|
||||||
|
|
||||||
|
## Runs
|
||||||
|
|
||||||
|
2026-08-14:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run build:area -- --config config/areas/hanyang-block.json --stages intermediates
|
||||||
|
npm run road:compile -- --config config/areas/hanyang-block.json
|
||||||
|
```
|
||||||
|
|
||||||
|
`comparison.json` is a coverage and diagnostic record. Feature counts are not
|
||||||
|
a geometry-quality score: osm2streets and the native compiler segment roads at
|
||||||
|
different levels.
|
||||||
|
|
||||||
|
| Area | Directional roads | Native surfaces | Native junctions | Movements | Internal ends | Manual candidates | osm2streets road surfaces |
|
||||||
|
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||||
|
| nantaizi-lake-innovation-valley | 34 | 19 | 6 | 46 | 4 | 2 | 50 |
|
||||||
|
| hanyang-block | 475 | 352 | 20 | 369 | 161 | 83 | 1826 |
|
||||||
|
|
||||||
|
## Observed Failure Modes
|
||||||
|
|
||||||
|
The hanyang osm2streets/QGIS run completed, but its log reported repeated:
|
||||||
|
|
||||||
|
- roads trimmed into oblivion;
|
||||||
|
- degenerate intersections that could not be collapsed because layers, names,
|
||||||
|
highway types, or lane specifications differ;
|
||||||
|
- intersection polygon requests with no roads.
|
||||||
|
|
||||||
|
The native compiler did not hide the related uncertainty. It reported 161
|
||||||
|
internal road ends. Eighty-three have one or more nearby, direction-compatible
|
||||||
|
candidate departures within 35 metres; these remain suggestions for explicit
|
||||||
|
review rather than automatic topology edits. The initial five one-way junctions
|
||||||
|
that lacked connector curves now publish road-surface envelopes based on their
|
||||||
|
semantic movements. Across hanyang, 369 movements are identified: 243 require
|
||||||
|
a connector curve, while 126 are continuous at their OSM node and intentionally
|
||||||
|
have no separate geometry.
|
||||||
|
|
||||||
|
## Resulting Priorities
|
||||||
|
|
||||||
|
1. Keep manual candidate suggestions and semantic overrides as the correction
|
||||||
|
path for near-miss topology. Do not bulk-connect candidates.
|
||||||
|
2. Expand ordinary junction support from 3/4 physical approaches only after
|
||||||
|
identifying a repeated unsupported topology; one-way movements that are
|
||||||
|
continuous at a node are already supported without fake connector geometry.
|
||||||
|
3. Add an inspectable movement artifact so turn geometry is not the only
|
||||||
|
representation of a road-to-road movement.
|
||||||
|
4. Use a visual review of a few explicit hanyang diagnostics before changing
|
||||||
|
connection-distance or road-class rules.
|
||||||
@@ -0,0 +1,32 @@
|
|||||||
|
{
|
||||||
|
"id": "native-road-compiler",
|
||||||
|
"name": "native-road-compiler",
|
||||||
|
"title": "Native road compiler workbench",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-13",
|
||||||
|
"completedAt": "2026-08-18",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [
|
||||||
|
"08-14-native-road-lane-markings",
|
||||||
|
"08-17-native-road-control-markings",
|
||||||
|
"08-17-native-road-center-lines",
|
||||||
|
"08-17-native-rounded-junctions",
|
||||||
|
"08-18-native-traffic-signal-parity"
|
||||||
|
],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||||
@@ -0,0 +1,77 @@
|
|||||||
|
# Native Lane Markings Design
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
The native compiler remains the source of truth. It derives two new polygon
|
||||||
|
layers alongside its existing surface, sidewalk, lane-centerline, and
|
||||||
|
connector outputs:
|
||||||
|
|
||||||
|
```text
|
||||||
|
canonical directed roads + lane centerlines + junction cutbacks
|
||||||
|
|
|
||||||
|
+-- lane separators: paint polygons between adjacent same-direction lanes
|
||||||
|
|
|
||||||
|
+-- direction arrows: repeated through-arrow template on directed lanes,
|
||||||
|
| outside the reserved junction marking zone
|
||||||
|
|
|
||||||
|
+-- turn arrows: tested existing template, anchored to an incoming lane
|
||||||
|
only when that lane has an explicit supported turn:lanes value
|
||||||
|
```
|
||||||
|
|
||||||
|
No OSM2streets rendered geometry is consumed by this path. The existing arrow
|
||||||
|
template library is reused only as a geometry/style asset, so the native lane
|
||||||
|
ID and OSM tags remain the evidence for placement.
|
||||||
|
|
||||||
|
## Contracts
|
||||||
|
|
||||||
|
- `layers/lane_separators.geojson`: polygon FeatureCollection. Each feature
|
||||||
|
records `native_id`, directed `road_id`, adjacent lane indices, source OSM
|
||||||
|
ways, and `native-road-lane-separator/v1` provenance.
|
||||||
|
- `layers/turn_arrows.geojson`: polygon FeatureCollection. Each feature records
|
||||||
|
its `native_id`, `road_id`, `lane_id`, OSM way IDs, direction, lane index,
|
||||||
|
maneuver, template asset, placement distance, and placement provenance.
|
||||||
|
- Unsupported turn values, a missing usable incoming-lane segment, or an
|
||||||
|
insufficient pre-junction placement distance create a diagnostic and no
|
||||||
|
arrow geometry.
|
||||||
|
- `layers/direction_arrows.geojson`: polygon FeatureCollection. Each feature
|
||||||
|
records the native lane and directed road, OSM way IDs, a stable sequence
|
||||||
|
index, its distance along the lane, and `native-road-direction-arrow/v1`
|
||||||
|
provenance. It uses the tested `through` template but is not a turn claim.
|
||||||
|
- The workbench serves both layers, draws them separately from its current
|
||||||
|
centerline/connector debug layer, and selects them by `native_id`.
|
||||||
|
- `catalog.NATIVE_ROAD_LAYERS` maps the two native sources to the existing
|
||||||
|
`lane_separators` and `lane_arrows_webscale` Blender materials. The native
|
||||||
|
adapter does not extend the osm2streets scene-layer registry.
|
||||||
|
|
||||||
|
## Placement
|
||||||
|
|
||||||
|
An incoming lane is oriented in driving direction. A turn arrow is sampled
|
||||||
|
from that lane's endpoint backwards by the configured safe distance, staying
|
||||||
|
outside the junction cutback. Its template basis uses the sampled lane tangent;
|
||||||
|
therefore it is on and aligned with the lane rather than the OSM centerline or
|
||||||
|
a screen-space direction. Multiple template rings remain separate polygons.
|
||||||
|
|
||||||
|
Lane separators are narrow polygons centered between adjacent lane centerlines
|
||||||
|
on a single directional carriageway. They stop at the same junction cutbacks as
|
||||||
|
the lane centerlines. A one-lane direction produces none.
|
||||||
|
|
||||||
|
Direction arrows are sampled at a fixed road-scale interval along the same
|
||||||
|
directed lane centerline. Their candidates exclude both endpoint buffers and
|
||||||
|
the turn-arrow reserve at the incoming end. This preserves a readable repeated
|
||||||
|
direction cue without overlapping a turn instruction at a junction.
|
||||||
|
|
||||||
|
## Compatibility And Rollback
|
||||||
|
|
||||||
|
All new files are additive under `native-road/layers/`. The existing
|
||||||
|
osm2streets/QGIS layer contract and `package/` are unchanged. Selecting
|
||||||
|
`--road-provider osm2streets` remains rollback. Missing native marking files
|
||||||
|
are a native Blender build error rather than a silent omission.
|
||||||
|
|
||||||
|
## Risks
|
||||||
|
|
||||||
|
- OSM turn tags can be incomplete or incompatible with the inferred lane
|
||||||
|
count. These are diagnostics, not guessed arrows.
|
||||||
|
- Very short approaches can have no safe position before the cutback. They are
|
||||||
|
skipped with a source-traceable diagnostic.
|
||||||
|
- Blender and Cesium need a real native build to verify the mesh/material
|
||||||
|
contract, not only GeoJSON unit tests.
|
||||||
@@ -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,31 @@
|
|||||||
|
# Implementation Plan
|
||||||
|
|
||||||
|
1. Add reusable template-placement helper to the existing turn-arrow module,
|
||||||
|
preserving its supported-asset gate and output ring shape.
|
||||||
|
2. Extend the native compiler with lane-separator, repeated road-direction
|
||||||
|
arrow, and explicit-turn-arrow polygon generation plus source diagnostics
|
||||||
|
and layer persistence.
|
||||||
|
3. Extend native output records/counts and Blender adapter mappings. Reuse
|
||||||
|
existing `lane_separators` and `lane_arrows_webscale` materials only.
|
||||||
|
4. Add Workbench layers, toggles, selection/provenance inspector entries, and
|
||||||
|
preserve the existing Workbench-only direction triangle behavior.
|
||||||
|
5. Add focused fixtures for supported turn placement, unsupported maneuver,
|
||||||
|
short approach skip, and separator geometry; run native/workbench/build
|
||||||
|
stage tests.
|
||||||
|
6. Build Nantaizi with `blender,cesium,preview --road-provider native`, inspect
|
||||||
|
the final preview, and confirm no `package/` publication occurred.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:native-road
|
||||||
|
npm run test:road-workbench
|
||||||
|
npm run test:turn-lane-arrows
|
||||||
|
npm run test:build-stages
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json \
|
||||||
|
--stages blender,cesium,preview --road-provider native
|
||||||
|
```
|
||||||
|
|
||||||
|
Rollback is selecting `--road-provider osm2streets`; no existing output path
|
||||||
|
is replaced.
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
# Native road lane markings and turn arrows
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Complete the native-road visual language for Nantaizi before any cross-area
|
||||||
|
migration: lane separators, travel-direction markers, and OSM-backed turn
|
||||||
|
arrows must be inspectable in the Road Workbench and visible in Blender and
|
||||||
|
Cesium output.
|
||||||
|
|
||||||
|
## Confirmed Facts
|
||||||
|
|
||||||
|
- Native output currently contains directed lane centerlines and connector
|
||||||
|
curves, but it does not emit paintable lane-separator or turn-arrow polygons.
|
||||||
|
- The existing osm2streets path has tested arrow templates in
|
||||||
|
`scripts/lib/turn-lane-arrows.js`, the `lane_arrows_webscale` material layer,
|
||||||
|
and a matching Blender material. Reuse these instead of introducing a second
|
||||||
|
arrow style.
|
||||||
|
- Earlier reviews established that direction markers must sit on the OSM / lane
|
||||||
|
centerline, use a clearly directional sharp triangle, and never be treated as
|
||||||
|
a road-surface decoration that drifts sideways.
|
||||||
|
- Turn arrows must follow the actual incoming lane and be placed before its
|
||||||
|
junction, with OSM source way, direction, lane index, and maneuver retained
|
||||||
|
as provenance.
|
||||||
|
- Scope remains Nantaizi only. Existing osm2streets output remains untouched.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- R1: Native compilation emits polygonal lane-separator markings derived from
|
||||||
|
its own directed lane geometry.
|
||||||
|
- R2: Native compilation emits turn-arrow polygons for supported OSM
|
||||||
|
`turn:lanes` maneuvers, using the existing tested arrow templates and the
|
||||||
|
exact native incoming-lane centerline for placement.
|
||||||
|
- R2a: Native compilation emits repeated straight-ahead direction-arrow
|
||||||
|
polygons along directed lanes, matching the visual role of osm2streets'
|
||||||
|
ordinary road arrows. These are a separate layer from turn arrows, retain
|
||||||
|
their own provenance, and leave a clear buffer around junction turn arrows.
|
||||||
|
- R3: Native output preserves provenance for every marking: native road/lane
|
||||||
|
ID, OSM way IDs, direction, lane number, maneuver, and placement method.
|
||||||
|
- R4: The Workbench renders markings in a separately controllable layer and
|
||||||
|
exposes those provenance fields on selection.
|
||||||
|
- R5: The native Blender adapter consumes native marking layers through the
|
||||||
|
existing lane-separator and lane-arrow material layers; Cesium must receive
|
||||||
|
the same geometry through the exported GLB.
|
||||||
|
- R6: Unsupported, unplaceable, or ambiguous arrow inputs become diagnostics;
|
||||||
|
the compiler must not invent a maneuver.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] Nantaizi native output contains valid polygon GeoJSON for generated lane
|
||||||
|
separators, repeated road direction arrows, and every supported, explicitly
|
||||||
|
tagged turn arrow.
|
||||||
|
- [ ] A Workbench user can toggle, select, and inspect a generated marker and
|
||||||
|
see its lane, OSM, maneuver, and placement provenance.
|
||||||
|
- [ ] A selected direction marker is geometrically aligned to its directed lane
|
||||||
|
centerline; a selected turn arrow is on its incoming lane before the junction.
|
||||||
|
- [ ] Blender scene output and Cesium GLB contain native lane markings and
|
||||||
|
arrows with the existing visual material language.
|
||||||
|
- [ ] Unit tests cover a normal supported arrow, an unsupported maneuver, and
|
||||||
|
an unsafe/too-short placement; native compile and final Nantaizi visual build
|
||||||
|
pass without publishing `package/`.
|
||||||
|
|
||||||
|
## Out Of Scope
|
||||||
|
|
||||||
|
- Inventing turn arrows for untagged lanes, traffic-control semantics, changing
|
||||||
|
QGIS/osm2streets layers, or processing another area.
|
||||||
|
|
||||||
|
## Key Decision
|
||||||
|
|
||||||
|
- Sharp travel-direction triangles remain a Workbench-only inspection aid.
|
||||||
|
They explain raw OSM node order after a road is selected.
|
||||||
|
- Repeated `through` direction arrows are final road markings, distinct from
|
||||||
|
both those debug triangles and OSM-backed junction turn arrows. They are
|
||||||
|
placed on native lane centerlines at a fixed interval and enter the same
|
||||||
|
Blender/Cesium material layer as turn arrows.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-road-lane-markings",
|
||||||
|
"name": "native-road-lane-markings",
|
||||||
|
"title": "Native road lane markings and turn arrows",
|
||||||
|
"description": "Complete Nantaizi native lane separators, travel direction and turn-arrow geometry through Road Workbench, Blender and Cesium before cross-area migration.",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P1",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-14",
|
||||||
|
"completedAt": "2026-08-14",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": "08-13-native-road-compiler",
|
||||||
|
"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,35 @@
|
|||||||
|
# Native Lane Separator Style Overrides Design
|
||||||
|
|
||||||
|
## Contract
|
||||||
|
|
||||||
|
The override is identified by the stable `roadId` plus the adjacent lane pair:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "车道分隔线:road:way/123:forward:1-2",
|
||||||
|
"kind": "lane-separator-style",
|
||||||
|
"roadId": "road:way/123:forward",
|
||||||
|
"leftLaneIndex": 1,
|
||||||
|
"rightLaneIndex": 2,
|
||||||
|
"color": "white",
|
||||||
|
"pattern": "dashed"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The same `yellow|white` and `dashed|solid` enums are reused. A default is
|
||||||
|
white dashed. The generated Polygon stores `color`, `pattern` and
|
||||||
|
`effective_style`; source IDs remain unchanged.
|
||||||
|
|
||||||
|
## Rendering
|
||||||
|
|
||||||
|
The existing lane separator polygon represents the whole lane-pair path.
|
||||||
|
`solid` retains it as one continuous feature. `dashed` samples regular dash
|
||||||
|
polygons along the shared centreline with deterministic spacing and preserves
|
||||||
|
junction cutback. White uses the existing `lane_separators` material; yellow
|
||||||
|
uses a native-only yellow material route. Workbench separates lane separators
|
||||||
|
from turn arrows so their styles remain selectable and visible.
|
||||||
|
|
||||||
|
## Compatibility
|
||||||
|
|
||||||
|
No override means current visual default. Road edges, curbs and centre lines
|
||||||
|
are untouched. Existing `native-road-overrides/v1` files remain valid.
|
||||||
@@ -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,7 @@
|
|||||||
|
# Implementation Plan
|
||||||
|
|
||||||
|
1. Validate and resolve per-lane-pair style overrides.
|
||||||
|
2. Generate default/dashed/solid style geometry and effective properties.
|
||||||
|
3. Add the native Blender yellow lane-separator material route.
|
||||||
|
4. Add Workbench selection, Chinese editor and automatic staging.
|
||||||
|
5. Test compiler, Workbench, Blender catalog and Nantaizi native build.
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
# Native lane separator style overrides
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Make native same-direction lane separators selectable and persistently editable
|
||||||
|
in Road Workbench, using the style override pattern proven for centre lines.
|
||||||
|
|
||||||
|
## Confirmed Facts
|
||||||
|
|
||||||
|
- `compileLaneMarkings()` writes one continuous `0.12m` Polygon separator
|
||||||
|
between each adjacent lane pair, identified by `road_id`, `left_lane_index`
|
||||||
|
and `right_lane_index`.
|
||||||
|
- Lane separators currently have fixed light marking material and are displayed
|
||||||
|
together with turn arrows in Workbench.
|
||||||
|
- `native-road-overrides.json` already supports validated, persistent centre
|
||||||
|
line styles by logical native segment. The new type must not alter road-edge,
|
||||||
|
curb or sidewalk geometry.
|
||||||
|
|
||||||
|
## Initial Requirements
|
||||||
|
|
||||||
|
- Selecting a lane separator must show its lane-pair source and a Chinese
|
||||||
|
style editor.
|
||||||
|
- The first style catalog should mirror centre lines: white/yellow and
|
||||||
|
dashed/solid.
|
||||||
|
- The effective style must be generated into GeoJSON, visible in Workbench,
|
||||||
|
and consumed by native Blender/Cesium.
|
||||||
|
- Default output must remain the current white dashed-style separator.
|
||||||
|
|
||||||
|
## Out Of Scope
|
||||||
|
|
||||||
|
- Road-edge lines, curbs, sidewalks, double lines, partial ranges, lane-specific
|
||||||
|
legal restrictions and osm2streets layers.
|
||||||
|
|
||||||
|
## Key Decision
|
||||||
|
|
||||||
|
Each override applies only to the selected adjacent lane pair. This preserves
|
||||||
|
separate marking semantics on roads with three or more lanes.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] Selecting a separator exposes a Chinese style editor for its adjacent
|
||||||
|
lane pair; choosing a style stages it automatically.
|
||||||
|
- [ ] Save and regeneration preserve the per-pair style across reloads while
|
||||||
|
unedited separators retain the default.
|
||||||
|
- [ ] GeoJSON, Workbench, Blender and Cesium show the same effective style.
|
||||||
|
- [ ] Tests cover validation, defaults, per-pair isolation, automatic staging
|
||||||
|
and native scene consumption.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-lane-separator-styles",
|
||||||
|
"name": "native-lane-separator-styles",
|
||||||
|
"title": "Native lane separator style overrides",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-17",
|
||||||
|
"completedAt": "2026-08-17",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
# Native Road Centre-Line Style Overrides Design
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```text
|
||||||
|
Workbench selects a generated centre-line dash
|
||||||
|
-> segment_id identifies the logical road segment
|
||||||
|
-> staged center-line-style override
|
||||||
|
-> native-road-overrides.json
|
||||||
|
-> compileCenterLines resolves default or effective style
|
||||||
|
-> center_lines.geojson polygons with style fields
|
||||||
|
-> Workbench / Blender / Cesium
|
||||||
|
```
|
||||||
|
|
||||||
|
The authoritative edit is a new override kind, not a mutation of
|
||||||
|
`center_lines.geojson`. It has a deterministic ID based on `segmentId`, so a
|
||||||
|
later recompilation replaces the segment's style rather than accumulating
|
||||||
|
records.
|
||||||
|
|
||||||
|
## Override Contract
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "道路中心线:segment:way/123/1",
|
||||||
|
"kind": "center-line-style",
|
||||||
|
"segmentId": "segment:way/123/1",
|
||||||
|
"color": "yellow",
|
||||||
|
"pattern": "dashed"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`validateOverrides()` accepts only known model segment IDs and the finite
|
||||||
|
string enums `yellow|white` and `dashed|solid`. A style override applies once
|
||||||
|
to the paired forward/backward native roads for that segment. The existing
|
||||||
|
schema version remains `native-road-overrides/v1` because this is an additive
|
||||||
|
kind and old files remain valid.
|
||||||
|
|
||||||
|
## Geometry and Material
|
||||||
|
|
||||||
|
- Default remains yellow dashed: 2m dash, 2m gap, 0.25m width.
|
||||||
|
- `solid` generates deterministic adjacent 2m pieces with no gap. Pieces still
|
||||||
|
undergo the same junction cutback and control-marking exclusion as dashed
|
||||||
|
lines; this avoids creating a solid polygon across an excluded crossing.
|
||||||
|
- Style fields `color`, `pattern`, `dash_length_m`, `dash_gap_m`, and
|
||||||
|
`effective_style` are stored on every generated polygon.
|
||||||
|
- Blender currently maps all `center_lines` to one yellow material, so the
|
||||||
|
native adapter must support a white centre-line material route without
|
||||||
|
changing legacy osm2streets layers. The route must preserve the existing
|
||||||
|
yellow material for default and yellow overrides.
|
||||||
|
|
||||||
|
## Workbench UX
|
||||||
|
|
||||||
|
Selecting a centre-line dash shows a compact Chinese style panel in the
|
||||||
|
existing form area. A select control presents the four named choices. Choosing
|
||||||
|
one stages an override; the existing 保存 / 保存并重新生成 actions remain the
|
||||||
|
only persistence and generation actions. The panel also shows whether the
|
||||||
|
style is default or overridden and identifies the native road segment.
|
||||||
|
|
||||||
|
## Compatibility and Rollback
|
||||||
|
|
||||||
|
Unedited segments generate byte-compatible geometry style defaults apart from
|
||||||
|
the added style properties. Oneway/service filtering and control priority are
|
||||||
|
unchanged. Selecting `--road-provider osm2streets` remains a full rollback.
|
||||||
|
|
||||||
@@ -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,31 @@
|
|||||||
|
# Implementation Plan
|
||||||
|
|
||||||
|
1. Add validated `center-line-style` overrides and a helper which resolves the
|
||||||
|
effective default/override style by segment ID.
|
||||||
|
2. Generate yellow/white and dashed/solid centre-line geometry while retaining
|
||||||
|
cutback and control-marking exclusion behaviour; publish effective style
|
||||||
|
properties.
|
||||||
|
3. Extend the native Blender layer adapter/material handling to distinguish
|
||||||
|
white from yellow centre-line features without affecting legacy layers.
|
||||||
|
4. Add Workbench style controls, staging, Chinese selection evidence, and
|
||||||
|
immediate regenerated-layer display.
|
||||||
|
5. Add focused compiler, override, Workbench, Blender catalog, and build-stage
|
||||||
|
tests; compile/check Nantaizi and build Blender/Cesium/preview without the
|
||||||
|
package stage.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:native-road
|
||||||
|
npm run test:road-workbench
|
||||||
|
python3 -m unittest discover blender/tests
|
||||||
|
npm run test:build-stages
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run road:check -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender,cesium,preview --road-provider native
|
||||||
|
```
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
Remove the override records or choose `--road-provider osm2streets`; no legacy
|
||||||
|
output is modified.
|
||||||
@@ -0,0 +1,62 @@
|
|||||||
|
# Native road center line style overrides
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Allow a Road Workbench user to select a generated native road centre line and
|
||||||
|
persistently override its marking style, without turning the generated GeoJSON
|
||||||
|
into the source of truth.
|
||||||
|
|
||||||
|
## Confirmed Facts
|
||||||
|
|
||||||
|
- Native `center_lines.geojson` currently contains automatic yellow dashed
|
||||||
|
polygons (`2m` dash, `2m` gap, `0.25m` width), each tied to a `segment_id`.
|
||||||
|
- A displayed dash can already be selected and exposes its segment provenance,
|
||||||
|
but has no editing controls.
|
||||||
|
- `native-road-overrides.json` is the persistent authority for existing road
|
||||||
|
and connection edits. The Workbench already stages, validates, saves, then
|
||||||
|
recompiles those overrides.
|
||||||
|
- The generated layer is consumed by both Workbench and native Blender/Cesium;
|
||||||
|
styling must therefore be compiled geometry and use the existing
|
||||||
|
`center_lines` material path, not a Workbench-only display tint.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- R1: Selecting a centre-line dash must expose a Chinese style editor for its
|
||||||
|
logical target and show the current effective style.
|
||||||
|
- R2: Supported styles must include at least solid/dashed and white/yellow
|
||||||
|
marking colours.
|
||||||
|
- R3: Style choices must be stored in `native-road-overrides.json`, validated,
|
||||||
|
reapplied during compilation, and survive a future Workbench launch.
|
||||||
|
- R4: The regenerated GeoJSON must carry source traceability and effective
|
||||||
|
style fields so Workbench, Blender and Cesium show the same marking.
|
||||||
|
- R5: Default automatic centre lines remain unchanged for segments without an
|
||||||
|
override; one-way/service exclusions and control-marking avoidance remain
|
||||||
|
authoritative.
|
||||||
|
|
||||||
|
## Initial Scope Boundary
|
||||||
|
|
||||||
|
- Editing individual dash polygons is out of scope: they are derived pieces,
|
||||||
|
not user-owned objects.
|
||||||
|
- Per-segment control is recommended for the first version because current
|
||||||
|
native segments already stop at junctions and have stable IDs.
|
||||||
|
- Double-line semantics, legal `overtaking` inference, hand-drawn partial
|
||||||
|
ranges, and changes to osm2streets output are out of scope unless explicitly
|
||||||
|
accepted during planning.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] A user can select a centre line, choose a supported style in Chinese,
|
||||||
|
save it, regenerate, and see the result immediately in the Workbench.
|
||||||
|
- [ ] After reload and recompilation, the selected segment retains its style
|
||||||
|
while unedited segments retain the automatic yellow dashed default.
|
||||||
|
- [ ] Native Blender/Cesium uses the same effective style and does not require
|
||||||
|
osm2streets geometry.
|
||||||
|
- [ ] Tests cover schema validation, style geometry, default fallback,
|
||||||
|
persistence/API wiring, and Workbench selection/edit controls.
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
|
||||||
|
- The first version applies one override to the complete native segment between
|
||||||
|
junctions. Individual dash and partial-range editing are deferred.
|
||||||
|
- The initial style catalog is four explicit choices: yellow dashed, white
|
||||||
|
dashed, yellow solid, and white solid. Double-line semantics are deferred.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-road-center-line-styles",
|
||||||
|
"name": "native-road-center-line-styles",
|
||||||
|
"title": "Native road center line style overrides",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-17",
|
||||||
|
"completedAt": "2026-08-17",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||||
@@ -0,0 +1,50 @@
|
|||||||
|
# Native Road Centre Lines Design
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
The native compiler adds one independent polygon layer:
|
||||||
|
|
||||||
|
```text
|
||||||
|
canonical bidirectional segment + trimmed OSM centreline
|
||||||
|
-> repeated 2m x 0.25m dash polygons
|
||||||
|
-> native-road/layers/center_lines.geojson
|
||||||
|
-> Workbench / native Blender adapter / Cesium
|
||||||
|
```
|
||||||
|
|
||||||
|
It does not read osm2streets `center_lines.geojson`. The legacy layer is a
|
||||||
|
visual baseline only.
|
||||||
|
|
||||||
|
## Placement
|
||||||
|
|
||||||
|
- A candidate must have exactly forward and backward native roads for the same
|
||||||
|
`segmentId`, neither be `highway=service`, and have a valid trimmed OSM
|
||||||
|
centreline.
|
||||||
|
- Dashes use the legacy observed dimensions: 2m length, 0.25m width, with a
|
||||||
|
deterministic 2m gap. The first dash starts at a fixed segment-local offset
|
||||||
|
so rebuilds do not drift.
|
||||||
|
- The line is trimmed with the same `junctionPlans` cutback used by native lane
|
||||||
|
centreline generation. Any dash intersecting a crosswalk or stop line is
|
||||||
|
omitted, preserving the control-marking priority already established.
|
||||||
|
- One-way and service segments have no generated feature. A degenerate source
|
||||||
|
line produces a diagnostic rather than malformed geometry.
|
||||||
|
|
||||||
|
## Contracts
|
||||||
|
|
||||||
|
`layers/center_lines.geojson` is a Polygon FeatureCollection. Every feature
|
||||||
|
has `native_id`, `segment_id`, `directional_road_ids`, `osm_way_ids`,
|
||||||
|
`dash_index`, `dash_length_m`, `dash_gap_m`, `placement_rule`, and
|
||||||
|
`provenance="native-road-center-line/v1"`.
|
||||||
|
|
||||||
|
`compiled.json.layers.centerLines`, comparison count
|
||||||
|
`nativeCenterLineFeatures`, and `build-area.js` required native records use the
|
||||||
|
same filename. `catalog.NATIVE_ROAD_LAYERS` maps source `center_lines` to the
|
||||||
|
existing `center_lines` material layer.
|
||||||
|
|
||||||
|
The Workbench loads this source into the marking overlay, exposes a Chinese
|
||||||
|
toggle, and identifies it as `道路中心虚线` on selection.
|
||||||
|
|
||||||
|
## Compatibility
|
||||||
|
|
||||||
|
The change is additive within `native-road/`; `--road-provider osm2streets`
|
||||||
|
remains unaffected and is rollback. A native Blender build treats a missing
|
||||||
|
layer as an input error rather than silently omitting it.
|
||||||
@@ -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,19 @@
|
|||||||
|
# Implementation Plan
|
||||||
|
|
||||||
|
1. Add centre-dash constants and a pure native compiler routine based on the
|
||||||
|
shared bidirectional segment model and junction-trimmed centreline.
|
||||||
|
2. Filter invalid, one-way, service, and control-marking-conflicting dashes;
|
||||||
|
record actionable diagnostics for invalid geometry only.
|
||||||
|
3. Write `center_lines.geojson`, compilation/comparison counts, native build
|
||||||
|
records, required-layer checks, and Blender material adapter mapping.
|
||||||
|
4. Add Workbench API state, Chinese toggle, summary count, rendering, and
|
||||||
|
source evidence for a selected centre dash.
|
||||||
|
5. Add focused native and Workbench tests for generation, skips, control
|
||||||
|
avoidance, provenance, and file/API contracts.
|
||||||
|
6. Run native/unit/workbench/build-stage tests, compile/check Nantaizi, then
|
||||||
|
validate `blender,cesium,preview --road-provider native` without `package`.
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
Choose `--road-provider osm2streets`; no legacy layer or published package is
|
||||||
|
modified.
|
||||||
@@ -0,0 +1,58 @@
|
|||||||
|
# Native road center lines
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Restore the existing osm2streets-style road-centre dashed markings in the
|
||||||
|
native-road provider before treating native output as ready for broader quality
|
||||||
|
gates or new-area validation.
|
||||||
|
|
||||||
|
## Confirmed Facts
|
||||||
|
|
||||||
|
- Nantaizi's existing `osm2streets_web_out/center_lines.geojson` has 885
|
||||||
|
`type="center line"` polygons. Its sampled dash geometry is approximately
|
||||||
|
2.00m long by 0.25m wide.
|
||||||
|
- The legacy extraction excludes centre lines that overlap crosswalk zones and
|
||||||
|
that fall on service driving polygons (`build-osm2streets-qgis.js:474-480`).
|
||||||
|
- Native output currently has only same-direction `lane_separators`; it has no
|
||||||
|
`center_lines.geojson`, so a bidirectional road's directional carriageways
|
||||||
|
lack their visual and semantic divider.
|
||||||
|
- Existing Blender already owns a `center_lines` / `Center Line` material
|
||||||
|
layer. Native must adapt to it rather than creating a second scene registry.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- R1: For supported non-service, bidirectional native road segments, emit a
|
||||||
|
`center_lines.geojson` dashed centre divider derived from the canonical OSM
|
||||||
|
centreline and the segment's two directional carriageways.
|
||||||
|
- R2: Match the established visual baseline: yellow 0.25m-wide, 2m-long
|
||||||
|
dashes, clipped away from ordinary junction cutbacks and control markings.
|
||||||
|
- R3: Preserve source traceability: each dash records its native segment,
|
||||||
|
source OSM way, involved directional roads, placement interval/rule, and a
|
||||||
|
dedicated provenance value.
|
||||||
|
- R4: Add the layer to compilation records, Road Workbench display/selection
|
||||||
|
in Chinese, and the existing Blender/Cesium `center_lines` material path.
|
||||||
|
- R5: Do not render a centre divider on one-way or `highway=service` segments;
|
||||||
|
report invalid geometry instead of fabricating a divider.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] Native Nantaizi output contains a valid `layers/center_lines.geojson`
|
||||||
|
with source-traceable 2m x 0.25m dashed polygons.
|
||||||
|
- [ ] No native centre dash intersects a generated crosswalk or vehicle stop
|
||||||
|
line, and no dash reaches into the supported junction surface cutback.
|
||||||
|
- [ ] The Workbench can toggle and select centre lines, presenting their
|
||||||
|
source and rule in Chinese rather than calling them lane separators.
|
||||||
|
- [ ] Native `blender,cesium,preview` consumes the layer using the existing
|
||||||
|
`center_lines` material and does not run `package`.
|
||||||
|
- [ ] Tests cover two-way generation, one-way/service skips, control-marking
|
||||||
|
avoidance, provenance, output contract, and Workbench wiring.
|
||||||
|
|
||||||
|
## Out Of Scope
|
||||||
|
|
||||||
|
- Centre-line editing overrides, solid/double-centre-line semantics, arbitrary
|
||||||
|
OSM `overtaking` interpretation, lane colouring changes, and other areas.
|
||||||
|
|
||||||
|
## Key Decision
|
||||||
|
|
||||||
|
This task deliberately matches the existing stable visual layer first. It does
|
||||||
|
not claim to infer a country-wide legal marking taxonomy from sparse OSM tags.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-road-center-lines",
|
||||||
|
"name": "native-road-center-lines",
|
||||||
|
"title": "Native road center lines",
|
||||||
|
"description": "Align native-road output with the existing center_lines layer before broader quality work.",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-17",
|
||||||
|
"completedAt": "2026-08-17",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": "08-13-native-road-compiler",
|
||||||
|
"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,66 @@
|
|||||||
|
# Native Road Control Markings Design
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
The native compiler remains the source of truth. It extends its canonical OSM
|
||||||
|
parse with marked crossing nodes, then derives two additive polygon layers from
|
||||||
|
the crossing evidence, native directed lanes, and native junction plans:
|
||||||
|
|
||||||
|
```text
|
||||||
|
OSM crossing node + native directed lane centerlines + junction plans
|
||||||
|
|
|
||||||
|
+-- crosswalks.geojson: six zebra stripe polygons per safe crossing
|
||||||
|
|
|
||||||
|
+-- vehicle_stop_lines.geojson: one safe approach stop-line polygon
|
||||||
|
```
|
||||||
|
|
||||||
|
No osm2streets GeoJSON is read. Existing crossing geometry helpers may be
|
||||||
|
extracted or adapted only when they operate on native lane data and retain
|
||||||
|
native provenance.
|
||||||
|
|
||||||
|
## Source And Placement
|
||||||
|
|
||||||
|
- A source node is eligible only when `highway=crossing` and
|
||||||
|
`crossing:markings` is not `no`, `none`, or `unmarked`.
|
||||||
|
- The compiler finds native roads containing the crossing's OSM node and uses
|
||||||
|
the nearest compatible directed lane centerline to obtain the road tangent.
|
||||||
|
- Crosswalk stripes are perpendicular to that tangent and constrained to the
|
||||||
|
native road width. Existing fixed zebra dimensions are retained initially:
|
||||||
|
six 0.45m stripes with 0.45m gaps, 0.45m stripe width, and a highway-based
|
||||||
|
stripe length.
|
||||||
|
- A stop line is generated only when the crossing can be associated with a
|
||||||
|
supported junction approach and a safe outside-of-junction side. Otherwise
|
||||||
|
the crosswalk may remain valid but the missing stop line is diagnostic.
|
||||||
|
- Duplicate nearby crossing nodes use a stable cluster representative so one
|
||||||
|
physical crosswalk does not produce duplicate stripes.
|
||||||
|
|
||||||
|
## Contracts
|
||||||
|
|
||||||
|
`layers/crosswalks.geojson` and `layers/vehicle_stop_lines.geojson` are Polygon
|
||||||
|
FeatureCollections. Each feature records its crossing OSM node, source OSM way,
|
||||||
|
native directed road/lane when available, direction, placement method, and
|
||||||
|
`native-road-crosswalk/v1` or `native-road-stop-line/v1` provenance.
|
||||||
|
|
||||||
|
The Workbench API returns both layers as `state.layers.crosswalks` and
|
||||||
|
`state.layers.vehicleStopLines`. Its browser map uses separate toggleable
|
||||||
|
layers and selection evidence; the scene-preview toggle leaves real control
|
||||||
|
markings visible.
|
||||||
|
|
||||||
|
`catalog.NATIVE_ROAD_LAYERS` maps the sources to existing `crosswalks` and
|
||||||
|
`vehicle_stop_lines` material layers. This native adapter must not add them to
|
||||||
|
the osm2streets `ROAD_LAYERS` / `SCENE_LAYERS` registry.
|
||||||
|
|
||||||
|
## Compatibility And Rollback
|
||||||
|
|
||||||
|
The new files are additive under `native-road/layers/`. Existing osm2streets
|
||||||
|
output and QGIS input are unchanged. Selecting `--road-provider osm2streets`
|
||||||
|
remains rollback. A native Blender build treats a missing new layer as an error
|
||||||
|
rather than silently omitting a visible marking.
|
||||||
|
|
||||||
|
## Risks
|
||||||
|
|
||||||
|
- Crossing nodes can be detached from a routable road or lie on an ambiguous
|
||||||
|
multi-road segment. These become diagnostics rather than guessed geometry.
|
||||||
|
- A physical crossing split into several OSM nodes must deduplicate stably.
|
||||||
|
- A crosswalk near a non-supported junction may get stripes but no valid stop
|
||||||
|
line; this difference must be exposed in workbench provenance.
|
||||||
@@ -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,31 @@
|
|||||||
|
# Implementation Plan
|
||||||
|
|
||||||
|
1. Extend the native OSM parse/model with marked crossing-node evidence while
|
||||||
|
preserving existing road IDs and parser behavior.
|
||||||
|
2. Add native crossing clustering, tangent resolution from directed lane
|
||||||
|
centerlines, stripe geometry, safe stop-line placement, and source
|
||||||
|
diagnostics.
|
||||||
|
3. Persist the two new layers in `compile-native-roads.js`, comparison counts,
|
||||||
|
native build records, required native layer checks, and existing Blender
|
||||||
|
material mappings.
|
||||||
|
4. Add Workbench API/state fields, Chinese layer toggles, selection evidence,
|
||||||
|
and summary counts while retaining scene-preview behavior.
|
||||||
|
5. Add focused fixtures for marked and unmarked crossings, duplicate cluster
|
||||||
|
handling, a missing native-lane diagnostic, and output layer contracts.
|
||||||
|
6. Run native/unit/workbench/build-stage tests, compile/check Nantaizi, then
|
||||||
|
build `blender,cesium,preview --road-provider native` without `package/`.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:native-road
|
||||||
|
npm run test:road-workbench
|
||||||
|
npm run test:build-stages
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run road:check -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json \
|
||||||
|
--stages blender,cesium,preview --road-provider native
|
||||||
|
```
|
||||||
|
|
||||||
|
Rollback is selecting `--road-provider osm2streets`; no legacy output path is
|
||||||
|
changed.
|
||||||
@@ -0,0 +1,61 @@
|
|||||||
|
# Native road control markings
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Give Nantaizi's native-road provider inspectable, source-traceable crosswalk
|
||||||
|
and vehicle stop-line geometry, so intersection control markings do not depend
|
||||||
|
on the osm2streets render output.
|
||||||
|
|
||||||
|
## Confirmed Facts
|
||||||
|
|
||||||
|
- Native road output already owns road surfaces, sidewalks, lane separators,
|
||||||
|
repeated direction arrows, and explicit junction-turn arrows.
|
||||||
|
- Nantaizi's OSM input contains explicit marked crossings, including zebra and
|
||||||
|
traffic-signal crossings. The existing osm2streets output currently has 48
|
||||||
|
crosswalk-stripe polygons and 8 stop-line polygons.
|
||||||
|
- `build-osm2streets-qgis.js:1067` derives these markings from crossing nodes
|
||||||
|
plus osm2streets driving lanes. Native must not read that rendered geometry;
|
||||||
|
it can reuse only the tested geometry rules after adapting them to native
|
||||||
|
directed lanes and junction plans.
|
||||||
|
- Existing Blender materials already provide `crosswalks` and
|
||||||
|
`vehicle_stop_lines`; native may map into them without changing the legacy
|
||||||
|
osm2streets layer registry.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- R1: Native compilation uses explicit marked OSM crossing nodes only, and
|
||||||
|
emits crosswalk-stripe polygons plus approach stop lines only where safe
|
||||||
|
native directed-road placement exists.
|
||||||
|
- R2: Each generated feature preserves crossing node, OSM road, native road or
|
||||||
|
lane, direction, placement method, and relevant junction provenance.
|
||||||
|
- R3: The Road Workbench independently toggles, selects, and describes native
|
||||||
|
crosswalks and stop lines in Chinese.
|
||||||
|
- R4: Native Blender and Cesium builds consume both layers with the existing
|
||||||
|
control-marking materials; no `package/` publication is part of validation.
|
||||||
|
- R5: Missing compatible road context, ambiguous geometry, and unsupported
|
||||||
|
crossing inputs are diagnostics; the compiler must not invent a crossing.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] Nantaizi native output contains valid `crosswalks.geojson` and
|
||||||
|
`vehicle_stop_lines.geojson` features with source-traceable properties,
|
||||||
|
without reading osm2streets rendered layers.
|
||||||
|
- [ ] A Workbench user can toggle and select either marking type and see the
|
||||||
|
crossing node, associated road/direction, and placement evidence.
|
||||||
|
- [ ] Native Blender/Cesium output contains both marking types using existing
|
||||||
|
materials, after `blender,cesium,preview --road-provider native` and without
|
||||||
|
publishing `package/`.
|
||||||
|
- [ ] Tests cover a marked crossing, an unmarked crossing skip, a missing or
|
||||||
|
ambiguous native-road placement skip, and output-layer contract checks.
|
||||||
|
|
||||||
|
## Out Of Scope
|
||||||
|
|
||||||
|
- Hand-placed control-marking overrides, traffic-signal state-machine changes,
|
||||||
|
freehand polygon editing, processing another region, and importing
|
||||||
|
osm2streets-rendered crosswalk geometry.
|
||||||
|
|
||||||
|
## Key Decision
|
||||||
|
|
||||||
|
The first version is explicit-OSM-only. This is feasible for Nantaizi and
|
||||||
|
keeps control markings evidence-backed; missing data remains a diagnostic for
|
||||||
|
OSM improvement rather than a silent geometric guess.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-road-control-markings",
|
||||||
|
"name": "native-road-control-markings",
|
||||||
|
"title": "Native road control markings",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-17",
|
||||||
|
"completedAt": "2026-08-17",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": "08-13-native-road-compiler",
|
||||||
|
"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,19 @@
|
|||||||
|
# Native road edge markings
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
TBD.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- TBD
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] TBD
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
|
||||||
|
- Lightweight tasks can remain PRD-only.
|
||||||
|
- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-road-edge-markings",
|
||||||
|
"name": "native-road-edge-markings",
|
||||||
|
"title": "Native road edge markings",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-17",
|
||||||
|
"completedAt": "2026-08-17",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,3 @@
|
|||||||
|
{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"Check compiler and workbench marking contracts."}
|
||||||
|
{"file":".trellis/spec/blender/testing.md","reason":"Run required Blender test suite."}
|
||||||
|
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"Verify browser, compiler, and Blender consume the same output."}
|
||||||
@@ -0,0 +1,22 @@
|
|||||||
|
# Design
|
||||||
|
|
||||||
|
The compiler owns marking semantics. `center-line-style` remains segment
|
||||||
|
scoped because a bidirectional road segment shares one centre-line decision.
|
||||||
|
`edge-line-style` is scoped to `{ roadId, side }`, since a directional
|
||||||
|
carriageway has independently editable left and right outside edges.
|
||||||
|
|
||||||
|
`double: true` is valid only with yellow solid centre lines. Generation emits
|
||||||
|
two 0.32m-separated parallel polygons for each normal solid mark, preserving
|
||||||
|
junction cutback and crosswalk/stop-line clearance. This keeps the existing
|
||||||
|
solid line implementation and avoids a separate geometry pipeline.
|
||||||
|
|
||||||
|
Road edge lines use the existing road-edge offset geometry. A solid style is
|
||||||
|
one continuous buffered offset line; a dashed style uses deterministic 2m
|
||||||
|
marks at 4m spacing. Both carry `effective_style`, source IDs, side, and
|
||||||
|
native provenance.
|
||||||
|
|
||||||
|
The Workbench uses one marking form with an explicit selected target type.
|
||||||
|
Only a centre-line target exposes the double-yellow option; lane separators
|
||||||
|
and edge lines retain the ordinary colour/pattern choices. Staged changes pass
|
||||||
|
through the existing save and regenerate flow, so browser, compiler and
|
||||||
|
Blender read the same persisted override.
|
||||||
@@ -0,0 +1,3 @@
|
|||||||
|
{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"Native-road output, override, and stage contracts."}
|
||||||
|
{"file":".trellis/spec/blender/asset-generation.md","reason":"Native provider adapter and Blender output requirements."}
|
||||||
|
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"Intentional render-output change validation."}
|
||||||
@@ -0,0 +1,10 @@
|
|||||||
|
# Implementation
|
||||||
|
|
||||||
|
1. Extend override validation and native marking generation for explicit
|
||||||
|
double-yellow centre lines and per-side edge-line styles.
|
||||||
|
2. Extend the Chinese Workbench selection/form flow without adding another
|
||||||
|
editor or output format.
|
||||||
|
3. Add compiler and Workbench regression coverage for valid and invalid
|
||||||
|
payloads, generated geometry, and layer adapter completeness.
|
||||||
|
4. Compile/check Nantaizi, run native/Workbench/build-stage/Blender tests,
|
||||||
|
then run the native Blender/Cesium/preview chain.
|
||||||
@@ -0,0 +1,36 @@
|
|||||||
|
# Native road marking semantics
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Finish the native road marking model so the Nantaizi Road Workbench can
|
||||||
|
persist meaningful centre-line and road-edge-line styles, regenerate native
|
||||||
|
geometry deterministically, and deliver the same result to Blender/Cesium.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Add an explicit double-yellow-solid centre-line semantic. It must not be a
|
||||||
|
generic double-line switch that permits invalid colour/pattern combinations.
|
||||||
|
- Keep all marking edits area-local in `native-road-overrides.json`; generated
|
||||||
|
GeoJSON remains derived output.
|
||||||
|
- Make road edge lines selectable and style-editable in the Chinese Road
|
||||||
|
Workbench, alongside existing centre lines and lane separators.
|
||||||
|
- Preserve the default Nantaizi output unless a user supplies an override.
|
||||||
|
- Native geometry must remain independent of osm2streets render geometry.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] A `center-line-style` override with `double: true`, `yellow`, and
|
||||||
|
`solid` emits two offset centre-line polygons with an explicit effective
|
||||||
|
style, while invalid double combinations are rejected.
|
||||||
|
- [ ] An `edge-line-style` override targets one directional road side and
|
||||||
|
supports white/yellow plus solid/dashed styles.
|
||||||
|
- [ ] The Workbench exposes Chinese selection feedback, stages the correct
|
||||||
|
override payload, and only shows the double-yellow choice for centre lines.
|
||||||
|
- [ ] Nantaizi native compile/check, Workbench/native tests, Blender pure
|
||||||
|
tests, and native Blender/Cesium/preview build pass.
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
|
||||||
|
- Lightweight tasks can remain PRD-only.
|
||||||
|
- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-road-marking-semantics",
|
||||||
|
"name": "native-road-marking-semantics",
|
||||||
|
"title": "Native road marking semantics",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-17",
|
||||||
|
"completedAt": "2026-08-17",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,2 @@
|
|||||||
|
{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"Native geometry correctness and output contracts."}
|
||||||
|
{"file":".trellis/spec/blender/testing.md","reason":"Blender validation requirements."}
|
||||||
@@ -0,0 +1,18 @@
|
|||||||
|
# Design
|
||||||
|
|
||||||
|
Each approach contributes its two carriageway-edge points at the common
|
||||||
|
cutback distance. Points are ordered around the junction node. For each pair
|
||||||
|
from adjacent approaches, the compiler samples a deterministic quadratic
|
||||||
|
Bezier whose control point follows the pedestrian-side curb arc toward the
|
||||||
|
junction. Rounded plans use a larger cutback than the legacy straight envelope
|
||||||
|
so this visible curb shape still contains all turning connectors. Approach road
|
||||||
|
surfaces terminate at the same cutback, so they cannot cover the junction
|
||||||
|
outline in 3D output.
|
||||||
|
|
||||||
|
The curve is accepted only when the support intersection is finite, the pair
|
||||||
|
belongs to different approaches, and the resulting ring remains valid and
|
||||||
|
contains all published connector coordinates. Otherwise the original straight
|
||||||
|
chord remains for that corner and the plan reports a mixed/fallback boundary.
|
||||||
|
|
||||||
|
Lane connectors remain a separate vehicle-path layer. This task changes only
|
||||||
|
the road/intersection outline and sidewalk-corner shape.
|
||||||
@@ -0,0 +1,2 @@
|
|||||||
|
{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"Native geometry and build-stage contracts."}
|
||||||
|
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"Intentional geometry output change validation."}
|
||||||
@@ -0,0 +1,7 @@
|
|||||||
|
# Implementation
|
||||||
|
|
||||||
|
1. Build a rounded junction boundary from ordered approach-edge records with
|
||||||
|
tangent support-line intersections and deterministic curve samples.
|
||||||
|
2. Expose boundary mode/provenance and preserve containment fallback.
|
||||||
|
3. Extend focused native-road tests for curved ordinary intersections.
|
||||||
|
4. Validate Nantaizi compile/check, workbench tests, and native 3D build.
|
||||||
@@ -0,0 +1,38 @@
|
|||||||
|
# Rounded native road junctions
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Replace the octagonal native junction outline with smooth, tangentially joined
|
||||||
|
road-edge corners for ordinary Nantaizi T and cross junctions.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Junction surface boundaries must connect adjacent approach carriageway edges
|
||||||
|
with a smooth outward curve rather than a straight octagonal chord.
|
||||||
|
- Sidewalk corner surfaces must use the same rounded boundary concept so road
|
||||||
|
and pedestrian geometry do not disagree visually.
|
||||||
|
- Preserve a deterministic straight-edge fallback and an explicit diagnostic
|
||||||
|
when a corner cannot be safely constructed.
|
||||||
|
- Do not change lane connector semantics or derive geometry from osm2streets.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [x] Ordinary cross/T fixtures generate rounded junction polygons with more
|
||||||
|
than the prior eight straight boundary vertices and `boundary_mode` records
|
||||||
|
the chosen style.
|
||||||
|
- [x] Connector containment remains valid and degenerate geometry falls back
|
||||||
|
without publishing self-intersecting polygons.
|
||||||
|
- [x] Nantaizi compile/check and native Blender/Cesium/preview succeed.
|
||||||
|
|
||||||
|
## Verification Record
|
||||||
|
|
||||||
|
- Native geometry and Workbench tests passed.
|
||||||
|
- Nantaizi native compile/check passed with `ok=true`.
|
||||||
|
- Native Blender/Cesium/preview verification was completed manually in a
|
||||||
|
working Blender environment.
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
|
||||||
|
- Lightweight tasks can remain PRD-only.
|
||||||
|
- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-rounded-junctions",
|
||||||
|
"name": "native-rounded-junctions",
|
||||||
|
"title": "Rounded native road junctions",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-17",
|
||||||
|
"completedAt": "2026-08-18",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": "08-13-native-road-compiler",
|
||||||
|
"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,51 @@
|
|||||||
|
# Design
|
||||||
|
|
||||||
|
## Provider Boundary
|
||||||
|
|
||||||
|
`build-area.js` will resolve a native provider by default. Native stages consume only OSM, native
|
||||||
|
road overrides, and `native-road/` outputs. Legacy `intermediates`, `reimport`, and osm2streets
|
||||||
|
Blender input remain behind explicit legacy selection and keep their existing output contract.
|
||||||
|
|
||||||
|
## Native Data Flow
|
||||||
|
|
||||||
|
```text
|
||||||
|
OSM + native-road-overrides.json
|
||||||
|
-> compile-native-roads.js
|
||||||
|
-> native-road/layers/*.geojson + compiled.json + traffic-signals.json
|
||||||
|
-> Blender generate_scene.py --native-road --traffic-signals
|
||||||
|
-> .blend
|
||||||
|
-> Cesium/package GLB + manifest + runtime/traffic-signals.json
|
||||||
|
-> preview HTML + optional native vehicle route
|
||||||
|
```
|
||||||
|
|
||||||
|
The native compiler is the sole authority for road geometry, lane semantics, intersection surfaces,
|
||||||
|
stop lines, and signal runtime. No native stage reads `geojsonDir` or legacy assembly files.
|
||||||
|
|
||||||
|
## Preview Route
|
||||||
|
|
||||||
|
Add a native route adapter that derives route segments from `compiled.json` model roads/endpoints and
|
||||||
|
native lane/connector geometry. If the native route cannot be built for a valid area, preview remains
|
||||||
|
usable without vehicles and records a warning; missing legacy osm2streets lane polygons is never a
|
||||||
|
hard failure on the native path.
|
||||||
|
|
||||||
|
## Package Runtime
|
||||||
|
|
||||||
|
The package stage will copy the native-road signal runtime into its staging runtime directory and
|
||||||
|
declare it in the package manifest. Preview receives the package-relative runtime URI. Legacy signal
|
||||||
|
runtime publication remains conditional on the legacy provider.
|
||||||
|
|
||||||
|
## Configuration And Compatibility
|
||||||
|
|
||||||
|
`roadProvider` defaults to `native`; native stages are the default stage set. QGIS config fields and
|
||||||
|
legacy stage aliases remain accepted for explicit migration/debug commands, but native manifests and
|
||||||
|
docs do not claim them as inputs.
|
||||||
|
|
||||||
|
The Workbench may continue to read an existing `geojsonDir` only for an explicitly labeled reference
|
||||||
|
layer and comparison counters. Those reads are optional, isolated from native compile state, and must
|
||||||
|
never become required inputs for `/api/state`, native editing, package publication, or preview.
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
The original QGIS/osm2streets branch baseline is tagged
|
||||||
|
`qgis-original-baseline-20260818` on `main`. Reverting the native-only work can therefore use the tag
|
||||||
|
or switch to `main`; no destructive cleanup of legacy scripts is required.
|
||||||
@@ -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,27 @@
|
|||||||
|
# Implementation Plan
|
||||||
|
|
||||||
|
1. Add native provider/default-stage contracts and explicit legacy provider routing.
|
||||||
|
2. Make package publication and stage manifests consume native runtime artifacts.
|
||||||
|
3. Replace preview's hard dependency on osm2streets lane/network/intersection files with a native
|
||||||
|
route adapter and optional-route behavior.
|
||||||
|
4. Audit Blender, Cesium, preview, diagnostics, and area config for native-path legacy reads; retain
|
||||||
|
only the Workbench's optional, clearly labeled osm2streets reference layer.
|
||||||
|
5. Update README/config/spec documentation and add dependency-boundary regression tests.
|
||||||
|
6. Run native-only tests with legacy directories absent, then run focused legacy compatibility tests.
|
||||||
|
7. Run area compile/check plus available Blender/Cesium/preview validation; record any environment-only
|
||||||
|
limitation without weakening native contracts.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:native-road
|
||||||
|
npm run test:traffic-signals
|
||||||
|
npm run test:road-workbench
|
||||||
|
npm run test:preview-assets
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run road:check -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
node --check scripts/build-area.js
|
||||||
|
```
|
||||||
|
|
||||||
|
The final gate must also exercise a native-only config/output directory without QGIS/osm2streets
|
||||||
|
intermediates and assert package/runtime/preview outputs.
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
# Complete native-only pipeline replacement
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Make the native road compiler the primary and complete production path. A normal build of an
|
||||||
|
area must generate Blender, Cesium/package, and preview outputs directly from OSM plus native
|
||||||
|
artifacts without installing or running QGIS, GDAL, or osm2streets.
|
||||||
|
|
||||||
|
The existing QGIS/osm2streets workflow remains available only as an explicit legacy/debug path and
|
||||||
|
an optional Workbench reference layer. It is protected by the `qgis-original-baseline-20260818` tag
|
||||||
|
on `main`.
|
||||||
|
|
||||||
|
## Confirmed Current Gaps
|
||||||
|
|
||||||
|
- `normalizeAreaConfig()` defaults `stages.intermediates` to true and `blender.roadProvider` to
|
||||||
|
`osm2streets`.
|
||||||
|
- `build-area.js` sends `intermediates` to `build-osm2streets-qgis.js` and `reimport` to GDAL/QGIS.
|
||||||
|
- Native Blender input exists, but `preview` still requires `osm2streets_web_out/lane_polygons.geojson`,
|
||||||
|
`network.json`, and `intersection_surface.geojson` for vehicle-route generation.
|
||||||
|
- Package/runtime publication still copies `outputs.<area>.trafficSignals` from the legacy GeoJSON
|
||||||
|
directory instead of the native-road runtime artifact.
|
||||||
|
- README, config templates, stage names, and manifest descriptions still present QGIS as the normal
|
||||||
|
workflow.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- R1: Native is the default road provider and default build stages do not invoke QGIS, GDAL, or
|
||||||
|
osm2streets.
|
||||||
|
- R2: Native build generates all required road, lane, marking, junction, stop-line, and traffic-signal
|
||||||
|
inputs consumed by Blender and preview; no native stage reads `osm2streets_web_out`.
|
||||||
|
- R3: Native package publication copies runtime traffic signals and any other runtime descriptors
|
||||||
|
from native-road outputs, with stable package-relative URIs.
|
||||||
|
- R4: Native preview route generation uses native lane/road topology and native intersection geometry,
|
||||||
|
or explicitly omits the optional vehicle route when native route data is unavailable; it must not
|
||||||
|
fail because legacy osm2streets files are absent.
|
||||||
|
- R5: QGIS/osm2streets stages remain callable only through an explicit legacy provider/stage selection
|
||||||
|
and are not part of native defaults or native manifests. Workbench may display their existing
|
||||||
|
GeoJSON as a clearly labeled reference/comparison layer, but native editing, compile, package, and
|
||||||
|
preview results must not depend on it.
|
||||||
|
- R6: Documentation and config templates describe native-only as the primary workflow and clearly
|
||||||
|
mark the legacy path as transitional/debug-only.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] A clean native-only area build succeeds with QGIS absent and no `osm2streets-js-node` runtime
|
||||||
|
call, producing `.blend`, package manifest/GLB, runtime traffic signals, and preview HTML.
|
||||||
|
- [ ] Native preview opens when `osm2streets_web_out/` is absent; optional vehicle cruise either uses
|
||||||
|
native route data or is omitted with a visible non-fatal diagnostic.
|
||||||
|
- [ ] Native package manifest contains runtime traffic-signal anchors sourced from
|
||||||
|
`native-road/traffic-signals.json`; disabled signals remain absent from runtime.
|
||||||
|
- [ ] Workbench edits survive save, native recompile, package publication, and preview reload without
|
||||||
|
QGIS or osm2streets files.
|
||||||
|
- [ ] Explicit legacy QGIS/osm2streets commands still pass their existing focused tests, but no longer
|
||||||
|
run when using native defaults.
|
||||||
|
- [ ] Workbench remains usable when the optional osm2streets reference directory is absent; only the
|
||||||
|
reference layer/comparison counters degrade to unavailable.
|
||||||
|
- [ ] Tests assert the native-only dependency boundary and the QGIS baseline tag is documented.
|
||||||
|
|
||||||
|
## Out Of Scope
|
||||||
|
|
||||||
|
- Reimplementing QGIS editing features in the native compiler beyond existing Workbench controls.
|
||||||
|
- Deleting legacy scripts or historical output files in this task; they remain rollback/debug tooling.
|
||||||
|
- Changing Blender/Cesium visual semantics unrelated to removing the input dependency.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-only-pipeline-replacement",
|
||||||
|
"name": "native-only-pipeline-replacement",
|
||||||
|
"title": "Complete native-only pipeline replacement",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-18",
|
||||||
|
"completedAt": "2026-08-18",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||||
@@ -0,0 +1,70 @@
|
|||||||
|
# Design
|
||||||
|
|
||||||
|
## Authority And Boundaries
|
||||||
|
|
||||||
|
The native compiler remains the only road authority. The existing traffic-signal runtime remains the
|
||||||
|
only signal authority. The new feature adds a route/simulation layer beside those artifacts; it does
|
||||||
|
not alter signal geometry, phase grouping, or Blender static assets.
|
||||||
|
|
||||||
|
```text
|
||||||
|
native-road/compiled.json + native-road/layers/*
|
||||||
|
-> native route compiler
|
||||||
|
-> _preview/<area>-traffic-simulation.json
|
||||||
|
-> Cesium preview runtime
|
||||||
|
|
||||||
|
package/runtime/traffic-signals.json
|
||||||
|
-> signal phase clock + stop events
|
||||||
|
```
|
||||||
|
|
||||||
|
The descriptor is intentionally package-adjacent, not embedded in the GLB. A consumer can copy the
|
||||||
|
package and descriptor to another platform and reproduce the simulation without running Node.
|
||||||
|
|
||||||
|
## Descriptor Contract
|
||||||
|
|
||||||
|
Schema: `native-preview-traffic-simulation/v1`.
|
||||||
|
|
||||||
|
Required top-level fields:
|
||||||
|
|
||||||
|
- `areaId`, `coordinateSystem` (`WGS84` route coordinates, `ENU` model placement), `generatedAt`
|
||||||
|
- `source` with relative artifact references and SHA-256 records
|
||||||
|
- `settings` with speed, acceleration, deceleration, reaction time, vehicle length, and minimum gap
|
||||||
|
- `routes[]` with ordered WGS84 coordinates, cumulative distances, connector/maneuver IDs, and
|
||||||
|
`stops[]`
|
||||||
|
- `signals[]` copied by stable `signal_uid` from the runtime contract, including phase group and
|
||||||
|
stop-line association; no regenerated pose fields
|
||||||
|
- `migration` describing schema version, coordinate conversion, update-loop expectations, and
|
||||||
|
compatibility notes
|
||||||
|
|
||||||
|
The descriptor is deterministic for the same OSM, overrides, native compiler version, and settings.
|
||||||
|
|
||||||
|
## Route Construction
|
||||||
|
|
||||||
|
Use native directional roads and published connector geometry. Build a small number of deterministic
|
||||||
|
closed demonstration routes that cross real connectors and retain lane/road IDs. Route generation
|
||||||
|
must reject routes with missing geometry or disabled connectors and write structured diagnostics.
|
||||||
|
Native stop lines are matched by `road_id`/`lane_id` where available, with a bounded geometric
|
||||||
|
fallback recorded in the stop record. No fixed-width or legacy polygon fallback is allowed.
|
||||||
|
|
||||||
|
## Browser Simulation
|
||||||
|
|
||||||
|
Keep the existing signal phase functions and `signalData` payload. Replace the current per-vehicle
|
||||||
|
independent distance advance with a shared simulation state:
|
||||||
|
|
||||||
|
- each vehicle has route distance, speed, desired speed, status, and active stop reason;
|
||||||
|
- signal stop constraints are evaluated before the native stop line for red/yellow phases;
|
||||||
|
- leader constraints are evaluated on the same route and wrap around the loop;
|
||||||
|
- acceleration/deceleration clamps advance toward the minimum of desired speed, signal limit, and
|
||||||
|
leader-safe speed;
|
||||||
|
- vehicle position and orientation remain Cesium callback properties, with no per-frame allocation
|
||||||
|
of heavyweight Cesium objects;
|
||||||
|
- incident-card behavior remains local to each vehicle and must not mutate the descriptor or package.
|
||||||
|
|
||||||
|
Diagnostics expose route count, signal count, stopped vehicles, and queue length in the existing
|
||||||
|
preview diagnostics panel.
|
||||||
|
|
||||||
|
## Migration And Rollback
|
||||||
|
|
||||||
|
Document the descriptor, runtime signal schema, coordinate conversion, and a reference update loop in
|
||||||
|
`docs/native-preview-traffic-simulation.md`. Include a JSON example and a consumer checklist. Legacy
|
||||||
|
preview route files remain readable only through the existing legacy provider path; native generation
|
||||||
|
must not depend on them. Removing the new descriptor restores the existing no-cruise native preview.
|
||||||
@@ -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,37 @@
|
|||||||
|
# Implementation Plan
|
||||||
|
|
||||||
|
1. Add a native route compiler module that consumes `native-road/compiled.json` and native layers,
|
||||||
|
emits `native-preview-traffic-simulation/v1`, and records source hashes and migration metadata.
|
||||||
|
2. Wire native preview generation to write the descriptor and keep legacy osm2streets route
|
||||||
|
generation unchanged.
|
||||||
|
3. Extend the browser preview with shared deterministic vehicle state, signal stop constraints,
|
||||||
|
leader following, queue diagnostics, and graceful empty-route behavior.
|
||||||
|
4. Preserve the existing signal phase, `signal_uid`, pose, dynamic lens, countdown, disabled-signal,
|
||||||
|
and incident-card contracts; add focused regression tests for each boundary.
|
||||||
|
5. Add `docs/native-preview-traffic-simulation.md` with schema, example, coordinate rules, update
|
||||||
|
loop, migration checklist, and rollback notes.
|
||||||
|
6. Run focused Node tests, native compile/check, a native build with no legacy directory, and browser
|
||||||
|
preview validation in the available Blender/Cesium environment.
|
||||||
|
|
||||||
|
## Validation Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node --check scripts/lib/native-preview-traffic-simulation.js
|
||||||
|
node --check scripts/build-area.js
|
||||||
|
npm run test:native-road
|
||||||
|
npm run test:traffic-signals
|
||||||
|
npm run test:preview-assets
|
||||||
|
npm run test:native-preview-traffic
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run road:check -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender,cesium,compress,package,preview
|
||||||
|
```
|
||||||
|
|
||||||
|
## Risk Controls
|
||||||
|
|
||||||
|
- Do not change `scripts/lib/traffic-signals.js` geometry or phase semantics unless a test proves a
|
||||||
|
migration bug; prefer adapter code.
|
||||||
|
- Do not add route data to the static package manifest; it belongs beside `_preview/` and is optional.
|
||||||
|
- If native route generation produces no valid route, emit a valid descriptor with diagnostics and
|
||||||
|
keep preview usable.
|
||||||
|
- Keep all route and simulation math unit-testable without Cesium.
|
||||||
@@ -0,0 +1,38 @@
|
|||||||
|
# Native preview traffic simulation and migration contract
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Extend the native road compiler preview with a deterministic, portable vehicle traffic demonstration that consumes native road topology and the already-validated traffic-signal runtime. The result must be useful as a visual validation tool and as a migration reference for Cesium, Blender, or another platform consuming the generated area package.
|
||||||
|
|
||||||
|
## Confirmed Baseline
|
||||||
|
|
||||||
|
- Native road compilation is the production authority; QGIS/osm2streets is not a runtime input.
|
||||||
|
- The previous traffic-signal work is the source of truth and must remain compatible: deterministic `signal_uid`, `phase_group`, `mast_heading_deg`, `face_heading_deg`, stop-line anchors, shared `pose.*`, dynamic lens/countdown assets, and disabled-signal filtering.
|
||||||
|
- Existing browser preview already has signal phase timing, signal visualization, route stop matching, vehicle incident cards, and a missing-route fallback. Native preview currently omits the route.
|
||||||
|
- Native road output contains compiled roads/connectors and `vehicle_stop_lines.geojson`; the native package contains `runtime/traffic-signals.json`.
|
||||||
|
- The feature is preview-level deterministic behavior, not a legal navigation or microscopic traffic simulator.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- R1: Generate a native route artifact from `native-road/compiled.json` and native layer geometry; it must not read `osm2streets_web_out`, QGIS files, or legacy route files.
|
||||||
|
- R2: Preserve and consume the existing traffic-signal contract without deriving a second signal layout in the browser.
|
||||||
|
- R3: Vehicles must stop before a red/yellow signal at the native stop line, resume on green, and expose the active stop reason in preview diagnostics.
|
||||||
|
- R4: Multiple vehicles on the same route must maintain a configurable minimum gap; a stopped front vehicle must cause following vehicles to decelerate and queue rather than overlap it.
|
||||||
|
- R5: Route, signal, vehicle, stop-event, and following-distance data must be written as versioned, package-adjacent JSON with stable ENU/WGS84 and migration metadata. Another platform must be able to consume the artifact without executing the Node compiler.
|
||||||
|
- R6: The browser preview must degrade gracefully when there are no valid routes or signals; the primary scene remains usable and diagnostics explain the missing optional capability.
|
||||||
|
- R7: Documentation must describe the data flow, schemas, coordinate conventions, signal identity, stop-line association, update loop, and migration/rollback guidance.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] Native build emits a versioned route/traffic-simulation descriptor under the area output and preview loads it without any legacy directory present.
|
||||||
|
- [ ] At least one route crosses a native connector and contains a native stop-line association.
|
||||||
|
- [ ] A red/yellow phase visibly stops a vehicle before the stop line; green releases it.
|
||||||
|
- [ ] Two or more vehicles never overlap and maintain the configured minimum gap while cruising and while queued at a signal.
|
||||||
|
- [ ] Disabled native signals are absent from runtime control and do not create vehicle stops.
|
||||||
|
- [ ] Preview diagnostics report route count, signal count, stopped vehicles, queue length, and the active simulation descriptor version.
|
||||||
|
- [ ] Migration documentation and focused tests allow another consumer to reproduce route, signal, stopping, and gap behavior from generated assets alone.
|
||||||
|
- [ ] Existing traffic-signal tests and native road tests remain green; legacy provider behavior is unchanged.
|
||||||
|
|
||||||
|
## Decided Scope
|
||||||
|
|
||||||
|
- Simulation fidelity: MVP is a deterministic preview simulation with configurable speed, acceleration/deceleration, reaction time, and minimum gap. A full lane-changing, collision, priority, and multi-intersection traffic engine is deferred.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-preview-traffic-simulation",
|
||||||
|
"name": "native-preview-traffic-simulation",
|
||||||
|
"title": "Native preview traffic simulation and migration contract",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-18",
|
||||||
|
"completedAt": "2026-08-24",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
# Design
|
||||||
|
|
||||||
|
## Source Of Truth And Migration
|
||||||
|
|
||||||
|
The native compiler owns a versioned area-local signal model and override
|
||||||
|
artifact. It is generated from OSM controls and native geometry inputs, then
|
||||||
|
edited by the Workbench without QGIS. The existing
|
||||||
|
`traffic_signal_assemblies.geojson` is a migration adapter: it can be imported
|
||||||
|
into the native model and exported for legacy QGIS/reimport workflows, but a
|
||||||
|
native compile never requires it to exist.
|
||||||
|
|
||||||
|
The existing `buildTrafficSignalFeatures()` and validation functions remain the
|
||||||
|
compatibility implementation for initial generation and import/export. Imported
|
||||||
|
features retain their legacy `signal_uid` where valid; newly generated native
|
||||||
|
features use the same deterministic identity rule so downstream runtime IDs do
|
||||||
|
not fork.
|
||||||
|
|
||||||
|
## Workbench API And Editing
|
||||||
|
|
||||||
|
`GET /api/state` adds the normalized native signal model, source control
|
||||||
|
metadata, migration provenance, and derived runtime signal records. A signal
|
||||||
|
edit is represented as an atomic replacement of the validated native signal
|
||||||
|
override artifact through a dedicated signal save endpoint. A separate import
|
||||||
|
or export action handles the legacy QGIS collection; road overrides remain in
|
||||||
|
their existing file and schema.
|
||||||
|
|
||||||
|
The browser uses stable `signal_uid` values. It supports:
|
||||||
|
|
||||||
|
- generate: choose an OSM traffic-signal control and arm, then create the
|
||||||
|
deterministic assembly using the existing generator contract;
|
||||||
|
- move: update the Point coordinates while retaining stop-line/source fields;
|
||||||
|
- rotate: update `heading_deg` with normalized degrees;
|
||||||
|
- delete: remove the assembly from the editable collection;
|
||||||
|
- edit enabled state, display ID, mast reach, z offset, and phase group.
|
||||||
|
|
||||||
|
Every save validates uniqueness, identity, finite geometry, source references,
|
||||||
|
and field ranges before an atomic write. Deleted features are absent from the
|
||||||
|
runtime output; disabled features remain in the editable/QGIS layer but are
|
||||||
|
omitted by `buildTrafficSignalsFromFeatures()`.
|
||||||
|
|
||||||
|
## Delivery Flow
|
||||||
|
|
||||||
|
The native road compile result includes signal assemblies and derived runtime
|
||||||
|
metadata without adding them to road geometry layers. Native Blender/Cesium
|
||||||
|
stages consume `traffic_signals.json` and dynamic GLB inputs generated directly
|
||||||
|
from the native model. The legacy QGIS adapter may materialize the old GeoJSON,
|
||||||
|
but it is not in the native build's critical path.
|
||||||
|
|
||||||
|
## Compatibility And Rollback
|
||||||
|
|
||||||
|
QGIS reimport continues to read/export the compatibility GeoJSON while the
|
||||||
|
legacy path remains unchanged. If native signal editing fails validation, the
|
||||||
|
previous atomic native override remains in place and the user receives a
|
||||||
|
field-level error. Rollback is selecting the legacy provider or exporting the
|
||||||
|
last native state to the QGIS adapter.
|
||||||
@@ -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,31 @@
|
|||||||
|
# Implementation Plan
|
||||||
|
|
||||||
|
1. Define the native signal model/override artifact and migration adapter;
|
||||||
|
reuse existing generation, validation, and deterministic signal UID rules.
|
||||||
|
2. Add QGIS import/export commands that translate
|
||||||
|
`traffic_signal_assemblies.geojson` to/from the native artifact without
|
||||||
|
making native compile depend on QGIS.
|
||||||
|
3. Extend native compile/workbench state to expose signal assemblies, OSM
|
||||||
|
controls/arms, and derived runtime provenance.
|
||||||
|
4. Add validated atomic signal save operations for generate, move, rotate,
|
||||||
|
delete, and field edits; preserve legacy ID compatibility.
|
||||||
|
5. Add Workbench map styling, selection, editing controls, dirty state, save,
|
||||||
|
compile/reload, and clear error handling for signal assemblies.
|
||||||
|
6. Ensure native Blender/Cesium/preview stages consume runtime signal data
|
||||||
|
generated from the native model, while legacy stages remain compatible.
|
||||||
|
7. Add focused traffic-signal, Workbench, migration, and cross-layer round-trip tests;
|
||||||
|
run the existing legacy traffic-signal and preview suites.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:traffic-signals
|
||||||
|
npm run test:preview-assets
|
||||||
|
npm run test:road-workbench
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run road:check -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Manual acceptance must cover native-only generate/move/rotate/delete -> save ->
|
||||||
|
recompile -> runtime JSON and preview, plus QGIS import/export compatibility;
|
||||||
|
disabled signals must be omitted from runtime output.
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
# Native traffic signal parity with QGIS
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Move traffic-signal ownership from the QGIS editing chain into the native road
|
||||||
|
compiler and Workbench. Existing QGIS signal assemblies remain import/export
|
||||||
|
compatibility data during migration, but native overrides become the long-term
|
||||||
|
source for generation, editing, and Blender/Cesium/preview delivery.
|
||||||
|
|
||||||
|
## Confirmed Facts
|
||||||
|
|
||||||
|
- QGIS currently edits `traffic_signal_assemblies.geojson`; this is the
|
||||||
|
migration input/output contract, not the desired long-term authority.
|
||||||
|
- `scripts/reimport-gpkg.js` validates and reimports that legacy layer.
|
||||||
|
- `scripts/build-area.js` currently derives runtime `traffic_signals.json` from
|
||||||
|
the edited assemblies; the native path must replace this dependency.
|
||||||
|
- Existing native road layers do not read traffic-signal artifacts. Historical
|
||||||
|
native Cesium work intentionally omitted signal runtime assets.
|
||||||
|
- Stable signal identity and editable fields already include `signal_uid`,
|
||||||
|
enabled state, source/control/approach IDs, arm direction, pose, mast reach,
|
||||||
|
and phase-group/runtime data.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- R1: Native compile/workbench must own a versioned area-local signal model and
|
||||||
|
override artifact, with an explicit one-time/import compatibility path from
|
||||||
|
existing QGIS assemblies.
|
||||||
|
- R2: Workbench state must expose signal provenance and the existing editable
|
||||||
|
signal fields using stable IDs, and support generating, moving, rotating,
|
||||||
|
and deleting signal assemblies.
|
||||||
|
- R3: Native compile and preview delivery must generate runtime signal data
|
||||||
|
directly from the native model, preserving enabled/disabled state, arm
|
||||||
|
direction/pose, and phase-group data without requiring QGIS.
|
||||||
|
- R4: A compatibility adapter must import/export the existing QGIS assembly
|
||||||
|
format during migration and preserve legacy signal IDs where possible.
|
||||||
|
|
||||||
|
## Scope Boundary
|
||||||
|
|
||||||
|
- Native signal model and overrides are the long-term source of truth.
|
||||||
|
- QGIS GeoJSON/GeoPackage support is transitional compatibility only; do not
|
||||||
|
make native compile depend on QGIS or regenerate native edits from QGIS.
|
||||||
|
- Do not redesign signal geometry, timing logic, or vehicle behavior in this
|
||||||
|
task.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] A native compile/reopen round trip preserves edited signal assemblies,
|
||||||
|
stable IDs, enabled state, and provenance without QGIS running.
|
||||||
|
- [ ] The Road Workbench can generate, inspect, move, rotate, and delete signal
|
||||||
|
assemblies, then save durable edits without breaking QGIS reimport.
|
||||||
|
- [ ] Native Blender/Cesium/preview consume runtime signal data generated from
|
||||||
|
the native model, including disabled signals being omitted from runtime.
|
||||||
|
- [ ] QGIS import/export compatibility and legacy build stages continue to
|
||||||
|
pass while the migration adapter exists.
|
||||||
|
- [ ] Nantaizi has documented native-only and QGIS-imported round trips.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "native-traffic-signal-parity",
|
||||||
|
"name": "native-traffic-signal-parity",
|
||||||
|
"title": "Align native traffic signals with QGIS",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-18",
|
||||||
|
"completedAt": "2026-08-18",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "feature/native-road-compiler",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": "08-13-native-road-compiler",
|
||||||
|
"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,57 @@
|
|||||||
|
# Technical Design
|
||||||
|
|
||||||
|
## Boundary
|
||||||
|
|
||||||
|
The native compiler remains authoritative for OSM road identity, directed lanes,
|
||||||
|
connections, traffic signals, stop lines, and preview routes. A reference layer is
|
||||||
|
an optional geometry-calibration input consumed before junction surface publication.
|
||||||
|
|
||||||
|
## Proposed Flow
|
||||||
|
|
||||||
|
```text
|
||||||
|
optional reference GeoJSON (GCJ-02)
|
||||||
|
-> validate schema and coordinate bounds
|
||||||
|
-> GCJ-02 to WGS84 conversion
|
||||||
|
-> associate reference footprint with an OSM junction node
|
||||||
|
-> classify geometry by observable shape, not opaque vendor type alone
|
||||||
|
-> derive bounded junction-shape parameters
|
||||||
|
-> native compiler creates surface/connectors as usual
|
||||||
|
-> diagnostics compare generated geometry with reference
|
||||||
|
```
|
||||||
|
|
||||||
|
The first production validation keeps the reference overlay/diagnostic, then enables a
|
||||||
|
bounded `cross` junction template for explicitly configured references. Connector
|
||||||
|
endpoints and movement enumeration still come from the native model. T and complex
|
||||||
|
junctions remain on the existing algorithm until their templates are separately validated.
|
||||||
|
|
||||||
|
## Input Contract
|
||||||
|
|
||||||
|
Use an optional area-level reference configuration rather than a hard-coded filename.
|
||||||
|
The sample points to `inputs/osm/珠山湖大道(枫树二路)口.geojson`, declares `GCJ-02`,
|
||||||
|
and identifies the target through OSM node `8005332807` or a stable spatial/name match.
|
||||||
|
The file is not assumed to contain a CRS member; the configured source CRS is required.
|
||||||
|
|
||||||
|
## Geometry Safety
|
||||||
|
|
||||||
|
- Convert all reference coordinates to WGS84 before distance/overlap tests.
|
||||||
|
- Reject malformed or non-finite coordinates and references outside the OSM bounds plus a
|
||||||
|
bounded tolerance.
|
||||||
|
- Never let a reference polygon create a movement, lane, signal, or stop-line record.
|
||||||
|
- Keep a fallback path to the current `compileGeometry()` junction algorithm.
|
||||||
|
|
||||||
|
## Compatibility And Rollback
|
||||||
|
|
||||||
|
No-reference configs and existing output schemas remain unchanged. The experiment can be
|
||||||
|
disabled by omitting the reference section or setting it disabled. Generated diagnostics
|
||||||
|
must record source file hash, conversion mode, matched OSM node, and whether fallback was used.
|
||||||
|
No source reference file is rewritten.
|
||||||
|
|
||||||
|
## Open Technical Work
|
||||||
|
|
||||||
|
1. Select the smallest reusable geometry parameter set from the sample (approach cutback,
|
||||||
|
corner radius/rounding, island/marking envelopes, and tolerances).
|
||||||
|
2. Implement and test GCJ-02 conversion independently from compiler logic.
|
||||||
|
3. Compare the sample against all native junctions near the converted footprint before any
|
||||||
|
production surface override is enabled.
|
||||||
|
4. Add topology classification and template dispatch; only cross is enabled in this validation.
|
||||||
|
5. Preserve native connectors and controls while replacing only the bounded junction surface geometry.
|
||||||
@@ -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 @@
|
|||||||
|
# Validation Implementation Plan
|
||||||
|
|
||||||
|
进度标记于 2026-08-21。
|
||||||
|
|
||||||
|
1. [x] Add a read-only reference inspection utility or library helper that validates GeoJSON,
|
||||||
|
converts GCJ-02 to WGS84, computes bounds/center, and associates the sample with OSM node
|
||||||
|
`8005332807`. — `scripts/lib/gaode-junction-reference.js` + `scripts/inspect-junction-reference.js`
|
||||||
|
2. [x] Add focused tests for coordinate conversion, malformed input rejection, spatial association,
|
||||||
|
and the no-reference fallback. — `npm run test:gaode-junction-reference`
|
||||||
|
3. [x] Add a diagnostic comparison between the reference footprint and native
|
||||||
|
`intersection_surface.geojson`, including center offset, envelope overlap, and approach headings.
|
||||||
|
— 复杂路口的面写在 `road_surface.geojson`(`complex_part`)而非 `intersection_surface`,
|
||||||
|
原实现匹配不到、恒返回 `nativeIntersection: null`。已扩展为可回落到复杂路口簇
|
||||||
|
(新增 `--native-road-surface` / `--cluster-id`,schema 升至 v2)。
|
||||||
|
4. [x] Add a reference-backed, parameterized junction template and dispatch it only for
|
||||||
|
explicitly enabled samples. — 实际实现为 `complex-junction-v1`,非原计划的 cross 模板,
|
||||||
|
范围变更见 prd.md「Scope Drift」。
|
||||||
|
5. [x] Preserve connector, movement, signal, and stop-line generation; validate containment against
|
||||||
|
the new surface. — A/B 实测通过,数据见 prd.md「Verification Log」。
|
||||||
|
6. [x] Run native-road, preflight, preview-traffic, and package-contract tests, plus the sample
|
||||||
|
comparison. Inspect the generated overlay/diagnostic manually.
|
||||||
|
— 2026-08-21 全绿:`test:gaode-junction-reference`、`test:native-road`、`test:road-workbench`、
|
||||||
|
`test:preflight`、`test:native-preview-traffic`、`test:package-contract`、`test:traffic-signals`,
|
||||||
|
外加 `road:check` → `ok: true, errors: []`。人工视觉确认仍待用户。
|
||||||
|
7. [x] Stop at validation. Do not commit,
|
||||||
|
and do not modify the source OSM or reference GeoJSON. — 未 commit;参考 GeoJSON 未改;
|
||||||
|
源 OSM 有改动但来自人工 JOSM 编辑,非管线写入。
|
||||||
|
|
||||||
|
## 本次会话追加的修复(2026-08-21)
|
||||||
|
|
||||||
|
- 车道中心线与车道标线越过斑马线:`compileLaneCenterlines` 现接收模板已产出的斑马线/停止线,
|
||||||
|
新增 `trimLaneOutsideControls`(按到路口中心的半径定向后再裁剪,因为车道几何两种朝向都存在)。
|
||||||
|
拓扑几何 `coordinates` 保持完整,仅裁剪发布几何与标线源几何。
|
||||||
|
实测越线要素 20 → 0,分隔线越界 2 → 0,connector 356 / movement 370 前后一致。
|
||||||
|
- 新增诊断 `complex-junction-configured-radius-ignored`、`lane-centerline-fully-inside-control`。
|
||||||
|
- 删除死函数 `clusterApproachRing`。
|
||||||
|
- **复杂路口人行道转角**(`complex-junction.js`):直条带被裁在簇边界后,相邻两臂的步行带
|
||||||
|
各自留一个断头,中间整个楔形无覆盖。现沿圆角已定义的路缘补一条 2 m 宽转角带。
|
||||||
|
- 复用同一函数作用域内已算好的 `curve` / `tangents` / `edges` / `apex`,不重新拟合曲线
|
||||||
|
- 新增 `armCarriesSidewalk`(按臂的外向方向翻转道路自身的 `sidewalkLeft/Right`)、
|
||||||
|
`edgeRunToRadius`、`offsetPolylineAwayFromCenter`、`ringSelfIntersects`
|
||||||
|
- 经 `islands` 通道并入 `generatedComplexSidewalks`
|
||||||
|
- 自交或几何无效时跳过并报 `complex-junction-sidewalk-corner-fallback`,不硬塞坏几何
|
||||||
|
- 实测:人行道要素 7 → 8;生成角 1(平分线 286°,241°→331°,57 顶点);无自交;
|
||||||
|
与两侧条带均相接;面积采样 331 点中 0 点落在车行道内
|
||||||
|
- **限制**:全区 139 条路仅 3 条带人行道,4 个角中只有 286° 两侧齐备,
|
||||||
|
其余 3 个角当前不产出,缺少验证样本
|
||||||
|
|
||||||
|
## Rollback Points
|
||||||
|
|
||||||
|
- Delete/disable the optional reference configuration to restore the default native path.
|
||||||
|
- Remove only the reference diagnostic output; existing native-road outputs remain authoritative.
|
||||||
|
- Do not overwrite existing layers until the comparison is accepted.
|
||||||
@@ -0,0 +1,110 @@
|
|||||||
|
# Parameterize junction geometry with optional Gaode reference
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
验证一种通用的、参数化的路口几何生成范式:借鉴高德路口 GeoJSON 的规整边界和标线组织方式,
|
||||||
|
但保持 OSM/native compiler 对道路身份、连接关系、车道可行驶性、信号和停止线的权威性。
|
||||||
|
当前阶段先做一个可回滚的生产几何验证,不提交代码或产物。
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- R1: native 路口在没有参考数据时行为不变,现有 OSM/native 输出仍是默认路径。
|
||||||
|
- R2: 支持可选的路口参考输入,至少记录输入路径、坐标来源(GCJ-02)和目标 OSM 路口关联方式。
|
||||||
|
- R3: 参考输入先转换为 WGS84;禁止将 GCJ-02 坐标直接与 OSM/native 几何叠加。
|
||||||
|
- R4: 参考数据只允许影响路口面的规整化参数、边界形态和标线布局;不得改变 OSM 道路、车道、connector、
|
||||||
|
signal_uid、停止线归属或车辆路线拓扑。
|
||||||
|
- R5: 不机械复制高德 feature 的 `type=1..5`;先建立可审计的几何类别映射或只使用其可验证的形态特征。
|
||||||
|
- R6: 以“珠山湖大道(枫树二路)”路口作为验证样本,输出参考前后对比、偏差诊断和可回滚结果。
|
||||||
|
- R6.1: 生成器按路口拓扑选择模板,至少区分 cross、T 和复杂/多臂路口;不能用一个固定几何参数机械覆盖所有路口。
|
||||||
|
- R6.2: 首个生产几何验证只启用 cross 模板,利用参考样本校准 cutback、圆角和进口过渡;T/复杂路口先保留现有 native 行为并记录诊断。
|
||||||
|
- R6.3: 模板生成的路口面必须由 OSM/native 道路宽度、方向和车道结构驱动;高德几何只用于校准参数或对比,不直接复制其 feature。
|
||||||
|
- R7: 参考文件缺失、坐标转换失败、无法关联 OSM 路口或几何越界时,构建必须回退默认 native 算法并给出诊断,
|
||||||
|
不得静默覆盖生产几何。
|
||||||
|
- R8: 保持当前阶段 manifest、GLB/package 契约和无参考区域的 parity 行为不变。
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
> 措辞修订说明见文末「Scope Drift」。勾选项均为 2026-08-21 实测,证据记录在「Verification Log」。
|
||||||
|
|
||||||
|
- [x] 不配置参考输入时,现有 native-road 测试和样本区域输出保持默认行为。
|
||||||
|
- [x] 配置枫树二路参考后,能稳定关联 OSM node `8005332807`,并生成 WGS84 参考诊断。
|
||||||
|
- [x] 参考几何与 native 路口的叠加结果可检查:路口中心、边界、进口方向有数值和 SVG 记录。
|
||||||
|
- [x] 参考模式不改变 OSM 衍生的 connector、车道连接、信号或停止线集合;模板只新增自有
|
||||||
|
`complex-*` 命名空间要素。(原措辞「不会新增或删除…停止线」严于 R4 本意,已修订)
|
||||||
|
- [x] 参考模式失败时有明确 warning,并成功回退默认 native 几何。
|
||||||
|
- [x] 模板生成的路口面视觉上接近高德参考。connector / 信号 / 停止线集合一致性已实测通过;
|
||||||
|
视觉接近度由用户 2026-08-21 在工作台确认(「基本 ok」),其间提出的人行道转角缺口已修复并复核通过。
|
||||||
|
- [x] 无参考路口继续走默认 native 几何,不被模板误套。
|
||||||
|
- [x] 验证产物写入区域输出目录,未执行 git commit。(源 OSM 有改动,但来自人工 JOSM 编辑,
|
||||||
|
非管线写入;原措辞未区分这两者,已修订)
|
||||||
|
|
||||||
|
## Scope Drift(2026-08-21 记录)
|
||||||
|
|
||||||
|
R6.2 原定「首个生产几何验证只启用 cross 模板;T/复杂路口先保留现有 native 行为」。
|
||||||
|
实际实现走的是 `complex-junction-v1`,对枫树二路 4 节点簇做整体路口面、斑马线、停止线、
|
||||||
|
角部安全岛和圆角生成。范围已越过 R6.2,本文档据实修订,R6.2 视为被本次决策取代。
|
||||||
|
cross 模板(`cross-v1` / `cross-cluster-v1`)代码路径仍在,未被删除。
|
||||||
|
|
||||||
|
## Verification Log(2026-08-21)
|
||||||
|
|
||||||
|
参考模式 A/B 对照(同一 OSM 输入,`junctionTemplates.enabled` 开/关,独立 outputRoot):
|
||||||
|
|
||||||
|
| 指标 | ON | OFF | 判定 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| connector 要素 | 356 | 356 | 集合逐一相同,无新增/缺失 |
|
||||||
|
| movement / published | 370 / 356 | 370 / 356 | 一致 |
|
||||||
|
| connection | 215 | 215 | 一致 |
|
||||||
|
| 信号 uid 集合 | 20 | 20 | 集合完全一致 |
|
||||||
|
| 普通斑马线 `native-road-crosswalk/v1` | 6 | 6 | 一致 |
|
||||||
|
| 模板新增 `complex-crosswalk` | 128 | 0 | 模板自有命名空间 |
|
||||||
|
| 模板新增 `complex-corner-crosswalk` | 24 | 0 | 同上 |
|
||||||
|
| 模板新增 `complex-stop-line` | 4 | 0 | 同上 |
|
||||||
|
| 预览车道 `cluster-approach-lane` | 24 | 0 | 同上 |
|
||||||
|
|
||||||
|
参考关联与叠加(`npm run reference:junction`):
|
||||||
|
|
||||||
|
- 匹配方式 `node-id`,命中 `8005332807`,参考中心到节点 **8.98 m**
|
||||||
|
- 匹配到 `complex-cluster` = `zhushanhu-fengshu-complex`,13 个要素
|
||||||
|
- native core 半径 **24 m**(配置 `coreRadiusMeters: 28`),进口 4 / 车行道 8,
|
||||||
|
进口朝向 `[-118.5, -28, 62.2, 151.9]`
|
||||||
|
- 已知口径差异:检查工具用参考文件**全部** feature 算 bounds(约 380×330 m,含长引道),
|
||||||
|
而 `readReferenceCalibration` 只取 `type ∈ [1,2,3,4]` 的子集。两者不同量级,
|
||||||
|
故 bbox IoU(0.070)当前**不是**可用的质量指标,仅中心偏差和朝向可比。
|
||||||
|
|
||||||
|
失败回退(`referenceFile` 指向不存在路径):
|
||||||
|
|
||||||
|
- 编译成功不抛错;诊断由 `complex-junction-reference-calibrated` 降级为 `complex-junction-generated`
|
||||||
|
- connector 356 / movement 370 不变
|
||||||
|
- 该路径下 `lane-centerline-fully-inside-control` 触发 10 次:无参考时 coreRadius 仅 14.56 m,
|
||||||
|
10 条车道整体落在控制带内,回退为未裁剪发布。非回归(改动前同样未裁剪),但属已知限制。
|
||||||
|
|
||||||
|
非簇路口未受模板影响(A/B `intersection_surface`):
|
||||||
|
|
||||||
|
| | ON | OFF |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 普通路口面总数 | 41 | 45 |
|
||||||
|
| 簇成员节点出现次数 | 0(预期 0) | 4(模板关闭时预期 4) |
|
||||||
|
| 非簇节点(41 个) | — | 与 ON 逐点几何完全一致,无增无缺 |
|
||||||
|
| 模板 `complex_part` 要素 | 13,全部归属唯一簇 `zhushanhu-fengshu-complex` | 0 |
|
||||||
|
|
||||||
|
结论:模板严格限定在 `nodeIds` 列表内,无外溢。
|
||||||
|
|
||||||
|
## Known Gaps(2026-08-21)
|
||||||
|
|
||||||
|
1. `way/858770823:segment/2`(长 19.2 m,远端为 service 路口 `8613058676`)被 `native-road.js`
|
||||||
|
的 cluster 丢弃判据误伤,整段无路面,该节点周边 25×25 m 内 25.8% 露底。
|
||||||
|
判据应从「远端在 outerRadius 内」改为「远端也是 cluster 成员节点」,实测该判据分界干净。
|
||||||
|
**用户 2026-08-21 明确暂缓,未修改。**
|
||||||
|
2. `coreRadiusMeters` 在有参考文件时不参与计算(被 calibration 覆盖并 clamp 到 24)。
|
||||||
|
已加诊断 `complex-junction-configured-radius-ignored` 使其可见,行为未改。
|
||||||
|
3. `approachLengthMeters` 对 `complex-junction-v1` 无效(仅 `cross-v1` / `cross-cluster-v1` 使用)。
|
||||||
|
死函数 `clusterApproachRing` 已删除。
|
||||||
|
4. 无参考路径下普通停止线为 0(`crossing-no-safe-stop-line` 告警 1 条),先于本任务存在。
|
||||||
|
|
||||||
|
|
||||||
|
## Constraints And Deferred Scope
|
||||||
|
|
||||||
|
- OSM WGS84 与 native 拓扑是交通语义的单一事实源。
|
||||||
|
- 高德参考暂不作为完整道路网络输入,也不直接替代 road surface 或 connector 几何。
|
||||||
|
- 暂不定义所有高德 `type` 值的业务语义;先验证几何范式和校准边界。
|
||||||
|
- 暂不提交代码、配置或生成产物;本阶段完成后由用户决定是否进入正式实现。
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "gaode-junction-reference",
|
||||||
|
"name": "gaode-junction-reference",
|
||||||
|
"title": "Parameterize junction geometry with optional Gaode reference",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-19",
|
||||||
|
"completedAt": "2026-08-21",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "fengshu-er-road",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": "12aeda9a63867ff659cec2310c3e4c586907d005",
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": null,
|
||||||
|
"relatedFiles": [],
|
||||||
|
"notes": "",
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||||
@@ -0,0 +1,82 @@
|
|||||||
|
# Design: Live V2X Cesium Intersection View
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
The native pipeline remains the source of static scene geometry and package
|
||||||
|
placement. The existing Cesium preview gains an operations overlay and a compact
|
||||||
|
V2X sign-in gate. Vehicle entities and their trace lines exist only after the
|
||||||
|
authenticated V2X streams provide valid positions; no generated traffic route or
|
||||||
|
simulation is rendered. The implementation stays in the current generated static
|
||||||
|
preview architecture and does not import the source dashboard's Vue, AMap, or
|
||||||
|
Three dependencies.
|
||||||
|
|
||||||
|
The generated preview runtime is divided into four browser concerns:
|
||||||
|
|
||||||
|
1. `auth`: presents the V2X sign-in form, MD5-hashes the password to match the
|
||||||
|
source contract, stores a successful token in `sessionStorage`, and clears it
|
||||||
|
on sign-out or authorization failure.
|
||||||
|
2. `v2x-client`: owns configured REST/WS origins, adds the raw `Authorization`
|
||||||
|
request header, normalizes the source API envelope, and reports a capability
|
||||||
|
status rather than blanking the preview if an optional resource fails.
|
||||||
|
3. `coordinates`: labels external values as GCJ-02 and native values as WGS84 or
|
||||||
|
ENU. It converts V2X GCJ-02 positions to WGS84 exactly once before Cesium
|
||||||
|
entity creation; the existing native package placement contract is unchanged.
|
||||||
|
4. `cesium-v2x-overlay`: adds V2X links, devices, pole/configuration evidence,
|
||||||
|
metrics, and real signal phase updates to the existing Cesium viewer, with
|
||||||
|
independent visibility controls and diagnostics.
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
```text
|
||||||
|
V2X sign-in -> session token
|
||||||
|
| |
|
||||||
|
| +--> Authorization header / WS query parameter
|
||||||
|
v
|
||||||
|
configured V2X REST + WS endpoints -> GCJ-02 V2X geometry, devices, metrics, lamps
|
||||||
|
|
|
||||||
|
v
|
||||||
|
GCJ-02-to-WGS84 adapter
|
||||||
|
|
|
||||||
|
native package + route/signal descriptors -> WGS84/ENU -> existing Cesium viewer
|
||||||
|
^
|
||||||
|
|
|
||||||
|
Cesium V2X operations overlay
|
||||||
|
```
|
||||||
|
|
||||||
|
## Endpoint Contract
|
||||||
|
|
||||||
|
The first delivery consumes `queryCrossLinkInfo`, `queryPoles`, bound-device,
|
||||||
|
cross-device-config, and weekly flow-ratio APIs. It subscribes to
|
||||||
|
`/network/ws/network/signal` only after link data establishes usable phases.
|
||||||
|
Endpoint host/prefixes and selected `crossCode` are deployment configuration. A
|
||||||
|
development proxy forwards REST and WebSocket traffic so the browser never needs
|
||||||
|
a hard-coded private origin.
|
||||||
|
|
||||||
|
## Coordinate Contract
|
||||||
|
|
||||||
|
| Producer | Source CRS | Consumer rule |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| Native compiler package, traffic signals, route descriptor | WGS84 / local ENU | Preserve the existing Cesium package placement and WGS84 entity contracts. |
|
||||||
|
| V2X dashboard link, road, device, and pole data | GCJ-02 | Convert to WGS84 once before creating Cesium entities. |
|
||||||
|
| High德 reference GeoJSON | GCJ-02 | Calibration-only compiler input; no runtime map or SDK dependency. |
|
||||||
|
|
||||||
|
The existing `gaode-junction-reference` inverse conversion is an appropriate
|
||||||
|
source for the V2X adapter. It will be factored or safely reused only when doing
|
||||||
|
so preserves its compiler behavior and test coverage.
|
||||||
|
|
||||||
|
## Compatibility And Failure Handling
|
||||||
|
|
||||||
|
- Existing Cesium preview and its static-only workflow remain usable.
|
||||||
|
- The V2X overlay starts only after successful sign-in.
|
||||||
|
- An expired token returns the user to sign-in and removes live entities rather
|
||||||
|
than presenting stale data as current.
|
||||||
|
- A REST/WS capability failure is shown in diagnostics; native scene and signals
|
||||||
|
remain usable, while the vehicle layer stays empty rather than simulating data.
|
||||||
|
- Removing the optional overlay/support files restores current preview behavior
|
||||||
|
without changing static package contracts.
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
`sessionStorage` limits the upstream token to the current tab session. Credentials
|
||||||
|
are never persisted. Configuration examples use placeholders, and deployment
|
||||||
|
documentation requires an HTTPS same-origin reverse proxy for V2X API/WS traffic.
|
||||||
@@ -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,41 @@
|
|||||||
|
# Implementation Plan: Live V2X Cesium Intersection View
|
||||||
|
|
||||||
|
1. Read preview and pipeline specifications, then add a focused V2X preview
|
||||||
|
configuration. Keep secrets and private origins out of defaults and tracked
|
||||||
|
area configuration.
|
||||||
|
2. Add browser-safe GCJ-02-to-WGS84 conversion and focused tests for source
|
||||||
|
coordinate labels and prevention of duplicate conversion. Preserve the current
|
||||||
|
compiler reference conversion behavior.
|
||||||
|
3. Implement the V2X browser client: login, session token lifecycle, REST
|
||||||
|
envelope handling, capability errors, and signal WebSocket lifecycle.
|
||||||
|
4. Extend the generated Cesium preview with V2X entities and operations controls
|
||||||
|
for links, devices, poles/configuration, metrics, live signal state, and the
|
||||||
|
OBU/target-vehicle streams. Do not load or generate simulated vehicle routes.
|
||||||
|
5. Add a local development/proxy configuration example and deployment
|
||||||
|
documentation for V2X REST/WS proxying. Do not add an AMap key, SDK, or page.
|
||||||
|
6. Add focused tests for HTML generation, configuration escaping, login/request
|
||||||
|
construction, coordinate conversion, source-layer diagnostics, and graceful
|
||||||
|
unavailable/auth states. Run existing preview and native-road regressions.
|
||||||
|
7. Validate in a browser with a real V2X account and configured proxy: sign in,
|
||||||
|
inspect aligned native/V2X features, verify REST panels and signal updates,
|
||||||
|
then verify sign-out/token expiry behavior.
|
||||||
|
|
||||||
|
## Validation Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node --check scripts/lib/area-preview.js
|
||||||
|
node --check scripts/lib/cesium-preview.js
|
||||||
|
npm run test:gaode-junction-reference
|
||||||
|
npm run test:preview-assets
|
||||||
|
npm run test:native-preview-traffic
|
||||||
|
npm run test:traffic-signals
|
||||||
|
npm run road:compile -- --config config/areas/fengshu-er-road.json
|
||||||
|
npm run build:area -- --config config/areas/fengshu-er-road.json --stages preview
|
||||||
|
```
|
||||||
|
|
||||||
|
## Review Gates
|
||||||
|
|
||||||
|
- Confirm no token, account, or private host is committed.
|
||||||
|
- Verify V2X GCJ-02 coordinates convert once before Cesium use.
|
||||||
|
- Verify the existing native WGS84/ENU scene contract remains unchanged.
|
||||||
|
- Verify the current Cesium preview works without V2X configuration or sign-in.
|
||||||
@@ -0,0 +1,85 @@
|
|||||||
|
# Integrate live V2X intersection data into Cesium preview
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Provide a Cesium-based operational view of the current complex intersection in
|
||||||
|
this repository. It must show live data from the existing V2X platform while
|
||||||
|
retaining the native road compiler's WGS84/ENU output as the geometry authority.
|
||||||
|
|
||||||
|
## Confirmed Facts
|
||||||
|
|
||||||
|
- The source dashboard's holographic-intersection view uses V2X REST resources for
|
||||||
|
road/link geometry, device bindings, poles, configuration, traffic metrics, and
|
||||||
|
a token-authenticated signal WebSocket.
|
||||||
|
- The dashboard development proxy targets `172.16.1.159:50400` under `/api`,
|
||||||
|
`/websocket`, and `/vectortile`; the application sends the upstream token as the
|
||||||
|
`Authorization` header.
|
||||||
|
- The source dashboard uses AMap and therefore its road/link data is GCJ-02. Its
|
||||||
|
road-network exporter converts that data from GCJ-02 to WGS84 before export.
|
||||||
|
- This repository's native road, signal, and simulation artifacts are WGS84/ENU.
|
||||||
|
- The target is the existing Cesium preview, not AMap. High德 data in this
|
||||||
|
repository is a calibration/reference GeoJSON only, not a target runtime map.
|
||||||
|
- The requested page has a simple login gate; V2X data must remain real live
|
||||||
|
interface data, not copied mock data.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- R1: Add a Cesium-based complex-intersection operations view to this repository, protected by
|
||||||
|
a simple application login.
|
||||||
|
- R2: Integrate the real V2X REST endpoints used by the source dashboard, including
|
||||||
|
current intersection/link geometry, devices, poles/configuration, traffic metrics,
|
||||||
|
and signal state where upstream authorization permits it.
|
||||||
|
- R3: Keep the V2X platform credentials separate from the simple application login;
|
||||||
|
do not put a reusable upstream credential into browser source or committed files.
|
||||||
|
- R4: Treat V2X map-facing coordinates as GCJ-02. Treat native compiler artifacts
|
||||||
|
as WGS84/ENU, and convert V2X GCJ-02 coordinates to WGS84 exactly once before
|
||||||
|
adding them to Cesium.
|
||||||
|
- R5: Surface a clear unavailable/authentication state when live data cannot be
|
||||||
|
loaded while leaving the native complex-intersection view usable.
|
||||||
|
- R6: Make endpoint origin, selected V2X intersection code, and authorization
|
||||||
|
mechanism deployment configuration rather than hard-coded source values.
|
||||||
|
- R7: Vehicle lines and moving vehicles must come only from the authenticated
|
||||||
|
V2X vehicle streams. Do not render or fall back to generated route/simulation
|
||||||
|
data when the service is unavailable.
|
||||||
|
|
||||||
|
## Candidate Upstream Resources
|
||||||
|
|
||||||
|
- `GET /network/api/link/network/queryCrossLinkInfo/{crossCode}`: intersection
|
||||||
|
link geometry and signal phase association.
|
||||||
|
- `GET /network/api/pole/network/queryPoles/{crossCode}`: pole and light placement
|
||||||
|
configuration.
|
||||||
|
- `GET /facilities/api/crossDevice/findDeviceByCrossCode/{crossCode}`: bound devices.
|
||||||
|
- `GET /facilities/api/crossDeviceConfig/{crossCode}`: target-device configuration.
|
||||||
|
- `GET /facilities/api/FlowTravelRatio/queryListWeek?code={crossCode}` and related
|
||||||
|
cross-monitor resources: operational metrics.
|
||||||
|
- `WS /network/ws/network/signal?authorization={token}`: live signal lamps.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ] A user can pass the local login gate and open the current complex-intersection
|
||||||
|
Cesium view.
|
||||||
|
- [ ] The page retrieves and renders live V2X data for a configurable intersection
|
||||||
|
code without source-dashboard runtime dependencies.
|
||||||
|
- [ ] The page identifies the coordinate reference of each source and visually
|
||||||
|
aligns native WGS84 geometry with V2X data converted from GCJ-02.
|
||||||
|
- [ ] A missing/expired upstream credential or unavailable service is visible and
|
||||||
|
does not make the native intersection view unusable.
|
||||||
|
- [ ] Upstream URL, intersection code, and credentials/tokens are excluded from
|
||||||
|
tracked application source and documented for deployment.
|
||||||
|
|
||||||
|
## Out Of Scope
|
||||||
|
|
||||||
|
- Copying the source dashboard's Vue, AMap/Three, or proprietary UI component stack.
|
||||||
|
- Building a full user/role management service.
|
||||||
|
- Replacing native road geometry or traffic-signal contracts with V2X data.
|
||||||
|
- Generated vehicle-route or traffic-simulation fallback in the operations preview.
|
||||||
|
|
||||||
|
## Authentication Decision
|
||||||
|
|
||||||
|
- The page signs in to the upstream V2X service with the user-entered account,
|
||||||
|
posting `userName` and MD5-hashed `password` to
|
||||||
|
`/facilities/api/sys/login` through the configured API prefix.
|
||||||
|
- The returned token lives only in `sessionStorage`, is sent as the raw
|
||||||
|
`Authorization` header for REST requests, and is supplied as the
|
||||||
|
`authorization` WebSocket query parameter for the signal subscription.
|
||||||
|
- No default credentials, reusable token, or API secret may be committed.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"id": "v2x-amap-intersection-data",
|
||||||
|
"name": "v2x-amap-intersection-data",
|
||||||
|
"title": "Integrate live V2X intersection data into AMap preview",
|
||||||
|
"description": "",
|
||||||
|
"status": "completed",
|
||||||
|
"dev_type": null,
|
||||||
|
"scope": null,
|
||||||
|
"package": null,
|
||||||
|
"priority": "P2",
|
||||||
|
"creator": "dingkang",
|
||||||
|
"assignee": "dingkang",
|
||||||
|
"createdAt": "2026-08-24",
|
||||||
|
"completedAt": "2026-08-24",
|
||||||
|
"branch": null,
|
||||||
|
"base_branch": "fengshu-er-road",
|
||||||
|
"worktree_path": null,
|
||||||
|
"commit": null,
|
||||||
|
"pr_url": null,
|
||||||
|
"subtasks": [],
|
||||||
|
"children": [],
|
||||||
|
"parent": null,
|
||||||
|
"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**: 30
|
- **Total Sessions**: 41
|
||||||
- **Last Active**: 2026-08-12
|
- **Last Active**: 2026-08-24
|
||||||
<!-- @@@/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` | ~642 | Active |
|
| `journal-1.md` | ~887 | Active |
|
||||||
<!-- @@@/auto:active-documents -->
|
<!-- @@@/auto:active-documents -->
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -29,6 +29,17 @@
|
|||||||
<!-- @@@auto:session-history -->
|
<!-- @@@auto:session-history -->
|
||||||
| # | Date | Title | Commits | Branch |
|
| # | Date | Title | Commits | Branch |
|
||||||
|---|------|-------|---------|--------|
|
|---|------|-------|---------|--------|
|
||||||
|
| 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` |
|
||||||
|
| 39 | 2026-08-18 | Complete native-only pipeline replacement | `9e0e25a` | `feature/native-road-compiler` |
|
||||||
|
| 38 | 2026-08-18 | Complete native traffic signal workflow | `5accc0a` | `feature/native-road-compiler` |
|
||||||
|
| 37 | 2026-08-18 | Complete rounded native junction verification | `e41bfd1`, `f7e71cf` | `feature/native-road-compiler` |
|
||||||
|
| 36 | 2026-08-17 | Complete native road marking semantics | `9bb97d4` | `feature/native-road-compiler` |
|
||||||
|
| 35 | 2026-08-17 | Complete native lane separator styles | `bc04517` | `feature/native-road-compiler` |
|
||||||
|
| 34 | 2026-08-17 | Add center line style overrides | `47efb78` | `feature/native-road-compiler` |
|
||||||
|
| 33 | 2026-08-17 | Add native road center lines | `fb863da` | `feature/native-road-compiler` |
|
||||||
|
| 32 | 2026-08-17 | Native road control markings | `4c4f453` | `feature/native-road-compiler` |
|
||||||
|
| 31 | 2026-08-14 | Native road lane markings | `1b9829d` | `feature/native-road-compiler` |
|
||||||
| 30 | 2026-08-12 | Add vehicle incident preview cards | `761a526` | `main` |
|
| 30 | 2026-08-12 | Add vehicle incident preview cards | `761a526` | `main` |
|
||||||
| 29 | 2026-08-12 | Publish reusable area asset packages | `f385009`, `c925890`, `db0fba5`, `f2b8d79`, `0102ffb` | `main` |
|
| 29 | 2026-08-12 | Publish reusable area asset packages | `f385009`, `c925890`, `db0fba5`, `f2b8d79`, `0102ffb` | `main` |
|
||||||
| 28 | 2026-08-11 | 默认压缩交付 | `0790cbd` | `main` |
|
| 28 | 2026-08-11 | 默认压缩交付 | `0790cbd` | `main` |
|
||||||
|
|||||||
@@ -640,3 +640,248 @@ Added click-to-open vehicle information cards with normal, breakdown, and accide
|
|||||||
### Status
|
### Status
|
||||||
|
|
||||||
[OK] **Completed**
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 31: Native road lane markings
|
||||||
|
|
||||||
|
**Date**: 2026-08-14
|
||||||
|
**Task**: Native road lane markings
|
||||||
|
**Branch**: `feature/native-road-compiler`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Implemented native lane separators, repeated road direction arrows, explicit junction turn arrows, Workbench inspection/toggles, and Blender/Cesium adapter support for Nantaizi; validated native compile, checks, tests, and non-package visual build.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `1b9829d` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 32: Native road control markings
|
||||||
|
|
||||||
|
**Date**: 2026-08-17
|
||||||
|
**Task**: Native road control markings
|
||||||
|
**Branch**: `feature/native-road-compiler`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Added native-source crosswalk and stop-line layers with workbench inspection, Blender/Cesium delivery, and control-marking arrow avoidance.
|
||||||
|
|
||||||
|
### Main Changes
|
||||||
|
|
||||||
|
- Compiled explicit marked OSM crossings into source-traceable native GeoJSON.
|
||||||
|
- Added Chinese workbench control-layer toggle, selection evidence, and summary counts.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `4c4f453` | (see git log) |
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
|
||||||
|
- [OK] Passed native-road, road-workbench, turn-lane-arrows, build-stages, native compile/check, and Blender/Cesium/preview build.
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
|
|
||||||
|
### Next Steps
|
||||||
|
|
||||||
|
- Continue native road compiler workbench with the next user-approved priority.
|
||||||
|
|
||||||
|
|
||||||
|
## Session 33: Add native road center lines
|
||||||
|
|
||||||
|
**Date**: 2026-08-17
|
||||||
|
**Task**: Add native road center lines
|
||||||
|
**Branch**: `feature/native-road-compiler`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Implemented Nantaizi native-road center_lines output, workbench selection/toggle, Blender adapter, control-marking avoidance, and cross-layer verification.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `fb863da` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 34: Add center line style overrides
|
||||||
|
|
||||||
|
**Date**: 2026-08-17
|
||||||
|
**Task**: Add center line style overrides
|
||||||
|
**Branch**: `feature/native-road-compiler`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Added persistent native road centre-line colour and pattern overrides, automatic Workbench staging, continuous solid-line rendering, and Blender white material support.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `47efb78` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 35: Complete native lane separator styles
|
||||||
|
|
||||||
|
**Date**: 2026-08-17
|
||||||
|
**Task**: Complete native lane separator styles
|
||||||
|
**Branch**: `feature/native-road-compiler`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Completed per lane-pair separator colour/pattern overrides, Workbench staging, Blender yellow material routing, and centre-line control clearance.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `bc04517` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 36: Complete native road marking semantics
|
||||||
|
|
||||||
|
**Date**: 2026-08-17
|
||||||
|
**Task**: Complete native road marking semantics
|
||||||
|
**Branch**: `feature/native-road-compiler`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Added explicit double-yellow centre lines and per-side edge-line overrides; made all three marking classes selectable in the Chinese Road Workbench; synchronized Blender adapter coverage and verified Nantaizi native compile, quality gate, Blender/Cesium/preview manifests, and automated tests.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `9bb97d4` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 37: Complete rounded native junction verification
|
||||||
|
|
||||||
|
**Date**: 2026-08-18
|
||||||
|
**Task**: Complete rounded native junction verification
|
||||||
|
**Branch**: `feature/native-road-compiler`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Recorded user-confirmed native Blender/Cesium/preview verification for rounded native junctions, checked off all acceptance criteria, and archived the completed 08-17-native-rounded-junctions task.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `e41bfd1` | (see git log) |
|
||||||
|
| `f7e71cf` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 38: Complete native traffic signal workflow
|
||||||
|
|
||||||
|
**Date**: 2026-08-18
|
||||||
|
**Task**: Complete native traffic signal workflow
|
||||||
|
**Branch**: `feature/native-road-compiler`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Completed native traffic-signal ownership and Workbench editing. Added independent pole position, mast heading/reach, and face heading controls; removed native QGIS dependency; verified runtime preview, browser rendering, compile, tests, and quality gates. Archived native traffic signal and road compiler tasks.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `5accc0a` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 39: Complete native-only pipeline replacement
|
||||||
|
|
||||||
|
**Date**: 2026-08-18
|
||||||
|
**Task**: Complete native-only pipeline replacement
|
||||||
|
**Branch**: `feature/native-road-compiler`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Made native road compilation the default provider and full-build stage set; decoupled package traffic signals and preview from QGIS/osm2streets, made diagnostics provider-aware, updated docs/specs/tests, and preserved explicit legacy reference/debug paths. Native road compile/check and all available Node tests passed. QGIS baseline remains tagged qgis-original-baseline-20260818.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `9e0e25a` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 40: Stabilize Fengshu native road compilation
|
||||||
|
|
||||||
|
**Date**: 2026-08-24
|
||||||
|
**Task**: Stabilize Fengshu native road compilation
|
||||||
|
**Branch**: `fengshu-er-road`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Validated and committed the Fengshu Er Road native compilation fixes, including stale override tolerance, corrected unreferenced complex-junction sizing, updated OSM input, and focused road/traffic preview regression coverage.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `f1f829c` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
|
|
||||||
|
|
||||||
|
## Session 41: Use live V2X vehicle streams only
|
||||||
|
|
||||||
|
**Date**: 2026-08-24
|
||||||
|
**Task**: Use live V2X vehicle streams only
|
||||||
|
**Branch**: `fengshu-er-road`
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
Replaced the Cesium preview's simulated vehicle route with authenticated OBU and target-vehicle V2X streams, converting GCJ-02 coordinates to WGS84 exactly once. Removed native traffic-simulation output, regenerated Fengshu Er Road preview, documented the no-fallback contract, and verified focused preview, V2X, budget, native-road, and signal tests.
|
||||||
|
|
||||||
|
### Git Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| `b7031f1` | (see git log) |
|
||||||
|
|
||||||
|
### Status
|
||||||
|
|
||||||
|
[OK] **Completed**
|
||||||
@@ -1,6 +1,8 @@
|
|||||||
# OSM Asset Pipeline
|
# OSM Asset Pipeline
|
||||||
|
|
||||||
把单个园区/片区 OSM XML 转为可消费的 Blender 场景和 Cesium GLB。osm2streets GeoJSON、GeoPackage、QGIS 工程和预览图都是中间资产,用来提供道路几何、调试标线效果,以及给 Blender/Cesium 生成提供输入。
|
原始 QGIS/osm2streets 基线保留在 Git tag `qgis-original-baseline-20260818`,用于回撤和对照;当前分支的默认生产链路是 native-only。
|
||||||
|
|
||||||
|
把单个园区/片区 OSM XML 转为可消费的 Blender 场景和 Cesium GLB。Native road compiler 是默认生产道路来源;osm2streets GeoJSON、GeoPackage、QGIS 工程和预览图仅作为显式 legacy/debug 资产或 Workbench 参考层。
|
||||||
|
|
||||||
## 目标产物
|
## 目标产物
|
||||||
|
|
||||||
@@ -17,17 +19,19 @@
|
|||||||
- `<area-id>-roads.glb`、`-buildings.glb`、`-vegetation.glb`、`-water.glb`:Cesium 分类检查用的辅助模型
|
- `<area-id>-roads.glb`、`-buildings.glb`、`-vegetation.glb`、`-water.glb`:Cesium 分类检查用的辅助模型
|
||||||
- `<area-id>.json`:Cesium 放置元数据和示例代码
|
- `<area-id>.json`:Cesium 放置元数据和示例代码
|
||||||
- `<area-id>-cesium-preview.html`:Cesium 本地预览页
|
- `<area-id>-cesium-preview.html`:Cesium 本地预览页
|
||||||
- `osm2streets_web_out/`:osm2streets GeoJSON 中间层
|
- `native-road/`:native road compiler 的道路、路口、标线和信号灯运行时产物
|
||||||
|
- `osm2streets_web_out/`:可选的 osm2streets/QGIS 参考中间层
|
||||||
- `<area-id>.gpkg` / `<area-id>.qgz` / `<area-id>-preview.png`:QGIS 调试资产
|
- `<area-id>.gpkg` / `<area-id>.qgz` / `<area-id>-preview.png`:QGIS 调试资产
|
||||||
|
|
||||||
## 环境
|
## 环境
|
||||||
|
|
||||||
需要:
|
默认 native-only 构建需要:
|
||||||
|
|
||||||
- QGIS 与 GDAL 工具链
|
|
||||||
- Blender
|
- Blender
|
||||||
- Node.js / npm
|
- Node.js / npm
|
||||||
|
|
||||||
|
QGIS/GDAL 仅在显式运行 legacy `intermediates`/`reimport` 或 Workbench 参考链路时需要。
|
||||||
|
|
||||||
macOS 默认使用 QGIS `/Applications/QGIS.app` 与 Blender
|
macOS 默认使用 QGIS `/Applications/QGIS.app` 与 Blender
|
||||||
`/Applications/Blender.app`。Linux 配置中,`qgisApp` 是安装前缀(通常为
|
`/Applications/Blender.app`。Linux 配置中,`qgisApp` 是安装前缀(通常为
|
||||||
`/usr`),`blenderApp` 是可执行文件路径(通常为 `/usr/bin/blender`)。
|
`/usr`),`blenderApp` 是可执行文件路径(通常为 `/usr/bin/blender`)。
|
||||||
@@ -66,7 +70,7 @@ npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json
|
|||||||
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages reimport
|
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages reimport
|
||||||
```
|
```
|
||||||
|
|
||||||
`intermediates` 会生成 osm2streets GeoJSON、GeoPackage、QGIS 工程和 QGIS 预览图。`blender` 使用 OSM 和 osm2streets GeoJSON 生成 `.blend`/`.png`。`cesium` 从 `.blend` 导出包 staging,`compress` 压缩 staging 主 GLB,`package` 校验并原子发布 `package/`,`preview` 生成仅用于本地验证的 HTML 和 `_preview/` 动态描述符。`reimport` 把手工编辑过的 GeoPackage 回导为 GeoJSON,不含在 `all` 里,详见 [QGIS 手工修正工作流](#qgis-手工修正工作流)。
|
默认构建依次由 native road compiler、Blender、Cesium、压缩、package 和 preview 组成,不读取 `osm2streets_web_out/`。native preview 在没有 legacy 路线文件时仍可用,只是不提供可选车辆巡航。`intermediates`/`reimport` 仍可显式运行 legacy QGIS 链路,详见 [QGIS 手工修正工作流](#qgis-手工修正工作流)。
|
||||||
|
|
||||||
Cesium 预览默认显示完整场景。点击 `Inspect` 后会按道路、建筑、绿化与设施、水体加载辅助 GLB;该模式用于单独检查生成结果,主 GLB 是压缩后的下游交付资产。
|
Cesium 预览默认显示完整场景。点击 `Inspect` 后会按道路、建筑、绿化与设施、水体加载辅助 GLB;该模式用于单独检查生成结果,主 GLB 是压缩后的下游交付资产。
|
||||||
|
|
||||||
@@ -96,6 +100,53 @@ npm run preflight:area -- --config config/areas/nantaizi-lake-innovation-valley.
|
|||||||
预检有 error 时退出非零且不会更新记录;通过后写 `preflight.manifest.json`,保留本次
|
预检有 error 时退出非零且不会更新记录;通过后写 `preflight.manifest.json`,保留本次
|
||||||
验证的 config / OSM 文件摘要和检查结果。
|
验证的 config / OSM 文件摘要和检查结果。
|
||||||
|
|
||||||
|
## Native Road Workbench
|
||||||
|
|
||||||
|
`road:compile` 是独立于 osm2streets 的实验性道路编译器入口。它从 OSM 生成可追溯的
|
||||||
|
道路模型、基础道路面、诊断与对比摘要,写入 `outputs/<area-id>/native-road/`,不会覆盖
|
||||||
|
`osm2streets_web_out/` 或影响现有 Blender/Cesium 构建:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
npm run road:check -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
```
|
||||||
|
|
||||||
|
`road:check` 验证已发布 connector 与语义行驶动作的一致性,并在诊断包含 error、图层缺失或
|
||||||
|
动作/几何对应关系不一致时以非零退出。warning 保留给工作台审查,不会阻止产物打开。
|
||||||
|
|
||||||
|
### Native Preview Traffic Simulation
|
||||||
|
|
||||||
|
native preview 会额外生成:
|
||||||
|
|
||||||
|
```text
|
||||||
|
outputs/<area-id>/_preview/<area-id>-traffic-simulation.json
|
||||||
|
```
|
||||||
|
|
||||||
|
该文件使用 `native-preview-traffic-simulation/v1`,记录 native 路线、connector、停止点、
|
||||||
|
信号 `signal_uid`、源文件 SHA-256、坐标系和仿真参数。它与 `package/manifest.json` 一起可
|
||||||
|
迁移到其他平台;消费方不需要运行 Node 或 QGIS。预览中的车辆会根据现有信号相位在停止线
|
||||||
|
前停车,并按最小车距跟车排队。该功能是确定性的验证预览,不是法规级导航或完整交通仿真。
|
||||||
|
|
||||||
|
迁移契约、JSON 示例、更新循环和回撤方式见
|
||||||
|
[native preview traffic simulation](docs/native-preview-traffic-simulation.md)。
|
||||||
|
|
||||||
|
启动本地浏览器工作台:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run road:workbench -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||||
|
```
|
||||||
|
|
||||||
|
工作台默认先编译,并在 `http://127.0.0.1:8787/` 启动基于 OpenLayers 的 GIS 工作台,展示
|
||||||
|
OSM 道路、原生结果、车道、行驶动作、诊断和每个值的来源。可编辑道路宽度、车道数、两侧
|
||||||
|
人行道,以及候选路口端点连接。保存写入
|
||||||
|
`outputs/<area-id>/native-road-overrides.json`;此文件是版本化的可审查输入,下一次编译和
|
||||||
|
启动工作台时会自动加载。编辑不会直接修改最终 polygon。
|
||||||
|
|
||||||
|
道路按行驶方向显示:点击道路面、中心线、车道或转向路径后,蓝色三角形标记当前方向在 OSM
|
||||||
|
原始中心线上的方向;右侧“路口连接”只列出该方向到达终点路口后可驶入的目标道路,并标记为
|
||||||
|
左转、直行、右转或掉头。车道按当前方向从左向右编号。内部断头诊断中的近邻候选不会自动连接,
|
||||||
|
必须由用户显式暂存、保存并重新编译。
|
||||||
|
|
||||||
诊断会输出 OSM bounds、building way / multipolygon relation、显式高度、植被数量、
|
诊断会输出 OSM bounds、building way / multipolygon relation、显式高度、植被数量、
|
||||||
现有产物状态,以及 GLB 的 size / nodes / meshes / materials / images / extensions。
|
现有产物状态,以及 GLB 的 size / nodes / meshes / materials / images / extensions。
|
||||||
缺少已期望的基线产物、异常 building relation、GLB 超过保守预算等会进入 `Warnings`。
|
缺少已期望的基线产物、异常 building relation、GLB 超过保守预算等会进入 `Warnings`。
|
||||||
@@ -117,9 +168,9 @@ outputs/<area-id>/_pipeline/stages/compress.manifest.json
|
|||||||
造成假 stale。
|
造成假 stale。
|
||||||
|
|
||||||
manifest 记录阶段输入/输出文件的 bytes、mtime、sha256、耗时和结构摘要:前段记录 OSM /
|
manifest 记录阶段输入/输出文件的 bytes、mtime、sha256、耗时和结构摘要:前段记录 OSM /
|
||||||
GeoJSON feature counts,Blender 记录 `.blend` / render,Cesium/压缩记录 GLB digest,
|
native-road 或 legacy GeoJSON feature counts,Blender 记录 `.blend` / render,Cesium/压缩记录 GLB digest,
|
||||||
preview 记录 GLB、metadata、`lane_polygons.geojson`、`network.json`、`intersection_surface.geojson`、
|
preview 记录 GLB、metadata、provider 对应的道路输入、可选车辆路线和 runtime 文件。legacy
|
||||||
车辆路线和 runtime 文件。巡航道路区间按 osm2streets internal road 匹配真实 Driving lane 中轴,
|
巡航道路区间按 osm2streets internal road 匹配真实 Driving lane 中轴,native preview 可省略巡航,
|
||||||
路口 connector 必须通过 intersection surface 越界检查。`diagnose:area` 会读取这些
|
路口 connector 必须通过 intersection surface 越界检查。`diagnose:area` 会读取这些
|
||||||
manifest;缺失或当前输入/输出 sha/bytes 不一致会在 `Stage manifests` 和 `Warnings`
|
manifest;缺失或当前输入/输出 sha/bytes 不一致会在 `Stage manifests` 和 `Warnings`
|
||||||
里标出来。
|
里标出来。
|
||||||
@@ -170,7 +221,7 @@ cp config/examples/template.json config/areas/my-area.json
|
|||||||
"qgisApp": "/Applications/QGIS.app",
|
"qgisApp": "/Applications/QGIS.app",
|
||||||
"blenderApp": "/Applications/Blender.app",
|
"blenderApp": "/Applications/Blender.app",
|
||||||
"stages": {
|
"stages": {
|
||||||
"intermediates": true,
|
"intermediates": false,
|
||||||
"blender": true,
|
"blender": true,
|
||||||
"cesium": true
|
"cesium": true
|
||||||
},
|
},
|
||||||
@@ -188,7 +239,8 @@ cp config/examples/template.json config/areas/my-area.json
|
|||||||
},
|
},
|
||||||
"blender": {
|
"blender": {
|
||||||
"treeStyle": "natural",
|
"treeStyle": "natural",
|
||||||
"officeOverrides": ""
|
"officeOverrides": "",
|
||||||
|
"roadProvider": "native"
|
||||||
},
|
},
|
||||||
"compress": {
|
"compress": {
|
||||||
"textureSize": 768,
|
"textureSize": 768,
|
||||||
@@ -327,7 +379,7 @@ npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json
|
|||||||
- 这套流程假设你的手工修改已经保存在 `outputs/<area-id>/<area-id>.gpkg` 中
|
- 这套流程假设你的手工修改已经保存在 `outputs/<area-id>/<area-id>.gpkg` 中
|
||||||
- 所有图层先导出到临时目录并校验通过后才写回 `osm2streets_web_out/`;任一图层缺失或导出结果不是合法 FeatureCollection,整批都不落盘(`ogr2ogr` 遇到不存在的图层会留下 0 字节文件,直接覆盖会静默损坏数据)
|
- 所有图层先导出到临时目录并校验通过后才写回 `osm2streets_web_out/`;任一图层缺失或导出结果不是合法 FeatureCollection,整批都不落盘(`ogr2ogr` 遇到不存在的图层会留下 0 字节文件,直接覆盖会静默损坏数据)
|
||||||
- `intermediates` 与 `reimport` 互斥,同时指定会直接报错:前者用 OSM 重建 `gpkg`,正好会抹掉后者要读回的手工修改
|
- `intermediates` 与 `reimport` 互斥,同时指定会直接报错:前者用 OSM 重建 `gpkg`,正好会抹掉后者要读回的手工修改
|
||||||
- `blender,cesium` 阶段读取的是 `osm2streets_web_out/*.geojson`,不是直接读取 `gpkg`
|
- 在显式 legacy provider 下,`blender,cesium` 阶段读取的是 `osm2streets_web_out/*.geojson`,不是直接读取 `gpkg`;native provider 不读取这些文件
|
||||||
- 如果 Blender 当前环境不稳定,先确认 `geojson` 已完成回导,再单独排查 Blender 本身
|
- 如果 Blender 当前环境不稳定,先确认 `geojson` 已完成回导,再单独排查 Blender 本身
|
||||||
- 增删图层或调整 `z_index` 只需改 `scripts/lib/scene-layers.js`,构建、场景合并、场景样式、QGIS 工程会一并同步
|
- 增删图层或调整 `z_index` 只需改 `scripts/lib/scene-layers.js`,构建、场景合并、场景样式、QGIS 工程会一并同步
|
||||||
|
|
||||||
|
|||||||
Binary file not shown.
Loaded 100 of 160 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user