ModelTranslator: RizomUV 接入 UV 展开管线设计（默认模式+质量门回退 seam/smart）

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/superpowers/specs/2026-07-17-rizomuv-unwrap-design.md

@@ -0,0 +1,92 @@
+# ModelTranslator：UV 展开接入 RizomUV 设计
+
+日期：2026-07-17
+状态：已确认
+
+## 背景与目标
+
+`model_decimate.py` 现有两种 UV 重展模式：锐边 seam（默认）与 Smart UV Project（回退）。
+在高面数目标（如 store 10000 面）下锐边碎多，seam 展开质量不过门回退 smart，
+利用率明显下降（36.4% vs 54.9%）。
+
+本机装有 RizomUV 2025（`C:\Program Files\RizomUV2025\rizomuv.exe`），其自动分割/展开/打包
+质量优于 Blender 内建方案。目标：把 RizomUV 接入为**默认** UV 展开模式，
+不可用或质量不达标时自动回退现有链路。
+
+## 决策记录
+
+- **接入方式**：rizom 设为 `--unwrap` 默认值；`seam`/`smart` 保留可选（用户确认）
+- **切缝策略**：RizomUV 全自动切缝（AutoSeam），不用锐边角度口径（用户确认）
+- **运行行为**：RizomUVLink 启动真实 RizomUV 实例（弹窗、占一个 license token），
+  批处理时窗口短暂出现后自动关闭——用户确认可接受
+- **管线形态**：FBX 直进直出 RizomUV（方案 A），不走 OBJ 中转
+
+## 架构
+
+```
+model_decimate.py src/x.fbx --tris N [--unwrap rizom|seam|smart] [--rizom exe路径]
+  │
+  ├─ 1. bl_decimate.py（Blender）：join + 三角化 + 减面
+  │     unwrap=rizom 时以 "none" 模式运行：不展 UV，直接导出 x_low.fbx
+  │
+  ├─ 2. rizom_unwrap.py（系统 Python + RizomUVLink）：
+  │     Load(x_low.fbx) → AutoSeam → Unfold → Optimize → Pack → Save(覆盖 x_low.fbx) → Quit
+  │
+  └─ 3. bl_uvgate.py（Blender）：载入 rizom 输出量 UV 指标
+        ├─ 达标（翻转 ≤2% 且 重叠 ≤8%）→ 通过，x_low.fbx 即最终产物
+        └─ 不达标 → 就地 seam 重展（内部含 smart 回退），重新导出覆盖
+```
+
+回退链：**rizom →（不可用/不达标）→ seam →（不达标）→ smart**。
+每次回退在 warnings 中说明原因。
+
+### 组件职责
+
+| 组件 | 职责 | 依赖 |
+|---|---|---|
+| `model_decimate.py` | CLI 编排三步；`--unwrap` 默认 `rizom`；新增 `--rizom` 覆盖 exe 路径 | mt_run |
+| `bl_decimate.py` | 新增 `none` 展开模式（减面不展 UV）；`seam`/`smart` 逻辑不动 | Blender |
+| `rizom_unwrap.py`（新） | RizomUVLink 驱动 RizomUV 完成自动切缝/展开/打包；进程内完成，异常抛给上层 | RizomUVLink（随 RizomUV 安装自带，MIT） |
+| `bl_uvgate.py`（新） | 量 UV 指标（复用 bl_decimate 现有 bmesh 指标函数）；不达标就地重展并重导出 | Blender |
+
+### RizomUV 发现与调用
+
+- 查找顺序：`--rizom` 参数 → 环境变量 `RIZOMUV_EXE` → Windows 注册表
+  （`SOFTWARE\Rizom Lab\RizomUV VS RS 202X.Y`，官方 README 提供的方法）→
+  `C:\Program Files\RizomUV2025\rizomuv.exe` 兜底
+- `RizomUVLink` 模块从 RizomUV 安装目录 `RizomUVLink/` 动态 `sys.path` 引入，
+  按当前 Python 版本自动加载对应 pyd（本机 3.12 匹配 `rizomuvlink_python312.pyd`）
+- 展开参数：AutoSeam 全自动；Pack 岛距对齐现有 `PACK_MARGIN`（4px@2048）、允许旋转；
+  Optimize 迭代数用 RizomUV 默认值，实现时依据本地 `doc/index.html` 脚本参考校准命令名
+- 实例生命周期：一次减面 = 启动一次 RizomUV、处理一个 FBX、Quit 释放；
+  不做常驻实例（CLI 工具场景，简单可靠优先）
+
+## 错误处理
+
+| 情形 | 行为 |
+|---|---|
+| RizomUV 未安装 / exe 不存在 | 警告 + 回退 seam，不中断 |
+| RizomUVLink import 失败（Python 版本不配等） | 警告 + 回退 seam |
+| 启动/license 获取失败、IPC 断连（CZEx）、超时（默认 300s） | 警告 + 回退 seam |
+| Rizom 输出 FBX 无 UV 或 Blender 无法导入 | 视同不达标，bl_uvgate 就地重展 |
+| 质量门不达标（翻转 >2% 或 重叠 >8%） | bl_uvgate 就地 seam 重展（内部含 smart 回退） |
+
+## 日志与产物
+
+- 日志格式沿用：`UV: 模式=rizom 岛数=N 利用率=X% 翻转=X% 重叠=X%`；
+  回退时模式显示 `seam_fallback` / `smart_fallback` 并带警告行
+- 产物不变：`<名>_low.fbx`，后续 `model_bake.py` / `model_translator.py` 管线无感知
+
+## 测试
+
+- 纯函数（RizomUV 路径解析、回退决策）进 `tests/` unittest，不依赖 RizomUV/Blender
+- 端到端冒烟：store.fbx 减面 3000 / 10000 两档，对比 rizom vs seam 的
+  岛数/利用率/翻转/重叠；各跑一次 `model_bake.py` 确认贴图无脏色
+- 回退路径冒烟：`--rizom` 指向不存在的 exe，确认回退 seam 且产物正常
+
+## 非目标
+
+- 不做 RizomUV 常驻实例/连接池
+- 不做 UDIM、多 UV 通道、纹理密度均衡等高级功能
+- 不改 seam/smart 现有算法与阈值
+- README 补 rizom 模式说明（实现时更新）