ModelTranslator: UVPackmaster4 排布集成设计文档（headless spike 7 模型实证）

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/superpowers/specs/2026-07-20-uvpackmaster4-pack-design.md

@@ -0,0 +1,86 @@
+# 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 调用可能变化）