Refactor pipeline around area asset builds

2026-07-27 12:56:13 +08:00
parent 59a22ea697
commit 61e4820a4c
10 changed files with 446 additions and 139 deletions
--- a/README.md
+++ b/README.md
@@ -1,14 +1,25 @@
-# OSM GIS Pipeline
+# OSM Asset Pipeline

-把 OSM XML 转为 QGIS 工程（osm2streets 风格道路）和可选的 Blender 3D 场景。
+把单个园区/片区 OSM XML 转为可消费的 Blender 场景和 Cesium GLB。osm2streets GeoJSON、GeoPackage、QGIS 工程和预览图都是中间资产，用来提供道路几何、调试标线效果，以及给 Blender/Cesium 生成提供输入。
+
+## 目标产物
+
+每个区域默认输出到 `outputs/<area-id>/`：
+
+- `<area-id>.blend`：Blender 场景，包含道路、建筑、水体、植被等
+- `<area-id>.png`：Blender 预览渲染
+- `<area-id>.glb`：Cesium 可加载的 3D 模型
+- `<area-id>.json`：Cesium 放置元数据和示例代码
+- `osm2streets_web_out/`：osm2streets GeoJSON 中间层
+- `<area-id>.gpkg` / `<area-id>.qgz` / `<area-id>-preview.png`：QGIS 调试资产

 ## 环境

 需要：

 - macOS QGIS：默认 `/Applications/QGIS.app`
+- Blender：默认 `/Applications/Blender.app`
 - Node.js / npm
- Blender（可选，用于 3D 场景生成）

 首次使用：

@@ -17,93 +28,94 @@ cd /Users/que01/osm2streets-qgis-workflow
 npm install
 ```

-## QGIS 管线（强依赖 osm2streets）
+## 主流程

-使用默认配置：
+默认构建南台子湖创新谷样例：

 ```bash
-cd /Users/que01/osm2streets-qgis-workflow
 npm run build
 ```

-使用指定配置：
+指定区域配置：

 ```bash
-node scripts/build-osm2streets-qgis.js --config /path/to/config.json
+npm run build:area -- --config config/areas/hanyang-block.json
 ```

-命令行参数可以覆盖配置文件：
+只跑部分阶段：

 ```bash
-node scripts/build-osm2streets-qgis.js \
-  --input /path/to/osm.xml \
-  --out-dir /path/to/out \
-  --gpkg /path/to/output.gpkg \
-  --project /path/to/output.qgz \
-  --preview /path/to/output_preview.png
+npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages intermediates
+npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender
+npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages cesium
 ```

-创建新区域配置可以从模板复制：
+`intermediates` 会生成 osm2streets GeoJSON、GeoPackage、QGIS 工程和 QGIS 预览图。`blender` 使用 OSM 和 osm2streets GeoJSON 生成 `.blend`/`.png`。`cesium` 从 `.blend` 导出 `.glb`/`.json`。
+
+## 区域配置
+
+新区域从模板复制：

 ```bash
