MHR: Meta's parametric human body model as a PyTorch package

What the Momentum Human Rig actually is

MHR is the Momentum Human Rig, described as an anatomically-inspired parametric full-body digital human model developed at Meta, and the README calls it a minimal Python package for a parametric 3D human body model with identity, pose and facial expression parameterisation.

The composition of the rig is what makes it useful, and the repository description lists the pieces. There is a parametric body skeletal model, a realistic 3D mesh skinned to that skeleton with levels of detail, a body blendshape and pose corrective model, and a facial blendshape model. The description also says the design is friendly for both the computer graphics and computer vision communities, which is a claim about the interface rather than the output.

The parameter counts are the headline numbers. Identity uses 45 shape parameters controlling body identity. Pose uses 204 model parameters for full-body articulation. Facial expression uses 72 expression parameters. There are seven levels of detail, LOD 0 through LOD 6, for different performance requirements.

The correction model is the technically interesting part. The pose correctives are non-linear and neural network based, described as pose-dependent deformations, and the asset list shows the machinery: a corrective_activation.npz file holding sparse activations for a pose corrective MLP, plus corrective blendshape files per LOD. A linear blend shape model cannot represent the way a shoulder deforms when a hand rotates past a certain angle, and that is the class of artefact these correctives exist to remove.

The paper is on arXiv at 2511.15586, and the licence is Apache-2.0.

Three installation routes, and why Pixi comes first

The README offers three options and puts a warning on the third one.

Option 1, the recommended path, uses Pixi, which is a conda-based package manager, and the reason given is that it provides the most reliable environment setup:

# Clone the repository
git clone [email protected]:facebookresearch/MHR.git
cd MHR

# Install dependencies with Pixi
pixi install

# Download and unzip the model assets
pixi run download-assets

# Activate the environment
pixi shell

Option 2 uses the TorchScript model, which requires no model assets at all:

# Install MHR
pip install mhr

# Download the torchscript model
mhr-download-assets --member assets/mhr_model.pt --output mhr_model.pt

The README is candid about the trade. The advantage is that no codebase or model assets are required beyond that single file. The disadvantage is that this route currently supports LOD 1 only, and gives limited access to model properties.

Option 3 is plain pip, and it carries an explicit experimental label, because some dependencies such as pymomentum may not resolve correctly on all platforms, with the advice to fall back to Pixi if you hit problems:

# Install PyMomentum (CPU or GPU)
pip install pymomentum-cpu  # or pymomentum-gpu

# Install MHR
pip install mhr

# Download and unzip the model assets
mhr-download-assets

The Pixi configuration lives in pyproject.toml under a pixi.workspace section with conda-forge as the channel and two platforms listed, osx-arm64 and linux-64. That platform list is the concrete constraint behind the warning: there is no Linux aarch64 or Windows environment declared, which is why a plain pip install is presented as the escape hatch rather than the default.

Loading the model and driving it with parameters

The basic usage is short enough to read in one go:

import torch
from mhr.mhr import MHR

# Load MHR model (LOD 1, on CPU)
mhr_model = MHR.from_files(device=torch.device("cpu"), lod=1)

# Define parameters
batch_size = 2
identity_coeffs = 0.8 * torch.randn(batch_size, 45)      # Identity
model_parameters = 0.2 * (torch.rand(batch_size, 204) - 0.5)  # Pose
face_expr_coeffs = 0.3 * torch.randn(batch_size, 72)     # Facial expression

# Generate mesh vertices and skeleton information (joint orientation and positions).
vertices, skeleton_state = mhr_model(identity_coeffs, model_parameters, face_expr_coeffs)

Three things stand out. The call returns both the mesh vertices and the skeleton state, which carries joint orientations and positions, so you do not need a separate forward kinematics implementation to place the result in a scene. The parameters are plain tensors of the documented shapes, so any tensor code you already have can drive the model. And the third argument is the expression coefficients, which are per-face parameters rather than something baked into the body.

