Model card

README.md

@@ -0,0 +1,65 @@
+---
+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 · **Paper:** arXiv (link coming soon)
+
+## 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},
+  year    = {2026}
+}
+```