SAM 3D Body

SAM 3D Body — управляемая промптами модель Meta, которая восстанавливает 3D-меш всего тела, включая кисти и стопы, по одному изображению и рамкам людей. LibreYOLO оборачивает upstream-пакет, а не портирует его.

Задачи: mesh
Размеры: d3, h at 512 px
Установка: pip install libreyolo
Уровень поддержки: Только инференс, начиная с v. Только предсказание, валидация и экспорт. Функции обучения неприменимы.
Исходный проект: SAM 3D Body от Meta Platforms, Inc., SAM License (not OSI-approved). Статья, исходный код
Лицензии: Код: MIT, веса: SAM License (not OSI-approved). Коммерческое использование

Установка

bash

pip install libreyolo

Так ставится только адаптер LibreYOLO. Сам SAM 3D Body в поставку не входит, потому что собственный код LibreYOLO не может быть производным от кода под такой лицензией: клонируйте upstream-репозиторий и установите его зависимости самостоятельно, а затем укажите LibreYOLO путь к клону.

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",
)

или задайте переменную окружения SAM_3D_BODY_PATH, чтобы не передавать sam_3d_body_path при каждом вызове. Тот, кто никогда не создаёт объект этого семейства, никогда не запускает импорт и никогда не сталкивается с SAM License. Это семейство не подключено ни к фабрике LibreYOLO(), ни к CLI-команде libreyolo predict; LibreSAM3DBody — единственная точка входа.

Предсказание

Python

from libreyolo import SAMPLE_IMAGEfrom libreyolo.models.sam3dbody import LibreSAM3DBody # Это семейство не зарегистрировано в фабрике LibreYOLO(), поэтому# объект создаётся напрямую. model_path=None запускает скачивание# с Hugging Face, доступ к которому ограничен; строка же трактуется# как путь к уже существующему локальному чекпойнту и никогда не# скачивается автоматически.# Для инференса нужно устройство с CUDA; пути через CPU нет.model = LibreSAM3DBody(None, size="d3", device="cuda")result = model(SAMPLE_IMAGE, person_boxes=[[34, 12, 220, 400]]) meshes = result.meshesprint(meshes.vertices.shape)    # (N, V, 3), система координат камеры, метрыprint(meshes.joints3d.shape)    # (N, J, 3)

С детектором людей

from libreyolo import LibreYOLO, SAMPLE_IMAGEfrom libreyolo.models.sam3dbody import LibreSAM3DBody # Здесь нет сокращения строкой-именем: передайте готовый детектор# LibreYOLO, обычный callable или экземпляр PersonDetector.detector = LibreYOLO("LibreRFDETRn.pt")model = LibreSAM3DBody(None, size="d3", device="cuda") result = model(SAMPLE_IMAGE, person_detector=detector)

Скачивание чекпойнта ограничено: чтобы первая загрузка прошла, нужно принять лицензию Meta на странице модели в Hugging Face и авторизоваться командой hf auth login. Самому инференсу устройство с CUDA нужно всегда: upstream-оценщик переносит батч на GPU без проверок, поэтому на машине только с CPU вместо отката на запасной путь выбрасывается ошибка. result.meshes — объект Meshes, построчно выровненный с result.boxes (по строке на каждого найденного человека): vertices и joints3d заданы в метрических единицах и уже включают оценённое смещение камеры, joints2d — в пикселях исходного изображения, а вращения следуют соглашению MHR: углы Эйлера, а не axis-angle. Об источниках, стриминге и обработке результатов см. предсказание.

Варианты

Два бэкбона за одной и той же моделью тела MHR: d3 использует энкодер DINOv3 ViT-H/16+, а h — исходный энкодер ViT-H.

Экспорт

Задача	ONNX	TorchScript	ExecuTorch	TensorRT	OpenVINO	Paddle	MNN	RKNN	ncnn	TFLite	CoreML	Core AI
mesh	mesh to ONNX: не поддерживается	mesh to TorchScript: не поддерживается	mesh to ExecuTorch: не поддерживается	mesh to TensorRT: не поддерживается	mesh to OpenVINO: не поддерживается	mesh to Paddle: не поддерживается	mesh to MNN: не поддерживается	mesh to RKNN: не поддерживается	mesh to ncnn: не поддерживается	mesh to TFLite: не поддерживается	mesh to CoreML: не поддерживается	mesh to Core AI: не поддерживается

Экспорт меша тела не реализован: LibreYOLO пока не определил контракт экспортируемого графа для задачи меша, в том числе как представлять раскладку параметров MHR за пределами PyTorch.

Чекпойнты

Все опубликованные файлы весов этого семейства.

Файл	Вход (пикс.)	Лицензия весов
mesh
LibreSAM3DBodyd3-mesh.pt	512	other
LibreSAM3DBodyh-mesh.pt	512	other

Все перечисленные выше файлы уже доступны в организации LibreYOLO и скачиваются при первом использовании.

Лицензирование

Проверяйте лицензию в репозитории конкретных весов на Hugging Face. Она указана для каждого чекпойнта в организации LibreYOLO и может различаться даже внутри одного семейства. Этот репозиторий считается авторитетным источником, а сводка ниже описывает условия на момент последней проверки страницы.

Это описание соответствующих лицензий, а не юридическая консультация. Если ответ важен для коммерческого использования, прочитайте лицензии самостоятельно и проконсультируйтесь с юристом.

Оригинальная работа: SAM 3D Body, Meta Platforms, Inc.
Лицензия исходного проекта: SAM License (not OSI-approved)
Исходный код проекта: github.com/facebookresearch/sam-3d-body
Код LibreYOLO: MIT
Веса: SAM License (not OSI-approved), повторно опубликованы на huggingface.co/LibreYOLO
Толкование: 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.

Модель тела, которой управляют эти чекпойнты, — MHR (Momentum Human Rig) — выпущена Meta отдельно, под лицензией Apache-2.0. LibreYOLO во время работы скачивает её TorchScript-файл из публичного релиза самого MHR и кэширует локально; этот файл LibreYOLO у себя не зеркалирует, и на него распространяются собственные условия Apache-2.0, а не SAM License.

Цитирование

@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}
}

Скопировано из блока цитирования авторов на странице github.com/facebookresearch/sam-3d-body#citing-sam-3d-body.