Skip to content

Build and train a custom model to identify birds visiting bird feeders

License

Notifications You must be signed in to change notification settings

Alyetama/BirdFSD-YOLOv5

Repository files navigation

BirdFSD-YOLOv5

Build and train a custom model to identify birds visiting bird feeders.

📖 Documentation

Poetry Build Docker Build Documentation Status Supported Python versions PEP8 Codacy Badge GitHub latest release Docker Hub GitHub License

Requirements

🚀 Getting started

Fork and clone this repository

  • Then, click on and enable all the workflows that are highlighted wuth a red square in the image below:

  • Clone the repository:
git clone https://github.com/bird-feeder/BirdFSD-YOLOv5.git
cd BirdFSD-YOLOv5
git clone https://github.com/ultralytics/yolov5.git

Install dependencies

  • If you're on an Apple silicon device (Apple M1), follow the instructions here. Otherwise, run:
pip install -r requirements.txt

Instructions for Apple M1 users

Click here
# Skip this if you're not on an Apple silicon device!

# If you don't have conda, install it:
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh"
bash "Miniforge3-MacOSX-arm64.sh" -b
rm "Miniforge3-MacOSX-arm64.sh"
conda init zsh
source ~/.zshrc
conda activate

# Then, run:
yes | pip uninstall grpcio
conda install grpcio --yes
pip install -r requirements.txt

Build the package

poetry build
pip install .

🌱 Environment Variables

  • rename .env.example to .env, then edit the values based on the table below.
mv .env.example .env
nano .env  # or with any other editor
# See the table for details about the environment variables.
Name Value
TOKEN Label-Studio Access Token.
LS_HOST The URL of the label-studio app (e.g., https://label-studio.example.com) – make sure you include https:// in the URL.
DB_CONNECTION_STRING MongoDB connection string (e.g., mongodb://mongodb0.example.com:27017). See this article for details.
DB_NAME Name of the main MongoDB database (default: label_studio).
S3_ACCESS_KEY (Optional) The S3 bucket's Access Key ID.
S3_SECRET_KEY (Optional) The S3 bucket's Secret Key.
S3_REGION (Optional) The S3 bucket's region (default: us-east-1).
S3_ENDPOINT (Optional) The S3 bucket's endpoint/URL server.
EXCLUDE_LABELS (Optional) Comma-separated list of labels to exclude from processing (e.g., label a,label b).
  • When you're done editing the .env file, run:
python birdfsd_yolov5/model_utils/check_env_file.py --env-file .env

🗃️ Setup

  • To use the GitHub Actions workflows (recommended!), you will need to add every environment variable and its value from .env to the Secrets of your fork (you can find Secrets under Settings).

Click here to show an example of a new secret

🔧 Dataset preparation

  • Option 1: Run the JSON to YOLOv5 (data preprocessing) workflow under github Actions.

  • Option 2: Run it locally with:

    python birdfsd_yolov5/preprocessing/json2yolov5.py
    mv dataset-YOLO/dataset_config.yml .
    python birdfsd_yolov5/model_utils/relative_to_abs.py

⚡ Training1

Use the Colab notebook:

Open In Colab

📝 Prediction

  • Option 1: Run the Predict workflow under github Actions.

  • Option 2: Use the Colab notebook:

    Open In Colab

🐳 Using Docker

docker pull alyetama/birdfsd-yolov5:latest

Example Usage

docker run -it --env-file .env alyetama/birdfsd-yolov5 python birdfsd_yolov5/preprocessing/json2yolov5.py

🔖 Related

Footnotes

  1. yolov5/wiki/Train-Custom-Data