# SAM 3D Body
SAM 3D Body is Meta's promptable model for recovering a full-body 3D mesh, including hands and feet, from a single image and person boxes. LibreYOLO wraps the upstream package rather than porting it.
Tasks: Body mesh. Install: pip install libreyolo.
Verified against LibreYOLO v1.6.0.

## Install

```bash
pip install libreyolo
```

That gives you LibreYOLO's adapter only. SAM 3D Body itself is not bundled,
because its license is not one LibreYOLO's own code may be derived from: clone
the upstream repository and install its dependencies yourself, then point
LibreYOLO at the clone.

```bash
git clone https://github.com/facebookresearch/sam-3d-body
pip install roma einops yacs omegaconf braceexpand pytorch-lightning timm
```

```python
from libreyolo.models.sam3dbody import LibreSAM3DBody

model = LibreSAM3DBody(
    None,
    size="d3",
    sam_3d_body_path="/path/to/sam-3d-body",
    device="cuda",
)
```

or set the `SAM_3D_BODY_PATH` environment variable instead of passing
`sam_3d_body_path` on every call. A user who never constructs this family
never triggers the import, and never encounters the SAM License. This family
is not wired into the `LibreYOLO()` factory or the `libreyolo predict` CLI
command; `LibreSAM3DBody` is the only entry point.

## Predict

**Python**

```python
from libreyolo import SAMPLE_IMAGE
from libreyolo.models.sam3dbody import LibreSAM3DBody

# This family is not registered with the LibreYOLO() factory, so it
# is constructed directly. model_path=None is what triggers the
# gated Hugging Face download; a string is instead treated as an
# existing local checkpoint path and is never fetched automatically.
# Inference requires a CUDA device; there is no CPU path.
model = LibreSAM3DBody(None, size="d3", device="cuda")
result = model(SAMPLE_IMAGE, person_boxes=[[34, 12, 220, 400]])

meshes = result.meshes
print(meshes.vertices.shape)    # (N, V, 3), camera frame, meters
print(meshes.joints3d.shape)    # (N, J, 3)
```

**With a person detector**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE
from libreyolo.models.sam3dbody import LibreSAM3DBody

# No named-string shortcut here: pass a constructed LibreYOLO
# detector, a plain callable, or a PersonDetector instance.
detector = LibreYOLO("LibreRFDETRn.pt")
model = LibreSAM3DBody(None, size="d3", device="cuda")

result = model(SAMPLE_IMAGE, person_detector=detector)
```

The checkpoint download is gated: it requires accepting Meta's license on the
Hugging Face model page and authenticating with `hf auth login` before the
first download succeeds. Inference itself needs a CUDA device unconditionally:
the upstream estimator moves its batch to the GPU without checking, so a
CPU-only machine raises rather than falling back. `result.meshes` is a
`Meshes` payload, row-aligned with `result.boxes` (one row per detected
person): `vertices` and `joints3d` are metric and already include the
estimated camera translation, `joints2d` is in pixels on the original image,
and rotations follow MHR's convention, Euler angles rather than axis-angle.
See [prediction](/docs/predict) for sources, streaming and result handling.

Automatic acquisition requires `libreyolo[hf]` and access to the gated model. Local checkpoints must be the reviewed snapshot directory, or its unchanged `model.ckpt` beside matching `model_config.yaml` and `LICENSE`. Pinned hashes and accepted snapshot inventories reject renamed, modified, linked or extra assets. MHR assets are also pinned. Keep the local snapshot unchanged while the upstream constructor reads it.

## Variants

Two backbones behind the same MHR body model: `d3` uses a DINOv3 ViT-H/16+
encoder, and `h` uses the original ViT-H encoder.

## Export

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

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

Body-mesh export is not implemented: LibreYOLO has not yet defined an
exported-graph contract for the mesh task, including how to represent the MHR
parameter layout outside PyTorch.

## 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: SAM 3D Body, Meta Platforms, Inc.
- Upstream license: SAM License (not OSI-approved)
- Upstream source: https://github.com/facebookresearch/sam-3d-body
- LibreYOLO code: MIT
- Weights: SAM License (not OSI-approved), republished at https://huggingface.co/LibreYOLO
- Interpretation: The SAM License is not one OSI recognizes as open source. Meta can amend its terms unilaterally, disclaims all warranty and liability, forbids reverse engineering the SAM Materials, and forbids any use touching military or warfare purposes, nuclear applications, espionage, weapons, or other export-controlled ends. It does not forbid commercial use outright, but a litigation clause ends your license the moment you sue Meta over the SAM Materials, so read it yourself before shipping a product on it. LibreYOLO wraps Meta's package rather than porting its code: none of it is vendored, it is an optional dependency the user installs themselves, and a user who never touches the mesh task never encounters these terms. The checkpoints are mirrored byte-identically behind the same Hugging Face access gate Meta uses, so accepting the license happens on Meta's own model page. LibreYOLO's own adapter code is MIT. The body model the checkpoints drive, MHR (Momentum Human Rig), is Meta's separate Apache-2.0 release and is fetched at runtime from its own public repository rather than mirrored.

The body model the checkpoints drive, MHR (Momentum Human Rig), is a separate
Meta release under Apache-2.0. LibreYOLO fetches its TorchScript asset from
MHR's own public release at runtime and caches it locally; that file is not
mirrored by LibreYOLO and carries its own Apache-2.0 terms, not the SAM
License.

## Citation

```bibtex
@article{yang2026sam3dbody,
  title={SAM 3D Body: Robust Full-Body Human Mesh Recovery},
  author={Yang, Xitong and Kukreja, Devansh and Pinkus, Don and Sagar, Anushka and Fan, Taosha and Park, Jinhyung and Shin, Soyong and Cao, Jinkun and Liu, Jiawei and Ugrinovic, Nicolas and Feiszli, Matt and Malik, Jitendra and Dollar, Piotr and Kitani, Kris},
  journal={arXiv preprint arXiv:2602.15989},
  year={2026}
}
```

Copied from https://github.com/facebookresearch/sam-3d-body#citing-sam-3d-body