Files
osmWorkflow/.trellis/spec/blender/asset-generation.md

18 KiB
Raw Permalink Blame History

资产生成

适用:改动 Blender 侧的几何构建、材质、实例化,或往场景里加新资产。 贯穿全篇的约束是两条:压低对象数(GLB 要能在浏览器里跑)和 构建必须确定性(parity 校验的前提)。


MeshBatch:几何构建的主力

mesh.py:1-9 说明了它为什么存在:场景的绝大部分是平面多边形和拉伸棱柱, 把它们批进一个 mesh datablock 能同时压低 Blender 对象数和导出 glTF 的节点数。

用法固定为「累积 → 一次 finish()」:

batch = MeshBatch("Lake Surface", water_c, water_mat)
batch.add_polygon(ring, 0.10)
batch.finish()                    # water.py:12-14

三条内建行为

  1. 自动去掉重复的闭合点(mesh.py:41-42, 55-56)。传闭合环或开放环都行, 与 geom.py 的宽容度一致
  2. 退化输入静默返回:len(ring) < 3 直接 return,不抛
  3. 空批次 finish() 返回 None(mesh.py:66-67),不产生空对象

名字前缀是承重的

# Foliage reads as blobby volume, so it wants smooth normals; the built
# environment wants its facets. The name prefix is the discriminator.
if self.name.startswith("Tree_") or self.name.startswith("Scrub_"):
    for polygon in mesh.polygons:
        polygon.use_smooth = True                          # mesh.py:72-77

改植被对象的命名前缀会静默改变着色。加新的植被类资产时要么沿用 Tree_ / Scrub_ 前缀,要么显式扩展这个判断。

单材质约束

一个 MeshBatch 只挂一个材质(mesh.py:64)。需要多材质就开多个 batch—— 这也正是材质顺序决定 GLB 索引的地方。

便捷包装

make_prism / add_roof(mesh.py:83, 89)是「单个形体」的一次性包装,内部就是 MeshBatch + finish()。只放一个形体时用它们,批量累积时直接用 MeshBatch。


材质:声明与构建分离

catalog.MATERIALS          声明「是什么」    纯 Python,无 bpy
      │
      ▼  materials.from_spec(spec)          materials.py:198
真实的 bpy.types.Material                    只在 Blender 内

这个拆分让 catalog 能被任何不启动 Blender 的工具读取(materials.py:3-7)。

kind 选构建器

kind 走哪条路 必填字段
solid make_material() name、color
textured make_textured_material() name、diffuse、normal、scale

solid 可以再叠 procedural(噪声驱动的基色和凹凸,from_spec 里判断)。 可选字段一律 spec.get(key, 默认值)——加新的可选字段不要改已有条目。

加一种材质

  1. catalog.MATERIALS 末尾追加一个条目(顺序决定 GLB 材质索引)
  2. 若 kind 是 textured,贴图放 assets/textures/(materials.py:14 的 TEXTURE_ROOT)
  3. generate_scene.py 里用 material_from_spec(catalog.MATERIALS["<key>"]) 取
  4. 若这个材质在 Cesium 里需要调色,把 cesium 子契约写在同一个 MATERIALS 条目里。materials.from_spec() 会把它序列化到 material["cesium_export"],导出器优先读这个属性

颜色是线性 RGB

catalog 里的 color 是 Blender 的线性值,不是 sRGB hex,也不从 scripts/lib/scene-layers.js 换算。两套配色独立调过,理由见 图层表。


实例化:树

tree.py:1-8 的模式——import 一次 → bake 朝向 → 每棵树只 link 一个轻对象复用 同一个 datablock:

Nothing is duplicated per tree, so the .blend and the exported GLB carry each mesh and each texture exactly once no matter how many trees are planted.

TreeVariant 是 (meshes, height, base_z) 三元组(tree.py:62-65):

  • height — 变体自身的高度,目标高度除以它得到缩放系数
  • base_z — 变体自身的地面线,取负乘以缩放就能把树干落到 z=0, 不管源文件把原点放在哪(tree.py:301-303)

assemble() 返回种植数量,0 表示模型缺失或 style 未知,调用方据此回退到程序化 树。

Shapespark 是当前模型树样式

当前唯一模型树 style 是 shapespark,资产来自 assets/models/custom/shapespark_plants/tree-*/model.gltf。该目录是从 Shapespark low-poly plants kit 拆分出的单植物 glTF/bin,贴图共享在 assets/models/custom/shapespark_plants/textures/。

