ViTPose 仓库实战:HRNet + DarkPose 在 COCO-WholeBody 全身关键点估计中的配置与训练指南
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 无偏解码分支:
- 先通过
_get_max_preds找到热图峰值坐标作为粗略预测; - 对热图做高斯调制:
heatmaps = np.log(np.maximum(_gaussian_blur(heatmaps, kernel), 1e-10)),其中kernel即配置中的modulate_kernel; - 在调制后的对数空间中,对峰值邻域做 Taylor 展开(
_taylor函数)求亚像素级极值,得到更精确的坐标; - 最后通过
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)设置下评测。