ViTPose 2D 人体关键点数据集准备与使用全指南:COCO / MPII / AIC / CrowdPose 等八大数据集详解
ViTPose 2D 人体关键点数据集准备与使用全指南:COCO / MPII / AIC / CrowdPose 等八大数据集详解
本文是面向 ViTPose(基于 MMPose 的姿态估计框架)的 2D 人体关键点任务数据集准备指南。文章以 docs/zh_cn/tasks/2d_body_keypoint.md 为骨架,逐数据集讲解官方数据目录结构、标注文件来源、检测框结果文件的作用,并结合仓库源码(数据集类实现、基础配置与 ViTPose 训练配置)说明这些数据如何被加载、预处理与评估。读完本文,你将能够按官方规范在 ViTPose 中完整准备 COCO、MPII、MPII-TRB、AIC、CrowdPose、OCHuman、MHP、PoseTrack18 与 sub-JHMDB 九个数据集,并理解它们与 top-down 姿态估计训练/评估流程的对接方式。
一、总览:ViTPose 支持的 2D 人体关键点数据集
在 ViTPose 中,所有 2D 人体关键点数据集的根目录统一约定放置在 $MMPOSE/data 下($MMPOSE 即本仓库根目录)。如果你的文件结构比较特殊,需要在对应配置文件中修改 data_root、ann_file、img_prefix 等路径参数。
MMPose(ViTPose 所基于的框架)为 2D 人体关键点任务支持以下数据集:
- 图像类:COCO、MPII、MPII-TRB、AI Challenger(AIC)、CrowdPose、OCHuman、MHP
- 视频类:PoseTrack18、sub-JHMDB
这些数据集的元信息(关键点名称、骨架连接、颜色、权重、sigmas 等)都定义在 configs/base/datasets/ 目录下对应的 *_info.py 或 dataset_info 配置中,并在训练配置中通过 _base_ 继承引用。例如 COCO 的关键点定义见 configs/base/datasets/coco.py,MPII 见 configs/base/datasets/mpii.py。
对应的数据集加载类位于 mmpose/datasets/datasets/top_down/ 目录下。从源码结构看,多数 top-down 数据集(AIC、CrowdPose、OCHuman、MHP、PoseTrack18、sub-JHMDB)都直接继承 TopDownCocoDataset(见 topdown_coco_dataset.py),因此共享同一套 COCO 风格的标注加载与 mAP 评估逻辑;而 MPII 与 MPII-TRB 则直接继承 Kpt2dSviewRgbImgTopDownDataset,使用各自独立的加载与 PCKh 评估逻辑。
二、COCO:多人姿态估计的事实标准基准
COCO(Microsoft COCO: Common Objects in Context, ECCV'2014)是 2D 人体关键点研究中最常用的基准数据集,也是 ViTPose 论文中报告核心结果(COCO val2017 与 test-dev 上的 AP)的主战场。
2.1 下载与目录结构
请从 COCO 官网的下载页获取数据文件。注意:2017 Train/Val 对于 COCO 关键点的训练和评估是必要的。此外,还需要:
- COCO val2017 的人体检测结果(用于复现多人姿态估计结果):由 HRNet-Human-Pose-Estimation 项目提供,仓库使用其中的
COCO_val2017_detections_AP_H_56_person.json; - COCO test-dev 评估用 image-info(
person_keypoints_test-dev-2017.json):可选,仅当需要在 COCO'2017 test-dev 上评估时使用。
将数据置于 $MMPOSE/data 下,整理为如下结构:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── coco
│-- annotations
│ │-- person_keypoints_train2017.json
│ |-- person_keypoints_val2017.json
│ |-- person_keypoints_test-dev-2017.json
|-- person_detection_results
| |-- COCO_val2017_detections_AP_H_56_person.json
| |-- COCO_test-dev2017_detections_AP_H_609_person.json
│-- train2017
│ │-- 000000000009.jpg
│ │-- 000000000025.jpg
│ │-- 000000000030.jpg
│ │-- ...
`-- val2017
│-- 000000000139.jpg
│-- 000000000285.jpg
│-- 000000000632.jpg
│-- ...
仓库测试数据目录 tests/data/coco/ 中保留了 test_coco.json、test_coco_det_AP_H_56.json、test_coco_wholebody.json 及若干示例图片,可作为理解标注格式的参考。
2.2 COCO 的 17 个关键点定义
TopDownCocoDataset 的 docstring(见 topdown_coco_dataset.py)完整列出了 COCO 关键点索引:
0: 'nose', 1: 'left_eye', 2: 'right_eye', 3: 'left_ear', 4: 'right_ear',
5: 'left_shoulder', 6: 'right_shoulder', 7: 'left_elbow', 8: 'right_elbow', 9: 'left_wrist',
10: 'right_wrist', 11: 'left_hip', 12: 'right_hip', 13: 'left_knee', 14: 'right_knee',
15: 'left_ankle', 16: 'right_ankle'
在 configs/base/datasets/coco.py 中,每个关键点都包含 name、id、color、type(upper/lower)与 swap(水平翻转配对)信息;skeleton_info 定义了 19 条骨架连接;joint_weights 给出各关节在损失中的权重(肘/腕/膝/踝等远端关节权重更高);sigmas 则是 OKS(Object Keypoint Similarity)评估所需的各关节归一化标准差。这些元信息正是 ViTPose 配置文件 ViTPose_base_coco_256x192.py 中 dataset_info={{_base_.dataset_info}} 引用的内容。
2.3 训练与评估如何消费数据
从 ViTPose_base_coco_256x192.py 可以看到 COCO 在 ViTPose 中的完整使用方式:
- 训练集使用
ann_file: data/coco/annotations/person_keypoints_train2017.json,img_prefix: data/coco/train2017/; - 验证/测试集使用
person_keypoints_val2017.json,img_prefix: data/coco/val2017/; data_cfg中image_size=[192, 256]、heatmap_size=[48, 64],输出 17 通道热图;evaluation = dict(interval=10, metric='mAP', save_best='AP')表明使用 COCO 官方 mAP(AP/AP.5/AP.75/AR 系列指标)评估。
在推理阶段,若使用外部检测框(而非 GT 框),data_cfg 中的 use_gt_bbox=False、bbox_file='data/coco/person_detection_results/COCO_val2017_detections_AP_H_56_person.json'、det_bbox_thr=0.0 等参数会生效。源码 topdown_coco_dataset.py 中的 _load_coco_person_detection_results 会读取该 JSON 文件、过滤 category_id != 1 与低分框,再经 _xywh2cs 转为 center/scale 作为单人裁剪框。
评估阶段(topdown_coco_dataset.py)会对每个检测框做 rescoring(关键点平均分 × 检测框分),再执行 OKS NMS(soft_nms=False 时用 oks_nms,阈值 oks_thr=0.9,关键点可见阈值 vis_thr=0.2),最后通过 COCOeval(xtcocotools)输出 AP 系列指标。
三、MPII:单人与多人姿态估计经典基准
MPII(2D Human Pose Estimation: New Benchmark and State of the Art Analysis, CVPR'2014)包含约 2.5 万张图像、4 万人体实例,共 16 个关键点。
3.1 下载与目录结构
从 MPII 官网下载数据集图像;仓库使用官方标注转换后的 JSON 格式,需另下载 mpii_annotations 压缩包。整理为:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── mpii
|── annotations
| |── mpii_gt_val.mat
| |── mpii_test.json
| |── mpii_train.json
| |── mpii_trainval.json
| `── mpii_val.json
`── images
|── 000001163.jpg
|── 000003072.jpg
注意 mpii_gt_val.mat 是官方验证集标注,用于 PCKh 评估;测试样例见 tests/data/mpii/。
3.2 预测结果格式转换工具 mat2json
在训练和推理过程中,MPII 的预测结果默认保存为 .mat 格式(源码见 topdown_mpii_dataset.py,评估时会 savemat(pred_file, mdict={'preds': preds}) 写出 pred.mat)。仓库提供了 mat2json 工具将其转换为更易读的 JSON 格式:
python tools/dataset/mat2json ${PRED_MAT_FILE} ${GT_JSON_FILE} ${OUTPUT_PRED_JSON_FILE}
例如:
python tools/dataset/mat2json work_dirs/res50_mpii_256x256/pred.mat data/mpii/annotations/mpii_val.json pred.json
该工具的实现位于 tools/dataset/mat2json.py:用 scipy.io.loadmat 读取 preds,从 GT JSON 中取图像名,并将预测坐标写入每条标注的 joints 字段,最终输出符合 MPII 评估格式的 annotations 结构。
3.3 MPII 的加载与评估特性
MPII 与 COCO 的关键差异体现在源码 topdown_mpii_dataset.py 中:
- 1-based 坐标修正:MPII 采用 Matlab 风格 1-based 索引,加载时需
center = center - 1、joints_3d[:, 0:2] = joints[:, 0:2] - 1; - 裁剪框微调:
center[1] = center[1] + 15 * scale[1]且scale = scale * 1.25,以避免裁剪掉四肢; - PCKh 评估:以头部尺寸(headbox 对角线 × 0.6)为归一化尺度,阈值 0.5 判定命中,输出 Head、Shoulder、Elbow、Wrist、Hip、Knee、Ankle 各部位 PCKh 与总体 PCKh、PCKh@0.1。
对应 ViTPose 配置 ViTPose_base_mpii_256x192.py 中,评估配置为 metric='PCKh'、save_best='PCKh',data_cfg 中 use_gt_bbox=True(MPII 使用 GT 裁剪框)、输出 16 通道热图。MPII 的 16 个关键点索引(right_ankle → left_wrist,含 pelvis、thorax、upper_neck、head_top)同样定义在 configs/base/datasets/mpii.py。
四、MPII-TRB:稠密化的三元组人体表示
MPII-TRB(TRB: A Novel Triplet Representation for Understanding 2D Human Body, ICCV'2019)在 MPII 基础上增加了稠密标注:除 14 个标准关节外,还包含 right_neck/left_neck、各关节的 medial_*/lateral_* 中间点,共 40 个关键点(完整索引见 topdown_mpii_trb_dataset.py)。
4.1 下载与目录结构
图像直接复用 MPII 数据集,另需下载 mpii_trb_annotations 标注压缩包:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── mpii
|── annotations
| |── mpii_trb_train.json
| |── mpii_trb_val.json
`── images
|── 000001163.jpg
|── 000003072.jpg
4.2 配置与实现要点
参考配置 res50_mpii_trb_256x256.py:channel_cfg 中 num_output_channels=40、dataset_joints=40,评估指标为 PCKh。由于 40 关节的稠密标注中多数是成对出现的 medial/lateral 点,其 dataset_info(见 configs/base/datasets/mpii_trb.py)中的 swap 字段对水平翻转增强至关重要——翻转后成对关节需要正确交换,避免标签错位。
五、AI Challenger(AIC):大规模人体关键点竞赛数据集
AI Challenger 2017(ArXiv'2017)由 AI Challenger 竞赛发布,提供大规模人体关键点标注,共 14 个关键点(right_shoulder → neck,含 head_top/neck,见 topdown_aic_dataset.py)。
5.1 下载与目录结构
下载 AI Challenger 2017 数据集(2017 Train/Val 对训练与评估均必要)及 aic_annotations 标注文件,整理为:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── aic
│-- annotations
│ │-- aic_train.json
│ |-- aic_val.json
│-- ai_challenger_keypoint_train_20170902
│ │-- keypoint_train_images_20170902
│ │ │-- 0000252aea98840a550dac9a78c476ecb9f47ffa.jpg
│ │ │-- 000050f770985ac9653198495ef9b5c82435d49c.jpg
│ │ │-- ...
`-- ai_challenger_keypoint_validation_20170911
│-- keypoint_validation_images_20170911
│-- 0002605c53fb92109a3f2de4fc3ce06425c3b61f.jpg
│-- 0003b55a2c991223e6d8b4b820045bd49507bf6d.jpg
│-- ...
5.2 实现特点
TopDownAicDataset(topdown_aic_dataset.py)继承自 TopDownCocoDataset,但 _get_db 中强制 assert self.use_gt_bbox(AIC 训练仅使用 GT 框),其评估复用了 COCO 的 COCOeval 流程,但传入 use_area=False(AIC 官方评估不使用面积归一化)。AIC 的 sigmas 取自官方 keypoint_eval 脚本(delta = 2 x sigma),见 configs/base/datasets/aic_info.py。
六、CrowdPose:拥挤场景姿态估计基准
CrowdPose(CVPR'2019)专注于拥挤、遮挡场景下的多人姿态估计,共 14 个关键点。
6.1 下载与目录结构
下载 CrowdPose 数据集、标注文件与人体检测结果(crowdpose_annotations 压缩包内附带检测框结果):
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── crowdpose
│-- annotations
│ │-- mmpose_crowdpose_train.json
│ │-- mmpose_crowdpose_val.json
│ │-- mmpose_crowdpose_trainval.json
│ │-- mmpose_crowdpose_test.json
│ │-- det_for_crowd_test_0.1_0.5.json
│-- images
│-- 100000.jpg
│-- 100001.jpg
│-- 100002.jpg
│-- ...
6.2 检测框与训练/评估策略
文档明确说明了 CrowdPose 的惯例:对于 top-down 方法,仿照 CrowdPose 论文使用 YOLOv3 的预训练权重来产生人体检测框(即上表中的 det_for_crowd_test_0.1_0.5.json);对于模型训练,仿照 HigherHRNet,在 CrowdPose 训练/验证数据集上训练,并在 CrowdPose 测试集上评估。TopDownCrowdPoseDataset(topdown_crowdpose_dataset.py)同样继承 TopDownCocoDataset,因此共享 COCO 风格的关键点加载、OKS NMS 与 mAP 评估链路。测试样例见 tests/data/crowdpose/。
七、OCHuman:重度遮挡人体数据集
OCHuman(Pose2Seg: Detection Free Human Instance Segmentation, CVPR'2019)面向重度遮挡/截断场景,关键点定义与 COCO 一致(17 个关键点,含 nose、eyes、ears 等,见 configs/base/datasets/ochuman.py)。
7.1 下载与目录结构
从 OCHuman 官方仓库下载图像与标注,整理为:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── ochuman
│-- annotations
│ │-- ochuman_coco_format_val_range_0.00_1.00.json
│ |-- ochuman_coco_format_test_range_0.00_1.00.json
|-- images
│-- 000001.jpg
│-- 000002.jpg
│-- 000003.jpg
│-- ...
7.2 实现特点
TopDownOCHumanDataset(topdown_ochuman_dataset.py)继承 TopDownCocoDataset,标注本身就是 COCO 格式(ochuman_coco_format_*),因此可以直接复用 COCO 的加载与 mAP 评估逻辑。测试样例见 tests/data/ochuman/。
八、MHP:拥挤场景多人解析数据集
MHP(Understanding Humans in Crowded Scenes, ACM MM'2018)是面向拥挤场景的多人体解析数据集,关键点定义见 configs/base/datasets/mhp.py(16 个关键点,与 MPII 类似的关节体系)。
8.1 下载与目录结构
从 MHP 官网下载数据文件,另下载 mhp_annotations 标注,整理为:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── mhp
│-- annotations
│ │-- mhp_train.json
│ │-- mhp_val.json
│
`-- train
│ │-- images
│ │ │-- 1004.jpg
│ │ │-- 10050.jpg
│ │ │-- ...
│
`-- val
│ │-- images
│ │ │-- 10059.jpg
│ │ │-- 10068.jpg
│ │ │-- ...
│
`-- test
│ │-- images
│ │ │-- 1005.jpg
│ │ │-- 10052.jpg
│ │ │-- ...
参考配置 res50_mhp_256x192.py 中,TopDownMhpDataset 的 img_prefix 分别为 data/mhp/train/images/ 与 data/mhp/val/images/,与上述目录一一对应。
九、PoseTrack18:视频人体姿态估计与跟踪基准
PoseTrack18(CVPR'2018)是视频任务基准,同时评估单帧姿态估计精度(mAP)与跨帧跟踪。关键点定义(17 个,nose → right_ankle)见 configs/base/datasets/posetrack18.py。
9.1 下载与目录结构
从 PoseTrack 官网下载数据文件、posetrack18_annotations 标注与 posetrack18_mask 掩码(掩码用于加速训练)。仓库已将官方所有单视频标注文件合并为两个 JSON(posetrack18_train.json 与 posetrack18_val.json),整理为:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── posetrack18
│-- annotations
│ │-- posetrack18_train.json
│ │-- posetrack18_val.json
│ │-- posetrack18_val_human_detections.json
│ │-- train
│ │ │-- 000001_bonn_train.json
│ │ │-- 000002_bonn_train.json
│ │ │-- ...
│ │-- val
│ │ │-- 000342_mpii_test.json
│ │ │-- 000522_mpii_test.json
│ │ │-- ...
│ `-- test
│ │-- 000001_mpiinew_test.json
│ │-- 000002_mpiinew_test.json
│ │-- ...
│
`-- images
│ │-- train
│ │ │-- 000001_bonn_train
│ │ │ │-- 000000.jpg
│ │ │ │-- 000001.jpg
│ │ │ │-- ...
│ │ │-- ...
│ │-- val
│ │ │-- 000342_mpii_test
│ │ │ │-- 000000.jpg
│ │ │ │-- 000001.jpg
│ │ │ │-- ...
│ │ │-- ...
│ `-- test
│ │-- 000001_mpiinew_test
│ │ │-- 000000.jpg
│ │ │-- 000001.jpg
│ │ │-- ...
│ │-- ...
`-- mask
│-- train
│ │-- 000002_bonn_train
│ │ │-- 000000.jpg
│ │ │-- 000001.jpg
│ │ │-- ...
│ │-- ...
`-- val
│-- 000522_mpii_test
│ │-- 000000.jpg
│ │ │-- 000001.jpg
│ │ │-- ...
│-- ...
9.2 检测框与官方评估工具
对于 top-down 方法,仓库使用 MMDetection 的预训练 Cascade R-CNN(X-101-64x4d-FPN)来生成人体检测框,对应 demo 配置见 demo/mmdetection_cfg/cascade_rcnn_x101_64x4d_fpn_1class.py。
PoseTrack 评估需要使用官方评估工具 poseval,请从 GitHub 安装:
pip install git+https://github.com/svenkreiss/poseval.git
TopDownPoseTrack18Dataset(topdown_posetrack18_dataset.py)的评估会按官方单视频 GT 文件逐一写出预测 JSON(含 track_id,见 _write_posetrack18_keypoint_results),再调用 poseval 的 evaluateAP 计算 Head/Shoulder/Elbow/Wrist/Hip/Knee/Ankle 各部位 AP 与 Total AP。若未安装 poseval,评估会抛出 ImportError(见 topdown_posetrack18_dataset.py)。
十、sub-JHMDB:动作识别场景的姿态标注
sub-JHMDB(RSN 论文中使用的视频子集,ICCV'2020 相关)从 JHMDB 动作识别数据集中筛选出姿态标注子集,共 15 个关键点(neck、belly、head 及四肢关节,见 configs/base/datasets/jhmdb.py 与 topdown_jhmdb_dataset.py)。
10.1 下载与目录结构
从 JHMDB 官网下载重命名后的图像包 Rename_Images.tar.gz,另下载 jhmdb_annotations 标注,整理为:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── jhmdb
│-- annotations
│ │-- Sub1_train.json
│ |-- Sub1_test.json
│ │-- Sub2_train.json
│ |-- Sub2_test.json
│ │-- Sub3_train.json
│ |-- Sub3_test.json
|-- Rename_Images
│-- brush_hair
│ │--April_09_brush_hair_u_nm_np1_ba_goo_0
| │ │--00001.png
| │ │--00002.png
│-- catch
│-- ...
10.2 训练配置要点
参考配置 res50_jhmdb_sub1_256x256.py:sub-JHMDB 分为 Sub1/Sub2/Sub3 三个子集,每个子集有独立的 train/test 标注;评估指标为 <a href="https://link.gitcode.com/i/8fb7ac5793da715ecaaf5ac95c02f0b1" target="_blank">'PCK', 'tPCK'](tPCK 即 temporal PCK,考虑视频时序);通常从 MPII 预训练权重 load_from 微调,仅训练 20 个 epoch。测试数据见 [tests/data/jhmdb/。
十一、数据集在 ViTPose 中的统一接入方式
无论选择哪个数据集,ViTPose 的接入流程都遵循同一模式:
- 放置数据:将图像、标注、检测框文件按上文目录结构放入
$MMPOSE/data; - 继承基础配置:在模型配置(如 ViTPose_base_coco_256x192.py)的
_base_中引用configs/_base_/datasets/<dataset>.py,从而获得dataset_info(关键点、骨架、权重、sigmas); - 设置数据字段:
data段中为 train/val/test 分别指定type(如TopDownCocoDataset、TopDownMpiiDataset)、ann_file、img_prefix、data_cfg与pipeline; - 数据增强流水线:训练阶段依次执行
LoadImageFromFile→TopDownRandomFlip(flip_prob=0.5)→TopDownHalfBodyTransform(COCO 专属,prob_half_body=0.3)→TopDownGetRandomScaleRotation(rot_factor=40, scale_factor=0.5)→TopDownAffine→ToTensor→NormalizeTensor(ImageNet 均值和方差)→TopDownGenerateTarget(高斯热图,ViTPose 使用 UDP 编码sigma=2)→Collect;验证/测试阶段则省略翻转、半身与随机增强; - 评估:各数据集类内置对应的
evaluate方法,COCO 系列用 mAP/AP,MPII 系列用 PCKh,sub-JHMDB 用 PCK/tPCK,PoseTrack18 用 poseval 的 AP。
ViTPose 论文所涉及的 COCO、MPII、AIC 等数据集均按上述规范接入;仓库还提供了跨数据集联合训练的配置,例如 vitPose+_base_coco+aic+mpii+ap10k+apt36k+wholebody_256x192_udp.py,展示了 ViTPose++ 如何在同一框架下混用多人人体(COCO/AIC/MPII)、动物(AP10K/APT36K)与全身(WholeBody)标注进行通用姿态估计训练。
结语
本文以 docs/zh_cn/tasks/2d_body_keypoint.md 为准绳,系统梳理了 ViTPose 支持的 9 个 2D 人体关键点数据集的下载来源、标注文件与目录规范,并结合 mmpose/datasets/datasets/top_down/ 下的数据集类实现与 configs/base/datasets/ 下的元信息配置,解释了各数据集在加载、预处理、检测框消费与指标评估上的差异。按上述步骤准备数据后,即可配合 tools/train.py 与 tools/test.py 直接开展 ViTPose 的 2D 人体关键点训练与评估。