时序关系网络

新增（2020年4月20日）：请查看我们最近在CVPR'20发表的工作用于动作识别的时序金字塔网络（TPN），该方法大幅超越TRN，在仅使用RGB流的情况下，已在多个视频基准上接近当前最优结果。额外福利：该仓库中附带了bolei_juggling_v2.mp4！

我们发布了基于TSN-pytorch代码库构建的时序关系网络的代码。

新增（2018年7月29日）：本工作已被ECCV'18接收，请参阅论文获取最新成果。我们还发布了在Something-Something V2数据集上训练的当前最优模型，具体说明见下文。

注意：请始终使用git clone --recursive https://github.com/metalbubble/TRN-pytorch来克隆该项目，否则将无法使用inception系列CNN架构。

数据准备

下载Something-Something数据集、Jester数据集或Charades数据集。将其解压到某个文件夹中。使用process_dataset.py生成训练、验证和测试集的索引文件。最后，在datasets_video.py中正确配置训练、验证和类别元文件。

对于Something-Something-V2，我们提供了一个实用脚本extract_frames.py，用于将下载的.webm视频转换为包含提取帧的目录。此外，对应的光流图像可从这里下载。

代码

实现时序关系网络模块的核心代码是TRNmodule。它可以直接插拔到TSN之上。

训练与测试

• 单尺度TRN的训练命令：

CUDA_VISIBLE_DEVICES=0,1 python main.py something RGB \
                     --arch BNInception --num_segments 3 \
                     --consensus_type TRN --batch-size 64

• 多尺度TRN的训练命令：

CUDA_VISIBLE_DEVICES=0,1 python main.py something RGB \
                     --arch BNInception --num_segments 8 \
                     --consensus_type TRNmultiscale --batch-size 64

• 单尺度TRN的测试命令：

python test_models.py something RGB model/TRN_something_RGB_BNInception_TRN_segment3_best.pth.tar \
   --arch BNInception --crop_fusion_type TRN --test_segments 3

• 多尺度TRN的测试命令：

python test_models.py something RGB model/TRN_something_RGB_BNInception_TRNmultiscale_segment8_best.pth.tar \
   --arch BNInception --crop_fusion_type TRNmultiscale --test_segments 8

预训练模型与演示代码

• 下载在Something-Something、Something-Something-V2、Jester以及Moments in Time数据集上训练的预训练模型：

./download.sh

• 下载示例视频及提取的帧。您将获得一个mp4视频文件和一个包含该视频RGB帧的文件夹。

cd sample_data
./download_sample_data.sh

示例视频如下：

• 测试在Something-Something-V2上训练的预训练模型：

python test_video.py --arch BNInception --dataset somethingv2 \
    --weights pretrain/TRN_somethingv2_RGB_BNInception_TRNmultiscale_segment8_best.pth.tar \
    --frame_folder sample_data/bolei_juggling

结果：sample_data/bolei_juggling
0.500 -> 将某物抛向空中并接住
0.141 -> 将某物抛向空中后任其落下
0.072 -> 假装投掷某物
0.024 -> 投掷某物
0.024 -> 用某物击打某物

• 测试在Moments in Time上训练的预训练模型：

python test_video.py --arch InceptionV3 --dataset moments \
    --weights pretrain/TRN_moments_RGB_InceptionV3_TRNmultiscale_segment8_best.pth.tar \
    --frame_folder sample_data/bolei_juggling

结果：sample_data/bolei_juggling
0.982 -> 杂耍
0.003 -> 翻转
0.003 -> 旋转
0.003 -> 吸烟
0.002 -> 吹口哨

• 测试在mp4视频文件上的预训练模型：

python test_video.py --arch InceptionV3 --dataset moments \
    --weights pretrain/TRN_moments_RGB_InceptionV3_TRNmultiscale_segment8_best.pth.tar \
    --video_file sample_data/bolei_juggling.mp4 --rendered_output sample_data/predicted_video.mp4

上述命令使用ffmpeg从提供的视频--video_file中提取帧，并可选地根据用于预测的帧生成新视频--rendered_output，在视频左上角显示预测的类别。

