docs/ARCHITECTURE.md

# EcoPulse System Architecture

This document provides a technical deep-dive into the EcoPulse pipeline, explaining the interaction between the foundation models and the classification head.

## Design Philosophy
EcoPulse is built on the principle of **Modular Decoupling**. By separating the *segmentation* of objects from the *classification* of those objects, we can swap out individual models (e.g., upgrading from ResNet to EfficientNet) without re-engineering the entire pipeline.

## The Three-Phase Pipeline

### Phase 1: Classification (Feature Extraction)
The core classifier is a **ResNet-50** architecture. 
- **Dataset:** EuroSAT (13 spectral bands, though EcoPulse uses the RGB version for broader compatibility).
- **Optimization:** Trained using Adam optimizer with Automatic Mixed Precision (AMP) to leverage NVIDIA Tensor Cores.
- **Responsibility:** Accepts a 64x64 patch and outputs a probability distribution across 10 land-cover classes.

### Phase 2: Segmentation & Quantification (Orchestration)
The orchestration layer, found in `src/greenery_estimator.py`, manages the data flow:
1. **Instance Segmentation:** Meta's **Segment Anything Model (SAM)** processes the high-resolution input image. It generates a collection of boolean masks representing distinct environmental features.
2. **Dynamic Cropping:** For each mask, the system calculates a bounding box and extracts the corresponding pixels from the original image.
3. **Classification:** Each cropped patch is fed into the ResNet-50 classifier.
4. **Weighted Aggregation:** If a mask is classified as a "greenery" category (Forest, Pasture, Herbaceous Vegetation, or Permanent Crop), its total pixel count is added to the regional tally.

### Phase 3: Interpretability (Explainable AI)
To prevent "black-box" decisions, EcoPulse implements **Grad-CAM (Gradient-weighted Class Activation Mapping)**:
- **Hooks:** The system registers forward and backward hooks on the `layer4` convolutional block of the ResNet-50 model.
- **Activation Maps:** During inference, the system captures the gradients of the target class score flowing into the feature maps.
- **Heatmaps:** A weighted combination of these feature maps produces a heatmap, highlighting the textural patterns (like canopy density or leaf structure) that led to the classification.

## Data Schema
Results are aggregated into a standardized dictionary format:
```python
{
    'greenery_percentage': float,
    'green_pixels': int,
    'total_pixels': int,
    'mask_classifications': [
        {
            'mask_id': int,
            'class': str,
            'is_green': bool,
            'pixels': int,
            'bbox': list,
            'segmentation': np.ndarray
        },
        ...
    ]
}
```

## Performance Considerations
- **Memory Management:** SAM is a memory-intensive model (~2.5GB VRAM). The Streamlit GUI uses `@st.cache_resource` to prevent redundant memory allocation.
- **Processing Time:** Segmentation is the bottleneck. The system uses a centralized `config.yaml` to allow users to adjust segmentation granularity to balance speed and precision.