ModelTranslator: UVPM 排布利用率优化实现计划
3 任务：UVPM4 属性探针(spike)→_uvpm_repack 开旋转+启发式(防御式)→ 端到端验证 gargoyle 3000 利用率对比 + well1500 回归 + README。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
ud18010
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
f117886091
commit
09861faced
@@ -0,0 +1,259 @@
|
||||
# UVPM 排布利用率优化实现计划（旋转 + 启发式搜索）
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 在 `_uvpm_repack` 中开启 UVPM4 的旋转与启发式搜索，把薄条 UV 岛塞得更紧，明显提升 gargoyle 3000 的 UV 利用率而不退化其他指标。
|
||||
|
||||
**Architecture:** 改动集中在 `bl_decimate.py` 的 `_uvpm_repack`（Blender 脚本）。因 UVPM4 属性名/默认值随版本可能不同，先用一次性探针脚本确认确切属性名与取值，再据实设置；属性设置走防御式 `_uvpm_set`（`hasattr` 才设），单个属性名不匹配只跳过、不拖垮整个 UVPM 排布。无纯函数可 TDD，靠探针 + 端到端验证（沿用本仓库约定）。
|
||||
|
||||
**Tech Stack:** Python 3、Blender 5.0 headless（`bpy`）、UVPackmaster 4 扩展。
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
- `Tools/ModelTranslator/bl_decimate.py`（Modify）：新增常量 `UVPM_ROTATION_STEP`/`UVPM_HEURISTIC_TIME` 与辅助 `_uvpm_set`；在 `_uvpm_repack` 的 margin 设置后、pack 前开启旋转+启发式。
|
||||
- `Tools/ModelTranslator/README.md`（Modify）：注明 UVPM 排布已开旋转+启发式。
|
||||
- `Tools/ModelTranslator/tests/bl_probe_uvpm.py`（Create then Delete）：一次性探针，不入库。
|
||||
|
||||
---
|
||||
|
||||
## Task 1: UVPM4 属性探针（spike）
|
||||
|
||||
确认 UVPM4 `default_main_props` 的旋转/启发式属性名、默认值、类型，并验证 headless 下开启后能跑通 pack。结果决定 Task 2 的确切属性名与取值。
|
||||
|
||||
**Files:**
|
||||
- Create: `Tools/ModelTranslator/tests/bl_probe_uvpm.py`（用完删除，不入库）
|
||||
|
||||
- [ ] **Step 1: 写探针脚本**
|
||||
|
||||
Create `Tools/ModelTranslator/tests/bl_probe_uvpm.py`:
|
||||
|
||||
```python
|
||||
"""探针：枚举 UVPM4 default_main_props 的旋转/启发式/边距属性，并在测试网格上
|
||||
验证 headless 开启后能跑通 pack。运行：
|
||||
blender -b --factory-startup --python tests/bl_probe_uvpm.py"""
|
||||
import bpy
|
||||
import addon_utils
|
||||
|
||||
# headless GPU 补丁（同 _uvpm_enable：UVPM 导入期建视口 shader 会 SystemError）
|
||||
import gpu
|
||||
_orig = gpu.shader.from_builtin
|
||||
def _safe(*a, **k):
|
||||
try:
|
||||
return _orig(*a, **k)
|
||||
except SystemError:
|
||||
return None
|
||||
gpu.shader.from_builtin = _safe
|
||||
|
||||
UVPM_EXT = "bl_ext.user_default.uvpackmaster4"
|
||||
if addon_utils.enable(UVPM_EXT, default_set=True) is None:
|
||||
print("UVPM_PROBE {'error': 'enable failed'}")
|
||||
raise SystemExit
|
||||
|
||||
p = bpy.context.scene.uvpm4_props.default_main_props
|
||||
|
||||
# 枚举与 旋转/启发式/搜索/边距 相关的属性名 + 当前值
|
||||
keys = ("rot", "heurist", "search", "margin", "iter")
|
||||
props = {}
|
||||
for n in dir(p):
|
||||
if n.startswith("_"):
|
||||
continue
|
||||
if any(k in n.lower() for k in keys):
|
||||
try:
|
||||
props[n] = repr(getattr(p, n))
|
||||
except Exception as e:
|
||||
props[n] = "ERR:%r" % e
|
||||
print("UVPM_PROPS " + repr(props))
|
||||
|
||||
# 测试 pack：UV 球 smart_project，尽力开启旋转/启发式，跑一次 pack
|
||||
bpy.ops.mesh.primitive_uv_sphere_add()
|
||||
obj = bpy.context.view_layer.objects.active
|
||||
bpy.ops.object.mode_set(mode='EDIT')
|
||||
bpy.ops.mesh.select_all(action='SELECT')
|
||||
bpy.ops.uv.smart_project()
|
||||
|
||||
def try_set(name, val):
|
||||
if not hasattr(p, name):
|
||||
return "absent"
|
||||
try:
|
||||
setattr(p, name, val)
|
||||
return "ok=%r" % getattr(p, name)
|
||||
except Exception as e:
|
||||
return "ERR:%r" % e
|
||||
|
||||
tried = {
|
||||
"rotation_enable": try_set("rotation_enable", True),
|
||||
"rotation_step": try_set("rotation_step", 90),
|
||||
"heuristic_enable": try_set("heuristic_enable", True),
|
||||
"heuristic_search_time": try_set("heuristic_search_time", 3),
|
||||
"heuristic_max_wait_time": try_set("heuristic_max_wait_time", 3),
|
||||
}
|
||||
bpy.context.scene.tool_settings.use_uv_select_sync = True
|
||||
try:
|
||||
ret = bpy.ops.uvpackmaster4.pack(mode_id='pack.single_tile', pack_op_type='0')
|
||||
tried["pack"] = sorted(ret)
|
||||
except Exception as e:
|
||||
tried["pack"] = "ERR:%r" % e
|
||||
finally:
|
||||
bpy.ops.object.mode_set(mode='OBJECT')
|
||||
print("UVPM_TRY " + repr(tried))
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行探针**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && "D:\tools\blender-5.0.0-windows-x64\blender.exe" -b --factory-startup --python tests/bl_probe_uvpm.py 2>&1 | grep -E "UVPM_PROPS|UVPM_TRY|UVPM_PROBE"
|
||||
```
|
||||
Expected: 两行 `UVPM_PROPS {...}`（可用属性名+默认值）与 `UVPM_TRY {...}`（各属性设置结果 + `pack` 返回 `['FINISHED']`）。
|
||||
|
||||
- [ ] **Step 3: 记录结论**
|
||||
|
||||
从输出确认并记录：
|
||||
- 旋转属性的确切名（`rotation_enable` 是否存在？步进属性名与类型/取值范围，如 `rotation_step` 是 int 度数还是 enum）。
|
||||
- 启发式属性的确切名（`heuristic_enable`？时间上限是 `heuristic_search_time` 还是 `heuristic_max_wait_time`？单位/类型）。
|
||||
- `pack` 是否返回 `FINISHED`（确认 headless 可跑）。
|
||||
- 若启发式需要非 `'0'` 的 `pack_op_type` 或专门 mode，记录之。
|
||||
这些结论用于 Task 2 的确切属性名与常量取值。
|
||||
|
||||
- [ ] **Step 4: 删除探针脚本**
|
||||
|
||||
```bash
|
||||
cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && rm tests/bl_probe_uvpm.py
|
||||
```
|
||||
（探针一次性、不入库；结论写入 Task 2 的 commit 正文。）
|
||||
|
||||
---
|
||||
|
||||
## Task 2: `_uvpm_repack` 开启旋转 + 启发式
|
||||
|
||||
新增防御式 `_uvpm_set` 辅助与常量，在 `_uvpm_repack` 的 margin 设置后、pack 前开启旋转与启发式搜索。**属性名与取值以 Task 1 探针结论为准**——下方代码用最可能的名字，执行时按探针实测替换/校正。
|
||||
|
||||
**Files:**
|
||||
- Modify: `Tools/ModelTranslator/bl_decimate.py`（常量区 + `_uvpm_repack` 之前新增 `_uvpm_set` + `_uvpm_repack` 内部）
|
||||
|
||||
- [ ] **Step 1: 新增常量**
|
||||
|
||||
在 `bl_decimate.py` 常量区 `UVPM_TEX_SIZE = 2048` 那一行之后追加（取值以探针结论校正）：
|
||||
|
||||
```python
|
||||
UVPM_ROTATION_STEP = 90 # UVPM 旋转步进（度）；探针确认类型/范围后校正
|
||||
UVPM_HEURISTIC_TIME = 5 # UVPM 启发式搜索秒数上限
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 新增 `_uvpm_set` 辅助**
|
||||
|
||||
在 `bl_decimate.py` 的 `_uvpm_repack` 函数**之前**新增：
|
||||
|
||||
```python
|
||||
def _uvpm_set(p, name, value, warnings):
|
||||
"""防御式设 UVPM 属性：属性存在才设，否则记警告跳过——
|
||||
名字不匹配（UVPM 版本差异）时降级为按原 margin 跑 UVPM，不丢整个排布。"""
|
||||
if hasattr(p, name):
|
||||
try:
|
||||
setattr(p, name, value)
|
||||
except Exception as e:
|
||||
warnings.append("UVPM 属性 %s 设置失败（%s），跳过" % (name, e))
|
||||
else:
|
||||
warnings.append("UVPM 属性 %s 不存在，跳过" % name)
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 在 `_uvpm_repack` 开启旋转 + 启发式**
|
||||
|
||||
在 `_uvpm_repack` 中，现有三行 margin 设置（`p.pixel_margin_enable = True` / `p.pixel_margin = UVPM_PIXEL_MARGIN` / `p.pixel_margin_tex_size = UVPM_TEX_SIZE`）之后、`bpy.context.scene.tool_settings.use_uv_select_sync = True` 之前，插入（属性名以 Task 1 为准替换）：
|
||||
|
||||
```python
|
||||
_uvpm_set(p, "rotation_enable", True, warnings)
|
||||
_uvpm_set(p, "rotation_step", UVPM_ROTATION_STEP, warnings)
|
||||
_uvpm_set(p, "heuristic_enable", True, warnings)
|
||||
_uvpm_set(p, "heuristic_search_time", UVPM_HEURISTIC_TIME, warnings)
|
||||
```
|
||||
|
||||
注意：
|
||||
- 若 Task 1 发现时间上限属性名是 `heuristic_max_wait_time`（而非 `heuristic_search_time`），把最后一行的名字换成实测的；`hasattr` 守卫使写错的名字只被跳过、不报错，但**为让功能真正生效，必须用探针确认的正确名字**。
|
||||
- 若 Task 1 发现启发式需要非 `'0'` 的 `pack_op_type`，同时修改 `_uvpm_repack` 里 `bpy.ops.uvpackmaster4.pack(...)` 的 `pack_op_type` 实参，并在 commit 正文说明。
|
||||
- 这些设置在现有 `_uvpm_repack` 的 `try/except Exception` 内；`_uvpm_set` 的 `hasattr` 守卫确保单属性问题不触发整体回退。
|
||||
|
||||
- [ ] **Step 4: 语法自检 + 单测不回归**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -c "import ast; ast.parse(open('bl_decimate.py', encoding='utf-8').read()); print('OK')" && python -m unittest tests.test_bl_decimate 2>&1 | tail -3
|
||||
```
|
||||
Expected: `OK`，随后单测全 PASS（本改动无纯函数，仅确认无破坏）。（排布效果在 Task 3 端到端验证。）
|
||||
|
||||
- [ ] **Step 5: 提交**
|
||||
|
||||
```bash
|
||||
cd "d:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_decimate.py && git commit -m "ModelTranslator: _uvpm_repack 开启旋转+启发式搜索（防御式设属性）
|
||||
|
||||
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||||
```
|
||||
（在 commit 正文补一句 Task 1 探针确认的确切属性名/取值，便于追溯。）
|
||||
|
||||
---
|
||||
|
||||
## Task 3: 端到端验证 + README
|
||||
|
||||
**Files:**
|
||||
- Modify: `Tools/ModelTranslator/README.md`
|
||||
|
||||
- [ ] **Step 1: 全量单测**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_decimate tests.test_uv_preview tests.test_unity_assets 2>&1 | tail -3
|
||||
```
|
||||
Expected: 全部 PASS。
|
||||
|
||||
- [ ] **Step 2: 端到端主验收（gargoyle 3000）+ 计时**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && rm -f src/gargoyle_low_uv.png && PYTHONIOENCODING=utf-8 python -c "import time,subprocess,sys; t=time.time(); r=subprocess.run([sys.executable,'model_decimate.py','src/gargoyle.fbx','--tris','3000','--max-overlap','0.15'],capture_output=True,text=True,encoding='utf-8'); print(r.stdout[-800:]); print('ELAPSED %.1fs'%(time.time()-t))"
|
||||
```
|
||||
Expected: `模式=seam@45+uvpm`；岛数≈390（排布不改岛数）；**利用率明显高于基线 52.3%**；翻转 0%；重叠 ≤13.3%（不高于基线）。记录利用率与 `ELAPSED` 秒数（pack 增量）。若有 `UVPM 属性 … 不存在` 警告说明属性名未对齐，需回 Task 2 用探针名校正。
|
||||
|
||||
- [ ] **Step 3: 观察图肉眼确认**
|
||||
|
||||
用 Read 工具打开 `src/gargoyle_low_uv.png`，确认薄条岛塞得更紧、空白（黑块）区域明显减少。
|
||||
|
||||
- [ ] **Step 4: 回归 well1500（正常 seam@66 情形）**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && PYTHONIOENCODING=utf-8 python model_decimate.py src/well1500.fbx --tris 5000 2>&1 | tail -4
|
||||
```
|
||||
Expected: 成功，无异常退出；`模式=seam@NN+uvpm`；利用率不低于其历史水平（排布增强不应变差）。
|
||||
|
||||
- [ ] **Step 5: 更新 README**
|
||||
|
||||
在 `Tools/ModelTranslator/README.md` 的 `- **model_decimate.py**：…` 那条中，把 `排布默认用 UVPackmaster 4 重排（只在最终选定 UV 上跑一次）` 这一处描述扩写为：
|
||||
|
||||
```markdown
|
||||
排布默认用 UVPackmaster 4 重排（只在最终选定 UV 上跑一次，已开旋转+启发式搜索以提升薄条岛的利用率）
|
||||
```
|
||||
|
||||
（只改这一处短语，不动其余。）
|
||||
|
||||
- [ ] **Step 6: 提交**
|
||||
|
||||
```bash
|
||||
cd "d:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/README.md && git commit -m "ModelTranslator: README 注明 UVPM 已开旋转+启发式搜索
|
||||
|
||||
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
- [ ] **Step 7: 汇报前后对比**
|
||||
|
||||
在最终汇报里给出：基线（seam@45 / 390 岛 / 52.3% / 翻转 0% / 重叠 13.3%）vs 现在（利用率 / 岛数 / 翻转 / 重叠 / pack 耗时），并附观察图观察结论。
|
||||
|
||||
---
|
||||
|
||||
## Self-Review 记录
|
||||
|
||||
- **Spec 覆盖**：①探针确认属性名→Task 1；②`_uvpm_repack` 开旋转+启发式（防御式 `_uvpm_set` + 常量）→Task 2；③验证（gargoyle 主验收 + well1500 回归 + 观察图）→Task 3 Step 2-4；README→Task 3 Step 5；错误处理（属性名不匹配跳过、整体失败回退、启发式时间上限）→Task 2 `_uvpm_set` 守卫 + 常量。全部有对应任务。
|
||||
- **占位符**：探针脚本、`_uvpm_set`、常量、各命令均为完整内容。属性名标注"以 Task 1 为准"是 spike-first 设计的必要性质（执行时由 Task 1 输出定稿），非未决占位——`hasattr` 守卫保证即便名字有出入也不崩，Task 3 Step 2 的"属性不存在"警告会兜住并要求回改。
|
||||
- **类型/命名一致**：`_uvpm_set(p, name, value, warnings)`（Task 2 Step 2 定义，Step 3 调用一致）；常量 `UVPM_ROTATION_STEP`/`UVPM_HEURISTIC_TIME`（Task 2 Step 1 定义，Step 3 使用一致）；`p` 即 `scene.uvpm4_props.default_main_props`（与现有 `_uvpm_repack` 一致）。
|
||||
- **已知风险**：UVPM4 属性名/取值由 Task 1 探针定；启发式若需特定 `pack_op_type` 在 Task 2 据实调整；薄条几何天然限制上限，验收以"明显上升"而非硬数字（spec 一致）。
|
||||
Reference in New Issue
Block a user