Bird Species Classification

This workspace contains a trained MobileNetV2 model for bird-species classification, the notebooks used to train and test it, and the dataset layout used for training/validation/testing.

Highlights

• Trains MobileNetV2 on ~525 bird species
• Exports the Keras model birds_mobilenetv2.keras
• Includes notebooks to reproduce training and to test GPU/CUDA
• Uses a local HuggingFace cache (configured in the notebooks)

Important files

• Birds_MobileNetV2.ipynb – training, evaluation, and export cells
• test_gpu_cuda.ipynb – quick GPU/CUDA sanity checks
• birds_mobilenetv2.keras – exported Keras model (inference-ready)
• requirements_gpu.txt – Python dependencies (GPU-enabled TensorFlow build expected)
• data/ – dataset root with train/, valid/, and test/ subfolders; each class is a subdirectory containing images

Data layout

• The data/ directory contains train/, valid/, and test/.
• Each of those contains one folder per class. Folder names are numeric class IDs (e.g. 0, 1, ..., 525). The class-to-index mapping corresponds to these folder names.

Quick setup

1. Create a virtual environment (recommended):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2. Install dependencies:

pip install -r requirements_gpu.txt

3. (Optional) Configure HuggingFace cache location for the session (the notebooks set this to E:\hf_cache):

# for current session only
$env:HF_HOME = "E:\hf_cache"
# or persist across sessions (Windows)
# setx HF_HOME "E:\hf_cache"

Running the notebooks

• Open Birds_MobileNetV2.ipynb and run the cells sequentially. The notebook trains, evaluates, and exports birds_mobilenetv2.keras.
• Use test_gpu_cuda.ipynb to confirm your GPU/CUDA setup if you plan to train or run inference on GPU.

Quick inference example (Python)

from tensorflow.keras.models import load_model
from PIL import Image
import numpy as np
import os

# Load model
model = load_model('birds_mobilenetv2.keras')

# Load and preprocess an image
img = Image.open('data/test/0/sample.jpg').convert('RGB').resize((224, 224))
arr = np.array(img) / 255.0
pred = model.predict(arr[np.newaxis, ...])[0]
pred_idx = int(np.argmax(pred))

# Map index back to class folder name (labels derived from data/train folder names)
labels = sorted(os.listdir('data/train'))
print('Predicted index:', pred_idx)
print('Predicted class folder:', labels[pred_idx])

Notes & tips

• requirements_gpu.txt expects a GPU-enabled TensorFlow compatible with your CUDA/cuDNN versions — install matching drivers first.
• If you don't have a GPU, install a CPU TensorFlow build instead (adjust requirements_gpu.txt or create a separate requirements_cpu.txt).
• The notebooks include code to force the HuggingFace cache directory to E:\hf_cache — change that path if needed.

Contact / next steps

• If you want, I can add a small inference script (infer.py) and a labels file generated from data/train to make CLI inference trivial. Ask and I will add it.

Exact CLI commands used (PowerShell)

Create and activate the virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Install dependencies:

pip install -r requirements_gpu.txt

Create the example image used for the demo:

.venv\Scripts\python scripts/create_example_image.py

Run inference (example used during verification):

.venv\Scripts\python infer.py --image data/test/0/example.jpg --model birds_mobilenetv2.keras --labels labels.txt --topk 3

Notes from the verification run:

• Inference ran inside the virtualenv and loaded birds_mobilenetv2.keras.
• TensorFlow detected the GPU and issued a mixed-precision compatibility warning on NVIDIA GeForce GTX 1080 (compute capability 6.1); inference completed successfully.

Labels guidance

• The model was trained using human-readable class names from the HuggingFace dataset. If your labels.txt contains numeric IDs (folder names), infer.py will still run but will print numeric IDs rather than species names.
• To generate a numeric, integer-sorted labels.txt (stable index → ID mapping), run:

.venv\Scripts\python scripts/generate_numeric_labels.py

• To fetch the original human-readable labels from the HuggingFace dataset used for training, run (requires internet and the datasets package):

.venv\Scripts\python -c "from datasets import load_dataset; names=load_dataset('yashikota/birds-525-species-image-classification')['train'].features['label'].names; open('labels_hf.txt','w',encoding='utf-8').write('\n'.join(names))"

After generating labels_hf.txt, call infer.py --labels labels_hf.txt to get species names in the output.