ViTPose 仓库中的 AP-10K 动物姿态估计实战:基于 ResNet 的 Top-Down 热图方案完整解析
ViTPose 仓库中的 AP-10K 动物姿态估计实战:基于 ResNet 的 Top-Down 热图方案完整解析
本篇技术指南围绕 ViTPose 仓库中 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/ 目录下的 ResNet 系列配置展开,系统讲解如何在 AP-10K 动物姿态数据集上使用 Simple Baseline(ResNet 骨干 + 反卷积热图头)完成训练、验证与推理。读完本文,你将掌握 AP-10K 数据集的 17 关键点定义、res50_ap10k_256x256.py 与 res101_ap10k_256x256.py 两份配置的完整参数含义、底层数据集加载与评估流程,以及从零跑通训练测试的具体命令。
一、背景:AP-10K 数据集与 SimpleBaseline2D 方法
1.1 方法出处:SimpleBaseline2D(ECCV'2018)
本文涉及的模型配置对应经典论文 "Simple baselines for human pose estimation and tracking"(Bin Xiao 等,ECCV 2018)。该方法的核心思想非常简洁:在 ResNet 骨干网络输出的低分辨率特征图之后,堆叠若干反卷积层(deconv)将特征上采样,再用一层 1×1 卷积生成各关键点的热图,从而避免了复杂的手工设计模块。仓库中的实现证据位于 mmpose/models/heads/topdown_heatmap_simple_head.py,TopdownHeatmapSimpleHead 默认包含 3 层反卷积(每层 256 个滤波器、4×4 卷积核、stride=2),配合 BN 与 ReLU,最后接 1×1 卷积输出通道数为关键点数的热图。
1.2 数据集出处:AP-10K(NeurIPS'2021)
AP-10K 是由 "AP-10K: A Benchmark for Animal Pose Estimation in the Wild"(Hang Yu 等,NeurIPS 2021 Datasets and Benchmarks Track)提出的野外动物姿态估计基准,图像来自真实野外环境,覆盖多种动物类别,标注了 17 个语义关键点。仓库中数据集类 AnimalAP10KDataset 的实现位于 mmpose/datasets/datasets/animal/animal_ap10k_dataset.py,其注释明确引用了该论文。
二、官方实验结果(验证集指标)
原文档 resnet_ap10k.md 给出了两个 ResNet 配置在 AP-10K 验证集上的完整结果,输入尺寸均为 256×256,评估指标遵循 COCO Keypoint 风格(AP、AP⁵⁰、AP⁷⁵,并按目标尺度分 APᴹ 与 APᴸ):
| Arch | Input Size | AP | AP⁵⁰ | AP⁷⁵ | APᴹ | APᴸ | ckpt | log |
|---|---|---|---|---|---|---|---|---|
| pose_resnet_50 | 256×256 | 0.699 | 0.940 | 0.760 | 0.570 | 0.703 | ckpt | log |
| pose_resnet_101 | 256×256 | 0.698 | 0.943 | 0.754 | 0.543 | 0.702 | ckpt | log |
可以观察到:在 AP-10K 验证集上 ResNet-50 与 ResNet-101 的总体 AP 几乎持平(0.699 vs 0.698),说明在 256×256 输入下该数据集的难度瓶颈更多集中在数据本身而非骨干容量;而 ResNet-50 在中尺度目标(APᴹ 0.570 vs 0.543)上反而略占优势。这一现象也印证了简单基线方法在小尺寸输入下的实用性。
三、配置文件逐段精解
两份配置 res50_ap10k_256x256.py 与 res101_ap10k_256x256.py 的差异仅在于 pretrained 与 backbone.depth(50/101),其余完全一致。下面以 res50_ap10k_256x256.py 为准逐段解读。
3.1 基础配置继承
_base_ = [
'../../../../_base_/default_runtime.py',
'../../../../_base_/datasets/ap10k.py'
]
evaluation = dict(interval=10, metric='mAP', save_best='AP')
- 继承自 default_runtime.py:每 10 个 epoch 保存一次 checkpoint、日志级别 INFO、
dist_params = dict(backend='nccl')、workflow = [('train', 1)],并关闭 OpenCV 多线程(opencv_num_threads = 0)以避免系统过载。 - 继承自 ap10k.py:该文件定义了 AP-10K 的
dataset_info(见第四节)。 - 评估策略:每 10 个 epoch 在验证集上评测一次,指标为
mAP,并根据AP决定最优模型保存。
3.2 优化器与学习率策略
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
- 采用 Adam 优化器,初始学习率
5e-4,不做梯度裁剪。 - 学习率采用阶梯式衰减:线性 warmup 500 个 iteration(起始学习率为
lr * 0.001),在第 170 与 200 个 epoch 处分别衰减,总训练周期为 210 个 epoch。这套设置与 Simple Baseline 论文中"长训练 + 阶梯衰减"的习惯一致,是复现表中指标的关键超参。 - 日志配置中
interval=1(每个 iteration 打印一次日志)是训练侧显式覆盖了基线的interval=50,便于监控。
3.3 通道配置:17 关键点映射
channel_cfg = dict(
num_output_channels=17,
dataset_joints=17,
dataset_channel=[[0, 1, ..., 16]],
inference_channel=[0, 1, ..., 16])
num_output_channels:模型输出的热图通道数,等于关键点数 17。dataset_channel:数据集中实际使用的关键点通道映射,此处为全部 17 个。inference_channel:推理阶段输出的通道顺序,与dataset_channel相同(无通道重排需求)。
3.4 模型结构: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':两阶段 top-down 检测器,先由检测框裁出实例,再回归单实例关键点。对应实现见 mmpose/models/detectors/top_down.py。pretrained='torchvision://resnet50':加载 torchvision 提供的 ImageNet 预训练权重。backbone=dict(type='ResNet', depth=50):实现位于 mmpose/models/backbones/resnet.py,输出 2048 维特征图(ResNet-50/101 的 stage4 输出均为 2048 通道,这也是in_channels=2048的由来)。keypoint_head:TopdownHeatmapSimpleHead,输入 2048 通道,输出 17 通道热图;损失为带目标权重的JointsMSELoss(use_target_weight=True,即仅对可见关键点计算 MSE)。该 head 的默认结构为 3 层反卷积(256→256→256,卷积核 4×4)+ 1×1 卷积,可在 topdown_heatmap_simple_head.py 中确认。test_cfg四项关键推理参数:flip_test=True:开启水平翻转测试(TTA),将原图与翻转图的热图按flip_pairs对齐融合,通常可带来稳定提升;post_process='default':使用默认的热图后处理(取最大响应位置并按核大小调制坐标偏移);shift_heatmap=True:翻转热图由于特征未对齐存在半像素偏移,推理时左移一个像素以补偿;modulate_kernel=11:坐标调制核大小,用于亚像素精度的关键点定位细化。
3.5 数据配置 data_cfg
data_cfg = dict(
image_size=[256, 256],
heatmap_size=[64, 64],
num_output_channels=17,
num_joints=17,
dataset_channel=..., inference_channel=...,
soft_nms=False,
nms_thr=1.0,
oks_thr=0.9,
vis_thr=0.2,
use_gt_bbox=True,
det_bbox_thr=0.0,
bbox_file='',
)
image_size=[256, 256]:网络输入尺寸;heatmap_size=[64, 64]:热图输出尺寸(相对输入 4× 下采样,对应反卷积网络的分辨率)。- NMS 相关参数在评估阶段生效:
soft_nms=False使用标准 OKS-NMS,nms_thr=1.0(此处实际走 OKS 阈值)、oks_thr=0.9、vis_thr=0.2(关键点可见性阈值,用于重打分,即score = 关键点平均分 × 框得分)。 use_gt_bbox=True:训练与验证阶段直接使用标注框,无需外部检测器;det_bbox_thr=0.0、bbox_file=''因此保持默认。这也意味着表中所列指标是在"给定真实框"的假设下评测的。
3.6 训练与验证数据流水线
训练流水线(train_pipeline)按顺序执行:
LoadImageFromFile:读取图像;TopDownRandomFlip(flip_prob=0.5):随机水平翻转,并按flip_pairs同步交换左右关键点;TopDownHalfBodyTransform(num_joints_half_body=8, prob_half_body=0.3):以 0.3 概率只保留上半身/下半身区域做增强;TopDownGetRandomScaleRotation(rot_factor=40, scale_factor=0.5):随机旋转 ±40°、随机缩放 0.5~1.5 倍;TopDownAffine:按 center/scale/rotation 做仿射变换;ToTensor+NormalizeTensor(ImageNet 均值为[0.485, 0.456, 0.406]、标准差[0.229, 0.224, 0.225]);TopDownGenerateTarget(sigma=2):以高斯核(标准差 2 像素)生成 64×64 的目标热图;Collect:收集img/target/target_weight及image_file/joints_3d/center/scale/rotation/bbox_score/flip_pairs等元信息。
验证/测试流水线只包含读取、仿射、归一化与 Collect(无需数据增强与目标热图生成)。这些变换类均注册于 mmpose/datasets/pipelines/top_down_transform.py。
3.7 数据装载
data_root = 'data/ap10k'
data = dict(
samples_per_gpu=64,
workers_per_gpu=4,
val_dataloader=dict(samples_per_gpu=32),
test_dataloader=dict(samples_per_gpu=32),
train=dict(type='AnimalAP10KDataset', ann_file=...ap10k-train-split1.json, ...),
val=dict(type='AnimalAP10KDataset', ann_file=...ap10k-val-split1.json, ...),
test=dict(type='AnimalAP10KDataset', ann_file=...ap10k-test-split1.json, ...),
)
- 数据根目录为
data/ap10k,训练/验证/测试标注分别为annotations/ap10k-train-split1.json、ap10k-val-split1.json、ap10k-test-split1.json,图像前缀为data/ap10k/data/。 - 单卡 batch size 64、4 个加载 worker;验证与测试 batch size 32。
四、AP-10K 数据集信息:17 个关键点与骨架定义
数据集元信息定义在 configs/base/datasets/ap10k.py(以及同内容的 ap10k_info.py)中,它同时服务于模型训练时的通道映射、翻转配对与评估时的 OKS 计算:
- 17 个关键点(按索引):
L_Eye、R_Eye、Nose、Neck、Root of tail、L_Shoulder、L_Elbow、L_F_Paw、R_Shoulder、R_Elbow、R_F_Paw、L_Hip、L_Knee、L_B_Paw、R_Hip、R_Knee、R_B_Paw。 - 左右对称配对(
swap字段):左右眼、肩、肘、前掌、髋、膝、后掌一一互换,供翻转增强与flip_test使用。 - 骨架连接:
skeleton_info定义了 17 条连线(眼-眼、眼-鼻、鼻-颈、颈-尾根、四肢链等),用于可视化。 - OKS 关键参数:
sigmas数组(如眼部 0.025、膝关节 0.087、前掌 0.062 等)是 OKS 评估中按关键点归一化的标准差;joint_weights中膝/掌等部位权重更高(最高 1.5),体现不同部位在损失中的相对重要性。
五、源码级原理:数据加载与评估流程
5.1 数据集类 AnimalAP10KDataset
AnimalAP10KDataset(animal_ap10k_dataset.py)继承自 Kpt2dSviewRgbImgTopDownDataset(kpt_2d_sview_rgb_img_top_down_dataset.py),核心逻辑:
__init__中强制use_gt_bbox=True(assert self.use_gt_bbox),从 COCO 风格标注中逐图解析实例;- 每个实例经
_xywh2cs将检测框转换为center与scale(padding=1.25,并按image_size长宽比修正,像素标准差取 200),见 kpt_2d_sview_rgb_img_top_down_dataset.py; __getitem__深拷贝 db 条目并附加ann_info后送入Compose(pipeline),完成增强与目标生成。
5.2 评估流程(mAP)
evaluate 方法仅接受 mAP 指标(传入 <a href="https://link.gitcode.com/i/1aa71e8c44a34057268c4a407c1458d9" target="_blank">'PCK'] 会抛出 KeyError,这一点在 [tests/test_datasets/test_animal_dataset.py 中有专门测试)。流程为:
- 汇总每张图的多实例预测,按
bbox_id排序去重; - 以
vis_thr=0.2对关键点打分并重打分(score = 关键点均值 × 框得分); - 若
use_nms=True,则按soft_nms开关选择soft_oks_nms或oks_nms,以oks_thr=0.9、sigmas来自数据集信息进行后处理; - 写出
result_keypoints.json,调用xtcocotools.cocoeval.COCOeval(animal_ap10k_dataset.py)统计AP / AP .5 / AP .75 / AP (M) / AP (L) / AR等 10 项指标,文档表格中的 AP 系列即来源于此。
5.3 单元测试佐证
仓库测试 test_animal_dataset.py 使用 tests/data/ap10k/test_ap10k.json 与 2 张示例图,覆盖了 AnimalAP10KDataset 的构建、索引采样与 mAP 评估(构造完全正确的预测时 AP == 1.0),可作为读者自行验证数据流正确性的参考。
六、训练与测试命令
假设 AP-10K 数据已按 data/ap10k 目录结构就位(标注在 annotations/ 下、图像在 data/ 下),即可按 getting_started.md 中的标准流程执行:
单卡训练:
python tools/train.py configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/res50_ap10k_256x256.py \
--work-dir work_dirs/res50_ap10k_256x256
多卡分布式训练(假设 8 卡):
bash tools/dist_train.sh configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/res50_ap10k_256x256.py 8
单卡测试(使用文档表格中的官方权重):
python tools/test.py configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/res50_ap10k_256x256.py \
https://download.openmmlab.com/mmpose/animal/resnet/res50_ap10k_256x256-35760eb8_20211029.pth \
--eval mAP
测试入口脚本为 tools/test.py,训练入口为 tools/train.py。如需调整输入尺寸、骨干深度或增强强度,直接修改配置中的 image_size、backbone.depth、rot_factor 等字段即可,两份 ResNet 配置共用同一套结构与流水线,改动一处即可迁移。
七、总结
本文以 resnet_ap10k.md 为骨架,完整还原了 ViTPose 仓库中 AP-10K 上 ResNet 基线的官方结果,并逐字段解读了 res50/res101_ap10k_256x256.py 的模型结构、数据管线、优化策略与评估配置,进一步下沉到 AnimalAP10KDataset 的加载-增强-评估源码链路,最终给出可直接复现的训练/测试命令。无论是想快速复现表格指标,还是在此基础上替换骨干(如切换为 ViTPose 系列的 Vision Transformer 骨干)或调整数据增强,这份配置都是可靠且最小的改造起点。