MMPose 二维动物关键点数据集全指南:Animal-Pose、AP-10K 等 9 大数据集的准备、解析与训练实践
MMPose 二维动物关键点数据集全指南:Animal-Pose、AP-10K 等 9 大数据集的准备、解析与训练实践
MMPose 的二维动物姿态估计(2D Animal Keypoint)模块面向科研与工业场景,统一支持 9 个主流动物关键点数据集:Animal-Pose、AP-10K、Horse-10、MacaquePose、Vinegar Fly、Desert Locust、Grévy's Zebra、ATRW 与 Animal Kingdom。本文以官方数据集指南为主体,结合仓库源码、配置与转换工具,完整讲解每个数据集的下载方式、目录结构、标注格式、解析脚本与训练配置,读完即可在本地按规范准备好任意动物数据集并跑通 Top-Down 训练与评测流程。
数据集准备总览与目录规范
所有动物数据集的准备遵循统一的约定:将数据集根目录软链接(symlink)到 $MMPOSE/data 下,即仓库根目录的 data/ 文件夹。若你的目录结构与约定不同,需要同步修改配置文件中的 data_root 路径。
MMPose 当前支持的 2D 动物关键点数据集与来源如下:
- Animal-Pose(ICCV'2019)
- AP-10K(NeurIPS'2021)
- Horse-10(WACV'2021)
- MacaquePose(bioRxiv'2020)
- Vinegar Fly / Desert Locust / Grévy's Zebra(均来自 DeepPoseKit-Data,2019)
- ATRW(ACM MM'2020)
- Animal Kingdom(CVPR'2022)
从仓库结构看,这 9 个数据集在代码层面被统一抽象为 mmpose/datasets/datasets/animal/ 下的 9 个 Dataset 类,全部继承自 BaseCocoStyleDataset(见 mmpose/datasets/datasets/animal/init.py),即所有动物数据集的标注都被整理成了 COCO 风格 JSON,因此可以复用一套数据加载、评估逻辑。
Animal-Pose(ICCV'2019)
论文与标注格式
Animal-Pose 提出"跨域自适应"方法解决宠物/牲畜姿态估计问题,标注了 5 个类别(狗、猫、羊、牛、马),共 20 个关键点:双眼、双耳根、鼻子、喉部、尾根、鬐甲,以及四肢的肘、膝、掌(如 L_F_Elbow、R_B_Knee、L_F_Paw 等)。关键点定义可在 AnimalPoseDataset 类的 docstring 与 configs/base/datasets/animalpose.py 中查到,后者还给出了每个关键点的 color、type(upper/lower)、左右对称 swap 关系、用于 OKS 评估的 sigmas 与损失加权 joint_weights。
准备步骤
- 下载 PASCAL VOC2012 的图像,取 dog、cat、sheep、cow、horse 五类作为 trainval 数据;
- 下载官方 test-set(1000 张图像、5 个类别),其中包含原始标注;
- 下载 MMPose 预处理后的标注文件(
animalpose_annotations.tar)。官方标注需要额外处理才能被 MMPose 读取,因此建议直接使用预处理标注;若希望自行生成,可参考解析脚本 tools/dataset_converters/parse_animalpose_dataset.py。
将解压后的目录整理为如下结构:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── animalpose
│
│-- VOC2012
│ │-- Annotations
│ │-- ImageSets
│ │-- JPEGImages
│ │-- SegmentationClass
│ │-- SegmentationObject
│
│-- animalpose_image_part2
│ │-- cat
│ │-- cow
│ │-- dog
│ │-- horse
│ │-- sheep
│
│-- annotations
│ │-- animalpose_train.json
│ |-- animalpose_val.json
│ |-- animalpose_trainval.json
│ │-- animalpose_test.json
│
│-- PASCAL2011_animal_annotation
│ │-- cat
│ │ |-- 2007_000528_1.xml
│ │ |-- 2007_000549_1.xml
│ │ │-- ...
│ │-- cow
│ │-- dog
│ │-- horse
│ │-- sheep
│
│-- annimalpose_anno2
│ │-- cat
│ │ |-- ca1.xml
│ │ |-- ca2.xml
│ │ │-- ...
│ │-- cow
│ │-- dog
│ │-- horse
│ │-- sheep
官方划分与自建划分
官方数据集没有提供官方的 train/val/test 划分,MMPose 的约定是:从 PascalVOC 中选取图像作为 train+val,共 3608 张图像、5117 个标注实例,其中训练集 2798 张图像 / 4000 个标注,验证集 810 张图像 / 1117 个标注;其余来源的 1000 张图像 / 1000 个标注用作测试集。
训练配置示例
以 HRNet-w32 为例,配置文件位于 configs/animal_2d_keypoint/topdown_heatmap/animalpose/td-hm_hrnet-w32_8xb64-210e_animalpose-256x256.py,关键部分如下:
- 数据集类型:
dataset_type = 'AnimalPoseDataset',data_root = 'data/animalpose/',训练/验证标注分别为annotations/animalpose_train.json与annotations/animalpose_val.json; - 编码器:
MSRAHeatmap,输入 256×256,热图 64×64,sigma=2; - 输出通道:
out_channels=20,对应 20 个动物关键点; - 训练策略:210 个 epoch,Adam(lr=5e-4),
LinearLR预热 500 步后接MultiStepLR(milestones=[170, 200],gamma=0.1),每 10 个 epoch 验证一次,并按coco/AP保存最优 checkpoint; - 数据增强:
RandomFlip、RandomHalfBody、RandomBBoxTransform+TopdownAffine; - 评估器:
CocoMetric,直接使用data/animalpose/annotations/animalpose_val.json。
AP-10K(NeurIPS'2021)
数据集规模与特点
AP-10K 是"野外环境"动物姿态估计基准,标注了 50 个动物物种、10015 张图像、13028 个实例,每个实例 17 个关键点(双眼、鼻子、颈部、尾根以及四肢的肩/肘/前掌/髋/膝/后掌)。关键点完整定义见 configs/base/datasets/ap10k.py 与 AP10KDataset。
注意:官方明确要求该数据与标注仅供非商业用途。
目录结构
图像与标注统一从官方下载(ap10k 压缩包),解压到 {MMPose}/data 后整理为:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── ap10k
│-- annotations
│ │-- ap10k-train-split1.json
│ |-- ap10k-train-split2.json
│ |-- ap10k-train-split3.json
│ │-- ap10k-val-split1.json
│ |-- ap10k-val-split2.json
│ |-- ap10k-val-split3.json
│ |-- ap10k-test-split1.json
│ |-- ap10k-test-split2.json
│ |-- ap10k-test-split3.json
│-- data
│ │-- 000000000001.jpg
│ │-- 000000000002.jpg
│ │-- ...
标注目录下的 JSON 已按 7:1:2 比例随机划分为 train/val/test 三份,每份又提供 split1/2/3 三个等价划分,便于多次实验取平均。
RTMPose 训练配置示例
AP-10K 是 MMPose 中动物姿态的主流训练集,RTMPose-m 配置见 configs/animal_2d_keypoint/rtmpose/ap10k/rtmpose-m_8xb64-210e_ap10k-256x256.py,与 HRNet 配置相比特点鲜明:
- 数据集:
dataset_type = 'AP10KDataset',data_root = 'data/ap10k/',训练/验证/测试分别用ap10k-train-split1.json、ap10k-val-split1.json、ap10k-test-split1.json,图像前缀为data_prefix=dict(img='data/'); - 编码器:
SimCCLabel,输入 256×256,sigma=(5.66, 5.66),simcc_split_ratio=2.0; - 模型:CSPNeXt(mmdet 作用域)+
RTMCCHead,输出 17 通道,配KLDiscretLoss; - 两阶段训练:前 180 epoch 使用较强增强(
scale_factor=[0.6,1.4]、rotate_factor=80、CoarseDropoutp=1.0),最后 30 epoch 通过PipelineSwitchHook切换到弱增强(p=0.5)微调; - 其他细节:AdamW(lr=4e-3、weight_decay=0.05)、CosineAnnealingLR、
EMAHook、auto_scale_lr(base_batch_size=512),测试与验证使用独立评估器。
Horse-10(WACV'2021)
Horse-10 是马匹姿态数据集,主要研究预训练对跨域鲁棒性的提升。图像需从官网下载,标注使用 MMPose 预处理后的 horse10_annotations.tar。根据作者要求,该数据同样仅供非商业用途。
整理后的目录结构:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── horse10
│-- annotations
│ │-- horse10-train-split1.json
│ |-- horse10-train-split2.json
│ |-- horse10-train-split3.json
│ │-- horse10-test-split1.json
│ |-- horse10-test-split2.json
│ |-- horse10-test-split3.json
│-- labeled-data
│ │-- BrownHorseinShadow
│ │-- BrownHorseintoshadow
│ │-- ...
对应的数据集类为 Horse10Dataset,元信息(关键点、骨架、sigmas)定义在 configs/base/datasets/horse10.py。仓库提供了完整的训练配置,位于 configs/animal_2d_keypoint/topdown_heatmap/horse10。
MacaquePose(bioRxiv'2020)
MacaquePose 是"野外"猕猴姿态数据集,用于无标记动作捕捉(markerless motion capture)研究,共 17 个关键点(鼻、双眼、双耳、双肩、双肘、双腕、双髋、双膝、双踝)。关键点定义见 configs/base/datasets/macaque.py。
图像需从官方主页下载,标注使用 MMPose 预处理的 macaque_annotations.tar。目录结构:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── macaque
│-- annotations
│ │-- macaque_train.json
│ |-- macaque_test.json
│-- images
│ │-- 01418849d54b3005.jpg
│ │-- 0142d1d1a6904a70.jpg
│ │-- ...
官方未提供测试集,MMPose 随机选取 12500 张图像用于训练,其余用于评估,相关处理逻辑见解析脚本 tools/dataset_converters/parse_macaquepose_dataset.py。注意:中文文档中此链接写作 tools/dataset/...,实际仓库路径为上述 tools/dataset_converters/ 下的脚本。
DeepPoseKit 三件套:Vinegar Fly、Desert Locust 与 Grévy's Zebra
这三个数据集都来自 DeepPoseKit 生态(Graving et al., eLife'2019),特点是官方均不提供独立测试集,因此 MMPose 统一采用随机划分策略:90% 图像用于训练,剩余 10% 用于评估。它们的标注由同一套解析脚本 tools/dataset_converters/parse_deepposekit_dataset.py 生成。
三者的关键点数量与定义各不相同,分别定义于:
- Vinegar Fly(果蝇,32 关键点):configs/base/datasets/fly.py
- Desert Locust(沙漠蝗虫,34 关键点):configs/base/datasets/locust.py
- Grévy's Zebra(斑马,9 关键点):configs/base/datasets/zebra.py
Vinegar Fly 目录结构
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── fly
│-- annotations
│ │-- fly_train.json
│ |-- fly_test.json
│-- images
│ │-- 0.jpg
│ │-- 1.jpg
│ │-- ...
Desert Locust 目录结构
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── locust
│-- annotations
│ │-- locust_train.json
│ |-- locust_test.json
│-- images
│ │-- 0.jpg
│ │-- 1.jpg
│ │-- ...
Grévy's Zebra 目录结构
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── zebra
│-- annotations
│ │-- zebra_train.json
│ |-- zebra_test.json
│-- images
│ │-- 0.jpg
│ │-- 1.jpg
│ │-- ...
对应数据集类为 FlyDataset、LocustDataset、ZebraDataset,各自的训练配置位于 configs/animal_2d_keypoint/topdown_heatmap/fly、configs/animal_2d_keypoint/topdown_heatmap/locust 与 configs/animal_2d_keypoint/topdown_heatmap/zebra。
ATRW(ACM MM'2020)
ATRW 采集的是野外环境下的东北虎(西伯利亚虎)图像。图像分三个包下载:atrw_pose_train.tar.gz、atrw_pose_val.tar.gz、atrw_pose_test.tar.gz。
有一个重要的兼容性说明:ATRW 官方标注中图像字段名是 filename 而非 COCO 标准的 file_name,MMPose 已将其修改为与其他 coco 风格 JSON 一致,请直接使用预处理后的 atrw_annotations.tar,避免字段不匹配导致的加载失败。
目录结构:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── atrw
│-- annotations
│ │-- keypoint_train.json
│ │-- keypoint_val.json
│ │-- keypoint_trainval.json
│-- images
│ │-- train
│ │ │-- 000002.jpg
│ │ │-- ...
│ │-- val
│ │ │-- 000001.jpg
│ │ │-- ...
│ │-- test
│ │ │-- 000000.jpg
│ │ │-- ...
Animal Kingdom(CVPR'2022)
Animal Kingdom 是面向动物行为理解(Animal Behavior Understanding)的大规模多样数据集,共 23 个关键点。与上述数据集不同,它的标注按任务与物种分组:ak_P1(姿态)、ak_P2(行为)、ak_P3 细分为 amphibian/bird/fish/mammal/reptile 五类,每组均含 train.json 与 test.json。
图像需通过官方申请表获取,解压到 {MMPose}/data 后整理为:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── ak
|--annotations
│ │-- ak_P1
│ │ │-- train.json
│ │ │-- test.json
│ │-- ak_P2
│ │ │-- train.json
│ │ │-- test.json
│ │-- ak_P3_amphibian
│ │ │-- train.json
│ │ │-- test.json
│ │-- ak_P3_bird
│ │ │-- train.json
│ │ │-- test.json
│ │-- ak_P3_fish
│ │ │-- train.json
│ │ │-- test.json
│ │-- ak_P3_mammal
│ │ │-- train.json
│ │ │-- test.json
│ │-- ak_P3_reptile
│ │-- train.json
│ │-- test.json
│-- images
│ │-- AAACXZTV
│ │ │--AAACXZTV_f000059.jpg
│ │ │--...
│ │-- AAAUILHH
│ │ │--AAAUILHH_f000098.jpg
│ │ │--...
对应数据集类为 AnimalKingdomDataset,训练配置位于 configs/animal_2d_keypoint/topdown_heatmap/ak。
数据集的统一代码实现
虽然 9 个数据集来源、物种、关键点数量各异,但它们的加载逻辑完全统一。以 AnimalPoseDataset 与 AP10KDataset 为例(animalpose_dataset.py、ap10k_dataset.py),每个类:
- 通过
@DATASETS.register_module()注册到 MMPose 的注册器,使配置文件中可以直接用type='AnimalPoseDataset'引用; - 继承
BaseCocoStyleDataset,复用 COCO 风格 JSON 的解析、过滤、索引逻辑; - 通过类属性
METAINFO = dict(from_file='configs/_base_/datasets/xxx.py')从configs/_base_/datasets/下加载关键点、骨架、sigmas、joint_weights 等元信息,保证"配置即元数据"的一致性; - 提供
data_mode('topdown'/'bottomup')、bbox_file(评估时可替换为检测框结果)、indices(取前若干样本用于快速调试)、serialize_data(内存共享优化)、lazy_init(仅取元信息时跳过标注加载)等参数。
从源码结构可以推断:任何遵循同样 COCO 风格 JSON 的自定义动物数据集,都可以通过继承 BaseCocoStyleDataset 并仿照上述类快速接入,这也是 MMPose 数据集扩展机制的通用路径。
训练与评估
准备好任意数据集后,使用统一的训练/测试入口即可。以 Animal-Pose 为例:
# 单卡训练
python tools/train.py configs/animal_2d_keypoint/topdown_heatmap/animalpose/td-hm_hrnet-w32_8xb64-210e_animalpose-256x256.py
# 多卡分布式训练(8 GPU)
bash tools/dist_train.sh configs/animal_2d_keypoint/topdown_heatmap/animalpose/td-hm_hrnet-w32_8xb64-210e_animalpose-256x256.py 8
# 测试
python tools/test.py configs/animal_2d_keypoint/topdown_heatmap/animalpose/td-hm_hrnet-w32_8xb64-210e_animalpose-256x256.py <checkpoint路径>
所有动物数据集的评估器统一使用 CocoMetric,以 COCO 风格 AP/AR 指标衡量关键点精度,训练过程中会自动按 coco/AP 保存最优模型。
常见问题排查
- 路径不一致:若数据集不在
data/目录下,需同步修改配置中的data_root与ann_file/data_prefix,保证data_root + ann_file能拼出真实标注路径; - ATRW 无法加载:检查标注中字段是否为
file_name,务必使用 MMPose 预处理版本; - 数据集类找不到:确认
type与注册名一致(如AnimalPoseDataset、AP10KDataset、Horse10Dataset、MacaqueDataset、FlyDataset、LocustDataset、ZebraDataset、ATRWDataset、AnimalKingdomDataset),这些名字均可在 mmpose/datasets/datasets/animal/init.py 中核对; - 关键点数不匹配:输出通道数(
out_channels)必须等于对应数据集的keypoint_info数量,如 Animal-Pose 为 20、AP-10K 为 17; - DeepPoseKit 系列数据划分:fly/locust/zebra 官方无测试集,MMPose 固定按 9:1 随机划分,如需自定义划分可修改对应 JSON 或基于解析脚本重新生成。
通过本文,你可以按统一规范准备全部 9 个动物数据集,理解它们的元信息定义方式与 COCO 风格标注结构,并基于 HRNet 与 RTMPose 两种主流方案直接开展训练与评测。