Fish Auto

鱼类实验视频的单鱼跟踪与行为分析项目。

这个仓库现在的目标是做成一个可复用的单视频检测平台：给一段视频和 CAC/信息素 加入时间，就能自动生成轨迹和行为统计结果。仓库里仍保留了那批历史实验视频，但主入口已经不再依赖固定视频名。

这个项目现在能做什么

• 从 videos/*.wmv 生成单鱼轨迹
• 对任意单个视频执行“跟踪 + 分析”一键流程
• 自动识别水槽 ROI，过滤明显的离群检测
• 对 1大CAC.wmv 这类解码不稳定的 WMV 自动转成稳定缓存视频再跟踪
• 输出轨迹 JSON、摘要图和可选 GIF
• 基于轨迹统计 游泳 / 静止 / 后退 / 跳水
• 输出机器可读的 behavior_summary.json / behavior_summary.csv
• 仍支持对 36大CAC / 37大CAC / 38大CAC / 1大CAC / 1小 做批量回归分析

当前目录

fish_auto/                         Python 包与 CLI 入口
process_video.py                   单视频一键处理
serve_web_ui.py                    本地 Web/UI 壳子
track_fish_trajectory.py           单视频跟踪
analyze_fish_behavior.py           行为分析
diagnose_behavior_metrics.py       诊断脚本
run_all_trajectory_and_analyze.py  批量流程
videos/                            原始实验视频
weights/                           模型权重
docs/                              补充文档
webui/                             Web 页面资源
start_web_ui.command               一键启动 Web/UI
README.md                          项目说明
pyproject.toml                     包定义与 CLI 入口
requirements.txt                   依赖清单

更详细的结构说明见 docs/PROJECT_STRUCTURE.md。

命名说明：

• 历史实验名 1小CAC 对应原始视频 videos/1小.wmv
• 这条视频的输出目录是 runs/1小/，不是 runs/1小CAC/

快速开始

1. 安装

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
pip install -e .

如果后续确实要跑 ONNX/RAFT 相关流程，再额外安装：

pip install 'fish-auto[onnx]'

2. 一键处理单视频

python process_video.py /path/to/video.wmv --cac-time 05:22

或：

fish-auto process /path/to/video.wmv --cac-time 05:22

默认会：

• 生成或复用 runs/<视频名>/fish_trajectory/trajectory.json
• 计算 CAC 前后行为统计
• 写出 runs/<视频名>/behavior_analysis/behavior_summary.json
• 写出 runs/<视频名>/behavior_analysis/behavior_summary.csv

常用参数：

• --run-name custom_name
  • 避免不同目录下同名视频写到同一个 runs/<stem>/
• --skip-track
  • 已有轨迹时只重跑分析
• --force-track
  • 强制重新生成轨迹

3. 仅生成单视频轨迹

python track_fish_trajectory.py videos/1大CAC.wmv

或：

fish-auto track videos/1大CAC.wmv

默认行为：

• 优先使用 runs/fish_yolo_retrain_yolo2_mps2/weights/best.pt
• 如果不存在，再回退到 weights/fish_yolo.pt
• 检测到 .wmv 时，必要时会在 runs/_video_cache/ 生成稳定跟踪缓存

输出目录示例：

runs/1大CAC/fish_trajectory/
├── trajectory.json
├── trajectory_summary.png
└── trajectory_animation.gif   # 需要 Pillow + imageio

4. 单独跑行为分析

python analyze_fish_behavior.py --video videos/1大CAC.wmv --cac-time 05:22 --save-report

或：

fish-auto analyze --video videos/1大CAC.wmv --cac-time 05:22 --save-report

不带参数运行 python analyze_fish_behavior.py 时，仍会按历史实验配置批量分析。

5. 跑诊断

fish-auto diagnose

6. 启动本地 Web/UI

最省事的方式：

./start_web_ui.command

它会优先使用项目自己的 .venv，首次运行会自动创建虚拟环境并安装依赖，然后启动并自动打开浏览器。

也可以继续手动运行：

fish-auto web --port 8000

或：

python serve_web_ui.py --port 8000

打开 http://127.0.0.1:8000 后，可以：

• 填本地视频路径，或直接上传一个视频
• 输入 CAC 时间
• 直接发起单视频处理
• 查看实时日志、行为统计和结果文件入口

主要脚本

• process_video.py
  • 通用单视频入口
  • 输入视频路径和 CAC 时间，自动跑完整流程并落盘结果
• serve_web_ui.py
  • 本地 Web/UI 启动入口
• fish_auto/webapp.py
  • Web 后端
  • 负责提交任务、轮询状态、展示结果文件
• track_fish_trajectory.py
  • 单视频跟踪主入口
  • 现在包含 WMV 缓存转码、重新挂轨、轨迹元数据写出
• analyze_fish_behavior.py
  • 读取轨迹 JSON，做静止/游泳/后退/跳水统计
  • 当前规则以平滑轨迹和连续帧约束为主
• diagnose_behavior_metrics.py
  • 用于检查覆盖率、速度分布和行为规则是否合理

输入与输出

输入

• videos/
  • 实验视频
• weights/
  • 基础模型

输出

• runs/
  • 运行时自动创建，不在最小上传包中预置
• runs/<视频名>/fish_trajectory/
  • 正式轨迹结果
• runs/_video_cache/
  • WMV 的稳定缓存视频源
• runs/<run_name>/behavior_analysis/
  • 行为统计 JSON/CSV 报告
• webui/
  • Web 页面模板和静态资源

已知限制

• 当前仍假设视频里只有一条主要鱼轨迹
• 行为分析仍然是规则法，不是端到端行为分类模型
• 后退 和 跳水 仍属于启发式指标，可信度低于 静止/游泳
• 批量模式里那组 CAC 时间点仍是历史实验配置；通用流程请显式传 --cac-time
• Web UI 目前是本地单机壳子，不做用户系统、任务持久化或分布式调度

推荐用法

• 新视频优先使用 fish-auto process <video> --cac-time <time>
• 日常分析结果优先看 runs/<run_name>/behavior_analysis/behavior_summary.json
• 调试时先跑 fish-auto diagnose

其他文档

• docs/PROJECT_STRUCTURE.md
• docs/WORKFLOW.md