tree.py 加载 12 个 tree 变体,每个变体 import 一次、bake 成共享 mesh datablock; OSM 树实例只 link 这些 mesh。变体选择必须确定性,当前用 stable instance index 经过 golden-turn 序列选变体:

variant = variants[int(((index * GOLDEN_TURN) % 1.0) * len(variants))]

拆分 glTF 会让 Blender 生成 branch-01.001、branch-01.002 这类重复材质名; tree.py 必须按 base name 去重材质槽,否则 export_cesium.py 会为同一张贴图重复 bake Cesium 材质。

已删除的模型树 style 有记录

tree.py:18-25 记着 polyhaven style 被删的原因(LOD1 对象不是整棵树,是给几何节点 散布用的树枝和叶簇,直接种出来是一地树枝,连同 78MB 资产一起删了)。

apple 和 fattree style 已在 Shapespark 方案被用户接受后删除:apple 需要强抠图、 法线和 Cesium 曝光补偿,远近观感不如 Shapespark 稳定;fattree 视觉风格不匹配。 对应资产目录 assets/models/speedtree/apple_low/ 和 assets/models/lyrog/fattree/ 也已删除。

这类"试过、不行、为什么"的记录要保留。 删掉它,下一个人会重新引入同一个资产。

灌木边缘实例有性能预算

generate_scene.py 的 scrub 不是只有贴地面:natural=scrub 会先生成 Scrub_<way_id> 地面覆盖,再沿边界实例化 assets/models/custom/shapespark_plants/bush-03/model.gltf (add_scrub_edge_bushes()),并在大 scrub 面内部稀疏补树。

这些 bush 是共享 mesh 的多 node 实例。共享 mesh 能压 GLB 体积,但 Cesium 近景 Follow 仍要处理每个 node / draw。nantaizi-lake-innovation-valley 曾经用 SCRUB_BUSH_SPACING = 0.82、SCRUB_BUSH_LIMIT_PER_PATCH = 180,结果一个场景有约 707 个 bush nodes;车辆 Follow 到灌木密集区域时明显卡顿。当前预算是:

SCRUB_BUSH_SPACING = 1.8
SCRUB_BUSH_LIMIT_PER_PATCH = 60

在 nantaizi 上约 266 个 bush nodes,scrub 地面覆盖仍保留。旧高模 bush 和 rejected bush_low 资产已删除:前者太重,后者几何从 63,762 vertices / 67,536 indices 降到 4,044 / 4,050,但用户实测视觉效果不理想,不能作为默认方向。

不要只为了“更满”把间距调回 1m 以下;那是在把预览流畅度换成近景装饰密度。若确实 需要更密的灌木,先做一个视觉可接受的低模 bush,或做显式 LOD / instancing 方案,再 跑 nantaizi 的 Blender/Cesium/preview 验证。继续压 GLB 总体体积应考虑贴图尺寸/KTX2, 而不是只减面。


确定性:用无理数周期代替 RNG

这是全仓最容易被无意破坏的约定。tree.py:290-292:

# Irrational periods stand in for an RNG: no repeat over any realistic
# tree count, and a pure function of the index, so rebuilding an area
# plants the identical forest.
scale_wobble = 1.0 + SCALE_JITTER * math.sin(index * 2.399963)
yaw          = ((index * GOLDEN_TURN) % 1.0) * math.tau
tilt_x       = TILT_JITTER * math.sin(index * 1.114517)
tilt_y       = TILT_JITTER * math.cos(index * 0.927295)

黄金角 GOLDEN_TURN(tree.py:47-49)让相邻的树朝向永不重复也永不成规律—— 一排树看起来像种的,不像盖章盖的。

规则:需要"随机"外观时,用 index 的纯函数(无理数周期 / 黄金角), 或者收一个显式 seed(geom.sample_polygon_interior 就是这么做的)。

绝不要用无种子的 random 或任何时间相关的量—— 重建同一片区域必须得到逐字节相同的结构,否则 parity 校验永久性地红。


Cesium 导出:一层独立的调色

export_cesium.py:1-9:创作用的场景刻意使用了一些 Blender 专有节点 (草地 tint、程序化树冠变化),而 glTF 的材质词汇小得多。所以导出器 新建临时的、仅供导出的 PBR 材质,展 UV,把引用到的图片全部内嵌进 GLB。

导出材质带 EXPORT_PREFIX = "Cesium " 前缀(export_cesium.py:30), 这样第二遍扫到实例化网格的共享材质槽时能认出自己的产物、跳过不重复处理。

