SAM 3D

SAM 3D Body 是 SAM 3D 的一部分，SAM 3D 是一套用于物体和人体网格重建的模型。如果您正在寻找 SAM 3D Objects，请点击此处。

SAM 3D Body：鲁棒的全身人体网格恢复

Xitong Yang*, Devansh Kukreja*, Don Pinkus*, Anushka Sagar, Taosha Fan, Jinhyung Park⚬, Soyong Shin⚬, Jinkun Cao, Jiawei Liu, Nicolas Ugrinovic, Matt Feiszli†, Jitendra Malik†, Piotr Dollar†, Kris Kitani†

Meta 超级智能实验室

*核心贡献者， ⚬实习生， †项目负责人

SAM 3D Body (3DB) 是一种可提示的单张图像全身三维人体网格恢复（HMR）模型。我们的方法表现出最先进的性能，在各种野外条件下具有强大的泛化能力和一致的准确性。3DB 基于 Momentum Human Rig（MHR），这是一种新的参数化网格表示法，它将骨骼结构与表面形状解耦，以提高准确性和可解释性，从而估计人体的躯干、脚部和手部姿态。

3DB 采用编码器-解码器架构，并支持辅助提示，包括二维关键点和掩码，从而实现类似于 SAM 系列模型的用户引导推理。我们的模型是在高质量注释数据上训练的，这些数据来自一个多阶段的注释管道，该管道使用可微优化、多视角几何、密集关键点检测以及一个数据引擎来收集和标注涵盖常见和罕见姿势、且视角广泛的图像数据。

定性结果

输入	SAM 3D Body	CameraHMR	NLF	HMR2.0b

与现有方法相比，我们的 SAM 3D Body 展现出更优的重建质量，具有更精确的姿势估计、更好的形状恢复，以及对遮挡和复杂视角的更好处理能力。

最新更新

2025年11月19日 -- 检查点发布，数据集公开，网页演示和论文已上线！

安装

请参阅 INSTALL.md，了解 Python 环境设置和模型检查点访问的说明。

入门

3DB 可以从单张图像中重建全身三维人体网格，还可以选择性地使用关键点/掩码提示，以及通过手部解码器进行手部细化。

要快速入门，请运行我们的演示脚本，使用来自 Hugging Face 的模型进行推理和可视化（请务必遵循 INSTALL.md 来申请访问我们的检查点）。

# 从 Hugging Face 下载资源
hf download facebook/sam-3d-body-dinov3 --local-dir checkpoints/sam-3d-body-dinov3

# 使用默认的 ViTdet 检测器和 MoGe2 FOV 模型运行演示脚本
python demo.py \
    --image_folder <图片路径> \
    --output_folder <输出路径> \
    --checkpoint_path ./checkpoints/sam-3d-body-dinov3/model.ckpt \
    --mhr_path ./checkpoints/sam-3d-body-dinov3/assets/mhr_model.pt

# 若要使用 SAM3 作为检测器，以与 SAM3D 的在线 Playground 保持一致
python demo.py \
    --image_folder <图片路径> \
    --output_folder <输出路径> \
    --checkpoint_path ./checkpoints/sam-3d-body-dinov3/model.ckpt \
    --mhr_path ./checkpoints/sam-3d-body-dinov3/assets/mhr_model.pt \
    --detector_name sam3

你也可以尝试以下代码，直接从 Hugging Face 加载模型：

import cv2
import numpy as np
from notebook.utils import setup_sam_3d_body
from tools.vis_utils import visualize_sample_together

# 设置估计器
estimator = setup_sam_3d_body(hf_repo_id="facebook/sam-3d-body-dinov3")

# 加载并处理图像
img_bgr = cv2.imread("图片路径.jpg")
outputs = estimator.process_one_image(cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB))

# 可视化并保存结果
rend_img = visualize_sample_together(img_bgr, outputs, estimator.faces)
cv2.imwrite("output.jpg", rend_img.astype(np.uint8))

如需完整的可视化演示，请参阅 notebook/demo_human.ipynb。

模型说明

SAM 3D Body 检查点

下表展示了 2025 年 11 月 19 日发布的 SAM 3D Body 检查点的性能。

主干网络（规模）	3DPW (MPJPE)	EMDB (MPJPE)	RICH (PVE)	COCO (PCK@.05)	LSPET (PCK@.05)	Freihand (PA-MPJPE)
DINOv3-H+ (840M) (配置, 检查点)	54.8	61.7	60.3	86.5	68.0	5.5
ViT-H (631M) (配置, 检查点)	54.8	62.9	61.7	86.8	68.9	5.5

SAM 3D Body 数据集

SAM 3D Body 数据已在 Hugging Face 上发布。请按照 说明 下载并处理数据。

SAM 3D Objects

SAM 3D Objects 是一种基础模型，能够从单张图像中重建完整的 3D 形状几何、纹理和布局。

