SAM 3D Body部署与视频推理教程

文章目录

• • 1. 这篇教程能得到什么
  • 2. 已验证环境
  • 3. 代码和模型地址
  • 4. 下载代码
  • 5. 创建Conda环境
  • 6. 安装PyTorch
  • 7. 安装SAM 3D依赖
  • 8. 下载模型权重
  • • 方法A：官方Hugging Face
    • 方法B：魔搭镜像
  • 9. 先生成YOLO人体提示
  • 10. 单个关键帧推理
  • 11. 扫描整段视频
  • 12. 生成人体网格与教师—TCN综合可视化
  • 13. 怎么判断结果正确
  • 14. 已踩过的坑
  • • Hugging Face下载失败
    • Git LFS占位文件
    • `braceexpand`或`webdataset`缺失
    • 模型提示缺少部分state dict键
    • 三维人体上下颠倒
    • 第一次可视化很慢
  • 15. 性能和边界
  • 16. 最短复现路径

项目	内容
项目名称	mask2world
项目版本	1.3
教程版本	1.0
最后更新	2026-07-16
适用范围	Windows 11、NVIDIA显卡、单张图片与整段视频的SAM 3D Body离线推理

1. 这篇教程能得到什么

按照本文操作，可以把普通单目视频转换成连续的完整三维人体：

原视频 → YOLO人体关键点提供人框 → SAM 3D Body逐帧恢复人体表面和三维骨骼 → 保存连续三维序列 → 输出正面、侧面和原视频同步可视化

SAM 3D Body在本项目中是离线教师，不是最终部署到Orin的实时模型。

2. 已验证环境

本项目实际跑通的机器：

操作系统：Windows 11 显卡：NVIDIA GeForce RTX 4060 Ti 16GB Conda：D:\application\anaconda3 环境名：sam3d_body Python：3.12.13 PyTorch：2.9.0+cu126 TorchVision：0.24.0+cu126 CUDA运行时：12.6 NumPy：2.5.1 OpenCV：5.0.0

Meta官方安装文档推荐Python 3.11。本项目因为本机已有Python 3.12和CUDA 12.6的PyTorch wheel，使用3.12.13也已经完整跑通。

3. 代码和模型地址

官方资源：

• 代码：https://github.com/facebookresearch/sam-3d-body
• 官方DINOv3权重：https://huggingface.co/facebook/sam-3d-body-dinov3
• 官方安装说明：https://github.com/facebookresearch/sam-3d-body/blob/main/INSTALL.md
• 魔搭镜像：https://modelscope.cn/models/facebook/sam-3d-body-dinov3
• 许可证：SAM License，使用前应阅读官方仓库中的LICENSE。

本机已经验证的代码提交：

b5c765a0d89d789985e186d396315e7590887b94

当前实际路径：

SAM 3D代码：E:\Reset\external\sam-3d-body 模型目录：E:\Reset\external\sam-3d-body\checkpoints\sam-3d-body-dinov3 mask2world：E:\Reset\mask2world

模型目录最终必须至少包含：

sam-3d-body-dinov3\ ├─ model.ckpt ├─ model_config.yaml └─ assets\ └─ mhr_model.pt

model.ckpt约2.1GB，mhr_model.pt约696MB。只有几KB的文件通常是Git LFS占位文件，不能推理。

4. 下载代码

在PowerShell中运行：

Set-LocationE:\Reset\external git clone https://github.com/facebookresearch/sam-3d-body E:\Reset\external\sam-3d-body

如果目录已经存在，不要重复克隆，也不要删除原目录。

5. 创建Conda环境

&'D:\application\anaconda3\Scripts\conda.exe'create-n sam3d_body python=3.12 pip-y

以后不必先执行conda activate，可以直接使用环境中的Python：

&'D:\application\anaconda3\envs\sam3d_body\python.exe'--version

6. 安装PyTorch

本机D:\zero_track已经保存匹配Python 3.12和CUDA 12.6的wheel：

