基于 HRNet 的 COCO 人体姿态估计:ViTPose 仓库 topdown heatmap 配置全解析

原创2026-10-13 13:35:451,862 阅读
文章标签:人工智能计算机视觉深度学习机器学习

基于 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 相同 ...),
)

两处细节值得留意:

数据目录需按 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 及自定义数据集上快速开展姿态估计实验。

登录后查看全文
ViTPose