SAM 3D Body

SAM 3D Body 是 Meta 的可提示模型，它从单张图像加人体框恢复出包含手和脚在内的全身 3D 网格。LibreYOLO 封装的是上游的包，而不是把它移植过来。

任务: mesh
尺寸: d3, h at 512 px
安装: pip install libreyolo
支持层级: 仅推理，自 v 起。仅支持预测、验证和导出。训练相关的功能不适用。
上游: SAM 3D Body，由 Meta Platforms, Inc. 发布，采用 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。从来不构造这个家族的用户永远不会触发这个 import，也永远不会碰到 SAM License。这个家族既没有接进 LibreYOLO() 工厂函数，也没有接进 libreyolo predict CLI 命令；LibreSAM3DBody 是唯一的入口。

预测

Python

from libreyolo import SAMPLE_IMAGEfrom libreyolo.models.sam3dbody import LibreSAM3DBody # 这个家族没有注册到 LibreYOLO() 工厂函数里，所以要直接构造。# model_path=None 才会触发受限（gated）的 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 检测器、# 一个普通的可调用对象，或者一个 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 是一个 Meshes 负载，和 result.boxes 按行对齐（检测到的每个人一行）：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 尚未为网格这个任务定义导出图的约定，其中也包括在 PyTorch 之外怎么表示 MHR 的参数布局。

检查点

这个家族已发布的全部权重文件。

文件	输入（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）是 Meta 单独发布的，采用 Apache-2.0 许可。LibreYOLO 在运行时从 MHR 自己的公开发布里拉取它的 TorchScript 资源，并缓存到本地；这个文件不由 LibreYOLO 镜像，适用的是它自己的 Apache-2.0 条款，而不是 SAM License。

引用

@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 上提供的引用块。