EcoVisionPro - Desktop Application Setup & Run Guide

A step-by-step guide for setting up, running, and building the EcoVisionPro Desktop Application using uv (Fast Python Package & Project Manager).

---

📋 Prerequisites

• Python: v3.10 or higher
• uv: Fast Python Package Manager (uv documentation)
• Git: (For cloning the repository)

---

🚀 Step-by-Step Setup Guide

Step 1: Navigate to the Project Directory

Open your Terminal / Command Prompt / PowerShell and navigate to the project directory:

git clone https://github.com/hyper-lynn/EcoVisionAI
cd EcoVisionPro

---

Step 2: Install uv (If Not Already Installed)

• Windows (PowerShell):

  powershell -executionpolicy bypass -c "irm https://astral.sh/uv/install.ps1 | iex"

• macOS / Linux:

  curl -LsSf https://astral.sh/uv/install.sh | sh

• Via Python pip:

  pip install uv

Verify installation by running uv --version.

---

Step 3: Sync Dependencies & Virtual Environment

Run uv sync. This automatically creates a isolated virtual environment (.venv) and installs all required dependencies defined in pyproject.toml (Flet, OpenCV, Pillow, PySerial, etc.).

uv sync

---

💻 Running the Desktop Application

Using uv run, you do not need to manually activate the virtual environment. Choose one of the following methods to start the desktop app:

Method 1: Via Flet Runner (Recommended with Hot-Reload)

uv run flet run

Tip: Launches the desktop window with live hot-reloading enabled as you edit the source code.

---

Method 2: Direct Python Script Execution

uv run python main.py

Or run directly targeting src/main.py:

uv run python src/main.py

---

Method 3: Test in Web Browser Mode

If you wish to test the UI inside a web browser:

uv run flet run --web

---

🛠️ Useful Commands

1. Adding a New Dependency

uv add <package-name>

2. Running Automated Tests

uv run pytest

---

📦 Building Standalone Desktop Executables (.exe / .app)

To compile and package the app into a standalone Desktop Executable:

• Windows (.exe):

  uv run flet build windows

• macOS (.app / .dmg):

  uv run flet build macos

• Linux:

  uv run flet build linux

---

📁 Project Structure

EcoVisionPro/
├── src/
│   ├── assets/       # Static assets (images, icons)
│   ├── services/     # Hardware & Serial logic
│   ├── views/        # Declarative UI View components
│   ├── state.py      # App State Management
│   └── main.py       # Desktop App Entry point
├── main.py           # Root main launcher
├── pyproject.toml    # Dependencies & tool settings
├── uv.lock           # Locked dependency graph
└── README.md         # Documentation