| --- |
| 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} |
| } |
| ``` |
|
|
