用于动作识别的3D ResNet

更新（2020年4月13日）

我们在arXiv上发表了一篇论文。

片冈弘克、若宫天贺、原健翔和佐藤裕隆，
“超大规模数据集能否进一步提升时空3D卷积神经网络？”，
arXiv预印本，arXiv:2004.04968，2020年。

我们上传了本文中描述的预训练模型，包括在Kinetics-700与Moments in Time数据集合并后预训练的ResNet-50模型。

更新（2020年4月10日）

我们对脚本进行了重大更新。如果您希望使用旧版本来复现我们的CVPR2018论文，应使用CVPR2018分支中的脚本。

此次更新包括以下内容：

• 重构整个项目
• 支持较新的PyTorch版本
• 支持分布式训练
• 支持在Moments in Time数据集上进行训练和测试
• 新增R(2+1)D模型
• 上传在Kinetics-700、Moments in Time以及STAIR-Actions数据集上训练的3D ResNet模型

摘要

这是用于以下论文的PyTorch代码：

片冈弘克、若宫天贺、原健翔和佐藤裕隆，
“超大规模数据集能否进一步提升时空3D卷积神经网络？”，
arXiv预印本，arXiv:2004.04968，2020年。

原健翔、片冈弘克和佐藤裕隆，
“迈向基于时空3D卷积的动作识别良好实践”，
国际模式识别大会论文集，第2516–2521页，2018年。

原健翔、片冈弘克和佐藤裕隆，
“时空3D卷积神经网络能否重演2D卷积神经网络与ImageNet的发展历程？”，
IEEE计算机视觉与模式识别会议论文集，第6546–6555页，2018年。

原健翔、片冈弘克和佐藤裕隆，
“利用3D残差网络学习时空特征以进行动作识别”，
ICCV动作、手势与情感识别研讨会论文集，2017年。

该代码支持在Kinetics、Moments in Time、ActivityNet、UCF-101和HMDB-51数据集上进行训练、微调和测试。

引用

如果您使用此代码或预训练模型，请引用以下内容：

@inproceedings{hara3dcnns,
  author={Kensho Hara and Hirokatsu Kataoka and Yutaka Satoh},
  title={Can Spatiotemporal 3D CNNs Retrace the History of 2D CNNs and ImageNet?},
  booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
  pages={6546--6555},
  year={2018},
}

预训练模型

预训练模型可在这里获取。
所有模型均在Kinetics-700（K）、Moments in Time（M）、STAIR-Actions（S）或其合并数据集（KM、KS、MS、KMS）上训练。
如果您希望在自己的数据集上对这些模型进行微调，应指定以下选项。

r3d18_K_200ep.pth：--model resnet --model_depth 18 --n_pretrain_classes 700
r3d18_KM_200ep.pth：--model resnet --model_depth 18 --n_pretrain_classes 1039
r3d34_K_200ep.pth：--model resnet --model_depth 34 --n_pretrain_classes 700
r3d34_KM_200ep.pth：--model resnet --model_depth 34 --n_pretrain_classes 1039
r3d50_K_200ep.pth：--model resnet --model_depth 50 --n_pretrain_classes 700
r3d50_KM_200ep.pth：--model resnet --model_depth 50 --n_pretrain_classes 1039
r3d50_KMS_200ep.pth：--model resnet --model_depth 50 --n_pretrain_classes 1139
r3d50_KS_200ep.pth：--model resnet --model_depth 50 --n_pretrain_classes 800
r3d50_M_200ep.pth：--model resnet --model_depth 50 --n_pretrain_classes 339
r3d50_MS_200ep.pth：--model resnet --model_depth 50 --n_pretrain_classes 439
r3d50_S_200ep.pth：--model resnet --model_depth 50 --n_pretrain_classes 100
r3d101_K_200ep.pth：--model resnet --model_depth 101 --n_pretrain_classes 700
r3d101_KM_200ep.pth：--model resnet --model_depth 101 --n_pretrain_classes 1039
r3d152_K_200ep.pth：--model resnet --model_depth 152 --n_pretrain_classes 700
r3d152_KM_200ep.pth：--model resnet --model_depth 152 --n_pretrain_classes 1039
r3d200_K_200ep.pth：--model resnet --model_depth 200 --n_pretrain_classes 700
r3d200_KM_200ep.pth：--model resnet --model_depth 200 --n_pretrain_classes 1039

旧版预训练模型仍可在这里获取。
不过，在当前脚本中使用旧版预训练模型需要进行一些修改。

环境要求

• PyTorch（需0.4及以上版本）

