# InstantHMR
InstantHMR, by Naturalpad and LAAS-CNRS, is a real-time human mesh recovery model. For each person box it returns MHR body pose and identity parameters, 70 keypoints in 2D and 3D, the camera translation and an 18,439-vertex mesh. LibreYOLO ports it natively in PyTorch and finds the people with RF-DETR.
Tasks: Body mesh. Install: pip install libreyolo.
Verified against LibreYOLO v1.8.0.

## Install

InstantHMR needs no optional extra. The default person detector,
`LibreRFDETRm.pt`, needs the RF-DETR extra.

```bash
pip install "libreyolo[rfdetr]"
```

## Predict

Weights download from the LibreYOLO Hugging Face mirrors on first use, after
a licence notice.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreInstantHMRm-mesh.pt")   # people found with LibreRFDETRm.pt
result = model("people.jpg")

meshes = result.meshes            # one row per box in result.boxes
print(meshes.body_model)          # "mhr"
print(meshes.vertices.shape)      # (people, 18439, 3) metres, camera frame
print(meshes.joints2d.shape)      # (people, 70, 2) pixels
```

**Your own boxes**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreInstantHMRm-mesh-commercial.pt")
boxes = [[40, 20, 260, 600]]      # x1, y1, x2, y2 per person
result = model("people.jpg", person_boxes=boxes)
```

People are found by an RF-DETR detector (`LibreRFDETRm.pt` by default).
Pass `person_boxes=` to use your own boxes, or `person_detector=` to swap the
detector. `result.meshes` rows line up with `result.boxes`. Everything is in
the camera frame of the original image: `transl` is in metres, `vertices` and
`joints3d` are metric and include `transl`, and `joints2d` is in pixels on the
original image. `global_orient`, `body_pose` and `betas` hold the MHR
parameters; MHR rotations are Euler angles in radians. See the
[body mesh](/docs/tasks/body-mesh) task page for the full payload.

## Variants

Four sizes, `n`, `t`, `s` and `m`, all at a 288 px person crop, plus
`LibreInstantHMRm-mesh-commercial.pt`, an `m` trained only on commercially
usable images. Upstream publishes ONNX only; LibreYOLO rebuilds PyTorch
checkpoints that match the upstream ONNX graphs within 8e-5 for all five
releases.

## Train

`train()` fine-tunes a pretrained checkpoint on a YOLO-pose dataset with
COCO-17 person keypoints, using 2D keypoint, reprojection and frozen-prior
losses. Training from scratch and `resume` are not supported. `val()` raises:
the usual body-mesh benchmarks (3DPW, EMDB) are research-license only, so
none is bundled; the MPJPE, PA-MPJPE and PVE metrics are in
`libreyolo.validation.mesh_metrics` for a dataset you hold.

**Python**

```python
from libreyolo import LibreYOLO

# Fine-tune a pretrained checkpoint on a YOLO-pose COCO-17 dataset.
model = LibreYOLO("LibreInstantHMRs-mesh.pt")
model.train(data="my-pose-dataset.yaml", epochs=20)
```

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | Axelera | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Body mesh | yes |  |  |  |  |  |  |  |  |  |  |  |  |

A "yes" means the export is supported. An empty cell means the exporter refuses that combination.

`export(format="onnx")` writes a graph with `image` and `cliff_cond` inputs
and the mesh faces in its metadata.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreInstantHMRm-mesh.pt")
model.export(format="onnx")   # inputs image, cliff_cond; faces in metadata
```

## Checkpoints

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreInstantHMRn-mesh.pt` |  | Body mesh | cc-by-nc-4.0 |
| `LibreInstantHMRt-mesh.pt` |  | Body mesh | cc-by-nc-4.0 |
| `LibreInstantHMRs-mesh.pt` |  | Body mesh | cc-by-nc-4.0 |
| `LibreInstantHMRm-mesh.pt` |  | Body mesh | cc-by-nc-4.0 |
| `LibreInstantHMRm-mesh-commercial.pt` |  | Body mesh | apache-2.0 |

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: InstantHMR, Naturalpad and LAAS-CNRS
- Upstream license: CC-BY-NC-4.0 (n, t, s, m checkpoints); Apache-2.0 (m commercial checkpoint)
- Upstream source: https://github.com/Naturalpad-studio/InstantHMR
- LibreYOLO code: Apache-2.0
- Weights: CC-BY-NC-4.0 (n, t, s, m checkpoints); Apache-2.0 (m commercial checkpoint), republished at https://huggingface.co/LibreYOLO
- Interpretation: The licence depends on the checkpoint. The n, t, s and m weights are CC BY-NC 4.0: attribution is required and commercial use is not allowed, because part of their training images (SA-1B, AI Challenger) are non-commercial. LibreInstantHMRm-mesh-commercial was trained on Harmony4D and commercially licensed COCO images only and is Apache-2.0, which allows commercial and closed-source use if you keep the license text and notices. Every checkpoint was also trained on the SAM 3D Body dataset annotations, released by Meta under the SAM License, whose terms pass through with the weights, and they embed the MHR body constants (Apache-2.0). The upstream code is Apache-2.0 (Naturalpad-studio/InstantHMR at commit 5437400d4b25c1972821e51916fac34bd96acce6; LICENSE and NOTICE in libreyolo/models/instanthmr); the mesh decode was written clean-room so that no SAM-licensed sam-3d-body code is used, and the fine-tuning trainer is original LibreYOLO MIT code. Upstream publishes ONNX only (momolesang/InstantHMR, revision 07988f51c8c8908cfc7bb44fc18f645c9551b0bf); LibreYOLO converts them to PyTorch and mirrors them as LibreYOLO/LibreInstantHMR{n,t,s,m}-mesh and -m-mesh-commercial, not gated, and prints a notice before auto-download.

InstantHMR is by Naturalpad and LAAS-CNRS
([Naturalpad-studio/InstantHMR](https://github.com/Naturalpad-studio/InstantHMR)).
The code is Apache-2.0. The weights licence depends on the checkpoint:

- `n`, `t`, `s` and `m`: CC BY-NC 4.0, **non-commercial only**, because part
  of their training images (SA-1B, AI Challenger) are non-commercial.
- `m-commercial`: Apache-2.0, trained on Harmony4D and commercially licensed
  COCO images only.

Every checkpoint was also trained on the SAM 3D Body dataset annotations,
released by Meta under the SAM License, whose terms pass through with the
weights. The mesh decode was written clean-room, so no SAM-licensed
sam-3d-body code is used. The checkpoints are mirrored as
`LibreYOLO/LibreInstantHMR{n,t,s,m}-mesh` and
`LibreYOLO/LibreInstantHMRm-mesh-commercial`, not gated.

## Citation

```bibtex
@misc{adjel2026instanthmr,
  title        = {InstantHMR: Real-Time Human Mesh Recovery on Your Phone},
  author       = {Adjel, Mohamed and Chalabi, Kahina and Bonnet, Vincent},
  year         = {2026},
  howpublished = {HAL preprint hal-05854387},
  url          = {https://hal.science/hal-05854387},
  note         = {LAAS report no. 26486}
}
```

Copied from https://github.com/Naturalpad-studio/InstantHMR#citation
