166 lines
4.8 KiB
Markdown
166 lines
4.8 KiB
Markdown
# 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 放置元数据和示例代码
|
||
- `<area-id>-cesium-preview.html`：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
|
||
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages preview
|
||
```
|
||
|
||
`intermediates` 会生成 osm2streets GeoJSON、GeoPackage、QGIS 工程和 QGIS 预览图。`blender` 使用 OSM 和 osm2streets GeoJSON 生成 `.blend`/`.png`。`cesium` 从 `.blend` 导出 `.glb`/`.json`，并生成 Cesium 预览 HTML。`preview` 只在已有 `.glb/.json` 时补生成 HTML。
|
||
|
||
## 区域配置
|
||
|
||
新区域从模板复制：
|
||
|
||
```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",
|
||
"cesiumPreview": "/absolute/path/to/custom-preview.html"
|
||
}
|
||
}
|
||
```
|
||
|
||
预览 Cesium 页面时，需要在输出目录启动 HTTP 服务，避免浏览器拦截本地文件请求：
|
||
|
||
```bash
|
||
cd outputs/my-area
|
||
python3 -m http.server 8765
|
||
```
|
||
|
||
然后打开 `http://localhost:8765/my-area-cesium-preview.html`。
|
||
|
||
## 实验：车辆巡航
|
||
|
||
`preview` 和 `cesium` 阶段会额外生成 `<area-id>-vehicle-route.json` 和 `<area-id>-vehicle-car.gltf`。路线文件从 OSM bounds 内的可行驶 `highway` way 提取道路中心线，并向右偏移约 1.3 米作为车辆行驶线，避免车辆压道路中心线。Cesium 预览页会加载最长道路段并显示一辆实验车辆循环巡航。
|
||
|
||
这是用于验证高精度巡航可用性的预览层功能，不会改变 Blender/GLB 主资产本身。车辆模型是无 logo 的轻量预览模型，生成在输出目录中。
|
||
|
||
## 已沉淀区域
|
||
|
||
- `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) - 变更记录
|