README.md

metadata

title: Forest Fire Detection FirenetCNN
emoji: 🔥
colorFrom: red
colorTo: pink
sdk: gradio
app_file: app.py
pinned: false
license: mit
python_version: '3.12'
short_description: Forest fire and smoke detection with CNN + Grad-CAM

Forest Fire Detection Using FirenetCNN and XAI Techniques

This project implements a Convolutional Neural Network (CNN) to detect and classify forest fires from images and videos. The model leverages transfer learning with the MobileNetV2 architecture and is trained to distinguish between three classes: 'fire', 'smoke', and 'no_fire'.

To enhance model interpretability and trustworthiness, the project incorporates Explainable AI (XAI) using Grad-CAM (Gradient-weighted Class Activation Mapping). This technique generates heatmaps that visualize the specific regions in an image the model focuses on to make its predictions.

Key Features

• Multi-Class Classification: Classifies input into 'fire', 'smoke', or 'no_fire' categories.
• Transfer Learning: Utilizes a pre-trained MobileNetV2 model, fine-tuned for the specific task of fire detection.
• Data Augmentation: Employs various image augmentation techniques (rotation, shifting, shearing, zooming, and flipping).
• Versatile Prediction: Capable of performing predictions on static images, pre-recorded videos, and live webcam feeds.
• Explainable AI (XAI): Implements Grad-CAM to produce heatmaps, providing visual insight into the model's decisions.
• Web Interface: Gradio-based web application for easy deployment and demo.
• Docker Support: Containerized deployment for production use.

Model Performance

The model was evaluated on a test set of 405 images, achieving an overall accuracy of 82%.

              precision    recall  f1-score   support

        fire       0.92      0.81      0.86       121
     no_fire       0.76      0.98      0.86       146
        smoke       0.84      0.67      0.75       138

    accuracy                           0.82       405
   macro avg       0.84      0.82      0.82       405
weighted avg       0.83      0.82      0.82       405

Project Structure

├── src/                    # Python package (core functionality)
│   ├── __init__.py         # Package exports
│   ├── model.py            # Model definition and utilities
│   ├── gradcam.py          # Grad-CAM implementation
│   ├── inference.py        # Unified inference engine
│   └── training.py         # Training pipeline
├── models/                 # Trained model files
│   ├── FirenetCNN1.h5      # Primary trained model
│   ├── FirenetCNN.h5       # Alternative model version
│   └── firenet_model.h5    # Base model
├── app.py                  # Gradio web application
├── config.py               # Project configuration
├── Dockerfile              # Docker build file
├── docker-compose.yml      # Docker Compose configuration
├── pyproject.toml          # Python package configuration
├── requirements.txt        # Dependencies
└── Fire_PredCopy.ipynb     # Original training notebook (reference)

Installation & Setup

Prerequisites

• Python 3.10+
• uv (recommended) or pip
• A webcam for live detection (optional)

Option 1: Using uv (Recommended)

# Clone the repository
git clone https://github.com/OpelSpeedster/Forest-Fire-Detection-Using-FirenetCNN-and-XAI-Techniques.git
cd Forest-Fire-Detection-Using-FirenetCNN-and-XAI-Techniques

# Install dependencies
uv pip install -r requirements.txt

# Run the application
uv run python app.py

Option 2: Using pip

# Clone and install
git clone https://github.com/OpelSpeedster/Forest-Fire-Detection-Using-FirenetCNN-and-XAI-Techniques.git
cd Forest-Fire-Detection-Using-FirenetCNN-and-XAI-Techniques

pip install -r requirements.txt
python app.py

Option 3: Docker

# Build and run with Docker Compose
docker compose up --build

# Or build manually
docker build -t fire-detection .
docker run -p 7860:7860 -v ./models:/app/models fire-detection

Download the Dataset

This project uses the Forest Fire Classifier Dataset. Download and structure as:

data/
└── forestfire-classifier-dataset/
    ├── train/
    │   ├── fire/
    │   ├── nofire/
    │   └── smoke/
    ├── val/
    │   ├── fire/
    │   ├── nofire/
    │   └── smoke/
    └── test/
        ├── fire/
        ├── nofire/
        └── smoke/

