santosh3110/Ecoclassify-Wildlife_Classifier
0
1---2title: EcoClassify - Wildlife Classifier3emoji: 🦁4colorFrom: green5colorTo: blue6sdk: streamlit7sdk_version: "1.36.0"8app_file: app.py9pinned: false10---11 12# 🦉 EcoClassify – Wildlife Image Classifier 13 1415161718 19> **AI-powered wildlife conservation.** 20EcoClassify is an **end-to-end computer vision project** that classifies camera trap images into wildlife species using **transfer learning (ResNet50).** 21It includes **model explainability (Grad-CAM)**, **batch inference**, **fine-tuning via Streamlit UI**, and **MLflow/DagsHub integration** for experiment tracking. It was born out of the need to help researchers, educators, and nature lovers quickly identify species without needing to be a machine learning wizard. This project was developed as part of my internship at **Euron**, with heartfelt thanks to **Sudhanshu Kumar, Director of Euron,** for his guidance and mentorship.22 23🔗 **Live Demo on Streamlit Cloud**: 24[](https://ecoclassify---wildlife-image-classifier-ojyez7lpcmvjx25vmxr95c.streamlit.app/)25 26🔗 **Live Demo on Hugging Face**: [](https://huggingface.co/spaces/santosh3110/Ecoclassify-Wildlife_Classifier)27 28---29 30## 📸 App Screenshots 31 32| Inference (Single Image) | Grad-CAM Explainability |33|---------------------------|--------------------------|34|  |  | 35 36| Batch Inference | Fine-Tuning |37|-----------------|-------------|38|  |  | 39 40---41 42## 📖 Table of Contents 43 441. [About](#-about) 452. [Features](#-features) 463. [Architecture](#-architecture) 474. [Dataset](#-dataset) 485. [Installation](#-installation) 496. [Usage](#-usage) 507. [Streamlit App](#-streamlit-app) 518. [Training & Evaluation](#-training--evaluation) 529. [Explainability](#-explainability) 5310. [Batch Inference](#-batch-inference) 5411. [Fine-Tuning](#-fine-tuning) 5512. [Design Docs](#-design-docs) 5613. [Results](#-results) 5714. [Future Work](#-future-work) 5815. [Acknowledgements](#-acknowledgements) 59 60---61 62## 🌍 About 63 64Camera traps capture **millions of images** in wildlife conservation projects. Manual classification is slow, error-prone, and not scalable. 65 66**EcoClassify** provides: 67- 🔬 Automated **species classification** (7 classes + Blank). 68- 🖼️ **Explainability dashboard** (Grad-CAM heatmaps). 69- ⚡ **Batch inference** for CSV/ZIP datasets. 70- 🎛️ **Fine-tuning** interface for custom datasets. 71- 📊 **MLflow/DagsHub** experiment logging. 72 73---74 75## 🚀 Features 76 77- ✅ Species classification: *Antelope_Duiker, Bird, Civet_Genet, Hog, Leopard, Monkey_Prosimian, Rodent, Blank*. 78- ✅ **Transfer learning** with ResNet50 backbone. 79- ✅ **Grad-CAM** explainability for predictions. 80- ✅ **Streamlit app** with multiple tabs: Inference, Batch, Fine-tuning. 81- ✅ **Config-driven training** (YAML params & config). 82- ✅ **Experiment tracking** with MLflow + DagsHub. 83 84---85 86## 🏗️ Architecture 87 88### System Architecture 89 90```mermaid91flowchart TD92 A[User Uploads Image] --> B[Preprocessing & Augmentation]93 B --> C[Model Inference: ResNet50]94 C --> D[Predictions: Species + Confidence ]95 C --> E[Explainability Engine: Grad-CAM]96 D & E --> F[Streamlit Dashboard: Results]97 F --> G[Download CSV / Fine-tune Model]98```99 100### End-to-End Pipeline 101 102```mermaid103graph LR104 A[Data Ingestion] --> B[Data Loader]105 B --> C[Training Pipeline with MLflow Logging]106 C --> D[Evaluation of Models with MLflow Logging]107 D --> E[Batch Inference]108 E --> F[Streamlit App]109 F --> G[Model Fine Tuning]110```111 112### Project Structure 113 114```115.116EcoClassify---Wildlife-Image-Classifier/117│118├── app.py # Streamlit app entry point119├── main.py # Orchestrates full training → eval → inference pipeline120├── setup.py # Package setup121├── requirements.txt # Dependencies122├── README.md # Documentation123├── LICENSE124├── colab_code.ipynb # Code for running the repo on Google Colab125├── params.yaml # Hyperparameters126├── init_project_structure.py # Script to bootstrap project tree127│128├── artifacts/ # All experiment outputs129│ ├── base_model/ # Initial CNN model130│ ├── resnet50_model/ # ResNet50 base model131│ ├── training/ # Trained model checkpoints132│ ├── prepare_callbacks/ # Callback checkpoints133│ ├── evaluation/ # Confusion matrices & reports134│ ├── explanations/ # Grad-CAM heatmaps135│ ├── batch_inference/ # Batch predictions136│ ├── data_ingestion/ # Raw & processed datasets137│ └── streamlit_outputs/ # Models & mappings saved from app138│139├── config/140│ └── config.yaml # Centralized config file141│ 142├── docs/ # Project Documents143│ ├── PRD.pdf # Product Requirements & Specification Document144│ ├── HLD.pdf # High Level Design Document145│ └── LLD.pdf # Low Level Design Document146│147├── logs/148│ └── running_logs.log # Pipeline logs149│150├── research/ # Notebooks for experiments151│ └── experiment.ipynb152│ 153│154└── src/ecoclassify/ # Source code (modular package)155 ├── components/ # Core ML components156 │ ├── customcnn_base_model.py157 │ ├── resnet50_model.py158 │ ├── training.py159 │ ├── evaluation.py160 │ ├── explanation_generator.py161 │ ├── fine_tuning.py162 │ ├── batch_inference.py163 │ ├── data_ingestion.py164 │ └── data_loader.py165 │166 ├── pipeline/ # Orchestrated stages167 │ ├── stage_01_data_ingestion.py168 │ ├── stage_02_customcnn_base_model.py169 │ ├── stage_03_resnet_50_model.py170 │ ├── stage_04_model_training.py171 │ ├── stage_05_model_evaluation.py172 │ ├── stage_06_generate_explanations.py173 │ └── stage_07_batch_inference.py174 │175 ├── config/ # Config manager176 │ └── configuration.py177 │178 ├── constants/ # File paths & constants179 │ └── paths.py180 │181 ├── entity/ # Config/data entities182 │ └── config_entity.py183 │184 ├── utils/ # Utility functions185 │ ├── common.py186 │ └── logger.py187 │188 └── __init__.py189```190 191---192 193## 📚 Dataset 194 195- **Source**: Conser-vision Practice Area: Image Classification by drivendata.org196- **Provided by**: 197 *The Pan African Programme: The Cultured Chimpanzee, Wild Chimpanzee Foundation, DrivenData. (2022). Conser-vision Practice Area: Image Classification. Retrieved [July 12 2025] from https://www.drivendata.org/competitions/87/competition-image-classification-wildlife-conservation/.* 198 199---200 201## ⚙️ Installation 202 203```bash204git clone https://github.com/santosh3110/EcoClassify---Wildlife-Image-Classifier.git205cd EcoClassify---Wildlife-Image-Classifier206conda create -n ecoclassify python=3.10 -y207conda activate ecoclassify208pip install -r requirements.txt209```210 211(Optional: install PyTorch with CUDA if using GPU). 212 213---214 215## ▶️ Usage 216 217### Run Streamlit App 218 219```bash220streamlit run app.py221```222 223App opens at **http://localhost:8501**. 224 225### CLI Training 226 227```bash228python ecoclassify/pipelines/main.py229```230 231---232 233## 🖥️ Streamlit App 234 235👉 Try EcoClassify directly without setup: [Live Demo on Hugging Face 🚀](https://huggingface.co/spaces/santosh3110/Ecoclassify-Wildlife_Classifier)236 237Tabs available: 238 2391. **About** – Project info, dataset, motivation. 2402. **Inference** – Upload images → classification + Grad-CAM heatmaps. 2413. **Batch Inference** – Upload CSV + ZIP → get predictions CSV. 2424. **Fine-Tuning** – Upload dataset (train/val) → retrain ResNet50 with custom hyperparameters. 243 244---245 246## 📊 Model Training & Evaluation 247 248- Models trained: 249 - **CustomCNN** (100 epochs) 250 - **ResNet50 (transfer learning)** (50 epochs) 251 252- Evaluation scope:253 - Confusion matrix254 - Classification report255 - Calibration metrics (temperature scaling)256 - **Artifacts** stored under artifacts/257 258### Results Summary259 260| Model | Temperature | Uncalibrated Accuracy | Calibrated Accuracy | Uncalibrated Precision | Calibrated Precision | Uncalibrated Recall | Calibrated Recall | Uncalibrated F1 | Calibrated F1 | Uncalibrated Log-Loss | Calibrated Log-Loss |261|:----------|:-----------:|:---------------------:|:-------------------:|:----------------------:|:--------------------:|:--------------------:|:-------------------:|:----------------:|:----------------:|:----------------------:|:----------------------:|262| CustomCNN | 0.66 | 0.70 | 0.70 | 0.70 | 0.70 | 0.70 | 0.70 | 0.69 | 0.69 | 0.89 | 0.83 |263| ResNet50 | 0.82 | 0.89 | 0.89 | 0.89 | 0.89 | 0.89 | 0.89 | 0.89 | 0.89 | 0.41 | 0.39 |264 265### Macro & Weighted Averages266 267| Model | Macro Precision | Macro Recall | Macro F1 | Weighted Precision | Weighted Recall | Weighted F1 |268|:----------|:----------------:|:------------:|:--------:|:------------------:|:---------------:|:-----------:|269| CustomCNN | 0.72 | 0.70 | 0.71 | 0.70 | 0.70 | 0.69 |270| ResNet50 | 0.90 | 0.90 | 0.90 | 0.89 | 0.89 | 0.89 |271 272### Per-class Metrics273 274### CustomCNN275 276| Class | Precision | Recall | F1-score | Support |277|:-----------------:|:---------:|:------:|:--------:|:-------:|278| antelope_duiker | 0.50 | 0.50 | 0.50 | 495.00 |279| bird | 0.75 | 0.69 | 0.72 | 328.00 |280| blank | 0.62 | 0.36 | 0.46 | 443.00 |281| civet_genet | 0.80 | 0.92 | 0.86 | 485.00 |282| hog | 0.92 | 0.79 | 0.85 | 195.00 |283| leopard | 0.91 | 0.87 | 0.89 | 451.00 |284| monkey_prosimian | 0.57 | 0.79 | 0.66 | 498.00 |285| rodent | 0.69 | 0.70 | 0.70 | 403.00 |286 287### ResNet50288 289| Class | Precision | Recall | F1-score | Support |290|:-----------------:|:---------:|:------:|:--------:|:-------:|291| antelope_duiker | 0.81 | 0.81 | 0.81 | 495.00 |292| bird | 0.93 | 0.96 | 0.95 | 328.00 |293| blank | 0.77 | 0.62 | 0.68 | 443.00 |294| civet_genet | 0.94 | 0.97 | 0.96 | 485.00 |295| hog | 0.97 | 0.98 | 0.98 | 195.00 |296| leopard | 0.94 | 0.98 | 0.96 | 451.00 |297| monkey_prosimian | 0.90 | 0.93 | 0.91 | 498.00 |298| rodent | 0.89 | 0.95 | 0.92 | 403.00 |299 300### Training visuals:301- CustomCNN Training Chart: 302- ResNet50 Training Chart: 303 304- Results tracked via 305 306### Confusion matrices:307 308| CustomCNN confusion matrix| ResNet50 confusion matrix |309|---------------------------|---------------------------|310|  | | 311 312---313 314## 🔎 Explainability 315 316- **Grad-CAM** highlights model focus regions. 317- Outputs side-by-side comparison: 318 - Original Image 319 - Heatmap Overlay 320- Sample Grad-CAM heatmaps generated on Val dataset:321 322 323 324 325---326 327## 📦 Batch Inference 328 329- Upload **CSV** (image paths) + **ZIP** (images). 330- Pipeline produces **predictions.csv** with class & confidence. 331 332---333 334## 🛠️ Fine-Tuning 335 336- Upload dataset in structure: 337 338```339dataset.zip340 ├── train/341 │ ├── class1/342 │ ├── class2/343 └── val/344 ├── class1/345 ├── class2/346```347 348- Configure hyperparams (epochs, batch size, LR, early stopping). 349- Retrains ResNet50 on uploaded data. 350- Outputs: new model weights + mapping. 351 352---353 354## 📄 Design Docs 355 356📌 Included in `/docs`: 357 358- **PRD** – Product Requirements & Specs 359- **HLD** – High-Level Architecture Design 360- **LLD** – Low-Level Implementation Design 361 362---363 364## 🧩 Future Work 365 366- 🚀 Deploy as **FastAPI + Docker** microservice. 367- 📱 Extend to **mobile app** for field researchers. 368- 🧪 Add **ensemble models** (ResNet + ViT). 369- 🐾 Multi-label support (detect multiple species in one frame). 370 371---372 373## ❤️ Acknowledgements 374 375- The Pan African Programme: The Cultured Chimpanzee, Wild Chimpanzee Foundation, DrivenData. (2022). Conser-vision Practice Area: Image Classification. Retrieved [July 12 2025] from https://www.drivendata.org/competitions/87/competition-image-classification-wildlife-conservation/. 376- Mentorship: **Sudhanshu Kumar (Euron)** 377- Frameworks: PyTorch, Streamlit, MLflow, TorchCAM 378 379---380 381## 📜 License 382 383Apache 2.0 License © 2025 Santosh Kumar Guntupalli 384 385---386 387✨ *Made with love for Wildlife & AI* 🐆🌱