The model is loaded from files with an explicit device and an explicit LOD, so the same code path serves a CPU preview and a GPU render, and the level of detail is a parameter rather than a property of the install.

The dependency set is short: Python 3.11 or newer, PyTorch, pymomentum at 0.1.90 or newer, and trimesh at 4.8.3 or newer, where trimesh is called out as being for the additional tools only, namely the SMPL conversion, LOD conversion and segmentation. The PyMomentum integration is advertised as a fast CPU solver, and it is the dependency most likely to decide whether an install succeeds.

The parameter semantics, and the part that is not PCA

The README documents what each parameter block means, and the details matter more than the counts.

Identity parameters have shape [batch_size, 45] and a typical range of -3 to +3, described as zero-mean with unit variance. The composition is stated plainly: the first 20 control body shape identity, the second 20 control head, and the last 5 for hands. So the identity vector is not a single undifferentiated shape space, it is three blocks with different meanings, and a pipeline that wants to hold head identity fixed while varying body shape has to slice the vector accordingly.

The 204 pose parameters are described as joint angles and scalings. Scalings alongside angles means the model can vary limb length, which is what lets the identity parameters cover proportions and the pose parameters cover articulation without the two fighting.

The expression parameters are the ones to read carefully. Their shape is [batch_size, 72] with a typical range of -1 to +1, and they are described as artist-sculpted, sparse semantic blendshape weights that follow FACS. The README adds the crucial caveat: these are not PCA components and not a one-to-one list of FACS Action Units. If you are porting an expression rig from an existing facial animation pipeline, the indices will not line up with anything you already have, which is why the repository also points at a facial expression mapping document and at FACE_EXPRESSION_NAMES importable from the mhr package.

That semantic naming is what makes the model usable by the computer vision side of the community. A parameter named for a recognised expression category can be regressed from an image; an opaque PCA coefficient cannot.

Differentiability: the reason this is a PyTorch package and not a mesh file

Both the Python and the TorchScript models support standard PyTorch autograd, and the README explains how to use it.

Enable gradients only on the inputs you intend to optimise, keep gradient mode enabled, and do not wrap the call in torch.no_grad() or torch.inference_mode():

identity_coeffs.requires_grad_()
model_parameters.requires_grad_()
face_expr_coeffs.requires_grad_()

vertices, skeleton_state = mhr_model(
    identity_coeffs,
    model_parameters,
    face_expr_coeffs,
)
loss = vertices.square().mean()
loss.backward()

The README also notes that the calls in demo.py use torch.no_grad() because that script does inference only, which is a useful sign about how the demo and the optimisation path are separated.

This is the feature that changes what the model is for. A rig that produces differentiable vertices can be fitted to an image by backpropagating a loss on the projected silhouette or the rendered landmarks, optimising the identity, pose and expression parameters directly. That turns a human body model from an asset you pose into a parameteriser you solve for. It is also why the README points at Sam3D for Human Motion Recovery with MHR, since recovering motion from images is the natural downstream task.

The neural network pose correctives are part of the same story. Because the corrections are a learned function of pose rather than a table lookup, they remain differentiable, which a linear blend shape correction would also be, but a small MLP can represent deformations that a fixed blend shape basis cannot at all.

What ships in the repository: assets, tools and the SMPL bridge

The project structure in the README shows what you get after downloading the assets.

The assets directory holds the model parameterisation in a compact_v6_1.model file, the corrective_activation.npz sparse activations for the pose corrective MLP, per-LOD corrective blendshape files, an FBX rig per LOD with identity and expression blendshapes, and the TorchScript model as mhr_model.pt. The mhr package itself is three files: io.py for asset loading, mhr.py for the model implementation and utils.py for helpers.

