SAM3DBody-cpp 소개
단일 카메라 한 대로 사람의 3차원 자세와 전신 메시를 실시간으로 복원하는 일은 보통 무거운 Python 딥러닝 스택을 필요로 합니다. SAM3DBody-cpp는 그 추론 과정을 순수 C++로 옮긴 독립 실행형 추론 엔진입니다. 런타임에는 Python 의존성이 전혀 없으며, BGR 이미지를 입력받아 사람별 신체 자세 파라미터와 카메라 변환(translation), 그리고 선택적으로 전체 3D 메시 정점과 70개의 신체·손 키포인트를 출력합니다.
SAM3DBody-cpp는 SAM-3D-Body 모델의 추론을 ONNX Runtime과 ggml로 실행합니다. 카메라 영상에서 추출한 자세를 표준 BVH 모션 캡처 파일로 내보낼 수 있어, 결과물을 Blender 같은 DCC 도구에 그대로 가져다 쓸 수 있습니다. 컴파일된 공유 라이브러리를 ctypes로 호출하는 Python 프론트엔드와, 70개 키포인트를 내보내는 CSV 익스포터도 함께 제공됩니다.
이 프로젝트의 특징은 추론 경로를 가볍게 유지하면서도 손과 표정까지 포함한 조밀한 신체 모델을 다룬다는 점입니다. 무거운 비전 백본은 ONNX Runtime의 CUDA 실행 제공자(execution provider)에서 돌리고, 작은 후처리 헤드는 ggml로 CPU에서 계산하는 식으로 역할을 나눕니다. 모델·데이터 변환과 학습 환경 같은 개발 도구는 상위 프로젝트인 Fast-SAM-3D-Body에 분리되어 있습니다.
SAM3DBody-cpp의 복원 파이프라인
SAM3DBody-cpp는 2D 키포인트를 3D로 들어 올리는(2D-to-3D lifting) 방식이 아닙니다. 깊이 센서나 바닥 평면, 스테레오 없이 이미지 특징에서 곧바로 3D 신체 모델 파라미터를 회귀(regress)합니다. 원본 이미지에서 시작하는 단계는 다음과 같습니다.
- YOLO11m-pose 가 사람의 바운딩 박스와 17개의 COCO 키포인트를 검출합니다.
- 각 크롭은 DINOv3-ViT-H/14+ 백본 을 거쳐
[1280, 32, 32]공간 특징 맵으로 변환됩니다. 이 단계가 연산량이 가장 큽니다. - 6층 PromptableDecoder 가 크롭의 광선 방향(ray direction)과 초점 거리를 조건으로 받아 특징 맵을 1024차원 자세 토큰으로 압축합니다.
- 두 개의 작은 FFN 헤드가 ggml로 CPU에서 실행되어, 519개의 자세 파라미터와 3개의 카메라 파라미터를 디코딩합니다. 자세 파라미터에는 전역 방향(6D 연속 회전 표현), 127개 관절의 오일러 각, SMPL 계열의 형태 베타(shape betas), 손 자세, 표정이 포함됩니다.
- 이 파라미터들이 18,439개 정점에 대한 선형 블렌드 스키닝(Linear Blend Skinning, LBS)을 구동해 전체 신체 메시와 70개 키포인트를 만듭니다.
초점 거리는 이미지 대각선에서 추정해 디코더의 조건 입력에 반영합니다. 그래서 모델은 크롭 안에서 보이는 신체 크기를 미터 단위 깊이와 연관 짓도록 학습되며, 이는 SMPL/HMR 계열 모델이 쓰는 단안(monocular) 신체 비례 기반 깊이 추정과 같은 접근입니다. 복원된 신체는 예측된 루트 변환(root translation)을 통해 카메라 공간에 배치됩니다.
SAM3DBody-cpp의 다중 인물 BVH 모션 캡처 출력
--bvh 옵션을 주면 검출된 사람마다 표준 BVH 모션 캡처 파일(p_0.bvh, p_1.bvh 등)을 따로 씁니다. 내장된 2D 바운딩 박스 IoU 트래커가 프레임 사이에서 각 인물의 정체성을 안정적으로 유지하고, 각 파일의 관절 OFFSET은 해당 배우의 측정된 뼈 길이에 맞춰 자동으로 조정됩니다. 결과 파일은 Blender나 BVHTester 같은 도구로 바로 가져갈 수 있으며, 함께 제공되는 Blender 플러그인은 그 결과로 MakeHuman 리깅 캐릭터를 구동합니다.
./fast_sam_3dbody_run --from clip.mp4 --bvh ./p.bvh --headless
# → p_0.bvh, p_1.bvh, …
SAM3DBody-cpp 설치와 실행
먼저 사전 빌드된 ONNX·GGUF·LBS 모델 파일을 Hugging Face 모델 저장소에서 받아 onnx/ 디렉토리를 저장소 루트에 둡니다. 빌드 요구 사항은 CMake 3.18 이상, C++17 컴파일러, OpenCV이며 CUDA Toolkit은 선택입니다.
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
CMake가 의존성을 자동으로 처리합니다. ONNX Runtime 1.20.1은 없으면 GitHub 릴리스에서 내려받고, ggml은 FetchContent로 가져오며, CUDA는 자동 감지되어 없으면 CPU 전용으로 폴백합니다. 빌드가 끝나면 독립 실행 파일 fast_sam_3dbody_run 과 공유 라이브러리 libfast_sam_3dbody.so 가 만들어집니다.
# 단일 이미지: 자세 파라미터를 표준 출력으로
./fast_sam_3dbody_run --onnx-dir ../onnx --gguf ../onnx/pipeline.gguf \
--yolo ../onnx/yolo.onnx --from input.png
# 웹캠(장치 0)
./fast_sam_3dbody_run --onnx-dir ../onnx --gguf ../onnx/pipeline.gguf \
--yolo ../onnx/yolo.onnx --from 0
기본 backbone.onnx 는 BFloat16으로 내보내져 CUDA GPU가 필요합니다. CUDA GPU가 없으면 같은 Hugging Face 저장소에서 float32 CPU 호환 백본(backbone_fp32.onnx)을 받아 --backbone backbone_fp32.onnx --cuda -1 로 실행합니다. 다만 DINOv3-ViT-H는 약 6억 3천만 개의 파라미터를 가지고 있어, 최신 노트북 CPU에서 백본 한 번의 순전파에 5~15초가 걸립니다. 따라서 영상 처리는 사실상 어렵고, 단일 이미지나 저빈도 사용에 적합합니다. 실시간에 가까운 처리에는 CUDA GPU가 필요합니다.
SAM3DBody-cpp의 라이선스
SAM3DBody-cpp는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
SAM3DBody-cpp 모델 다운로드
SAM3DBody-cpp 프로젝트 GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 