RU version:

---

Распознавание чаек с помощью YOLOv8 для мониторинга дикой природы

Данный репозиторий содержит проект по компьютерному зрению, который считает количество тихоокеанских чаек на острове Ушатуд, входящем в Южно-Камчатский федеральный заповедник. Модель построена с использованием YOLOv8 и обучена на изображениях с фотоловушки, чтобы помочь инспекторам заповедника в их природоохранной деятельности.

Пример фотографий чаек

---

Почему я делал этот проект?

Мне было интересно поработать с современными моделями компьютерного зрения, в частности YOLOv8, применить различные Data Augmentations к изображениями, освоить ClearML для отслеживания моделей, экспериментов и метрик, а также получить опыт создания полноценного ML проекта, а не просто Jupyter Notebook.

---

Используемые технологии:

• Python 3.11+
• NumPy
• Pandas
• OpenCV (cv2)
• TQDM
• Ultralytics YOLOv8
• PyTorch
• DataAugmentationForObjectDetection
• Requests

---

Структура проекта

seagull-detection-project/
├── data/
├── models/
├── notebooks/
│     └──Seagull_Count.ipynb
├── output/
├── scripts/
│   ├── prepare_data.py
│   ├── train.py
│   ├── predict.py
│   └── evaluate.py
├── src/
│   ├── __init__.py
│   ├── augmentations.py
│   ├── data_aug/
│   │     ├──__init__.py
│   │     ├──bbox_util.py
│   │     └──data_aug.py
│   ├── data_utils.py
│   └── processing.py
├──   .gitignore
├──   README.md
└──   requirements.txt

---

Установка

Для настройки среды проекта выполните следующее:

1. Клонируйте репозиторий:

   git clone https://github.com/mikhailvokhrameev/seagull_recognition_hackaton.git
   cd seagull_recognition_hackaton

2. Создайте и активируйте виртуальное окружение (рекомендуется):

   # Создание окружения
   python3 -m venv venv
   
   # Активация на macOS/Linux:
   source venv/bin/activate
   
   # Активация на Windows:
   # venv\Scripts\activate

3. Установите:

   pip install -r requirements.txt

---

Использование

Важно: Все команды должны запускаться из корневой папки проекта.

Шаг 1: Подготовка данных

Этот скрипт загружает датасет, распаковывает его и создает конфигурационный файл data.yaml, необходимый для обучения.

python -m scripts.prepare_data

Шаг 2: Тренировка модели

Этот скрипт обучает модель YOLOv8. При первом запуске следует использовать флаг --preprocess, чтобы применить все этапы обработки и дополнения данных.

# Для обучения с предобработкой на GPU (рекомендуется)
python -m scripts.train --preprocess --epochs 200 --batch 16 --device 0

# Для обучения на CPU (будет очень медленно)
python -m scripts.train --preprocess --epochs 200 --batch 16 --device cpu

• Лучшие веса модели будут сохранены в новой папке runs/detect/train/. Для удобства скопируйте файл best.pt из этого каталога в каталог models/ перед запуском predict.

Шаг 3: Оценка эффективности модели

Используйте этот скрипт для проверки среднеквадратичной ошибки (RMSE) подсчетов вашей модели по сравнению с истинными labels в валидационной выборке.

python -m scripts.evaluate --weights models/best.pt --source valid/images/

Шаг 4: Запуск предсказания

Используйте этот скрипт для создания CSV-файла с данными о количестве чаек для новой папки с изображениями.

# Пример для тестового набора, расположенного в папке с именем «test_images»
python -m scripts.predict --weights models/best.pt --source test_images/ --output output/submission.csv

Итоговый файл submission.csv будет сохранен в папке output/.

---

Используемые внешние библиотеки и репозитории

Проект использует сторонний код для аугментации изображений:

• DataAugmentationForObjectDetection
  • Ссылка на репозиторий: https://github.com/Paperspace/DataAugmentationForObjectDetection
  • Лицензия: MIT
  • В проекте используется модуль data_aug для аугментаций изображений и bounding boxes.

---

ENG version:

---

YOLOv8 Seagull Detection for Wildlife Monitoring

This repository contains a computer vision project to count the number of slaty-backed gulls on Utashud Island, part of the South Kamchatka Federal Reserve. The model is built using YOLOv8 and trained on images from a camera trap to aid reserve inspectors in their conservation efforts.

Example of photos of seagulls

---

Why I did this project?

I was interested in working with modern computer vision models, specifically YOLOv8, applying various Data Augmentations to images, mastering ClearML for tracking models, experiments, and metrics, and gaining experience in creating a full-fledged ML project, rather than just a *Jupyter Notebook *.

---

Technologies used:

• Python 3.11+
• NumPy
• Pandas
• OpenCV (cv2)
• TQDM
• Ultralytics YOLOv8
• PyTorch
• DataAugmentationForObjectDetection
• Requests

---

Project Structure

seagull-detection-project/
├── data/
├── models/
├── notebooks/
│     └──Seagull_Count.ipynb
├── output/
├── scripts/
│   ├── prepare_data.py
│   ├── train.py
│   ├── predict.py
│   └── evaluate.py
├── src/
│   ├── __init__.py
│   ├── augmentations.py
│   ├── data_aug/
│   │     ├──__init__.py
│   │     ├──bbox_util.py
│   │     └──data_aug.py
│   ├── data_utils.py
│   └── processing.py
├──   .gitignore
├──   README.md
└──   requirements.txt

---

Setup and Installation

Follow these steps to set up the project environment.

1. Clone the Repository:

   ```bash
   git clone https://github.com/mikhailvokhrameev/seagull_recognition_hackaton.git
   cd seagull_recognition_hackaton

2. Create and Activate a Virtual Environment (Recommended): This isolates the project's dependencies from your system's Python installation.

   # Create the environment
   python3 -m venv venv
   
   # Activate it (on macOS/Linux)
   source venv/bin/activate
   
   # On Windows, use:
   # venv\Scripts\activate

3. Установите необходимые пакеты:

   pip install -r requirements.txt

---

Usage Workflow

Important: All commands should be run from the root directory of the project.

Step 1: Prepare the Data

This script downloads the seagull dataset, unzips it, and creates the data.yaml configuration file required for training.

python -m scripts.prepare_data

Step 2: Train the Model

This script trains the YOLOv8 model. The --preprocess flag should be used for the first run to apply all data processing and augmentation steps.

# To train with preprocessing on a GPU (recommended)
python -m scripts.train --preprocess --epochs 200 --batch 16 --device 0

# To train on a CPU (will be very slow)
python -m scripts.train --preprocess --epochs 200 --batch 16 --device cpu

• The best model weights will be saved in a new runs/detect/train/ directory. For convenience, copy the best.pt file from there into the models/ directory before running predictions.

Step 3: Evaluate Model Performance

Use this script to check the Root Mean Squared Error (RMSE) of your model's counts against the ground truth labels in the validation set.

python -m scripts.evaluate --weights models/best.pt --source valid/images/

Step 4: Run Predictions

Use this script to generate a submission CSV file with seagull counts for a new directory of images.

# Example for a test set located in a folder named 'test_images'
python -m scripts.predict --weights models/best.pt --source test_images/ --output output/submission.csv

The final submission.csv will be saved in the output/ folder.

---

External libraries and repositories used

The project uses third-party code for image augmentation:

• DataAugmentationForObjectDetection
  • Repository link: https://github.com/Paperspace/DataAugmentationForObjectDetection
  • License: MIT
  • The project uses the data_aug module for image and bounding box augmentation.