&'D:\application\anaconda3\envs\sam3d_body\python.exe'-m pip install `'D:\zero_track\torch-2.9.0+cu126-cp312-cp312-win_amd64.whl'`'D:\zero_track\torchvision-0.24.0+cu126-cp312-cp312-win_amd64.whl'`'D:\zero_track\torchaudio-2.9.0+cu126-cp312-cp312-win_amd64.whl'

检查CUDA：

&'D:\application\anaconda3\envs\sam3d_body\python.exe'-c"import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"

正确结果应包含True和实际显卡名称。

7. 安装SAM 3D依赖

先安装本项目实际用到的依赖：

&'D:\application\anaconda3\envs\sam3d_body\python.exe'-m pip install ` pytorch-lightning pyrender opencv-python yacs scikit-image einops timm dill pandas rich ` hydra-core hydra-submitit-launcher hydra-colorlog pyrootutils webdataset braceexpand ` chump'networkx==3.2.1'roma joblib seaborn wandb appdirs ffmpeg cython jsonlines ` pytest xtcocotools loguru optree fvcore pycocotools tensorboard huggingface_hub

再安装SAM 3D Body代码：

Set-LocationE:\Reset\external\sam-3d-body &'D:\application\anaconda3\envs\sam3d_body\python.exe'-m pip install-e.

本项目没有安装Detectron2人体检测器，也没有安装MoGe相机视场估计器。原因是：

• 人框来自项目已有YOLO姿态结果；
• 当前任务不需要SAM 3D自己重新检测人；
• 没有FOV估计器时模型会使用默认视场，程序能够运行，但绝对相机几何不是精确标定结果。

8. 下载模型权重

方法A：官方Hugging Face

官方仓库需要先申请访问权限。申请通过并登录后：

Set-LocationE:\Reset\external\sam-3d-body hf auth login hf download facebook/sam-3d-body-dinov3--local-dircheckpoints/sam-3d-body-dinov3

方法B：魔搭镜像

Hugging Face访问受阻时，可以检查魔搭上的facebook/sam-3d-body-dinov3镜像：

&'D:\application\anaconda3\envs\sam3d_body\python.exe'-m pip install modelscope &'D:\application\anaconda3\envs\sam3d_body\python.exe'-c"from modelscope import snapshot_download; snapshot_download('facebook/sam-3d-body-dinov3', local_dir=r'E:\Reset\external\sam-3d-body\checkpoints\sam-3d-body-dinov3')"

下载后必须检查发布者、许可证、文件层级和文件大小，不要只看模型名称相同。

检查文件：

Get-Item`'E:\Reset\external\sam-3d-body\checkpoints\sam-3d-body-dinov3\model.ckpt',`'E:\Reset\external\sam-3d-body\checkpoints\sam-3d-body-dinov3\assets\mhr_model.pt'|Select-ObjectFullName,Length

9. 先生成YOLO人体提示

SAM 3D脚本使用项目已有的pose_tracks.npz计算人框。该文件由reset3环境生成。

以参考视频为例：

Set-LocationE:\Reset\mask2world &'D:\application\anaconda3\envs\reset3\python.exe'analyze_kick_unsupervised.py `--video input_data\test_kick.mp4 `--out input_data\kick_yolo26n_unsupervised_v3 `--pose-backend yolo26n `--semantic-name 踢腿

成功后应存在：

input_data\kick_yolo26n_unsupervised_v3\pose_tracks.npz input_data\kick_yolo26n_unsupervised_v3\discovery.json

10. 单个关键帧推理

先跑一帧最容易排查环境问题：

Set-LocationE:\Reset\mask2world &'D:\application\anaconda3\envs\sam3d_body\python.exe'run_sam3d_body_keyframes.py `--video input_data\test_kick.mp4 `--pose input_data\kick_yolo26n_unsupervised_v3\pose_tracks.npz `--output input_data\kick_reference_sam3d_body `--times 20.0

输出包括关键帧图片和包含人体网格、三维关节、相机平移的NPZ文件。

11. 扫描整段视频

参考视频使用10FPS教师采样：

&'D:\application\anaconda3\envs\sam3d_body\python.exe'extract_sam3d_body_sequence.py `--video input_data\test_kick.mp4 `--pose input_data\kick_yolo26n_unsupervised_v3\pose_tracks.npz `--output input_data\kick_reference_sam3d_sequence `--sample-fps 10

test2和test3较长，当前使用5FPS：

&'D:\application\anaconda3\envs\sam3d_body\python.exe'extract_sam3d_body_sequence.py `--video input_data\test2.mp4 `--pose input_data\kick_test2_baseline\pose_tracks.npz `--output input_data\kick_test2_sam3d_sequence `--sample-fps 5 &'D:\application\anaconda3\envs\sam3d_body\python.exe'extract_sam3d_body_sequence.py `--video input_data\test3.mp4 `--pose input_data\kick_test3_baseline\pose_tracks.npz `--output input_data\kick_test3_sam3d_sequence `--sample-fps 5

主要输出：

sam3d_body_sequence.npz 三维教师序列报告.json 整段视频脚部前后深度曲线.jpg

12. 生成人体网格与教师—TCN综合可视化

当前可视化命令会在缺少网格缓存时重新运行SAM 3D Body，然后生成1920×900中文视频：

Set-LocationE:\Reset\mask2world &'D:\application\anaconda3\envs\sam3d_body\python.exe'visualize_sam3d_teacher_and_tcn.py `--names reference test2 test3

