ViTPose 仓库中基于 HRNet 的 AP-10K 动物姿态估计配置详解
ViTPose 仓库中基于 HRNet 的 AP-10K 动物姿态估计配置详解
AP-10K 是 NeurIPS'2021 发布的野外动物姿态估计基准(10 类动物、超过 10,000 张标注图片、17 个关键点)。本文以 ViTPose 仓库中 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/hrnet_ap10k.md 为骨架,完整解析 HRNet 系列在 AP-10K 上的 top-down 热图方案:从配置文件逐项拆解、训练与验证命令,到数据集实现与 mAP 评估的底层原理,读者可直接据此复现、微调与部署 HRNet 动物姿态模型。
AP-10K 基准与 17 关键点定义
AP-10K("AP-10K: A Benchmark for Animal Pose Estimation in the Wild",NeurIPS'2021 Datasets and Benchmarks Track)是一个面向真实野外场景的动物姿态估计数据集。它采用 COCO 风格的 keypoint 标注格式,每只动物标注 17 个关键点。
在 ViTPose 仓库中,AP-10K 的关键点与骨架定义集中在 configs/base/datasets/ap10k.py,关键点索引与名称如下(与 mmpose/datasets/datasets/animal/animal_ap10k_dataset.py 中记录一致):
| ID | 名称 | 部位 | 左右对称交换(swap) |
|---|---|---|---|
| 0 | L_Eye | 上部 | R_Eye |
| 1 | R_Eye | 上部 | L_Eye |
| 2 | Nose | 上部 | - |
| 3 | Neck | 上部 | - |
| 4 | Root of tail | 下部 | - |
| 5 | L_Shoulder | 上部 | R_Shoulder |
| 6 | L_Elbow | 上部 | R_Elbow |
| 7 | L_F_Paw | 上部 | R_F_Paw |
| 8 | R_Shoulder | 上部 | L_Shoulder |
| 9 | R_Elbow | 上部 | L_Elbow |
| 10 | R_F_Paw | 下部 | L_F_Paw |
| 11 | L_Hip | 下部 | R_Hip |
| 12 | L_Knee | 下部 | R_Knee |
| 13 | L_B_Paw | 下部 | R_B_Paw |
| 14 | R_Hip | 下部 | L_Hip |
| 15 | R_Knee | 下部 | L_Knee |
| 16 | R_B_Paw | 下部 | L_B_Paw |
ap10k.py 中还定义了骨架连线(skeleton_info)、各关节损失权重(joint_weights)以及用于 OKS 评估的关键点标准差(sigmas),例如前爪/后爪权重为 1.2、肘部与膝盖为 1.5,对应的 sigmas 值从 0.025(眼睛)到 0.107(髋部)不等,说明不同部位对定位误差的容忍度不同。
注意:仓库中该配置文件同样被 APT-36K 数据集复用,例如 ViTPose_base_ap10k_256x192.py 中
data_root = 'data/apt36k'但dataset_info仍继承自ap10k.py,这体现了_base_配置复用机制。
HRNet 在 AP-10K 上的模型库结果
原文档 hrnet_ap10k.md 给出了 HRNet 系列在 AP-10K 验证集上的官方结果,完整继承如下:
| 网络结构 | 输入尺寸 | AP | AP^50 | AP^75 | AP^M | AP^L | 权重 | 日志 |
|---|---|---|---|---|---|---|---|---|
| pose_hrnet_w32 | 256x256 | 0.738 | 0.958 | 0.808 | 0.592 | 0.743 | ckpt | log |
| pose_hrnet_w48 | 256x256 | 0.744 | 0.959 | 0.807 | 0.589 | 0.748 | ckpt | log |
从结果看,HRNet-w48 相比 w32 在整体 AP 上提升约 0.6 个百分点(0.744 vs 0.738),主要贡献来自大目标(AP^L 0.748 vs 0.743),而小目标 AP^M 反而略有下降(0.589 vs 0.592),这与更大的特征通道带来的细节分辨率收益在小目标上的边际效应有关。这些指标对应的模型元信息同样记录在 hrnet_ap10k.yml,供模型库索引使用。
上述结果对应的示例图片可参考仓库测试数据(000000000004.jpg 为 AP-10K 中的一帧野外动物图像):
配置文件逐项解析
HRNet 的两个配置 hrnet_w32_ap10k_256x256.py 与 hrnet_w48_ap10k_256x256.py 结构完全一致,仅在骨干网络宽度(32/48)与预训练权重上不同。下面以 w32 为例完整拆解。
配置继承(base)
_base_ = [
'../../../../_base_/default_runtime.py',
'../../../../_base_/datasets/ap10k.py'
]
- default_runtime.py:提供通用运行时设置,包括
checkpoint_config = dict(interval=10)(每 10 个 epoch 保存一次 checkpoint)、log_level = 'INFO'、dist_params = dict(backend='nccl')、分布式训练协议workflow = [('train', 1)],以及opencv_num_threads = 0与mp_start_method = 'fork'等性能相关设置。 - ap10k.py:提供
dataset_info,即上文的关键点、骨架、权重与 sigmas 定义。
训练与优化设置
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 在验证集上以
mAP评估一次,并依据AP保存最优模型; - 优化器为 Adam,初始学习率 5e-4,不做梯度裁剪;
- 学习率采用 step 衰减策略:线性 warmup 500 次迭代(初始比例为 0.001),在第 170 与 200 个 epoch 分别衰减;
- 总训练 210 个 epoch。
通道配置与数据裁剪
channel_cfg = dict(
num_output_channels=17,
dataset_joints=17,
dataset_channel=[[0, 1, 2, ..., 16]],
inference_channel=[0, 1, 2, ..., 16])
AP-10K 的标注通道与模型输出通道完全一致(均为 17,且无类别筛选),因此 dataset_channel 与 inference_channel 是逐一的恒等映射。对于多数据集拼接等更复杂的场景,这两个字段会承担通道重排的作用(详见 Kpt2dSviewRgbImgTopDownDataset 中 ann_info 的组装逻辑)。
data_cfg 则定义了关键的数据与后处理参数:
data_cfg = dict(
image_size=[256, 256],
heatmap_size=[64, 64],
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:1);use_gt_bbox=True:训练与验证均使用数据集的 GT 框而非检测框(AP-10K 数据集的_get_db中直接断言assert self.use_gt_bbox,参见 animal_ap10k_dataset.py),如需评测检测-姿态级联,可将bbox_file指向外部检测结果并调整det_bbox_thr;soft_nms=False、nms_thr=1.0、oks_thr=0.9控制评估时的 NMS 策略与阈值(见下文评估一节)。
模型结构
model = dict(
type='TopDown',
pretrained='https://download.openmmlab.com/mmpose/pretrain_models/hrnet_w32-36af842e.pth',
backbone=dict(
type='HRNet',
in_channels=3,
extra=dict(
stage1=dict(num_modules=1, num_branches=1, block='BOTTLENECK',
num_blocks=(4, ), num_channels=(64, )),
stage2=dict(num_modules=1, num_branches=2, block='BASIC',
num_blocks=(4, 4), num_channels=(32, 64)),
stage3=dict(num_modules=4, num_branches=3, block='BASIC',
num_blocks=(4, 4, 4), num_channels=(32, 64, 128)),
stage4=dict(num_modules=3, num_branches=4, block='BASIC',
num_blocks=(4, 4, 4, 4), num_channels=(32, 64, 128, 256)))),
keypoint_head=dict(
type='TopdownHeatmapSimpleHead',
in_channels=32,
out_channels=channel_cfg['num_output_channels'],
num_deconv_layers=0,
extra=dict(final_conv_kernel=1, ),
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))
- 整体检测器类型为
TopDown(top-down 两阶段:先检测框,再在框内回归关键点); - 骨干网络
HRNet的高分辨率多分支结构在 mmpose/models/backbones/hrnet.py 的HRNet类中实现,四个 stage 分别保持 1、2、3、4 个并行分支并逐级融合。w48 配置仅把各 stage 的num_channels替换为 (48, 96, 192, 384) 并更换预训练权重为hrnet_w48-8ef0771d.pth; - 关键点头使用
TopdownHeatmapSimpleHead(实现见 mmpose/models/heads/topdown_heatmap_simple_head.py)。HRNet 配置将其num_deconv_layers设为 0,即不经过反卷积,直接由高分辨率分支特征经 1×1 卷积输出 17 通道热图;这与 ResNet 方案(res50_ap10k_256x256.py中TopdownHeatmapSimpleHead默认 3 层反卷积,输入通道 2048)形成对比,也正是 HRNet 全程保持高分辨率表征的设计优势; - 训练损失为
JointsMSELoss(关节均方误差),use_target_weight=True表示按可见性加权; - 测试配置开启
flip_test=True(水平翻转测试融合),post_process='default'配合shift_heatmap=True与modulate_kernel=11进行热图解码偏移补偿与调制。解码阶段由 mmpose/core/evaluation/top_down_eval.py 中的_get_max_preds从热图取最大值位置,再经 post_transforms.py 的transform_preds反变换回原图坐标。
数据流水线(pipeline)
训练流水线(train_pipeline)按序执行:
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=[...]),
]
各环节作用:50% 概率水平翻转(配合 flip_pairs 做标签对称交换);30% 概率使用半身变换(当可见关节数 ≥ 8 时)以强化局部特征学习;随机旋转 ±40° 与缩放 ±50% 增强尺度鲁棒性;仿射变换把检测框裁剪到 256×256;随后转张量、按 ImageNet 均值和方差归一化;TopDownGenerateTarget 以高斯核 sigma=2 生成 64×64 热图目标;最后 Collect 收集 img、target、target_weight 以及元信息(image_file、joints_3d、center、scale、rotation、flip_pairs 等)供后处理使用。
验证/测试流水线 val_pipeline = test_pipeline 仅保留读取、仿射、归一化与 Collect(keys=['img']),不生成目标热图,且 samples_per_gpu 在验证/测试时降为 32(训练为 64),以适配显存与评估批次。
数据加载
data_root = 'data/ap10k'
data = dict(
samples_per_gpu=64,
workers_per_gpu=4,
train=dict(
type='AnimalAP10KDataset',
ann_file=f'{data_root}/annotations/ap10k-train-split1.json',
img_prefix=f'{data_root}/data/',
data_cfg=data_cfg,
pipeline=train_pipeline,
dataset_info={{_base_.dataset_info}}),
val=dict(...ap10k-val-split1.json...),
test=dict(...ap10k-test-split1.json...))
数据集的注册类为 AnimalAP10KDataset(继承自 Kpt2dSviewRgbImgTopDownDataset)。其 _load_coco_keypoint_annotation_kernel 会读取 COCO 风格标注、过滤空框/无关键点目标、把 bbox 通过 _xywh2cs(填充系数 1.25)转换为 (center, scale),并组织成 db 样本列表;评估部分通过 COCOeval(..., 'keypoints', sigmas) 完成,具体见 animal_ap10k_dataset.py。
训练、验证与推理
单卡/多卡训练
# 单卡训练(默认使用 0 号 GPU)
python tools/train.py \
configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/hrnet_w32_ap10k_256x256.py
# 指定工作目录与 GPU
python tools/train.py \
configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/hrnet_w32_ap10k_256x256.py \
--work-dir work_dirs/hrnet_w32_ap10k \
--gpu-id 1
# 多卡分布式训练(8 卡示例)
bash tools/dist_train.sh \
configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/hrnet_w32_ap10k_256x256.py 8
tools/train.py 支持 --resume-from(断点续训)、--no-validate(关闭训练中验证)、--seed/--deterministic(复现)、--cfg-options(命令行覆盖配置,如 model.backbone.extra.stage2.num_channels=...)以及 --launcher(none/pytorch/slurm/mpi)等参数;分布式训练还可用 tools/slurm_train.sh 提交 SLURM 任务。多卡场景可配合 --autoscale-lr 按 GPU 数量自动缩放学习率。
验证与测试
python tools/test.py \
configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/hrnet_w32_ap10k_256x256.py \
https://download.openmmlab.com/mmpose/animal/hrnet/hrnet_w32_ap10k_256x256-18aac840_20211029.pth \
--eval mAP \
--out results.pkl
--eval mAP 触发验证集上的 COCO keypoint 评估;--out 保存预测结果;--fuse-conv-bn 可在推理时融合卷积与 BN 略微提速。
评估流程与 mAP 计算原理
AnimalAP10KDataset.evaluate(见 animal_ap10k_dataset.py)内部执行以下步骤:
- 将模型输出的
preds、boxes、image_paths、bbox_ids按图像聚合,并按bbox_id排序去重; - 对每个检测结果做 rescoring:
score = 平均关键点置信度 × 框得分(仅统计超过vis_thr=0.2的关键点); - 对每张图执行 OKS NMS(
soft_nms=False时使用oks_nms,阈值oks_thr=0.9),OKS 相似度依赖sigmas; - 写出
result_keypoints.json,调用 COCOAPI 的COCOeval计算 AP / AP50 / AP75 / AP(M) / AP(L) 等指标(即 hrnet_ap10k.md 结果表中的全部指标)。
对应的单元测试位于 tests/test_datasets/test_animal_dataset.py(test_ap10k_dataset),使用 tests/data/ap10k/test_ap10k.json 构造数据集并验证 evaluate 返回 AP == 1.0,同时断言非 mAP 指标会抛出 KeyError——这印证了 AP-10K 数据集仅支持 mAP 一种评估指标。
图片与视频推理 Demo
仓库提供现成的 top-down 推理脚本(详见 demo/docs/2d_animal_demo.md):
# 单张图片(基于 GT 框 json)
python demo/top_down_img_demo.py \
configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/hrnet_w32_ap10k_256x256.py \
https://download.openmmlab.com/mmpose/animal/hrnet/hrnet_w32_ap10k_256x256-18aac840_20211029.pth \
--img-root tests/data/ap10k/ --json-file tests/data/ap10k/test_ap10k.json \
--out-img-root vis_results \
[--show --device cpu --kpt-thr 0.3]
若输入为完整画面(无检测框)的视频,可使用 demo/top_down_video_demo_full_frame_without_det.py;若需要端到端的"检测 + 姿态估计"流程,则可组合 demo/mmdetection_cfg/ 下的检测器配置与 demo/top_down_video_demo_with_mmdet.py。上述脚本的可视化实现位于 mmpose/core/visualization/image.py。
与同目录其他骨干的对比
ap10k 目录下同时提供 ResNet 与 ViTPose 系列配置,便于横向对比:
| 骨干 | 配置文件 | 输入尺寸 | 关键区别 |
|---|---|---|---|
| ResNet-50 | res50_ap10k_256x256.py | 256×256 | Simple Baseline:2048 通道特征 + 3 层反卷积上采样 |
| ResNet-101 | res101_ap10k_256x256.py | 256×256 | 同上,深度更深 |
| HRNet-w32 / w48 | 本文两个配置 | 256×256 | 全程高分辨率,无反卷积头 |
| ViTPose-Small | ViTPose_small_ap10k_256x192.py | 256×192 | ViT 骨干(patch 16,embed_dim 384,depth 12)+ 2 层反卷积头 |
ResNet 系列结果记录于 resnet_ap10k.md(ResNet-50 AP 0.699、ResNet-101 AP 0.698),均低于 HRNet 系列,反映了高分辨率表征在姿态估计任务中的优势。ViTPose 系列则展示了 Transformer 骨干在同一任务上的扩展性(Small/Large/Huge 三档配置齐全)。选择骨干时可参考本文的评估命令对验证集 AP 进行复测。
小结
本文完整继承了 hrnet_ap10k.md 的模型库结果,并围绕 hrnet_w32_ap10k_256x256.py 与 hrnet_w48_ap10k_256x256.py 两个配置,从数据集定义、优化策略、网络结构、数据流水线、训练/验证/推理命令到 mAP 评估源码逐层展开。核心要点:
- AP-10K 为 COCO 风格 17 关键点动物基准,关键点定义见 configs/base/datasets/ap10k.py;
- HRNet-w32/w48 均以 256×256 输入、64×64 热图训练 210 个 epoch,验证 AP 分别为 0.738 与 0.744;
- 数据集实现与 mAP 评估逻辑分别在 animal_ap10k_dataset.py 与 top_down_eval.py 中可查证;
- 单元测试 tests/test_datasets/test_animal_dataset.py 提供了开箱即用的回归验证样例。
读者只需准备好 data/ap10k 目录(annotations 三个 split 的 json 与 data/ 图片目录),即可按本文命令复现 HRNet 在 AP-10K 上的完整训练与评估流程。
