# UVPackmaster 4 集成设计：Blender 展开路径的 UV 排布增强

日期：2026-07-20
状态：已确认

## 背景与目标

ModelTranslator 减面流程的 Blender 展开路径（seam/smart）用内置 `pack_islands` 排布 UV 岛，
碎岛多的模型利用率低（store 系列仅 36-39%）。本机已安装 UVPackmaster 4（v4.0.4，
Blender 5.0 扩展 `bl_ext.user_default.uvpackmaster4`）+ 独立打包引擎
（`C:\Program Files\UVPackmaster\engine4`，注册表 HKLM `Software\UVPackmaster\Engine4InstallPath`
可自动发现）。

Spike 实测 7 个模型（headless）全部提升、无退化、翻转/重叠不变：

| 模型 | 岛数 | fill 前 | fill 后 |
|---|---|---|---|
| store_low_uv | 730 | 38.5% | 68.8% |
| store10k_low | 1405 | 36.4% | 65.1% |
| well1500_low | 240 | 74.8% | 86.1% |
| woodcar_uv | 772 | 61.8% | 69.1% |
| well500_uv | 343 | 66.8% | 71.6% |
| well_uv | 459 | 58.8% | 61.2% |
| house1000_uv | 355 | 75.6% | 76.8% |

目标：seam/smart 展开后用 UVPM4 重排提升利用率；UVPM4 不可用时无感回退现状。

## 范围

- **改**：`bl_decimate.py`（唯一实质改动文件）、`bl_uvgate.py`（mode 标注前缀判断微调）、README
- **不改**：RizomUV 成功路径（Rizom 自带 Pack 质量已好，不加工序）、CLI 参数（自动尝试+回退，无新开关）

## 设计

### 数据流

```
seam:  锐边seam → unwrap → pack_islands(保底) ─┬→ UVPM4 repack 成功 → mode="seam+uvpm"
                                               └→ 失败/不可用 → 保底布局+警告 → mode="seam"
smart: Smart UV Project(自带排布) ─────────────┬→ UVPM4 repack 成功 → mode="smart+uvpm"
                                               └→ 失败 → 原布局 → mode="smart"
rizom: 成功 → 不动；失败 → bl_uvgate 就地 seam 重展（复用 _do_unwrap）→ 自动带 UVPM4
```

采用"保底+增强"：内置排布始终先跑完，UVPM4 成功则覆盖，失败则保底布局原样保留——
回退天然安全，无需补跑逻辑。质量门指标在 repack 之后采集，校验的是最终 UV。

### 新函数 `_uvpm_repack(obj, warnings) -> bool`（bl_decimate.py）

在 `_do_unwrap` 的 seam/smart 分支展开完成后调用；返回 True 时 mode 加 `+uvpm` 后缀。
内部步骤（全部经 spike 验证）：

1. **GPU 补丁**（仅 `bpy.app.background`）：包装 `gpu.shader.from_builtin`，
   SystemError 时返 None——UVPM4 的 ui_renderer 在模块导入期创建视口覆盖层 shader，
   headless 无 GPU 绘图会炸；覆盖层仅交互用，pack 不受影响
2. **启用扩展**：`addon_utils.enable("bl_ext.user_default.uvpackmaster4", default_set=True)`
   —— `--factory-startup` 下扩展默认未启用；`default_set=True` 才建
   `preferences.addons` 条目（UVPM4 register 的 `get_prefs()` 依赖它），
   factory-startup 关闭偏好自动保存，不会写盘；enable 幂等，uvgate 二次调用无害。
   引擎路径经注册表自动发现，无需配置
3. **像素边距**：`scene.uvpm4_props.default_main_props` 设
   `pixel_margin_enable=True, pixel_margin=4, pixel_margin_tex_size=2048`
   ——与现有 `PACK_MARGIN=0.002`（≈2048 图 4px）及烘焙 padding 同口径
4. **执行**：编辑模式全选（uv_select_sync 开）→
   `bpy.ops.uvpackmaster4.pack(mode_id='pack.single_tile', pack_op_type='0')`
   （UVPM4 非交互调用走假 TIMER 同步轮询，headless 兼容）
5. **失败处理**：任何一步异常 → 记警告返 False——与 RizomUV"失败不中断管线"哲学一致

### 兼容性

- `bl_uvgate.py` 的 `if m["mode"] == "seam"` 改为 `startswith("seam")`，
  使 `seam+uvpm` 也能正确标注为回退产物
- 日志 UV 指标行 `模式=` 字段直接反映排布器，无新参数

## 测试与验收

- 单测（`tests/test_bl_decimate.py`）：mode 后缀/回退标注纯逻辑
- 冒烟 1：`model_decimate.py src/store.fbx --tris 3000 --unwrap seam`
  —— fill 显著提升（预期 ~65%+ vs 现状 ~38%）且质量门通过
- 冒烟 2：默认 rizom 路径（本机 Rizom 未授权 → uvgate 回退 seam）——回退链带上 UVPM4
- README：依赖节加 UVPackmaster 4（可选，未装自动回退）；减面条目补排布说明

## 风险

- UVPM4 引擎为付费产品，换机器未装时全链路回退 `pack_islands`，行为与现状一致
- GPU 补丁属于绕过插件限制的补丁行为，UVPM 大版本升级需复验（导入期 GPU 调用可能变化）