UniRig自动骨骼蒙皮部署
UniRig由清华大学计算机系与VAST- Tripo3d 联合研发，是首个支持全类别3D模型的自动骨骼绑定框架。该框架创新性地将骨骼结构转换为序列化标记，利用自回归模型实现拓扑结构预测。
其突破在于使用包含14,000+模型的Rig-Articulation-XL2.0数据集，通过大规模训练使模型具备跨类别泛化能力。
# 结论
- 生成人体主体骨骼比较准确，在无人工干预的情况下生成的 骨架和 Mixamo (opens new window) 人工干预生成的差不太多，但是还没达到能代替人工操作的精度，部分关节位置有少许偏差，但各种模型都能生成骨骼,Mixamo 只能生成人型。
- 生成蒙皮权重一般，具体效果比 Mixamo (opens new window) 差一点，但胜在通用性，各种模型都能算，其蒙皮预测模型结构 比腾讯的 GoSkining 简单太多，最终效果更是无法比较。但和 meshy.ai (opens new window) 、accurig (opens new window) 这些比较还是要强些。
- 适应性强，人，飞鸟，动物模型都能生成不错的骨骼（没有针对人型做特别训练）。
- 受数据集影响 预训练模型比较差，全是 Mixamo (opens new window) ，VRoid Hub (opens new window)来的角色模型，原始训练数据中的关节位置，蒙皮权重都只有非常少量的人工参与或是由业余爱好者制作，训练出来的模型肯定不会太好。
# 其他问题
- 目前生成的骨骼没有结构命名，关于骨骼属性预测相关功能，项目说后续会放出。
- 生成的绑定模型，会将全部模型合并，并且是重心原点，而非通常的脚底原点。
- 只支持 Blender 导出的 fbx 格式，3dsMax 导出的FBX无法正确读取。
# 蒙皮预测
随机从原数据集中拿一个模型进行测试，左侧图是 预测蒙皮权重，右侧是原始蒙皮权重。
# 骨骼预测
与上图同样模型，红色为预测骨架，绿色为原始骨骼。
抛开手指偏差，整体还原度还是非常可以的，连手肘处关节的错误都是一样的。
# 核心方法：自回归预测与创新的 Tokenization
UniRig 的核心在于借鉴了 驱动语言 和 图像生成领域进步的大型自回归模型的力量。
实现这一目标的关键创新是骨骼树 Tokenization (Skeleton Tree Tokenization) 方法。
关节坐标：骨骼关节的离散化空间位置。
层级结构：明确的父子关系，确保生成有效的树状结构。
骨骼语义：使用特殊 Token 标识骨骼类型（例如，Mixamo 等标准模板骨骼，用于头发 / 布料模拟的动态弹簧骨骼）。
这种优化的 Tokenization 方案，与朴素方法相比，序列长度减少约 30%，使得基于 OPT 架构的自回归模型能够有效地学习骨骼结构的内在模式，并以形状编码器处理后的输入模型几何信息作为条件。
项目链接
论文链接
[2504.12451] One Model to Rig Them All: Diverse Skeleton Rigging with UniRig (opens new window)
# Articulation-XL2.0 数据集
本项目的预训练模型使用的 是 南洋理工和字节跳动 联合发布的 Articulation-XL2.0 (opens new window) 数据集。
而角色模型基本是在 Github.com (opens new window) ，VRoid Hub (opens new window) 上找的公开角色 fbx,vrm 资源，而且在收集过程中 渲染每个模型，让视觉语言模型 ChatGPT-4 给每个模型生成描述标题。
模型绑定骨骼数量在 10 - 256之间。
总共分 8 个类型:
- mixamo（单独分类）
- 其他人型 （Biped）
- 四足（Quadruped）
- 鸟，飞行 （Bird Flyer）
- 多足蜘蛛 （Insect Arachnid）
- 水生怪物 （Water Creature）
- 静态（Static）
- 其他 （Other）
# 各类别占比
# 模型骨骼数量分布
我随机下载两个，如下
mixamo的模型主要都是人体主体骨骼，很少有其他附加骨骼，而 VRiod 模型则会多出 裙摆、头发等Spring 骨骼。
论文上提到的 物理模拟辅助训练策略,是指在训练模型时，对飘带骨骼进行飘带计算，来评估骨骼和蒙皮效果（个人感觉完全没有必要，用随机旋转效果可能好），而其他类型的模型，如mixamo 类，直接加载一段动画来评估，其他怪物等，采用骨骼随机角度旋转的方式来评估蒙皮效果。
虽然在模型数量上 人型占大多数，但论文作者在预训练时，人为将人型类型采样概率调整 40%
VRoid 25%, Mixamo 5%，其他人型10% ，四足 20% ，飞行 15%，静态 5%，多足 10%，水生 怪 10 % ，也就是说为了发论文，论证该方案能适应多种模型，特意调低了人型的适应性。
如果要实际落地使用，应该为不同类别训练不同的模型，毕竟各类别蒙皮复杂度和骨骼结构差异毕竟大。
提示
数据集作者认为 VRoid 模型质量比较高，所以给的采样率高达 25% ，下图是 VRoid Hub 首页截图。 从下载的模型来看，其实整个训练数据集质量并不高。
部分角色模型名单： meta_Articulation_XL_2.0.csv · Seed3D/Articulation-XL2.0 at main (opens new window)
# 骨骼命名风格
国内游戏行业常用的 骨架命名风格 ：3dsMax - Biped , Maya - Adv
上面的 骨骼语义 是指骨骼名字，预测骨架，预测蒙皮权重，骨骼的命名有非常大的影响权重.
# mixamorig (opens new window)命名风格
/UniRig/configs/skeleton/mixamo.yaml
# Vroid (opens new window) 风格
/configs/skeleton/vroid.yaml
尚不清楚，项目中内置的两个骨架命名风格有何作用，猜测是后续输出生成骨架的命名.
# 实际测试
目前项目只放出一个 run.py 应用测试脚本，具体参数设置等没有任何说明文档。
- 输入模型 生成骨骼。
- 输入模型和骨骼 生成蒙皮权重。
本次测试分两类:
- 从其训练的数据集里挑两个模型测试其还原效果。
- 使用全新模型进行测试。
重点是蒙皮权重，骨骼生成实际应用范围比较小。
提示
- 目前生成的骨骼没有结构命名，关于骨骼属性预测相关功能项目说后续会放出。
- 生成的绑定模型，会将全部模型合并，并且是重心原点，而非通常的脚底原点。
- 只支持 Blender 导出的 fbx 格式，3dsMax 导出的FBX无法正确读取。
# 骨骼生成
输入模型，直接预测生成骨骼，如下图。
没找到什么控制参数，速度挺快，但是生成的骨骼不对称，无结构命名。
- bash launch/inference/generate_skeleton.sh --input examples/test_HF.obj --output results/test_HF_skeleton.fbx
# 生成蒙皮
# 身体
主体骨架命名风格
# 披风
单层，实测双层披风权重效果和也差不多，只是里外层穿帮的多。
披风骨骼命名风格
效果还是不错，毕竟训练的数据集里，很少有披风的模型。
- bash launch/inference/generate_skin.sh --num_runs 4 --input examples/skeleton/test01/PC_HF_MB_Bow-UniRig-noSkin-bl.fbx --output results/PC_HF_MB_Bow-UniRig-Skin.fbx
# 部署
📌
在 192.168.239.199 的wsl2 Ubuntu 上部署，使用CUDA12.1 环境。
在 Ubuntu 上部署基本上没啥特别地方，基础要求是：
- Python 3.11 + CUDA 12.1
conda create -n UniRig python=3.11
conda activate UniRig
2
在 Ubunte 上创建的py环境，默认路径 /home/nd/miniconda3/envs/ 其中的 nd 是我系统用户名。
创建环境之后，手动安装下面 4 个包。
- torch-2.4.0+cu121-cp311-cp311-win_amd64.whl
- torch_scatter-2.1.2+pt24cu121-cp311-cp311-win_amd64.whl
- torch_cluster-1.6.3+pt24cu121-cp311-cp311-win_amd64.whl
- torchvision-0.19.0+cu121-cp311-cp311-win_amd64.whl
可以从下面两个链接中找到上面 4 个包。
进入上面创建的环境 目录，拉取Github 上的项目。
cd miniconda3/envs/UniRig/
git clone https://github.com/VAST-AI-Research/UniRig
cd UniRig
2
3
拉取完整之后，再cd 进入 项目文件夹中。最终项目路径 miniconda3/envs/UniRig/UniRig/名为 UniRig 的环境中有个 UniRig 项目文件夹。
📌
注意 项目的 examples 文件中的 glb 模型因 LFS问题无法拉取成功，可手动下载。
接着就执行 自动安装 环境 依赖。
pip install -r requirements.txt
最后 安装 3 个特定版本的 依赖包。
pip install spconv-cu121
pip install numpy==1.26.4
pip install fast_simplification==0.1.7
2
3
到此部署完成。
# 使用huggingface 的国内镜像
https://hf-mirror.com/ (opens new window)
运行时，相关的脚本会自动从 huggingface 下载模型，但是速度比较慢，还得设置代理，而直接使用国内镜像源，不用代理，速度也快。
export HF_ENDPOINT=https://hf-mirror.com
source ~/.bashrc
#查看是否正确添加 环境变量
echo $HF_ENDPOINT
2
3
4
5
📌
这种环境变量设置是临时，下次链接 WSL 主机时，就会被重置。
/home/nd/.cache/huggingface/hub/models--VAST-AI--UniRig/ 下载的模路径。
# 安装Blender 4.2
该项目输入模型 直接 多种 格式，其中包括 fbx ， 但不支持对 3dsMax ,Maya 导出的Fbx 。
需要提前将你的 FBX 模型导入 Blender 中洗一次出来。
导入 带骨骼的FBX设置，如下图。
# 错误解决
# pyrender版本问题
项目使用的 pyrender 0.1.45 , 但是安装d 时候因为要 PyOpenGl 配合，实际安装是 pyrender 0.1.5
而0.1.5版本修改比较多。
# 缺少 shaders
如下图，找一个 pyrender 0.1.45 的shaders 文件复制过去就行。
# /home/nd/miniconda3/envs/UniRig/UniRig/src/data/vertex_group.py
修改显示方案为 osmeas
GLTF 修改成 pyrender.constants.GLTF.TRIANGLES
get_nodes 修改成 _get_nodes
