ViTPose 仓库 CPM 人体姿态估计配置全解析:基于 COCO 的 Top-Down Heatmap 训练、测试与推理实践

原创2026-10-14 12:19:031,751 阅读
文章标签:人工智能计算机视觉深度学习机器学习

ViTPose 仓库 CPM 人体姿态估计配置全解析:基于 COCO 的 Top-Down Heatmap 训练、测试与推理实践

本文以 cpm_coco.md 为核心,围绕 ViTPose 仓库中 CPM(Convolutional Pose Machines,CVPR'2016)在 COCO 人体关键点数据集上的完整落地流程展开。你将从一份实验指标表出发,逐行读懂 cpm_coco_256x192.py / cpm_coco_384x288.py 的模型、数据与训练配置,并通过 CPM backbone 源码 与多阶段 Head 实现理解其"级联阶段精修热图"的底层原理,最终掌握使用 tools/train.py、tools/test.py 与 demo 脚本完成训练、评测与推理的完整技能。

一、模型与数据集背景

1.1 CPM:卷积姿态机

CPM 由 Wei 等人发表于 CVPR 2016(论文标题 Convolutional Pose Machines),是人体姿态估计领域的奠基性工作之一。其核心思想是通过多个级联的卷积阶段,逐级精修关节点的响应热图(heatmap):前一阶段的输出热图会被拼接回网络,作为后续阶段的输入,使网络能够隐式地学习关节间的空间约束关系,从而逐步修正早期阶段的定位误差。

本仓库中该算法的引用信息记录在 cpm_coco.md 的 bibtex 块中:

@inproceedings{wei2016convolutional,
  title={Convolutional pose machines},
  author={Wei, Shih-En and Ramakrishna, Varun and Kanade, Takeo and Sheikh, Yaser},
  booktitle={Proceedings of the IEEE conference on Computer Vision and Pattern Recognition},
  pages={4724--4732},
  year={2016}
}

1.2 COCO 数据集

实验评测使用的数据集为 Microsoft COCO(ECCV 2014,Microsoft COCO: Common Objects in Context),其 17 个人体关键点定义(nose、左右眼/耳、肩、肘、腕、髋、膝、踝)可在 coco.py 的 keypoint_info 与 topdown_coco_dataset.py 的注释中逐一对照。仓库内置的测试样例标注文件为 test_coco.json。

二、COCO val2017 上的官方评测结果

原文表格给出了在**检测器 human AP 为 56.4(COCO val2017)**条件下的结果,这是理解该模型精度的前提——Top-Down 方案的 AP 同时受检测框质量影响。两个分辨率的官方指标如下:

Arch Input Size AP AP50 AP75 AR AR50
cpm 256x192 0.623 0.859 0.704 0.686 0.903
cpm 384x288 0.650 0.864 0.725 0.708 0.905

两个可观察到的规律:

  • 分辨率提升带来明显增益:从 256x192 提升到 384x288 后,AP 从 0.623 提高到 0.650(+0.027),AP75 从 0.704 提升到 0.725,说明 CPM 对输入分辨率(进而热图分辨率)较为敏感。
  • AP50 与 AR50 接近上限:两档分辨率下均超过 0.85 / 0.90,说明粗粒度定位已较饱和,主要差距集中在精细定位(AP75)上。

原文档同时给出了官方训练好的权重与日志下载入口;在本仓库中,这两个实验的元信息还登记在 model-index.yml(对应条目 configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/cpm_coco.yml)。评测口径(mAP、OKS 阈值、NMS 逻辑)可继续参阅下文"六、评测与后处理"。

三、配置文件逐段拆解

两个分辨率配置结构完全相同,仅 image_size / heatmap_size 与 TopDownGenerateTarget 的 sigma(256x192 用 2,384x288 用 3)不同。以下以 cpm_coco_256x192.py 为例逐段说明。

3.1 基础继承与训练超参

_base_ = [
    '../../../../_base_/default_runtime.py',
    '../../../../_base_/datasets/coco.py'
]
evaluation = dict(interval=10, metric='mAP', save_best='AP')

optimizer = dict(
    type='Adam',
    lr=5e-4,
)
optimizer_config = dict(grad_clip=None)
# learning policy
lr_config = dict(
    policy='step',
    warmup='linear',
    warmup_iters=500,
    warmup_ratio=0.001,
    step=[170, 200])
total_epochs = 210
  • _base_ 引入了两套基础配置:default_runtime.py 提供 checkpoint 保存间隔(每 10 epoch)、日志钩子、分布式参数(backend='nccl')等运行期设置;coco.py 提供完整的 17 关键点定义、骨架连接、joint_weights 与 sigmas(用于 OKS 计算)。
  • evaluation:每 10 个 epoch 在验证集上计算 mAP,并依据 AP 保存最优模型。
  • 优化器为 Adam,lr=5e-4,无梯度裁剪;学习率采用 step 策略,在 170、200 epoch 处衰减;前 500 iter 线性 warmup,warmup 初始比例 0.001;总计训练 210 epochs。

3.2 通道配置

channel_cfg = dict(
    num_output_channels=17,
    dataset_joints=17,
    dataset_channel=[
        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
    ],
    inference_channel=[
        0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16
    ])

COCO 的 17 个关键点在配置中按 0~16 的索引顺序排列;dataset_channel 表示数据标注通道到模型输出的映射,inference_channel 表示推理时输出的关节顺序。两者在此均为恒等映射,因为 CPM 直接输出 17 通道热图。

3.3 模型结构

model = dict(
    type='TopDown',
    pretrained=None,
    backbone=dict(
        type='CPM',
        in_channels=3,
        out_channels=channel_cfg['num_output_channels'],
        feat_channels=128,
        num_stages=6),
    keypoint_head=dict(
        type='TopdownHeatmapMultiStageHead',
        in_channels=channel_cfg['num_output_channels'],
        out_channels=channel_cfg['num_output_channels'],
        num_stages=6,
        num_deconv_layers=0,
        extra=dict(final_conv_kernel=0, ),
        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))

各部分对应的源码实现:

  • type='TopDown':装配为 Top-Down 检测器,对应 top_down.py 中的 TopDown 类,其前向流程为 backbone → neck(可选) → keypoint_head,训练时调用 forward_train 计算 loss 与准确率,测试时调用 forward_test 做翻转测试(flip_test=True 时对原图与水平翻转图分别推理并取平均)。
  • type='CPM':主干网络,实现在 cpm.py,feat_channels=128、num_stages=6。与常见 backbone 不同,CPM 的"输出"是多个阶段的 17 通道热图列表,而不是单一特征图。
  • TopdownHeatmapMultiStageHead:多阶段热图 Head,实现在 topdown_heatmap_multi_stage_head.py。这里 num_stages=6 与 backbone 阶段数一致;num_deconv_layers=0 表示不使用反卷积上采样(热图分辨率直接由 backbone 的 stride 决定);final_conv_kernel=0 表示最终层使用恒等映射 nn.Identity()(源码中 0 代表 Identity)。
  • JointsMSELoss:加权 MSE 热图损失,实现在 mse_loss.py。use_target_weight=True 时按各关节可见性权重(来自 target_weight)参与损失计算;多阶段训练中,TopdownHeatmapMultiStageHead.get_loss 会对每个阶段输出的热图分别计算 MSE 并累加为 heatmap_loss。

test_cfg 三个参数的影响:

  • flip_test=True:测试时叠加翻转推理(见 top_down.py 的 forward_test,两路热图取平均)。
  • post_process='default':热图坐标后处理,对应 top_down_eval.py 中 keypoints_from_heatmaps 的 default 分支——在最大响应位置用相邻像素差分做 ±0.25 偏移修正。
  • modulate_kernel=11:与训练时 sigma=2 的高斯目标对应(源码注释明确 K=11 匹配 sigma=2,K=17 匹配 sigma=3),用于 megvii/unbiased 等后处理模式的调制。

3.4 数据配置

data_cfg = dict(
    image_size=[192, 256],
    heatmap_size=[24, 32],
    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',
)
  • image_size=[192, 256](宽、高)与 heatmap_size=[24, 32]:输入图与热图的宽高;热图分辨率约为输入的 1/8(CPM 的 stem 包含 3 次 stride=2 的 MaxPool)。
  • soft_nms=False、oks_thr=0.9、nms_thr=1.0、vis_thr=0.2:评测阶段 OKS-NMS 阈值、关键点可见性阈值等,被 topdown_coco_dataset.py 的 evaluate 消费。
  • use_gt_bbox=False:训练/验证不使用 GT 框,而使用外部检测器结果文件 COCO_val2017_detections_AP_H_56_person.json(human AP 56.4 的来源即此检测器),这也解释了原文档评测结果的附加前提。
  • det_bbox_thr=0.0:不对检测框置信度做额外过滤。

3.5 数据加载与数据集定义

data = dict(
    samples_per_gpu=64,
    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/',
        data_cfg=data_cfg,
        pipeline=val_pipeline,
        dataset_info={{_base_.dataset_info}}),
    test=dict(...))
  • 训练时每 GPU 64 张图(256x192 配置),验证/测试时每 GPU 32 张;data_root = 'data/coco',需按 data_preparation.md 准备 train2017/、val2017/ 图片与对应标注 json。
  • TopDownCocoDataset 实现在 topdown_coco_dataset.py,继承自 Kpt2dSviewRgbImgTopDownDataset。

