docs/INSTALLATION.md

# Installation Guide

EcoPulse requires **Python 3.12+**. To ensure a smooth installation and avoid version conflicts, we recommend using [uv](https://github.com/astral-sh/uv), a high-performance Python package and project manager.

## Option 1: Using `uv` (Recommended)

`uv` will automatically handle the Python version specified in `.python-version` and manage the virtual environment for you.

1.  **Install `uv`** (if not already installed):
    ```bash
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
    *(On Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`)

2.  **Initialize the Environment:**
    Navigate to the project root and run:
    ```bash
    uv sync
    ```
    This command will create a `.venv`, install the correct Python version (3.12), and install all dependencies from `pyproject.toml`.

3.  **Activate & Run:**
    ```bash
    uv run streamlit run app.py
    ```

## Option 2: Using standard `pip`

If you prefer using standard `pip`, ensure you are on Python 3.12+.

1.  **Create a Virtual Environment:**
    ```bash
    python -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
    ```

2.  **Install Dependencies:**
    ```bash
    pip install -r requirements.txt
    ```

## Post-Installation Check
To verify the installation, run the integrated syntax check:
```bash
python -m compileall src scripts app.py
```
If no errors are returned, the system is ready for use.

---

## Collaborator Onboarding
If you are joining the project as a developer, please follow these additional steps:

### 1. Dataset Acquisition
The `data/` directory is ignored by Git due to its size. To run the full evaluation or training pipelines, you must:
- Download the **EuroSAT (RGB)** dataset and place it in `data/EuroSAT`.
- Download the **DeepGlobe Land Cover** dataset and place it in `data/DeepGlobe`.
- *(Note: The Streamlit app will work for one-off image uploads even without these full datasets).*

### 2. Model Weights
- The **SAM ViT-H checkpoint** (2.5GB) will be automatically downloaded to `outputs/models/` the first time you run the pipeline. Ensure you have a stable internet connection for the initial run.
- The **ResNet-50 weights** should be provided by the project lead or trained locally using `scripts/train_classifier.py`.

### 3. Hardware Requirements
EcoPulse is optimized for **NVIDIA GPUs (CUDA)**.
- **VRAM:** At least 8GB of VRAM is recommended for SAM ViT-H.
- **CPU Fallback:** If no GPU is detected, the system will fall back to CPU, but processing times for segmentation will increase significantly (from ~5s to ~60s+ per image).

---

## Low-Power & Linux (Manjaro) Optimization
If you are presenting on a laptop with limited hardware or running a Linux distribution like **Manjaro KDE**, please note the following:

### 1. Scaling for Performance
If the laptop lacks a dedicated GPU or has limited VRAM, you can switch to a lighter version of the Segment Anything Model.
- **Action:** In `config/config.yaml`, change `sam_model_type` from `vit_h` (Huge) to `vit_b` (Base) and update the `sam_checkpoint` path accordingly.
- **Benefit:** This significantly reduces VRAM usage and speeds up inference on weaker hardware.

### 2. Linux-Specific Dependencies (OpenCV)
On some Linux distributions (like Manjaro/Arch), OpenCV may require additional system libraries for GUI rendering. If you encounter an error related to `libGL.so`, run:
```bash
sudo pacman -S libglvnd
```

### 3. Pathing & Permissions
- EcoPulse uses `os.path.join` throughout the codebase, ensuring it works seamlessly across Windows (`\`) and Linux (`/`).
- Ensure the user running the app has read/write permissions for the `data/temp/` and `outputs/` directories.

### 4. Presentation Tip
Since loading the models (2.5GB+) can take time on a laptop, launch the Streamlit app **before** the presentation begins. This ensures the models are pre-cached in memory and ready for an instant demo.


---

## Troubleshooting

### Windows Issues
1. **Microsoft Visual C++ Build Tools:**
   Some dependencies (like `opencv-python` or `segment-anything`) may require C++ Build Tools during installation. If you see a "C++ Build Tools" error:
   - Download the [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/).
   - Select "Desktop development with C++" during installation.
2. **Path Length Limits:**
   If you encounter errors related to long file paths, enable long paths in Windows:
   - Run PowerShell as Admin: `New-ItemProperty -Path "HKLM:\System\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force`

### Linux (Manjaro/Arch) Issues
1. **Missing libGL:**
   If `import cv2` fails with a `libGL.so.1` error:
   - Run: `sudo pacman -S libglvnd`
2. **VRAM Issues with SAM:**
   If you get an `Out of Memory (OOM)` error:
   - Change `sam_model_type` to `vit_b` in `config/config.yaml`.
   - Clear your cache in the Streamlit "System Controls" sidebar.

### General Issues
- **Python Version Mismatch:**
  Ensure `python --version` returns 3.12.x. If using `uv`, this is handled automatically.
- **Git Link Failures:**
  The `segment-anything` dependency is installed directly from GitHub. Ensure `git` is installed and accessible in your terminal.