Profile
Back to NewsBack
GitHub Trending 3 min
Reader Mode
facebookresearch/MHR: Momentum Human Rig is an anatomically-inspired parametric full-body digital human model developed at Meta. It includes: A parametric body skeletal model; A realistic 3D mesh skinned to the skeleton with levels of detail;A body b

facebookresearch/MHR: Momentum Human Rig is an anatomically-inspired parametric full-body digital human model developed at Meta. It includes: A parametric body skeletal model; A realistic 3D mesh skinned to the skeleton with levels of detail;A body b

3 hours ago

MHR - Momentum Human Rig

A minimal Python package for the Momentum Human Rig - a parametric 3D human body model with identity, pose, and facial expression parameterization.

arXiv</a>

Overview

!MHR teaser

MHR (Momentum Human Rig) is a high-fidelity 3D human body model that provides:

  • Identity Parameterization: 45 shape parameters controlling body identity
  • Pose Parameterization: 204 model parameters for full-body articulation
  • Facial Expression: 72 expression parameters for detailed face animation
  • Multiple LOD Levels: 7 levels of detail (LOD 0-6) for different performance requirements
  • Non-linear Pose Correctives: Neural network-based pose-dependent deformations
  • PyTorch Integration: Differentiable inference and optimization on CPU or GPU
  • PyMomentum Integration: Compatible with fast CPU solver

Installation

Option 1. Using Pixi (Recommended)

Pixi is a conda-based package manager. This is the recommended installation method as 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. Using the TorchScript model

# Install MHR
pip install mhr

Download the torchscript model

mhr-download-assets --member assets/mhr_model.pt --output mhr_model.pt

Start using the torchscript model

New to TorchScript model? In short it's a Graph mode of pytorch models. More details here. You can take ./demo.py as a reference to start using the torchscript model.
  • Advantage: no codebase or model assets are required.
  • Disadvantage: Currently only support for LOD 1; limited access to model properties.

Option 3. Using pip (⚠️ Experimental)

Note: pip installation is experimental. Some dependencies (e.g., pymomentum) may not resolve correctly on all platforms. If you encounter issues, please use the recommended Pixi installation above.
# Install PyMomentum, which works with any recent PyTorch
pip install pymomentum-core

Install MHR

pip install mhr

Download and unzip the model assets

mhr-download-assets
Known issue on Linux: the PyPI builds of PyMomentum ship a private copy of libstdc++. Depending on which PyTorch build loads the system copy first, the two copies can mix, and then MHR.from_files crashes with a segmentation fault (#44). No PyMomentum release on PyPI fixes this yet. It happens with pymomentum-cpu, which requires PyTorch 2.8, and with the CPU-only PyTorch wheels from download.pytorch.org (seen on CentOS Stream 9); pymomentum-core with the default PyTorch from PyPI did not crash in our tests. If you hit the crash, use the Pixi environment or conda-forge pymomentum, or start Python with PyMomentum's copy preloaded:
>
> LD_PRELOAD=$(python -c "import glob, sysconfig; print(glob.glob(sysconfig.get_paths()['purelib'] + '/pymomentum_.libs/libstdc++.so*')[0])") python demo.py
>

Dependencies

  • Python >= 3.11
  • PyTorch
  • pymomentum >= 0.1.89 (CI tests 0.1.114)
  • trimesh >= 4.8.3 (for additional tools only: mhr-smpl conversion, LOD conversion and segmentation)

Quick Start

Run the Demo

python demo.py

This will generate a test MHR mesh and compare outputs with the TorchScript model.

The demo saves the mesh with trimesh. The Pixi environment includes it; with a pip install, run pip install "trimesh>=4.8.3,<5" first.

Visualization Demo

!Visualization Notebook

Interactive Jupyter notebook for MHR visualization. See tools/mhr_visualization/README.md.

SMPL/SMPL-X Conversion

Conversion between MHR and SMPL/SMPL-X. See tools/mhr_smpl_conversion/README.md.

glTF Export

Export MHR poses and animations to glTF (.glb) for Blender and other tools. See tools/mhr_export/README.md.

Basic Usage

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)

