unirig

unirig — 自动 3D 绑定（骨架 → 蒙皮 → 合并）

关键词：unirig · auto-rigging · skeleton prediction · skinning weights

仅对用户获准修改的资产进行绑定。UniRig 采用 MIT 许可，但其检查点、Rig-XL/VRoid/Objaverse 数据以及用户自己的模型各自都有对应的条款。

UniRig 是一个两阶段自回归绑定框架：类似 GPT 的 Transformer 根据网格几何预测拓扑有效的骨架，随后骨骼点交叉注意力模型预测每个顶点的蒙皮权重。第三步会将预测得到的绑定合并回原始资产（完整分辨率、带纹理）。

最常见的失败是跳过合并阶段或合并了错误的文件——请参阅步骤 5。第二常见的失败是环境中悄然缺少 CUDA 扩展。

何时使用此技能

• 用户希望将静态 3D 角色、生物或道具转换为已绑定的资产
• 用户只需要骨架，或需要为已编辑的骨架添加蒙皮权重
• 用户需要在 CUDA 机器上安装并验证 UniRig，或希望事先确认自己的机器无法运行它
• 用户希望对目录中的模型进行批量绑定
• 用户正在选择 UniRig、其后续项目 SkinTokens，或传统／托管式绑定工具
• 用户已有绑定输出，并希望验证关节和蒙皮权重是否确实已写入

说明

步骤 1：收集初始信息并选择阶段

开始任何操作前，收集以下四项信息：

• 资产：文件格式（.obj、.fbx/.FBX、.dae、.glb、.gltf、.vrm）、面数、单个模型还是目录、是否带纹理
• 目标：仅骨架、仅蒙皮，还是完整的绑定交付物
• 硬件：NVIDIA GPU + CUDA 版本、显存、操作系统（没有 CUDA ⇒ 无法推理；请转用其他方案）
• 限制条件：安装成本（UniRig 需要 spconv、flash_attn、torch_scatter、torch_cluster、bpy），以及是否需要手动控制骨架

路由规则：

1. 静态网格，尚无骨架 → 骨架阶段（--stage skeleton）
2. 已有骨架（预测生成或手动编辑）→ 蒙皮阶段（--stage skin）
3. 交付物必须保留原始几何和材质 → 合并阶段（--stage merge）
4. 三个阶段一次完成 → --stage all（scripts/rig.sh 的默认值）
5. 没有 CUDA GPU，或用户需要由美术人员控制命名／IK／约束 → 转用其他方案 （参见 references/route-outs-and-troubleshooting.md）

步骤 2：安装任何内容之前检查环境

bash scripts/doctor.sh            # human-readable readiness report
bash scripts/doctor.sh --json     # machine-readable, for agent branching

doctor.sh 会报告 Python 3.11、torch 与 CUDA 是否可用、spconv、torch_scatter、torch_cluster、flash_attn、bpy、trimesh、UniRig 检出目录、其 launch/inference 脚本，以及 Hugging Face 是否可访问。缺少阻塞项时，它会以 1 退出，因此 Agent 可以在承诺生成无法运行的绑定前停止。若检出目录不在 ~/.cache/unirig/UniRig，请使用 --unirig-home <path>（或 UNIRIG_HOME）。

步骤 3：安装此技能，并在机器符合条件时安装上游仓库

npx skills add https://github.com/akillness/jeo-skills --skill unirig

bash scripts/install.sh --repo-only          # clone/update UniRig only
bash scripts/install.sh --cuda cu121         # clone + create venv + install deps
bash scripts/install.sh --cuda cu121 --torch 2.4.0 --vrm

安装程序刻意采取保守策略：

• 如果机器上没有 nvidia-smi，除非传入 --force，否则不会安装仅支持 CUDA 的 wheel；
• spconv-<cuda> 和 PyG wheel 索引会根据 --cuda/--torch 确定，与上游 README 保持一致，而不会猜测某个固定版本的 wheel；
• 最后才尝试安装 flash_attn；如果失败会明确报告，不会忽略——源码构建方式请参阅故障排除参考；
• --vrm 还会注册随附的 Blender VRM 插件。

完整的依赖详情见 references/environment-and-install.md。

步骤 4：先通过试运行规划流程，再执行

# print the exact upstream commands without executing them
bash scripts/rig.sh --input examples/giraffe.glb --output results/giraffe_rigged.glb --dry-run

# run the whole pipeline (skeleton → skin → merge)
bash scripts/rig.sh --input examples/giraffe.glb --output results/giraffe_rigged.glb

# one stage at a time
bash scripts/rig.sh --stage skeleton --input model.glb --output results/model_skeleton.fbx
bash scripts/rig.sh --stage skin --input results/model_skeleton.fbx --output results/model_skin.fbx
bash scripts/rig.sh --stage merge --source results/model_skin.fbx --target model.glb \
  --output results/model_rigged.glb

# whole directory (skeleton and skin stages only — upstream merge takes one file pair)
bash scripts/rig.sh --stage skeleton --input-dir assets/ --output-dir results/skeletons/

