# SkinTokens turns skinning weights into a vocabulary, and rigs a mesh with one sequence > SkinTokens is a learned discrete representation of skinning weights, and TokenRig is the autoregressive model built on it that generates a skeleton and its weights as a single token sequence from one mesh. The paper reports large accuracy gains over separate-stage baselines, and the code ships as a research release with a 14 GB GPU requirement and a Hugging Face demo. **VAST-AI-Research/SkinTokens** — SkinTokens: A Learned Compact Representation for Unified Autoregressive Rigging - Repository: https://github.com/VAST-AI-Research/SkinTokens - Website: https://zjp-shadow.github.io/works/SkinTokens/ - Stars: 535 · Forks: 78 - Language: Python - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/vast-ai-research-skintokens ## One sequence instead of two stages SkinTokens is a learned, compact and discrete representation for skinning weights. Built on that representation, TokenRig is a unified autoregressive framework that models the entire rig, that is skeleton and skinning weights, as a single token sequence. Given an input 3D mesh, it generates a complete skeleton hierarchy and skin weights that can be directly imported into standard 3D pipelines for character animation and simulation. The point of the representation is in how it changes the problem. Skinning weights are, conventionally, a dense per-vertex vector, and the usual automatic rigging systems either predict them with a regression head or generate them with a separate model, which is why the pipeline tends to be split into a skeleton stage and a skinning stage. Making them discrete and compact turns them into tokens, and tokens are what a language model already knows how to emit. So the rig becomes a sequence: the skeleton first, then the skin tokens, interleaved, generated by one autoregressive model. The comparison with the previous work is the paper's own claim. SkinTokens is the successor to UniRig, from SIGGRAPH '25, and while UniRig uses separate stages for skeleton prediction and skinning, SkinTokens unifies both into a single autoregressive sequence via learned discrete skin tokens. The README states the effect as a 98% to 133% improvement in skinning accuracy and a 17% to 22% improvement in bone prediction over state-of-the-art baselines. Those are large numbers and they are the authors' measurements against their chosen baselines, so they are worth reading with the usual caution. The paper is on arXiv as 2602.04805, the project page carries the teaser and the qualitative comparisons, and the code and checkpoints are under the VAST-AI-Research organisation. The project is Python, MIT licensed, with no published GitHub releases and the last push on 2026-05-12. ## The three stage method The overview describes the method in three stages, and each one is a separate piece of machinery. The first is learning SkinTokens. An FSQ-CVAE compresses sparse skinning weights into a compact discrete vocabulary. FSQ is finite scalar quantization, so the encoder maps a weight vector onto a grid of fixed levels and the decoder reconstructs the weights, and the discrete codes are what the second stage emits. The compression is what makes the whole thing possible, because a raw weight vector per vertex would be an enormous number of tokens to generate. The second is unified autoregressive modeling. A Qwen3-0.6B-based Transformer generates the full rig, skeleton followed by SkinTokens, as one interleaved sequence. So the base model is a small language model, which is a deliberate choice: the sequence machinery, the sampling and the training tricks all come for free, and a 0.6 billion parameter model is small enough to run on a single consumer GPU. The third is RL refinement via GRPO. Tailored geometric and semantic rewards, namely volumetric joint coverage, bone-mesh containment, skinning sparsity and deformation smoothness, refine the model for out-of-distribution assets. That last stage is the interesting one for a practitioner. A model trained on a particular corpus of human-made characters will do something predictable and mediocre on a creature, a prop or a hard-surface object. The reinforcement learning stage exists to move the model off that distribution, and the reward function is a geometric specification of what makes a rig good: every bone should occupy volume, bones should be inside the mesh, the weights should be sparse so that a vertex is not influenced by many bones, and the deformation should be smooth. So the design is: a tokenizer for the hard part, a language model for the sequence, and a reward function for the cases the corpus did not cover. ## What you need and how to install it The hardware requirement is the first thing to read, because it decides whether this is even a candidate. An NVIDIA GPU with at least 14 GB of memory is required for inference. The software requirements are Python 3.11 or newer, the CUDA Toolkit 12.1 or newer, and uv is recommended for managing dependencies. The install steps are four commands plus the model download. First the clone: ```sh git clone https://github.com/VAST-AI-Research/SkinTokens.git cd SkinTokens ``` Then the environment and PyTorch, with the version pinned and the CUDA build selected in the index URL: ```sh uv venv --python 3.11 source .venv/bin/activate uv pip install torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 --index-url https://download.pytorch.org/whl/cu128 ``` The README carries a note on that line: adjust the CUDA version in the PyTorch index URL to match your driver, with a pointer to the PyTorch getting started page for the other CUDA versions. The `cu128` in the URL is a CUDA 12.8 build, and a mismatched index is the usual cause of a wheel that will not import. Then the dependencies, the flash-attention build, and the checkpoints: ```sh uv pip install -r requirements.txt ``` ```sh uv pip install flash-attn --no-build-isolation ``` ```sh python download.py --model ``` The `--no-build-isolation` flag on flash-attn matters. That package compiles against the installed PyTorch, so it needs to see the torch you just installed rather than a fresh one in an isolated build environment. The download step puts the TokenRig and FSQ-CVAE checkpoints into `experiments/`, and the Qwen3-0.6B config into `models/`, which tells you the directory layout the code expects. ## The models, the demo and the command line Two pretrained models are published on Hugging Face under VAST-AI/SkinTokens, and the first one is the one you want. `articulation_xl_quantization_256_token_4` is the TokenRig autoregressive rigging model, trained on ArticulationXL 2.0 plus VRoid Hub plus ModelsResource and refined with GRPO. The README marks it as recommended. The name encodes the design: 256 tokens, a 4-level quantization, and a training set that is a mix of a large articulated dataset, anime style characters and scanned models. `skin_vae_2_10_32768` is the FSQ-CVAE, the skin-weight tokenizer used to encode and decode skinning weights. You need it to run inference, since it is what turns the emitted tokens back into weights. For trying it, the README offers a hosted Hugging Face Space where you upload a mesh and get a rigged result in the browser, which is the easiest way to see what the model does before you commit a GPU to it. Locally, `python demo.py` starts a Gradio interface on `http://127.0.0.1:1024`. The command line is where the real options are: ```sh # Rig a single model python demo.py --input examples/giraffe.glb --output results/giraffe.glb # Rig with original texture and scale preserved python demo.py --input examples/giraffe.glb --output results/giraffe.glb --use_transfer # Skin a model using its existing skeleton python demo.py --input examples/giraffe_skeleton.glb --output results/giraffe.glb --use_skeleton --use_transfer # Batch process a directory python demo.py --input examples/ --output results/ --use_transfer ``` `--use_transfer` preserves the original texture and scale, and `--use_skeleton` reuses an existing skeleton so only the skinning is generated. The third command is the one to note: a mesh that already has a skeleton only needs weights, and that is a much easier task for the model than inventing the hierarchy as well. The generation parameters are a normal set for a transformer sampler, with `--top_k` at 5, `--top_p` at 0.95, `--temperature` at 1.0, `--repetition_penalty` at 2.0 and `--num_beams` at 10 for beam search. There is also `--use_postprocess` for applying voxel-based skin postprocessing. ## The dependency set tells you what is really involved The requirements file is short enough to read as a description of the pipeline, and two entries stand out. `bpy>=4.2` is the Blender Python module. So this project is not only generating data structures, it is driving Blender, and the repository has a `bpy_server.py` at the root, which is presumably how the mesh is loaded, the rig is built and the result is exported. That explains the dependency on `trimesh` and `open3d` as well, which handle the mesh geometry itself. The rest of the list is the machine learning stack. `transformers>=4.57.0` for the Qwen3 model, `diffusers>=0.35.0` for the diffusion model used in the token pretraining, `lightning` for the training loop, `omegaconf` and `python-box` for configuration, `einops` for tensor manipulation, `addict` for dictionary attribute access, and `fast-simplification` for mesh decimation. The serving and interface side is `gradio` for the local demo, `bottle` and `tornado` for the web layer, `huggingface_hub` for the model download, and `numpy>=1.26.0`. So the pipeline touches a graphics engine, a mesh processing library, a transformer stack and a diffusion stack. That is a wide dependency surface for a research release, and it is worth remembering that `bpy` in particular is a large, platform-sensitive install. The repository layout matches: `src/` for the code, `configs/` for the configuration, `demo.py` and `download.py` at the root, `examples/giraffe.glb` as the sample asset, and `assets/` for the figures used in the README. ## Where this fits, and what it costs The alternative approaches to automatic rigging fall into three categories, and the differences are about who does the work. The first is hand rigging in a DCC application, which is what most characters still go through. A human builds the bone hierarchy and paints the weights. The difference in approach is that TokenRig replaces an artist judgement with a learned prior over what a plausible skeleton looks like, which is faster and consistent but produces a rig that a human may want to adjust. The second is a commercial auto-rigging product. The README even links one, the Tripo 3D Studio, in the badge row. The difference there is support and a service rather than a model: you get a product with a company behind it, and you get whatever constraints it imposes. The third is a two-stage learned system, which is what UniRig was, and what the SkinTokens paper is measured against. The claimed advantage of the unified approach is that the two problems inform each other, since the skeleton the model chooses changes the weights that are sensible, and the weights push back on the skeleton during generation. The costs are concrete. A 14 GB GPU is a real constraint, and inference rather than training, so this is a deployment-shaped requirement rather than a research one. The Blender dependency means the output path goes through a graphics engine. The model is trained on a specific mix of datasets, so a character outside that mix is out of distribution, which is exactly the case the GRPO stage was added to address, and the README calls that stage the answer for it rather than a guarantee. And the project is a research artefact: no releases are published, the checkpoints are on Hugging Face, and the accuracy figures come from the authors. For a studio that rigs hundreds of assets, the sensible next step is to run it on your own asset mix and compare against your own baseline, which is also the only way to find out whether the out-of-distribution behaviour is acceptable for your pipeline. ## Conclusion Adopt TokenRig if you are producing rigged characters in volume and have the GPU budget for it, since a single mesh in and a rig out removes the most tedious part of asset production. Do not adopt it as a production service, since the repository publishes no releases, the checkpoints are research artefacts, and the reported accuracy gains are the authors' own measurements against their chosen baselines. Verify first that you have an NVIDIA GPU with at least 14 GB of memory and a CUDA toolkit of 12.1 or newer, that the download script has placed both the TokenRig and the FSQ-CVAE checkpoints in `experiments/`, that flash-attn installed with `--no-build-isolation` on your PyTorch build, and that the mesh you feed it is the kind of asset the ArticulationXL, VRoid Hub and ModelsResource training mix resembles. ## FAQ ### What are SkinTokens and TokenRig? SkinTokens is a learned, compact and discrete representation for skinning weights. TokenRig is the unified autoregressive framework built on it, which models the entire rig, skeleton and skinning weights, as a single token sequence and generates a complete skeleton hierarchy and skin weights for an input 3D mesh. ### How does TokenRig differ from UniRig? SkinTokens is the successor to UniRig from SIGGRAPH 2025. UniRig uses separate stages for skeleton prediction and skinning, while SkinTokens unifies both into a single autoregressive sequence via learned discrete skin tokens, which the README reports as a 98% to 133% improvement in skinning accuracy and 17% to 22% in bone prediction over state-of-the-art baselines. ### What hardware do I need to run TokenRig? An NVIDIA GPU with at least 14 GB of memory is required for inference. The software requirements are Python 3.11 or newer and the CUDA Toolkit 12.1 or newer, with uv recommended for managing dependencies. ### How do I install the SkinTokens project? Clone the repository, create a virtual environment with `uv venv --python 3.11` and install the pinned PyTorch build from the CUDA index URL, then install the requirements, install flash-attn with `--no-build-isolation`, and finally run `python download.py --model` to fetch the TokenRig and FSQ-CVAE checkpoints into `experiments/` and the Qwen3-0.6B config into `models/`. ### Which pretrained models are available? Two on Hugging Face: `articulation_xl_quantization_256_token_4`, the recommended TokenRig rigging model trained on ArticulationXL 2.0, VRoid Hub and ModelsResource and refined with GRPO, and `skin_vae_2_10_32768`, the FSQ-CVAE skin-weight tokenizer used to encode and decode skinning weights. ## Sources - [Issues](https://github.com/VAST-AI-Research/SkinTokens/issues) - [License: MIT](https://github.com/VAST-AI-Research/SkinTokens/blob/main/LICENSE) - [Project website](https://zjp-shadow.github.io/works/SkinTokens/) - [README](https://github.com/VAST-AI-Research/SkinTokens/blob/main/README.md) - [VAST-AI-Research/SkinTokens on GitHub](https://github.com/VAST-AI-Research/SkinTokens) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vast-ai-research-skintokens