MeTRAbs 绝对 3D 人体姿态估计器

本仓库包含以下论文的代码：

MeTRAbs：用于绝对 3D 人体姿态估计的度量尺度截断鲁棒热图
作者：伊斯特万·萨兰迪、蒂姆·林德、凯·O·阿拉斯、巴斯蒂安·莱贝
IEEE 生物特征、行为与身份科学汇刊（T-BIOM），自动人脸与手势识别 2020 年精选最佳成果。

该仓库已更新至改进版本，应用于以下论文：

利用几何感知自编码器桥接骨骼格式，从数十个数据集学习 3D 人体姿态估计
作者：伊斯特万·萨兰迪、亚历山大·赫尔曼斯、巴斯蒂安·莱贝
IEEE/CVF 计算机视觉应用冬季会议（WACV），2023 年。

新闻

• [2023-08-02] 大规模代码库重构，模型如我们在WACV'23论文中所述，多个组件被拆分到独立仓库，新增 PyTorch 推理支持等。
• [2021-12-03] 增加了新的骨干网络，包括从 ResNet-18 到 ResNet-152 的 ResNet 系列。
• [2021-10-19] 发布了基于 EfficientNetV2 的最新最优模型以及使用 MobileNetV3 的超快速模型，简化了API，支持多种骨骼约定，可处理径向/切向畸变，改进了抗锯齿处理、合理性过滤等功能。
• [2021-10-19] 整个代码库迁移到 TensorFlow 2 和 Keras。
• [2020-11-19] 在 IEEE 自动人脸与手势识别会议（FG'20）上作口头报告（演讲视频和幻灯片)。
• [2020-11-16] 训练与评估代码现已发布，并附带数据集预处理脚本！代码和模型升级至 Tensorflow 2。
• [2020-10-06] 期刊论文被接受发表于 IEEE 生物特征、行为与身份科学汇刊（T-BIOM），FG 特别期最佳论文。
• [2020-08-23] 在 ECCV2020 的 3DPW 工作坊上作了简短报告（幻灯片）。
• [2020-08-06] 我们的方法赢得了**3DPW 挑战赛**。

推理代码

我们发布了独立的 TensorFlow 模型（SavedModel），以便于下游研究中的应用。加载模型后，您可以在一行 Python 代码中进行推理，无需依赖本代码库。您可以在Google Colab中试用。

使用概要

import tensorflow as tf
import tensorflow_hub as tfhub

model = tfhub.load('https://bit.ly/metrabs_l')
image = tf.image.decode_jpeg(tf.io.read_file('img/test_image_3dpw.jpg'))
pred = model.detect_poses(image)
pred['boxes'], pred['poses2d'], pred['poses3d']

更多示例请参阅demos/文件夹。

注意：由于所用训练数据集的许可限制，这些模型仅可用于非商业用途。

或者，您可以尝试实验性的 PyTorch 版本：

wget -O - https://bit.ly/metrabs_l_pt | tar -xzvf -
python -m metrabs_pytorch.scripts.demo_image --model-dir metrabs_eff2l_384px_800k_28ds_pytorch --image img/test_image_3dpw.jpg

演示

• ./demo.py 可自动下载模型，对示例图像进行预测，并使用 Matplotlib 或PoseViz（若已安装）显示结果。
• ./demo_video.py filepath-or-url-to-video.mp4 可对视频进行推理。

文档

• 带有示例的使用指南
• 完整 API 参考

功能概览

• 通过关键字参数 skeleton 支持多种骨骼约定（如 COCO、SMPL、H36M）。
• 同时支持多张图像（批量）和单张图像预测。
• 背后采用先进的并行化裁剪逻辑：
  • 通过图像金字塔和超采样实现抗锯齿处理，以及伽玛校正缩放。
  • GPU 加速的针孔透视（单应变换）及径向/切向镜头畸变校正。
• 估计结果以3D 世界坐标系（提供标定信息时）和2D 像素坐标系返回。
• 内置可配置的测试时增强（TTA），包括旋转、翻转和亮度调整（关键字参数 num_aug 设置每次检测的 TTA 图像数量）。
• 自动抑制不合理姿态，并在 3D 姿态层面进行非极大值抑制（可关闭）。
• 多种骨干网络，具有不同的速度-精度权衡（EfficientNetV2、MobileNetV3）。

训练与评估

请参阅 docs 目录。

BibTeX

如果您在研究中使用了本工作，请按以下格式引用：

