README.md

metadata

title: EleFind - Aerial Elephant Detection
emoji: 🐘
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.8.0
app_file: app.py
python_version: '3.10'
suggested_hardware: cpu-basic
license: mit
tags:
  - object-detection
  - yolo
  - yolov11
  - sahi
  - computer-vision
  - elephant-detection
  - wildlife-conservation
  - aerial-imagery
pinned: false

EleFind — Aerial Elephant Detection

A web application for detecting elephants in aerial and drone imagery using YOLOv11 with SAHI (Slicing Aided Hyper Inference).

Features

• Real-time elephant detection with bounding boxes and confidence scores
• Adjustable SAHI parameters (confidence, slice size, overlap, IoU)
• True Grad-CAM explanations from YOLO's high-resolution detection features
• Automatic CUDA and Apple MPS GPU detection
• Explicit CPU/GPU processing selection with a live availability refresh
• Responsive single-screen desktop workspace with viewport-height results
• Confidence bar charts and per-detection data tables
• Automatic model download from HuggingFace Hub

Quick Setup

Requirements: Python 3.10, Git

git clone https://github.com/iamhelitha/EleFind-gradio-ui.git
cd EleFind-gradio-ui
pip install -r requirements.txt
python app.py

Open http://127.0.0.1:7860 in your browser. The model downloads automatically on first run.

Processing Device

EleFind lists every accelerator that the installed PyTorch build can use:

• NVIDIA GPUs appear as cuda:0, cuda:1, and so on.
• Apple Silicon GPUs appear as mps.
• CPU is always available and can be selected even when a GPU is present.

The recommended available accelerator is selected initially. Use Refresh GPU availability after changing drivers or the runtime. Models are loaded lazily and cached separately for each selected device. A CPU-only Hugging Face Space will only show CPU; selecting a GPU in the UI cannot add GPU hardware to the host.

Grad-CAM

Enable Generate Grad-CAM to create a detection-targeted gradient-weighted activation map in the Grad-CAM tab. Each SAHI detection is explained from a high-resolution local crop so small elephants are not lost by whole-image downscaling. The Grad-CAM view uses dark grayscale context with color only on gradient activations, making it clearly different from the labeled detection image. It is not a probability or segmentation mask and adds an extra forward/backward pass per detection.

Detection and Grad-CAM outputs have in-page zoom controls from 50% to 800%, a reset action, scrollable panning while zoomed, and an Open image in browser action. Gradio's fullscreen button is disabled for these outputs.

Testing

pytest test_detection.py -v
pytest test_detection.py -v -m "not slow"   # skip inference tests

Environment Variables

Variable	Description	Default
HF_MODEL_REPO	HuggingFace model repository	iamhelitha/EleFind-yolo11-elephant
HF_MODEL_FILE	Model filename in the repository	best.pt

Model

Property	Value
Architecture	YOLOv11 (Ultralytics)
Training data	Sliced aerial elephant imagery (1024 x 1024 patches)
Inference	SAHI with NMS post-processing
Precision	53.2 %
Recall	49.1 %
F1-Score	51.0 %
mAP@0.5	84.3 %

SAHI Configuration

Parameter	Value
Slice size	1024 x 1024
Overlap ratio	0.30
Confidence threshold	0.30
IoU threshold	0.40

Training Results

Training curves — loss convergence and metric progression over 100 epochs:

Normalized confusion matrix and Precision-Recall curve (mAP@0.5 = 0.843):

  

Sample validation predictions — detections on held-out aerial tiles:

Project Structure

EleFind-gradio-ui/
├── app.py               # Gradio web application (HF Spaces entry point)
├── test_detection.py    # Pytest test suite
├── requirements.txt     # Python dependencies
├── packages.txt         # System-level dependencies (HF Spaces)
├── pytest.ini           # Pytest configuration
├── MODEL_CARD.md        # Model card
├── examples/            # Sample aerial images for the demo
└── assets/              # Training visualizations for documentation

Tech Stack

• Ultralytics YOLOv11 — object detection
• SAHI — slicing aided hyper inference for high-resolution images
• Gradio — web UI framework
• HuggingFace Hub — model hosting and Spaces deployment

Citation

If you use EleFind in your work, please cite:

@software{guruge2025elefind,
  title     = {EleFind: Aerial Elephant Detection using YOLOv11 and SAHI},
  author    = {Guruge, Helitha},
  year      = {2025},
  url       = {https://github.com/iamhelitha/EleFind-gradio-ui}
}

Acknowledgments

This project is built on the following works:

@dataset{naude2019aerial,
  title     = {The Aerial Elephant Dataset},
  author    = {Naud\'{e}, Johannes J. and Joubert, Deon},
  year      = {2019},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.3234780},
  url       = {https://zenodo.org/records/3234780}
}

@software{jocher2023ultralytics,
  title     = {Ultralytics YOLO},
  author    = {Jocher, Glenn and Qiu, Jing and Chaurasia, Ayush},
  year      = {2023},
  version   = {8.0.0},
  url       = {https://github.com/ultralytics/ultralytics},
  license   = {AGPL-3.0}
}

@article{akyon2022sahi,
  title     = {Slicing Aided Hyper Inference and Fine-tuning for Small Object Detection},
  author    = {Akyon, Fatih Cagatay and Altinuc, Sinan Onur and Temizel, Alptekin},
  journal   = {2022 IEEE International Conference on Image Processing (ICIP)},
  doi       = {10.1109/ICIP46576.2022.9897990},
  pages     = {966--970},
  year      = {2022}
}

@article{abid2019gradio,
  title     = {Gradio: Hassle-Free Sharing and Testing of ML Models in the Wild},
  author    = {Abid, Abubakar and Abdalla, Ali and Abid, Ali and Khan, Dawood and Alfozan, Abdulrahman and Zou, James},
  journal   = {arXiv preprint arXiv:1906.02569},
  year      = {2019}
}

Author

Helitha Guruge — Undergraduate Research Project

License

MIT