Note: The dataset folder is named nofire (without underscore), which matches the trained model's class ordering.

Usage

Web Interface

uv run python app.py

This launches a Gradio web interface at http://localhost:7860 with:

1. 📷 Image Classification - Upload images for fire/smoke/no_fire detection with Grad-CAM visualization
2. 🎥 Video Analysis - Upload videos for frame-by-frame analysis with class distribution statistics
3. 📹 Webcam Inference - Live webcam detection (via Python API)
4. 📊 Model Information - Architecture details and performance metrics

Python API

from src.inference import FireNetInference

# Initialize inference engine
engine = FireNetInference("models/FirenetCNN1.h5")

# Predict on a single image
result = engine.predict_image("path/to/image.jpg")
print(f"Prediction: {result['label']} ({result['confidence']*100:.2f}%)")

# Process a video
stats = engine.predict_video("path/to/video.mp4", output_path="output.mp4")
print(f"Processed {stats['processed_frames']} frames")

# Grad-CAM demo for all classes
demo = engine.create_gradcam_demo_image("path/to/image.jpg")

Training

# Train a new model
uv run python -m src.training \
    --train-dir data/forestfire-classifier-dataset/train \
    --val-dir data/forestfire-classifier-dataset/val \
    --model-path models/FirenetCNN.keras \
    --epochs 100

# With fine-tuning
uv run python -m src.training \
    --train-dir data/forestfire-classifier-dataset/train \
    --val-dir data/forestfire-classifier-dataset/val \
    --epochs 50 --fine-tune --fine-tune-epochs 20

Evaluation

from src.inference import FireNetInference

results = FireNetInference.evaluate_model_on_dataset(
    "models/FirenetCNN1.h5",
    "data/forestfire-classifier-dataset/test",
    output_report="evaluation_report.txt"
)

print(f"Accuracy: {results['accuracy']:.2f}")
print(f"F1 Score: {results['weighted_avg_f1']:.2f}")

Deploying to Hugging Face Spaces (ZeroGPU)

This app is preconfigured to deploy as a Gradio Space with ZeroGPU hardware.

1. Create a new Space at https://huggingface.co/new-space with SDK: Gradio.
2. Upload only the files the Space needs (skip large media/notebooks/office docs):

   pip install -U "huggingface_hub[cli]"
   huggingface-cli login
   huggingface-cli upload <your-username>/<space-name> . --repo-type=space \
     --include "app.py" "config.py" "requirements.txt" "packages.txt" "README.md" \
     --include "src/**" "models/FirenetCNN1.h5"
   

3. In the Space's Settings tab, set Hardware to ZeroGPU.
4. The app loads models/FirenetCNN1.h5 by default (override with the MODEL_PATH variable/secret in Space Settings if you rename it).

Note on TensorFlow + ZeroGPU: Hugging Face's ZeroGPU is officially validated for PyTorch workloads. This app still requests a ZeroGPU slot per prediction via @spaces.GPU, and TensorFlow will use the GPU automatically if it's visible inside that worker process; if not, TensorFlow transparently falls back to CPU (no crash), so the Space stays fully functional either way.

Model Files

File	Format	Size	Description
FirenetCNN1.h5	HDF5	~24 MB	Primary trained model
FirenetCNN.h5	HDF5	~24 MB	Alternative version
firenet_model.h5	HDF5	~2 MB	Base model

The inference engine tries .keras format first, then falls back to .h5.

Class Labels

Index	Label	Description
0	fire	Active fire detected
1	no_fire	No fire detected
2	smoke	Smoke detected

Key Technical Details

• Architecture: MobileNetV2 + custom classifier head (GlobalAveragePooling2D → Dense(1024) → Dropout(0.5) → Dense(3))
• Input Size: 224x224x3
• Grad-CAM Layer: out_relu (last convolutional layer of MobileNetV2)
• Preprocessing: Rescaling to [0, 1], no mean subtraction

License

This project is licensed under the MIT License. See the LICENSE file for details.

Credit

The original model was trained by Vishal S V. This version provides a modern, deployable interface for the FirenetCNN model with Gradio web app, Docker support, and comprehensive Python API.