conda install pytorch torchvision cudatoolkit=10.1 -c soumith

• FFmpeg、FFprobe

• Python 3

准备工作

ActivityNet

• 使用官方爬虫下载视频。
• 使用util_scripts/generate_video_jpgs.py将avi格式转换为jpg文件。

python -m util_scripts.generate_video_jpgs mp4_video_dir_path jpg_video_dir_path activitynet

• 使用util_scripts/add_fps_into_activitynet_json.py向json文件中添加帧率信息。

python -m util_scripts.add_fps_into_activitynet_json mp4_video_dir_path json_file_path

Kinetics

• 使用官方爬虫下载视频。
  • 测试集位于video_directory/test。
• 使用util_scripts/generate_video_jpgs.py将avi格式转换为jpg文件。

python -m util_scripts.generate_video_jpgs mp4_video_dir_path jpg_video_dir_path kinetics

• 使用util_scripts/kinetics_json.py生成类似于ActivityNet的json格式标注文件。
  • 爬虫中包含CSV文件（kinetics_{train, val, test}.csv）。

python -m util_scripts.kinetics_json csv_dir_path 700 jpg_video_dir_path jpg dst_json_path

UCF-101

• 在此处下载视频及训练/测试划分。
• 使用util_scripts/generate_video_jpgs.py将avi格式转换为jpg文件。

python -m util_scripts.generate_video_jpgs avi_video_dir_path jpg_video_dir_path ucf101

• 使用util_scripts/ucf101_json.py生成类似于ActivityNet的json格式标注文件。
  • annotation_dir_path包含classInd.txt、trainlist0{1, 2, 3}.txt以及testlist0{1, 2, 3}.txt。

python -m util_scripts.ucf101_json annotation_dir_path jpg_video_dir_path dst_json_path

HMDB-51

• 请从这里下载视频及训练/测试划分文件。
• 使用 util_scripts/generate_video_jpgs.py 将 avi 格式的视频转换为 jpg 文件。

python -m util_scripts.generate_video_jpgs avi_video_dir_path jpg_video_dir_path hmdb51

• 使用 util_scripts/hmdb51_json.py 生成类似于 ActivityNet 的 JSON 格式标注文件。
  • annotation_dir_path 包含 brush_hair_test_split1.txt 等文件。

python -m util_scripts.hmdb51_json annotation_dir_path jpg_video_dir_path dst_json_path

运行代码

假设数据目录结构如下：

~
  data/
    kinetics_videos/
      jpg/
        .../（类别名称目录）
          .../（视频名称目录）
            ...（jpg 文件）
    results/
      save_100.pth
    kinetics.json

请确认所有选项。

python main.py -h

在 Kinetics-700 数据集（700 个类别）上使用 4 个 CPU 线程（用于数据加载）训练 ResNet-50。
批量大小为 128。
每 5 个 epoch 保存一次模型。 训练过程中会使用所有可用的 GPU。
如果只想使用部分 GPU，可以设置 CUDA_VISIBLE_DEVICES=...。

python main.py --root_path ~/data --video_path kinetics_videos/jpg --annotation_path kinetics.json \
--result_path results --dataset kinetics --model resnet \
--model_depth 50 --n_classes 700 --batch_size 128 --n_threads 4 --checkpoint 5

从第 101 个 epoch 继续训练。（将加载 ~/data/results/save_100.pth 模型。）

python main.py --root_path ~/data --video_path kinetics_videos/jpg --annotation_path kinetics.json \
--result_path results --dataset kinetics --resume_path results/save_100.pth \
--model_depth 50 --n_classes 700 --batch_size 128 --n_threads 4 --checkpoint 5

使用已训练好的模型（~/data/results/save_200.pth）计算每个视频的前 5 类概率。
请注意，由于实际批量大小由 inference_batch_size * (n_video_frames / inference_stride) 决定，因此 inference_batch_size 应设置得较小。

python main.py --root_path ~/data --video_path kinetics_videos/jpg --annotation_path kinetics.json \
--result_path results --dataset kinetics --resume_path results/save_200.pth \
--model_depth 50 --n_classes 700 --n_threads 4 --no_train --no_val --inference --output_topk 5 --inference_batch_size 1

评估识别结果的 top-1 视频准确率（~/data/results/val.json）。

python -m util_scripts.eval_accuracy ~/data/kinetics.json ~/data/results/val.json --subset val -k 1 --ignore

在 UCF-101 数据集上对预训练模型（~/data/models/resnet-50-kinetics.pth）的 fc 层进行微调。

