ViTPose 二维动物关键点数据集准备与实战指南:Animal-Pose、AP-10K 等 8 大数据集全解析
ViTPose 二维动物关键点数据集准备与实战指南:Animal-Pose、AP-10K 等 8 大数据集全解析
本文聚焦 ViTPose/MMPose 框架中的 2D 动物关键点估计任务,完整讲解 Animal-Pose、AP-10K、Horse-10、MacaquePose、Vinegar Fly、Desert Locust、Grévy's Zebra、ATRW 共 8 个数据集的结构、下载方式与目录组织规范,并延伸到对应训练配置、评估指标与推理演示脚本,帮助你从零搭建可复现的动物姿态估计实验环境。
数据准备总原则
在开始之前,请先阅读框架的 安装指南 完成环境搭建。所有动物关键点数据集统一采用 COCO 风格的 JSON 标注格式,数据准备遵循两条核心原则:
- 推荐将数据集根目录软链接(symlink)到
$MMPOSE/data下(MMPOSE为仓库根目录); - 如果你的目录结构与官方约定不同,需要同步修改对应配置文件中的
data_root、ann_file与img_prefix路径。
仓库约定的标准目录骨架如下(以 animalpose 为例):
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
`── animalpose
ViTPose 仓库为每个数据集都在 configs/base/datasets/ 目录下提供了独立的 dataset_info 基础配置,其中完整定义了 keypoint_info(关键点名称、颜色、左右 swap 关系)、skeleton_info(骨架连线)、joint_weights(关节权重)与 sigmas(OKS 评估用的关键点标准差)。例如 configs/base/datasets/animalpose.py 中 Animal-Pose 的 20 个关键点定义、configs/base/datasets/ap10k.py 中 AP-10K 的 17 个关键点定义均可直接复用,无需在训练配置里重复编写。
Animal-Pose(ICCV'2019)
数据集简介
Animal-Pose 是面向跨域动物姿态估计的数据集,论文为《Cross-Domain Adaptation for Animal Pose Estimation》(ICCV 2019)。其关键点包括左眼、右眼、左耳基、右耳基、鼻、喉、尾基、肩隆(Withers)以及前后四肢的肘、膝、爪共 20 个关键点,具体索引映射定义在 configs/base/datasets/animalpose.py 与数据集类 mmpose/datasets/datasets/animal/animal_pose_dataset.py 中。
下载与目录结构
按以下步骤准备数据:
- 下载 PASCAL2011 的图像,重点使用其中 dog、cat、sheep、cow、horse 五个类别作为 trainval 数据;
- 下载官方 test-set 图像(1000 张、5 个类别)及原始标注;
- 下载 MMPose 预处理好的标注文件
animalpose_annotations.tar(已转换为 COCO 兼容格式);若想自行生成标注,可运行仓库提供的解析脚本 tools/dataset/parse_animalpose_dataset.py。
解压到 {MMPOSE}/data 后,标准目录结构为:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── animalpose
│-- VOC2011
│ │-- 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 划分,ViTPose 采用如下约定(与 tools/dataset/parse_animalpose_dataset.py 的脚本逻辑一致):
- 从 PascalVOC 图像中选出 train + val 集合,共 3608 张图像、5117 个标注实例;
- 其中 2798 张图像、4000 个标注实例用于训练;
- 810 张图像、1117 个标注实例用于验证(即
resnet_animalpose.md/hrnet_animalpose.md中“Results on AnimalPose validation set (1117 instances)”的由来); - 其余来源的 1000 张图像、1000 个标注实例用于测试。
AP-10K(NeurIPS'2021)
数据集简介
AP-10K 是野外场景动物姿态估计基准数据集(《AP-10K: A Benchmark for Animal Pose Estimation in the Wild》)。标注包含 50 个动物物种,共 10,015 张标注图像、13,028 个实例,关键点数量为 17 个(左眼、右眼、鼻、颈、尾根、肩、肘、前爪、髋、膝、后爪等,定义见 configs/base/datasets/ap10k.py)。官方按 7:1:2 的比例随机划分训练集、验证集与测试集,并提供 3 组不同划分(split1/split2/split3)用于交叉验证。
下载与目录结构
从官方渠道下载图像与标注(注意:该数据与标注仅限非商业用途)。解压到 {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
│ │-- ...
对应的数据集实现类为 mmpose/datasets/datasets/animal/animal_ap10k_dataset.py 中的 AnimalAP10KDataset,它继承 Kpt2dSviewRgbImgTopDownDataset,除常规关键点加载外,还会为每个实例记录 category(物种类别),评估时按真实类别写回 category_id。
Horse-10(WACV'2021)
Horse-10 来自《Pretraining boosts out-of-domain robustness for pose estimation》(WACV 2021),包含 22 个马匹关键点(定义见 configs/base/datasets/horse10.py)。图像从官网下载,标注文件下载 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
│ │-- ...
MacaquePose(bioRxiv'2020)
MacaquePose 是野外猕猴姿态数据集(《MacaquePose: A novel 'in the wild' macaque monkey pose dataset for markerless motion capture》)。图像从官网下载,标注文件下载 macaque_annotations.tar。目录结构如下:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── macaque
│-- annotations
│ │-- macaque_train.json
│ |-- macaque_test.json
│-- images
│ │-- 01418849d54b3005.jpg
│ │-- 0142d1d1a6904a70.jpg
│ │-- 01ef2c4c260321b7.jpg
│ │-- 020a1c75c8c85238.jpg
│ │-- 020b1506eef2557d.jpg
│ │-- ...
由于官方未提供测试集,ViTPose 随机选取 12,500 张图像用于训练,其余用于评估(划分逻辑见 tools/dataset/parse_macaquepose_dataset.py)。该数据集配套的模型配置位于 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/macaque/,包含 res50/res101/res152 与 hrnet_w32/hrnet_w48 共 5 套配置,输入尺寸为 256x192。
DeepPoseKit 系列:Vinegar Fly、Desert Locust、Grévy's Zebra
这三个数据集均出自 DeepPoseKit 生态(《DeepPoseKit, a software toolkit for fast and robust animal pose estimation using deep learning》,Elife 2019)与果蝇姿态估计论文(《Fast animal pose estimation using deep neural networks》,Nature Methods 2019),由 tools/dataset/parse_deepposekit_dataset.py 负责从原始格式解析为 COCO JSON。
三个数据集目录结构完全一致,仅根目录名不同:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── fly # locust / zebra 同理
│-- annotations
│ │-- fly_train.json
│ |-- fly_test.json
│-- images
│ │-- 0.jpg
│ │-- 1.jpg
│ │-- 2.jpg
│ │-- 3.jpg
│ │-- ...
三个数据集均未提供官方测试集,ViTPose 随机选取 90% 图像用于训练,其余 10% 用于评估:
- Vinegar Fly(果蝇):下载
vinegar_fly_images.tar与vinegar_fly_annotations.tar,图像为 192x192 单虫图像,对应配置位于 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/fly/; - Desert Locust(沙漠蝗虫):下载
locust_images.tar与locust_annotations.tar,对应配置位于 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/locust/; - Grévy's Zebra(细纹斑马):下载
zebra_images.tar与zebra_annotations.tar,对应配置位于 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/zebra/。
ATRW(ACM MM'2020)
ATRW(Amur Tiger Re-identification in the Wild)采集自野外东北虎(又称西伯利亚虎)图像,是 CVWC 2019 挑战赛的一部分。需分别下载 atrw_pose_train.tar.gz、atrw_pose_val.tar.gz、atrw_pose_test.tar.gz 三份图像包。
需要注意一个兼容性细节:ATRW 官方标注文件中关键点字段名是 filename 而非 COCO 标准的 file_name,ViTPose 已修正该字段并提供修改后的标注文件 atrw_annotations.tar。其 15 个关键点定义(耳、鼻、肩、爪、髋、膝、尾、中心等)见 configs/base/datasets/atrw.py。目录结构如下:
mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
│── atrw
│-- annotations
│ │-- keypoint_train.json
│ │-- keypoint_val.json
│ │-- keypoint_trainval.json
│-- images
│ │-- train
│ │ │-- 000002.jpg
│ │ │-- 000003.jpg
│ │ │-- ...
│ │-- val
│ │ │-- 000001.jpg
│ │ │-- 000013.jpg
│ │ │-- ...
│ │-- test
│ │ │-- 000000.jpg
│ │ │-- 000004.jpg
│ │ │-- ...
训练配置与源码实现解读
配置文件结构
以 Animal-Pose 的 ResNet50 配置 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/animalpose/res50_animalpose_256x256.py 为例,其结构可拆解为:
_base_继承 configs/base/default_runtime.py 与 configs/base/datasets/animalpose.py;channel_cfg:num_output_channels=20、dataset_joints=20,输出通道数等于 Animal-Pose 的关键点数量;model:type='TopDown'(top-down 两阶段中的姿态估计器),backbone 为ResNet(depth=50)(预训练权重torchvision://resnet50),keypoint_head为TopdownHeatmapSimpleHead,损失函数JointsMSELoss(use_target_weight=True);data_cfg:image_size=[256, 256]、heatmap_size=[64, 64]、use_gt_bbox=True(训练/验证阶段直接使用标注框,无需检测器)、soft_nms=False、oks_thr=0.9、vis_thr=0.2;- 优化器
Adam(lr=5e-4),学习率策略为 step 衰减(step=[170, 200],共total_epochs=210,线性 warmup 500 步); - 数据流经
LoadImageFromFile → TopDownRandomFlip → TopDownHalfBodyTransform → TopDownGetRandomScaleRotation → TopDownAffine → ToTensor → NormalizeTensor → TopDownGenerateTarget → Collect,其中TopDownGenerateTarget(sigma=2)负责从标注关键点生成高斯热图监督信号。
ViTPose 在动物任务上的配置
本仓库在 AP-10K 上直接提供了 ViTPose 系列配置(见 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/),包括 ViTPose_small/large/huge/base_ap10k_256x192.py。以 ViTPose_small_ap10k_256x192.py 为例:
- backbone 为
ViT:img_size=(256, 192)、patch_size=16、embed_dim=384、depth=12、num_heads=12、mlp_ratio=4、qkv_bias=True、drop_path_rate=0.3; keypoint_head使用 2 层反卷积(num_deconv_layers=2,滤波器(256, 256),卷积核(4, 4))将 ViT 输出上采样为热图;data_cfg对应输入image_size=[192, 256]、heatmap_size=[48, 64];- 其余训练超参(Adam、210 epoch、step 衰减、warmup)与 ResNet/HRNet 配置保持一致。
数据集加载与评估源码
8 个数据集类统一位于 mmpose/datasets/datasets/animal/,均继承自 Kpt2dSviewRgbImgTopDownDataset(旧的 AnimalBaseDataset 已在 animal_base_dataset.py 中被标记为 deprecated 并抛错提示迁移)。核心流程为:
_get_db():断言use_gt_bbox,调用_load_coco_keypoint_annotations()从 COCO JSON 中读出 bbox 与关键点,通过_xywh2cs把 bbox 转换为 top-down 训练所需的center与scale;evaluate():仅支持metric='mAP',预测结果先按可见关键点得分做 rescoring(vis_thr过滤),再按soft_nms/oks_nms以oks_thr做后处理去重,最后调用 xtcocotools 的COCOeval计算并输出AP、AP .5、AP .75、AP (M)、AP (L)、AR、AR .5、AR .75、AR (M)、AR (L)共 10 项指标(以 mmpose/datasets/datasets/animal/animal_pose_dataset.py 的实现为准,AP-10K 的AnimalAP10KDataset在 rescoring 之外还额外保留并写回每个实例的物种category)。
基准结果参考
仓库在动物任务上提供了多个模型的基准结果(以验证集 mAP 为准):
- Animal-Pose(1117 个验证实例):见 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/animalpose/resnet_animalpose.md 与 hrnet_animalpose.md。ResNet50 为 AP 0.688(AP50 0.945),ResNet101 为 0.696,ResNet152 为 0.709;HRNet-W32 为 0.736,HRNet-W48 为 0.737,且均附有 ckpt 与 log 下载链接。
- AP-10K 验证集:见 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/ap10k/hrnet_ap10k.md。HRNet-W32 为 AP 0.738,HRNet-W48 为 0.744(含 AP50、AP75、AP(M)、AP(L) 细分指标)。
模型测试与训练命令
测试单个数据集
准备好数据与 checkpoint 后,可用 tools/test.py 或 tools/dist_test.sh 在验证集上评估 mAP:
# 单卡测试
python tools/test.py ${CONFIG_FILE} ${CHECKPOINT_FILE} \
--eval mAP
# 多卡测试
./tools/dist_test.sh ${CONFIG_FILE} ${CHECKPOINT_FILE} ${GPU_NUM} \
--eval mAP
CHECKPOINT_FILE 既可以是本地已下载的 .pth 路径,也可以是 checkpoint 的 URL 链接。以 --cfg-options 可覆盖配置项,例如 --cfg-options model.backbone.depth=50。完整可选参数(--out、--fuse-conv-bn、--gpu_collect、--launcher 等)参见 docs/en/getting_started.md。
训练模型
# 单卡训练
python tools/train.py ${CONFIG_FILE} [--work-dir ${YOUR_WORK_DIR}]
# 多卡训练(8 卡示例)
./tools/dist_train.sh ${CONFIG_FILE} 8
# Slurm 集群训练
./tools/slurm_train.sh ${PARTITION} ${JOB_NAME} ${CONFIG_FILE} ${WORK_DIR}
训练输出(日志与 checkpoint)默认保存在配置中的 work_dir。默认每轮在验证集上评估一次,可通过 evaluation = dict(interval=10, metric='mAP', save_best='AP') 调整评估间隔与最优模型保存依据(动物任务配置中即采用 interval=10)。--resume-from 从断点恢复(同时加载权重与优化器状态),--load-from 仅加载权重用于微调。相关说明详见 docs/en/getting_started.md。
推理演示脚本
仓库在 demo/docs/2d_animal_demo.md 中提供了完整的动物姿态演示方案,分为三类场景:
1. 静态图像演示(使用标注框)
给定 COCO 格式 JSON 与图像目录,用 demo/top_down_img_demo.py 逐张推理:
python demo/top_down_img_demo.py \
${MMPOSE_CONFIG_FILE} ${MMPOSE_CHECKPOINT_FILE} \
--img-root ${IMG_ROOT} --json-file ${JSON_FILE} \
--out-img-root ${OUTPUT_DIR} \
[--show --device ${GPU_ID or CPU}] \
[--kpt-thr ${KPT_SCORE_THR}]
以猕猴(macaque)模型为例:
python demo/top_down_img_demo.py \
configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/macaque/res50_macaque_256x192.py \
https://download.openmmlab.com/mmpose/animal/resnet/res50_macaque_256x192-98f1dd3a_20210407.pth \
--img-root tests/data/macaque/ --json-file tests/data/macaque/test_macaque.json \
--out-img-root vis_results
CPU 推理时追加 --device=cpu。
2. 视频演示(全图输入)
当视频中目标居中、无需检测时,用 demo/top_down_video_demo_full_frame_without_det.py:
python demo/top_down_video_demo_full_frame_without_det.py \
${MMPOSE_CONFIG_FILE} ${MMPOSE_CHECKPOINT_FILE} \
--video-path ${VIDEO_FILE} \
--out-video-root ${OUTPUT_VIDEO_ROOT} \
[--show --device ${GPU_ID or CPU}] \
[--kpt-thr ${KPT_SCORE_THR}]
果蝇(fly)模型示例:
python demo/top_down_video_demo_full_frame_without_det.py \
configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/fly/res152_fly_192x192.py \
https://download.openmmlab.com/mmpose/animal/resnet/res152_fly_192x192-fcafbd5a_20210407.pth \
--video-path demo/resources/<demo_fly_video.avi> \
--out-video-root vis_results
3. 视频演示(检测器 + 姿态估计)
需要先安装 mmdet。对 COCO 中的 10 个常见动物类别(bird、cat、dog、horse、sheep、cow、elephant、bear、zebra、giraffe,对应 COCO 类别 id 15–24),使用 COCO 预训练检测模型 + 动物姿态模型,脚本为 demo/top_down_video_demo_with_mmdet.py:
python demo/top_down_video_demo_with_mmdet.py \
${MMDET_CONFIG_FILE} ${MMDET_CHECKPOINT_FILE} \
${MMPOSE_CONFIG_FILE} ${MMPOSE_CHECKPOINT_FILE} \
--video-path ${VIDEO_FILE} \
--out-video-root ${OUTPUT_VIDEO_ROOT} \
--det-cat-id ${CATEGORY_ID}
[--show --device ${GPU_ID or CPU}] \
[--bbox-thr ${BBOX_SCORE_THR} --kpt-thr ${KPT_SCORE_THR}]
以 Horse-10 模型检测马(--det-cat-id 18)为例:
python demo/top_down_video_demo_with_mmdet.py \
demo/mmdetection_cfg/faster_rcnn_r50_fpn_coco.py \
https://download.openmmlab.com/mmdetection/v2.0/faster_rcnn/faster_rcnn_r50_fpn_2x_coco/faster_rcnn_r50_fpn_2x_coco_bbox_mAP-0.384_20200504_210434-a5d8aa15.pth \
configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/horse10/res50_horse10_256x256-split1.py \
https://download.openmmlab.com/mmpose/animal/resnet/res50_horse10_256x256_split1-3a3dc37e_20210405.pth \
--video-path demo/resources/<demo_horse.mp4> \
--out-video-root vis_results \
--bbox-thr 0.1 \
--kpt-thr 0.4 \
--det-cat-id 18
对于 COCO 之外的动物(如猕猴),仓库在 demo/docs/mmdet_modelzoo.md 提供了 1 类检测模型(如 demo/mmdetection_cfg/cascade_rcnn_x101_64x4d_fpn_1class.py),配合 --det-cat-id 即可完成检测加姿态的完整链路。
推理加速技巧
针对 2D 动物姿态模型,可通过修改配置提速:
- 将
test_cfg中的flip_test设为False(关闭测试期水平翻转 TTA,速度提升明显); - 保持
post_process='default'(默认的后处理即可,无需额外模块)。
小结
在 ViTPose 中开展 2D 动物关键点估计,数据层的关键在于:将各数据集按上述目录规范放入 data/ 下、确认 ann_file/img_prefix 与配置一致;模型层则可直接复用仓库为每个动物数据集提供的 ResNet、HRNet 与 ViTPose 系列配置(位于 configs/animal/2d_kpt_sview_rgb_img/topdown_heatmap/);评估统一以 COCO 风格 mAP 为准,推理可通过 demo 下的脚本快速落地。测试用的小规模标注数据(如 tests/data/animalpose/、tests/data/ap10k/、tests/data/macaque/ 等)也已随仓库提供,便于验证流程是否跑通。