Update README.md

README.md

@@ -1,15 +1,250 @@
 ---
-title: FirenetCNN
-emoji: 💬
-colorFrom: yellow
-colorTo: purple
+title: Forest Fire Detection FirenetCNN
+emoji: 🔥
+colorFrom: red
+colorTo: pink
 sdk: gradio
-sdk_version: 6.5.1
 app_file: app.py
 pinned: false
-hf_oauth: true
-hf_oauth_scopes:
-- inference-api
+license: mit
+python_version: "3.12"
+short_description: Forest fire and smoke detection with CNN + Grad-CAM
 ---
 
-An example chatbot using [Gradio](https://gradio.app), [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/v0.22.2/en/index), and the [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index).
+# Forest Fire Detection Using FirenetCNN and XAI Techniques
+
+[![Ask DeepWiki](https://devin.ai/assets/askdeepwiki.png)](https://deepwiki.com/OpelSpeedster/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](https://docs.astral.sh/uv/) (recommended) or pip
+- A webcam for live detection (optional)
+
+### Option 1: Using uv (Recommended)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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](https://www.kaggle.com/datasets/google-brain/forest-fire-detection-from-satellite-images). 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
+
+```bash
+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
+
+```python
+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
+
+```bash
+# 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
+
+```python
+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](https://huggingface.co/docs/hub/spaces-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):
+   ```bash
+   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](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.