docs/USAGE.md

EcoPulse Usage Manual

This guide details how to operate the various components of the EcoPulse platform, from the CLI scripts to the interactive dashboard.

1. Interactive Dashboard

The dashboard is the primary interface for visual analysis and presentations.

streamlit run app.py

Features:

• Single Image Analysis: Upload a satellite image to view greenery coverage and Grad-CAM heatmaps.
• Region Comparison: Upload two images to contrast their environmental metrics side-by-side.
• System Controls: Monitor GPU VRAM usage and clear model cache in real-time.

2. CLI Evaluation

To run a batch evaluation of the pipeline against a labeled dataset (e.g., DeepGlobe):

python scripts/evaluate_segmentation.py

This will output Mean IoU and Dice Score metrics to the console and save result visualizations to outputs/figures/.

3. Region Comparison (CLI)

For rapid comparison of two geographic areas without the GUI:

python scripts/compare_regions.py --image_a data/area1.jpg --image_b data/area2.jpg

Outputs:

• outputs/figures/region_comparison.png: A side-by-side visual report.
• outputs/figures/region_comparison_report.csv: A data report for further analysis.

4. CNN Training

To retrain or fine-tune the land-cover classifier on the EuroSAT dataset:

python scripts/train_classifier.py --config config/config.yaml

• Logs are saved to outputs/logs/ (compatible with TensorBoard).
• The best performing model weights are saved to outputs/models/resnet50_eurosat.pth.

5. Interpretability Analysis

To run the automated interpretability analysis which generates Grad-CAM heatmaps and Pearson correlation statistics:

python scripts/evaluate_interpretability.py

This generates scatter plots and correlation coefficients in outputs/figures/.

6. Training on Google Colab

EcoPulse is fully compatible with Google Colab for cloud training.

Zero-Code-Change Workflow:

1. Clone the Repo:

   !git clone https://github.com/your-username/ecopulse-satellite-analysis.git
   %cd ecopulse-satellite-analysis
   

2. Install Dependencies:

   !pip install -r requirements.txt
   

3. Data Mounting: If your datasets are on Google Drive, mount them and create a symlink so the internal paths remain valid:

   from google.colab import drive
   drive.mount('/content/drive')
   !ln -s /content/drive/MyDrive/EcoPulseData/data data
   

4. Execute Training:

   !python scripts/train_classifier.py --config config/config.yaml
   

Because all paths in config/config.yaml are relative to the project root, the code will execute perfectly in the Colab environment without modification.