MMPose 二维动物关键点数据集全指南:Animal-Pose、AP-10K 等 9 大数据集的准备、解析与训练实践

原创2026-09-16 23:22:041,819 阅读
文章标签:人工智能计算机视觉深度学习

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 动物关键点数据集与来源如下:

从仓库结构看,这 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。

准备步骤

  1. 下载 PASCAL VOC2012 的图像,取 dog、cat、sheep、cow、horse 五类作为 trainval 数据;
  2. 下载官方 test-set(1000 张图像、5 个类别),其中包含原始标注;
  3. 下载 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、CoarseDropout p=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 目录结构

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),每个类:

  1. 通过 @DATASETS.register_module() 注册到 MMPose 的注册器,使配置文件中可以直接用 type='AnimalPoseDataset' 引用;
  2. 继承 BaseCocoStyleDataset,复用 COCO 风格 JSON 的解析、过滤、索引逻辑;
  3. 通过类属性 METAINFO = dict(from_file='configs/_base_/datasets/xxx.py') 从 configs/_base_/datasets/ 下加载关键点、骨架、sigmas、joint_weights 等元信息,保证"配置即元数据"的一致性;
  4. 提供 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 两种主流方案直接开展训练与评测。

登录后查看全文
mmpose