AMASS: the tutorials and tooling behind a human motion capture archive

This repository is the code, not the dataset

AMASS is a large database of human motion that unifies different optical marker based motion capture datasets by representing them within a common framework and parameterization, and the README says it is readily useful for animation, for visualization and for generating training data for deep learning. But this repository is not the database. It holds the tutorials and helper code released with the AMASS paper at ICCV 2019, and the data itself lives at the project's own site. The division of responsibility is stated explicitly, and it is worth internalising before you file anything. Questions about the dataset itself, meaning its contents, its frame rates, its ground planes, its coordinate conventions, its missing subjects and download access, go to the contact listed on that website and not to this repository. That boundary keeps the issue tracker focused on code, and it also means the repository cannot tell you whether the data you downloaded is complete or whether the conventions you assumed are right.

The status note is the most useful paragraph in the README

The README opens with a status section dated 2026-09-17, and it is unusually precise about what has and has not been checked. The repository holds the tutorials and helper code released with the paper and is not under active development. On that date the dependencies were pinned so the notebooks match the installed `human_body_prior`, specifically so that the notebooks' BodyModel calls, the ones taking `bm_fname`, `num_betas`, `num_dmpls` and `dmpl_fname`, match the installed code. Those calls were exercised with a synthetic body model in a test file called `tests/test_tutorial_calls.py`, and each notebook's setup cells are run in `tests/test_notebook_prefixes.py`. And then the sentence that matters for anyone planning work: the tutorials were not run end to end with the licence gated SMPL+H and SMPL-X models and the AMASS data. In other words, the code is checked at the seams, where a changed API would break a notebook, and not at the far end, where the data and the licensed models meet. A researcher can rely on the notebooks being in step with the pinned library and should still expect to debug the first real run.

The body model stack, and where the models come from

The modelling pipeline is described in the Body Models section. AMASS uses the MoSh++ pipeline to fit the SMPL+H body model to human optical marker based motion capture data, and in the paper they use SMPL+H with an extended shape space, that is 16 betas, together with 8 DMPLs. The README also notes that AMASS is compatible with the SMPL and SMPL-X body models, and that the tools show how to use the body data from AMASS to animate those models. The models themselves are not in the repository, and the instruction is to download them and place them in the `body_models` folder of the repository after obtaining the code from GitHub. That separation is a licensing boundary as much as a size boundary, since the body models come with their own terms, which is also why the status note says the tutorials were not exercised with the licence gated models. The repository's own split recommendations are provided as well, with three non-overlapping train, validation and test splits following the recommended splits of the data.

Installing, and the two smoke tests that stand in for a full run

The requirements are a Python version, a pinned library and some visualisation tooling. Python 3.11 or 3.12, the Human Body Prior pinned by commit in both `requirements.txt` and `setup.py`, which brings PyTorch with it, and `body_visualizer` together with Pyrender for the visualisations in the notebooks. The install is two commands run from the root folder, and the tests are one more:

pip install -r requirements.txt
pip install -e .

pip install pytest
pytest tests

The packaging metadata is strict about the Python version, with `python_requires` set to 3.11 up to but not including 3.13, and the package version is 1.0.1 with the package root under `src/`. The two test files are the practical answer to the fact that the notebooks cannot be run end to end in CI, since the licence gated models are not available there. `test_tutorial_calls.py` checks the body model call signatures against a synthetic model, and `test_notebook_prefixes.py` runs the setup cells of each notebook, which catches a changed import or a changed constructor before a researcher spends an afternoon on it.

Why the dependencies are pinned to commits rather than versions

The requirements file explains the pinning policy in a comment, and the reason is the same one the status note gives. The `human_body_prior` package is pinned to a commit so that the `BodyModel(bm_fname=...)` call in the notebooks matches the installed code, and `body_visualizer` is pinned the same way, while torch, numpy and tqdm come with `human_body_prior` rather than being listed separately. The rest of the list is short and readable, with trimesh, tables, ipywidgets and matplotlib, which is a useful contrast with a typical research requirements file. The `setup.py` repeats the pin inside `install_requires`, referencing the same commit, so the two installation paths cannot drift apart. Pinning a git commit rather than a released version is a trade: you get a tree that is known to match the notebooks, and in exchange you inherit the risk that the pinned commit is not reachable later or that it is incompatible with a newer torch. The status note's discipline, pinning on a specific date and then documenting what was verified, is the part that makes the approach defensible.

Tutorials, synthetic motion and the data contribution path

The released material has two halves. The first is the tools and Jupyter notebooks that demonstrate how to use AMASS to animate the SMPL+H body model, and the README points at the notebooks directory for the details. The second is, as promised in the supplementary material of the paper, code to produce synthetic motion capture using DFaust registrations, which is useful when you want motion data with a known ground truth or a controlled perturbation. The repository also carries a `support_data/` directory with a preview image of the bodies recovered from motion capture sequences. The contribution path is about data rather than code, and it is unusually hands-on. The research community needs more human motion data, and if you have interesting marker based motion capture data and are willing to share it for research purposes, the project will label and clean your motion capture, run the MoSh pipeline on it for you, add it to the AMASS dataset and cite you as the original owner of the marker data. The contact for that is the AMASS email address.

A research licence, not an open source licence

The licence section is the part to read before anything else, and it is not an open source grant. The software is under a copyright licence for non-commercial scientific research purposes, with the terms and conditions in the LICENSE file and a note to read it and any accompanying documentation before downloading or using the dataset and software. The wording is explicit that by downloading, cloning, installing or otherwise using the repository you acknowledge having read the terms, that you agree to be bound by them, and that if you do not agree you must not download or use it. It adds that any infringement automatically terminates your rights under the licence. The setup file header makes the same point from the other direction, noting that the Max Planck Society holds all proprietary rights, that you can only use the program if you have closed a licence agreement or obtained the right from someone authorised to grant it, and that any use without a valid licence is prohibited. Commercial use has a separate route through the licensing address given in the README, and questions go to the maintainer, whose contact details and the citation for the paper are provided there.

Editorial conclusion

Adopt this repository if you are doing research with AMASS data and need the body model plumbing, the split definitions and the synthetic motion generation code that accompany the paper. Do not adopt it as a maintained library, because the README says the project is not under active development, and do not expect the tutorials to have been run end to end against the licensed models. Before you start, read the status note dated 2026-09-17, since it tells you which calls were verified with a synthetic body model and which were not, and accept the licence terms, since they cover non-commercial scientific research only and point at a separate address for commercial licensing. The code lives under `src/`, the notebooks under `notebooks/`, the tests under `tests/`, and the last push was on 2026-09-17.

Frequently asked questions

Official sources

1. Issues
2. nghorbani/amass on GitHub
3. Project website
4. README
5. Releases