---
title: EcoPulse
emoji: 🌿
colorFrom: green
colorTo: green
sdk: streamlit
sdk_version: "1.28.0"
python_version: "3.12"
app_file: app.py
pinned: false
---

# EcoPulse: Advanced Satellite Vegetation Analysis

> **EcoPulse** is a high-performance deep learning pipeline designed for the automated detection, segmentation, and quantification of vegetation in satellite imagery. 

By integrating Meta's **Segment Anything Model (SAM)** with custom-trained convolutional neural networks (CNNs), EcoPulse provides a scalable, instance-aware alternative to traditional multispectral vegetation indices.

---

## 🌟 Core Capabilities

| Capability | Description |
| :--- | :--- |
| **Instance-Aware Segmentation** | Utilizes SAM (ViT-B) for zero-shot segmentation of satellite imagery, identifying distinct land-cover objects with pixel-level precision instead of relying on raw spectral ratios. |
| **Multi-Class Classification** | A fine-tuned ResNet-50 classifier (trained on EuroSAT) categorizes segmented masks into 10 distinct land-cover classes, differentiating between natural forests, pasture land, and urban greenery. |
| **Quantitative Auditing** | Aggregates classification results to compute the exact Greenery Coverage Percentage of a given region—essential for urban planning and environmental compliance. |
| **Explainable AI (XAI)** | Features Grad-CAM visualization for class activation heatmaps and supports side-by-side region comparison to contrast environmental health metrics transparently. |

---

## 📊 Technical Results

The pipeline has been rigorously validated against industry-standard datasets, demonstrating robust morphological feature extraction:

| Metric / Analysis | Result | Context |
| :--- | :--- | :--- |
| **mIoU** | `0.3356` | Segmentation performance on DeepGlobe Land Cover dataset. |
| **Dice Coefficient** | `0.5020` | Segmentation performance on DeepGlobe Land Cover dataset. |
| **Vegetation Correlation**| `Pearson = -0.9094` | Strong negative correlation with NGRDI, validating learned morphological features against traditional spectral indices. |

---

## 🚀 Getting Started

### Prerequisites
- **Python:** 3.12+ (managed automatically via `uv`)
- **Hardware:** NVIDIA GPU with CUDA support (Recommended)
- **Tooling:** [uv](https://github.com/astral-sh/uv) (Highly Recommended)

### Installation
For comprehensive details, please refer to the [Installation Guide](docs/INSTALLATION.md).

**Quick start with `uv`:**
```bash
uv sync
uv run streamlit run app.py
```

---

## 💻 Usage

### Interactive Dashboard (Recommended)
Launch the Streamlit GUI to perform real-time analysis and region comparisons:
```bash
streamlit run app.py
```

### Command Line Interface
Execute various components of the pipeline directly from the terminal:

| Action | Command |
| :--- | :--- |
| **Evaluation Pipeline** | `python scripts/evaluate_segmentation.py` |
| **Interpretability Analysis** | `python scripts/evaluate_interpretability.py` |
| **Region Comparison** | `python scripts/compare_regions.py --image_a path/to/area1.jpg --image_b path/to/area2.jpg` |

---

## 📂 Project Structure

| Directory / File | Description |
| :--- | :--- |
| `src/` | Core logic (CNN models, SAM utilities, greenery estimation). |
| `scripts/` | Production scripts for training, evaluation, and comparison. |
| `app.py` | Interactive Streamlit dashboard entry point. |
| `config/` | Centralized configuration management. |
| `docs/` | Technical documentation and architecture deep-dives. |

---

## 📄 License
This project is licensed under the MIT License. See `LICENSE` for details.