# FishAction

> **仓库瘦身说明**：为减小部署体积，已移除本目录下的 `slowfast/`（PySlowFast 完整训练工程）。当前默认推理与训练入口为 **PyTorchVideo X3D**（`train_pytorchvideo_x3d.py`、`predict_video_x3d_3class.py`）。若需恢复 SlowFast，请从备份或上游 `facebookresearch/SlowFast` 自行放回。

基于深度学习的鱼类行为识别与分类系统，通过分析输入视频片段自动识别和分类鱼类的各种行为动作。

## 📋 目录

- [项目简介](#项目简介)
- [推荐模型](#推荐模型)
- [功能特性](#功能特性)
- [环境要求](#环境要求)
- [安装指南](#安装指南)
- [数据集准备](#数据集准备)
- [使用方法](#使用方法)
- [模型训练](#模型训练)
- [模型评估](#模型评估)
- [推理预测](#推理预测)
- [项目结构](#项目结构)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

## 🐟 项目简介

FishAction 是一个专门用于鱼类行为识别和分类的深度学习项目。通过分析视频片段，系统能够自动识别和分类鱼类的各种行为，如游动、觅食、逃避、社交等。该项目可应用于：

- 海洋生态学研究
- 水产养殖监控
- 鱼类行为分析
- 生物多样性保护

## 🎯 推荐模型

### 基于 PySlowFast 代码库

本项目基于 [PySlowFast](https://github.com/facebookresearch/SlowFast) 代码库构建，这是 Facebook AI Research (FAIR) 提供的开源视频理解代码库。PySlowFast 提供了多种先进的视频动作识别模型实现，包括：

- **X3D**: 轻量级高效的视频识别模型
- **SlowFast**: 双路径架构，慢路径捕获空间语义，快路径捕获时间动态
- **MViT**: 多尺度视觉 Transformer
- **I3D**: Inflated 3D ConvNet
- **C2D**: 2D CNN 基线
- **Non-local Network**: 非局部神经网络
- **VideoMAE**: 基于掩码自编码器的视频预训练
- **Rev-ViT**: 可逆视觉 Transformer

### 主要推荐：X3D 系列模型

**X3D (Expandable 3D Networks)** 是 Facebook AI Research 开发的轻量级视频动作识别模型，专门为效率和性能的平衡而设计。推荐使用 **X3D-M** 或 **X3D-S** 变体：

#### 为什么选择 X3D？

✅ **速度快**：相比传统 3D CNN 模型（如 I3D、SlowFast），X3D 在保持高精度的同时显著提升了推理速度

✅ **模型小**：参数量适中，易于微调和部署

✅ **性能好**：在 Kinetics-400、Kinetics-600 等大型数据集上表现优异

✅ **易微调**：提供预训练权重，支持快速迁移学习

✅ **多尺度**：提供 XS、S、M、L、XL 等多个变体，可根据需求选择

#### 模型变体对比

| 模型 | 参数量 | FLOPs | 速度 | 推荐场景 |
|------|--------|-------|------|----------|
| X3D-XS | ~3.8M | 0.38G | 最快 | 实时推理、资源受限 |
| X3D-S | ~13.2M | 1.3G | 快 | **推荐：平衡速度与精度** |
| X3D-M | ~24.1M | 6.2G | 中等 | **推荐：更高精度需求** |
| X3D-L | ~77.6M | 26.6G | 较慢 | 高精度要求 |

#### 其他可选模型

- **SlowFast**: 双路径架构，精度高，适合对精度要求高的场景
- **MViT**: 基于 Transformer 的多尺度模型，适合复杂场景
- **VideoMAE**: 基于 Masked Autoencoder 的视频模型，精度高但速度较慢
- **I3D**: 经典的 3D CNN 模型，稳定可靠

## ✨ 功能特性

- 🎥 支持多种视频格式输入（MP4, AVI, MOV 等）
- 🔄 支持模型微调（Fine-tuning）
- 📊 提供详细的训练和评估指标
- 🚀 快速推理，支持批量处理
- 📈 可视化训练过程和结果
- 🔧 易于扩展和自定义

## 💻 环境要求

- Python >= 3.8
- PyTorch >= 1.10.0
- CUDA >= 11.0 (GPU 推荐)
- ffmpeg (用于视频处理)

## 📦 安装指南

### 0. Git 认证配置（重要）

**为了避免每次推送/拉取时输入用户名和密码，强烈建议配置 SSH 密钥。**

详细配置步骤请参考：[SETUP_GIT.md](SETUP_GIT.md)

配置完成后，使用 SSH URL 克隆仓库：
```bash
git clone --recursive git@github.com:yourusername/FishAction.git
```

### 1. 克隆仓库（包含子模块）

```bash
# 方式一：克隆时同时初始化子模块
git clone --recursive https://github.com/yourusername/FishAction.git
cd FishAction

# 方式二：如果已经克隆了仓库，需要初始化子模块
git submodule update --init --recursive
```

### 2. 安装 PySlowFast

进入 SlowFast 子模块目录并安装：

```bash
cd slowfast
python setup.py build develop
cd ..
```

### 3. 创建虚拟环境

```bash
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows
```

### 4. 安装依赖

```bash
pip install -r requirements.txt
```

### 5. 安装 PyTorch (根据你的 CUDA 版本)

```bash
# CUDA 11.3
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu113

# CPU only
pip install torch torchvision torchaudio
```

### 6. 安装其他依赖

根据 PySlowFast 的要求，可能还需要安装：

```bash
pip install fvcore iopath simplejson av psutil opencv-python tensorboard
```

> **注意**：详细的安装说明请参考 `slowfast/INSTALL.md`

## 📁 数据集准备

### 数据集结构

建议按以下结构组织数据集：

```
dataset/
├── train/
│   ├── swimming/
│   │   ├── video1.mp4
│   │   ├── video2.mp4
│   │   └── ...
│   ├── feeding/
│   │   ├── video1.mp4
│   │   └── ...
│   └── escaping/
│       └── ...
├── val/
│   └── (same structure as train)
└── test/
    └── (same structure as train)
```

### 数据集要求

- 视频格式：MP4, AVI, MOV 等常见格式
- 视频长度：建议 2-10 秒
- 分辨率：建议 224x224 或更高
- 帧率：建议 30fps

## 🚀 使用方法

### 快速开始

```bash
# 使用预训练模型进行推理
python infer.py --video_path path/to/video.mp4 --model_path path/to/model.pth
```

## 🎓 模型训练

### 1. 准备配置文件

PySlowFast 使用 YAML 配置文件。可以参考 `slowfast/configs/` 目录下的示例配置文件，或创建自定义配置：

```bash
# 查看可用的配置文件
ls slowfast/configs/

# 例如使用 X3D-M 配置
cp slowfast/configs/Kinetics/X3D_M.yaml configs/x3d_m_fish.yaml
```

修改配置文件中的关键参数：

```yaml
MODEL:
  NUM_CLASSES: 10  # 你的鱼类行为类别数
  ARCH: x3d
  MODEL_NAME: X3D
  DEPTH: 16
  FRAME_HEIGHT: 224
  FRAME_WIDTH: 224

DATA:
  PATH_TO_DATA_DIR: "dataset"
  PATH_PREFIX: ""
  TRAIN_LISTS: ["train.csv"]
  TEST_LISTS: ["val.csv"]
  NUM_FRAMES: 16
  SAMPLING_RATE: 1

TRAIN:
  ENABLE: True
  BATCH_SIZE: 8
  NUM_WORKERS: 4
  EPOCHS: 50
  BASE_LR: 0.001
```

### 2. 准备数据列表

PySlowFast 需要 CSV 格式的数据列表文件，格式如下：

```csv
path/to/video1.mp4 0
path/to/video2.mp4 1
path/to/video3.mp4 0
...
```

### 3. 开始训练

使用 PySlowFast 的训练工具：

```bash
python slowfast/tools/run_net.py \
    --cfg configs/x3d_m_fish.yaml \
    DATA.PATH_TO_DATA_DIR dataset \
    DATA.PATH_PREFIX "" \
    NUM_GPUS 1 \
    TRAIN.BATCH_SIZE 8
```

### 4. 使用预训练权重

PySlowFast 支持从 Kinetics 预训练权重开始微调。预训练权重会自动下载，或手动下载后指定路径：

```bash
# 在配置文件中设置
MODEL:
  PRETRAINED_MODEL_FILE: "path/to/pretrained/x3d_m.pyth"
```

## 📊 模型评估

使用 PySlowFast 的评估工具：

```bash
python slowfast/tools/run_net.py \
    --cfg configs/x3d_m_fish.yaml \
    DATA.PATH_TO_DATA_DIR dataset \
    TEST.ENABLE True \
    TEST.CHECKPOINT_FILE_PATH checkpoints/best_model.pyth \
    NUM_GPUS 1
```

## 🔮 推理预测

### 单视频推理

```bash
python infer.py \
    --video_path path/to/video.mp4 \
    --model_path checkpoints/best_model.pth \
    --output_path result.json
```

### 批量推理

```bash
python infer.py \
    --video_dir path/to/videos \
    --model_path checkpoints/best_model.pth \
    --output_dir results/
```

## 📂 项目结构

```
FishAction/
├── README.md
├── requirements.txt
├── slowfast/             # PySlowFast 子模块（包含 X3D、SlowFast 等模型实现）
│   ├── slowfast/         # 核心代码
│   ├── configs/          # 模型配置文件
│   ├── tools/            # 训练和评估工具
│   └── ...
├── configs/              # 项目配置文件
│   ├── x3d_s_config.yaml
│   └── x3d_m_config.yaml
├── src/
│   ├── models/           # 自定义模型扩展
│   ├── data/             # 数据处理
│   │   ├── dataset.py
│   │   └── transforms.py
│   ├── train.py          # 训练脚本（基于 PySlowFast）
│   ├── evaluate.py       # 评估脚本
│   └── infer.py          # 推理脚本
├── utils/                # 工具函数
│   ├── logger.py
│   └── visualization.py
├── checkpoints/          # 模型检查点
└── results/              # 结果输出
```

> **注意**：`slowfast/` 目录是 git 子模块，包含了完整的 PySlowFast 代码库。所有模型实现和训练工具都在此目录中。

## 📚 参考资料

### 代码库

- [PySlowFast 官方仓库](https://github.com/facebookresearch/SlowFast) - Facebook AI Research 的视频理解代码库
- [PySlowFast 模型库](https://github.com/facebookresearch/SlowFast/blob/main/MODEL_ZOO.md) - 预训练模型和基准测试结果

### 论文

- [X3D: Expanding Architectures for Efficient Video Recognition](https://arxiv.org/abs/2004.04730)
- [SlowFast Networks for Video Recognition](https://arxiv.org/abs/1812.03982)
- [MViT: Multiscale Vision Transformers](https://arxiv.org/abs/2104.11227)
- [VideoMAE: Masked Autoencoders are Data-Efficient Learners for Self-Supervised Video Pre-Training](https://arxiv.org/abs/2203.12602)

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 🙏 致谢

- [Facebook AI Research (FAIR)](https://ai.facebook.com/research/) 提供的 [PySlowFast](https://github.com/facebookresearch/SlowFast) 代码库
- PyTorch 社区的支持
- 所有为视频理解领域做出贡献的研究者们

---

如有问题或建议，请提交 Issue 或联系项目维护者。