613 lines
24 KiB
Markdown
613 lines
24 KiB
Markdown
# RizomUV UV 展开接入实现计划
|
||
|
||
> **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:** `model_decimate.py` 默认用 RizomUV（RizomUVLink 驱动）做 UV 自动切缝/展开/打包，不可用或质量门不达标自动回退 seam/smart。
|
||
|
||
**Architecture:** 三步管线——Blender 减面（`none` 模式不展 UV）→ 系统 Python 经官方 RizomUVLink 驱动 rizomuv.exe（AutoSeam→Cut→Unfold→Pack→Save 覆盖 FBX）→ Blender `bl_uvgate.py` 量 UV 指标做质量门，不达标就地 seam 重展。设计文档：`docs/superpowers/specs/2026-07-17-rizomuv-unwrap-design.md`。
|
||
|
||
**Tech Stack:** Python 3.12（系统）、RizomUVLink（RizomUV 2025 安装自带，MIT，`rizomuvlink_python312.pyd`）、Blender 5.0 headless。
|
||
|
||
**已核实的 API 事实**（来自 `C:\Program Files\RizomUV2025\RizomUVLink\RizomUVLinkBase.py` docstring 与 `doc/index.html`）：
|
||
|
||
- `CRizomUVLink()` 方法：`RunRizomUV(exePath=...)`（启动实例并连接，返回端口）、`Load/Select/Cut/Unfold/Pack/Save/Quit(params)`；异常类型 `CZEx`
|
||
- 自动切缝 = `Select` 边工作集 + `Auto` 表：`Auto.QuasiDevelopable`（标准版叫 MOSAIC，`Developability` 0~1 为分割力度）、`Auto.HandleCutter`（切柄）、`Auto.PipesCutter`（连洞）、`Auto.SkeletonUnoverlap`（防重叠后处理）、`Auto.FlatteningMode`（0=unfold）、`Auto.Quality`
|
||
- `Cut`：`{"PrimType": "Edge", "WorkingSet": "Visible"}` 按选中边切缝
|
||
- `Unfold` 参数：`BorderIntersections`、`TriangleFlips`（bool，防边界交叉/翻转）、`Iterations`
|
||
- `Pack` 参数：顶层 `RootGroup`/`WorkingSet`/`ProcessTileSelection`/`Translate`/`RecursionDepth`，`Global` 表内 `PaddingSize`（岛间距，UV 单位）、`MarginSize`（tile 边距，UV 单位）、`MapResolution`（int）、`Rotate.Step`（度）、`Scaling.Mode`（int 枚举，顺序 0=OFF、1=SET_3D_AREA、2=AVG_RATIO_OF_MOVABLE_ISLANDS、3=AVG_RATIO_OF_GROUP；文档明言首次展开后建议 AVG_RATIO_OF_GROUP）
|
||
- 注册表查找（官方 README）：`HKLM\SOFTWARE\Rizom Lab\RizomUV VS RS 202X.Y` 的默认值键 `rizomuv.exe`——**实测该值是不带后缀的安装前缀**（如 `C:\Program Files\RizomUV2025\rizomuv`），官方代码只取 `dirname` 用，须拼回 `rizomuv.exe`
|
||
- 本机安装：`C:\Program Files\RizomUV2025\rizomuv.exe`
|
||
|
||
**风险提示（执行者注意）**：`Select.Auto`/`Pack.Global` 的个别键名若被 RizomUV 拒绝（CZEx 报 unknown parameter），以 `link.Select.__doc__` / `link.Pack.__doc__` 打印出的参数名为准就地修正，不要猜。
|
||
|
||
---
|
||
|
||
### Task 1: bl_decimate.py——质量门纯函数 `uv_gate_ok` + `none` 展开模式
|
||
|
||
**Files:**
|
||
- Modify: `Tools/ModelTranslator/bl_decimate.py`（阈值常量附近 + `_do_unwrap` + `main`）
|
||
- Test: `Tools/ModelTranslator/tests/test_bl_decimate.py`
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
在 `tests/test_bl_decimate.py` 末尾（`if __name__` 之前，若无该块则文件末尾）追加：
|
||
|
||
```python
|
||
class TestUvGateOk(unittest.TestCase):
|
||
def test_clean_passes(self):
|
||
self.assertTrue(bd.uv_gate_ok(0.0, 0.0))
|
||
|
||
def test_boundary_passes(self):
|
||
self.assertTrue(bd.uv_gate_ok(bd.UV_FLIP_TOL, bd.UV_OVERLAP_TOL))
|
||
|
||
def test_flip_exceeds_fails(self):
|
||
self.assertFalse(bd.uv_gate_ok(0.03, 0.0))
|
||
|
||
def test_overlap_exceeds_fails(self):
|
||
self.assertFalse(bd.uv_gate_ok(0.0, 0.09))
|
||
|
||
def test_overlap_none_treated_as_zero(self):
|
||
self.assertTrue(bd.uv_gate_ok(0.01, None))
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_decimate -v 2>&1 | tail -15
|
||
```
|
||
|
||
预期：5 个新用例 ERROR（`AttributeError: module 'bl_decimate' has no attribute 'uv_gate_ok'`），旧用例全过。
|
||
|
||
- [ ] **Step 3: 实现 `uv_gate_ok` 并让 `_do_unwrap` 复用**
|
||
|
||
`bl_decimate.py` 中 `UV_OVERLAP_TOL` 常量定义之后加：
|
||
|
||
```python
|
||
def uv_gate_ok(flipped, overlap):
|
||
"""UV 质量门：翻转与重叠占比都在阈值内。overlap 为 None（op 不可用）按 0 处理。"""
|
||
return flipped <= UV_FLIP_TOL and (overlap or 0.0) <= UV_OVERLAP_TOL
|
||
```
|
||
|
||
`_do_unwrap` 中原判断：
|
||
|
||
```python
|
||
m = _collect_uv_metrics(obj)
|
||
overlap = m["overlap"] or 0.0
|
||
if m["flipped"] <= UV_FLIP_TOL and overlap <= UV_OVERLAP_TOL:
|
||
```
|
||
|
||
改为：
|
||
|
||
```python
|
||
m = _collect_uv_metrics(obj)
|
||
if uv_gate_ok(m["flipped"], m["overlap"]):
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试确认通过**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_decimate -v 2>&1 | tail -5
|
||
```
|
||
|
||
预期：`OK`。
|
||
|
||
- [ ] **Step 5: 加 `none` 展开模式**
|
||
|
||
`bl_decimate.py` 的 `main()` 中，`uv_info = _do_unwrap(obj, unwrap_mode, warnings)` 一行改为：
|
||
|
||
```python
|
||
if unwrap_mode == "none":
|
||
# rizom 管线：跳过展开，UV 由后续 RizomUV 步骤生成
|
||
_clear_uv_layers(obj.data)
|
||
uv_info = {"mode": "none", "islands": 0, "fill": 0.0,
|
||
"flipped": 0.0, "overlap": None}
|
||
else:
|
||
uv_info = _do_unwrap(obj, unwrap_mode, warnings)
|
||
```
|
||
|
||
文件头 docstring 的调用说明 `[seam|smart]` 改为 `[seam|smart|none]`。
|
||
|
||
- [ ] **Step 6: 冒烟验证 none 模式**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && "D:/tools/blender-5.0.0-windows-x64/blender.exe" -b --factory-startup --python bl_decimate.py -- src/store.fbx /tmp/store_none.fbx 3000 none 2>&1 | grep MT_SUMMARY
|
||
```
|
||
|
||
预期：`"uv": {"mode": "none", ...}`，无报错。
|
||
|
||
- [ ] **Step 7: Commit**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_decimate.py Tools/ModelTranslator/tests/test_bl_decimate.py && git commit -m "ModelTranslator: 质量门抽纯函数 uv_gate_ok + 减面 none 模式（rizom 管线前置）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: rizom_unwrap.py——exe 发现（纯逻辑 + 注册表）
|
||
|
||
**Files:**
|
||
- Create: `Tools/ModelTranslator/rizom_unwrap.py`
|
||
- Test: `Tools/ModelTranslator/tests/test_rizom_unwrap.py`
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
新建 `tests/test_rizom_unwrap.py`：
|
||
|
||
```python
|
||
import os
|
||
import sys
|
||
import unittest
|
||
|
||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||
import rizom_unwrap as ru
|
||
|
||
|
||
class TestCandidatePaths(unittest.TestCase):
|
||
def test_priority_order(self):
|
||
self.assertEqual(ru.candidate_paths("a.exe", "b.exe", "c.exe"),
|
||
["a.exe", "b.exe", "c.exe", ru.DEFAULT_RIZOM])
|
||
|
||
def test_none_entries_skipped(self):
|
||
self.assertEqual(ru.candidate_paths(None, None, None), [ru.DEFAULT_RIZOM])
|
||
|
||
def test_env_only(self):
|
||
self.assertEqual(ru.candidate_paths(None, "b.exe", None),
|
||
["b.exe", ru.DEFAULT_RIZOM])
|
||
|
||
|
||
class TestFindRizomuv(unittest.TestCase):
|
||
def test_missing_exe_raises(self):
|
||
os.environ.pop("RIZOMUV_EXE", None)
|
||
with self.assertRaises(ru.RizomError):
|
||
ru.find_rizomuv("Z:/no/such/rizomuv.exe", use_registry=False,
|
||
default="Z:/no/default.exe")
|
||
|
||
|
||
if __name__ == "__main__":
|
||
unittest.main()
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_rizom_unwrap -v 2>&1 | tail -8
|
||
```
|
||
|
||
预期：`ModuleNotFoundError: No module named 'rizom_unwrap'`。
|
||
|
||
- [ ] **Step 3: 实现路径发现**
|
||
|
||
新建 `rizom_unwrap.py`：
|
||
|
||
```python
|
||
"""RizomUV 自动展开：官方 RizomUVLink 驱动 rizomuv.exe 做 AutoSeam/Unfold/Pack。
|
||
仅在系统 Python 中使用（不进 Blender）；任何不可用/失败抛 RizomError，
|
||
由 model_decimate.py 回退 Blender seam 展开。"""
|
||
import os
|
||
import sys
|
||
import threading
|
||
|
||
DEFAULT_RIZOM = r"C:\Program Files\RizomUV2025\rizomuv.exe"
|
||
MAP_RES = 2048 # Pack 目标贴图分辨率
|
||
PADDING_PX = 4 # 岛间距（像素）＝ bl_decimate.PACK_MARGIN(0.002) * 2048
|
||
TIMEOUT_S = 300 # 单条命令超时
|
||
|
||
|
||
class RizomError(Exception):
|
||
"""RizomUV 不可用或处理失败（上层据此回退）。"""
|
||
|
||
|
||
def candidate_paths(cli_arg=None, env_val=None, reg_val=None, default=DEFAULT_RIZOM):
|
||
"""rizomuv.exe 候选路径，优先级：CLI 参数 > 环境变量 > 注册表 > 默认安装位置。"""
|
||
return [p for p in (cli_arg, env_val, reg_val, default) if p]
|
||
|
||
|
||
def registry_rizom_path():
|
||
"""官方 README 的注册表查找（HKLM\\SOFTWARE\\Rizom Lab\\RizomUV VS RS 202X.Y），
|
||
新版本优先；找不到或非 Windows 返回 None。"""
|
||
try:
|
||
import winreg
|
||
except ImportError:
|
||
return None
|
||
for i in range(9, 1, -1):
|
||
for j in range(10, -1, -1):
|
||
if i == 2 and j < 2:
|
||
continue
|
||
key_path = "SOFTWARE\\Rizom Lab\\RizomUV VS RS 202%d.%d" % (i, j)
|
||
try:
|
||
key = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, key_path)
|
||
return winreg.QueryValue(key, "rizomuv.exe")
|
||
except OSError:
|
||
continue
|
||
return None
|
||
|
||
|
||
def find_rizomuv(cli_arg=None, use_registry=True, default=DEFAULT_RIZOM):
|
||
"""返回第一个真实存在的 rizomuv.exe；都不存在抛 RizomError。"""
|
||
reg = registry_rizom_path() if use_registry else None
|
||
cands = candidate_paths(cli_arg, os.environ.get("RIZOMUV_EXE"), reg, default)
|
||
for p in cands:
|
||
if os.path.isfile(p):
|
||
return p
|
||
raise RizomError("找不到 rizomuv.exe（尝试过：%s）" % "; ".join(cands))
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试确认通过**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_rizom_unwrap -v 2>&1 | tail -5
|
||
```
|
||
|
||
预期：`OK`（4 个用例）。
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/rizom_unwrap.py Tools/ModelTranslator/tests/test_rizom_unwrap.py && git commit -m "ModelTranslator: rizom_unwrap exe 发现（CLI>env>注册表>默认，官方 README 口径）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: rizom_unwrap.py——RizomUVLink 展开驱动
|
||
|
||
**Files:**
|
||
- Modify: `Tools/ModelTranslator/rizom_unwrap.py`（文件末尾追加）
|
||
|
||
无法对真实 RizomUV 进程写单测；本任务以「对 store 低模跑通全流程」为验收（Step 3）。
|
||
|
||
- [ ] **Step 1: 实现驱动**
|
||
|
||
`rizom_unwrap.py` 末尾追加：
|
||
|
||
```python
|
||
def _import_link(exe):
|
||
"""从 RizomUV 安装目录动态引入官方 RizomUVLink 模块（随安装自带，MIT）。"""
|
||
link_dir = os.path.join(os.path.dirname(exe), "RizomUVLink")
|
||
if not os.path.isdir(link_dir):
|
||
raise RizomError("RizomUVLink 目录不存在：%s" % link_dir)
|
||
if link_dir not in sys.path:
|
||
sys.path.insert(0, link_dir)
|
||
try:
|
||
import RizomUVLink
|
||
return RizomUVLink
|
||
except Exception as e: # pyd 与 Python 版本不匹配等
|
||
raise RizomError("RizomUVLink 导入失败：%s" % e)
|
||
|
||
|
||
def _call(label, fn, params, timeout=TIMEOUT_S):
|
||
"""带超时执行一条 RizomUV 命令；超时或 CZEx 抛 RizomError。"""
|
||
out, err = [], []
|
||
|
||
def run():
|
||
try:
|
||
out.append(fn(params))
|
||
except Exception as e:
|
||
err.append(e)
|
||
|
||
t = threading.Thread(target=run, daemon=True)
|
||
t.start()
|
||
t.join(timeout)
|
||
if t.is_alive():
|
||
raise RizomError("%s 超时（%ds）" % (label, timeout))
|
||
if err:
|
||
raise RizomError("%s 失败：%s" % (label, err[0]))
|
||
return out[0] if out else None
|
||
|
||
|
||
def rizom_unwrap(fbx_path, exe, map_res=MAP_RES, padding_px=PADDING_PX):
|
||
"""AutoSeam 全自动切缝 -> Unfold -> Pack -> 覆盖保存 fbx_path。失败抛 RizomError。"""
|
||
mod = _import_link(exe)
|
||
link = mod.CRizomUVLink()
|
||
try:
|
||
link.RunRizomUV(exePath=exe)
|
||
except Exception as e:
|
||
raise RizomError("RizomUV 启动失败（license/环境）：%s" % e)
|
||
fbx_abs = os.path.abspath(fbx_path)
|
||
pad_uv = float(padding_px) / map_res
|
||
try:
|
||
_call("Load", link.Load, {"File.Path": fbx_abs, "File.XYZ": True})
|
||
# AutoSeam：MOSAIC(QuasiDevelopable) + 切柄/连洞 + 防重叠后处理
|
||
_call("Select(AutoSeam)", link.Select, {
|
||
"PrimType": "Edge", "WorkingSet": "Visible",
|
||
"Select": True, "ResetBefore": True,
|
||
"Auto": {
|
||
"QuasiDevelopable": {"Developability": 0.5, "IslandPolyNBMin": 1,
|
||
"AreaMinRatio": 0.0, "FitCones": False,
|
||
"Straighten": True},
|
||
"HandleCutter": True,
|
||
"PipesCutter": True,
|
||
"SkeletonUnoverlap": {},
|
||
"FlatteningMode": 0,
|
||
"FlatteningUnfoldParams": {"BorderIntersections": True,
|
||
"TriangleFlips": True},
|
||
"StoreCoordsUVW": True,
|
||
"Quality": 0.5,
|
||
}})
|
||
_call("Cut", link.Cut, {"PrimType": "Edge", "WorkingSet": "Visible"})
|
||
_call("Unfold", link.Unfold, {"PrimType": "Edge", "WorkingSet": "Visible",
|
||
"BorderIntersections": True,
|
||
"TriangleFlips": True})
|
||
# Scaling.Mode=3 (AVG_RATIO_OF_GROUP)：官方文档建议首次展开后用该模式统一密度
|
||
_call("Pack", link.Pack, {
|
||
"RootGroup": "RootGroup", "WorkingSet": "Visible",
|
||
"ProcessTileSelection": False, "RecursionDepth": 1,
|
||
"Translate": True,
|
||
"Global": {"MapResolution": map_res,
|
||
"PaddingSize": pad_uv, "MarginSize": pad_uv,
|
||
"Rotate": {"Step": 90.0},
|
||
"Scaling": {"Mode": 3}}})
|
||
_call("Save", link.Save, {"File.Path": fbx_abs})
|
||
finally:
|
||
try:
|
||
link.Quit({})
|
||
except Exception:
|
||
pass
|
||
```
|
||
|
||
- [ ] **Step 2: 确认既有单测未被破坏**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_rizom_unwrap tests.test_bl_decimate 2>&1 | tail -3
|
||
```
|
||
|
||
预期：`OK`。
|
||
|
||
- [ ] **Step 3: 真机冒烟（临时脚本，不入库）**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && cp src/store_low.fbx /tmp/rz_smoke.fbx && python -c "
|
||
from rizom_unwrap import find_rizomuv, rizom_unwrap
|
||
rizom_unwrap('/tmp/rz_smoke.fbx', find_rizomuv())
|
||
print('SMOKE OK')"
|
||
```
|
||
|
||
预期：RizomUV 窗口短暂出现后关闭，打印 `SMOKE OK`，`/tmp/rz_smoke.fbx` 被覆盖（mtime 更新）。
|
||
若某条命令 CZEx 报未知参数：打印对应 `link.<方法>.__doc__` 查正确键名后修正代码，禁止瞎猜重试。
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/rizom_unwrap.py && git commit -m "ModelTranslator: RizomUVLink 驱动 AutoSeam/Unfold/Pack（带 300s 超时，失败抛 RizomError）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: bl_uvgate.py——UV 质量门（不达标就地 seam 重展）
|
||
|
||
**Files:**
|
||
- Create: `Tools/ModelTranslator/bl_uvgate.py`
|
||
|
||
纯函数（门限判断）已在 Task 1 覆盖单测；本脚本是 Blender 编排层，以 Step 2/3 冒烟为验收。
|
||
|
||
- [ ] **Step 1: 实现**
|
||
|
||
新建 `bl_uvgate.py`：
|
||
|
||
```python
|
||
"""Blender 内运行：校验低模 FBX 的 UV 质量门；无 UV 或不达标就地 seam 重展并覆盖导出。
|
||
调用：blender -b --factory-startup --python bl_uvgate.py -- <low.fbx> [mode_label]
|
||
mode_label 仅用于日志/回退警告中标注上游展开方式（默认 rizom）。"""
|
||
import os
|
||
import sys
|
||
|
||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||
|
||
|
||
def main():
|
||
import bpy
|
||
import json
|
||
from bl_decimate import (join_meshes, uv_gate_ok, _collect_uv_metrics,
|
||
_do_unwrap)
|
||
argv = sys.argv[sys.argv.index("--") + 1:]
|
||
fbx = argv[0]
|
||
mode_label = argv[1] if len(argv) > 1 else "rizom"
|
||
warnings = []
|
||
|
||
bpy.ops.wm.read_factory_settings(use_empty=True)
|
||
bpy.ops.import_scene.fbx(filepath=fbx)
|
||
meshes = [o for o in bpy.data.objects if o.type == 'MESH']
|
||
if not meshes:
|
||
print("MT_SUMMARY " + json.dumps({"error": "FBX 中没有 mesh"},
|
||
ensure_ascii=False))
|
||
return
|
||
obj = join_meshes(meshes)
|
||
|
||
if obj.data.uv_layers:
|
||
m = _collect_uv_metrics(obj)
|
||
if uv_gate_ok(m["flipped"], m["overlap"]):
|
||
m["mode"] = mode_label
|
||
print("MT_SUMMARY " + json.dumps(
|
||
{"uv": m, "reexported": False, "warnings": warnings},
|
||
ensure_ascii=False))
|
||
return
|
||
warnings.append("%s UV 质量不达标（翻转 %.1f%% 重叠 %s），回退 seam"
|
||
% (mode_label, m["flipped"] * 100,
|
||
"%.1f%%" % (m["overlap"] * 100)
|
||
if m["overlap"] is not None else "未知"))
|
||
else:
|
||
warnings.append("%s 输出无 UV，回退 seam" % mode_label)
|
||
|
||
m = _do_unwrap(obj, "seam", warnings) # 内部自带 smart 回退
|
||
if m["mode"] == "seam":
|
||
m["mode"] = "seam_fallback"
|
||
bpy.ops.object.select_all(action='DESELECT')
|
||
obj.select_set(True)
|
||
bpy.ops.export_scene.fbx(filepath=os.path.abspath(fbx), use_selection=True,
|
||
path_mode='STRIP', embed_textures=False)
|
||
print("MT_SUMMARY " + json.dumps(
|
||
{"uv": m, "reexported": True, "warnings": warnings},
|
||
ensure_ascii=False))
|
||
|
||
|
||
if __name__ == "__main__" and "--" in sys.argv:
|
||
main()
|
||
```
|
||
|
||
- [ ] **Step 2: 冒烟——达标路径**
|
||
|
||
用 Task 3 冒烟产物（RizomUV 已展开的 FBX）：
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && "D:/tools/blender-5.0.0-windows-x64/blender.exe" -b --factory-startup --python bl_uvgate.py -- /tmp/rz_smoke.fbx rizom 2>&1 | grep MT_SUMMARY
|
||
```
|
||
|
||
预期：`"mode": "rizom"`、`"reexported": false`，翻转/重叠数值在阈值内。
|
||
|
||
- [ ] **Step 3: 冒烟——回退路径（无 UV）**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && "D:/tools/blender-5.0.0-windows-x64/blender.exe" -b --factory-startup --python bl_decimate.py -- src/store.fbx /tmp/gate_noneuv.fbx 3000 none 2>&1 | grep MT_SUMMARY && "D:/tools/blender-5.0.0-windows-x64/blender.exe" -b --factory-startup --python bl_uvgate.py -- /tmp/gate_noneuv.fbx rizom 2>&1 | grep MT_SUMMARY
|
||
```
|
||
|
||
预期：第二条输出 `"mode": "seam_fallback"`（或 `smart_fallback`）、`"reexported": true`、警告含"输出无 UV，回退 seam"。
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_uvgate.py && git commit -m "ModelTranslator: bl_uvgate UV 质量门——rizom 产物校验，无 UV/不达标就地 seam 重展"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: model_decimate.py——rizom 默认编排
|
||
|
||
**Files:**
|
||
- Modify: `Tools/ModelTranslator/model_decimate.py`
|
||
|
||
- [ ] **Step 1: 实现编排**
|
||
|
||
`model_decimate.py` 全文改为：
|
||
|
||
```python
|
||
"""FBX 减面 CLI：减到指定三角面数并重展 UV（默认 RizomUV 自动展开），输出 <名>_low.fbx。
|
||
用法：python model_decimate.py src/well1500.fbx --tris 5000 [-o dir]
|
||
[--unwrap rizom|seam|smart] [--rizom exe] [--blender exe]"""
|
||
import argparse
|
||
import os
|
||
|
||
from mt_run import find_blender, run_blender_script
|
||
|
||
|
||
def main():
|
||
ap = argparse.ArgumentParser(description=__doc__)
|
||
ap.add_argument("input", help="FBX 文件")
|
||
ap.add_argument("--tris", type=int, required=True, help="目标三角面数")
|
||
ap.add_argument("-o", "--out", default=None, help="输出目录（默认源文件同目录）")
|
||
ap.add_argument("--unwrap", choices=("rizom", "seam", "smart"), default="rizom",
|
||
help="UV 展开：rizom=RizomUV 自动切缝（默认，不可用回退 seam），"
|
||
"seam=锐边接缝整岛展开，smart=Smart UV Project")
|
||
ap.add_argument("--rizom", default=None, help="rizomuv.exe 路径（默认自动发现）")
|
||
ap.add_argument("--blender", default=None)
|
||
args = ap.parse_args()
|
||
if args.tris <= 0:
|
||
ap.error("--tris 必须为正整数")
|
||
|
||
blender = find_blender(args.blender)
|
||
name = os.path.splitext(os.path.basename(args.input))[0]
|
||
outdir = args.out or os.path.dirname(os.path.abspath(args.input))
|
||
out_fbx = os.path.join(outdir, name + "_low.fbx")
|
||
|
||
if args.unwrap == "rizom":
|
||
# 三步：Blender 减面（不展UV）-> RizomUV 展开 -> Blender 质量门（不达标就地 seam 重展）
|
||
s = run_blender_script(blender, "bl_decimate.py",
|
||
[args.input, out_fbx, str(args.tris), "none"])
|
||
warnings = list(s["warnings"])
|
||
from rizom_unwrap import RizomError, find_rizomuv, rizom_unwrap
|
||
try:
|
||
rizom_unwrap(out_fbx, find_rizomuv(args.rizom))
|
||
except RizomError as e:
|
||
warnings.append("RizomUV 不可用：%s" % e)
|
||
g = run_blender_script(blender, "bl_uvgate.py", [out_fbx, "rizom"])
|
||
s["uv"] = g["uv"]
|
||
s["warnings"] = warnings + g["warnings"]
|
||
else:
|
||
s = run_blender_script(blender, "bl_decimate.py",
|
||
[args.input, out_fbx, str(args.tris), args.unwrap])
|
||
|
||
print("== %s: %d -> %d 面（目标 %d）-> %s" %
|
||
(s["src"], s["tris_before"], s["tris_after"], s["target"], out_fbx))
|
||
u = s["uv"]
|
||
overlap = "%.1f%%" % (u["overlap"] * 100) if u["overlap"] is not None else "n/a"
|
||
print(" UV: 模式=%s 岛数=%d 利用率=%.1f%% 翻转=%.1f%% 重叠=%s" %
|
||
(u["mode"], u["islands"], u["fill"] * 100, u["flipped"] * 100, overlap))
|
||
for w in s["warnings"]:
|
||
print(" [警告] %s" % w)
|
||
|
||
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
|
||
- [ ] **Step 2: 全量单测**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest discover -s tests -p "test_*.py" 2>&1 | tail -3
|
||
```
|
||
|
||
预期：`OK`。
|
||
|
||
- [ ] **Step 3: 端到端冒烟——rizom 默认路径**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python model_decimate.py src/store10k.fbx --tris 10000
|
||
```
|
||
|
||
预期：`UV: 模式=rizom ...`，无"回退"警告；记录岛数/利用率/翻转/重叠，与旧 smart_fallback 基线（岛 1405 / 利用率 36.4%）对比，利用率应明显更高。
|
||
|
||
- [ ] **Step 4: 端到端冒烟——回退路径**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python model_decimate.py src/store.fbx --tris 3000 --rizom Z:/no/such.exe
|
||
```
|
||
|
||
预期：警告含"RizomUV 不可用"，`UV: 模式=seam_fallback ...` 且指标达标（store 3000 面 seam 基线：岛 388 / 利用率 54.9% / 翻转 0.2% / 重叠 6.2%）。
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/model_decimate.py && git commit -m "ModelTranslator: 减面默认 RizomUV 展开（三步编排，失败/不达标回退 seam）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 6: 烘焙链路验证 + README
|
||
|
||
**Files:**
|
||
- Modify: `Tools/ModelTranslator/README.md`（依赖节 + model_decimate 说明）
|
||
|
||
- [ ] **Step 1: rizom 产物烘焙冒烟**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python model_bake.py src/store10k.fbx src/store10k_low.fbx
|
||
```
|
||
|
||
预期：五张贴图全出、无警告。用 Read 工具查看 `out_bake/store10k/store10k_color.png`：岛内无黑斑/脏色。
|
||
|
||
- [ ] **Step 2: 更新 README**
|
||
|
||
`README.md` 「依赖」节 Blender 条目后加：
|
||
|
||
```markdown
|
||
- RizomUV 2025+（可选，UV 展开质量更好；默认路径 `C:\Program Files\RizomUV2025\rizomuv.exe`，也可用 `--rizom` 参数或环境变量 `RIZOMUV_EXE` 指定；未安装自动回退 Blender 展开）
|
||
```
|
||
|
||
「减面与高低模烘焙」节中 model_decimate.py 的说明整句改为：
|
||
|
||
```markdown
|
||
- **model_decimate.py**：多 mesh 自动 join；三角化后 Decimate(collapse) 减到 `--tris`（±3%，最多 2 轮修正）；旧 UV 全删后重展——默认 **RizomUV 自动切缝展开**（官方 RizomUVLink 驱动：MOSAIC 分割 + 切柄/连洞 + Pack，会短暂弹出 RizomUV 窗口、占一个 license），RizomUV 不可用或质量门不达标（翻转 >2% 或重叠 >8%）自动回退锐边 seam 展开（再不达标回退 Smart UV Project）；`--unwrap seam|smart` 可跳过 RizomUV；输出 `<名>_low.fbx`（`-o` 改目录），日志报 UV 岛数/利用率
|
||
```
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/README.md && git commit -m "ModelTranslator: README 补 RizomUV 展开说明（store10k 冒烟对比通过）"
|
||
```
|
||
|
||
---
|
||
|
||
## 自审记录
|
||
|
||
- Spec 覆盖：默认 rizom（Task 5）、AutoSeam（Task 3）、回退链 rizom→seam→smart（Task 4/5）、exe 发现四级（Task 2）、超时（Task 3 `_call`）、无 UV 视同不达标（Task 4）、日志口径（Task 5 沿用）、README（Task 6）、单测+冒烟+回退冒烟（Task 1/2/5/6）——全覆盖
|
||
- 占位符扫描：无 TBD/省略；所有代码块完整
|
||
- 类型一致性：`uv_gate_ok(flipped, overlap)`（Task 1 定义，Task 4 使用）、`RizomError/find_rizomuv/rizom_unwrap`（Task 2/3 定义，Task 5 导入）、`candidate_paths(cli, env, reg, default)` 签名测试与实现一致
|