文章目录1. 这篇教程能得到什么2. 已验证环境3. 代码和模型地址4. 下载代码5. 创建Conda环境6. 安装PyTorch7. 安装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 CondaD:\application\anaconda3 环境名sam3d_body Python3.12.13 PyTorch2.9.0cu126 TorchVision0.24.0cu126 CUDA运行时12.6 NumPy2.5.1 OpenCV5.0.0Meta官方安装文档推荐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 mask2worldE:\Reset\mask2world模型目录最终必须至少包含sam-3d-body-dinov3\ ├─ model.ckpt ├─ model_config.yaml └─ assets\ └─ mhr_model.ptmodel.ckpt约2.1GBmhr_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.execreate-n sam3d_body python3.12 pip-y以后不必先执行conda activate可以直接使用环境中的PythonD:\application\anaconda3\envs\sam3d_body\python.exe--version6. 安装PyTorch本机D:\zero_track已经保存匹配Python 3.12和CUDA 12.6的wheelD:\application\anaconda3\envs\sam3d_body\python.exe-m pip install D:\zero_track\torch-2.9.0cu126-cp312-cp312-win_amd64.whlD:\zero_track\torchvision-0.24.0cu126-cp312-cp312-win_amd64.whlD:\zero_track\torchaudio-2.9.0cu126-cp312-cp312-win_amd64.whl检查CUDAD:\application\anaconda3\envs\sam3d_body\python.exe-cimport 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 chumpnetworkx3.2.1roma 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-cfrom modelscope import snapshot_download; snapshot_download(facebook/sam-3d-body-dinov3, local_dirrE:\Reset\external\sam-3d-body\checkpoints\sam-3d-body-dinov3)下载后必须检查发布者、许可证、文件层级和文件大小不要只看模型名称相同。检查文件Get-ItemE:\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,Length9. 先生成YOLO人体提示SAM 3D脚本使用项目已有的pose_tracks.npz计算人框。该文件由reset3环境生成。以参考视频为例Set-LocationE:\Reset\mask2world D:\application\anaconda3\envs\reset3\python.exeanalyze_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.json10. 单个关键帧推理先跑一帧最容易排查环境问题Set-LocationE:\Reset\mask2world D:\application\anaconda3\envs\sam3d_body\python.exerun_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.exeextract_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 10test2和test3较长当前使用5FPSD:\application\anaconda3\envs\sam3d_body\python.exeextract_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.exeextract_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 整段视频脚部前后深度曲线.jpg12. 生成人体网格与教师—TCN综合可视化当前可视化命令会在缺少网格缓存时重新运行SAM 3D Body然后生成1920×900中文视频Set-LocationE:\Reset\mask2world D:\application\anaconda3\envs\sam3d_body\python.exevisualize_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. 怎么判断结果正确不要只看“成功帧数”。至少观看可视化并检查头在上、脚在下正面左右腿与原视频一致侧面左方表示朝摄像机脚真正向镜头踢出时侧面深度确实变化被裁掉的身体是模型补出的假设不能当作原图真实观测三维人体是否出现骨长突变、前后翻转或脚穿插。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.180.19秒一帧。当前是逐帧模型视频时间连续性来自后续分析不是模型内部视频跟踪。单目三维仍有前后歧义和尺度不确定性。它只恢复人体不理解车辆、垃圾桶、球、地面接触和动作目的。本项目把它作为离线教师Orin只部署蒸馏后的小型TCN。16. 最短复现路径已经有环境、代码、权重和pose_tracks.npz时只需Set-LocationE:\Reset\mask2world D:\application\anaconda3\envs\sam3d_body\python.exeextract_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.exevisualize_sam3d_teacher_and_tcn.py--names test3
文章目录1. 这篇教程能得到什么2. 已验证环境3. 代码和模型地址4. 下载代码5. 创建Conda环境6. 安装PyTorch7. 安装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 CondaD:\application\anaconda3 环境名sam3d_body Python3.12.13 PyTorch2.9.0cu126 TorchVision0.24.0cu126 CUDA运行时12.6 NumPy2.5.1 OpenCV5.0.0Meta官方安装文档推荐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 mask2worldE:\Reset\mask2world模型目录最终必须至少包含sam-3d-body-dinov3\ ├─ model.ckpt ├─ model_config.yaml └─ assets\ └─ mhr_model.ptmodel.ckpt约2.1GBmhr_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.execreate-n sam3d_body python3.12 pip-y以后不必先执行conda activate可以直接使用环境中的PythonD:\application\anaconda3\envs\sam3d_body\python.exe--version6. 安装PyTorch本机D:\zero_track已经保存匹配Python 3.12和CUDA 12.6的wheelD:\application\anaconda3\envs\sam3d_body\python.exe-m pip install D:\zero_track\torch-2.9.0cu126-cp312-cp312-win_amd64.whlD:\zero_track\torchvision-0.24.0cu126-cp312-cp312-win_amd64.whlD:\zero_track\torchaudio-2.9.0cu126-cp312-cp312-win_amd64.whl检查CUDAD:\application\anaconda3\envs\sam3d_body\python.exe-cimport 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 chumpnetworkx3.2.1roma 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-cfrom modelscope import snapshot_download; snapshot_download(facebook/sam-3d-body-dinov3, local_dirrE:\Reset\external\sam-3d-body\checkpoints\sam-3d-body-dinov3)下载后必须检查发布者、许可证、文件层级和文件大小不要只看模型名称相同。检查文件Get-ItemE:\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,Length9. 先生成YOLO人体提示SAM 3D脚本使用项目已有的pose_tracks.npz计算人框。该文件由reset3环境生成。以参考视频为例Set-LocationE:\Reset\mask2world D:\application\anaconda3\envs\reset3\python.exeanalyze_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.json10. 单个关键帧推理先跑一帧最容易排查环境问题Set-LocationE:\Reset\mask2world D:\application\anaconda3\envs\sam3d_body\python.exerun_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.exeextract_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 10test2和test3较长当前使用5FPSD:\application\anaconda3\envs\sam3d_body\python.exeextract_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.exeextract_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 整段视频脚部前后深度曲线.jpg12. 生成人体网格与教师—TCN综合可视化当前可视化命令会在缺少网格缓存时重新运行SAM 3D Body然后生成1920×900中文视频Set-LocationE:\Reset\mask2world D:\application\anaconda3\envs\sam3d_body\python.exevisualize_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. 怎么判断结果正确不要只看“成功帧数”。至少观看可视化并检查头在上、脚在下正面左右腿与原视频一致侧面左方表示朝摄像机脚真正向镜头踢出时侧面深度确实变化被裁掉的身体是模型补出的假设不能当作原图真实观测三维人体是否出现骨长突变、前后翻转或脚穿插。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.180.19秒一帧。当前是逐帧模型视频时间连续性来自后续分析不是模型内部视频跟踪。单目三维仍有前后歧义和尺度不确定性。它只恢复人体不理解车辆、垃圾桶、球、地面接触和动作目的。本项目把它作为离线教师Orin只部署蒸馏后的小型TCN。16. 最短复现路径已经有环境、代码、权重和pose_tracks.npz时只需Set-LocationE:\Reset\mask2world D:\application\anaconda3\envs\sam3d_body\python.exeextract_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.exevisualize_sam3d_teacher_and_tcn.py--names test3
