Open infrastructure for human motion models, benchmarks, and interoperable motion data.

Train, run, compare, and connect motion systems without rebuilding the runtime around every method.

Documentation · Quickstart · Tasks · Datasets · Models · Training · Evaluators · Benchmarks · Motion I/O

Motius packages motion methods behind consistent bundles, task pipelines, trainers, evaluators, and representation bridges.

Start here

Install from source:

git lfs install
git clone https://github.com/ZeyuLing/Motius.git
cd Motius
git lfs pull
python -m pip install -e ".[dev]"

Git LFS materializes the simulator meshes and USD assets used by the public motion-tracking trainers.

Load any released checkpoint through its self-describing artifact:

from motius import Pipeline

pipe = Pipeline.from_pretrained(
    "ZeyuLing/Motius-MoMask-HumanML3D",
    bundle_kwargs={"device": "cuda"},
)
motions = pipe.infer_text_to_motion(
    ["a person walks forward and then sits down"],
    [120],
)
print(motions[0].shape)  # (120, 263), HumanML3D physical scale

The artifact declares its trusted Motius pipeline, task APIs, required files, and bundled dependencies. Pipeline.from_pretrained never executes Python code from the checkpoint repository.

Continue with the installation and smoke tests, then choose a dataset, a task, a released method, or a benchmark.

Datasets

The Dataset Hub records the official source, Motius-hosted copy when one exists, expected local directory, supported tasks, and benchmark split contract for every public dataset.

Browse all datasets, download commands, and protocol notes.

Task system

The Task Registry is the only public task vocabulary. Tasks are listed flat instead of being forced into overlapping modality or capability families. Tracks such as prediction, in-betweening, sparse keyframes, and TP2M remain inside their parent task.

Model cards use these exact labels. Benchmark settings use Task · Setting, such as Text-to-Motion · SMPL Skeleton and Sequential Text-to-Motion · BABEL.

Models and benchmarks

Motion interoperability

Representation and embodiment

HumanML3D-263 → SMPL-22 → SOMA-30 / ARDY-Core-27 → Unitree G1

Open synchronized viewer · Representation matrix · Conversion API · Retargeting routes

The shared bridge connects native feature vectors, SMPL-family bodies, kinematic skeletons, rigged characters, and robot embodiments. Exact routes preserve source state; lossy joint-only and cross-skeleton routes expose their IK or retargeting diagnostics.

Actor count is an orthogonal layout property. Single-person motion uses (T, D); paired and multi-person motion use (T, A, D) in one shared world frame. The GT InterX comparison and Three.js viewer show InterHuman-262 and SMPL-H under the same conversion contract.

Character Export

Any supported human-motion representation can pass through the SMPL-22 bridge into a rigged FBX character. Compare the same motion as a skeleton, an SMPL mesh, and four Mixamo characters in the 30 fps character preview, then follow the FBX export guide. Starting from a static humanoid instead? The automatic rigging pipeline imports GLB/GLTF/FBX/OBJ/PLY/STL, fits and skins a canonical SMPL-22 armature, and exports a rigged FBX or GLTF asset for the same motion bridge.

Automatic Rigging: Diverse Meshes To Motion

Motius exposes two Auto-Rig paths behind auto_rig_character(): a fully local, deterministic template baseline for upright T/A-pose humans, and an optional make_it_animatable backend for characters with much wider shapes and proportions. Both paths produce a Motius-compatible SMPL-22 bone subset that can be driven through the existing FBX motion bridge.

The approved demo below starts from three downloaded, textured meshes. Input audits verify zero armatures, Armature modifiers, vertex groups, and Actions; the characters are then auto-rigged, normalized to the SMPL-22 contract, and driven by the same stored 150-frame HumanML3D motion. The cyan/white overlay is the generated skeleton, not a reference skeleton:

Open the full 960 × 540, 30 fps MP4, inspect the machine-readable manifest, or read the Auto-Rig guide.

The diverse-character demo uses the upstream Make-It-Animatable inference backend, followed by Motius's Mixamo-to-SMPL22 normalization, motion retargeting, orientation priors, validation, and rendering. The integration is explicit so the media is not misrepresented as output from the simpler local template fitter. Install the optional client and run it with:

pip install -e ".[auto-rig]"
python tools/auto_rig_character.py character.glb rigged.fbx \
  --method make-it-animatable --blender /path/to/blender

The public backend uploads the input mesh to a third-party Hugging Face Space; use a trusted self-hosted endpoint for private assets. Auto-Rig creates the rest rig and skin, while animation retargeting is a separate stage. This remains a rigging and deformation smoke test, not proof of production-quality anatomy on every mesh. See the guide for method boundaries, third-party attribution, and the foot/head orientation limitations of position-only SMPL-22 motion.

Train and extend

The Training Hub is the source of truth for which packages have Motius-native trainers. It documents data contracts, precision, losses, distributed launch, full-state resume, checkpoint cadence, and output layout. An integrated inference pipeline is not automatically advertised as trainable.

Train a Python config locally or with Accelerate:

python tools/train.py path/to/config.py \
  --work-dir outputs/training/my_experiment --auto-resume
accelerate launch tools/train.py path/to/config.py \
  --work-dir outputs/training/my_distributed_experiment --auto-resume

A method package owns its model, bundle, trainer adapter, task pipeline, and evaluation adapters. The common runtime owns distributed execution, checkpoint I/O, registration, conversion, and lifecycle hooks.

Use the architecture guide to add a package, the development guide for repository conventions, and the Training Hub for the supported-package matrix and released recipes.

Architecture

flowchart LR
    C["Config and dataset"] --> R["Registry"]
    R --> B["ModelBundle"]
    B --> T["Trainer"]
    B --> P["Task pipeline"]
    P --> E["Benchmark adapters"]
    P --> M["Motion Toolkit"]
    T --> X["Distributed runtime"]
    E --> L["Persisted results"]
    M --> O["Bodies, characters, robots"]

The split is intentional: a method can change architecture without renaming its task, a benchmark can change dataset without becoming a new method, and a motion representation can change without silently changing evaluation space.

Documentation

Project status

Motius is an active research release. Public artifacts are versioned, evaluation protocols are persisted with their results, and method-specific licenses and upstream attribution remain documented in each model card. Core APIs may evolve as additional methods move onto the shared runtime.