模型保持在局部 ENU 坐标系(X 东、Y 北、Z 上),靠伴生 JSON 配合 Cesium.Transforms.eastNorthUpToFixedFrame 摆放。

WGS84 ENU 坐标契约

Blender 中所有经纬度几何必须通过 osmassets.osm.Projector 转换。该转换必须与 Cesium 的 eastNorthUpToFixedFrame(anchor) 使用同一个 WGS84 椭球语义:先将经纬度转换为 ECEF,再将相对锚点的向量投影到 East/North 轴。禁止用固定 111320 m/deg 的 equirectangular(等距圆柱)近似生成场景坐标。

固定米/度近似只会在锚点附近碰巧重合;纬向比例与 WGS84 实际比例不同,误差会随离锚点 距离增长。表现为 Cesium Entity 路线在部分道路居中、在其他道路相对整个 GLB 路面同向 平移。只验证 route 与 GeoJSON 自洽无法发现此问题,必须重新生成 blender,cesium,preview 并在最终 Cesium 画面中核对。

修改 Projector 后至少执行:

python3 -m unittest blender.tests.test_pure
npm run build:area -- --config config/areas/<area>.json --stages blender,cesium,preview

blender.tests.test_pure.ProjectorTest 必须断言锚点为原点、East/North 方向正确,以及局部 经纬度增量符合 WGS84 椭球曲率半径。

Cesium contract

新生成场景的 Cesium 导出调色写在 catalog.MATERIALS[*]["cesium"],由 materials.from_spec() 保存成材质自定义属性 material["cesium_export"]。导出器打开 .blend 后优先读这个属性,不 import catalog。

cesium 子契约字段:

字段 作用
tint diffuse 贴图导出前往目标颜色混合
metallic 覆盖导出 PBR metallic
base_color 直接替换导出基色,并禁用 diffuse/normal 图
emission 自发光兜底

export_cesium.py 仍保留 EXPORT_TINTS、EXPORT_METALLIC_OVERRIDES、 EXPORT_BASE_COLOR_OVERRIDES、EXPORT_EMISSION_OVERRIDES 四张按材质名字符串匹配的表, 但它们只是旧 .blend 兼容回退。新材质不要只写旧表。

交通信号倒计时字体

assets/fonts/7LED-1.ttf 是项目纳入版本管理的倒计时字体。它的字形是反向轮廓:可见 的 LED 段是字体轮廓里的孔,而不是普通实心文字。因此 Blender 侧不能直接把文字曲线 转成普通填充面(会得到“发光背景+黑色数字”),也不能依赖曲线描边。正确做法是在 blender/osmassets/traffic_signals.py 中采样负 Bezier 轮廓,构造带前后盖面的挤出棱柱, 使 LED 段成为实心发光几何。数字 mesh 必须先在 Blender 中单独渲染确认,再进入 Cesium 导出;导出器出现“Could not calculate tangents”只表示这些无 UV 的纯色网格没有切线, 不等同于倒计时集合为空或几何失败。

共享与拆分动态资产

倒计时数字按 phase group 共享 20 个数字 mesh(0-19),不要按信号灯复制网格。Cesium 阶段必须生成三个动态 GLB:traffic-signals-dynamic.glb 只含灯珠, traffic-signals-countdown-0.glb 和 traffic-signals-countdown-1.glb 分别含两个相位组的 倒计时节点。两个倒计时模型与灯珠模型使用同一个 modelMatrix,浏览器只切换当前数字 节点,并给整个倒计时模型设置 color + ColorBlendMode.REPLACE,从而让字色跟随当前 红/黄/绿相位且不增加每个灯的材质/几何副本。

导出器按完整材质名包含 Countdown Group 0 / Countdown Group 1 判断分组;不能用 集合名的精确相等比较,否则实际材质名 Traffic Signal Countdown Group 0 会被误判为 空集合。

为什么新资产总是"发黑"

export_cesium.py:38-54 记录了这个反复出现的问题:

Cesium 的默认光照偏白,场景里每一个材质都被手工提亮过——草往亮绿混 72%、 带肋墙面往白混 86%、建筑自发光 0.18。一个没调过的新资产是唯一如实渲染的东西, 放在旁边就显得发黑。

所以加新资产时,"它在 Blender 里看着对"不代表在 Cesium 里对,必须在 catalog.MATERIALS[*]["cesium"] 里给它配一份调校。

抠图植被走的是另一套(FOLIAGE_ALBEDO_GAIN = 2.1 + FOLIAGE_SATURATION = 1.75, :55, 66),用增益而不是 tint——因为那是一张同时装着叶片、树皮、果实的图集, 往绿色混会把树干也染绿。增益保留色相关系,只把整体曝光抬到和邻居一致。

