ModelTranslator: 烘焙质量自适应优化设计

2026-07-16 14:52:03 +08:00
parent 0ba883b8d0
commit e693a2edcf
1 changed files with 199 additions and 0 deletions
@@ -0,0 +1,199 @@
+# ModelTranslator 烘焙质量自适应优化设计
+
+日期：2026-07-16
+
+前置设计：
+
+- `2026-07-16-model-decimate-bake-design.md`
+- `2026-07-16-decimate-uv-seam-unwrap-design.md`
+
+## 背景
+
+`well1500.fbx`（约 150 万面）与 `well_uv.fbx`（5000 面）的现有烘焙结果存在明显脏污。诊断排除了模型位置和缩放错位，确认问题由三类因素叠加：
+
+1. 低模保留了不再适配减面后拓扑的自定义平滑法线。低模着色法线与高模表面法线的中位偏差为 31.9 度，约 19.5% 的采样偏差超过 45 度。
+2. 自动射线使用包围盒对角线的 2%，本例为 0.0282；高低模 99% 的实际表面距离只有约 0.0041，过宽射线容易命中相邻结构。
+3. 低模 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 或分部烘焙：质量上限更高，但需要额外资产约定，超出当前工具的零配置目标。
+
+## 数据流
+
+```text
+高模 FBX
+  -> model_decimate
+     -> 减面
+     -> 法线重建
+     -> 自适应 seam UV + padding
+     -> 低模 FBX
+
+高模 FBX + 任意低模 FBX
+  -> model_bake
+     -> 包围盒/UV/法线诊断
+     -> 必要时仅在内存中修复低模
+     -> BVH 表面距离采样
+     -> 自适应射线
+     -> 五张贴图 + 包含最终法线/UV 的低模 FBX
+```
+
+## 法线处理
+
+### 减面输出
+
+Decimate 和最终三角化完成后：
+
+1. 清除导入 FBX 携带的 custom split normals。
+2. 调用 Blender 5 的 `shade_smooth_by_angle`，默认角度 66 度并保留已有锐边。
+3. UV 展开使用相同或更低的 seam 角度，保证所有法线硬边也是 UV 边界；允许 UV 有额外接缝。
+4. 输出法线修复前后的基础指标。
+
+### 外部低模
+
+烘焙阶段最多均匀采样 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 个低模面中心，统计到高模最近表面的距离。
+
+自动射线计算：
+
+```text
+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` 新增：
+
+```text
+--texture-size 2048
+--padding 8
+--smooth-angle 66
+```
+
+`model_bake.py` 新增：
+
+```text
+--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`，写入未跟踪的临时输出目录：
+
+1. 减面输出仍为 5000 面（允许现有 3% 容差）。
+2. UV overlap 不超过 2%，flipped 不超过 0.5%。
+3. 法线修复后的 median 和 P90 均低于修复前，median 不高于 20 度。
+4. 自动射线位于 0.004 到 0.010 之间，并报告为 adaptive。
+5. 低模 FBX 和五张指定尺寸 PNG 均存在且非空。
+6. 查看 normal、AO、color，确认没有大面积跨部件投射或异常空洞。
+7. 运行 ModelTranslator 全部现有单元测试，确保转换器行为无回归。
+
+## 风险与控制
+
+- BVH 会增加一次高模内存占用和数秒分析时间；采样上限控制低模侧开销，相对 Cycles 烘焙可接受。
+- `uv.select_overlap` 是 Blender 质量指标，可能对边界接触较敏感；候选选择同时检查翻转和 fill，真实模型冒烟作为最终质量门。
+- 自动法线或 UV 修复会改变输出低模的顶点着色表现和 UV，但不会修改源文件，并提供 keep 参数退出自动行为。
+- 单一全局射线仍不等价于手工 cage；极密集或多层模型后续可扩展显式 cage，此次不提前增加接口。
+
+## 验收标准
+
+- 无参数运行现有三步命令仍可完成。
+- 当前 well 案例自动触发法线和 UV 修复，射线改为真实距离驱动。
+- 自动指标满足测试章节中的数值门槛。
+- 输出贴图经视觉检查明显减少彩色法线噪声、UV 串色和跨部件投射。
+- README 说明新默认行为、覆盖参数和质量指标。