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