Меш тела

Восстановление меша тела превращает одно изображение и набор рамок людей в параметрическое 3D-тело для каждого человека: параметры формы и позы, вершины в заданной позе, 3D-суставы и сдвиг камеры, который помещает их перед объективом.

Определение

Восстановление меша тела возвращает объект Meshes на каждое изображение, строки которого выровнены с result.boxes: строка i описывает человека в рамке i — тот же контракт, который задача оценки позы использует для ключевых точек.

Всё выражено в системе координат камеры исходного изображения. transl — метрическая величина в метрах, ось +z направлена от камеры. vertices и joints3d метрические и уже включают transl, поэтому складывать что-то дополнительно не нужно. joints2d — пиксели на холсте исходного изображения, а не на кропе, который видела сеть. faces хранит топологию меша один раз на всё изображение, а не построчно, потому что она общая для всех людей. Мировой системы координат или системы, связанной с гравитацией, в этой версии нет, и ни одно поле молча их не подменяет.

Раскладка параметров различается между моделями тела, поэтому ничего о формах тензоров не зафиксировано: body_model называет параметризацию, а размерности читаются из самих тензоров. Для "mhr", Momentum Human Rig, повороты заданы углами Эйлера в радианах, а не в осево-угловом представлении, body_pose — плоский вектор параметров по суставам, а не по тройке на сустав, а betas — коэффициенты блендшейпов идентичности. Масштаб скелета, поза кистей и мимика лежат в extras.

Канонический ключ задачи — mesh. body-mesh, hmr и human-mesh-recovery приводятся к нему.

Модели

SAM 3D Body — единственное семейство для этой задачи, и это обёртка, а не порт: пакет sam-3d-body от Meta выпущен под SAM License, от которой код самой LibreYOLO не может быть производным, поэтому ничего из него не вложено в репозиторий. Два бэкбона используют одну и ту же модель тела MHR: d3 на энкодере DINOv3 ViT-H/16+ и h на исходном ViT-H.

Перед первым предсказанием нужно выполнить три условия, и ни одно из них не опционально.

Пакет из upstream-проекта устанавливаете вы, а не LibreYOLO:

bash

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

Укажите библиотеке путь к клону через sam_3d_body_path= или переменную окружения SAM_3D_BODY_PATH. Если это семейство не создаётся, импорт не происходит вовсе.

Зеркало с чекпойнтом закрыто. Примите лицензию на странице модели на Hugging Face и авторизуйтесь через hf auth login — иначе первое скачивание завершится ошибкой. Сама модель тела MHR — отдельный релиз под Apache-2.0, она скачивается из собственного публичного источника и кэшируется локально.

Для инференса нужно устройство с CUDA. Модуль оценки из upstream-проекта переносит батч на GPU без проверок, поэтому запасного пути через CPU нет, а device="cpu" вызывает ошибку.

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

Python

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

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

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

Люди попадают в модель одним из двух способов. person_boxes передаёт рамки, которые у вас уже есть, и только для одного изображения: фиксированный набор рамок не может следовать за людьми по кадрам видео, поэтому с видеоисточником этот аргумент вызывает ошибку, а не молча переиспользует рамки первого кадра. person_detector принимает готовый детектор LibreYOLO, вызываемый объект или PersonDetector — это путь для видео. focal_length задаёт известный внутренний параметр камеры; если его не указать, модель использует собственную оценку, и именно её сообщает meshes.focal_length.

Это семейство не подключено ни к фабрике LibreYOLO(), ни к CLI-команде libreyolo predict. LibreSAM3DBody — единственная точка входа. Об источниках, стриминге и работе с результатами см. предсказание.

Обучение

Ни одно семейство в этой задаче не обучается внутри LibreYOLO. LibreSAM3DBody.train() вызывает ошибку: обучайте в upstream-проекте и загружайте получившийся чекпойнт сюда.

Валидация

Валидатора для мешей нет, и val() вызывает ошибку. Обычные бенчмарки распространяются только под исследовательской лицензией, поэтому ни один из них не входит в комплект и ни один не скачивается автоматически.

Сами метрики доступны как libreyolo.validation.mesh_metrics — для оценки на датасете, который у вас уже есть. Функция принимает предсказанные и эталонные суставы, опционально предсказанные и эталонные вершины, и возвращает словарь ровно с теми же ключами, что и у валидатора:

metrics/mpjpe — средняя ошибка положения по суставам после выравнивания корневого сустава, то есть она оценивает позу, игнорируя, где человек стоит в сцене. metrics/pa_mpjpe — та же величина после полного выравнивания по Прокрусту: поворот, равномерный масштаб и сдвиг, что убирает ошибку глобальной ориентации и размера тела и оставляет только позу суставов. metrics/pve — средняя ошибка по вершинам поверхности меша после выравнивания по центроиду вершин; в отличие от суставных метрик она чувствительна к форме тела и появляется, только если переданы оба массива вершин. Во всех трёх метриках меньше — лучше. Входные данные считаются метрическими, в метрах, а scale_to_mm переводит результаты в миллиметры, в которых их приводят в статьях.

Экспорт

Экспорт мешей не реализован. В LibreYOLO не определён контракт метаданных экспортированного графа для этой задачи, в том числе то, как переносить раскладку параметров MHR за пределы PyTorch, поэтому export() вызывает ошибку, а не выдаёт граф, вывод которого нельзя было бы интерпретировать.