rig.sh 是对 launch/inference/generate_skeleton.sh、 generate_skin.sh 和 merge.sh 的轻量、如实封装：它会验证输入后缀，在最终输出旁生成中间文件 <input>_skeleton.fbx / <input>_skin.fbx 路径（可通过 --skeleton-out / --skin-out 覆盖），从 UNIRIG_HOME 按顺序运行各阶段，并在缺少预期产物时失败，而不是报告一个实际上并未写出的骨骼绑定结果。--seed、 --faces-target-count、--num-runs、--add-root、--force-override、--skeleton-task 和 --skin-task 会直接传递给上游，并采用上游自身的默认值。

步骤 5：遵守两条合并规则

1. 合并蒙皮文件，而不是骨架文件。 merge.sh --source <skeleton>.fbx 会生成一个没有蒙皮权重的 骨架。要生成可交付的骨骼绑定结果，请使用 *_skin.fbx 输出。
2. 先修复骨架，再进行蒙皮。 缺少骨骼（尾巴、翅膀、额外肢体）时，蒙皮质量会大幅下降。在 Blender 中手动编辑预测的骨架，然后对编辑后的 FBX 重新运行 --stage skin。不同的 --seed 值会生成不同的骨架方案——提交前可以低成本采样几个。

阶段标志、默认值、配置文件和 tmp/ npz 缓存记录在 references/inference-pipeline.md 中。

步骤 6：验证交付产物，不要想当然

python3 scripts/inspect_glb.py results/model_rigged.glb
python3 scripts/inspect_glb.py results/model_rigged.glb --json

inspect_glb.py 仅使用标准库（无需 torch 或 Blender）：它会解析 GLB/glTF JSON 块，并报告网格、节点、skins、关节数量、动画，以及是否有任何网格图元带有 JOINTS_0/WEIGHTS_0 属性。如果文件没有蒙皮，它会以 1 退出；这正是“误合并了骨架文件”的情况。对于 FBX 输出，请在 Blender 中或使用 bpy 验证（参见故障排除参考）——FBX 是二进制格式，无法仅用标准库解析。

步骤 7：训练和数据集（仅在用户要求时）

训练、Rig-XL/VRoid 数据布局、raw_data.npz 键模式以及 Rignet 验证任务均记录在 references/training-and-datasets.md 中。对于只需要推理的请求，不要启动训练——首次推理时会自动下载已发布的检查点。

示例

示例 1：“帮我给这个 GLB 角色绑定骨骼”

doctor.sh → rig.sh --dry-run 显示计划 → rig.sh → 使用 inspect_glb.py 确认输出包含蒙皮和关节。

示例 2：“尾巴没有骨骼”

不要基于错误的骨架重新运行蒙皮。使用另一个 --seed 重新采样，或在 Blender 中编辑骨架 FBX，然后对编辑后的文件运行 --stage skin 并重新合并。

示例 3：“我用的是 MacBook”

doctor.sh 会以阻止状态退出。请直截了当地说明，并改用 CUDA 机器／云 GPU、托管的 Tripo 骨骼绑定服务，或传统的 Mixamo/AccuRig/Rigify——不要假装存在 CPU 后备方案。

示例 4：“UniRig 和 SkinTokens 哪个更好？”

SkinTokens 是同一实验室推出的后续项目（统一的自回归蒙皮 Token，经过 RL 训练，据报告蒙皮效果提升 98–133%，骨骼预测提升 17–22%）。新项目建议使用它；如果用户需要 UniRig 已发布的检查点、其 Rig-XL 工具，或现有可用环境，则继续使用 UniRig。

检查清单

1. 在操作 shell 之前，先记录资产／目标／硬件／限制信息。
2. 先运行 doctor.sh；如果环境存在阻碍，应报告问题，而不是盲目安装。
3. 在没有 NVIDIA GPU 的机器上，绝不安装仅支持 CUDA 的 wheel。
4. 在长时间运行 GPU 任务之前，先试运行工作流，并展示准确的上游命令。
5. 先修复骨架，再进行蒙皮；拓扑结构看起来不对时，抽样测试种子。
6. 将 *_skin.fbx 合并到原始资产中，绝不要合并 *_skeleton.fbx。
7. 使用 inspect_glb.py（GLB）或 Blender（FBX）验证交付内容——绝不能仅凭命令退出代码就声称成功。
8. 如果 UniRig 不适用，应如实转向 SkinTokens、托管服务或传统绑定人员。

参考资料

• references/environment-and-install.md — Python 3.11、torch/CUDA 矩阵、spconv/PyG/flash_attn 常见问题、检查点、VRM 插件
• references/inference-pipeline.md — extract/skeleton/skin/merge 的所有上游标志和默认值、配置、tmp/ npz 缓存
• references/training-and-datasets.md — Rig-XL/VRoid 数据、raw_data.npz 架构、配置分层、训练和 Rignet 验证任务
• references/route-outs-and-troubleshooting.md — 不应使用 UniRig 的情况，以及反复出现的安装／运行时错误
• scripts/doctor.sh — 就绪情况报告（--json；受阻时退出代码为 1）
• scripts/install.sh — 技能插件 + 上游克隆／venv／依赖项
• scripts/rig.sh — 支持按阶段运行的包装脚本，带有 --dry-run
• scripts/inspect_glb.py — 基于标准库的 GLB/glTF 绑定验证工具
• UniRig repository · 论文 · 检查点 · SkinTokens 后续项目