Сітка тіла

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

Визначення

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

Усе виражено в системі координат камери вихідного зображення. transl подано в метрах, а +z спрямовано від камери. vertices і joints3d подано в метричних одиницях, і вони вже містять transl, тому додаткова композиція не потрібна. joints2d подано в пікселях полотна вихідного зображення, а не фрагмента, який отримала мережа. faces містить топологію сітки один раз для всього зображення, а не для кожного рядка, оскільки вона спільна для всіх людей. У цій версії немає світової системи координат чи системи сили тяжіння, і жодне поле не підміняє їх неявно.

Структури параметрів різних моделей тіла відрізняються, тому форми не фіксовані: body_model називає параметризацію, а кількість елементів визначається з тензорів. Для "mhr", Momentum Human Rig, обертання подано кутами Ейлера в радіанах, а не у форматі вісь-кут; body_pose, це плоский вектор параметрів для суглобів, а не одна трійка на суглоб; betas, це коефіцієнти blendshape ідентичності. Масштаб скелета, поза рук і вираз обличчя містяться в extras.

Канонічний ключ задачі, mesh. body-mesh, hmr і human-mesh-recovery нормалізуються до нього.

Моделі

SAM 3D Body, єдине сімейство для цієї задачі, і це обгортка, а не перенесення коду. Пакет Meta sam-3d-body опубліковано за ліцензією SAM, на основі якої не можна створювати власний код 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() спричиняє помилку замість створення графа, результат якого неможливо інтерпретувати.