VPoser learns which human poses are possible

Why a prior over poses is needed

The description states the problem plainly. The articulated 3D pose of the human body is high-dimensional and complex, many applications make use of a prior distribution over valid human poses, and modelling that distribution is difficult. VPoser is a learning based variational human pose prior trained from a large dataset of human poses represented as SMPL bodies. The point of a prior is that it rules out the impossible, and in a body fitting problem the naive objective will happily find a rotation configuration that puts an elbow through a rib. The body prior can be used as an inverse kinematics solver for many tasks such as fitting a body model to images, and the README is explicit that this is the main contribution of the repository to SMPLify-X. The six listed features follow from that purpose, starting with a prior over SMPL pose parameters and ending with the ability to generate valid 3D human poses for data-dependent tasks.

Six properties, and why each one matters

The feature list is short and each entry carries weight. It defines a prior of SMPL pose parameters, so the model is expressed in the same parameterisation as the body model it constrains, which means the prior and the body can be composed without a conversion step. It is end-to-end differentiable, which is the property that decides whether it can be used inside a fitting loop at all, since the whole point of an inverse kinematics solver is that the gradient has to flow back to the image or the keypoint positions. It provides a way to penalize impossible poses while admitting valid ones, which is the difference between a prior and a hard constraint. It effectively models correlations among the joints of the body, so a prior that treated each joint independently would be almost useless, since human limbs move together. And it introduces an efficient, low-dimensional representation for human pose, which is what makes sampling and optimisation over poses tractable.

A variational autoencoder over pose

The training section explains the mechanism. VPoser is trained as a variational autoencoder that learns a latent representation of human pose and regularises the distribution of the latent code to be a normal distribution. That is a standard variational setup, and the reason it fits this problem is that the normal prior on the latent code is what makes the latent space smooth and interpolable, which the tutorial demonstrates with a latent interpolation notebook showing novel poses sampled along a path through the space. The training data comes from the AMASS dataset, which holds the SMPL pose parameters of various publicly available human motion capture datasets, so the prior is fitted to real motion rather than to synthetic rotations. The documentation also asks that anyone training their own VPoser on AMASS follows the dataset's own citation guideline, which is the polite form of saying the dataset has terms of use that extend to models trained on it.

Installing with uv, and the Python version floor

The installation instructions have been modernised around uv, and the requirements section is specific. Python 3.11 to 3.12 is recommended, with a note to avoid 3.13 and 3.14 for now due to limited third-party wheels, and uv has to be installed. The core install is one command:

uv sync

Development tools, meaning the tests and the linters, come from an extra:

uv sync --extra dev

and there are optional extras for Lightning and for visualisation. The quick check confirms the package imports:

uv run python -c "import human_body_prior; print('ok')"

The tests run with pytest through the same environment, and there is a note about PyTorch CUDA builds, since the default dependency is the CPU wheel and you have to install the right one for your CUDA setup. If your global Python is 3.13 or 3.14, the instructions suggest creating the environment with a supported version instead, either with uv venv --python 3.12 followed by a sync, or by pinning 3.12 with uv python pin before syncing.

The weights are not in the repository

Two downloads are needed and neither is in the repository, which is the first practical thing to sort out. The pretrained VPoser checkpoints are downloaded from the SMPL-X project page, and the tutorials include guidance on the expected folder layout and on pointing the code at the checkpoint. The SMPL-X body models, for example the model.npz file, come from the SMPL-X website and require registration, and you provide the path through the bm_fname argument when you construct the BodyModel. The tutorials directory holds the concrete instructions, with a notebook on the VPoser body poZ space for the SMPL body model family, a notebook on sampling novel body poses, and two IK example scripts, one for 3D joints and one for mocap markers. The repository itself is small, with the human_body_prior/ package, the tutorials, the tests, the support data, a pyproject.toml and a uv.lock.

The inverse kinematics engine

The advanced section is where the prior earns its keep. Given the position of some key points, you can find the necessary body joint rotation configurations through inverse kinematics, and the keypoints can be 3D, either joint locations or 3D mocap markers on the body surface, or 2D as in SMPLify-X. The engine has a flexible keypoint definition interface, demonstrated in the tutorials, and you can define keypoints on the SMPL body, either joints or any locations relative to the body surface, then fit the body model parameters to them while using VPoser's parameterisation. The supported features are listed as a list, and they are the reasons to use this rather than writing the loop yourself. It is batch enabled, so many fits run at once. The keypoint definition is flexible. LBFGS with a wolfe line search and the ADAM optimizer are already enabled, so you are not choosing a single optimiser for everything. There is no need to initialise the body, because it always starts from zero. And the body pose, the translation and the global orientation are optimised jointly and iteratively, rather than in a sequence of separate solves.

Licence, citation and the package metadata

The licensing is the part to read before anything else, and it is not a standard open source licence. The software is covered by a copyright licence for non-commercial scientific research purposes, and the terms in the LICENSE file and its accompanying documentation have to be read before downloading or using the model and the software, including the 3D meshes, blend weights, blend shapes, textures, scripts and animations, with the download itself constituting acceptance of the terms. Commercial licensing is handled separately, through a licensing contact at the Max Planck Institute for Intelligent Systems. The citation request covers direct or indirect use of the code and points at the SMPL-X paper, Expressive Body Capture: 3D Hands, Face, and Body from a Single Image, and the AMASS citation guideline applies if you train your own model on that dataset. The code was developed by Nima Ghorbani while at Perceiving Systems, with a general contact address for questions. The package metadata shows the build is hatchling, the runtime dependencies are numpy, torch, omegaconf, loguru, tqdm, PyYAML and transforms3d, with optional extras for Lightning, trimesh, a mesh library and the dev tools, and the ruff configuration sets a line length of 100 with the pycodestyle, pyflakes and bugbear rule sets. The package version in the file is 2.3.0 while the tagged release is 1.0.0 from 2025-12-17, the default branch is staging, and the last push was on 2026-09-24.

Editorial conclusion

VPoser fits a research group that fits SMPL or SMPL-X bodies to images or keypoints and needs a pose space that rejects anatomically impossible solutions while staying differentiable, because a rejection sampler would break the gradient path that the rest of the fitting pipeline depends on. It does not fit a commercial product, since the licence covers non-commercial scientific research only and commercial licensing goes through a separate contact. It does not fit a team that cannot obtain the SMPL-X model files, which require registration and are not redistributed here. Before you start, read the licence file, download the pretrained VPoser checkpoint and the SMPL-X models as the documentation describes, and pin the Python version, since the project requires 3.11 or 3.12 and warns against 3.13 and 3.14 for now because of third-party wheel coverage.

Frequently asked questions

Official sources

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