200 lines
8.0 KiB
Markdown
200 lines
8.0 KiB
Markdown
# 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 说明新默认行为、覆盖参数和质量指标。
|