SAM 3D Body

Installazione

pip install libreyolo

Questo ti dà solo l'adattatore di LibreYOLO. SAM 3D Body in sé non è incluso, perché la sua licenza non è una da cui il codice di LibreYOLO possa derivare: clona il repository upstream e installa le sue dipendenze per conto tuo, poi fai puntare LibreYOLO al clone.

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

from libreyolo.models.sam3dbody import LibreSAM3DBody

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

oppure imposta la variabile d'ambiente SAM_3D_BODY_PATH invece di passare sam_3d_body_path a ogni chiamata. Chi non costruisce mai questa famiglia non innesca mai l'import, e non incontra mai la SAM License. Questa famiglia non è collegata alla factory LibreYOLO() né al comando CLI libreyolo predict; LibreSAM3DBody è l'unico entry point.

Predizione

from libreyolo import SAMPLE_IMAGEfrom libreyolo.models.sam3dbody import LibreSAM3DBody # Questa famiglia non è registrata nella factory LibreYOLO(),# quindi la si costruisce direttamente. model_path=None è ciò che# innesca il download vincolato da Hugging Face; una stringa è# invece trattata come il percorso di un checkpoint locale già# esistente e non viene mai scaricata automaticamente.# L'inferenza richiede un dispositivo CUDA; non c'è un percorso 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), sistema della camera, metriprint(meshes.joints3d.shape)    # (N, J, 3)

from libreyolo import LibreYOLO, SAMPLE_IMAGEfrom libreyolo.models.sam3dbody import LibreSAM3DBody # Qui non c'è una scorciatoia con stringa nominata: passa un# detector LibreYOLO già costruito, un semplice callable oppure# un'istanza di PersonDetector.detector = LibreYOLO("LibreRFDETRn.pt")model = LibreSAM3DBody(None, size="d3", device="cuda") result = model(SAMPLE_IMAGE, person_detector=detector)

Il download del checkpoint è vincolato: richiede di accettare la licenza di Meta sulla pagina del modello su Hugging Face e di autenticarsi con hf auth login perché il primo download vada a buon fine. L'inferenza stessa ha bisogno di un dispositivo CUDA senza eccezioni: l'estimatore upstream sposta il suo batch sulla GPU senza controllare, quindi una macchina con la sola CPU solleva un errore invece di ricadere su un fallback. result.meshes è un payload Meshes, allineato riga per riga con result.boxes (una riga per persona rilevata): vertices e joints3d sono metrici e includono già la traslazione stimata della camera, joints2d è in pixel sull'immagine originale, e le rotazioni seguono la convenzione di MHR, angoli di Eulero invece che axis-angle. Vedi predizione per le sorgenti, lo streaming e la gestione dei risultati.

Varianti

Due backbone dietro lo stesso modello corporeo MHR: d3 usa un encoder DINOv3 ViT-H/16+, mentre h usa l'encoder ViT-H originale.

Esportazione

L'esportazione della mesh corporea non è implementata: LibreYOLO non ha ancora definito un contratto di grafo esportato per il task della mesh, compreso come rappresentare il layout dei parametri di MHR fuori da PyTorch.

Checkpoint

Tutti i file di pesi pubblicati per questa famiglia.

Licenze

Citazione

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