8.0 KiB
ModelTranslator 烘焙质量自适应优化设计
日期：2026-07-16
前置设计：
2026-07-16-model-decimate-bake-design.md2026-07-16-decimate-uv-seam-unwrap-design.md
背景
well1500.fbx（约 150 万面）与 well_uv.fbx（5000 面）的现有烘焙结果存在明显脏污。诊断排除了模型位置和缩放错位，确认问题由三类因素叠加：
- 低模保留了不再适配减面后拓扑的自定义平滑法线。低模着色法线与高模表面法线的中位偏差为 31.9 度，约 19.5% 的采样偏差超过 45 度。
- 自动射线使用包围盒对角线的 2%，本例为 0.0282；高低模 99% 的实际表面距离只有约 0.0041，过宽射线容易命中相邻结构。
- 低模 UV 检测到约 7.3% 重叠，且 UV 打包间距与 16px 烘焙扩边不匹配。
Blender 5 的无界面实验表明，清除低模自定义法线并按 66 度平滑后，法线偏差中位数可从 31.9 度降到 16.4 度，超过 45 度的采样可从 19.5% 降到 5.3%。UV seam 角度自适应降到 45 度时，当前模型可在保持合理利用率的同时把重叠降到约 1.3%。
目标
- 默认产出可用的 normal、AO、color、metallic、roughness 贴图，不再依赖用户反复试射线参数。
- 修复工具自己生成的低模法线，并能诊断、修复外部低模的异常法线。
- 对 UV 重叠、翻转、padding 不匹配建立烘焙前质量门。
- 保持现有命令和输出命名兼容；高级用户可以保留手工法线、UV 或显式指定射线。
- 在命令输出中给出足够的质量指标，便于定位后续模型特例。
非目标
- 不实现手工 cage 建模或高低模部件名称匹配。
- 不引入 xatlas 等外部依赖。
- 不改变源 FBX；所有自动修复只作用于当前 Blender 会话和最终输出 FBX。
- 不保证 5000 面可以无损表达任意 150 万面场景；工具会报告极端减面风险，但目标面数仍由用户决定。
方案选择
采用“自适应质量管线”：减面阶段生成适合烘焙的法线和 UV，烘焙阶段再次验证外部低模，并根据真实高低模距离计算射线。
未采用的方案：
- 仅降低固定射线百分比：改动小，但无法适配不同尺寸和细节密度。
- 强制显式 cage 或分部烘焙：质量上限更高，但需要额外资产约定，超出当前工具的零配置目标。
数据流
高模 FBX
-> model_decimate
-> 减面
-> 法线重建
-> 自适应 seam UV + padding
-> 低模 FBX
高模 FBX + 任意低模 FBX
-> model_bake
-> 包围盒/UV/法线诊断
-> 必要时仅在内存中修复低模
-> BVH 表面距离采样
-> 自适应射线
-> 五张贴图 + 包含最终法线/UV 的低模 FBX
法线处理
减面输出
Decimate 和最终三角化完成后：
- 清除导入 FBX 携带的 custom split normals。
- 调用 Blender 5 的
shade_smooth_by_angle，默认角度 66 度并保留已有锐边。 - UV 展开使用相同或更低的 seam 角度，保证所有法线硬边也是 UV 边界；允许 UV 有额外接缝。
- 输出法线修复前后的基础指标。
外部低模
烘焙阶段最多均匀采样 10000 个低模面中心，用高模 BVH 最近点及高模插值着色法线计算偏差：
- 中位偏差大于 25 度，或 P90 大于 50 度，判为异常。
- 异常时默认执行与减面阶段相同的法线重建。
--keep-low-normals跳过修复，但保留警告和指标。
该判断只用于决定是否修复，不会拒绝烘焙。源低模文件不会被覆盖，修复结果写入烘焙输出目录中的 FBX。
UV 处理
自适应 seam
替换当前单一 66 度 seam 尝试。按 60, 55, 50, 45, 40, 30 度从高到低展开，每次收集 islands、fill、flipped、overlap：
- overlap 不超过 2%；
- flipped 不超过 0.5%；
- fill 大于 0。
选择第一个达标结果，以优先减少 UV 岛数。所有候选都失败时回退 Smart UV Project，并报告原因和最终指标。
外部低模质量门
烘焙前复用同一指标：
- UV 缺失：保持现有行为，直接报错。
- overlap 超过 2% 或 flipped 超过 0.5%：默认用自适应 seam 重展。
--keep-low-uv跳过重展，但保留警告。
重展只改变输出 FBX。对唯一贴图烘焙而言，重叠 UV 无法可靠保留，因此自动修复是默认行为。
Padding
model_decimate.py新增--texture-size，默认 2048。- 两个 CLI 都新增
--padding，默认 8px。 - UV 打包 margin 由
padding / texture_size计算。 - Blender bake 的
margin使用同一个 padding 值。
当前 16px bake margin 与约 4px UV 间距的组合不再作为默认值。8px 是 2048 贴图在利用率和 mipmap 安全之间的折中，用户可按目标平台覆盖。
自适应射线
烘焙导入高低模并完成低模法线修复后，构建高模世界空间 BVH。最多均匀采样 10000 个低模面中心，统计到高模最近表面的距离。
自动射线计算：
base = P99(distance) * 1.5
lower = bbox_diagonal * 0.0005
upper = bbox_diagonal * 0.01
ray = clamp(base, lower, upper)
max_ray_distance = ray * 2
- 显式
--ray-distance完全绕过自动估算，保持最高优先级。 - P99 被上限截断时打印警告，提示检查模型对应关系或显式指定射线。
- BVH 无有效采样时停止烘焙并返回明确错误，不回退到原来的 2% 固定值。
对当前 well 模型，预期自动射线约为 0.0062，而不是 0.0282。
CLI 与兼容性
model_decimate.py 新增：
--texture-size 2048
--padding 8
--smooth-angle 66
model_bake.py 新增：
--padding 8
--smooth-angle 66
--keep-low-normals
--keep-low-uv
现有参数、默认输出目录和文件命名不变。内部 Blender 脚本 argv 同步追加对应值；旧 CLI 调用无需修改。
指标与错误处理
MT_SUMMARY 增加：
normal:{repaired, before_median, before_p90, after_median, after_p90}uv: 现有字段外增加{repaired, seam_angle, padding}ray:{source, distance_p99, value, capped}
CLI 用短行打印这些指标。自动修复、保留异常数据和射线上限截断使用警告；缺少 UV、BVH 无命中、无 mesh 等无法产生可信结果的情况继续返回错误。
测试
所有纯决策逻辑先按 TDD 添加失败测试：
- 百分位与射线 clamp；
- 法线异常判定；
- seam 候选选择；
- padding 到 UV margin 的换算；
- keep 参数下的决策分支。
Blender 冒烟验证使用 well1500.fbx + well_uv.fbx，写入未跟踪的临时输出目录：
- 减面输出仍为 5000 面（允许现有 3% 容差）。
- UV overlap 不超过 2%，flipped 不超过 0.5%。
- 法线修复后的 median 和 P90 均低于修复前，median 不高于 20 度。
- 自动射线位于 0.004 到 0.010 之间，并报告为 adaptive。
- 低模 FBX 和五张指定尺寸 PNG 均存在且非空。
- 查看 normal、AO、color，确认没有大面积跨部件投射或异常空洞。
- 运行 ModelTranslator 全部现有单元测试，确保转换器行为无回归。
风险与控制
- BVH 会增加一次高模内存占用和数秒分析时间；采样上限控制低模侧开销，相对 Cycles 烘焙可接受。
uv.select_overlap是 Blender 质量指标，可能对边界接触较敏感；候选选择同时检查翻转和 fill，真实模型冒烟作为最终质量门。- 自动法线或 UV 修复会改变输出低模的顶点着色表现和 UV，但不会修改源文件，并提供 keep 参数退出自动行为。
- 单一全局射线仍不等价于手工 cage；极密集或多层模型后续可扩展显式 cage，此次不提前增加接口。
验收标准
- 无参数运行现有三步命令仍可完成。
- 当前 well 案例自动触发法线和 UV 修复，射线改为真实距离驱动。
- 自动指标满足测试章节中的数值门槛。
- 输出贴图经视觉检查明显减少彩色法线噪声、UV 串色和跨部件投射。
- README 说明新默认行为、覆盖参数和质量指标。