---
license: mit
tags:
  - onnx
  - auto-rigging
  - skeleton-prediction
  - rigging
  - 3d
  - qtmesheditor
library_name: onnx
pipeline_tag: other
---

# UniRig (skeleton stage) — ONNX export

**ONNX re-export of the skeleton-prediction stage of
[VAST-AI/UniRig](https://huggingface.co/VAST-AI/UniRig)** (*"One Model to Rig
Them All"*, SIGGRAPH 2025 — MIT code + MIT weights, trained on
Articulation-XL2.0 / CC-BY-4.0): an autoregressive transformer that predicts a
full skeleton (joints + hierarchy) from raw mesh geometry — no template or
markers needed. All credit for the original weights goes to VAST-AI-Research.

Exported for **[QtMeshEditor](https://github.com/fernandotonon/QtMeshEditor)**
(issue #408), powering `qtmesh rig --algo unirig`, the Inspector's
**Generate Rig (AI)** button, and the `auto_rig` MCP tool — local inference
via ONNX Runtime with a template-rig fallback.

> The files QtMeshEditor downloads at runtime live in the shared
> [`fernandotonon/QtMeshEditor-models`](https://huggingface.co/fernandotonon/QtMeshEditor-models)
> repo under `unirig/`. This repo is the standalone model card + mirror.

Note: UniRig's **skin-weight head is not included** — it depends on
spconv/PTv3, which has no ONNX lowering. For ML skin weights see
[`QtMeshEditor-skintokens-onnx`](https://huggingface.co/fernandotonon/QtMeshEditor-skintokens-onnx).

## Files

| file | role |
|---|---|
| `encoder.onnx` | Michelangelo point-cloud encoder: `pc [1,N,3]` + `feats [1,N,3]` (normals), N ≤ 65536 → latent prefix |
| `decoder.onnx` | ~350M-param causal-LM **KV-cache step** |
| `embed.onnx` | token id → embedding |

## Inference contract

1. Surface-sample up to 65536 points + normals, normalise into a centred unit
   box (+Y up).
2. Run the encoder → latent prefix for the LM.
3. Greedy **constrained** autoregressive decode with a manual KV cache,
   masking each step to the tokenizer FSM's valid next tokens (a documented
   simplification of upstream's beam+sampling — deterministic, still yields a
   valid tree). Safety cap 2048 tokens; generation ends at EOS (typically
   ~180 tokens).
4. Detokenize: 256 coordinate bins over `[-1,1]`,
   `undiscretize(t) = (t+0.5)/256*2-1`; vocab 267 (`branch=256`, `bos=257`,
   `eos=258`); per-bone records `[branch?, parent xyz, joint xyz]` → joints +
   parent indices. Match branch parents to the nearest earlier joint rather
   than requiring exact bin equality — real decodes frequently miss the exact
   bin.

## Reproducing

`scripts/export-unirig-onnx.py` in the QtMeshEditor repo (one-time, offline;
via `optimum` with a hand-rolled KV-cache fallback).

## License

MIT (same as the upstream code and weights). Training data: Articulation-XL2.0
(CC-BY-4.0) — credit VAST-AI-Research.