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