-cp config/examples/template.json config/my-area.json
+cp config/examples/template.json config/areas/my-area.json
 ```

-### 配置项
+核心配置：

 ```json
 {
-  "qgisApp": "/Applications/QGIS.app",
+  "id": "my-area",
  "input": "/absolute/path/to/input.osm",
-  "outDir": "/absolute/path/to/osm2streets_web_out",
-  "gpkg": "/absolute/path/to/output.gpkg",
-  "project": "/absolute/path/to/output.qgz",
-  "preview": "/absolute/path/to/output_preview.png",
-  "arrowScale": 0.8,
-  "clipPad": 0.002,
-  "canvasPad": 0.001,
-  "previewPad": 0.0007,
-  "canvasExtent": null,
-  "previewExtent": null,
-  "layerPrefix": "osm2streets",
-  "osm2streets": {
-    "debug_each_step": false,
-    "dual_carriageway_experiment": false,
-    "sidepath_zipping_experiment": false,
-    "inferred_sidewalks": true,
-    "osm2lanes": true
+  "outputRoot": "/absolute/path/to/outputs",
+  "qgisApp": "/Applications/QGIS.app",
+  "blenderApp": "/Applications/Blender.app",
+  "stages": {
+    "intermediates": true,
+    "blender": true,
+    "cesium": true
+  },
+  "qgis": {
+    "arrowScale": 0.8,
+    "clipPad": 0.002,
+    "canvasPad": 0.001,
+    "previewPad": 0.0007,
+    "canvasExtent": null,
+    "previewExtent": null,
+    "layerPrefix": "osm2streets"
+  },
+  "blender": {
+    "treeStyle": "natural",
+    "officeOverrides": ""
  }
 }
 ```

- `input`：OSM XML 输入文件路径。
- `outDir`：osm2streets GeoJSON 中间产物输出目录。
- `gpkg` / `project` / `preview`：最终 GeoPackage、QGIS 工程、预览 PNG 路径。
- `layerPrefix`：QGIS 图层显示名称前缀（如 `"osm2streets"` → `"osm2streets road surface"`）。
- `arrowScale`：方向箭头几何缩放。
- `osm2streets`：osm2streets 引擎选项。
+`scripts/build-area.js` 会按 `id` 自动推导默认输出路径。确实需要定制时，可以增加 `outputs` 覆盖：

-### 输出图层
+```json
+{
+  "outputs": {
+    "areaDir": "/absolute/path/to/custom-area",
+    "blend": "/absolute/path/to/custom.blend",
+    "glb": "/absolute/path/to/custom.glb"
+  }
+}
+```

-GeoPackage 内会生成：
+## 已沉淀区域

- `road_surface`
- `intersection_surface`
- `sidewalks`
- `sidewalk_corners`
- `lane_separators`
- `center_lines`
- `vehicle_stop_lines`
- `lane_arrows_webscale`
- `crosswalks`
+- `config/areas/nantaizi-lake-innovation-valley.json`
+- `config/areas/hanyang-block.json`

-QGIS 工程绘制顺序：路面在最底，车道线、斑马线、停止线和箭头在上。
+## 低层命令

-## Blender 3D 场景（可选）
+通常优先使用 `npm run build:area`。如果只想调试旧 QGIS/osm2streets 阶段，可以直接运行：

-osm2streets 道路几何为可选输入；不提供时回退到 OSM highway 折线。
+```bash
+npm run build:qgis -- --config config/hanyang-block.json
+```

-生成场景：
+Blender 低层命令：

 ```bash
 /Applications/Blender.app/Contents/MacOS/Blender \
@@ -112,70 +124,24 @@ osm2streets 道路几何为可选输入；不提供时回退到 OSM highway 折
  --osm "/path/to/input.osm" \
  --geojson "/path/to/osm2streets_web_out" \
  --output "/path/to/scene.blend" \
-  --render "/path/to/preview.png"
+  --render "/path/to/preview.png" \
+  --tree-style natural
 ```

-`--geojson` 为可选参数。使用 `--office-overrides` 指定应渲染为办公楼的 OSM way ID（逗号分隔）。
-
-导出为 Cesium GLB：
+Cesium GLB 低层导出：

 ```bash
 /Applications/Blender.app/Contents/MacOS/Blender \
  --background \
  --python blender/export_cesium.py -- \
  --blend "/path/to/scene.blend" \
-  --glb "/path/to/scene_cesium.glb" \
-  --metadata "/path/to/scene_cesium.json"
+  --glb "/path/to/scene.glb" \
+  --metadata "/path/to/scene.json"
 ```

 详见 [blender/README.md](blender/README.md)。

-## 运行示例
-
-以下命令已在本机验证通过。
-
-QGIS 管线（使用汉阳区区块 OSM 数据）：
-
-```bash
-node scripts/build-osm2streets-qgis.js \
-  --config config/hanyang-block.json
-```
-
-Blender 场景（含 osm2streets 道路几何）：
-
-```bash
-/Applications/Blender.app/Contents/MacOS/Blender \
-  --background --factory-startup \
-  --python blender/generate_scene.py -- \
-  --osm "/Users/que01/Desktop/南台子湖创新谷OSM.osm" \
-  --geojson "/Users/que01/osm2streets-qgis-workflow/outputs/nantaizi-lake-innovation-valley/osm2streets_web_out" \
-  --output "/tmp/scene.blend" \
-  --render "/tmp/preview.png"
-```
-
-Blender 场景（纯 OSM，无 osm2streets 道路）：
-
-```bash
-/Applications/Blender.app/Contents/MacOS/Blender \
-  --background --factory-startup \
-  --python blender/generate_scene.py -- \
-  --osm "/Users/que01/Desktop/南台子湖创新谷OSM.osm" \
-  --output "/tmp/scene-nogeojson.blend" \
-  --render "/tmp/preview-nogeojson.png"
-```
-
-Cesium GLB 导出：
-
-```bash
-/Applications/Blender.app/Contents/MacOS/Blender \
-  --background \
-  --python blender/export_cesium.py -- \
-  --blend "/tmp/scene.blend" \
-  --glb "/tmp/scene.glb" \
-  --metadata "/tmp/scene.json"
-```
-
 ## 文档

- [docs/input-cases.md](docs/input-cases.md) — 已验证的 OSM 输入案例
- [docs/changelog.md](docs/changelog.md) — 变更记录
+- [docs/input-cases.md](docs/input-cases.md) - 已验证的 OSM 输入案例
+- [docs/changelog.md](docs/changelog.md) - 变更记录