ViTPose 仓库 CPM 人体姿态估计配置全解析:基于 COCO 的 Top-Down Heatmap 训练、测试与推理实践
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 中由四部分构成:
stem:由 3 组"9x9 卷积 + MaxPool(3, stride=2)"下采样,再接 5x5 卷积降至 32 通道,最后经 512 通道的 1x1 卷积得到 stage-1 的 17 通道热图输出;middle:从原始输入并行提取的"中间特征"(同样经 3 次下采样,保持 128 通道),供后续阶段作为上下文拼接;cpm_stages:从 stage-2 到 stage-6 共num_stages-1=5个CpmBlock,每个 block 由 3 层 11x11 卷积(128 通道)组成;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:
_get_max_preds:取每通道热图的 argmax 得到像素级位置与置信度;post_process='default':对峰值邻域做 ±0.25 亚像素偏移修正;transform_preds:将热图坐标经仿射逆变换映射回原图坐标(基于center/scale元数据);- 数据集端按可见性阈值
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 指标的全过程。