FOLIAGE_EMISSION = 0.25 的职责只是给背光面兜底,不是主要提亮手段 (:32-36)。想让植被更亮就调增益,别调自发光。


反模式

反模式 后果
每个形体建一个对象而不用 MeshBatch 对象数与 glTF 节点数爆炸
改 Tree_ / Scrub_ 命名前缀 平滑着色静默失效
用无种子 random 或时间量做抖动 parity 校验永久红
每棵树复制一份 mesh/贴图 .blend 与 GLB 体积按棵数线性膨胀
直接 append vendored 资产的材质 alpha-clip 缺失,树冠渲染成一块
删掉"试过不行"的注释 下一个人重新踩同一个坑
从 scene-layers.js 的 hex 换算 Blender 颜色 抹掉独立调过的配色
用固定米/度比例投影经纬度 GLB 与 Cesium Entity 随离锚点距离产生位置漂移
加新资产不配 Cesium 调色 Cesium 里显得发黑
靠调 FOLIAGE_EMISSION 提亮植被 用错了旋钮,该调 albedo gain
在 MATERIALS 中间插入条目 GLB 材质索引整体平移
直接用 Cesium Model.getMaterial().setValue() 改普通 glTF PBR 材质 运行时数字仍保持原色,不能实现相位字色
每个信号灯各自生成 0-19 全套倒计时 mesh 节点和几何按信号数量线性膨胀;应按两个 phase group 共享

Cesium 导出准备:依赖图更新边界

export_cesium.py 的 prepare_independent_meshes(candidates) 只优化可证明为对象局部的 准备工作。Blender 的 bpy.ops 调用前后会更新 view layer;对约 1,744 个对象逐个调用 选择、修改器及模式切换会重复评估整个场景。实测原导出 173 秒中绝大部分用于更新, 采用以下边界后约 16 秒;不能全局 monkey-patch 或禁用 _view_layer_update。

  • select_only(obj) 用选择数据 API;空修改器栈在改变上下文前直接返回。
  • 原有修改器仅允许已证明局部的 BEVEL 进入预处理;其他类型保持原顺序回退。
  • batch_triangulate_meshes 使用真正的 Triangulate 修改器及当前 Blender 默认值, 一次评估后通过 new_from_object(..., preserve_all_data_layers=True) 获取结果。 必须先收集所有结果,再替换原网格;替换/删除修改器会使 evaluated 数据失效。 共享、形状键、自定义法线、库链接、fake-user 保留网格不进入这个复制路径。
  • mesh_has_multiple_users 按 Blender ID_REAL_USERS 判断:users - int(use_fake_user)。 对多个真实用户的网格,原修改器应用本来就失败,提前跳过保持原拓扑与共享关系。
  • 缺 UV 的已准备网格在临时小场景逐对象调用原 smart_project,通过 window.scene 保持编辑模式上下文一致;有 UV 的模型资产不重展。退出必须恢复窗口场景和 view layer, 删除临时场景。无法满足条件时使用原操作路径。

验证使用 blender/tools/check_export_preparation.py -- --baseline <original_export_cesium.py> 在真实 Blender 内比对 control、共享网格、形状键、自定义法线、fake user、Bevel 和 Boolean 依赖回退。真实区域还必须比全部主/分类/动态 GLB 的结构摘要、解码后的索引、 坐标、UV、法线、切线、材质与贴图哈希。不要只用顶点数相同证明视觉一致。

Blender 4.5 的 Triangulate 默认 quad method 是 shortest diagonal,并非 BEAUTY。 直接换成 BMesh BEAUTY 会改变拆面和后续 UV,不能称为等价提速。任何替代算法必须先 核对源码默认值和属性转换路径。详见任务 09-17-cesium-export-performance/research/。

第三方资产导入的源文件边界

第三方 Blend 只属于一次性入库工具的输入,不能成为 build:area 或 Cesium 预览的运行时依赖。 完成拆分后,仓库必须包含可直接消费的 glTF/bin、共享贴图、manifest 和人工预览;原始下载文件可 以删除。导入工具应将源文件路径作为显式 --source 参数,manifest 最多保留源文件名作溯源, 不能写死用户 Downloads 目录。

删除原始文件前必须确认入库资产已通过结构验证和人工预览;删除后若需重新导入,必须重新取得 同一 Blend 与其外部贴图。blender/tools/split_lowpoly_cars.py 是这一约定的实例,不参与区域 构建阶段。


相关