Bird Species Classifier

A fine-grained bird species classifier for 200 species, built on DINOv2 ViT-B/14 fine-tuned with a linear probe warmup. The Streamlit app accepts any bird photo and returns top-5 predictions with confidence bars, hover thumbnails from the training set, attention rollout, and last-layer attention visualizations.

---

Prerequisites

• Python 3.8+ (tested on 3.12)
• A Kaggle account with API credentials configured (for downloading the dataset)
• Trained model weights (see below — weights are not included in this repo)

---

1. Install dependencies

From the BirdClassification/ directory:

pip install -r requirements.txt

If you are using a conda environment, activate it first:

conda activate myenv
python -m pip install -r requirements.txt

---

2. Configure Kaggle credentials

The data download script uses the Kaggle API. You need a kaggle.json credentials file before running it.

1. Log in to kaggle.com and go to Account -> API -> Create New Token.
2. This downloads kaggle.json.
3. Place it at ~/.kaggle/kaggle.json and restrict its permissions:

mkdir -p ~/.kaggle
mv ~/Downloads/kaggle.json ~/.kaggle/kaggle.json
chmod 600 ~/.kaggle/kaggle.json

---

3. Download the dataset

Run the data puller from the BirdClassification/ directory. It downloads the 200-class bird dataset from Kaggle and places Train/ and Test/ inside data/:

python utils/data_puller.py

The script is a no-op if data/Train/ and data/Test/ already exist.

---

4. Obtain trained model weights

The app requires three files that are produced by running src/train.ipynb. They are not included in this repository and must be generated by training the model yourself.

Recommended: train on Google Colab (free T4 GPU, ~30 min)

1. Upload src/train.ipynb to Google Colab.
2. Set the runtime to GPU: Runtime -> Change runtime type -> T4 GPU.
3. Run all cells. The notebook will mount Google Drive and save weights there automatically.
4. Download the following three files from MyDrive/bird_classifier/ in your Google Drive:

File	Description
best_vit.pth	Model weights checkpoint
class_names.json	Ordered list of 200 class names
model_config.json	Model architecture and normalisation config

5. Place all three files in BirdClassification/models/:

BirdClassification/
└── models/
    ├── best_vit.pth
    ├── class_names.json
    └── model_config.json

---

5. Run the app

From the BirdClassification/ directory:

python -m streamlit run src/app.py

Open the URL printed in the terminal (default: http://localhost:8501).

If you are using a conda environment:

conda run -n myenv python -m streamlit run src/app.py

---

Project structure

BirdClassification/
├── data/
│   ├── Train/          # 200 class subdirectories, ~48 images each
│   └── Test/           # 200 class subdirectories, ~12 images each
├── models/             # Place trained weights here (not in repo)
├── src/
│   ├── app.py          # Streamlit demo app
│   └── train.ipynb     # Training notebook (run in Colab)
├── utils/
│   └── data_puller.py  # Downloads dataset from Kaggle
└── requirements.txt