• 手势识别网络摄像头演示脚本： python fps_dem_trn.py

待办事项

• 待办：网络摄像头演示脚本
• 待办：可视化脚本
• 待办：类别感知的数据增强

参考文献：

B. Zhou, A. Andonian, 和 A. Torralba. 视频中的时序关系推理。欧洲计算机视觉会议（ECCV），2018年。PDF

@article{zhou2017temporalrelation,
    title = {视频中的时序关系推理},
    author = {周博磊、安多尼安·亚历克斯、奥利瓦·奥德、托拉尔巴·安东尼奥},
    journal={欧洲计算机视觉会议},
    year={2018}
}

致谢

我们的时序关系网络可以轻松插拔到TSN-Pytorch之上，但也可以方便地扩展到其他网络架构。我们感谢熊元俊发布TSN-Pytorch代码库。Something-Something数据集和Jester数据集来自TwentyBN，我们非常感激他们为构建这些优质视频数据集所做出的努力。请参考他们的数据集网站以正确使用这些数据。

TRN-pytorch 快速上手指南

TRN (Temporal Relation Networks) 是一个用于视频动作识别的深度学习模型，基于 TSN-pytorch 构建，擅长捕捉视频帧之间的时间关系。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 16.04+)
• Python: Python 3.x
• 深度学习框架: PyTorch (建议版本与官方 TSN 兼容，通常为 0.4.0 - 1.2.0，具体视显卡驱动而定)
• 其他依赖:
  • ffmpeg: 用于视频帧提取和处理。
  • git: 必须支持递归克隆。
  • CUDA 环境 (如需 GPU 训练/推理)。

前置依赖安装示例 (Ubuntu):

sudo apt-get update
sudo apt-get install ffmpeg git
pip install torch torchvision opencv-python numpy

2. 安装步骤

重要提示：该项目依赖子模块（特别是 Inception 系列 CNN 架构），必须使用 --recursive 参数克隆，否则无法运行。

2.1 克隆代码库

git clone --recursive https://github.com/metalbubble/TRN-pytorch
cd TRN-pytorch

2.2 下载预训练模型 (可选)

如果您只想进行测试或演示，可以直接下载官方提供的预训练模型：

./download.sh

2.3 准备示例数据 (可选)

下载用于测试的示例视频和提取后的帧：

cd sample_data
./download_sample_data.sh
cd ..

3. 基本使用

以下展示最基础的推理测试流程，直接使用预训练模型对示例视频进行动作分类。

3.1 单视频推理测试

假设您已下载了针对 "Something-Something-V2" 数据集训练的预训练模型，并准备了示例帧数据 sample_data/bolei_juggling。

运行以下命令进行测试：

python test_video.py --arch BNInception --dataset somethingv2 \
    --weights pretrain/TRN_somethingv2_RGB_BNInception_TRNmultiscale_segment8_best.pth.tar \
    --frame_folder sample_data/bolei_juggling

预期输出示例：

RESULT ON sample_data/bolei_juggling
0.500 -> Throwing something in the air and catching it
0.141 -> Throwing something in the air and letting it fall
...

3.2 直接处理 MP4 视频文件

如果您不想手动提取帧，可以直接输入 .mp4 视频文件（需安装 ffmpeg），并可生成带有预测结果的可视化视频：

python test_video.py --arch InceptionV3 --dataset moments \
    --weights pretrain/TRN_moments_RGB_InceptionV3_TRNmultiscale_segment8_best.pth.tar \
    --video_file sample_data/bolei_juggling.mp4 --rendered_output sample_data/predicted_video.mp4

3.3 核心模块说明

如果您希望在其他项目中集成 TRN，核心实现位于 TRNmodule.py。该模块设计为即插即用，可轻松嵌入到基于 TSN 架构的网络中。

---

注：如需从头训练模型，请先参考原文档 "Data preparation" 部分准备 Something-Something、Jester 或 Charades 数据集，并使用 process_dataset.py 生成索引文件。