---
license: cc-by-nc-4.0
library_name: pytorch
pipeline_tag: text-to-3d
tags:
  - text-to-motion
  - motion-generation
  - skeleton
  - animation
  - flow-matching
---

# TopX

TopX generates motion for an unseen skeleton from a text prompt and the skeleton file alone: its kinematic tree, rest
pose and joint names. No clips of the character, templates, retargeting or fine-tuning are needed. It is a 73M-parameter
flow-matching transformer with attention factorised over joints and frames; across joints, queries and keys are rotated
by HK-RoPE, a heat-kernel rotary encoding of the skeleton graph. One model animates skeletons from 4 to 117 joints and
generates up to 240 frames at 30 fps.

**Code:** https://github.com/CHDTevior/TopX-OOD-Code · **Project page:** https://chdtevior.github.io/TopX-page/ · **Paper:** [arXiv:2610.34321](https://arxiv.org/abs/2610.34321)

## Files

| file | content | sha256 |
|---|---|---|
| `topx.pt` | `{"config": architecture and normalisation, "model": state dict}` (293 MB, float32) | `f6d8e086235d1f99069cce47a2a7e5d59141a9442b7b5b2880937716b0ee405a` |

## Usage

```bash
git clone https://github.com/CHDTevior/TopX-OOD-Code.git && cd TopX-OOD-Code
pip install -r requirements.txt
huggingface-cli download Tevior/TopX-OOD topx.pt --local-dir weights
bash demo/run_demos.sh                                   # nine demo skeletons, no text encoder needed
python scripts/generate.py --ckpt weights/topx.pt --skeleton my_rig.bvh --up +Y --forward +Z \
    --text "An object walks forward and sits down." --frames 120 --out out/
```

The output is a BVH file of the input hierarchy (in its own axes and units), an `.npz` with joint positions and
rotations, and a GIF preview. Prompts and joint descriptions are encoded with LLM2Vec
(`McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised`, built on the gated `meta-llama/Meta-Llama-3-8B-Instruct`).

## Training data

The training split of the SkelShift benchmark: the Objaverse-XL subset of UniML3D, the AniMo4D animal library with
HumanML3D, further animations and species from the same game library as AniMo4D, and the Truebones zoo (139,102 clips
on 5,127 skeletons with 6 to 142 joints). See the paper for the split and the evaluation.

## License

The weights are released under [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use
with attribution. The code is MIT-licensed. Licences of the training data and of the text encoder apply to their
respective parts.

## Citation

```bibtex
@article{sun2026topx,
  title   = {TopX: Text-to-Motion for Unseen Skeletons from the Skeleton File Alone},
  author  = {Sun, Tengjiao and Fang, Pengcheng and Zhan, Xiaoyu and Fu, Dongjie and Cai, Xiaohao and Kim, Hansung},
  journal = {arXiv preprint arXiv:2610.34321},
  year    = {2026}
}
```