SAM 3D Body

Instalación

pip install libreyolo

Eso te da solo el adaptador de LibreYOLO. SAM 3D Body en sí no viene incluido, porque su licencia no es una de la que pueda derivarse el código propio de LibreYOLO: clona el repositorio upstream e instala sus dependencias por tu cuenta, y luego apunta LibreYOLO al clon.

git clone https://github.com/facebookresearch/sam-3d-bodypip 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",)

o define la variable de entorno SAM_3D_BODY_PATH en lugar de pasar sam_3d_body_path en cada llamada. Quien nunca construya esta familia no dispara nunca el import, y nunca se topa con la SAM License. Esta familia no está conectada a la factoría LibreYOLO() ni al comando de CLI libreyolo predict; LibreSAM3DBody es el único punto de entrada.

Predicción

from libreyolo import SAMPLE_IMAGEfrom libreyolo.models.sam3dbody import LibreSAM3DBody # Esta familia no está registrada en la factoría LibreYOLO(), así# que se construye directamente. model_path=None es lo que dispara# la descarga restringida de Hugging Face; una cadena, en cambio, se# trata como la ruta de un checkpoint local ya existente y nunca se# descarga automáticamente.# La inferencia requiere un dispositivo CUDA; no hay camino por 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 de la cámara, metrosprint(meshes.joints3d.shape)    # (N, J, 3)

from libreyolo import LibreYOLO, SAMPLE_IMAGEfrom libreyolo.models.sam3dbody import LibreSAM3DBody # Aquí no hay atajo por cadena con nombre: pasa un detector# LibreYOLO ya construido, un callable normal o una instancia de# PersonDetector.detector = LibreYOLO("LibreRFDETRn.pt")model = LibreSAM3DBody(None, size="d3", device="cuda") result = model(SAMPLE_IMAGE, person_detector=detector)

La descarga del checkpoint está restringida: exige aceptar la licencia de Meta en la página del modelo en Hugging Face y autenticarse con hf auth login para que la primera descarga funcione. La inferencia en sí necesita un dispositivo CUDA sin excepciones: el estimador upstream mueve su batch a la GPU sin comprobar nada, así que una máquina solo con CPU lanza un error en vez de hacer fallback. result.meshes es un payload Meshes, alineado fila a fila con result.boxes (una fila por persona detectada): vertices y joints3d son métricos y ya incluyen la traslación de cámara estimada, joints2d va en píxeles sobre la imagen original, y las rotaciones siguen la convención de MHR, ángulos de Euler en lugar de axis-angle. Consulta predicción para las fuentes, el streaming y el manejo de resultados.

La descarga automática requiere libreyolo[hf] y acceso al modelo restringido. Los checkpoints locales deben ser el directorio de snapshot revisado, o su model.ckpt sin modificar junto con los archivos model_config.yaml y LICENSE correspondientes. Los hashes fijados y los inventarios de snapshots aceptados rechazan archivos renombrados, modificados, enlazados o adicionales. Los archivos de MHR también están fijados. Mantén el snapshot local sin cambios mientras el constructor upstream lo lee.

Variantes

Dos backbones detrás del mismo modelo corporal MHR: d3 usa un encoder DINOv3 ViT-H/16+ y h usa el encoder ViT-H original.

Exportación

La exportación de mallas corporales no está implementada: LibreYOLO todavía no ha definido un contrato de grafo exportado para la tarea de malla, incluido cómo representar la disposición de parámetros de MHR fuera de PyTorch.

Licencia

Cita

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