87 lines
4.4 KiB
Markdown
87 lines
4.4 KiB
Markdown
# 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 调用可能变化）
|