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

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