docs/INSTALLATION.md

Installation Guide

EcoPulse requires Python 3.12+. To ensure a smooth installation and avoid version conflicts, we recommend using 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):

   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:

   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:

   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:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

2. Install Dependencies:

   pip install -r requirements.txt
   

Post-Installation Check

To verify the installation, run the integrated syntax check:

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:

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.
   • 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.