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.

```bash
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):

```bash
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:

```bash
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:

```bash
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:

```bash
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:**
    ```python
    !git clone https://github.com/your-username/ecopulse-satellite-analysis.git
    %cd ecopulse-satellite-analysis
    ```
2.  **Install Dependencies:**
    ```python
    !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:
    ```python
    from google.colab import drive
    drive.mount('/content/drive')
    !ln -s /content/drive/MyDrive/EcoPulseData/data data
    ```
4.  **Execute Training:**
    ```python
    !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.