# facebookresearch/mhr architecture

> Architecture diagram of the GitHub repository facebookresearch/mhr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebookresearch/mhr
- Repository: https://github.com/facebookresearch/mhr

## Overview

MHR is a parametric human-rig package: callers provide identity, pose, and expression parameters and receive mesh vertices and skeleton state. Supporting branches convert between MHR and SMPL-family models, provide mesh utilities, and offer a local web viewer. The model-loading and inference path is shown in sampled source; conversion and viewer internals are only partially sampled, so uncertain connections are omitted or marked unverified.

Main entry points: [`tools/mhr_smpl_conversion/conversion.py`](https://github.com/facebookresearch/mhr/blob/main/tools/mhr_smpl_conversion/conversion.py) (SMPL conversion), [`mhr/mhr.py`](https://github.com/facebookresearch/mhr/blob/main/mhr/mhr.py) (MHR inference), [`web-viewer/server.py`](https://github.com/facebookresearch/mhr/blob/main/web-viewer/server.py) (Viewer backend), [`mhr/io.py`](https://github.com/facebookresearch/mhr/blob/main/mhr/io.py) (Asset loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["MHR model"]
  node_assets[("Model assets")]
  node_asset_loader["Asset loading<br/>[io.py]"]
  node_mhr_model["MHR inference<br/>[mhr.py]"]
  node_pose_correctives["Pose correctives<br/>[mhr.py]"]
  node_sparse_ops["Sparse operations<br/>[utils.py]"]
  node_expression_names["Expression mapping<br/>[face_expression.py]"]
  node_download["Asset download<br/>[download_assets.py]"]
end

subgraph group_conversion["Model conversion"]
  node_conversion_api["SMPL conversion<br/>[conversion.py]"]
  node_momentum_fit["PyMomentum fitting"]
  node_torch_fit["PyTorch fitting<br/>[pytorch_fitting.py]"]
  node_conversion_assets[("Conversion mappings<br/>[file_assets.py]")]
end

subgraph group_tools["Mesh tools"]
  node_lod_conversion["LOD conversion"]
  node_segmentation["Segmentation<br/>[example.py]"]
  node_visualization["Visualization notebook"]
end

subgraph group_viewer["Web viewer"]
  node_viewer_server["Viewer backend<br/>[server.py]"]
  node_viewer_ui["Three.js interface<br/>[app.js]"]
  node_exporters["Mesh exporters<br/>[exporters.py]"]
end

node_caller(("Python caller"))
node_viewer_user(("Viewer user"))

node_caller -->|"provides parameters"| node_mhr_model
node_asset_loader -->|"loads model data"| node_assets
node_mhr_model -->|"loads assets"| node_asset_loader
node_mhr_model -->|"applies correctives"| node_pose_correctives
node_pose_correctives -->|"uses sparse layer"| node_sparse_ops
node_caller -->|"downloads assets"| node_download
node_conversion_api -->|"uses MHR model"| node_mhr_model
node_conversion_api -.->|"selects fitting"| node_momentum_fit
node_conversion_api -.->|"selects fitting"| node_torch_fit
node_conversion_api -.->|"uses mappings"| node_conversion_assets
node_caller -->|"requests conversion"| node_conversion_api
node_caller -->|"converts LOD"| node_lod_conversion
node_caller -->|"creates segments"| node_segmentation
node_segmentation -->|"loads model"| node_mhr_model
node_caller -->|"opens visualization"| node_visualization
node_viewer_user -.->|"uses viewer"| node_viewer_server
node_viewer_ui -.->|"sends controls"| node_viewer_server
node_viewer_server -->|"uses exporters"| node_exporters

click node_asset_loader "https://github.com/facebookresearch/mhr/blob/main/mhr/io.py"
click node_mhr_model "https://github.com/facebookresearch/mhr/blob/main/mhr/mhr.py"
click node_pose_correctives "https://github.com/facebookresearch/mhr/blob/main/mhr/mhr.py"
click node_sparse_ops "https://github.com/facebookresearch/mhr/blob/main/mhr/utils.py"
click node_expression_names "https://github.com/facebookresearch/mhr/blob/main/mhr/face_expression.py"
click node_download "https://github.com/facebookresearch/mhr/blob/main/mhr/download_assets.py"
click node_conversion_api "https://github.com/facebookresearch/mhr/blob/main/tools/mhr_smpl_conversion/conversion.py"
click node_momentum_fit "https://github.com/facebookresearch/mhr/blob/main/tools/mhr_smpl_conversion/pymomentum_fitting.py"
click node_torch_fit "https://github.com/facebookresearch/mhr/blob/main/tools/mhr_smpl_conversion/pytorch_fitting.py"
click node_conversion_assets "https://github.com/facebookresearch/mhr/blob/main/tools/mhr_smpl_conversion/file_assets.py"
click node_lod_conversion "https://github.com/facebookresearch/mhr/tree/main/tools/mhr_LOD_conversion"
click node_segmentation "https://github.com/facebookresearch/mhr/blob/main/tools/mhr_create_segmentation/example.py"
click node_visualization "https://github.com/facebookresearch/mhr/tree/main/tools/mhr_visualization"
click node_viewer_server "https://github.com/facebookresearch/mhr/blob/main/web-viewer/server.py"
click node_viewer_ui "https://github.com/facebookresearch/mhr/blob/main/web-viewer/static/app.js"
click node_exporters "https://github.com/facebookresearch/mhr/blob/main/web-viewer/exporters.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_assets,node_asset_loader,node_mhr_model,node_pose_correctives,node_sparse_ops,node_expression_names,node_download,node_viewer_user toneBlue
class node_conversion_api,node_momentum_fit,node_torch_fit,node_conversion_assets toneAmber
class node_lod_conversion,node_segmentation,node_visualization toneMint
class node_viewer_server,node_viewer_ui,node_exporters toneRose
class node_caller toneIndigo
```

## Components

### MHR model

- **Model assets**
- [Asset loading](https://github.com/facebookresearch/mhr/blob/main/mhr/io.py): `mhr/io.py`
- [MHR inference](https://github.com/facebookresearch/mhr/blob/main/mhr/mhr.py): `mhr/mhr.py`
- [Pose correctives](https://github.com/facebookresearch/mhr/blob/main/mhr/mhr.py): `mhr/mhr.py`
- [Sparse operations](https://github.com/facebookresearch/mhr/blob/main/mhr/utils.py): `mhr/utils.py`
- [Expression mapping](https://github.com/facebookresearch/mhr/blob/main/mhr/face_expression.py): `mhr/face_expression.py`
- [Asset download](https://github.com/facebookresearch/mhr/blob/main/mhr/download_assets.py): `mhr/download_assets.py`

### Model conversion

- [SMPL conversion](https://github.com/facebookresearch/mhr/blob/main/tools/mhr_smpl_conversion/conversion.py): `tools/mhr_smpl_conversion/conversion.py`
- [PyMomentum fitting](https://github.com/facebookresearch/mhr/blob/main/tools/mhr_smpl_conversion/pymomentum_fitting.py): `tools/mhr_smpl_conversion/pymomentum_fitting.py`
- [PyTorch fitting](https://github.com/facebookresearch/mhr/blob/main/tools/mhr_smpl_conversion/pytorch_fitting.py): `tools/mhr_smpl_conversion/pytorch_fitting.py`
- [Conversion mappings](https://github.com/facebookresearch/mhr/blob/main/tools/mhr_smpl_conversion/file_assets.py): `tools/mhr_smpl_conversion/file_assets.py`

### Mesh tools

- [LOD conversion](https://github.com/facebookresearch/mhr/tree/main/tools/mhr_LOD_conversion): `tools/mhr_LOD_conversion`
- [Segmentation](https://github.com/facebookresearch/mhr/blob/main/tools/mhr_create_segmentation/example.py): `tools/mhr_create_segmentation/example.py`
- [Visualization notebook](https://github.com/facebookresearch/mhr/tree/main/tools/mhr_visualization): `tools/mhr_visualization`

### Web viewer

- [Viewer backend](https://github.com/facebookresearch/mhr/blob/main/web-viewer/server.py): `web-viewer/server.py`
- [Three.js interface](https://github.com/facebookresearch/mhr/blob/main/web-viewer/static/app.js): `web-viewer/static/app.js`
- [Mesh exporters](https://github.com/facebookresearch/mhr/blob/main/web-viewer/exporters.py): `web-viewer/exporters.py`

### Other components

- **Python caller**
- **Viewer user**

## Connections

- Python caller → MHR inference: provides parameters (evidence: `README.md`)
- Asset loading → Model assets: loads model data (evidence: `mhr/io.py`)
- MHR inference → Asset loading: loads assets (evidence: `mhr/mhr.py`)
- MHR inference → Pose correctives: applies correctives (evidence: `mhr/mhr.py`)
- Pose correctives → Sparse operations: uses sparse layer (evidence: `mhr/mhr.py`)
- Python caller → Asset download: downloads assets (evidence: `README.md`)
- SMPL conversion → MHR inference: uses MHR model (evidence: `tools/mhr_smpl_conversion/conversion.py`)
- SMPL conversion → PyMomentum fitting: selects fitting (evidence: `tools/mhr_smpl_conversion/conversion.py`)
- SMPL conversion → PyTorch fitting: selects fitting (evidence: `tools/mhr_smpl_conversion/conversion.py`)
- SMPL conversion → Conversion mappings: uses mappings
- Python caller → SMPL conversion: requests conversion (evidence: `README.md`)
- Python caller → LOD conversion: converts LOD (evidence: `README.md`)
- Python caller → Segmentation: creates segments (evidence: `tools/mhr_create_segmentation/example.py`)
- Segmentation → MHR inference: loads model (evidence: `tools/mhr_create_segmentation/example.py`)
- Python caller → Visualization notebook: opens visualization (evidence: `README.md`)
- Viewer user → Viewer backend: uses viewer
- Three.js interface → Viewer backend: sends controls
- Viewer backend → Mesh exporters: uses exporters (evidence: `web-viewer/server.py`)
