基于 HRNet 的 COCO 人体姿态估计:ViTPose 仓库 topdown heatmap 配置全解析
基于 HRNet 的 COCO 人体姿态估计:ViTPose 仓库 topdown heatmap 配置全解析
导读
本文以 ViTPose 仓库中 hrnet_coco.md 文档为骨架,系统讲解 HRNet 在 COCO val2017 数据集上、采用 top-down heatmap 范式进行人体 2D 关键点估计的完整实践:包括四种官方配置(w32/w48 × 256x192/384x288)的精度对比、骨干网络与检测头源码级原理、完整训练/测试命令,以及推理演示方法。读完本文,你将掌握 HRNet + COCO 姿态估计的配置结构、每个关键参数的含义与调优思路,并能直接基于仓库配置复现训练与推理。
注:本文所述内容均以当前 ViTPose 仓库实际文件为准;文中涉及的指标均为仓库文档与配置文件记载的官方结果。
一、文档速览:HRNet 在 COCO 上的官方结果
hrnet_coco.md 给出了 HRNet 在 COCO val2017 上的评测结果,评测条件为使用人体检测器 AP=56.4 的检测框(即 COCO_val2017_detections_AP_H_56_person.json,该路径在 hrnet_w32_coco_256x192.py 等配置的 bbox_file 中指定)。完整结果如下:
| Arch | Input Size | AP | AP⁵⁰ | AP⁷⁵ | AR | AR⁵⁰ | ckpt | log |
|---|---|---|---|---|---|---|---|---|
| pose_hrnet_w32 | 256x192 | 0.746 | 0.904 | 0.819 | 0.799 | 0.942 | ckpt | log |
| pose_hrnet_w32 | 384x288 | 0.760 | 0.906 | 0.829 | 0.810 | 0.943 | ckpt | log |
| pose_hrnet_w48 | 256x192 | 0.756 | 0.907 | 0.825 | 0.806 | 0.942 | ckpt | log |
| pose_hrnet_w48 | 384x288 | 0.767 | 0.910 | 0.831 | 0.816 | 0.946 | ckpt | log |
同一配置的元数据也以 Collections/Models 结构记录在 hrnet_coco.yml 中,二者数值完全一致,可用于模型索引与自动收集。
规律解读:输入分辨率 256x192 → 384x288 可带来约 0.014~0.011 的 AP 提升;w32 → w48 在同一分辨率下可带来约 0.010~0.007 的 AP 提升;两者叠加(w48 + 384x288)达到四组配置中最高 AP 0.767。作为参考,仓库 inference_speed_summary.md 记录了 HRNet-W32 256x192 在 COCO 上的推理速度数据(输入形状 (3,192,256),AP 0.746)。
二、配置结构总览:四份配置文件的公共骨架
四份配置文件(hrnet_w32_coco_256x192.py、hrnet_w32_coco_384x288.py、hrnet_w48_coco_256x192.py、hrnet_w48_coco_384x288.py)共享同一结构,由以下几大块组成:
_base_ # 继承 default_runtime.py 与 datasets/coco.py
evaluation # 验证间隔与指标(mAP, save_best='AP')
optimizer # Adam, lr=5e-4
lr_config # step 策略 + linear warmup, step=[170,200]
total_epochs # 210
channel_cfg # 通道/关键点配置(17 关节)
model # TopDown 检测器 = HRNet backbone + TopdownHeatmapSimpleHead
data_cfg # 图像/热图尺寸、NMS 与 bbox 相关配置
train_pipeline # 训练数据流水线(含增强)
val/test_pipeline # 验证/测试流水线
data # 数据集路径与 dataloader 配置
两个基础配置分别位于 default_runtime.py(checkpoint 每 10 epoch 保存一次、TextLoggerHook 日志、dist_params = dict(backend='nccl')、workflow=<a href="https://link.gitcode.com/i/e16213d3713520277937aa8d447de817" target="_blank">('train',1)],并禁用 OpenCV 多线程、使用 fork 多进程启动)和 [coco.py(完整定义了 COCO 的 dataset_info:17 个关键点的名称/颜色/左右交换关系、19 条骨架连线、joint_weights 与 sigmas)。其中 joint_weights(如腕部 1.5、肘/膝 1.2)直接用于加权 MSE 损失,sigmas 用于 OKS 评估,左右 swap 字段则是测试时翻转融合的关键依据。
三、channel_cfg 与 data_cfg:关键点通道与数据几何
3.1 channel_cfg
所有 HRNet COCO 配置的 channel_cfg 完全一致:
channel_cfg = dict(
num_output_channels=17, # 输出热图通道数 = COCO 17 个关键点
dataset_joints=17,
dataset_channel=[[0,1,2,...,16]], # 数据集中使用的关键点索引
inference_channel=[0,1,2,...,16]) # 推理输出的关键点索引
这里 dataset_channel 与 inference_channel 相同,说明 COCO 数据集的 17 个关节全部参与训练与推理(无裁剪/重排)。当需要做数据集关节子集映射(如只用上半身)时,这两项就会不同。
3.2 data_cfg
以 256x192 配置为例:
data_cfg = dict(
image_size=[192, 256], # 输入图像尺寸 [W, H],384x288 配置为 [288, 384]
heatmap_size=[48, 64], # 热图尺寸 [W, H],为 image_size 的 1/4;384x288 对应 [72, 96]
num_output_channels=17,
num_joints=17,
dataset_channel=channel_cfg['dataset_channel'],
inference_channel=channel_cfg['inference_channel'],
soft_nms=False, # 不使用 soft-NMS
nms_thr=1.0, # NMS 阈值(配合 soft_nms 使用)
oks_thr=0.9, # OKS 阈值,用于关键点 NMS
vis_thr=0.2, # 关键点可视化/过滤置信度阈值
use_gt_bbox=False, # 验证时使用检测器 bbox 而非 GT bbox
det_bbox_thr=0.0, # 检测框置信度阈值
bbox_file='data/coco/person_detection_results/'
'COCO_val2017_detections_AP_H_56_person.json')
要点:heatmap_size 恒为 image_size 的 1/4(192→48,256→64;288→72,384→96),这是网络输出热图与输入图像之间的固定降采样比例;use_gt_bbox=False 表明文档所示精度是基于检测框的结果(对应“detector having human AP of 56.4”的评测前提),即 top-down 流程中的人体框来自外部检测器。
四、model 配置源码级拆解:HRNet 骨干 + 简单热图头
4.1 检测器整体结构
model = dict(
type='TopDown', # 顶层检测器类型(top-down 范式)
pretrained='https://download.openmmlab.com/mmpose/pretrain_models/hrnet_w32-36af842e.pth', # w48 为 hrnet_w48-8ef0771d.pth
backbone=dict(type='HRNet', in_channels=3, extra=dict(...)),
keypoint_head=dict(
type='TopdownHeatmapSimpleHead',
in_channels=32, # w48 配置为 48(取 HRNet stage4 第 0 分支通道数)
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='default', # 默认后处理(取热图最大值)
shift_heatmap=True, # 翻转后平移热图以对齐
modulate_kernel=11)) # DARK 相关调制核大小
pretrained 分别指向官方 HRNet-W32/W48 的 ImageNet 预训练权重,训练时将加载骨干部分。
4.2 HRNet 骨干的 extra 配置
extra 定义了四个阶段的网络结构。w32 与 w48 的唯一区别在于各阶段 num_channels:
| 阶段 | w32 通道数 | w48 通道数 | num_modules | num_branches | block | num_blocks |
|---|---|---|---|---|---|---|
| stage1 | (64,) | (64,) | 1 | 1 | BOTTLENECK | (4,) |
| stage2 | (32, 64) | (48, 96) | 1 | 2 | BASIC | (4, 4) |
| stage3 | (32, 64, 128) | (48, 96, 192) | 4 | 3 | BASIC | (4, 4, 4) |
| stage4 | (32, 64, 128, 256) | (48, 96, 192, 384) | 3 | 4 | BASIC | (4, 4, 4, 4) |
从源码 mmpose/models/backbones/hrnet.py 可以看出:
- HRNet 的核心思路是始终保留高分辨率分支:stage1 只有一个分支,stage2/3/4 逐步新增低分辨率分支,最终并行维护 4 个分辨率分支;
HRModule._make_fuse_layers(hrnet.py#L127-L192)实现多分辨率特征融合:高分辨率分支通过stride=2卷积下采样与低分辨率对齐,低分辨率分支通过nn.Upsample(scale_factor=2**(j-i), mode='nearest')上采样与高分辨率对齐,逐元素相加后经 ReLU 输出;HRNet.forward(hrnet.py#L561-L595)在 stage2/3/4 之间通过transition层(_make_transition_layer)对新分支做下采样生成,最终返回 4 个分辨率的特征列表y_list;- 检测头默认取
in_index=0,即 stage4 的第 0 个分支(分辨率最高、通道数为 32/48),这正是keypoint_head.in_channels=32/48的由来。
4.3 TopdownHeatmapSimpleHead:无转置卷积的轻量头
TopdownHeatmapSimpleHead 的实现见 mmpose/models/heads/topdown_heatmap_simple_head.py:
num_deconv_layers=0时,deconv_layers = nn.Identity()(L86-L87),即省去了传统 SimpleBaseline 中的三层转置卷积,这正是 HRNet 高分辨率特征的收益所在;final_conv_kernel=1表示最后一层用1x1卷积把输入通道映射到 17 个关节热图(kernel_size=1, padding=0,见 L92-L105);- 前向流程
forward(L197-L202)为x -> _transform_inputs -> deconv_layers -> final_layer,其中_transform_inputs按in_index=0选取最高分辨率特征; - 推理时
inference_model(L204-L227)会根据flip_pairs对翻转图的热图做flip_back融合,并在shift_heatmap=True时执行output_heatmap[:, :, :, 1:] = output_heatmap[:, :, :, :-1]的水平平移对齐——这就是test_cfg中翻转测试配置在源码层的落地。
4.4 损失函数:JointsMSELoss
JointsMSELoss 实现在 mmpose/models/losses/mse_loss.py#L8-L44:
- 对每个关节分别计算预测热图与目标热图之间的 MSE;
use_target_weight=True时,先按target_weight(来自joint_weights)对预测与目标热图逐元素加权再算损失,实现不同关节的不同惩罚权重(如腕部权重 1.5);- 最终取所有关节的平均并乘
loss_weight(默认 1.0)。
TopdownHeatmapSimpleHead.get_loss(topdown_heatmap_simple_head.py#L146-L168)将 loss 以 heatmap_loss 键返回;训练时还会通过 get_accuracy 计算 PCK 精度(pose_pck_accuracy,见 mmpose/core/evaluation/top_down_eval.py#L179)。
五、数据流水线:训练增强与热图生成
5.1 train_pipeline
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), # ≥8 个可见关节时以 0.3 概率裁剪半身
dict(type='TopDownGetRandomScaleRotation',
rot_factor=40, scale_factor=0.5), # 随机旋转 ±40°、尺度缩放 ±50%
dict(type='TopDownAffine'), # 仿射变换到 image_size
dict(type='ToTensor'),
dict(type='NormalizeTensor',
mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]), # ImageNet 归一化
dict(type='TopDownGenerateTarget', sigma=2), # 生成高斯热图;384x288 配置为 sigma=3
dict(type='Collect',
keys=['img', 'target', 'target_weight'],
meta_keys=['image_file','joints_3d','joints_3d_visible',
'center','scale','rotation','bbox_score','flip_pairs']),
]
需要特别注意的是 sigma 与输入分辨率的对应关系:256x192 配置使用 sigma=2,384x288 配置使用 sigma=3(见 hrnet_w32_coco_384x288.py#L110),目的是让高斯核在更高分辨率热图上保持大致一致的物理尺度。TopDownGenerateTarget 将 2D 关键点绘制为热图尺寸下的高斯峰,作为回归目标。
5.2 val_pipeline / test_pipeline
val_pipeline = [
dict(type='LoadImageFromFile'),
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='Collect', keys=['img'],
meta_keys=['image_file','center','scale','rotation','bbox_score','flip_pairs']),
]
test_pipeline = val_pipeline
验证与测试流水线只保留必要的对齐与归一化,不生成 target,同时保留 flip_pairs 元数据供翻转测试使用。
六、训练与验证配置:优化器、学习率与数据
6.1 优化器与学习率
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 衰减,并在前 500 步做线性 warmup(初始 lr 为 5e-4×0.001);
- 总训练 210 个 epoch,在第 170 与 200 epoch 各衰减一次(典型做法为 ×0.1);
- 每 10 个 epoch 在 val 上评估一次,以 mAP 为指标并保存 AP 最优的 checkpoint。
6.2 数据配置
data_root = 'data/coco'
data = dict(
samples_per_gpu=64, # 256x192 配置;384x288 配置为 32(显存考量)
workers_per_gpu=2,
val_dataloader=dict(samples_per_gpu=32),
test_dataloader=dict(samples_per_gpu=32),
train=dict(
type='TopDownCocoDataset',
ann_file=f'{data_root}/annotations/person_keypoints_train2017.json',
img_prefix=f'{data_root}/train2017/',
data_cfg=data_cfg,
pipeline=train_pipeline,
dataset_info={{_base_.dataset_info}}),
val=dict(type='TopDownCocoDataset',
ann_file=f'{data_root}/annotations/person_keypoints_val2017.json',
img_prefix=f'{data_root}/val2017/', ...),
test=dict(... 与 val 相同 ...),
)
两处细节值得留意:
- samples_per_gpu 随分辨率调整:256x192 配置为 64,384x288 配置降为 32(见 hrnet_w48_coco_384x288.py#L141),以控制单卡显存占用;
- 数据集类型为
TopDownCocoDataset,其实现位于 mmpose/datasets/datasets/top_down/topdown_coco_dataset.py(对应测试见 tests/test_datasets/test_top_down_dataset.py)。
数据目录需按 data/coco/annotations/...、data/coco/train2017/、data/coco/val2017/ 结构准备(下载与整理方式可参考 docs/en/data_preparation.md)。
七、训练、测试与推理演示:完整命令
7.1 单卡训练
python tools/train.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/hrnet_w32_coco_256x192.py
默认 work_dir 为 ./work_dirs/hrnet_w32_coco_256x192(由 tools/train.py#L96-L102 以配置文件名为基准生成)。常用参数:
python tools/train.py <config> \
--work-dir ./work_dirs/hrnet_w32_coco_256x192 \ # 自定义输出目录
--gpu-id 0 \ # 指定 GPU(非分布式)
--seed 0 --deterministic \ # 复现
--cfg-options model.backbone.with_cp=True \ # 覆盖任意配置项
--no-validate # 跳过训练中验证
--cfg-options 支持以 key=value 形式覆盖深层配置(tools/train.py#L56-L62),例如缩小 batch 或切换预训练权重。
7.2 分布式训练
仓库提供 tools/dist_train.sh 与 tools/slurm_train.sh:
bash tools/dist_train.sh \
configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/hrnet_w48_coco_384x288.py \
8
第二个参数为 GPU 数量,脚本内部通过 --launcher pytorch 走分布式流程(init_dist(args.launcher, **cfg.dist_params),见 tools/train.py#L132-L137)。
7.3 测试评估
python tools/test.py \
configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/hrnet_w32_coco_256x192.py \
<checkpoint.pth> \
--metrics mAP
评估时使用 val 数据与 bbox_file 中提供的检测框(use_gt_bbox=False),最终输出 mAP/AP/AR 指标;--metrics 支持多种指标(如 acc、mAP、AUC)。分布式评测可使用 tools/dist_test.sh。
7.4 发布模型(去除优化器状态)
python tools/publish_model.py \
work_dirs/hrnet_w32_coco_256x192/latest.pth \
hrnet_w32_coco_256x192
输出文件名形如 hrnet_w32_coco_256x192-{hash id}_{time_stamp}.pth(见 docs/en/useful_tools.md#L128-L131),可用于对外发布或部署。
7.5 图像推理演示
使用 demo/top_down_img_demo.py 可对 COCO 格式 JSON 中的检测框逐图推理并可视化:
python demo/top_down_img_demo.py \
configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/hrnet_w32_coco_256x192.py \
<checkpoint.pth> \
--img-root tests/data/coco/ \
--json-file tests/data/coco/test_coco.json \
--out-img-root vis_results
该脚本参数包括(demo/top_down_img_demo.py#L18-L51):--img-root(图片根目录)、--json-file(含 bbox 的 COCO JSON)、--show(窗口显示)、--out-img-root(输出目录)、--device(默认 cuda:0)、--kpt-thr(关键点置信度阈值,默认 0.3)、--radius/--thickness(可视化样式)。其内部通过 inference_top_down_pose_model 逐个 bbox 裁剪、仿射、前向得到热图并解码关键点(解码实现见 mmpose/core/evaluation/top_down_eval.py#L474 的 keypoints_from_heatmaps,其中 post_process='default' 即取热图最大响应位置)。
八、评测细节:翻转测试与热图解码
test_cfg 中的三项配置共同决定了评测精度,可结合源码理解其作用:
flip_test=True:推理时同时输入原图与水平翻转图,将翻转图的热图按flip_pairs(即 coco.py 中keypoint_info的swap字段,如left_shoulder ↔ right_shoulder)反向翻转后与原图热图取平均;shift_heatmap=True:由于翻转会导致特征错位,融合前将翻转热图水平平移一个像素(output_heatmap<a href="https://link.gitcode.com/i/900e3241ea6c2b46911600b10a7ccd4f" target="_blank">:, :, :, 1:] = output_heatmap[:, :, :, :-1],见 [topdown_heatmap_simple_head.py#L223-L224);post_process='default':keypoints_from_heatmaps(top_down_eval.py#L474)对每个关节取热图最大值(_get_max_preds,top_down_eval.py#L63)得到亚像素坐标,再经transform_preds(mmpose/core/post_processing/post_transforms.py#L150)按仿射参数映射回原图坐标;modulate_kernel=11:在post_process相关流程中配合使用的调制核尺寸参数(DARK 类后处理的卷积核大小),与post_process='default'搭配使用。
提示:仓库在相同目录下还提供了一系列 HRNet 变体配置(hrnet_dark_coco.md、hrnet_udp_coco.md、hrnet_fp16_coco.md、hrnet_augmentation_coco.md),分别对应 DARK 编码、UDP 无偏数据处理、FP16 混合精度与增强策略等进阶方向;ViTPose 系列骨干配置(如 ViTPose_base_coco_256x192.py)也沿用了本节相同的 topdown heatmap 框架,可直接对比不同骨干的精度表现。
结语
本文以 hrnet_coco.md 为线索,完整串联了 HRNet 在 COCO 上 top-down heatmap 姿态估计的配置、原理、训练与推理全链路:从 17 关节的 channel_cfg 与高斯热图生成,到 HRNet 四阶段多分辨率融合骨干、无转置卷积的 TopdownHeatmapSimpleHead 与加权 JointsMSELoss,再到翻转测试、学习率调度与分布式训练命令。掌握这套配置,即可举一反三地理解仓库内其他 topdown heatmap 模型(ResNet、MSPN、RSK 及 ViTPose 系列)的配置组织方式,并在 COCO 及自定义数据集上快速开展姿态估计实验。