OSM GIS Pipeline

把 OSM XML 转为 QGIS 工程（osm2streets 风格道路）和可选的 Blender 3D 场景。

环境

需要：

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

首次使用：

cd /Users/que01/osm2streets-qgis-workflow
npm install

QGIS 管线（强依赖 osm2streets）

使用默认配置：

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

使用指定配置：

node scripts/build-osm2streets-qgis.js --config /path/to/config.json

命令行参数可以覆盖配置文件：

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

创建新区域配置可以从模板复制：

cp config/examples/template.json config/my-area.json

配置项

{
  "qgisApp": "/Applications/QGIS.app",
  "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
  }
}

• input：OSM XML 输入文件路径。
• outDir：osm2streets GeoJSON 中间产物输出目录。
• gpkg / project / preview：最终 GeoPackage、QGIS 工程、预览 PNG 路径。
• layerPrefix：QGIS 图层显示名称前缀（如 "osm2streets" → "osm2streets road surface"）。
• arrowScale：方向箭头几何缩放。
• osm2streets：osm2streets 引擎选项。

输出图层

GeoPackage 内会生成：

• road_surface
• intersection_surface
• sidewalks
• sidewalk_corners
• lane_separators
• center_lines
• vehicle_stop_lines
• lane_arrows_webscale
• crosswalks

QGIS 工程绘制顺序：路面在最底，车道线、斑马线、停止线和箭头在上。

Blender 3D 场景（可选）

osm2streets 道路几何为可选输入；不提供时回退到 OSM highway 折线。

生成场景：

/Applications/Blender.app/Contents/MacOS/Blender \
  --background --factory-startup \
  --python blender/generate_scene.py -- \
  --osm "/path/to/input.osm" \
  --geojson "/path/to/osm2streets_web_out" \
  --output "/path/to/scene.blend" \
  --render "/path/to/preview.png"

--geojson 为可选参数。使用 --office-overrides 指定应渲染为办公楼的 OSM way ID（逗号分隔）。

导出为 Cesium GLB：

/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"

详见 blender/README.md。

运行示例

以下命令已在本机验证通过。

QGIS 管线（使用汉阳区区块 OSM 数据）：

node scripts/build-osm2streets-qgis.js \
  --config config/hanyang-block.json

Blender 场景（含 osm2streets 道路几何）：

/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 道路）：

/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 导出：

/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 — 已验证的 OSM 输入案例
• docs/changelog.md — 变更记录