AIC-Project/docs/superpowers/plans/2026-07-20-remove-rizomuv.md

移除 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 四个文件

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 整文件替换为

"""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: 验证残留引用与单测

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: 提交

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 行：

调用：blender -b --factory-startup --python bl_decimate.py -- <src.fbx> <out.fbx> <target_tris> [seam|smart|none]

改为：

调用：blender -b --factory-startup --python bl_decimate.py -- <src.fbx> <out.fbx> <target_tris> [seam|smart]

• Step 2: main() 删 none 分支

现有：

    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)

替换为：

    uv_info = _do_unwrap(obj, unwrap_mode, warnings)

（_clear_uv_layers 仍被 _unwrap_seam/_unwrap_smart 使用，保留。）

• Step 3: 回归单测

cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest discover tests 2>&1 | tail -3

Expected: OK

• Step 4: 提交

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 行

删除整行：

- RizomUV 2025+（可选，UV 展开质量更好；默认路径 `C:\Program Files\RizomUV2025\rizomuv.exe`，也可用 `--rizom` 参数或环境变量 `RIZOMUV_EXE` 指定；未安装或未授权自动回退 Blender 展开）

• Step 2: 重写 model_decimate.py 条目

现有 - **model_decimate.py**：... 整条替换为：

- **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: 全文残留检查

grep -in rizom "D:/UD/AI/AIC#Project/Tools/ModelTranslator/README.md" ; echo "grep_done"

Expected: 无输出（只打印 grep_done）

• Step 4: 提交

cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/README.md && git commit -m "ModelTranslator: README 移除 RizomUV 相关说明"

---

Task 4: 冒烟验证（默认路径 + 非法参数）

• Step 1: 默认路径冒烟

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: 非法参数报错

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: 清理

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. 记忆已清理，全部改动已提交