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:

{
    '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.