GPYOLO

Paper status: under review at Computers and Electronics in Agriculture.

GPYOLO is a YOLOv11-based detector for real-time fish disease recognition in complex aquaculture scenes. It is designed for practical deployment under turbidity, unstable illumination, occlusion, background clutter, blurred lesion boundaries, and resource-constrained edge hardware. This repository contains the modified model definitions, training code, evaluation scripts, and analysis utilities used in our study.

• Built on YOLOv11 for multi-species and multi-disease fish health monitoring.
• Introduces C3k2-LSKA to strengthen lesion-aware feature extraction in degraded underwater scenes.
• Replaces standard neck convolutions with DSConv for lightweight deployment.
• Uses Adaptive Threshold Focal Loss (ATFL) to improve learning on hard and under-represented disease categories.
• Applies Masked Generative Distillation (MGD) to transfer knowledge from GPYOLO-l to GPYOLO-s.
• Supports both centralized cloud-side analysis and low-latency edge-side inspection.

The following headline numbers are reported in the manuscript on our fish disease benchmark:

ATFL especially improves under-represented classes:

GPYOLO combines four core improvements:

1. C3k2-LSKA: enlarges the effective receptive field and enhances subtle lesion texture modeling.
2. DSConv: reduces computation and memory overhead in the neck while preserving accuracy.
3. ATFL: reweights hard diseased samples and suppresses easy healthy samples under long-tailed imbalance.
4. MGD: distills knowledge from a larger teacher into a lightweight student model.

These components are tailored for fish disease detection where lesions can be small, partially occluded, weakly contrasted, or visually confused with the surrounding underwater background.

Our dataset contains:

• 2,055 annotated images.
• 11 fish species.
• 22 fine-grained categories.
• Disease phenotypes including EUS, bacterial, fungal, parasitic, and viral diseases.

Species covered in the manuscript include Miichthys miiuy, Yellowtail, Brown croaker, Salmon, Carp, Goldfish, Tilapia, Colisa lalia, Snapper, Selenotoca multifasciata, and Crucian carp.

The manuscript dataset was assembled from previous in-house datasets and public fish disease image resources. This repository provides dataset configuration files such as data/NEU-DET.yaml, but the raw training images are not bundled in the repository.

GPYOLO/
├── assets/                         # README figures
├── data/                           # dataset YAML files
├── heatmap_test-pictures/          # example images for visualization
├── ultralytics/                    # modified Ultralytics codebase
├── train.py                        # training entry script
├── val.py                          # validation example script
├── get_FPS.py                      # latency / FPS benchmark
├── heatmap.py                      # Grad-CAM style visualization
├── MuHuTuiLi.py                    # robustness evaluation script
├── grouped_atfl_results.csv        # grouped ATFL results
├── grouped_tail_performance.png    # ATFL summary plot
└── metrice_curve.png               # training metrics curve

git clone https://github.com/moonburntcat/GPYOLO.git
cd GPYOLO

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
# source .venv/bin/activate

pip install -e .

If you want to run heatmap.py, install the Grad-CAM dependency as well:

pip install grad-cam

Before training, update the path field in data/NEU-DET.yaml so it points to your local dataset root.

The repository includes a ready-to-run training script:

python train.py

Equivalent CLI usage:

yolo detect train \
  model=ultralytics/cfg/models/11/yolo11-C3k2_LSKA+DSConv1.yaml \
  data=data/NEU-DET.yaml \
  epochs=200 \
  imgsz=640 \
  batch=4 \
  device=0

Validation:

yolo detect val \
  model=path/to/best.pt \
  data=data/NEU-DET.yaml \
  split=test \
  imgsz=640 \
  device=0

Inference:

yolo detect predict \
  model=path/to/best.pt \
  source=path/to/images \
  imgsz=640 \
  device=0 \
  save=True

• get_FPS.py: benchmarks latency and FPS for a given checkpoint.
• heatmap.py: generates class activation maps for qualitative analysis.
• MuHuTuiLi.py: evaluates performance under multiple simulated turbidity levels.
• plot_result.py: reproduces comparison plots from saved CSV results.

Example FPS benchmark:

python get_FPS.py --weights path/to/best.pt --device 0 --batch 1

• data/NEU-DET.yaml currently contains an author-local dataset path. Replace it with your own path before training or validation.
• Some utility scripts still contain hardcoded checkpoint names or local paths such as 3up.pt, 11s.pt, or absolute directories. Please edit them to match your environment.
• Raw dataset files and trained GPYOLO checkpoints are not included in the repository.

If you find this repository useful, please cite the manuscript:

@article{wang2026gpyolo,
  title   = {GPYOLO for Real-Time Fish Disease Detection in Complex Aquaculture Scenes with Cloud and Edge Deployment},
  author  = {Wang, Duanrui and Ge, Fan and Zheng, Lianghao and Zhang, Chun and Qin, Qiwei and Wang, Shaowen and Shi, Yi and Wu, Chi},
  journal = {Computers and Electronics in Agriculture},
  year    = {2026},
  note    = {Under review}
}

This project is built on top of the Ultralytics YOLO codebase. We thank the open-source community and the aquaculture experts who contributed to data collection and annotation.