快速搭建UniRig：3D骨骼绑定全攻略

本地搭建UniRig

UniRig是一个自动绑定3D模型骨骼并分配蒙皮权重的工具。下面是本地搭建的步骤：

1.下载代码

git clone https://github.com/VAST-AI-Research/UniRig
cd UniRig

 2. 创建虚拟环境

建议的软件版本
Python 3.11
PyTorch (tested with version >=2.3.1)
创建当前目虚拟环境方法
conda create -p ./venv python=3.11
conda activate ./venv

 3. 安装依赖

这里的依赖flash_attn比较麻烦，需要本地编译，时间超长
可以下载别人编译好的，不过其它依赖就需要安装相应的版本了
linux版编译好的库
https://github.com/Dao-AILab/flash-attention/releases
windows版编译好的库
https://github.com/kingbri1/flash-attention/releases

安装torch和torchvision，为了匹配预编译好的flash-attention我安装的下面版本
pip install torch==2.5.0 torchvision==0.20.0 --index-url https://download.pytorch.org/whl/cu124

获得ABI状态
python -c "import torch; print(torch._C._GLIBCXX_USE_CXX11_ABI)  # 记下来输出的 True/False"
下载对应 wheel 安装（Python3.11 + torch2.5 + cu12 + CXX11_ABI 匹配）：
若 CXX11_ABI=False：
pip install flash_attn-2.8.3+cu12torch2.5cxx11abiFALSE-cp311-cp311-linux_x86_64.whl
若 CXX11_ABI=True：
pip install flash_attn-2.8.3+cu12torch2.5cxx11abiTRUE-cp311-cp311-linux_x86_64.whl

修改requirements.txt文件把里面的flash_attn注释掉
python -m pip install -r requirements.txt

安装spconv
python -m pip install spconv-{you-cuda-version}
上面安的是cu124，所以这里安
python -m pip install spconv-cu124

python -m pip install torch_scatter torch_cluster -f https://data.pyg.org/whl/torch-{your-torch-version}+{your-cuda-version}.html --no-cache-dir
# 安装torch_scatter、torch_cluster（替换torch版本和CUDA版本）
python -m pip install torch_scatter torch_cluster -f https://data.pyg.org/whl/torch-2.1.0+cu118.html --no-cache-dir

python -m pip install numpy==1.26.4

若使用出现其他ImportError如缺失(libGL.so.1)，可补充安装和图形图像有关的依赖
apt install -y libsm6 libxext6 libxrender1 libfontconfig1 libgl1-mesa-glx

4.模型下载

大模型会在执行骨骼绑定时自动下载
也可以在huggingface或魔搭上自行下载
https://huggingface.co/VAST-AI/UniRig/
https://www.modelscope.cn/models/VAST-AI-Research/UniRig
模型功能说明：
骨骼绑定模型生成fbx
UniRig/skeleton/articulation-xl_quantization_256/model.ckpt
将骨骼绑定的fbx与原始3D模型结合生成带骨骼的原始格式的3D模型
UniRig/skeleton/rignet/model.ckpt
使用骨骼绑定后的模型进行蒙皮权重预测
UniRig/skin/articulation-xl/model.ckpt

5.调用示例：

骨骼绑定模型生成fbx
# 单文件绑定骨骼
bash launch/inference/generate_skeleton.sh --input examples/giraffe.glb --output results/giraffe_skeleton.fbx
# 处理在一个文件夹中的多个文件
bash launch/inference/generate_skeleton.sh --input_dir <your_input_directory> --output_dir <your_output_directory>
# 设置随机种子生成不同的绑骨骼模型
bash launch/inference/generate_skeleton.sh --input examples/giraffe.glb --output results/giraffe_skeleton.fbx --seed 42

使用骨骼绑定后的模型进行蒙皮权重预测
# 蒙皮一个文件
bash launch/inference/generate_skin.sh --input examples/skeleton/giraffe.fbx --output results/giraffe_skin.fbx
# 处理多文件
bash launch/inference/generate_skin.sh --input_dir <your_input_directory> --output_dir <your_output_directory>

将骨骼绑定的fbx与原始3D模型结合生成带骨骼的原始格式的3D模型
# 基于原模型合并骨骼数据
bash launch/inference/merge.sh --source results/giraffe_skeleton.fbx --target examples/giraffe.glb --output results/giraffe_rigged.glb
# 基于蒙皮调整的骨骼数据与原模型合并
bash launch/inference/merge.sh --source results/giraffe_skin.fbx --target examples/giraffe.glb --output results/giraffe_rigged.glb