ViTPose 全身关键点数据集实战指南:COCO-WholeBody 与 Halpe 的下载、目录组织与训练配置解析

原创2026-10-14 18:23:151,879 阅读
文章标签:人工智能计算机视觉深度学习机器学习

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 数据集需要下载以下三部分内容:

  1. COCO 图片:从 COCO 官网下载 2017 Train/Val 图片,用于 COCO 关键点训练与验证;
  2. COCO-WholeBody 标注文件:从 COCO-WholeBody 项目主页获取 Train 与 Validation 两份标注(官方以 Google Drive 形式分享);
  3. 人员检测结果:下载 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 数据集需要下载:

  1. Halpe 图片与标注:从 Halpe-FullBody 项目主页获取(官方下载渠道);
  2. 训练集图片:来自 HICO-Det 数据集;
  3. 验证集图片:来自 COCO val2017;
  4. 人员检测结果:同样下载 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,它提供了三种玩法:

  1. GT 框输入的单图演示:demo/top_down_img_demo.py + 配置文件 + 权重 + --json-file(GT 标注);
  2. mmdet 检测 + mmpose 估计:demo/top_down_img_demo_with_mmdet.py 串联人体检测与全身姿态估计;
  3. 视频全身姿态演示:demo/top_down_video_demo_with_mmdet.py。

推理加速方面,可关闭 flip_test(设为 False)、保持 post_process='default',并选用更快的人体检测器。

常见问题与自动化验证

Q:目录结构与文档不一致怎么办? 文档明确说明:如果目录结构不同,必须同步修改配置文件中的 data_root、ann_file、img_prefix、bbox_file 等路径字段,否则数据集加载会直接失败。

Q:如何验证数据集与评估链路是否就绪? 仓库测试覆盖了两个全身数据集的完整加载与评估流程:

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,即可直接运行仓库内训练、测试与演示脚本,开展全身关键点估计的复现与二次开发。

登录后查看全文
ViTPose