File size: 5,329 Bytes
43abac3 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 | # 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.
|