# UniRig
**Repository Path**: render3d/UniRig
## Basic Information
- **Project Name**: UniRig
- **Description**: UniRig 是全新的统一自动化骨骼绑定框架，它提出了一个强大的统一模型，能够为前所未有、种类繁多的 3D 模型生成高质量的绑定数据，涵盖人类、动物、复杂的幻想角色乃至无机结构
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://www.oschina.net/p/unirig
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-04-22
- **Last Updated**: 2025-04-22
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# UniRig: One Model to Rig Them All
[](https://zjp-shadow.github.io/works/UniRig/)
[](https://arxiv.org)
[](https://huggingface.co/VAST-AI/UniRig)
This repository contains the official implementation for the **UniRig** framework, a unified solution for automatic 3D model rigging, developed by Tsinghua University and [Tripo](https://www.tripo3d.ai).
**Paper:** [One Model to Rig Them All: Diverse Skeleton Rigging with UniRig](https://arxiv.org)
## 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. **(⏳ Coming Soon)**
* **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 Prediction checkpoint trained on [**Articulation-XL2.0**](https://huggingface.co/datasets/Seed3D/Articulation-XL2.0). Available on [Hugging Face](https://huggingface.co/VAST-AI/UniRig).
**Planned Future Releases:**
* ⏳ Skinning Weight Prediction Model checkpoint(s).
* ⏳ Release of the **Rig-XL** and **VRoid** datasets used in the paper.
* ⏳ 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](https://github.com/orgs/VAST-AI-Research) announcements for updates!
## Installation
1. **Prerequisites:**
* Python 3.11
* PyTorch (tested with version >=2.3.1)
2. **Clone the repository:**
```bash
git clone https://github.com/VAST-AI-Research/UniRig
cd UniRig
```
3. **Set up a virtual environment (recommended):**
```bash
conda create -n UniRig python=3.11
conda activate UniRig
```
4. **Install dependencies:**
```bash
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
```
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](https://github.com/saturday06/VRM-Addon-for-Blender).
Make sure you are in the root directory of the project, then:
```bash
python -c "import bpy, os; bpy.ops.preferences.addon_install(filepath=os.path.abspath('blender/add-on-vrm-v2.20.77_modified.zip'))"
```
## Usage
### Skeleton Prediction (Available Now)
Generate a skeleton for your 3D model using our pre-trained model. The process automatically analyzes the geometry and predicts an appropriate skeletal structure.
```bash
# 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 --output_dir
# 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 (Coming Soon)
```bash
# 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 --output_dir
```
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:
```bash
# 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
```
## Models
Available models are hosted on the: https://huggingface.co/VAST-AI/UniRig
## System Requirements
- CUDA-enabled GPU with at least 8GB VRAM
## Citation
```
```
## Acknowledgements
We would like to thank the following open-source projects and research works:
- [OPT](https://huggingface.co/facebook/opt-350m) for model architecture
- [3DShape2VecSet](https://github.com/1zb/3DShape2VecSet) for 3D shape representation
- [SAMPart3D](https://github.com/Pointcept/SAMPart3D) and [Michelangelo](https://github.com/NeuralCarver/Michelangelo/) for shape encoder implementation
- [Articulation-XL2.0](https://huggingface.co/datasets/Seed3D/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.