ViTPose 仓库 ResNet+SimpleBaseline2D 人体姿态估计实战:COCO Top-Down 热图配置、训练与评测深度解析
ViTPose 仓库 ResNet+SimpleBaseline2D 人体姿态估计实战:COCO Top-Down 热图配置、训练与评测深度解析
本篇技术指南以 ViTPose 仓库(基于 OpenMMLab MMPose 框架)中 configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/resnet_coco.md 模型库文档为核心,系统讲解以 ResNet 为骨干、采用 SimpleBaseline2D(ECCV 2018)解码头的二维人体关键点检测方案的完整落地路径:从 COCO 上的官方精度基准、逐字段剖析配置文件,到训练/测试命令与源码级原理。读完本文,你将掌握如何在 ViTPose 仓库中基于 ResNet-50/101/152 在 COCO 上训练、评测和部署 top-down 热图式姿态估计模型,并理解热图解码背后的实现细节。
一、模型背景:SimpleBaseline2D + ResNet + COCO 三者如何组合
该模型库文档(resnet_coco.md)开篇通过三组文献引用明确了技术栈的来源,分别对应算法、骨干网络与数据集三个层面:
- SimpleBaseline2D(ECCV 2018):Bin Xiao 等人提出的“简单基线”方案,论文 Simple baselines for human pose estimation and tracking。其核心思想是:在分类骨干(如 ResNet)之后接若干反卷积层(deconv)上采样特征,再通过 1×1 卷积输出每个关键点的热图,用极简结构逼近乃至超越当时复杂的多阶段方法。
- ResNet(CVPR 2016):Kaiming He 等人的 Deep residual learning for image recognition,作为特征提取骨干,通过残差连接缓解深层网络退化问题。仓库中对应实现位于 mmpose/models/backbones/resnet.py。
- COCO(ECCV 2014):Microsoft COCO 数据集提供 17 个身体关键点的标注(
person_keypoints_train2017.json/person_keypoints_val2017.json),其dataset_info定义(17 个关键点名称、左右交换对、骨架连接、关节权重与 sigma)完整存放在 configs/base/datasets/coco.py 中。
二、官方模型库基准:COCO val2017 上的完整精度表
resnet_coco.md 给出的结果基于“在 COCO val2017 上人体 AP 为 56.4 的检测器”提供的人体框(即文档中的 bbox_file 指向 data/coco/person_detection_results/COCO_val2017_detections_AP_H_56_person.json,仓库测试数据 tests/data/coco/test_coco_det_AP_H_56.json 同源)。完整继承原文档的精度基准如下:
| Arch | Input Size | AP | AP50 | AP75 | AR | AR50 | ckpt | log |
|---|---|---|---|---|---|---|---|---|
| pose_resnet_50 | 256x192 | 0.718 | 0.898 | 0.795 | 0.773 | 0.937 | res50_coco_256x192-ec54d7f3_20200709.pth |
res50_coco_256x192_20200709.log.json |
| pose_resnet_50 | 384x288 | 0.731 | 0.900 | 0.799 | 0.783 | 0.931 | res50_coco_384x288-e6f795e9_20200709.pth |
res50_coco_384x288_20200709.log.json |
| pose_resnet_101 | 256x192 | 0.726 | 0.899 | 0.806 | 0.781 | 0.939 | res101_coco_256x192-6e6babf0_20200708.pth |
res101_coco_256x192_20200708.log.json |
| pose_resnet_101 | 384x288 | 0.748 | 0.905 | 0.817 | 0.798 | 0.940 | res101_coco_384x288-8c71bdc9_20200709.pth |
res101_coco_384x288_20200709.log.json |
| pose_resnet_152 | 256x192 | 0.735 | 0.905 | 0.812 | 0.790 | 0.943 | res152_coco_256x192-f6e307c2_20200709.pth |
res152_coco_256x192_20200709.log.json |
| pose_resnet_152 | 384x288 | 0.750 | 0.908 | 0.821 | 0.800 | 0.942 | res152_coco_384x288-3860d4c9_20200709.pth |
res152_coco_384x288_20200709.log.json |
从表中可以读出两个明确的工程权衡规律:其一,同一骨干下将输入分辨率从 256×192 提升到 384×288,AP 普遍提升约 0.01~0.02(如 ResNet-50 从 0.718 到 0.731);其二,相同分辨率下加深骨干同样带来收益(256×192 下从 ResNet-50 的 0.718 到 ResNet-152 的 0.735)。这些权重与日志文件通过 OpenMMLab 官方模型库分发,可在 mmpose 生态的模型下载服务中获取(即原文档 ckpt/log 两列对应的资源,仓库侧由 model-index.yml 与各模型的 resnet_coco.yml 元数据登记,例如 resnet_coco.yml)。
三、配置文件逐字段剖析:以 res50_coco_256x192 为样本
六个模型共享同一套结构范式,差异仅在 backbone.depth、pretrained 与 data_cfg 的 image_size/heatmap_size。下面以 res50_coco_256x192.py 为完整样本展开。
3.1 配置继承与运行时基础
_base_ = [
'../../../../_base_/default_runtime.py',
'../../../../_base_/datasets/coco.py'
]
- default_runtime.py 提供运行时基础:
checkpoint_config = dict(interval=10)(每 10 个 epoch 存一次权重)、log_config(TextLoggerHook,每 50 次迭代打印)、dist_params = dict(backend='nccl')、workflow = [('train', 1)],并设置opencv_num_threads = 0与mp_start_method = 'fork'以避免 OpenCV 多线程导致系统过载、加速多进程启动。 - coco.py 定义完整的 COCO 17 关键点
dataset_info,其中joint_weights对手腕/脚踝等部位赋予更高权重(1.5),sigmas用于 OKS 评估中按关节部位缩放误差。
3.2 评估与优化策略
evaluation = dict(interval=10, metric='mAP', save_best='AP')
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
要点解读:
- 评估周期为 10 个 epoch,指标为 COCO
mAP,并以AP为保存最优模型的依据。 - 优化器使用 Adam,初始学习率 5e-4,不做梯度裁剪。
- 学习率采用 step 衰减:前 500 次迭代线性 warmup(起始比例为 0.001),在第 170 与第 200 个 epoch 分别衰减,总训练 210 个 epoch。从 tools/train.py 的
--autoscale-lr参数可知,若改变 GPU 数量,可按线性缩放规则(lr ∝ batch size)调整学习率。
3.3 模型结构:TopDown 检测器 + ResNet 骨干 + 简易热图头
model = dict(
type='TopDown',
pretrained='torchvision://resnet50',
backbone=dict(type='ResNet', depth=50),
keypoint_head=dict(
type='TopdownHeatmapSimpleHead',
in_channels=2048,
out_channels=channel_cfg['num_output_channels'],
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'对应 mmpose/models/detectors/top_down.py 中的TopDown类,它按backbone → neck(可选) → keypoint_head的顺序构建网络。训练时forward_train依次前向并调用head.get_loss/get_accuracy;测试时forward_test会在flip_test=True时对图像水平翻转再前向一次,将两路热图平均融合(output_heatmap = (output_heatmap + output_flipped_heatmap) * 0.5),这是 top-down 方案稳定提升精度的标准手段。 -
简易热图头:
TopdownHeatmapSimpleHead实现在 mmpose/models/heads/topdown_heatmap_simple_head.py。其构造函数默认num_deconv_layers=3、num_deconv_filters=(256, 256, 256)、num_deconv_kernels=(4, 4, 4)——即三个 stride=2 的转置卷积将 2048 通道的 ResNet 末层特征上采样 8 倍,再接一个 1×1 卷积(kernel_size=1, padding=0)输出 17 通道热图。_make_deconv_layer中每个 deconv 后跟BatchNorm2d + ReLU,权重初始化采用normal_init(std=0.001)。仓库单元测试 tests/test_models/test_top_down_head.py 的test_top_down_simple_head覆盖了不同num_deconv_layers/extra参数组合的构造与推理。 -
损失函数:
JointsMSELoss实现在 mmpose/models/losses/mse_loss.py,use_target_weight=True时按各关节的target_weight加权计算 MSE,即对难关节(如手腕、脚踝)的误差赋予更大惩罚;最终loss / num_joints * loss_weight归一化。
3.4 通道与数据配置:热图分辨率与高斯 sigma
channel_cfg = dict(
num_output_channels=17,
dataset_joints=17,
dataset_channel=[[0, 1, ..., 16]],
inference_channel=[0, 1, ..., 16])
COCO 的 17 个关键点索引与 coco.py 的 keypoint_info 一一对应(0=nose,1/2=左右眼……16=right_ankle),dataset_channel 与 inference_channel 在此场景下完全相同。
data_cfg = dict(
image_size=[192, 256], # 输入图像宽高
heatmap_size=[48, 64], # 热图宽高(输入的 1/4)
num_output_channels=17,
num_joints=17,
...
bbox_file='data/coco/person_detection_results/COCO_val2017_detections_AP_H_56_person.json')
image_size=[192, 256] 表示宽 192、高 256(对应 256x192 输入),heatmap_size=[48, 64] 是 1/4 分辨率热图。两个输入尺寸版本的关键差异:
| 配置 | image_size | heatmap_size | TopDownGenerateTarget sigma |
|---|---|---|---|
| res50_coco_256x192.py | [192, 256] | [48, 64] | sigma=2 |
| res50_coco_384x288.py | [288, 384] | [72, 96] | sigma=3 |
分辨率翻倍时热图高斯半径也相应增大(sigma 2→3),且 modulate_kernel=11 对应 sigma=2 的训练设置(源码注释明确 “K=17 for sigma=3 and k=11 for sigma=2”,见 top_down_eval.py 中 keypoints_from_heatmaps 的 kernel 参数说明)。该 test_cfg 三个字段直接决定了 topdown_heatmap_base_head.py decode 方法对热图的解码行为。
3.5 数据流水线:训练与验证的变换差异
训练流水线(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),
dict(type='Collect', keys=['img', 'target', 'target_weight'], meta_keys=[...])
- 水平翻转概率 0.5(配合
flip_pairs交换左右关节标签); - 半身变换:当图中可见关节数 ≥ 8 时以 0.3 概率只保留半身区域,强化局部特征学习;
- 随机缩放(scale_factor=0.5)与随机旋转(rot_factor=40 度);
- 仿射变换后张量化、按 ImageNet 统计做归一化;
TopDownGenerateTarget依据 sigma 生成高斯热图真值。
验证/测试流水线(val_pipeline / test_pipeline)则不包含随机增强与目标生成,仅做仿射、归一化与 Collect,保证评测确定性。
四、数据准备:COCO 与检测结果文件
训练前需将 COCO 数据按如下结构放置(仓库根目录下 data/coco/):
data/coco/
├── annotations/
│ ├── person_keypoints_train2017.json
│ └── person_keypoints_val2017.json
├── train2017/
├── val2017/
└── person_detection_results/
└── COCO_val2017_detections_AP_H_56_person.json
配置中 train/val/test 三段均使用 TopDownCocoDataset(实现见 mmpose/datasets/datasets/top_down 目录),其中 test 段复用 person_keypoints_val2017.json。bbox_file 指向预先用人体检测器(人体 AP 56.4)生成的检测框结果,这是 top-down 流程“先检测后关键点”的前提。
五、训练与测试:从单卡到分布式
5.1 训练
# 单 GPU
python tools/train.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/res50_coco_256x192.py
# 指定工作目录(默认输出到 work_dirs/res50_coco_256x192/)
python tools/train.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/res50_coco_256x192.py --work-dir work_dirs/res50_coco_256x192
# 8 卡分布式训练
./tools/dist_train.sh configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/res50_coco_256x192.py 8
# Slurm 集群(16 卡示例)
GPUS=16 GPUS_PER_NODE=8 CPUS_PER_TASK=2 ./tools/slurm_train.sh Test res50 \
configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/res50_coco_256x192.py work_dirs/res50_coco_256x192
getting_started.md 中特别说明 resume-from(恢复权重+优化器状态+epoch,用于断点续训)与 load-from(仅加载权重、从 0 开始,用于微调)的区别。使用 --cfg-options 可覆盖配置,例如把骨干换成 ResNet-18:--cfg-options model.backbone.depth=18。
5.2 测试与评测
# 单卡测试,输出 mAP
python tools/test.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/res50_coco_256x192.py \
checkpoints/res50_coco_256x192-ec54d7f3_20200709.pth --eval mAP
# 8 卡测试
./tools/dist_test.sh configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/res50_coco_256x192.py \
checkpoints/res50_coco_256x192-ec54d7f3_20200709.pth 8 --eval mAP
tools/test.py 内部会设置 cfg.model.pretrained = None 与 cfg.data.test.test_mode = True,加载权重后经 single_gpu_test/multi_gpu_test 得到预测,再由数据集 evaluate 按 --eval 指定指标(COCO 为 mAP)计算 AP/AP50/AP75/AR 等全套指标。--fuse-conv-bn 可将卷积与 BN 融合以小幅提速推理。
5.3 单图推理 Demo
使用真值框或检测框驱动的 top-down 图片 demo(demo/top_down_img_demo.py):
python demo/top_down_img_demo.py \
configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/res50_coco_256x192.py \
checkpoints/res50_coco_256x192-ec54d7f3_20200709.pth \
--img-root tests/data/coco/ --json-file tests/data/coco/test_coco.json \
--out-img-root vis_results
如需“检测器+姿态估计”端到端推理,可参考 demo/top_down_img_demo_with_mmdet.py 与 demo/mmdetection_cfg 下的人体检测配置。
六、从热图到关键点:后处理源码级原理
模型输出的是 [N, 17, H, W] 的响应热图,坐标解码链路如下:
-
翻转融合:
forward_test在flip_test=True时对翻转图再次前向,topdown_heatmap_simple_head.py 的inference_model调用flip_back(post_transforms.py)按flip_pairs交换左右通道并水平翻转,shift_heatmap=True时对翻转热图平移 1 像素以抵消翻转带来的特征错位,最后与原热图取平均。 -
峰值定位:top_down_eval.py 的
keypoints_from_heatmaps用_get_max_preds取每个通道 argmax 得到粗略坐标;post_process='default'时再对峰值邻域做 ±0.25 像素的亚像素偏移(比较左右、上下像素差值取符号),modulate_kernel=11作为高斯调制核参数(仅在megvii/unbiased模式使用)。 -
坐标还原:
transform_preds(post_transforms.py)结合center、scale将热图坐标映射回原图(scale 归一化因子 200),最终得到[K, 3](x, y, score)的人体关键点。
整条链路在 topdown_heatmap_base_head.py 的 decode 方法中统一起始,测试评估逻辑在 mmpose/core/evaluation/top_down_eval.py 完整可查。
七、扩展阅读:同目录下的进阶变体
同一目录(configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco)还提供了基于该基线的若干进阶配置,可在此基础上继续探索:
- dark 变体:
res50_coco_256x192_dark.py等,使用 Distribution-Aware 坐标表示(对应 resnet_dark_coco.md),通过post_process='unbiased'缓解量化偏差; - fp16 变体:
res50_coco_256x192_fp16_dynamic.py混合精度训练(对应 resnet_fp16_coco.md); - 其他骨干:同一 head 范式可无缝替换为 ResNeSt、ResNeXt、SEResNet、VGG 等骨干,均在同一目录下留有配置与模型库文档。
八、小结
以 resnet_coco.md 为索引,ViTPose 仓库完整承载了 “ResNet 骨干 + SimpleBaseline2D 简易热图头 + COCO top-down” 这条经典二维人体姿态估计技术路线:官方在 COCO val2017 上给出了从 ResNet-50 到 ResNet-152、两种输入分辨率共 6 组可复现的精度基准;配置层面可拆解为模型装配(top_down.py)、简易热图头(topdown_heatmap_simple_head.py)、加权 MSE 损失(mse_loss.py)与数据增强流水线四大部分;训练、测试与 demo 命令由 tools/train.py、tools/test.py 与 demo 目录提供完整入口。理解这条基线,也就掌握了仓库内绝大多数 top-down 热图方案(包括 ViTPose 系列)的公共骨架,是进入姿态估计实战的可靠起点。