blender-texture-baking

纹理烘焙（Cycles）

执行模型位于 blender-core。UV 来自 blender-retopology-uv，材质来自 blender-pbr-materials。

一次调用

scripts/bake_maps.py -- --low SM_Crate --high Crate_high Crate_bolts --maps normal ao curvature id \
   --res 2048 --samples 64 --margin-px 16 --pack-orm --out //textures

自烘焙（程序化材质 → 纹理，不使用 --high）：--low SM_Crate --maps basecolor roughness metallic normal --pack-orm。 脚本会选择 GPU（OptiX/CUDA/HIP/Metal/oneAPI），并在必要时回退到 CPU；创建色彩空间正确的目标图像，清理临时节点，并保存为 T_<name>_<N|AO|CURV|BC|R|M|ORM...>.png。

准备检查清单（大多数烘焙问题都出在此处）

1. 低模：已展开 UV，且无重叠（堆叠/镜像的岛沿 +1 U 移动），在烘焙分辨率下留出 ≥ 8 px 的边距，并已应用缩放。
2. 硬边 = 低模上的 UV 缝。可以使用由烘焙处理渐变的平滑着色，也可以在 UV 缝处拆分硬边。切勿在 UV 岛内部设置硬边。
3. 按照引擎的方式三角化低模，或导出已三角化的网格。三角化方式不一致会导致着色接缝。
4. 高模应完全覆盖低模，且只略微凸出。浮件（螺栓、面板细节）可以悬在表面上方一点，但必须位于挤出距离范围内。
5. 命名：使用 X_low / X_high 配对。逐个部件烘焙，或将各部件分开（沿某个轴移动每对模型），避免相邻部件互相投射，然后再将它们放回原位。
6. 根据需要应用高模上的修改器（会自动评估 multires 和 subd）。

光线：挤出与笼体

• --extrusion（米）会将光线起点从低模表面向外推。其值必须大于高模凸出低模的最远距离。默认值为低模对角线的 2%；max_ray_distance 为挤出距离的 2 倍。
• 笼体（--cage Crate_cage）：拓扑相同的低模副本，经过膨胀（Displace/"Push"）。当均匀挤出失败时（尖锐的凹角、薄部件），请使用笼体。对于光线未命中的位置，可在笼体上局部编辑。
• 值太小：出现孔洞或细节缺失。值太大：网格的其他部分会被投射进来（相交、“重影”）。

贴图指南

贴图	空间	说明
normal	Non-Color、切线空间、OpenGL（Unreal 使用 --directx）	16 倍采样抗锯齿已足够；游戏使用 8 位 PNG 即可
ao	Non-Color	64–256 次采样；除非需要接触 AO，否则只烘焙高模（不包括地面）
curvature	Non-Color，0.5 = 平坦	从烘焙后的法线派生（凸面为白色 / 凹面为深色）；用于控制边缘磨损
id	sRGB	每种高模材质对应一种纯色；将材质用作遮罩
thickness	Non-Color	使用内部光线的 AO；颜色越深表示越薄；用于 SSS/透射遮罩
basecolor/metallic/opacity	通过 emission 覆盖	读取源材质的 Principled 输入（也包括程序化节点链）
roughness、emit、combined	Cycles 原生通道	combined = 光照结果（光照贴图、风格化）
position	float	渐变遮罩

ORM = R：AO，G：Roughness，B：Metallic，是 glTF/Unreal 标准。Unity 使用不同的打包方式（blender-pbr-materials）。

修复常见问题

现象	原因	修复方法
圆柱上出现波浪线	低模面数太少、平滑渐变	增加分段，使用笼子，或为低模增加更多支撑线
细节倾斜（螺栓歪斜）	射线方向跟随平均后的低模法线	设置硬边和缝线、使用笼子，或单独烘焙浮动体
出现黑色/杂乱区域	射线未命中或击中背面	增大挤出距离，修复翻转的法线（blender-asset-qa），检查高模覆盖范围
在引擎中能看到接缝	边距太小、硬边没有缝线、切线空间不同	2k 下边距 ≥ 16 px，在硬边处添加缝线，导出切线（MikkTSpace）
出现相邻部件的细节	部件距离太近	拆分烘焙，或按对象对分别烘焙
在引擎中呈现反转的绿色效果	OpenGL/DirectX 不匹配	对 Unreal 使用 --directx，或在纹理导入器中翻转 G 通道
出现阶梯/色带	8 位图像包含大面积平滑渐变	烘焙为 16 位（float_buffer），并在导出时添加抖动

烘焙非 PBR 数据

• 顶点颜色：使用活动颜色属性设置 bake.target = "VERTEX_COLORS"（适用于移动端和 Roblox-free 着色）。
• 光照贴图：使用场景灯光，将 combined 烘焙到 UV2（--uv-layer UVMap_Lightmap）。
• 多级精度（没有单独的高模对象）：设置 bake.use_multires=True、bake.type="NORMALS"|"DISPLACEMENT"|"VECTOR_DISPLACEMENT"、bake.use_lores_mesh=True，然后运行 bpy.ops.object.bake_image()。视口级别是低模，雕刻级别是高模。

注意事项

• 低模的每个材质中，目标图像都必须是活动的 Image Texture 节点（脚本会处理此设置）。
• 在 Cycles 中烘焙时会使用活动 UV 映射（通过 --uv-layer 进行选择）。
• 图像不会自动保存：使用 img.save() 或 save_render。重新加载后，打包或内部图像会消失。
• 5.2：Cycles 纹理缓存（.tx）用于渲染内存，不会影响烘焙结果。
• 先对低模和高模运行 blender-asset-qa，因为翻转的法线和浮动块是造成大多数烘焙杂乱问题的原因。