人类视觉模型的基础

Rawal Khirodkar · Timur Bagautdinov · Julieta Martinez · Su Zhaoen · Austin James
Peter Selednik . Stuart Anderson . Shunsuke Saito

ECCV 2024 - 最佳论文候选

Sapiens 提供了一套全面的人类中心视觉任务解决方案（例如，2D 姿态估计、部位分割、深度、法线等）。该模型系列在 3 亿张野外采集的人类图像上进行了预训练，并在非约束条件下表现出色的泛化能力。这些模型还专为提取高分辨率特征而设计，原生以 1024×1024 的图像分辨率和 16 像素的补丁大小进行训练。

🚀 快速入门

克隆仓库

git clone https://github.com/facebookresearch/sapiens.git
export SAPIENS_ROOT=/path/to/sapiens

推荐：精简安装（仅推理）

对于主要为了在推理模式下运行现有模型而搭建环境的用户，我们推荐使用 Sapiens-Lite 安装。
此设置提供了优化的推理性能（快 4 倍），且依赖项极少（仅 PyTorch + numpy + cv2）。

完整安装

若要复现我们的完整训练环境，请运行提供的安装脚本。
这将创建一个名为 sapiens 的新 conda 环境，并安装所有必要的依赖项。

cd $SAPIENS_ROOT/_install
./conda.sh

请从 hugging-face 下载原始检查点。
您可以选择性地只下载感兴趣的检查点。
将 $SAPIENS_CHECKPOINT_ROOT 设置为 sapiens_host 文件夹的路径。请按照以下目录结构放置检查点：

sapiens_host/
├── detector/
│   └── checkpoints/
│       └── rtmpose/
├── pretrain/
│   └── checkpoints/
│       ├── sapiens_0.3b/
            ├── sapiens_0.3b_epoch_1600_clean.pth
│       ├── sapiens_0.6b/
            ├── sapiens_0.6b_epoch_1600_clean.pth
│       ├── sapiens_1b/
│       └── sapiens_2b/
├── pose/
   └── checkpoints/
      ├── sapiens_0.3b/
└── seg/
└── depth/
└── normal/

🌟 人类中心视觉任务

我们针对多项人类中心视觉任务对 Sapiens 进行了微调。请查看下面的列表。

• 图像编码器 ^[精简]

• 姿态估计 ^[精简]

• 身体部位分割 ^[精简]

• 深度估计 ^[精简]

• 表面法线估计 ^[精简]

🎯 微调 Sapiens 的简单步骤

微调我们的模型非常简单！以下是针对以下任务的详细训练指南。

• 姿态估计

• 身体部位分割

• 深度估计

• 表面法线估计

📈 定量评估

• 姿态估计

🤝 致谢、支持与贡献

我们感谢 OpenMMLab 的工作，本项目从中受益良多。
如有任何问题或疑问，请在仓库中提交 issue。
详情请参阅 贡献说明 和 行为准则。

许可证

本项目采用 LICENSE 许可证。
源自开源项目的部分代码则采用 Apache 2.0 许可证。

📚 引用

如果您在研究中使用 Sapiens，请考虑引用我们的工作。

@article{khirodkar2024sapiens,
  title={Sapiens：人类视觉模型的基础},
  author={Khirodkar, Rawal 和 Bagautdinov, Timur 和 Martinez, Julieta 和 Zhaoen, Su 和 James, Austin 和 Selednik, Peter 和 Anderson, Stuart 和 Saito, Shunsuke},
  journal={arXiv 预印本 arXiv:2408.12569},
  year={2024}
}

Sapiens 快速上手指南

Sapiens 是一套专注于人体视觉任务的基础模型系列，支持 2D 姿态估计、身体部位分割、深度估计和法线估计等任务。该模型在 3 亿张野生人体图像上预训练，原生支持 1024x1024 高分辨率输入，具有极强的泛化能力。

环境准备

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• 硬件要求: NVIDIA GPU (建议显存 16GB 以上以运行大尺寸模型)
• 软件依赖:
  • Python 3.8+
  • CUDA 11.8+ (根据 PyTorch 版本匹配)
  • Git
  • Conda (推荐用于环境管理)

注意：本项目由 Meta Reality Labs 开发，国内用户访问 HuggingFace 下载模型时可能需要配置网络代理或使用镜像站。

安装步骤

1. 克隆仓库

首先将代码库克隆到本地并设置环境变量：

git clone https://github.com/facebookresearch/sapiens.git
export SAPIENS_ROOT=$(pwd)/sapiens

2. 选择安装方式

方案 A：轻量级安装（推荐仅推理用户）

如果您只需要运行现有模型进行推理，推荐使用 Lite 版本。该方案依赖极少（仅需 PyTorch + numpy + cv2），推理速度提升约 4 倍。

请参考官方轻量版文档进行安装：

# 进入 lite 目录查看具体安装说明
cd $SAPIENS_ROOT/lite
# 具体命令请参阅 lite/README.md

方案 B：完整安装（包含训练与微调）

如果您需要复现训练流程或进行微调，请运行以下脚本创建名为 sapiens 的 Conda 环境：

cd $SAPIENS_ROOT/_install
./conda.sh

激活环境：

conda activate sapiens

3. 下载预训练权重

从 HuggingFace 下载所需的检查点文件。 (国内用户若下载缓慢，可尝试使用 HuggingFace 镜像站如 hf-mirror.com)

假设您将下载的权重存放在 $SAPIENS_CHECKPOINT_ROOT 目录下，请确保目录结构如下：

sapiens_host/
├── detector/
│   └── checkpoints/
│       └── rtmpose/
├── pretrain/
│   └── checkpoints/
│       ├── sapiens_0.3b/
│       │   └── sapiens_0.3b_epoch_1600_clean.pth
│       ├── sapiens_0.6b/
│       │   └── sapiens_0.6b_epoch_1600_clean.pth
│       ├── sapiens_1b/
│       └── sapiens_2b/
├── pose/
│   └── checkpoints/
│       └── sapiens_0.3b/
├── seg/
├── depth/
└── normal/

设置环境变量指向该目录：

export SAPIENS_CHECKPOINT_ROOT=/path/to/sapiens_host

基本使用

Sapiens 提供了针对不同任务的独立脚本。以下是以最常用的 姿态估计 (Pose Estimation) 为例的基本使用流程。

运行姿态估计推理

确保已激活环境并设置了正确的检查点路径，运行以下命令（具体参数请参考 docs/POSE_README.md）：

cd $SAPIENS_ROOT

# 示例：运行姿态估计推理
# 请根据实际下载的模型版本调整 config 和 checkpoint 路径
python tools/infer_pose.py \
    --config configs/pose/sapiens_0.3b.yaml \
    --checkpoint $SAPIENS_CHECKPOINT_ROOT/pose/checkpoints/sapiens_0.3b/latest.pth \
    --input assets/demo.jpg \
    --output_dir outputs/pose

其他任务快速入口

• 身体部位分割: 参考 docs/SEG_README.md
• 深度估计: 参考 docs/DEPTH_README.md
• 表面法线估计: 参考 docs/NORMAL_README.md

所有任务均支持高分辨率输入，建议在推理时保持图片原始分辨率或调整为 1024x1024 以获得最佳效果。