Computing gradients

Both the Python and TorchScript models support standard PyTorch autograd. Enable gradients only on the inputs you want to optimize before the forward pass, and keep gradient mode enabled; 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 calls in demo.py use torch.no_grad() because that script performs inference only.

Model Parameters

Identity Parameters (identity_coeffs)

  • Shape: [batch_size, 45]
  • Description: The first 20 control body shape identity, second 20 control head, and the last 5 for hands.
  • Typical Range: -3 to +3 (zero-mean, unit variance)

Model Parameters (model_parameters)

  • Shape: [batch_size, 204]
  • Description: Joint angles and scalings

Expression Parameters (face_expr_coeffs)

  • Shape: [batch_size, 72]
  • Description: Artist-sculpted, sparse semantic blendshape weights that follow FACS. These are not PCA components or a one-to-one list of FACS Action Units.
  • Typical Range: -1 to +1
  • Names and indices: See the facial expression mapping, or import FACE_EXPRESSION_NAMES from mhr.

Project Structure

MHR/
├── assets                              # Assets (downloaded and unzipped from release)
│   ├── compact_v6_1.model              # Model parameterization
│   ├── corrective_activation.npz       # Pose corrective MLP sparse activations
│   ├── corrective_blendshapes_lod?.npz # Pose corrective blendshapes
│   ├── lod?.fbx                        # Rig with identity and expression blendshapes
│   └── mhr_model.pt                    # Torchscript model
├── demo.py                             # Basic demo script
├── mhr                                 # Main package
│   ├── io.py                           # Asset loading utilities
│   ├── mhr.py                          # MHR model implementation
│   └── utils.py                        # Helper functions
├── pyproject.toml                      # Pixi project configuration
├── tests                               # Unit tests
└── tools                               # Additional tools
    ├── mhr_export                      # glTF export
    ├── mhr_visualization               # Jupyter visualization
    └── mhr_smpl_conversion             # Conversion between MHR and SMPL/SMPL-X

Testing

Run the test suite:

# Run all tests
pixi run pytest tests/

Run specific test

pixi run pytest tests/test_mhr.py

Inferring MHR parameters from images

If you want to do Human Motion Recovery with MHR, head to Sam3D.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Code of Conduct

Please read our CODE_OF_CONDUCT.md before contributing.

Citation

If you use MHR in your research, please cite:

@misc{MHR:2025,
      title={MHR: Momentum Human Rig},
      author={Aaron Ferguson and Ahmed A. A. Osman and Berta Bescos and Carsten Stoll and Chris Twigg and Christoph Lassner and David Otte and Eric Vignola and Fabian Prada and Federica Bogo and Igor Santesteban and Javier Romero and Jenna Zarate and Jeongseok Lee and Jinhyung Park and Jinlong Yang and John Doublestein and Kishore Venkateshan and Kris Kitani and Ladislav Kavan and Marco Dal Farra and Matthew Hu and Matthew Cioffi and Michael Fabris and Michael Ranieri and Mohammad Modarres and Petr Kadlecek and Rawal Khirodkar and Rinat Abdrashitov and Romain Prévost and Roman Rajbhandari and Ronald Mallet and Russell Pearsall and Sandy Kao and Sanjeev Kumar and Scott Parrish and Shoou-I Yu and Shunsuke Saito and Takaaki Shiratori and Te-Li Wang and Tony Tung and Yichen Xu and Yuan Dong and Yuhua Chen and Yuanlu Xu and Yuting Ye and Zhongshi Jiang},
      year={2025},
      eprint={2511.15586},
      archivePrefix={arXiv},
      primaryClass={cs.GR},
      url={https://arxiv.org/abs/2511.15586},
}

License

MHR is licensed under the Apache Software License 2.0, as found in the LICENSE file.

Chat with me