在 MMAction2 中准备 JHMDB 时空行为检测数据集：下载、解压、目录结构与 gttubes 标注详解

• 人工智能
• 计算机视觉
• 深度学习

本篇技术指南以 MMAction2 官方仓库中 tools/data/jhmdb/README_zh-CN.md 为骨架，系统讲解如何在$MMACTION2项目中准备 JHMDB（Joint-annotated Human Motion DataBase）数据集：从下载 RGB 帧、光流与真实标签文件，到解压、SSD 软链接优化，再到逐层核对目录结构与理解JHMDB-GT.pkl缓存文件中 6 项标注内容的含义。读完本文，你将能够在 MMAction2 中独立完成 JHMDB 数据集的落地准备，并掌握gttubes时空 tube 标注格式，为后续的时空行为检测（Spatio-Temporal Action Detection，STAD）训练与评测打下数据基础。

一、JHMDB 数据集简介与引用方式

JHMDB（Joint-annotated Human Motion DataBase）是经典的时空行为检测（spatio-temporal action detection）评测数据集，由 H. Jhuang、J. Gall、S. Zuffi、C. Schmid 与 M. J. Black 在 ICCV 2013 上提出。在 MMAction2 的官方数据支持列表中，JHMDB 与 UCF101-24、AVA、AVA-Kinetics 等一同被归类于“时空行为检测（Spatio-temporal Action Detection）”任务，详见 README_zh-CN.md。

关于数据集的基本信息，官方建议参考其官网。如果在论文中使用了该数据集，MMAction2 文档提供了如下 BibTeX 引用条目：

@inproceedings{Jhuang:ICCV:2013, title = {Towards understanding action recognition}, author = {H. Jhuang and J. Gall and S. Zuffi and C. Schmid and M. J. Black}, booktitle = {International Conf. on Computer Vision (ICCV)}, month = Dec, pages = {3192-3199}, year = {2013} }

二、准备前置条件

在执行任何准备步骤之前，请确保命令行当前路径为$MMACTION2/tools/data/jhmdb/，即：

cd $MMACTION2/tools/data/jhmdb/

其中$MMACTION2指代本仓库（mmaction2）的根目录。这一点很重要，因为后续解压命令的默认路径、以及建立软链接时使用的相对路径../../../data/jhmdb都以此为基准。若路径不对，解压产物会落到错误的位置，导致data/jhmdb目录结构不符合 MMAction2 的预期。

三、下载数据集：RGB 帧、光流与真实标签

JHMDB 的 RGB 帧（Frames）、光流（FlowBrox04）和真实标签（JHMDB-GT.pkl）统一打包在JHMDB.tar.gz中，官方推荐从 Google Drive 的 JHMDB 数据目录 下载。

值得注意的是，这份预处理好的数据并非来自 JHMDB 官方原始发布渠道，而是由 MOC（MCG-NJU/MOC-Detector）保持一致。

四、解压与 SSD 软链接优化

4.1 解压JHMDB.tar.gz

将下载得到的JHMDB.tar.gz放置在$MMACTION2/tools/data/jhmdb/目录下，然后执行：

tar -zxvf JHMDB.tar.gz

解压完成后，你会得到以下三个核心产物：

• FlowBrox04文件夹：Brox 光流帧
• Frames文件夹：RGB 视频帧
• JHMDB-GT.pkl文件：真实标签缓存文件

4.2 将帧存放到 SSD 以提升 I/O 性能

JHMDB 由 21 类行为、共 928 个视频片段组成，虽然整体规模不大，但在训练时每一轮 epoch 都会反复读取全部 RGB/光流帧。如果你的机器拥有大量 SSD 存储空间，推荐将抽取的帧存储在 I/O 性能更优秀的 SSD 上，以显著缩短数据读取时间。官方给出的做法是在数据目录上建立软链接：

# 执行这两行进行抽取（假设 SSD 挂载在 "/mnt/SSD/"） mkdir /mnt/SSD/JHMDB/ ln -s /mnt/SSD/JHMDB/ ../../../data/jhmdb

上述命令以$MMACTION2/tools/data/jhmdb/为当前路径，../../../data/jhmdb会解析到$MMACTION2/data/jhmdb。执行后，解压操作把数据实际写入 SSD，而$MMACTION2/data/jhmdb则通过软链接指向 SSD 上的真实目录，对 MMAction2 而言透明无感。这一做法与 docs/en/user_guides/prepare_dataset.md 中提到的“原始帧格式在 SSD 可用时读取更快”的说明相互印证：MMAction2 同时支持原始帧（rawframes）与视频（video）两种数据形态，前者依赖良好的磁盘 I/O，后者以运行时解码换取存储空间。

五、核对文件夹结构

解压完成后，请逐层核对目录结构。在 MMAction2 项目整体上下文中，JHMDB 的文件结构如下：