输出目录：

input_data\kick_stage_visualization

关键视频：

参考踢腿视频_SAM3D教师与TCN同步可视化.mp4 test2_SAM3D教师与TCN同步可视化.mp4 test3_SAM3D教师与TCN同步可视化.mp4

*_SAM3D人体网格缓存.npz保存完整人体表面。以后只修改文字、颜色或时间轴时会复用缓存，不重新跑模型。

13. 怎么判断结果正确

不要只看“成功帧数”。至少观看可视化并检查：

1. 头在上、脚在下；
2. 正面左右腿与原视频一致；
3. 侧面左方表示朝摄像机；
4. 脚真正向镜头踢出时，侧面深度确实变化；
5. 被裁掉的身体是模型补出的假设，不能当作原图真实观测；
6. 三维人体是否出现骨长突变、前后翻转或脚穿插。

14. 已踩过的坑

Hugging Face下载失败

官方权重需要申请权限和登录。无法下载时先检查魔搭镜像，但必须核对文件大小和许可证。

Git LFS占位文件

文件名存在不代表权重完整。model.ckpt应约2.1GB，不能只有几KB。

braceexpand或webdataset缺失

模型加载链路会间接导入这些包：

&'D:\application\anaconda3\envs\sam3d_body\python.exe'-m pip install braceexpand webdataset

模型提示缺少部分state dict键

当前官方代码和权重组合会打印一批missing keys，本项目实测仍能正常输出完整人体。判断是否真正失败，应看是否产生pred_vertices和pred_keypoints_3d，不能只看警告文字。

三维人体上下颠倒

这批SAM 3D输出的Y坐标已经与画面方向一致。绘图时再次取反会导致头在下、脚在上。当前visualize_sam3d_teacher_and_tcn.py已经按实际画面修正。

第一次可视化很慢

第一次要重新恢复所有人体网格并压缩缓存；以后复用缓存只需要重新编码视频。

15. 性能和边界

• 模型约12.85亿参数，加载显存约3.54GB；完整运行还需要输入和中间特征显存。
• 4060 Ti上预热后约0.18～0.19秒一帧。
• 当前是逐帧模型，视频时间连续性来自后续分析，不是模型内部视频跟踪。
• 单目三维仍有前后歧义和尺度不确定性。
• 它只恢复人体，不理解车辆、垃圾桶、球、地面接触和动作目的。
• 本项目把它作为离线教师，Orin只部署蒸馏后的小型TCN。

16. 最短复现路径

已经有环境、代码、权重和pose_tracks.npz时，只需：

Set-LocationE:\Reset\mask2world &'D:\application\anaconda3\envs\sam3d_body\python.exe'extract_sam3d_body_sequence.py `--video input_data\test3.mp4 `--pose input_data\kick_test3_baseline\pose_tracks.npz `--output input_data\kick_test3_sam3d_sequence `--sample-fps 5

若动作教师和TCN输出也已存在，再运行：

&'D:\application\anaconda3\envs\sam3d_body\python.exe'visualize_sam3d_teacher_and_tcn.py--names test3