380 lines
10 KiB
Markdown
380 lines
10 KiB
Markdown
# 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 或联系项目维护者。
|