UniRig: One Model to Rig Them All

[!IMPORTANT]

🔥 Exciting News: Introducing SkinTokens! 🔥

We are thrilled to announce SkinTokens, the powerful successor to UniRig (SIGGRAPH '25).

While UniRig uses separate stages for skeleton prediction and skinning, SkinTokens unifies both into a single autoregressive sequence via learned discrete skin tokens. By introducing Reinforcement Learning and an Efficient Skinning Compression Module, it pushes the boundaries of automated 3D rigging even further:

• 🚀 98%–133% improvement in skinning accuracy!
• 🦴 17%–22% improvement in bone prediction over state-of-the-art baselines!

👉 Click here to explore the SkinTokens repository now!

This repository contains the official implementation for the SIGGRAPH'25 (TOG) UniRig framework, a unified solution for automatic 3D model rigging, developed by Tsinghua University and Tripo.

Paper: One Model to Rig Them All: Diverse Skeleton Rigging with UniRig

Overview

Rigging 3D models – creating a skeleton and assigning skinning weights – is a crucial but often complex and time-consuming step in 3D animation. UniRig tackles this challenge by introducing a novel, unified framework leveraging large autoregressive models to automate the process for a diverse range of 3D assets.

Combining UniRig with keyframe animation produces these following results:

The full UniRig system consists of two main stages:

1. Skeleton Prediction: An GPT-like transformer autoregressively predicts a topologically valid skeleton hierarchy using a novel Skeleton Tree Tokenization scheme.
2. Skinning Weight & Attribute Prediction: A Bone-Point Cross Attention mechanism predicts per-vertex skinning weights and relevant bone attributes (e.g., for physics simulation) based on the predicted skeleton and input mesh geometry.

This repository provides the code implementation for the entire framework vision, with components being released progressively.

Key Features (Full UniRig Framework)

• Unified Model: Aims to handle diverse model categories (humans, animals, objects) with a single framework.
• Automated Skeleton Generation: Predicts topologically valid skeleton structures. (✅ Available in current release)
• Automated Skinning Prediction: Predicts per-vertex skinning weights. (✅ Available in current release)
• Bone Attribute Prediction: Predicts attributes like stiffness for physics-based secondary motion. (⏳ Coming Soon)
• High Accuracy & Robustness: Achieves state-of-the-art results on challenging datasets (as shown in the paper with Rig-XL/VRoid training).
• Efficient Tokenization: Uses Skeleton Tree Tokenization for compact representation and efficient processing.
• Human-in-the-Loop Ready: Designed to potentially support iterative refinement workflows.

🚨 Current Release Status & Roadmap 🚨

We are open-sourcing UniRig progressively. Please note the current status:

Available Now (Initial Release):

• ✅ Code: Implementation for skeleton and skinning prediction.
• ✅ Model: Skeleton & Skinning Prediction checkpoint trained on Articulation-XL2.0. Available on Hugging Face.
• ✅ Dataset: Release of the Rig-XL and VRoid datasets used in the paper. We also filtered out 31 broken models in the training dataset which do not affect the performance of the final model.
• ✅ Training code.

Planned Future Releases:

• ⏳ Full UniRig model checkpoints (Skeleton + Skinning) trained on Rig-XL/VRoid, replicating the paper's main results.

We appreciate your patience as we prepare these components for release. Follow VAST-AI-Research announcements for updates!

Installation

1. Prerequisites:

   • Python 3.11
   • PyTorch (tested with version >=2.3.1)

2. Clone the repository:

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

3. Set up a virtual environment (recommended):

   conda create -n UniRig python=3.11
   conda activate UniRig
   

4. Install dependencies:

   python -m pip install torch torchvision
   python -m pip install -r requirements.txt
   python -m pip install spconv-{you-cuda-version}
   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
   python -m pip install numpy==1.26.4
   

spconv is installed from this repo, torch_scatter and torch_cluster are installed from this site. Also, there is a high chance that you will encounter flash_attn installation error, go to its original repo and follow its installation guide.

5. Download Model Checkpoint: The currently available skeleton prediction model checkpoint is hosted on Hugging Face and will typically be downloaded automatically by the provided scripts/functions.

6. (Optional, for importing/exporting .vrm) Install the blender addon: The blender addon is modifed from VRM-Addon-for-Blender.

   Make sure you are in the root directory of the project, then:

   python -c "import bpy, os; bpy.ops.preferences.addon_install(filepath=os.path.abspath('blender/add-on-vrm-v2.20.77_modified.zip'))"
   

RigXL Dataset

processed data link

Notice that aside from vroid, all models are selected from Objaverse. Just download mapping.json if you already have Objaverse dataset (or need to download from web).

The json contains all ids of the models with type indicating their category and url specifying where to download. url is the same with fileIdentifier in Objaverse.

Training/validation split is put in datalist folder.

📝 Note:
All floating-point values are stored in float16 format for compression.

Visualize Data

Put the dataset in dataset_clean, go back to root, and run the command to export FBX model:

from src.data.raw_data import RawData
raw_data = RawData.load("dataset_clean/rigxl/12345/raw_data.npz")
raw_data.export_fbx("res.fbx")

Usage

Skeleton Prediction

Generate a skeleton for your 3D model using our pre-trained model. The process automatically analyzes the geometry and predicts an appropriate skeletal structure.

# Process a single file
bash launch/inference/generate_skeleton.sh --input examples/giraffe.glb --output results/giraffe_skeleton.fbx

# Process multiple files in a directory
bash launch/inference/generate_skeleton.sh --input_dir <your_input_directory> --output_dir <your_output_directory>

# Try different skeleton variations by changing the random seed
bash launch/inference/generate_skeleton.sh --input examples/giraffe.glb --output results/giraffe_skeleton.fbx --seed 42

Supported input formats: .obj, .fbx, .glb, and .vrm

Skinning Weight Prediction

# Skin a single file
bash launch/inference/generate_skin.sh --input examples/skeleton/giraffe.fbx --output results/giraffe_skin.fbx

# Process multiple files in a directory
bash launch/inference/generate_skin.sh --input_dir <your_input_directory> --output_dir <your_output_directory>

Note that the command above uses an edited-version from skeleton phase. The results may degrade significantly if the skeleton is inaccurate — for example, if tail bones or wing bones are missing. Therefore, it is recommended to refine the skeleton before performing skinning in order to achieve better results.

Merge the Predicted Results

Combine the predicted skeleton with your original 3D model to create a fully rigged asset:

# Merge skeleton from skeleton prediction
bash launch/inference/merge.sh --source results/giraffe_skeleton.fbx --target examples/giraffe.glb --output results/giraffe_rigged.glb

# Or merge skin from skin prediction
bash launch/inference/merge.sh --source results/giraffe_skin.fbx --target examples/giraffe.glb --output results/giraffe_rigged.glb

Note that there will be no skinning if you try to merge a skeleton file(giraffe_skeleton.fbx). Use the predicted skinning result(giraffe_skin.fbx) instead!

Rignet Dataset Validation

Validate the metrics mentioned in the paper. This is for academic usage.

First, Download the processed dataset from Hugging Face and extract it to the dataset_clean.

Then run the following command:

python run.py --task=configs/task/validate_rignet.yaml

To export skeleton & mesh, set record_res to True in the config file configs/system/ar_validate_rignet.yaml.

Train from Scratch

The code may be a bit messed up — hopefully this will be addressed in a future update from the VAST team.

bash launch/inference/preprocess.sh --config configs/data/<yourdata> --num_runs <number of threads to run>

python run.py --task=configs/task/train_rignet_ar.yaml

mode: predict # change it to predict
debug: False
experiment_name: test
resume_from_checkpoint: experiments/train_rignet_ar/last.ckpt # final ckpt path

components:
  data: quick_inference # inference data
  system: ar_inference_articulationxl # any system without `val_interval` or `val_start_from` should be ok
  tokenizer: tokenizer_rignet # must be the same in training
  transform: train_rignet_ar_transform # only need to keep the normalization method
  model: unirig_rignet # must be the same in training
  data_name: raw_data.npz

writer:
  __target__: ar
  output_dir: ~
  add_num: False
  repeat: 1
  export_npz: predict_skeleton
  export_obj: skeleton
  export_fbx: skeleton

trainer:
  max_epochs: 1
  num_nodes: 1
  devices: 1
  precision: bf16-mixed
  accelerator: gpu
  strategy: auto

bash launch/inference/generate_skeleton.sh --input examples/giraffe.glb --output examples/giraffe_skeleton.fbx --skeleton_task configs/task/rignet_ar_inference_scratch.yaml 

python run.py --task=configs/task/train_rignet_skin.yaml

mode: predict # change it to predict
debug: False
experiment_name: test
resume_from_checkpoint: experiments/train_rignet_skin/last.ckpt # final ckpt path

components:
  data: quick_inference # inference data
  system: skin
  transform: inference_skin_transform # do not need skin vertex_group
  model: unirig_skin # must be the same in training
  data_name: raw_data.npz

writer:
  __target__: skin
  output_dir: ~
  add_num: False
  repeat: 1
  save_name: predict
  export_npz: predict_skin
  export_fbx: result_fbx

trainer:
  max_epochs: 1
  num_nodes: 1
  devices: 1
  precision: bf16-mixed
  accelerator: gpu
  strategy: auto
  inference_mode: True

bash launch/inference/generate_skin.sh --input examples/skeleton/giraffe.fbx --output results/giraffe_skin.fbx --skin_task configs/task/rignet_skin_inference_scratch.yaml 

Models

Available models are hosted on the: https://huggingface.co/VAST-AI/UniRig

System Requirements

• For generation: CUDA-enabled GPU with at least 8GB VRAM

Citation

@article{10.1145/3730930,
author = {Zhang, Jia-Peng and Pu, Cheng-Feng and Guo, Meng-Hao and Cao, Yan-Pei and Hu, Shi-Min},
title = {One Model to Rig Them All: Diverse Skeleton Rigging with UniRig},
year = {2025},
issue_date = {August 2025},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
volume = {44},
number = {4},
issn = {0730-0301},
url = {https://doi.org/10.1145/3730930},
doi = {10.1145/3730930},
abstract = {The rapid evolution of 3D content creation, encompassing both AI-powered methods and traditional workflows, is driving an unprecedented demand for automated rigging solutions that can keep pace with the increasing complexity and diversity of 3D models. We introduce UniRig, a novel, unified framework for automatic skeletal rigging that leverages the power of large autoregressive models and a bone-point cross-attention mechanism to generate both high-quality skeletons and skinning weights. Unlike previous methods that struggle with complex or non-standard topologies, UniRig accurately predicts topologically valid skeleton structures thanks to a new Skeleton Tree Tokenization method that efficiently encodes hierarchical relationships within the skeleton. To train and evaluate UniRig, we present Rig-XL, a new large-scale dataset of over 14,000 rigged 3D models spanning a wide range of categories. UniRig significantly outperforms state-of-the-art academic and commercial methods, achieving a 215\% improvement in rigging accuracy and a 194\% improvement in motion accuracy on challenging datasets. Our method works seamlessly across diverse object categories, from detailed anime characters to complex organic and inorganic structures, demonstrating its versatility and robustness. By automating the tedious and time-consuming rigging process, UniRig has the potential to speed up animation pipelines with unprecedented ease and efficiency. Project Page: https://zjp-shadow.github.io/works/UniRig/},
journal = {ACM Trans. Graph.},
month = jul,
articleno = {123},
numpages = {18},
keywords = {auto rigging method, auto-regressive model}
}

Acknowledgements

We would like to thank the following open-source projects and research works:

• OPT for model architecture
• 3DShape2VecSet for 3D shape representation
• SAMPart3D and Michelangelo for shape encoder implementation
• Articulation-XL2.0 for a curated dataset

We are grateful to the broader research community for their open exploration and contributions to the field of 3D generation.