@article{sarandi2021metrabs,
  title={{MeTRAbs:} 基于度量尺度且对截断鲁棒的热图用于绝对3{D}人体姿态估计},
  author={S\'ar\'andi, Istv\'an and Linder, Timm and Arras, Kai O. and Leibe, Bastian},
  journal={IEEE生物特征、行为与身份科学汇刊},
  year={2021},
  volume={3},
  number={1},
  pages={16-30},
  doi={10.1109/TBIOM.2020.3037257}
}

上述论文是 FG'2020 会议论文的扩展期刊版本：

@inproceedings{Sarandi20FG,
  title={基于度量尺度且对截断鲁棒的热图用于3{D}人体姿态估计},
  author={S\'ar\'andi, Istv\'an and Linder, Timm and Arras, Kai O. and Leibe, Bastian},
  booktitle={IEEE国际自动人脸与手势识别会议},
  pages={677-684},
  year={2020}
}

较新的大规模模型对应于 WACV'23 论文：

@inproceedings{Sarandi2023dozens,
    author = {S\'ar\'andi, Istv\'an and Hermans, Alexander and Leibe, Bastian},
    title = {利用几何感知自编码器桥接骨骼格式，从数十个数据集学习{3D}人体姿态估计},
    booktitle = {IEEE/CVF冬季计算机视觉应用会议（WACV）},
    year = {2023}
} 

联系方式

本仓库中的代码由 István Sárándi（亚琛工业大学）编写，除非另有说明。

您有任何问题或反馈吗？请发送邮件至 sarandi@vision.rwth-aachen.de！

MeTRAbs 快速上手指南

MeTRAbs 是一个用于绝对 3D 人体姿态估计的开源工具，支持从单张图像或视频中提取具有真实尺度（Metric-Scale）的 3D 骨架数据。它具备抗截断、多骨架格式支持（如 COCO, SMPL, H36M）以及高性能推理等特点。

环境准备

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

• 操作系统: Linux 或 macOS (Windows 需通过 WSL2 运行)
• Python: 3.8 或更高版本
• GPU: 推荐使用 NVIDIA GPU 以加速推理（可选，CPU 亦可运行但速度较慢）
• 核心依赖:
  • TensorFlow 2.x (官方主推版本)
  • PyTorch (实验性支持)
  • tensorflow-hub
  • opencv-python (用于视频处理)
  • matplotlib (用于可视化)

建议创建一个独立的虚拟环境：

python -m venv metrabs_env
source metrabs_env/bin/activate  # Windows 用户使用: metrabs_env\Scripts\activate

安装基础依赖：

pip install tensorflow tensorflow-hub opencv-python matplotlib
# 如果使用 PyTorch 版本，请额外安装：
# pip install torch torchvision

注意：由于网络原因，国内用户安装 TensorFlow 或下载模型时可能较慢。建议使用清华源或阿里源加速 pip 安装： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tensorflow tensorflow-hub

安装步骤

MeTRAbs 的核心优势在于提供了独立的 SavedModel，您可以直接通过 TensorFlow Hub 加载预训练模型，无需克隆整个代码库即可进行推理。

方案 A：直接使用 TensorFlow Hub（推荐）

无需本地安装源码，直接在 Python 中加载云端模型。

1. 确保已安装 tensorflow 和 tensorflow-hub。
2. 模型将自动下载并缓存到本地（首次运行需联网）。

方案 B：使用 PyTorch 实验版本

如果您更习惯使用 PyTorch，可以下载转换后的模型文件。

# 下载并解压 PyTorch 模型
wget -O - https://bit.ly/metrabs_l_pt | tar -xzvf -

# 克隆仓库以获取演示脚本（仅用于运行 demo 脚本，非必须依赖）
git clone https://github.com/isarandi/metrabs.git
cd metrabs

基本使用

1. TensorFlow 版本（单行推理）

这是最简单的使用方式。加载模型后，只需一行代码即可完成从图像读取到 3D 姿态预测的全过程。

import tensorflow as tf
import tensorflow_hub as tfhub

# 加载预训练模型 (自动下载)
# 可选模型标识：metrabs_l (大模型), metrabs_m (中模型), metrabs_s (小模型)
model = tfhub.load('https://bit.ly/metrabs_l')

# 读取并解码图像
image = tf.image.decode_jpeg(tf.io.read_file('img/test_image_3dpw.jpg'))

# 执行推理
pred = model.detect_poses(image)

# 输出结果
# boxes: 检测框坐标
# poses2d: 2D 像素坐标
# poses3d: 3D 世界坐标 (米为单位)
print(pred['boxes'], pred['poses2d'], pred['poses3d'])

2. PyTorch 版本（命令行演示）

如果您使用了方案 B 安装了 PyTorch 模型，可以通过命令行直接对图片进行测试：

python -m metrabs_pytorch.scripts.demo_image --model-dir metrabs_eff2l_384px_800k_28ds_pytorch --image img/test_image_3dpw.jpg

3. 进阶功能提示

• 视频处理: 使用仓库中的 demos/demo_video.py 脚本，传入视频路径或 URL 即可处理视频流。
• 多骨架格式: 在调用 detect_poses 时，可通过参数 skeleton 指定输出格式（例如 'coco', 'smpl', 'h36m'）。
• 测试时增强 (TTA): 通过设置 num_aug 参数开启旋转、翻转等增强策略以提高精度。

许可说明：由于训练数据集的许可限制，下载的预训练模型仅限非商业用途使用。