Skip to content

Commit ee8fa1d

Browse files
libicoccoJavier Romero
andauthored
Added arxiv link and small fixes to README (#14)
* Added arxiv id * Changed pip order to make it the first one mentioned * Moved the visualization closer to the demo to encourage its use * Updated project tree description * add arxiv badge * fix arxiv badge * fix arxiv badge * fixed bibtex * added teaser image * added a visualization notebook image * adjusted bibtex --------- Co-authored-by: Javier Romero <javierromero1@fb.com>
1 parent 05abf70 commit ee8fa1d

File tree

3 files changed

+50
-44
lines changed

3 files changed

+50
-44
lines changed

README.md

Lines changed: 50 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,12 @@
22

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

5+
[![arXiv](https://img.shields.io/badge/arXiv-2511.15586-b31b1b.svg?style=flat-square)](https://arxiv.org/abs/2511.15586)
6+
57
## Overview
68

9+
![MHR teaser](images/teaser.jpg?raw=true)
10+
711
MHR (Momentum Human Rig) is a high-fidelity 3D human body model that provides:
812

913
- **Identity Parameterization**: 45 shape parameters controlling body identity
@@ -16,7 +20,21 @@ MHR (Momentum Human Rig) is a high-fidelity 3D human body model that provides:
1620

1721
## Installation
1822

19-
### Option 1. Using the torchscript model (Recommended)
23+
### Option 1. Using pip
24+
25+
```bash
26+
# Install PyMomentum (CPU or GPU)
27+
pip install pymomentum-cpu # or pymomentum-gpu
28+
29+
# Install MHR
30+
pip install mhr
31+
32+
# Download and unzip the model assets
33+
curl -OL https://github.com/facebookresearch/MHR/releases/download/v1.0.0/assets.zip
34+
unzip assets.zip
35+
```
36+
37+
### Option 2. Using the torchscript model
2038

2139
```bash
2240
# Download the torchscript model
@@ -32,7 +50,7 @@ New to TorchScript model? In short it's a Graph mode of pytorch models. More det
3250
- Advantage: no codebase or model assets are required.
3351
- Disadvantage: Currently only support for LOD 1; limited access to model properties.
3452

35-
### Option 2. Using Pixi (Recommended)
53+
### Option 3. Using Pixi
3654

3755
```bash
3856
# Clone the repository
@@ -51,20 +69,6 @@ pixi shell
5169
```
5270

5371

54-
### Option 3. Using pip
55-
56-
```bash
57-
# Install PyMomentum (CPU or GPU)
58-
pip install pymomentum-cpu # or pymomentum-gpu
59-
60-
# Install MHR
61-
pip install mhr
62-
63-
# Download and unzip the model assets
64-
curl -OL https://github.com/facebookresearch/MHR/releases/download/v1.0.0/assets.zip
65-
unzip assets.zip
66-
```
67-
6872

6973
### Dependencies
7074

@@ -83,6 +87,13 @@ python demo.py
8387

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

90+
### Visualization Demo
91+
92+
![Visualization Notebook](images/visualization_notebook.png?raw=true)
93+
94+
Interactive Jupyter notebook for MHR visualization. See [`tools/mhr_visualization/README.md`](tools/mhr_visualization/README.md).
95+
96+
8697
### Basic Usage
8798

8899
```python
@@ -118,32 +129,25 @@ vertices, skeleton_state = mhr_model(identity_coeffs, model_parameters, face_exp
118129
- **Description**: Facial expression blendshape weights
119130
- **Typical Range**: -1 to +1
120131

121-
## Tools
122-
123-
### Visualization
124-
125-
Interactive Jupyter notebook for MHR visualization. See [`tools/mhr_visualization/README.md`](tools/mhr_visualization/README.md).
126-
127-
128132
## Project Structure
129133

130134
```
131135
MHR/
132-
├── assets/ # Model assets
133-
├── rig_lod*.fbx # Rig files for each LOD
134-
├── corrective_blendshapes_lod*.npz # Blendshapes
135-
├── corrective_activation.npz # None-linear pose correctives
136-
── model_definition.model # Model parameterization
137-
── mhr/ # Main package
138-
├── __init__.py
139-
├── mhr.py # MHR model implementation
140-
├── io.py # Asset loading utilities
141-
── utils.py # Helper functions
142-
── tools/ # Additional tools
143-
├── mhr_visualization/ # Jupyter visualization
144-
├── tests/ # Unit tests
145-
── demo.py # Basic demo script
146-
└── pyproject.toml # Project configuration
136+
├── assets # Assets (downloaded and unzipped from release)
137+
   ├── compact_v6_1.model # Model parameterization
138+
   ├── corrective_activation.npz # Pose corrective MLP sparse activations
139+
   ├── corrective_blendshapes_lod?.npz # Pose corrective blendshapes
140+
   ├── lod?.fbx # Rig with identity and expression blendshapes
141+
│   └── mhr_model.pt # Torchscript model
142+
├── demo.py # Basic demo script
143+
├── mhr # Main package
144+
   ├── io.py # Asset loading utilities
145+
   ├── mhr.py # MHR model implementation
146+
│   └── utils.py # Helper functions
147+
├── pyproject.toml # Pixi project configuration
148+
├── tests # Unit tests
149+
── tools # Additional tools
150+
└── mhr_visualization # Jupyter visualization
147151
```
148152

149153
## Testing
@@ -175,12 +179,14 @@ Please read our [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) before contributing.
175179
If you use MHR in your research, please cite:
176180

177181
```bibtex
178-
@inproceedings{MHR:2025,
179-
author = {Ferguson, Aaron and Osman, Ahmed A. A. and Bescos, Berta and Stoll, Carsten and Twigg, Chris and Lassner, Christoph and Otte, David and Vignola, Eric and Bogo, Federica and Santesteban, Igor and Romero, Javier and Zarate, Jenna and Lee, Jeongseok and Park, Jinhyung and Yang, Jinlong and Doublestein, John and Venkateshan, Kishore and Kitani, Kris and Kavan, Ladislav and Dal Farra, Marco and Hu, Matthew and Cioffi, Matthew and Fabris, Michael and Ranieri, Michael and Modarres, Mohammad and Kadlecek, Petr and Khirodkar, Rawal and Abdrashitov, Rinat and Prévost, Romain and Rajbhandari, Roman and Mallet, Ronald and Pearsall, Russel and Kao, Sandy and Kumar, Sanjeev and Parrish, Scott and Saito, Shunsuke and Wang, Te-Li and Tung, Tony and Dong, Yuan and Chen, Yuhua and Xu, Yuanlu and Ye, Yuting and Jiang, Zhongshi},
180-
title = {MHR: Momentum Human Rig},
181-
booktitle = {Tech Report},
182-
year = {2025},
183-
url = {https://arxiv.org/abs/your-arxiv-id}
182+
@misc{MHR:2025,
183+
title={MHR: Momentum Human Rig},
184+
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 Russel 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},
185+
year={2025},
186+
eprint={2511.15586},
187+
archivePrefix={arXiv},
188+
primaryClass={cs.GR},
189+
url={https://arxiv.org/abs/2511.15586},
184190
}
185191
```
186192

images/teaser.jpg

221 KB
Loading

images/visualization_notebook.png

780 KB
Loading

0 commit comments

Comments
 (0)