# 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 模式说明（实现时更新）