python main.py --root_path ~/data --video_path ucf101_videos/jpg --annotation_path ucf101_01.json \
--result_path results --dataset ucf101 --n_classes 101 --n_pretrain_classes 700 \
--pretrain_path models/resnet-50-kinetics.pth --ft_begin_module fc \
--model resnet --model_depth 50 --batch_size 128 --n_threads 4 --checkpoint 5

3D-ResNets-PyTorch 快速上手指南

本指南帮助开发者快速部署和使用基于 PyTorch 的 3D ResNet 动作识别模型。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐) 或 macOS
• Python: 版本 3.x
• 深度学习框架: PyTorch 0.4 或更高版本
• 视频处理工具: FFmpeg 和 FFprobe (用于视频帧提取)
• 硬件: 支持 CUDA 的 NVIDIA GPU (用于训练和加速推理)

依赖安装

建议使用 Conda 管理环境。以下命令将安装 PyTorch、TorchVision 及对应的 CUDA toolkit（示例为 CUDA 10.1，请根据实际显卡驱动调整）：

conda install pytorch torchvision cudatoolkit=10.1 -c soumith

提示：国内用户可使用清华或中科大镜像源加速安装，例如： conda install pytorch torchvision cudatoolkit=10.1 -c soumith -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/

此外，请通过系统包管理器安装 FFmpeg：

• Ubuntu/Debian: sudo apt-get install ffmpeg
• CentOS: sudo yum install ffmpeg

安装步骤

本项目主要为 Python 脚本集合，无需复杂的编译安装过程。

1. 克隆仓库

   git clone https://github.com/kenshohara/3D-ResNets-PyTorch.git
   cd 3D-ResNets-PyTorch
   

2. 下载预训练模型（可选） 如果您希望直接使用在 Kinetics-700、Moments in Time 等大规模数据集上预训练的模型，可以从 Google Drive 下载 .pth 文件，并放置于项目目录下的 models/ 文件夹中。

3. 数据预处理 模型输入为 JPEG 图像序列。您需要先将视频数据集（如 Kinetics, UCF-101, HMDB-51）转换为 JPG 格式并生成标注 JSON 文件。

   以 Kinetics 数据集为例：

   # 将 MP4 视频转换为 JPG 帧序列
   python -m util_scripts.generate_video_jpgs mp4_video_dir_path jpg_video_dir_path kinetics
   
   # 生成 JSON 标注文件
   python -m util_scripts.kinetics_json csv_dir_path 700 jpg_video_dir_path jpg dst_json_path
   

   (请将路径替换为您的实际数据路径)

基本使用

1. 查看帮助信息

运行前可先查看所有可用参数：

python main.py -h

2. 训练模型

以下示例展示如何在 Kinetics-700 数据集上训练 ResNet-50 模型。配置为：批量大小 128，使用 4 个 CPU 线程加载数据，每 5 个 epoch 保存一次检查点，自动使用所有可用 GPU。

python main.py --root_path ~/data --video_path kinetics_videos/jpg --annotation_path kinetics.json \
--result_path results --dataset kinetics --model resnet \
--model_depth 50 --n_classes 700 --batch_size 128 --n_threads 4 --checkpoint 5

3. 断点续训

如果训练中断，可通过 --resume_path 加载之前的权重继续训练（例如从第 101 个 epoch 开始）：

python main.py --root_path ~/data --video_path kinetics_videos/jpg --annotation_path kinetics.json \
--result_path results --dataset kinetics --resume_path results/save_100.pth \
--model_depth 50 --n_classes 700 --batch_size 128 --n_threads 4 --checkpoint 5

4. 推理与测试

使用训练好的模型对视频进行预测，输出每个视频 Top-5 的分类概率：

python main.py --root_path ~/data --video_path kinetics_videos/jpg --annotation_path kinetics.json \
--result_path results --dataset kinetics --resume_path results/save_200.pth \
--model_depth 50 --n_classes 700 --n_threads 4 --no_train --no_val --inference --output_topk 5 --inference_batch_size 1

5. 微调（Fine-tuning）

在预训练模型（如在 Kinetics 上训练的模型）基础上，微调全连接层以适应新数据集（如 UCF-101）：

python main.py --root_path ~/data --video_path ucf101_videos/jpg --annotation_path ucf101_01.json \
--result_path results --dataset ucf101 --n_classes 101 --n_pretrain_classes 700 \
--pretrain_path models/resnet-50-kinetics.pth --ft_begin_module fc \
--model resnet --model_depth 50 --batch_size 128 --n_threads 4 --checkpoint 5