ViTPose 仓库实战:HRNet + DarkPose 在 COCO-WholeBody 全身关键点估计中的配置与训练指南

原创2026-10-14 11:29:421,949 阅读
文章标签:人工智能计算机视觉深度学习机器学习

ViTPose 仓库实战:HRNet + DarkPose 在 COCO-WholeBody 全身关键点估计中的配置与训练指南

本文以 ViTPose 仓库中 hrnet_dark_coco-wholebody.md 为核心,系统讲解如何在 COCO-WholeBody(133 点全身姿态)数据集上使用 HRNet 骨干网络结合 DarkPose 无偏坐标编解码方案完成训练与评估。读完本文,你将掌握两套官方配置(HRNet-W32 256x192 与 HRNet-W48 384x288+)的完整参数含义、DarkPose 在仓库源码中的具体实现位置,以及如何复现论文中的 Body / Foot / Face / Hand / Whole 分部位 AP、AR 指标。

背景:为什么是 HRNet + DarkPose + COCO-WholeBody

本文关联文档对应三种核心技术的组合:

  • HRNet(CVPR'2019):Deep High-Resolution Representation Learning for Human Pose Estimation,通过并行多分辨率分支与反复跨分辨率融合,始终保留高分辨率特征,是 top-down 热图方法中的经典骨干网络;
  • DarkPose(CVPR'2020):Distribution-Aware Coordinate Representation for Human Pose Estimation,通过"无偏编码 + 无偏解码"消除传统热图方法中坐标量化的系统性偏差;
  • COCO-WholeBody(ECCV'2020):Whole-Body Human Pose Estimation in the Wild,在 COCO 17 个身体关键点基础上扩展了脚部(6 点)、面部(68 点)和手部(42 点)关键点,共 133 个关键点。

从仓库目录结构看,该模型方案位于 configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/coco-wholebody/,属于"2D 关键点、单视角、RGB 图像、top-down 热图"任务分支;与同目录下的 ViTPose 系列、ResNet、ViP-NAS 方案并列,是全身姿态估计基准的重要组成。

官方结果一览(COCO-WholeBody v1.0 val)

文档中给出的评估条件为:检测器在 COCO val2017 上人体 AP 为 56.4,评估使用 COCO-WholeBody v1.0 验证集。官方配置与指标如下:

Arch Input Size Body AP Body AR Foot AP Foot AR Face AP Face AR Hand AP Hand AR Whole AP Whole AR
pose_hrnet_w32_dark 256x192 0.694 0.764 0.565 0.674 0.736 0.808 0.503 0.602 0.582 0.671
pose_hrnet_w48_dark+ 384x288 0.742 0.807 0.705 0.804 0.840 0.892 0.602 0.694 0.661 0.743

其中各列含义:

  • Body / Foot / Face / Hand:分别对应 17 个身体点、6 个脚部点、68 个面部点、42 个手部点的 AP 与 AR;
  • Whole:133 个关键点全体的 AP 与 AR;
  • 官方 Checkpoint 与训练日志下载地址随表格附注(ckpt / log 列),可在复现或推理时直接下载使用。

文档还特别指出:+ 表示该模型先在原始 COCO 数据集上预训练,再在 COCO-WholeBody 数据集上微调,官方实验表明这种两阶段策略能带来更好的性能。这正是第二个配置中 load_from 字段的来源(详见下文)。

配置一:pose_hrnet_w32_dark(256x192)

完整配置见 hrnet_w32_coco_wholebody_256x192_dark.py。下面按模块拆解关键配置。

数据集与 133 通道配置

配置文件通过 _base_ 继承基础运行时与数据集定义:

_base_ = [
    '../../../../_base_/default_runtime.py',
    '../../../../_base_/datasets/coco_wholebody.py'
]

其中 coco_wholebody.py 定义了 COCO-WholeBody 数据集的完整 dataset_info,包含 133 个关键点的名称、颜色、左右互换关系(swap)与骨架连线(skeleton)。从 TopDownCocoWholeBodyDataset 的源码注释可以确认关键点索引的划分方式(见 topdown_coco_wholebody_dataset.py):

0-16:   17 个身体关键点
17-22:  6 个脚部关键点
23-90:  68 个面部关键点
91-132: 42 个手部关键点
共 133 个关键点

两个配置都使用相同的通道配置:

channel_cfg = dict(
    num_output_channels=133,
    dataset_joints=133,
    dataset_channel=[list(range(133))],
    inference_channel=list(range(133)))

模型结构:HRNet 骨干 + 简单热图头

model = dict(
    type='TopDown',
    pretrained='https://download.openmmlab.com/mmpose/'
    'pretrain_models/hrnet_w32-36af842e.pth',
    backbone=dict(
        type='HRNet',
        in_channels=3,
        extra=dict(
            stage1=dict(
                num_modules=1, num_branches=1, block='BOTTLENECK',
                num_blocks=(4, ), num_channels=(64, )),
            stage2=dict(
                num_modules=1, num_branches=2, block='BASIC',
                num_blocks=(4, 4), num_channels=(32, 64)),
            stage3=dict(
                num_modules=4, num_branches=3, block='BASIC',
                num_blocks=(4, 4, 4), num_channels=(32, 64, 128)),
            stage4=dict(
                num_modules=3, num_branches=4, block='BASIC',
                num_blocks=(4, 4, 4, 4), num_channels=(32, 64, 128, 256)))),
    keypoint_head=dict(
        type='TopdownHeatmapSimpleHead',
        in_channels=32,
        out_channels=channel_cfg['num_output_channels'],
        num_deconv_layers=0,
        extra=dict(final_conv_kernel=1, ),
        loss_keypoint=dict(type='JointsMSELoss', use_target_weight=True)),
    train_cfg=dict(),
    test_cfg=dict(
        flip_test=True,
        post_process='unbiased',
        shift_heatmap=True,
        modulate_kernel=11))

要点解读:

  • HRNet 四阶段结构:stage1 为 1 个分支的 BOTTLENECK 残差块,stage2~stage4 逐步扩展到 2、3、4 个并行分支,通道数依次为 (32,64)、(32,64,128)、(32,64,128,256)。HRNet 的实现位于 mmpose/models/backbones/hrnet.py,其核心 HRModule 类负责多分支构建与跨分辨率特征融合(_make_branches / _make_fuse_layers);
  • 简单热图头:TopdownHeatmapSimpleHead(实现见 topdown_heatmap_simple_head.py)使用 HRNet 最高分辨率分支(in_channels=32)的输出,num_deconv_layers=0 表示不额外堆叠反卷积,直接通过 1x1 卷积输出 133 通道热图;损失函数为带 target_weight 的 JointsMSELoss;
  • DarkPose 解码:test_cfg 中 post_process='unbiased' 是 DarkPose 无偏解码的关键开关,modulate_kernel=11 对应高斯调制核大小,需要与训练时的高斯 sigma=2 匹配(见后文源码说明)。

数据路径与检测框

data_cfg = dict(
    image_size=[192, 256],
    heatmap_size=[48, 64],
    num_output_channels=133,
    num_joints=133,
    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',
)
  • image_size=[192, 256] 与 heatmap_size=[48, 64]:输入图像尺寸与输出热图尺寸,热图分辨率为输入的 1/4;
  • use_gt_bbox=False:验证时不使用真实框,而是使用检测框文件 COCO_val2017_detections_AP_H_56_person.json(该检测器在 COCO val2017 上人体 AP 为 56.4,与文档评测条件一致);训练时则使用 GT 框;
  • soft_nms=False、nms_thr=1.0:单目标 top-down 流程中的 NMS 相关配置。

训练流水线中的 DarkPose 无偏编码

train_pipeline = [
    dict(type='LoadImageFromFile'),
    dict(type='TopDownRandomFlip', flip_prob=0.5),
    dict(type='TopDownHalfBodyTransform',
         num_joints_half_body=8, prob_half_body=0.3),
    dict(type='TopDownGetRandomScaleRotation', rot_factor=40, scale_factor=0.5),
    dict(type='TopDownAffine'),
    dict(type='ToTensor'),
    dict(type='NormalizeTensor',
         mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
    dict(type='TopDownGenerateTarget', sigma=2, unbiased_encoding=True),
    dict(type='Collect',
         keys=['img', 'target', 'target_weight'],
         meta_keys=['image_file', 'joints_3d', 'joints_3d_visible',
                    'center', 'scale', 'rotation', 'bbox_score', 'flip_pairs']),
]

TopDownGenerateTarget(sigma=2, unbiased_encoding=True) 是 DarkPose 训练侧的关键。在 top_down_transform.py 的源码中可以看到两种高斯热图生成路径的差异:

  • 传统 MSRA 方式:先将关键点坐标除以特征步长后取整(mu_x = int(...)),再以整数位置为中心放置高斯核,这引入了最多 0.5 像素的量化偏移;
  • 无偏编码方式(unbiased_encoding=True):不再取整,直接以浮点坐标 mu_x = joints_3d[joint_id][0] / feat_stride[0] 计算高斯分布 exp(-((x-mu_x)^2+(y-mu_y)^2)/(2*sigma^2)),热图中心与真实关键点精确对齐,从根本上消除了编码阶段的量化偏差。

同理,验证/测试流水线不生成 target,仅做仿射变换、归一化并收集 center/scale/rotation 等用于坐标回映射的元信息。

优化器与学习率

optimizer = dict(type='Adam', lr=5e-4)
optimizer_config = dict(grad_clip=None)
lr_config = dict(
    policy='step',
    warmup='linear',
    warmup_iters=500,
    warmup_ratio=0.001,
    step=[170, 200])
total_epochs = 210
evaluation = dict(interval=10, metric='mAP', save_best='AP')
  • 优化器为 Adam,初始学习率 5e-4;
  • 学习率采用 step 策略,线性 warmup 500 步后在第 170 与第 200 个 epoch 衰减;
  • 总训练 210 个 epoch;评估每 10 个 epoch 执行一次,指标为 mAP,并依据 Whole 的 AP 保存最优模型;
  • 运行时基配置见 default_runtime.py,每 10 个 epoch 保存一次 checkpoint,日志每 50 个迭代输出一次。

配置二:pose_hrnet_w48_dark+(384x288)

完整配置见 hrnet_w48_coco_wholebody_384x288_dark_plus.py。它与 W32 版本的核心差异如下:

先在 COCO 预训练,再在 WholeBody 微调(+ 策略)

load_from = 'https://download.openmmlab.com/mmpose/top_down/hrnet/hrnet_w48_coco_384x288_dark-741844ba_20200812.pth'
model = dict(
    type='TopDown',
    pretrained=None,  # 不再加载 ImageNet 预训练权重
    ...
)
  • load_from 指向一个已在 COCO 数据集上训练好的 HRNet-W48 DarkPose 权重,训练启动时直接加载该 checkpoint 作为初始化,这正是文档中 + 的含义(先在原始 COCO 上训练、再在 COCO-WholeBody 上微调);
  • 与之相对,W32 配置使用 pretrained 加载 ImageNet 预训练权重(hrnet_w32-36af842e.pth),这是从头在 WholeBody 上训练的常规做法。

更大的骨干与输入分辨率

  • HRNet-W48:stage2~stage4 分支通道数升级为 (48,96)、(48,96,192)、(48,96,192,384),keypoint_head.in_channels=48;
  • 输入与热图尺寸:image_size=[288, 384]、heatmap_size=[72, 96],均为 W32 版本的 1.5 倍;
  • 高斯 sigma 与调制核:训练热图 sigma=3(对应 modulate_kernel=17),而 W32 版本为 sigma=2(对应 modulate_kernel=11)。这与源码中 keypoints_from_heatmaps 的注释一致——调制核大小需与训练高斯 sigma 匹配:K=17 for sigma=3 and k=11 for sigma=2(见 top_down_eval.py);
  • samples_per_gpu=32(W32 为 64),以适配更大的输入分辨率与模型容量。

DarkPose 解码在仓库中的实现原理

推理阶段,test_cfg 中的 post_process='unbiased' 会进入 top_down_eval.py 的 keypoints_from_heatmaps 无偏解码分支:

  1. 先通过 _get_max_preds 找到热图峰值坐标作为粗略预测;
  2. 对热图做高斯调制:heatmaps = np.log(np.maximum(_gaussian_blur(heatmaps, kernel), 1e-10)),其中 kernel 即配置中的 modulate_kernel;
  3. 在调制后的对数空间中,对峰值邻域做 Taylor 展开(_taylor 函数)求亚像素级极值,得到更精确的坐标;
  4. 最后通过 transform_preds 将热图坐标映射回原图(use_udp=False 时按 scale / output_size 的简化比例回映射)。

对比之下,普通 post_process='default' 只对峰值位置施加固定的 ±0.25 像素偏移修正,精度远低于 DarkPose 的分布调制 + Taylor 展开方案。这就是 DarkPose 在仓库中"编码(unbiased_encoding)+ 解码(post_process='unbiased')"的完整闭环。

另外,两个配置都开启了 flip_test=True(水平翻转测试,双路热图融合)与 shift_heatmap=True(翻转后热图平移补偿),进一步稳定预测结果。

训练、测试与复现

环境与数据准备

  • 按仓库 README.md 与 install.md 安装依赖(mmcv、mmpose 及其 requirements);
  • 准备 COCO 数据,目录结构需满足 data_root = 'data/coco',注释文件为 annotations/coco_wholebody_train_v1.0.json 与 annotations/coco_wholebody_val_v1.0.json,图像位于 train2017/ 与 val2017/;
  • 验证时需要的检测框文件放在 data/coco/person_detection_results/COCO_val2017_detections_AP_H_56_person.json。

训练命令

单卡训练 W32 模型:

python tools/train.py configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/coco-wholebody/hrnet_w32_coco_wholebody_256x192_dark.py

多卡分布式训练:

bash tools/dist_train.sh configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/coco-wholebody/hrnet_w32_coco_wholebody_256x192_dark.py 8

训练入口 tools/train.py 支持 --work-dir、--resume-from、--no-validate 等参数;单机多卡通过 tools/dist_train.sh 传入 GPU 数,集群环境可使用 tools/slurm_train.sh。

测试命令

python tools/test.py configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/coco-wholebody/hrnet_w32_coco_wholebody_256x192_dark.py \
    work_dirs/hrnet_w32_coco_wholebody_256x192_dark/best_AP_epoch_210.pth \
    --eval mAP

evaluation 配置中的 metric='mAP' 对应 top_down_eval.py 中的 COCO 评估实现,会分别输出 Body / Foot / Face / Hand / Whole 各分部位的 AP 与 AR,与本文开头的结果表一一对应。

官方权重复现

如需快速复现结果而非重新训练,可直接下载官方 checkpoint(见文档原表 ckpt / log 列),并用上述 test 命令配合对应配置进行推理评估。W32 模型输入 256x192,W48+ 模型输入 384x288,两者 post_process='unbiased' 的评测行为完全一致,可直接对比。

小结与调参要点

  • 编码与解码必须配套:DarkPose 方案要求训练侧 unbiased_encoding=True 与测试侧 post_process='unbiased' 同时启用,且 modulate_kernel 要与训练高斯 sigma 匹配(sigma=2 → kernel=11,sigma=3 → kernel=17),否则坐标精度会退化;
  • 分辨率与容量的权衡:W48 384x288 相比 W32 256x192 在 Whole AP 上提升约 0.079(0.582 → 0.661),但显存占用与推理耗时同步上升,samples_per_gpu 需相应下调;
  • 两阶段微调(+ 策略):先在 COCO 预训练再在 WholeBody 微调可显著提升全身关键点精度,官方在 W48 配置中通过 load_from 固化这一策略;
  • 评估口径:官方结果表基于 AP 56.4 的检测器框,若要严格对比指标,请使用配置中的 bbox_file,并在相同的翻转测试(flip_test=True)设置下评测。
登录后查看全文
ViTPose