# OSM GIS Pipeline

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

## 环境

需要：

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

首次使用：

```bash
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
```

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

```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
```

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

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

### 配置项

```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 折线。

生成场景：

```bash
/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：

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

详见 [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) — 变更记录