# OSM Asset Pipeline

把单个园区/片区 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

首次使用：

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

## 主流程

默认构建南台子湖创新谷样例：

```bash
npm run build
```

指定区域配置：

```bash
npm run build:area -- --config config/areas/hanyang-block.json
```

只跑部分阶段：

```bash
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/areas/my-area.json
```

核心配置：

```json
{
  "id": "my-area",
  "input": "/absolute/path/to/input.osm",
  "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": ""
  }
}
```

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

## 已沉淀区域

- `config/areas/nantaizi-lake-innovation-valley.json`
- `config/areas/hanyang-block.json`

## 低层命令

通常优先使用 `npm run build:area`。如果只想调试旧 QGIS/osm2streets 阶段，可以直接运行：

```bash
npm run build:qgis -- --config config/hanyang-block.json
```

Blender 低层命令：

```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" \
  --tree-style natural
```

Cesium GLB 低层导出：

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

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

## 文档

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