243 lines
9.0 KiB
Markdown
243 lines
9.0 KiB
Markdown
# 移除 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 -- <src.fbx> <out.fbx> <target_tris> [seam|smart|none]
|
||
```
|
||
|
||
改为：
|
||
|
||
```python
|
||
调用：blender -b --factory-startup --python bl_decimate.py -- <src.fbx> <out.fbx> <target_tris> [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. 记忆已清理，全部改动已提交
|