四、CPM 主干网络源码实现

CPM 的网络结构在 cpm.py 中由四部分构成:

  1. stem:由 3 组"9x9 卷积 + MaxPool(3, stride=2)"下采样,再接 5x5 卷积降至 32 通道,最后经 512 通道的 1x1 卷积得到 stage-1 的 17 通道热图输出;
  2. middle:从原始输入并行提取的"中间特征"(同样经 3 次下采样,保持 128 通道),供后续阶段作为上下文拼接;
  3. cpm_stages:从 stage-2 到 stage-6 共 num_stages-1=5 个 CpmBlock,每个 block 由 3 层 11x11 卷积(128 通道)组成;
  4. out_convs:每个后续阶段末尾的 1x1 卷积,把 128 通道特征压缩回 17 通道热图。

阶段间信息流的实现要点在 forward 中:

inp_feat = torch.cat(
    [out_feats[-1], self.middle_convind], 1)
cpm_feat = single_stage(inp_feat)
out_feat = out_conv(cpm_feat)
out_feats.append(out_feat)

即将上一阶段的热图输出与经过下采样的中间特征在通道维拼接,送入当前阶段的 CpmBlock,这正是论文中"前序预测热图作为后续阶段输入"思想的直接体现。最终 forward 返回 6 个 (N, 17, H, W) 热图的列表,其中 H、W 由输入尺寸决定。

