ViTPose 仓库中的 AP-10K 动物姿态估计实战:基于 ResNet 的 Top-Down 热图方案完整解析

原创2026-10-14 20:55:521,871 阅读
文章标签:人工智能计算机视觉深度学习机器学习

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)按顺序执行:

  1. LoadImageFromFile:读取图像;
  2. TopDownRandomFlip(flip_prob=0.5):随机水平翻转,并按 flip_pairs 同步交换左右关键点;
  3. TopDownHalfBodyTransform(num_joints_half_body=8, prob_half_body=0.3):以 0.3 概率只保留上半身/下半身区域做增强;
  4. TopDownGetRandomScaleRotation(rot_factor=40, scale_factor=0.5):随机旋转 ±40°、随机缩放 0.5~1.5 倍;
  5. TopDownAffine:按 center/scale/rotation 做仿射变换;
  6. ToTensor + NormalizeTensor(ImageNet 均值为 [0.485, 0.456, 0.406]、标准差 [0.229, 0.224, 0.225]);
  7. TopDownGenerateTarget(sigma=2):以高斯核(标准差 2 像素)生成 64×64 的目标热图;
  8. 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 中有专门测试)。流程为:

  1. 汇总每张图的多实例预测,按 bbox_id 排序去重;
  2. 以 vis_thr=0.2 对关键点打分并重打分(score = 关键点均值 × 框得分);
  3. 若 use_nms=True,则按 soft_nms 开关选择 soft_oks_nms 或 oks_nms,以 oks_thr=0.9、sigmas 来自数据集信息进行后处理;
  4. 写出 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 骨干)或调整数据增强,这份配置都是可靠且最小的改造起点。

登录后查看全文
ViTPose