mmaction2 ├── mmaction ├── tools ├── configs ├── data │ ├── jhmdb │ | ├── FlowBrox04 │ | | ├── brush_hair │ | | | ├── April_09_brush_hair_u_nm_np1_ba_goo_0 │ | | | | ├── 00001.jpg │ | | | | ├── 00002.jpg │ | | | | ├── ... │ | | | | ├── 00039.jpg │ | | | | ├── 00040.jpg │ | | | ├── ... │ | | | ├── Trannydude___Brushing_SyntheticHair___OhNOES!__those_fukin_knots!_brush_hair_u_nm_np1_fr_goo_2 │ | | ├── ... │ | | ├── wave │ | | | ├── 21_wave_u_nm_np1_fr_goo_5 │ | | | ├── ... │ | | | ├── Wie_man_winkt!!_wave_u_cm_np1_fr_med_0 │ | ├── Frames │ | | ├── brush_hair │ | | | ├── April_09_brush_hair_u_nm_np1_ba_goo_0 │ | | | | ├── 00001.png │ | | | | ├── 00002.png │ | | | | ├── ... │ | | | | ├── 00039.png │ | | | | ├── 00040.png │ | | | ├── ... │ | | | ├── Trannydude___Brushing_SyntheticHair___OhNOES!__those_fukin_knots!_brush_hair_u_nm_np1_fr_goo_2 │ | | ├── ... │ | | ├── wave │ | | | ├── 21_wave_u_nm_np1_fr_goo_5 │ | | | ├── ... │ | | | ├── Wie_man_winkt!!_wave_u_cm_np1_fr_med_0 │ | ├── JHMDB-GT.pkl

对结构做几点解读，便于排查问题：

• 类别目录：brush_hair、wave等是行为类别名，JHMDB 共 21 类，与JHMDB-GT.pkl中labels字段的 21 个类别名称一一对应。
• 视频目录命名：每个视频片段目录名形如April_09_brush_hair_u_nm_np1_ba_goo_0，其中嵌入了行为类别、人物编号（u_/cm_等表示遮挡/相机视角等子属性）、动作上下文等元信息，目录名中可能包含!等特殊字符（如Trannydude___Brushing_SyntheticHair___OhNOES!__those_fukin_knots!_brush_hair_u_nm_np1_fr_goo_2），在脚本处理时需注意字符串转义。
• 帧命名差异：Frames下是 PNG 格式的 RGB 帧（00001.png...），FlowBrox04下是 JPG 格式的光流帧（00001.jpg...）。两者均从 1 开始编号，这正是 AVA 系列时空检测数据集加载器默认start_index=1的原因（详见下文源码分析）。
• 关键文件：JHMDB-GT.pkl必须与Frames、FlowBrox04平级位于data/jhmdb/下。

六、深入理解JHMDB-GT.pkl标注缓存文件

JHMDB-GT.pkl是一个 pickle 序列化缓存文件，集中存放了数据集的全部真实标签信息。它包含 6 个项目，下面逐一拆解。

6.1labels（list）：21 个行为类别名称

一个由 21 个字符串组成的列表，依次列出全部行为类别名称，如brush_hair、wave等。类别在标注中的索引即基于此列表的顺序。

6.2gttubes（dict）：每个视频对应的基准 tubes

gttubes是时空行为检测任务的核心标注。其结构为：

• 键（key）：视频标识符，如'walk/Panic_in_the_Streets_walk_u_cm_np1_ba_med_5'，即“类别目录/视频目录名”的组合路径；
• 值（value）：一个字典，将标签索引（即labels中的下标）映射到该类别下的tube 列表。

其中：

• gttube：由标签索引和 tube 列表组成的字典，即上述值字典中的每一个键值对。
• tube：一个nframes行、5 列的 numpy array，每一行的格式为<frame index> <x1> <y1> <x2> <y2>。也就是说，一个 tube 用逐帧的人体包围框（bounding box）序列，在时空维度上追踪某一次动作实例。

可以借助仓库中的标注片段直观理解 tube 形态。在 MMAction2 的时空检测教程 projects/stad_tutorial/demo_stad_zh_CN.ipynb 中，以 MultiSports 数据集为例展示了相同的gttubes结构：每个类别标号对应一个 numpy array 列表，array 形状为(n, 5)，代表 n 帧、每帧标注(帧号, x1, y1, x2, y2)。JHMDB 的 tube 与之完全同构，区别仅在于 JHMDB 的 tube 列中不含置信度分数。

6.3nframes（dict）：每个视频对应的帧数

一个字典，键为视频标识符，值为该视频的总帧数。例如：

'walk/Panic_in_the_Streets_walk_u_cm_np1_ba_med_5': 16

6.4train_videos（list）：训练视频列表