CpmBlock 还断言 len(channels) == len(kernels)(每层卷积都有对应核大小),默认每阶段 3 层 11x11 卷积。对应单元测试见 test_cpm.py:例如输入 256x192 时,单阶段输出形状为 (1, 17, 32, 24),与 heatmap_size=[24, 32](宽 24、高 32)严格对应。

五、训练与测试

5.1 数据准备

按 data_preparation.md 准备 COCO 数据,并放置检测框结果文件到 data/coco/person_detection_results/COCO_val2017_detections_AP_H_56_person.json(测试时用于裁剪人体区域)。

5.2 单卡训练

python tools/train.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/cpm_coco_256x192.py

tools/train.py 支持的关键参数:

  • --work-dir:日志与 checkpoint 输出目录;
  • --no-validate:跳过训练期间验证;
  • --gpu-id:指定 GPU;
  • --seed / --deterministic:复现实验;
  • --cfg-options:以 key=value 方式覆盖配置,例如 --cfg-options optimizer.lr=1e-3;
  • --autoscale-lr:按 GPU 数量自动缩放学习率。

5.3 多卡训练

bash tools/dist_train.sh configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/cpm_coco_256x192.py 8

tools/dist_train.sh 通过 torch.distributed.launch 启动 --nproc_per_node=$GPUS 的分布式训练,端口默认 29500,可通过环境变量 PORT 修改。另有 tools/slurm_train.sh 支持 Slurm 集群。

5.4 测试与评测

python tools/test.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/cpm_coco_256x192.py \
    /path/to/checkpoint.pth --eval mAP

