Add colleague setup guide and env template for Change-Detection-DEV repo.

DEV_SETUP.md covers Python, GDAL/rasterio, library layout, run.py, and troubleshooting; README points to it.

Co-authored-by: Cursor <cursoragent@cursor.com>

.env.example

@@ -0,0 +1,30 @@
+# Copy to .env and uncomment values as needed (optional for local dev).
+# python run.py sets APP_MODE=dda automatically.
+
+# APP_MODE=dda
+# SECRET_KEY=change-me-to-a-long-random-string
+
+# Database (default: SQLite in data/satellite_app.db)
+# DATABASE_URL=sqlite:///./data/satellite_app.db
+
+# Local image library folder (default: library_sources/)
+# LOCAL_LIBRARY_ROOT=C:/path/to/your/images
+
+# GeoTIFF upload limit in MB (default 5120 = 5 GB)
+# MAX_GEOTIFF_MB=5120
+
+# Max pixel dimension for detection (lower = less RAM, default 4096 local)
+# DETECTION_MAX_SIDE=4096
+
+# Public URL for report links in emails (default http://localhost:8000 locally)
+# PUBLIC_BASE_URL=http://localhost:8000
+
+# Email notifications (optional)
+# EMAIL_API_URL=https://emailservice.managemybusinessess.com/api/email/send
+# SMTP_HOST=smtp.gmail.com
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASS=
+
+# Hugging Face model cache directory
+# HF_HOME=./.hf_cache

.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 data/satellite_app.db
 data/overlays/*
 !data/overlays/.gitkeep
+data/library_cache/
 # Local library images (too large for git — keep on disk only)
 library_sources/**/*.tif
 library_sources/**/*.tiff

DEV_SETUP.md