一个包含nsplits=1个元素的列表（即只有 1 个官方划分），每个元素是一个训练视频标识符列表。读取训练集划分的代码形如：

train_videos = GT['train_videos'][0]

这与 MMAction2 中时空检测评测代码的取法一致，例如 mmaction/evaluation/functional/multisports_utils.py 中vlist = GT['test_videos'][0]正是用下标[0]取出唯一划分。

6.5test_videos（list）：测试视频列表

与train_videos结构相同，同样包含nsplits=1个元素，每个元素是测试视频标识符列表。

6.6resolution（dict）：每个视频的分辨率

一个字典，键为视频标识符，值为(h, w)形式的高度、宽度元组。例如：

'pour/Bartender_School_Students_Practice_pour_u_cm_np1_fr_med_1': (240, 320)

在后续处理中，该分辨率信息可用于验证帧尺寸或为检测框做归一化。仓库中 projects/stad_tutorial/tools/generate_mmdet_anno.py 就展示了如何读取resolution字段来生成 COCO 格式的逐帧检测标注。

七、gttubes标注在 MMAction2 中的实际用途

JHMDB-GT.pkl中的gttubes并非静态陈列，而是时空行为检测训练与评测链条中的数据源头。在仓库源码中可以印证其典型用法：

• 评测阶段：时空检测评测函数直接读取GT['gttubes']与真实标签做逐帧匹配。例如 mmaction/evaluation/functional/multisports_utils.py 中的frameAP函数，会遍历GT['test_videos'][0]中的每个视频，从GT['gttubes'][v]取出 tube，再把每帧的(x1, y1, x2, y2)展开为按(video_idx, frame_idx)索引的 ground-truth 字典，用于计算 precision-recall 曲线。
• 格式转换阶段：projects/stad_tutorial/tools/generate_mmdet_anno.py展示了如何把gttubes（连同train_videos、test_videos、resolution）转换为逐帧的 COCO 检测标注 JSON，从而用现成的检测器管线（如 Faster R-CNN）生成时空检测所需的人体候选框。

这两个例子说明：只要你的时空检测数据集（无论是 JHMDB、MultiSports 还是自建数据）能整理成gttubes+labels+nframes+train_videos+test_videos+resolution的 pickle 结构，就可以直接复用 MMAction2 的评测代码，也可以借助转换脚本接入检测器。

八、准备完成后的下一步

数据准备完成后，通常还需要做两件事才能开始训练：

1. 生成行为识别用标注文件：如果你计划在原始帧（rawframes）形态下做行为识别任务，需要为每个视频生成一行<frame_directory> <total_frames> <label>的文本标注（total_frames可结合JHMDB-GT.pkl的nframes字段统计），格式参见 docs/en/user_guides/prepare_dataset.md；MMAction2 也提供了通用的build_file_list.py等工具脚本（位于 tools/data/build_file_list.py）辅助生成。
2. 修改配置文件：在 config 中正确指定data_root、ann_file、dataset_type等字段，将数据接入训练/评测流程。

需要说明的是：JHMDB 在 MMAction2 中被归类为时空行为检测数据集，其原始标注面向逐帧包围框评测；若要用作纯行为识别（classification）数据，需要自行基于gttubes/标签构建类别划分，并遵循 docs/en/user_guides/prepare_dataset.md 的标注格式规范。

九、常见问题与排查建议

• 解压后data/jhmdb不存在：多半是当前路径不在$MMACTION2/tools/data/jhmdb/，或软链接创建失败。请回到该目录重新执行tar与ln -s命令。
• JHMDB-GT.pkl无法用 pickle 加载：请确认下载的是完整文件且与数据版本配套，不要混用不同来源（MOC 版 vs 官网原始版）的标注。
• 帧目录名含特殊字符（如!）：在 shell 中处理时需加引号或转义，在 Python 脚本中则注意路径字符串处理。
• 光流帧与 RGB 帧编号不一致：检查是否完整解压；两者应均从00001开始连续编号。

十、总结

本文完整梳理了在 MMAction2 中准备 JHMDB 数据集的全部环节：数据集来源与引用、下载与解压、SSD 软链接优化、目录结构核对，以及对JHMDB-GT.pkl六项内容（labels、gttubes、nframes、train_videos、test_videos、resolution）的逐项解析，并结合仓库源码（multisports_utils.py、generate_mmdet_anno.py）说明了gttubes在评测与格式转换中的实际用途。完成上述步骤后，data/jhmdb便具备 MMAction2 所期望的标准结构，可作为时空行为检测实验的数据基础。更详尽的数据集准备总览可参考 tools/data/jhmdb/README.md（英文原版）与 docs/en/user_guides/prepare_dataset.md（MMAction2 数据准备指南）。

• 人工智能
• 计算机视觉
• 深度学习