tools/test.py 中 --eval mAP 触发 COCO 关键点 mAP 评测;其他有用参数:--out 保存结果、--fuse-conv-bn 融合卷积与 BN 以加速推理、--cfg-options 覆盖配置。多卡测试可运行 bash tools/dist_test.sh <config> <ckpt> 8 --eval mAP。评测时数据集端会先进行 关键点评分重打分(rescoring),再执行 OKS-NMS(oks_thr=0.9),最后调用 COCOeval 输出 AP/AP50/AP75/AR 系列指标,见 topdown_coco_dataset.py 的 evaluate 方法。

六、评测与后处理原理

从热图到最终坐标的链路位于 top_down_eval.py:

  1. _get_max_preds:取每通道热图的 argmax 得到像素级位置与置信度;
  2. post_process='default':对峰值邻域做 ±0.25 亚像素偏移修正;
  3. transform_preds:将热图坐标经仿射逆变换映射回原图坐标(基于 center / scale 元数据);
  4. 数据集端按可见性阈值 vis_thr 做重打分,再执行 OKS-NMS 抑制重叠框,最后用 COCO 官方评测计算 mAP。

在 TopdownHeatmapBaseHead.decode(topdown_heatmap_base_head.py)中,modulate_kernel 会传给 keypoints_from_heatmaps 作为高斯调制核大小。多阶段 Head 在推理时只取最后一个阶段的输出热图(output = output[-1]),并配合 shift_heatmap=True 对翻转热图做像素平移对齐(topdown_heatmap_multi_stage_head.py 的 inference_model),这与训练时对所有阶段热图计算损失形成"训练充分监督、推理取末级"的典型设计。

七、单图推理 Demo

使用 top_down_img_demo.py 可对单张图片进行可视化推理(需 --json-file 提供人体检测框):

python demo/top_down_img_demo.py \
    configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/cpm_coco_256x192.py \
    /path/to/checkpoint.pth \
    --img-root tests/data/coco/ \
    --json-file tests/data/coco/test_coco.json \
    --out-img-root vis_results/ \
    --show

脚本内部调用 mmpose/apis/inference.py 的 init_pose_model 与 inference_top_down_pose_model 完成模型初始化与关键点推理,再由 vis_pose_result 绘制骨架并输出到 --out-img-root。--kpt-thr 可调节关键点置信度显示阈值(默认 0.3)。测试样例图片(如 tests/data/coco/000000000785.jpg)可直接用于快速验证。

八、从配置到源码的关键对应关系

配置项 取值 对应源码 作用
model.type TopDown top_down.py Top-Down 检测器装配与前后向
backbone.type CPM cpm.py 6 阶段级联卷积姿态机
keypoint_head.type TopdownHeatmapMultiStageHead topdown_heatmap_multi_stage_head.py 多阶段热图输出与多阶段损失
loss_keypoint.type JointsMSELoss mse_loss.py 加权 MSE 热图损失
data_cfg.oks_thr 0.9 topdown_coco_dataset.py 评测期 OKS-NMS 阈值
test_cfg.post_process default top_down_eval.py 热图坐标亚像素修正
test_cfg.flip_test True top_down.py 翻转测试集成

九、小结与实践建议

CPM 在 ViTPose 仓库中以 6 阶段级联的形式落地为完整的 Top-Down 姿态估计方案:

  • 训练层面:Adam + 5e-4 初始学习率、step 衰减、210 epochs;多阶段 Head 对每级热图施加加权 MSE 监督,训练稳定、收敛曲线直观;
  • 精度层面:256x192 输入即可在 COCO val2017 上达到 0.623 AP,384x288 提升到 0.650 AP,适合作为精度与算力权衡的基线参考;
  • 工程层面:配置、主干、Head、损失、数据流水线与评测逻辑分层清晰,可直接以 cpm_coco_256x192.py 为模板,替换 _base_ 中的数据集文件(如 mpii.py、crowdpose.py)迁移到其他关键点任务。

对于希望深入研读的实现者,建议按 配置 → backbone(CPM) → multi-stage head → top_down_eval → dataset evaluate 的链路逐层阅读,即可完整还原从原始图片到 mAP 指标的全过程。

登录后查看全文
ViTPose