From affc0618cfcfadfe35b7140a497b0086cfa5a0d0 Mon Sep 17 00:00:00 2001 From: ud18010 Date: Mon, 20 Jul 2026 12:13:21 +0800 Subject: [PATCH] =?UTF-8?q?ModelTranslator:=20UVPackmaster4=20=E6=8E=92?= =?UTF-8?q?=E5=B8=83=E9=9B=86=E6=88=90=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= =?UTF-8?q?=EF=BC=88headless=20spike=207=20=E6=A8=A1=E5=9E=8B=E5=AE=9E?= =?UTF-8?q?=E8=AF=81=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- .../2026-07-20-uvpackmaster4-pack-design.md | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-20-uvpackmaster4-pack-design.md diff --git a/docs/superpowers/specs/2026-07-20-uvpackmaster4-pack-design.md b/docs/superpowers/specs/2026-07-20-uvpackmaster4-pack-design.md new file mode 100644 index 00000000..f198e655 --- /dev/null +++ b/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 调用可能变化）