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

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 调用可能变化）