7.1 KiB
Config：区域配置
覆盖
config/areas/*.json、config/examples/template.json、config/default.json。 无运行时——这是管线三层共同消费的契约，改一个字段会同时影响 Node、Blender、 预览页。
两层配置
用户只写第一层，第二层是机器生成的中间产物：
config/areas/<id>.json ← 你写的
│ build-area.js: normalizeAreaConfig() 补默认值 + 推导 14 个输出路径
▼
<areaDir>/_pipeline/osm2streets-qgis.config.json ← 生成的，不要手改
│
▼ build-osm2streets-qgis.js / reimport-gpkg.js
派生配置落在 _pipeline/ 而不是临时目录——构建失败时它还在，可以直接拿去复现。
config/default.json 和 config/hanyang-block.json 是低层脚本
（npm run build:qgis）用的旧格式配置，与 config/areas/ 不是一回事。
新工作一律用 config/areas/。
新增一个区域
cp config/examples/template.json config/areas/my-area.json
改 id 和 input 就能跑。其余全有默认值。
字段全表
顶层
| 字段 | 必填 | 默认 | 说明 |
|---|---|---|---|
id |
✅ | — | 区域标识。同时是默认输出目录名和全部产物的文件名 stem |
input |
✅ | — | OSM XML 的绝对路径。不存在直接抛错 |
outputRoot |
<repo>/outputs |
输出根目录 | |
qgisApp |
/Applications/QGIS.app |
也可用环境变量 QGIS_APP |
|
blenderApp |
/Applications/Blender.app |
||
stages |
见下 | 各阶段默认开关 | |
qgis |
见下 | QGIS/osm2streets 旋钮 | |
osm2streets |
见下 | 透传给 osm2streets 的选项 | |
blender |
见下 | Blender 侧选项 | |
outputs |
从 id 推导 |
输出路径覆盖，逃生舱 |
路径一律绝对。normalizeAreaConfig 对每一项都做 path.resolve，相对路径会
相对于进程 cwd 解析，不是相对于配置文件——所以别用。
stages
| 字段 | 默认 | 说明 |
|---|---|---|
intermediates |
true |
旧名 qgis 仍被接受 |
blender |
true |
|
cesium |
true |
reimport 和 preview 在这里配也没用——normalizeAreaConfig:117-118 把它们
硬编码为 false，只能靠 --stages 显式请求。
恢复动作（reimport）和补丁动作（preview）不该被一份配置文件变成默认行为。
--stages 会整体覆盖这里的默认值。
qgis
| 字段 | 默认 | 说明 |
|---|---|---|
arrowScale |
0.8 |
导出前对 osm2streets 车道箭头多边形的缩放 |
arrowMergeTriangles |
true |
把箭头的三角网合并成一个合法多边形。保留原箭头形状和转向，同时消掉共享三角边处的渲染缝隙 |
arrowOutlineSimplifyMeters |
0.05 |
去掉合并后箭头外轮廓上的亚分米级折角。默认值刚好去掉两个畸形尾顶点而不动箭头头部，剩下的尾边与杆身垂直 |
intersectionCornerSourceMaxDimensionMeters |
2.6 |
只保留小尺寸的 sidewalk corner 多边形。大的路口标记多边形不当人行道处理，因为它们会盖住可行驶的路口 |
clipPad |
0.002 |
送进 osm2streets 的裁剪框外扩（度） |
canvasPad |
0.001 |
QGIS 画布范围外扩（度） |
previewPad |
0.0007 |
预览图范围外扩（度） |
canvasExtent |
null |
显式画布范围，覆盖 canvasPad |
previewExtent |
null |
显式预览范围，覆盖 previewPad |
layerPrefix |
"osm2streets" |
QGIS 图层名前缀 |
三个 pad 单位是度不是米，且必须 >= 0（build-osm2streets-qgis.js:49-53 校验）。
arrowScale 必须 > 0。
这四个 arrow/corner 旋钮的默认值都是调出来的，改之前先看 README 里记的理由。 尤其
arrowOutlineSimplifyMeters——调大会开始削箭头头部。
osm2streets
原样透传给 JsStreetNetwork 构造函数（build-osm2streets-qgis.js:77）。默认：
{
"debug_each_step": false,
"dual_carriageway_experiment": false,
"sidepath_zipping_experiment": false,
"inferred_sidewalks": true,
"osm2lanes": true
}
⚠️ 给了就整体替换，不做逐字段合并（build-area.js:132：raw.osm2streets || {...}）。
只想改一个开关也必须把五个字段全写上，否则其余四个会退到 osm2streets 自己的默认值。
blender
| 字段 | 默认 | 说明 |
|---|---|---|
treeStyle |
"natural" |
合法值见 generate_scene.py 的 TREE_STYLES（natural、procedural、shapespark） |
officeOverrides |
"" |
旧名 office_overrides 仍被接受 |
outputs（逃生舱）
默认全部从 id 推导为 <outputRoot>/<id>/<fileStem>.<ext>。需要定制时逐项覆盖：
{
"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"
}
}
可覆盖的键（build-area.js:87-102）：areaDir、fileStem、geojsonDir、gpkg、
qgisProject、qgisPreview、blend、render、glb、metadata、cesiumPreview、
vehicleRoute、vehicleModel、pipelineDir。
优先改 fileStem 或 areaDir——它们能一次性影响全部派生路径。逐个覆盖容易漏。
加一个配置字段
normalizeAreaConfig（build-area.js:74）里加进对应的分组，用??不用||（false/0可能是合法值）- 只写两级 fallback：
raw.<group>?.<key> ?? 默认值。 不要制造新的顶层平铺别名——那三级写法是历史兼容，不是模式 - 若要传给低层脚本，加进
writeDerivedConfig（:189）的derivedConfig对象 - 若是数值，在消费侧加
Number.isFinite+ 范围校验，在任何副作用之前 - 更新
config/examples/template.json - 更新本文档的字段表
若新字段产出新文件，同时在 outputs 里加一行路径推导。
已沉淀的区域
config/areas/nantaizi-lake-innovation-valley.json（默认构建目标）config/areas/hanyang-block.json
两者都是 parity 校验的样本区域（parity.js:26 的 DEFAULT_AREAS）——
改动它们会影响基线比对。
反模式
| 反模式 | 后果 |
|---|---|
| 用相对路径 | 相对 cwd 解析，换个目录跑就错 |
手改 _pipeline/*.config.json |
下次构建被覆盖 |
只写 osm2streets 的一个字段 |
其余四个静默退到 osm2streets 默认值 |
布尔字段用 || 兜底 |
false 被翻转 |
| 给新字段造顶层平铺别名 | 扩大历史包袱 |
逐个覆盖 outputs 而不用 fileStem |
漏掉某个产物路径 |
在 stages 里配 reimport / preview |
无效，被硬编码为 false |
| 加数值字段不做范围校验 | 错配置在中途才崩，输出已被破坏 |