ViTPose 全身关键点数据集实战指南:COCO-WholeBody 与 Halpe 的下载、目录组织与训练配置解析
ViTPose 全身关键点数据集实战指南:COCO-WholeBody 与 Halpe 的下载、目录组织与训练配置解析
本文是 ViTPose 仓库中 2D Wholebody Keypoint 数据集文档 的深度实战解读,完整覆盖 MMPose 支持的两大全身关键点数据集 —— COCO-WholeBody(133 关键点)与 Halpe(136 关键点)的下载来源、标准目录结构、评估依赖安装,并结合仓库源码与 ViTPose 配置文件,讲解数据集加载、关键点分组定义、分项评估机制与训练配置的每一个关键参数。读完本文,你将能够独立完成全身关键点数据集的准备、目录校验、环境依赖安装,以及基于 ViTPose 模型配置的训练与验证流程。
数据集概览:MMPose 支持的全身关键点数据集
“全身(Whole-Body)关键点估计”在传统人体姿态估计(身体 17 关键点)的基础上,进一步引入脚部、面部与双手的关键点标注,一次推理即可同时输出身体骨架、面部轮廓与手部关节,是人机交互、AR/VR、数字人驱动等场景的核心基础能力。
MMPose(即本仓库 mmpose 模块)当前支持两个全身关键点数据集:
- COCO-WholeBody:基于 COCO 2017 图片的扩展标注,共 133 个关键点;
- Halpe:基于 HICO-Det / COCO 图片的扩展标注,共 136 个关键点。
两个数据集的结构差异主要在于身体关键点数量(17 vs 20),而脚部(6)、面部(68)、左右手(各 21)的标注规模一致。下文分别给出完整的数据准备步骤、目录结构与源码级说明。
COCO-WholeBody:133 个全身关键点数据集
数据集简介与论文信息
COCO-WholeBody 出自论文 Whole-Body Human Pose Estimation in the Wild(ECCV 2020,作者 Jin Sheng 等),其标注扩展了 COCO 数据集的全身关键点,官方引用信息如下(可直接用于论文致谢部分):
@inproceedings{jin2020whole,
title={Whole-Body Human Pose Estimation in the Wild},
author={Jin, Sheng and Xu, Lumin and Xu, Jin and Wang, Can and Liu, Wentao and Qian, Chen and Ouyang, Wanli and Luo, Ping},
booktitle={Proceedings of the European Conference on Computer Vision (ECCV)},
year={2020}
}
数据下载清单
按照官方文档,准备 COCO-WholeBody 数据集需要下载以下三部分内容:
- COCO 图片:从 COCO 官网下载 2017 Train/Val 图片,用于 COCO 关键点训练与验证;
- COCO-WholeBody 标注文件:从 COCO-WholeBody 项目主页获取 Train 与 Validation 两份标注(官方以 Google Drive 形式分享);
- 人员检测结果:下载 COCO val2017 的 person 检测结果(官方提供 OneDrive / GoogleDrive 两种下载渠道)。
下载完成后,将全部文件解压到 $MMPOSE/data 目录下,并整理成下文所示的标准目录结构。
标准目录结构
COCO-WholeBody 数据集的完整目录布局如下(务必保持文件名一致):
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── coco
│-- annotations
│ │-- coco_wholebody_train_v1.0.json
│ |-- coco_wholebody_val_v1.0.json
|-- person_detection_results
| |-- COCO_val2017_detections_AP_H_56_person.json
│-- train2017
│ │-- 000000000009.jpg
│ │-- 000000000025.jpg
│ │-- 000000000030.jpg
│ │-- ...
`-- val2017
│-- 000000000139.jpg
│-- 000000000285.jpg
│-- 000000000632.jpg
│-- ...
注意:文档建议将数据集根目录**符号链接(symlink)**到
$MMPOSE/data。如果你的目录结构不同,需要同步修改配置文件中的对应路径(即下文data_root与ann_file、img_prefix等字段)。
安装评估依赖:xtcocotools
COCO-WholeBody 的评估需要使用扩展版 COCO API(版本不低于 1.5),安装命令:
pip install xtcocotools
该依赖由 topdown_coco_wholebody_dataset.py 中的 from xtcocotools.cocoeval import COCOeval 直接调用,若未安装,运行验证(test)阶段会直接导入失败。
源码级解读:133 个关键点的组成与加载实现
从数据集类 TopDownCocoWholeBodyDataset(继承自 TopDownCocoDataset)的文档字符串与实现,可以精确还原 133 个关键点的分组:
0-16: 17 个身体关键点(body)
17-22: 6 个脚部关键点(foot)
23-90: 68 个面部关键点(face)
91-132: 42 个手部关键点(hands,左右各 21)
对应实现见 topdown_coco_wholebody_dataset.py,代码中以 self.body_num = 17、self.foot_num = 6、self.face_num = 68、self.left_hand_num = 21、self.right_hand_num = 21 显式定义各分组数量。
标注加载时,_load_coco_keypoint_annotation_kernel 会把 COCO-WholeBody 标注中分散的 keypoints、foot_kpts、face_kpts、lefthand_kpts、righthand_kpts 五个字段拼接为 num_joints × 3 的数组(x, y, visibility),并清洗越界 bbox。评估输出时,_coco_keypoint_results_one_category_kernel 再按 np.cumsum([0, 17, 6, 68, 21, 21]) * 3 的切分还原回五组字段。
分项评估是 COCO-WholeBody 的显著特点:_do_python_keypoint_eval 会依次对 keypoints_body、keypoints_foot、keypoints_face、keypoints_lefthand、keypoints_righthand 和 keypoints_wholebody 六组分别执行 COCOeval,并输出每组 AP/AR 统计,这正是测试配置中 metric='mAP', save_best='AP' 的含义。
关键点元信息定义在基础配置 configs/base/datasets/coco_wholebody.py 中,包含:
keypoint_info:133 个关键点的名称、id、可视化颜色、类型(upper/lower 或空)、左右对称交换关系(swap,用于水平翻转测试);skeleton_info:骨骼连线定义(如('left_ankle', 'left_knee')),供可视化绘制骨架;joint_weights:长度 133、全 1 的关节权重;sigmas:长度 133 的 OKS sigma 列表,逐关键点定义归一化容差,直接参与 mAP 计算。
ViTPose 训练配置解析(COCO-WholeBody)
ViTPose 仓库为 COCO-WholeBody 提供了 small / base / large / huge 四档完整的训练配置,位于 configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/coco-wholebody/。以 ViTPose_small_wholebody_256x192.py 为例,关键配置项如下:
通道与模型配置:channel_cfg 将 num_output_channels 与 dataset_joints 均设为 133;model.backbone 使用 type='ViT',small 规模为 embed_dim=384, depth=12, num_heads=12,输入 img_size=(256, 192)、patch_size=16,并开启 drop_path_rate=0.3;keypoint_head 使用 TopdownHeatmapSimpleHead,in_channels=384,两级反卷积(num_deconv_filters=(256, 256))后输出 133 通道热图,损失函数为 JointsMSELoss(use_target_weight=True)。
对应地,ViTPose_large_wholebody_256x192.py 将 ViT 规模提升为 embed_dim=1024, depth=24, num_heads=16,head 的 in_channels 同步改为 1024——这是切换 ViTPose 模型规格时必须同步修改的两处。
数据配置(data_cfg):
data_cfg = dict(
image_size=[192, 256],
heatmap_size=[48, 64],
num_output_channels=channel_cfg['num_output_channels'],
num_joints=channel_cfg['dataset_joints'],
dataset_channel=channel_cfg['dataset_channel'],
inference_channel=channel_cfg['inference_channel'],
soft_nms=False,
nms_thr=1.0,
oks_thr=0.9,
vis_thr=0.2,
use_gt_bbox=False,
det_bbox_thr=0.0,
bbox_file='data/coco/person_detection_results/'
'COCO_val2017_detections_AP_H_56_person.json',
)
其中 bbox_file 指向前面下载的 person 检测结果文件;use_gt_bbox=False 表示验证/测试阶段使用该检测框而非真实框。若希望使用 GT 框验证,可将其改为 True。
训练与验证流水线:训练采用 LoadImageFromFile → TopDownRandomFlip → TopDownHalfBodyTransform(prob_half_body=0.3)→ TopDownGetRandomScaleRotation(rot_factor=40, scale_factor=0.5)→ TopDownAffine → ToTensor → NormalizeTensor(ImageNet 均值/方差)→ TopDownGenerateTarget(sigma=2)→ Collect 的完整链路;验证/测试流水线去掉随机增强与热图生成,仅保留仿射变换与归一化。
数据集入口:data 字段中 train / val / test 均使用 type='TopDownCocoWholeBodyDataset',分别指向:
- 训练标注:
data/coco/annotations/coco_wholebody_train_v1.0.json,图片前缀data/coco/train2017/; - 验证/测试标注:
data/coco/annotations/coco_wholebody_val_v1.0.json,图片前缀data/coco/val2017/。
训练超参:优化器 Adam(lr=5e-4),lr_config 采用 step 策略、线性 warmup(warmup_iters=500, warmup_ratio=0.001),在 170/200 epoch 处衰减,total_epochs=210;evaluation 每 10 个 epoch 评估一次 mAP 并保存最优模型。
Halpe:136 个全身关键点数据集
数据集简介与论文信息
Halpe 全身关键点数据集来自 PaStaNet 工作 PaStaNet: Toward Human Activity Knowledge Engine(CVPR 2020),引用信息如下:
@inproceedings{li2020pastanet,
title={PaStaNet: Toward Human Activity Knowledge Engine},
author={Li, Yong-Lu and Xu, Liang and Liu, Xinpeng and Huang, Xijie and Xu, Yue and Wang, Shiyi and Fang, Hao-Shu and Ma, Ze and Chen, Mingyang and Lu, Cewu},
booktitle={CVPR},
year={2020}
}
数据下载清单
准备 Halpe 数据集需要下载:
- Halpe 图片与标注:从 Halpe-FullBody 项目主页获取(官方下载渠道);
- 训练集图片:来自 HICO-Det 数据集;
- 验证集图片:来自 COCO val2017;
- 人员检测结果:同样下载 COCO val2017 的 person 检测结果(OneDrive / GoogleDrive 两种渠道)。
下载完成后同样解压至 $MMPOSE/data,并按标准目录结构组织。
标准目录结构
Halpe 数据集的完整目录布局如下:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── halpe
│-- annotations
│ │-- halpe_train_v1.json
│ |-- halpe_val_v1.json
|-- person_detection_results
| |-- COCO_val2017_detections_AP_H_56_person.json
│-- hico_20160224_det
│ │-- anno_bbox.mat
│ │-- anno.mat
│ │-- README
│ │-- images
│ │ │-- train2015
│ │ │ │-- HICO_train2015_00000001.jpg
│ │ │ │-- HICO_train2015_00000002.jpg
│ │ │ │-- HICO_train2015_00000003.jpg
│ │ │ │-- ...
│ │ │-- test2015
│ │-- tools
│ │-- ...
`-- val2017
│-- 000000000139.jpg
│-- 000000000285.jpg
│-- 000000000632.jpg
│-- ...
注意 Halpe 的训练图片位于 hico_20160224_det/images/train2015/ 子目录,与 COCO-WholeBody 的布局不同。
安装评估依赖
Halpe 的评估同样依赖扩展版 COCO API:
pip install xtcocotools
源码级解读:TopDownHalpeDataset 与 136 关键点分组
Halpe 数据集类为 TopDownHalpeDataset(同样继承自 TopDownCocoDataset),见 topdown_halpe_dataset.py。其 136 个关键点分组为:
0-19: 20 个身体关键点(body)
20-25: 6 个脚部关键点(foot)
26-93: 68 个面部关键点(face)
94-135: 42 个手部关键点(hands,左右各 21)
与 COCO-WholeBody 相比,Halpe 在身体部分多出 3 个关键点(如胸、腹、盆骨等),因此总数从 133 变为 136。关键点元信息定义在 configs/base/datasets/halpe.py,同样包含完整的 keypoint_info、skeleton_info、joint_weights 与 sigmas。
Halpe 的训练配置位于 configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/halpe/。以 hrnet_w32_halpe_256x192.py 为例,与 COCO-WholeBody 配置的差异集中在:
channel_cfg的num_output_channels/dataset_joints均改为 136;- 数据集类型改为
TopDownHalpeDataset; - 训练标注为
data/halpe/annotations/halpe_train_v1.json,img_prefix为data/halpe/hico_20160224_det/images/train2015/; - 验证/测试标注为
data/halpe/annotations/halpe_val_v1.json,img_prefix为data/halpe/val2017/; - 优化器、学习率策略、训练流水线等其余部分与 COCO-WholeBody 配置保持一致。
关联子任务:全身标注衍生的 Face / Hand 独立数据集
COCO-WholeBody 的标注还可以按区域拆分为独立的面部、手部子任务数据集。仓库提供了对应的基础配置 coco_wholebody_face.py 与 coco_wholebody_hand.py,以及数据集类 FaceCocoWholeBodyDataset(face_coco_wholebody_dataset.py)和 HandCocoWholeBodyDataset(hand_coco_wholebody_dataset.py)。这意味着同一份 COCO-WholeBody 标注可以被全身、人脸、人手三条任务线共用,显著降低了多任务数据集的管理成本。
基于全身数据集的训练、测试与推理
数据准备完成后,即可使用仓库标准工具进行训练与测试(以 COCO-WholeBody 的 ViTPose small 配置为例):
# 训练
python tools/train.py configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/coco-wholebody/ViTPose_small_wholebody_256x192.py
# 测试(多 GPU 训练可参考 tools/dist_train.sh / tools/dist_test.sh)
python tools/test.py ${CONFIG_FILE} ${CHECKPOINT_FILE} --eval mAP
推理与可视化可参考 demo/docs/2d_wholebody_pose_demo.md,它提供了三种玩法:
- GT 框输入的单图演示:
demo/top_down_img_demo.py+ 配置文件 + 权重 +--json-file(GT 标注); - mmdet 检测 + mmpose 估计:
demo/top_down_img_demo_with_mmdet.py串联人体检测与全身姿态估计; - 视频全身姿态演示:
demo/top_down_video_demo_with_mmdet.py。
推理加速方面,可关闭 flip_test(设为 False)、保持 post_process='default',并选用更快的人体检测器。
常见问题与自动化验证
Q:目录结构与文档不一致怎么办?
文档明确说明:如果目录结构不同,必须同步修改配置文件中的 data_root、ann_file、img_prefix、bbox_file 等路径字段,否则数据集加载会直接失败。
Q:如何验证数据集与评估链路是否就绪? 仓库测试覆盖了两个全身数据集的完整加载与评估流程:
- tests/test_datasets/test_top_down_dataset.py 中的
test_top_down_COCO_wholebody_dataset与test_top_down_halpe_dataset,使用tests/data/coco/test_coco_wholebody.json等小规模测试标注验证数据加载、GT/检测框两种模式和 mAP 评估; - tests/test_datasets/test_bottom_up_dataset.py 中的
test_bottom_up_COCO_wholebody_dataset覆盖自底向上(Associative Embedding)路线的全身数据集。
Q:自底向上方法如何配置?
若使用 bottom-up 路线(如 HigherHRNet),配置见 configs/wholebody/2d_kpt_sview_rgb_img/associative_embedding/coco-wholebody/,其数据集类型为 BottomUpCocoWholeBodyDataset,输入分辨率通常为 512×512 或 640×640,无需 person 检测框。
小结
COCO-WholeBody(133 关键点)与 Halpe(136 关键点)是 MMPose / ViTPose 全身关键点估计的两大核心数据集。本文完整复现了官方文档的下载清单、目录结构与评估依赖安装步骤,并进一步从源码层面解析了关键点分组定义、分项评估机制、数据集加载实现,以及 ViTPose small/large 等训练配置中的通道数、ViT 骨干、流水线与路径字段的对应关系。按照本文步骤完成数据准备并正确设置 xtcocotools,即可直接运行仓库内训练、测试与演示脚本,开展全身关键点估计的复现与二次开发。