SAM 3D Body

SAM 3D Body는 단일 이미지와 사람 박스에서 손과 발을 포함한 전신 3D 메시를 복원하는 Meta의 프롬프트 가능 모델입니다. LibreYOLO는 이를 이식하는 대신 업스트림 패키지를 래핑합니다.

작업: mesh
크기: d3, h at 512 px
설치: pip install libreyolo
지원 티어: 추론 전용, v부터 지원. 예측, 검증, 내보내기만 지원합니다. 학습 기능은 적용되지 않습니다.
업스트림: Meta Platforms, Inc.의 SAM 3D Body, SAM License (not OSI-approved). 논문, 소스
라이선스: 코드 MIT, 가중치 SAM License (not OSI-approved). 상업적 사용

설치

bash

pip install libreyolo

이 명령은 LibreYOLO 어댑터만 설치합니다. SAM 3D Body 자체는 번들로 제공되지 않습니다. 해당 라이선스로부터 LibreYOLO의 자체 코드를 파생할 수 없기 때문입니다. 업스트림 저장소를 복제하고 종속성을 직접 설치한 뒤 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() 팩토리나 libreyolo predict CLI 명령에 연결되어 있지 않습니다. 유일한 진입점은 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)

체크포인트 다운로드에는 접근 제한이 있습니다. Hugging Face 모델 페이지에서 Meta의 라이선스에 동의하고 첫 다운로드 전에 hf auth login으로 인증해야 합니다. 추론 자체에는 조건 없이 CUDA 장치가 필요합니다. 업스트림 추정기가 확인 없이 배치를 GPU로 이동하므로 CPU 전용 시스템에서는 대체 경로로 전환하지 않고 예외가 발생합니다. result.meshes는 result.boxes와 행이 정렬된 Meshes 페이로드이며 탐지된 사람마다 행 하나가 대응합니다. vertices와 joints3d는 미터 단위이고 추정된 카메라 이동을 이미 포함합니다. joints2d는 원본 이미지의 픽셀 좌표이며 회전은 축각이 아닌 오일러 각을 사용하는 MHR 규칙을 따릅니다. 소스, 스트리밍, 결과 처리는 예측을 참조합니다.

변형

동일한 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 외부에서 표현하는 방법을 포함해 메시 작업용 내보낸 그래프 계약을 아직 정의하지 않았습니다.

체크포인트

이 계열에 공개된 모든 가중치 파일입니다.

파일	입력(px)	가중치 라이선스
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)은 Apache-2.0으로 공개된 별도의 Meta 릴리스입니다. LibreYOLO는 런타임에 MHR의 자체 공개 릴리스에서 TorchScript 자산을 가져와 로컬에 캐시합니다. 이 파일은 LibreYOLO에서 미러링하지 않으며 SAM License가 아니라 자체 Apache-2.0 약관이 적용됩니다.

인용

@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에 있는 저자의 인용 블록에서 복사했습니다.