osmWorkflow/.trellis/tasks/08-25-rc-p3-render-separation/research/native-layer-consumption-matrix.md

Native Road 图层消费矩阵

调研日期：2026-08-25

证据

• 编译器在 scripts/compile-native-roads.js:57,65-76 声明并写出 12 个图层。
• Blender 在 blender/generate_scene.py:796-834 遍历 catalog.NATIVE_ROAD_LAYERS，只消费其中 10 个图层。
• 当前映射及基础高度来自 blender/osmassets/catalog.py:53-64 与 ROAD_LAYERS。

当前消费与 manifest 目标

编译器 source	当前 Blender 行为	当前材质槽 / z 来源	manifest 目标
road_surface	直接渲染	road_surface / ROAD_LAYERS.road_surface	role: surface, materialLayer: road_surface
edge_lines	直接渲染	lane_separators / ROAD_LAYERS.lane_separators	role: marking, materialLayer: lane_separators
intersection_surface	直接渲染	intersection_surface / ROAD_LAYERS.intersection_surface	role: surface, materialLayer: intersection_surface
sidewalk_surface	直接渲染	sidewalks / ROAD_LAYERS.sidewalks	role: surface, materialLayer: sidewalks
lane_separators	按 color 分流	非 yellow: lane_separators; yellow: native_lane_separator_yellow; z 取 lane_separators	role: marking, materialLayer: lane_separators, splitBy.color（yellow 特例）
center_lines	按 color 分流	非 white: center_lines; white: native_center_line_white; z 取 center_lines	role: marking, materialLayer: center_lines, splitBy.color（white 特例）
direction_arrows	直接渲染	lane_arrows_webscale / ROAD_LAYERS.lane_arrows_webscale	role: marking, materialLayer: lane_arrows_webscale
turn_arrows	直接渲染	lane_arrows_webscale / ROAD_LAYERS.lane_arrows_webscale	role: marking, materialLayer: lane_arrows_webscale
crosswalks	直接渲染	crosswalks / ROAD_LAYERS.crosswalks	role: marking, materialLayer: crosswalks
vehicle_stop_lines	直接渲染	vehicle_stop_lines / ROAD_LAYERS.vehicle_stop_lines	role: marking, materialLayer: vehicle_stop_lines
lane_centerlines	不进入 Blender 遍历	无	role: semantic，Blender 跳过
connectors	不进入 Blender 遍历	无	role: semantic，Blender 跳过

结论与实施约束

• manifest 必须声明全部 12 个编译器图层，不能再用“未出现在列表中”表达不渲染。
• role: semantic 的两个图层不得读取 GeoJSON 或创建 Blender 几何。
• splitBy 至少需表达属性 color 的精确匹配与默认分支，且分流后沿用同一个基础材质槽的 z 值。
• Blender 消费 manifest 时，未知 materialLayer、缺失 source 文件、或 source 未在 manifest 声明都必须报错；不能静默跳过。