为了结合 SAM 3D Objects 和 SAM 3D Body 的优势，我们提供了一个示例笔记本，演示如何将两种模型的结果结合起来，使它们在同一参考系中对齐。请在此处查看：https://github.com/facebookresearch/sam-3d-objects/blob/main/notebook/demo_3db_mesh_alignment.ipynb。

许可证

SAM 3D Body 模型检查点和代码采用 SAM 许可证 许可。

贡献

请参阅 贡献指南 和 行为准则。

贡献者

SAM 3D Body 项目得益于众多贡献者的帮助： Vivian Lee、George Orlin、Nikhila Ravi、Andrew Westbury、Jyun-Ting Song、Zejia Weng、Xizi Zhang、Yuting Ye、Federica Bogo、Ronald Mallet、Ahmed Osman、Rawal Khirodkar、Javier Romero、Carsten Stoll、Jean-Charles Bazin、Sofien Bouaziz、Yuan Dong、Su Zhaoen、Fabian Prada、Alexander Richard、Michael Zollhoefer、Roman Rädle、Sasha Mitts、Michelle Chan、Yael Yungster、Azita Shokrpour、Helen Klein、Mallika Malhotra、Ida Cheng、Eva Galper。

引用 SAM 3D Body

如果您在研究中使用了 SAM 3D Body 或 SAM 3D Body 数据集，请使用以下 BibTeX 条目。

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

SAM 3D Body 快速上手指南

SAM 3D Body 是 Meta 推出的基于单张图像进行全身 3D 人体网格重建的模型。它支持提示词（如 2D 关键点和掩码）引导推理，并在各种复杂场景下表现出卓越的泛化能力和准确性。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 18.04+) 或 macOS。
• Python: 3.9 或更高版本。
• GPU: 推荐使用 NVIDIA GPU (CUDA 11.8+) 以获得最佳推理速度。
• 前置依赖:
  • PyTorch (与 CUDA 版本匹配)
  • OpenCV (opencv-python)
  • Hugging Face Hub (huggingface_hub)
  • 其他深度学习常用库 (numpy, PIL 等)

注意：具体的 Python 环境配置细节（如虚拟环境创建、特定版本依赖安装）请参阅项目根目录下的 INSTALL.md 文件。

安装步骤

1. 克隆仓库

首先克隆官方代码库：

git clone https://github.com/facebookresearch/sam-3d-body.git
cd sam-3d-body

2. 安装依赖

根据 INSTALL.md 中的指引安装必要的 Python 包。通常涉及安装 PyTorch 和项目要求的 requirements.txt。

3. 获取模型权重

模型权重托管在 Hugging Face 上。由于权限控制，您可能需要先访问 Hugging Face 页面申请访问权限，然后使用以下命令下载检查点（Checkpoints）和资源文件：

# 下载 DINOv3-H+  backbone 的模型权重
hf download facebook/sam-3d-body-dinov3 --local-dir checkpoints/sam-3d-body-dinov3

注：如果下载速度慢，可尝试配置 Hugging Face 镜像源或使用代理加速。

基本使用

方法一：运行演示脚本 (命令行)

这是最直接的测试方式，支持批量处理图片文件夹。

使用默认检测器 (ViTdet)：

python demo.py \
    --image_folder <path_to_images> \
    --output_folder <path_to_output> \
    --checkpoint_path ./checkpoints/sam-3d-body-dinov3/model.ckpt \
    --mhr_path ./checkpoints/sam-3d-body-dinov3/assets/mhr_model.pt

使用 SAM3 检测器 (与在线 Playground 对齐)：

python demo.py \
    --image_folder <path_to_images> \
    --output_folder <path_to_output> \
    --checkpoint_path ./checkpoints/sam-3d-body-dinov3/model.ckpt \
    --mhr_path ./checkpoints/sam-3d-body-dinov3/assets/mhr_model.pt \
    --detector_name sam3

请将 <path_to_images> 和 <path_to_output> 替换为您本地的实际路径。

方法二：Python 代码调用

您可以在自己的项目中直接加载模型进行处理：

import cv2
import numpy as np
from notebook.utils import setup_sam_3d_body
from tools.vis_utils import visualize_sample_together

# 1. 初始化估计器 (自动从 Hugging Face 加载模型)
estimator = setup_sam_3d_body(hf_repo_id="facebook/sam-3d-body-dinov3")

# 2. 读取并处理图像
img_bgr = cv2.imread("path/to/image.jpg")
# 注意：模型内部通常需要 RGB 格式输入
outputs = estimator.process_one_image(cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB))

# 3. 可视化并保存结果
rend_img = visualize_sample_together(img_bgr, outputs, estimator.faces)
cv2.imwrite("output.jpg", rend_img.astype(np.uint8))

更多高级用法（如交互式 Notebook 演示、结合 SAM 3D Objects 进行场景对齐）请参考项目中的 notebook/demo_human.ipynb。