@@ -0,0 +1,212 @@
+# DDA Change Detection — Local Dev Setup
+
+This repo is the **development branch** of the satellite change-detection app (DDA SOW). It runs the full dev UI: image library, GeoTIFF comparison, async jobs, reports, and PDF export.
+
+**Live dev Space (reference):** https://coderuday21-satdetect-dev.hf.space  
+**Production Space (do not deploy this repo there without review):** https://coderuday21-satdetect.hf.space
+
+---
+
+## 1. Prerequisites
+
+| Requirement | Notes |
+|-------------|--------|
+| **Python 3.10 – 3.12** | Tested with **3.11** (same as Docker). 3.13+ may have wheel issues for some packages. |
+| **Git** | Clone this repository. |
+| **~4 GB free disk** | PyTorch (CPU), transformers model cache, and sample GeoTIFFs. |
+| **RAM 8 GB+ recommended** | Detection loads AdaptFormer; large GeoTIFFs use more RAM. |
+
+### Windows (GeoTIFF / rasterio)
+
+`rasterio` needs GDAL. Easiest options:
+
+**Option A — pip wheels (try first):**
+```powershell
+pip install -r requirements.txt
+python -c "import rasterio; print('rasterio OK', rasterio.__version__)"
+```
+
+**Option B — if rasterio fails, use Conda for GDAL then pip for the rest:**
+```powershell
+conda create -n dda-cd python=3.11 -y
+conda activate dda-cd
+conda install -c conda-forge gdal rasterio -y
+pip install -r requirements.txt
+```
+
+**Option C — OSGeo4W:** Install [OSGeo4W](https://trac.osgeo.org/osgeo4w/) and ensure `gdal` is on `PATH` before `pip install rasterio`.
+
+### macOS / Linux
+
+```bash
+# macOS (Homebrew)
+brew install gdal
+
+# Ubuntu/Debian
+sudo apt-get install gdal-bin libgdal-dev
+export GDAL_CONFIG=/usr/bin/gdal-config
+pip install -r requirements.txt
+```
+
+---
+
+## 2. Clone and install
+
+```bash
+git clone https://github.com/Uday-at-Vedang/Change-Detection-DEV.git
+cd Change-Detection-DEV
+python -m venv venv
+```
+
+**Windows:**
+```powershell
+venv\Scripts\activate
+pip install -U pip setuptools wheel
+pip install -r requirements.txt
+```
+
+**macOS / Linux:**
+```bash
+source venv/bin/activate
+pip install -U pip setuptools wheel
+pip install -r requirements.txt
+```
+
+> First `pip install` may take 10–20 minutes (PyTorch + transformers).
+
+---
+
+## 3. Environment variables (optional)
+
+Copy the template and edit if needed:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Default (local) | Purpose |
+|----------|----------------|---------|
+| `APP_MODE` | `dda` (set by `run.py`) | `dda` = full dev UI; `legacy` = simple upload UI |
+| `SECRET_KEY` | random fallback | Set in production |
+| `DATABASE_URL` | SQLite in `data/` | PostgreSQL optional |
+| `LOCAL_LIBRARY_ROOT` | `library_sources/` | Custom image library folder |
+| `MAX_GEOTIFF_MB` | `5120` | Max GeoTIFF upload size (MB) |
+| `DETECTION_MAX_SIDE` | `4096` local / `2048` HF | Max pixel side for detection |
+| `EMAIL_API_URL` | manager API | Email notifications |
+| `SMTP_USER` / `SMTP_PASS` | — | Use SMTP if API URL empty |
+| `PUBLIC_BASE_URL` | `http://localhost:8000` | Report links in emails |
+
+Local dev does **not** require email config unless you test notifications.
+
+---
+
+## 4. Image library (local GeoTIFFs)
+
+Place images under year folders (not committed to git — too large):
+
+```
+library_sources/
+  2024/
+    site_a.tif
+  2025/
+    site_b.tif
+  2026/
+```
+
+See `library_sources/README.md` for details. Supported: `.tif`, `.tiff`, `.png`, `.jpg`.
+
+After adding files, start the app and click **Image Library → Refresh**.
+
+---
+
+## 5. Run the app
+
+```bash
+python run.py
+```
+
+Opens **http://127.0.0.1:8000** with the DDA dev UI (3 tabs: Image Library, Change Detection, Reports).
+
+Alternative (with auto-reload during development):
+
+```bash
+set APP_MODE=dda          # Windows
+export APP_MODE=dda       # macOS/Linux
+uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
+```
+
+### First run
+
+- Creates `data/satellite_app.db` and `data/overlays/`.
+- Downloads **AdaptFormer** model from Hugging Face on first detection (~500 MB). Requires internet.
+- Seed data: Delhi zone/village hierarchy is loaded automatically in DDA mode.
+
+### Health check
+
+```bash
+curl http://127.0.0.1:8000/health
+```
+
+Expected: `"appMode": "dda"`, `"status": "ok"`.
+
+---
+
+## 6. Using the dev UI
+
+1. **Image Library** — scan year folders, upload GeoTIFFs (up to 5 GB), view hierarchy.
+2. **Change Detection** — pick Base (T1) and Comparison (T2), run detection (async jobs on HF; sync locally).
+3. **Reports** — history, PDF download, browser report at `/dda/reports/{id}`.
+4. **Bell icon** — in-app notifications for completed jobs.
+
+---
+
+## 7. Project layout (DDA)
+
+```
+app/
+  main.py              # FastAPI entry
+  detection_engine.py  # Change detection pipeline
+  dda/                 # DDA modules (library, jobs, reports, geo)
+static/js/dda/         # Dev frontend
+templates/index_dda.html
+docs/IMPLEMENTATION_PLAN_DDA.md   # SOW phase plan
+```
+
+---
+
+## 8. Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `ImportError: rasterio` | Install GDAL (see §1), then reinstall rasterio |
+| Simple upload UI instead of DDA tabs | Set `APP_MODE=dda` or use `python run.py` |
+| Library empty | Add `.tif` files under `library_sources/YYYY/` and click Refresh |
+| Detection slow / OOM | Lower `DETECTION_MAX_SIDE=2048` or use smaller images |
+| Model download fails | Check internet; set `HF_HOME` to a writable folder |
+| Port 8000 in use | Change `PORT` in `run.py` or use `--port 8001` with uvicorn |
+
+---
+
+## 9. Deploy to Hugging Face dev Space (maintainers)
+
+See `DEPLOYMENT.md`. Dev Space remote:
+
+```powershell
+git remote add hf-dev https://huggingface.co/spaces/coderuday21/satdetect-dev
+git push hf-dev master:main
+```
+
+Do **not** push `master` to production `satdetect` without explicit sign-off.
+
+---
+
+## 10. Key API endpoints (DDA)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health + app mode |
+| GET | `/api/dda/local/images` | Library image list |
+| POST | `/api/dda/jobs` | Queue async detection |
+| GET | `/api/dda/reports/{id}/pdf` | PDF export |
+| GET | `/dda/reports/{id}` | Browser report page |
+| GET | `/api/history` | Detection run history |

README.md

@@ -1,5 +1,5 @@
 ---
-title: AI Change Detection
+title: DDA Change Detection (Dev)
 emoji: 🛰️
 colorFrom: gray
 colorTo: green
@@ -7,22 +7,54 @@ sdk: docker
 app_port: 7860
 ---
 
+# DDA Change Detection — Development
+
+Satellite / drone **change detection** web app for the DDA Scope of Work. This repository tracks **dev-only** features (`APP_MODE=dda`): image library, GeoTIFF comparison, async jobs, geo-referenced regions, reports, and PDF export.
+
+> **New to the project?** Start with **[DEV_SETUP.md](DEV_SETUP.md)** — step-by-step install and run instructions for your machine.
+
+| Environment | URL |
+|-------------|-----|
+| **Dev Space (HF)** | https://coderuday21-satdetect-dev.hf.space |
+| **Local** | http://127.0.0.1:8000 after `python run.py` |
+
+## Quick start
+
+```bash
+git clone https://github.com/Uday-at-Vedang/Change-Detection-DEV.git
+cd Change-Detection-DEV
+python -m venv venv
+venv\Scripts\activate          # Windows
+# source venv/bin/activate     # macOS/Linux
+pip install -r requirements.txt
+python run.py
+```
+
+1. Add GeoTIFFs to `library_sources/2025/` (or other year folders).
+2. Open **Image Library → Refresh**.
+3. Use **Change Detection** to compare T1 vs T2.
+
+Full details: **[DEV_SETUP.md](DEV_SETUP.md)** · SOW plan: **`docs/IMPLEMENTATION_PLAN_DDA.md`** · HF deploy: **`DEPLOYMENT.md`**
+
+---
+
 # Satellite Change Detection — Standalone Web App
 
 Standalone web application for satellite image change detection with **database storage** and a **clean, modern UI**. Opens directly on the detection page — no sign-in required.
 
 ## Features
 
+- **DDA dev UI** — Library, comparison, jobs, reports, PDF (when `APP_MODE=dda`)
 - **Direct access** — upload and run detection immediately (no login)
 - **Database** — SQLite (or set `DATABASE_URL` for PostgreSQL); stores detection runs
-- **Change detection** — Same model as the original app: AI-based, image difference, feature-based, hybrid
-- **Detection menu** — Choose between General Change Detection and Landslide Detection (Uttarakhand starter)
-- **Pothole detection** — Separate detection type for road damage (starter pipeline + future model hook)
-- **Object classification** — Changed regions labeled as Water, Vegetation/Tree, Building, Road, Bare Ground/Soil
-- **History** — List of past runs with overlay images and stats
-- **UI** — Single-page app with a dark, “control room” style and teal accents
+- **Change detection** — AdaptFormer deep learning + hybrid / difference methods
+- **GeoTIFF library** — Year-folder library, 5 GB upload limit, lat/lng on regions
+- **Object classification** — Changed regions labeled (Water, Vegetation, Building, Road, etc.)
+- **History & reports** — Past runs, PDF export, email notifications
 
-## Setup
+## Setup (legacy summary)
+
+See **[DEV_SETUP.md](DEV_SETUP.md)** for the complete guide. Minimal steps:
 
 1. **Create a virtual environment (recommended)**
 
@@ -41,7 +73,8 @@ Standalone web application for satellite image change detection with **database
 3. **Run the app**
 
    ```bash
-   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+   python run.py
+   # or: uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
    ```
 
 4. Open **http://localhost:8000** in your browser.
@@ -49,55 +82,43 @@ Standalone web application for satellite image change detection with **database
 ## First run
 
 - The SQLite DB and `data/` (overlay images) are created automatically on first use.
-- Upload **Before** and **After** images, choose a method, and click **Run detection**.
-- Results appear below; runs are saved in **History**.
+- **DDA mode:** place images in `library_sources/YYYY/` and use the Library tab.
+- **Legacy mode:** upload Before/After PNGs on the detection page.
+- AdaptFormer model downloads from Hugging Face on first detection (~500 MB).
 
 ## Configuration
 
+- **DDA mode:** `APP_MODE=dda` (default when using `run.py`). Copy `.env.example` → `.env` for optional overrides.
 - **Database**: set `DATABASE_URL` (e.g. `postgresql://user:pass@host/db`) to use another DB; otherwise SQLite under `data/satellite_app.db` is used.
-- **JWT**: set `SECRET_KEY` in `app/auth.py` (or via env) in production.
-- **Email**: By default, notifications are sent via the manager's email API (`https://emailservice.managemybusinessess.com/api/email/send`). Override with `EMAIL_API_URL` if needed. To use SMTP (e.g. Gmail) instead, set `EMAIL_API_URL` to empty and set `SMTP_USER` and `SMTP_PASS`.
-
-- **Landslide module**:
-  - Integrated at runtime through the same `/api/detect` endpoint using `detection_type=landslide_detection`.
-  - Engine code: `app/landslide_engine.py`
-  - Dataset preprocessing starter: `app/landslide_preprocessing.py`
-  - Planning/research brief: `Landslide_Detection_Uttarakhand_Integration_Plan.md`
-
-- **Pothole module**:
-  - Integrated at runtime through the same `/api/detect` endpoint using `detection_type=pothole_detection`.
-  - Engine code: `app/pothole_engine.py`
-  - Planning/research brief: `Pothole_Detection_Integration_Plan.md`
+- **JWT**: set `SECRET_KEY` via env in production.
+- **Email**: `EMAIL_API_URL` or `SMTP_USER` / `SMTP_PASS` — see `.env.example`.
 
 ## Project layout
 
 ```
 change_detection_webapp/
 ├── app/
-│   ├── main.py           # FastAPI app, routes
-│   ├── database.py       # SQLAlchemy, session
-│   ├── models.py         # User, DetectionRun
-│   ├── auth.py           # JWT, password hashing
-│   └── detection_engine.py  # Change detection (no Streamlit)
-├── static/
-│   ├── css/style.css     # Styles
-│   └── js/app.js         # Frontend logic
-├── templates/
-│   └── index.html        # Single-page UI
-├── data/                 # Created at runtime (DB + overlays)
+│   ├── main.py              # FastAPI app, routes
+│   ├── dda/                 # DDA dev modules (library, jobs, reports)
+│   └── detection_engine.py  # Change detection pipeline
+├── static/js/dda/           # DDA frontend
+├── templates/index_dda.html # DDA dev UI
+├── library_sources/         # Local GeoTIFF library (year folders)
+├── docs/IMPLEMENTATION_PLAN_DDA.md
+├── DEV_SETUP.md             # Colleague setup guide
 ├── requirements.txt
-└── README.md
+└── run.py                   # Local launcher (APP_MODE=dda)
 ```
 
-## API (for integration)
+## API (DDA highlights)
 
-- `POST /api/auth/register` — body: `{ "email", "password", "full_name" }`
-- `POST /api/auth/login` — body: `{ "email", "password" }` → returns `access_token`
-- `GET /api/me` — header: `Authorization: Bearer <token>`
-- `POST /api/detect` — form: `before`, `after` (files), `method`, `title`, etc. → returns stats, regions, overlay base64
-- `GET /api/history` — list of current user’s runs
-- `GET /api/overlay/<path>` — serve saved overlay image
-- `GET /health` — lightweight health check (no DB)
+- `GET /health` — app mode and version
+- `GET /api/dda/local/images` — library image list
+- `POST /api/dda/jobs` — queue async detection
+- `GET /api/dda/reports/{id}/pdf` — PDF download
+- `GET /dda/reports/{id}` — browser report page
+- `POST /api/detect` — legacy multipart upload detect
+- `GET /api/history` — detection run history
 
 ## Hugging Face: Space stuck on “Restarting”