diff --git a/docs/superpowers/plans/2026-07-20-remove-rizomuv.md b/docs/superpowers/plans/2026-07-20-remove-rizomuv.md new file mode 100644 index 00000000..b104f753 --- /dev/null +++ b/docs/superpowers/plans/2026-07-20-remove-rizomuv.md @@ -0,0 +1,242 @@ +# 移除 RizomUV 流程实现计划 + +> **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:** 从 ModelTranslator 彻底删除 RizomUV 链路,减面默认走 seam 展开 + UVPM4 排布。 + +**Architecture:** 纯删除/简化,无新功能:删 4 个只服务 rizom 的文件;`model_decimate.py` 去掉三步编排只留单次 Blender 调用;`bl_decimate.py` 去掉 none 展开模式;README 与记忆同步清理。UVPM4 集成(commit d5b777b)不动。spec:`docs/superpowers/specs/2026-07-20-remove-rizomuv-design.md`。 + +**Tech Stack:** Python 3、Blender 5.0 headless(`D:\tools\blender-5.0.0-windows-x64\blender.exe`)。仓库路径含 `#`,bash 中所有路径必须加引号。工作目录 `D:/UD/AI/AIC#Project/Tools/ModelTranslator`。 + +--- + +## 文件结构 + +| 文件 | 操作 | +|---|---| +| `Tools/ModelTranslator/rizom_unwrap.py` | 删除 | +| `Tools/ModelTranslator/bl_uvgate.py` | 删除 | +| `Tools/ModelTranslator/tests/test_rizom_unwrap.py` | 删除 | +| `Tools/ModelTranslator/tests/test_bl_uvgate.py` | 删除 | +| `Tools/ModelTranslator/model_decimate.py` | 简化(删 rizom 分支/--rizom,默认 seam) | +| `Tools/ModelTranslator/bl_decimate.py` | 删 none 模式分支 + docstring | +| `Tools/ModelTranslator/README.md` | 删 RizomUV 依赖行,重写减面条目 | + +--- + +### Task 1: 删除 rizom 文件 + 简化 model_decimate.py(一个逻辑变更,一次提交) + +**Files:** +- Delete: `Tools/ModelTranslator/rizom_unwrap.py`、`Tools/ModelTranslator/bl_uvgate.py`、`Tools/ModelTranslator/tests/test_rizom_unwrap.py`、`Tools/ModelTranslator/tests/test_bl_uvgate.py` +- Modify: `Tools/ModelTranslator/model_decimate.py`(整文件替换) + +- [ ] **Step 1: git rm 四个文件** + +```bash +cd "D:/UD/AI/AIC#Project" +git rm Tools/ModelTranslator/rizom_unwrap.py Tools/ModelTranslator/bl_uvgate.py Tools/ModelTranslator/tests/test_rizom_unwrap.py Tools/ModelTranslator/tests/test_bl_uvgate.py +``` + +- [ ] **Step 2: `model_decimate.py` 整文件替换为** + +```python +"""FBX 减面 CLI:减到指定三角面数并重展 UV(seam 展开 + UVPM4 排布),输出 <名>_low.fbx。 +用法:python model_decimate.py src/well1500.fbx --tris 5000 [-o dir] + [--unwrap seam|smart] [--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=("seam", "smart"), default="seam", + help="UV 展开:seam=锐边接缝整岛展开(默认),smart=Smart UV Project") + 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") + + 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() +``` + +(相对原文件:docstring 更新;`--unwrap` choices 去掉 rizom、默认改 seam、help 去掉 rizom 描述;删 `--rizom` 参数;删 `if args.unwrap == "rizom":` 三步编排分支及 else 缩进——打印逻辑逐字保留。) + +- [ ] **Step 3: 验证残留引用与单测** + +```bash +cd "D:/UD/AI/AIC#Project" && grep -rin rizom Tools/ModelTranslator --include="*.py" ; echo "grep_done" +cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest discover tests 2>&1 | tail -3 +``` + +Expected: grep 无输出(只打印 grep_done);单测 OK(此时剩 test_bl_decimate/test_bl_bake/test_bl_convert/test_unity_assets)。若 `__pycache__` 命中 grep 属编译缓存,可 `rm -rf Tools/ModelTranslator/__pycache__ Tools/ModelTranslator/tests/__pycache__` 后重验。 + +- [ ] **Step 4: 提交** + +```bash +cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/model_decimate.py && git commit -m "ModelTranslator: 移除 RizomUV 链路——减面默认 seam+UVPM4 排布" +``` + +--- + +### Task 2: bl_decimate.py 删 none 模式 + +**Files:** +- Modify: `Tools/ModelTranslator/bl_decimate.py` + +- [ ] **Step 1: docstring 更新** + +第 2 行: + +```python +调用:blender -b --factory-startup --python bl_decimate.py -- [seam|smart|none] +``` + +改为: + +```python +调用:blender -b --factory-startup --python bl_decimate.py -- [seam|smart] +``` + +- [ ] **Step 2: main() 删 none 分支** + +现有: + +```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) +``` + +替换为: + +```python + uv_info = _do_unwrap(obj, unwrap_mode, warnings) +``` + +(`_clear_uv_layers` 仍被 `_unwrap_seam`/`_unwrap_smart` 使用,保留。) + +- [ ] **Step 3: 回归单测** + +```bash +cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest discover tests 2>&1 | tail -3 +``` + +Expected: OK + +- [ ] **Step 4: 提交** + +```bash +cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_decimate.py && git commit -m "ModelTranslator: bl_decimate 删 none 展开模式——随 rizom 链退役" +``` + +--- + +### Task 3: README 清理 + +**Files:** +- Modify: `Tools/ModelTranslator/README.md` + +- [ ] **Step 1: 依赖节删 RizomUV 行** + +删除整行: + +```markdown +- RizomUV 2025+(可选,UV 展开质量更好;默认路径 `C:\Program Files\RizomUV2025\rizomuv.exe`,也可用 `--rizom` 参数或环境变量 `RIZOMUV_EXE` 指定;未安装或未授权自动回退 Blender 展开) +``` + +- [ ] **Step 2: 重写 model_decimate.py 条目** + +现有 `- **model_decimate.py**:...` 整条替换为: + +```markdown +- **model_decimate.py**:多 mesh 自动 join;三角化后 Decimate(collapse) 减到 `--tris`(±3%,最多 2 轮修正);旧 UV 全删后重展——默认锐边 seam 整岛展开,质量门不达标(翻转 >2% 或重叠 >8%)自动回退 Smart UV Project,`--unwrap smart` 可直接选投影式展开;排布默认用 UVPackmaster 4 重排(利用率显著提升,日志模式带 `+uvpm` 后缀,4px@2048 像素边距与烘焙 padding 同口径),UVPM4 不可用自动沿用内置 pack_islands 布局;输出 `<名>_low.fbx`(`-o` 改目录),日志报 UV 岛数/利用率 +``` + +- [ ] **Step 3: 全文残留检查** + +```bash +grep -in rizom "D:/UD/AI/AIC#Project/Tools/ModelTranslator/README.md" ; echo "grep_done" +``` + +Expected: 无输出(只打印 grep_done) + +- [ ] **Step 4: 提交** + +```bash +cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/README.md && git commit -m "ModelTranslator: README 移除 RizomUV 相关说明" +``` + +--- + +### Task 4: 冒烟验证(默认路径 + 非法参数) + +- [ ] **Step 1: 默认路径冒烟** + +```bash +cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" +PYTHONIOENCODING=utf-8 python model_decimate.py src/store.fbx --tris 3000 -o "$TEMP/mt_norizom_smoke" +``` + +Expected: +- `UV: 模式=seam+uvpm`(注意:不再是 seam_fallback+uvpm——rizom 链没了) +- 利用率 ~75% +- **无任何 RizomUV 字样输出、无弹窗**、整体耗时明显短于此前默认路径 + +- [ ] **Step 2: 非法参数报错** + +```bash +PYTHONIOENCODING=utf-8 python model_decimate.py src/store.fbx --tris 3000 --unwrap rizom 2>&1 | tail -2 +``` + +Expected: argparse 报错 `invalid choice: 'rizom'`,退出码非 0 + +- [ ] **Step 3: 清理** + +```bash +rm -rf "$TEMP/mt_norizom_smoke" +``` + +--- + +### Task 5: 记忆清理(由主会话控制器执行,不派子代理) + +- [ ] 删除 `C:\Users\Administrator\.claude\projects\D--UD-AI-AIC-Project\memory\rizomuv-license-blocker.md` +- [ ] 从 MEMORY.md 索引删除对应行 +- [ ] 检查其他记忆(hotupdate 等)无 rizom 引用 + +--- + +## 完成标准 + +1. `python -m unittest discover tests` 全绿 +2. `grep -rin rizom Tools/ModelTranslator --include="*.py" --include="*.md"` 零命中 +3. 冒烟:默认路径 `模式=seam+uvpm`;`--unwrap rizom` 参数非法 +4. 记忆已清理,全部改动已提交