README.md

---
title: Butterfly Classifier
emoji: 🦋
colorFrom: red
colorTo: blue
sdk: gradio
sdk_version: "5.44.1"
app_file: app.py
pinned: false
short_description: Upload a photo to use a model for butterfly classification
---

# 🦋 Butterfly Classifier — Live Demo

Upload a butterfly photo and see the **top-k** predicted species with confidence scores.

Standalone app window: https://michaelmwb-butterfly-classifier.hf.space/

For access to dataset of butterfly images, go → [here](https://drive.google.com/drive/folders/1EzBWq2fndev6-8rkBhKb2OtMmYOFyYHQ?usp=sharing)

---

## How to use
1. **Upload image** (JPG/PNG).  
2. Set **Top-k** (default: 5).  
3. Click **Predict** → the app returns the top classes with confidences.

> **Device:** The app selects the best device automatically (GPU if available on the Space, otherwise CPU). A manual **CPU** option is provided if needed.

---

## For best results
- Single butterfly, centered, sharp focus  
- Plain/clean background (avoid clutter)  
- Show full wings; crop out large borders  
- Good lighting; avoid harsh shadows or filters  
- Image size around **800–1200 px** on the short side

---

## What this demo shows
- **Top-k predictions** with confidence scores  
- **Auto device selection** (GPU/CPU) with a CPU fallback  
- Clean, upload-only interface (webcam disabled for maximum compatibility)

---

## Model & data (short card)
- **Backbone:** `VGG16` (transfer learning)  
- **Classes:** 75 butterfly species  
- **Training:** fine-tuned classifier head; ImageNet mean/std normalization  
- **Validation performance:** ~**90%** top-1 accuracy on held-out data  
- **Weights:** hosted on the Hub → [`MichaelMwb/butterfly-vgg16`](https://huggingface.co/MichaelMwb/butterfly-vgg16)

> **Note:** Accuracy depends on photo quality and how close the image distribution is to the training set.

---

## Privacy & disclaimer
- **Privacy:** Images are processed **in memory** and are **not stored** by this app.  
- **Disclaimer:** This is a research demo. Predictions may be incorrect—use as suggestions, not definitive IDs.

---

## Known limitations
- **Webcam:** intentionally **disabled** to avoid browser permission issues; upload works everywhere.
- **Edge cases:** unusual angles, heavy occlusion, extreme lighting, or multiple butterflies may reduce accuracy.

---