README.md

metadata

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 (Highly Recommended)

Installation

For comprehensive details, please refer to the Installation Guide.

Quick start with uv:

uv sync
uv run streamlit run app.py

---

💻 Usage

Interactive Dashboard (Recommended)

Launch the Streamlit GUI to perform real-time analysis and region comparisons:

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.