Two tools directories sit alongside. mhr_visualization holds a Jupyter notebook for visualising the model, and the README links an interactive Colab version of it plus a tools/mhr_visualization/README.md. mhr_smpl_conversion handles conversion between MHR and SMPL and SMPL-X, with its own README. The top level also has a web-viewer directory and a docs directory.

The SMPL bridge is worth a note. SMPL is the dominant parametric body model in the research world, so a conversion path lets you compare MHR against an existing pipeline or reuse existing SMPL assets and tooling. The README does not describe the conversion quality, so it is worth validating numerically on your own data before you rely on it.

A demo script sits at the root, and the README says running it generates a test MHR mesh and compares outputs with the TorchScript model, which is a good sanity check to run first because it tells you whether your Python implementation and your downloaded asset agree.

Limits: experimental packaging, one platform list, one release tag

Several limits are visible in what the README documents.

The packaging is the biggest one. The pip route is labelled experimental because the pymomentum dependency may not resolve correctly on all platforms, and the recommended Pixi environment declares only osx-arm64 and linux-64. On a Windows machine, an aarch64 Linux box, or a machine where the CPU lacks the instructions pymomentum-cpu expects, the install is a research project rather than a step. The pyproject.toml does use standard PEP 621 metadata with hatchling and hatch-vcs for version derivation, so the package is a normal wheel on PyPI, but the dependency that it depends on is the fragile part.

The second is that the TorchScript route, the one that avoids the whole asset download, only reaches LOD 1 and gives limited access to model properties. So the convenient path and the capable path are not the same path, and the documentation is clear that you are choosing between them.

The third is release history. There is a single tagged release, v1.0.1 from 2025-11-19, while the last push to the repository was on 2026-10-19. A version number of 1.0.1 with commits from the following year suggests the project is stable in API but not frozen, and the versioning scheme in pyproject.toml is a post-release scheme derived from VCS tags. Anyone pinning should pin a commit or a wheel and expect to test before moving.

Finally, the artefacts are large. The asset download pulls a model parameterisation, sparse MLP activations, per-LOD blendshapes and per-LOD FBX rigs, and the README gives no size for any of them, which is an awkward gap when you are planning a container image.

MHR against SMPL and against a production game engine rig

Two comparisons clarify the choice.

The first is against SMPL and SMPL-X. SMPL is the reference model for this kind of work, with a large body of literature, tooling and trained regressors already built on it. MHR differs in what it optimises for. The README describes an anatomically inspired rig with a neural network pose corrective model and a sparse semantic expression basis following FACS, and the seven LOD levels are a production concern that research-oriented models usually skip. If you need to compare against published SMPL results, the mhr_smpl_conversion tool is the bridge. If you need to drive a rig in a game engine with its own animation pipeline, a model with LODs and an FBX export is closer to what you need than a research model is.

The second is against a hand-built character rig in a production engine. A rigged character in an engine comes with authored blend shapes, hand-tuned corrective shapes and a set of facial blendshapes a director can pose. MHR cannot be used as a drop-in replacement for that, because its expression space is a fixed 72-dimensional basis with names, not something an artist sculpted for your production. What MHR offers instead is parametric access, which means you can solve for a body and a face from an image and then transfer the result, or drive a large population of varied bodies without authoring one rig per person.

The honest summary is that MHR sits between a research model and a production asset. It has the differentiability and the semantic parameterisation of the first, and the LODs and the export formats of the second, and it is not clear from the README which of the two it is being optimised for.

Editorial conclusion

Adopt MHR when you need an anatomically-informed full-body model with separate identity, pose and expression parameters, differentiable output for optimisation, or a conversion path to SMPL and SMPL-X for comparison. Do not adopt it if you need the full set of levels of detail via the TorchScript route alone, since the README states that route currently supports LOD 1 only, and treat the pip install as experimental. Verify first that your Python is 3.11 or newer, that the PyMomentum version resolves on your platform, and that the demo run reproduces the TorchScript output before you build on the mesh output.

Frequently asked questions

Official sources

1. facebookresearch/MHR on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases