From 26d91b0e7d0e3b952b4ffdc220803fcef5cb32e3 Mon Sep 17 00:00:00 2001 From: ud18010 Date: Fri, 17 Jul 2026 15:30:53 +0800 Subject: [PATCH] =?UTF-8?q?ModelTranslator:=20RizomUV=20=E6=8E=A5=E5=85=A5?= =?UTF-8?q?=20UV=20=E5=B1=95=E5=BC=80=E7=AE=A1=E7=BA=BF=E8=AE=BE=E8=AE=A1?= =?UTF-8?q?=EF=BC=88=E9=BB=98=E8=AE=A4=E6=A8=A1=E5=BC=8F+=E8=B4=A8?= =?UTF-8?q?=E9=87=8F=E9=97=A8=E5=9B=9E=E9=80=80=20seam/smart=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- .../specs/2026-07-17-rizomuv-unwrap-design.md | 92 +++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-17-rizomuv-unwrap-design.md diff --git a/docs/superpowers/specs/2026-07-17-rizomuv-unwrap-design.md b/docs/superpowers/specs/2026-07-17-rizomuv-unwrap-design.md new file mode 100644 index 00000000..b88af7da --- /dev/null +++ b/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 模式说明（实现时更新）