WORKFLOW.md

Satellite Change Detection — Project Workflow Guide

A complete walkthrough of how this project is structured, how a detection request flows through the system, and how to run it locally. Read this top-to-bottom to get familiar with the codebase.

---

1. What this project does

This is a standalone web application for satellite image change detection. A user uploads two images of the same place taken at different times (a "before" and an "after"), and the app:

1. Aligns the two images (registration).
2. Normalizes their colors/brightness.
3. Runs change detection (classical computer vision + a pretrained deep-learning model).
4. Finds and classifies the changed regions (new buildings, vegetation change, water, etc.).
5. Draws the changes on an overlay image and shows statistics.
6. Saves the run to a per-user history (with login/accounts).

It is deployed as a Docker container on Hugging Face Spaces, but runs the same way locally.

---

2. Tech stack

Layer	Technology
Backend API	FastAPI (Python), served by uvicorn
Image processing	OpenCV, NumPy, scikit-learn
Deep learning	PyTorch + Hugging Face Transformers (AdaptFormer model)
Database	SQLAlchemy ORM over SQLite (default) or PostgreSQL
Auth	JWT tokens (python-jose) + bcrypt password hashing (passlib)
Frontend	Plain HTML + CSS + vanilla JavaScript (single-page app)
Email	HTTP email API or SMTP (optional notifications)
Deployment	Docker → Hugging Face Spaces

There is no build step for the frontend — it's static files served directly.

---

3. Repository structure

change_detection_webapp/
├── app/
│   ├── main.py             # FastAPI app + all HTTP routes (entry point)
│   ├── detection_engine.py # CORE: preprocessing, registration, detection, classification
│   ├── model_inference.py  # AdaptFormer deep-learning model loader + tiled inference
│   ├── cd_models/          # Extra DL building blocks
│   │   ├── change_model.py  #   Siamese U-Net architecture (optional, needs weights)
│   │   └── model_utils.py   #   tiling, multi-scale, confidence-map helpers
│   ├── auth.py             # JWT create/verify, password hashing, current-user lookup
│   ├── database.py         # SQLAlchemy engine/session, DATA_DIR resolution
│   ├── models.py           # ORM models: User, DetectionRun
│   └── notifier.py         # Email notification sending
├── static/
│   ├── css/style.css       # All styles
│   └── js/app.js           # All frontend logic (auth, upload, render results)
├── templates/
│   └── index.html          # Single-page UI shell
├── scripts/
│   └── validate_detection.py  # Sanity checks for the detection pipeline
├── data/                   # Created at runtime: SQLite DB + overlay/thumbnail images
├── requirements.txt        # Python dependencies
├── Dockerfile              # Container build (also pre-downloads the model)
├── README.md               # Short setup notes (Hugging Face front-matter on top)
└── WORKFLOW.md             # This document

Note: the app/cd_models/ folder is named cd_models (not models) on purpose — app/models.py already exists for the database models, and a folder named models would shadow it and break imports.

---

4. High-level architecture

flowchart LR
    browser["Browser (index.html + app.js)"] -->|"HTTP / JSON"| api["FastAPI (main.py)"]
    api --> auth["auth.py (JWT)"]
    api --> engine["detection_engine.py"]
    engine --> model["model_inference.py (AdaptFormer)"]
    api --> db["(SQLite / Postgres via models.py)"]
    api --> notifier["notifier.py (email)"]
    api --> files["data/overlays (result images)"]

• The browser talks only to FastAPI over JSON + multipart form uploads.
• main.py is the only place that defines routes; it delegates the heavy lifting to detection_engine.run_detection(...).
• Results (overlay PNGs, thumbnails) are written to data/overlays/ and referenced by URL.
• Run metadata is stored in the database.

---

5. The detection pipeline (the core workflow)

This is the most important part to understand. Everything happens inside run_detection() in app/detection_engine.py.

flowchart TD
    start["run_detection(before, after, method, sensitivity, ...)"] --> pre["preprocess_image()  -- RGB, resize, denoise"]
    pre --> reg{"registration enabled?"}
    reg -->|yes| align["register_images()  -- SIFT/ORB + ECC align, returns quality metrics"]
    reg -->|no| norm
    align --> norm{"normalization enabled?"}
    norm -->|yes| radio["normalize_radiometry()  -- LAB color match + CLAHE"]
    norm -->|no| method
    radio --> method["pick detection method"]
    method --> ai["AI-Based Deep Learning (default)"]
    method --> diff["Image Difference"]
    method --> feat["Feature-Based (KMeans)"]
    method --> hyb["Hybrid / Hybrid AI"]
    ai --> fuse["AdaptFormer score + classical score -> confidence-gated fusion"]
    diff --> mask
    feat --> mask
    hyb --> fuse
    fuse --> mask["binary change mask"]
    mask --> regions["analyze_change_regions()  -- connected components + classify + NMS"]
    regions --> viz["visualize_changes()  -- draw boxes on overlay"]
    viz --> out["return mask, overlay, stats, regions"]

Step by step

1. Preprocess (preprocess_image): convert to RGB, cap the size (default 1600px max side) for speed, apply light Gaussian blur (and a bilateral filter only when the image is noisy) to reduce sensor noise without destroying edges.

2. Register / align (register_images): the two screenshots rarely line up perfectly.

   • First tries SIFT + FLANN feature matching → homography.
   • Falls back to ORB features if SIFT is weak.
   • Refines with ECC (sub-pixel alignment).
   • Falls back to multi-scale ECC if feature matching fails entirely.
   • Returns an (img1, img2_aligned, registration_ok, reg_meta) tuple. registration_ok and the quality metrics (inlier ratio, NCC) are surfaced to the UI as an alignment warning when the alignment is weak — important for Google Earth screenshots that differ in zoom/crop.

3. Radiometric normalization (normalize_radiometry): match the "after" image's color statistics to the "before" image in LAB space, plus symmetric CLAHE on the lightness channel, so lighting/season differences don't look like real change.

4. Detection method (selected by the method argument):

   • AI-Based Deep Learning (default): runs the AdaptFormer model (model_inference.predict_change_mask) to get a per-pixel change probability map, computes a classical multi-channel score map (color ΔE, SSIM, texture/LBP, edges, change-vector analysis), then fuses them with fuse_dl_and_classical(). Fusion is confidence-gated (not a blind union): the model drives structural changes, the classical signal + Excess-Green index supports vegetation changes.
   • Image Difference: LAB ΔE difference with adaptive (Otsu/MAD) thresholding.
   • Feature-Based: KMeans clustering of per-pixel difference features.
   • Hybrid / Hybrid AI: weighted combinations of the above.

5. Clean the mask (_clean_mask): morphological open/close, hole filling, remove tiny or thin (shadow-like) components.

6. Find & classify regions (analyze_change_regions): connected-components on the mask → bounding boxes → classify_object_type() assigns a label (New Construction/Building, Vegetation Change, Water Body Change, Road/Pavement, Bare Land, etc.) with a confidence and severity → non-maximum suppression removes overlapping/duplicate boxes.

7. Visualize (visualize_changes): draw a subtle tint on changed pixels and numbered, color-coded boxes for the top regions.

8. Return change_mask, result_image, stats, change_regions back to main.py.

Sensitivity

The detection_sensitivity slider (0–1, default 0.5) shifts thresholds: higher = detect more (more recall, more false positives), lower = stricter (fewer, higher-confidence detections).

---

6. The deep-learning model

• File: app/model_inference.py
• Model: deepang/adaptformer-LEVIR-CD (a change-detection transformer trained on the LEVIR-CD building dataset), pulled from the Hugging Face Hub.
• It is pre-downloaded at Docker build time (see the Dockerfile) so cold starts are fast, and preloaded on app startup so the first request isn't slow.
• Inference is tile-based: the image is split into overlapping 256×256 tiles (the model's native size), each tile is predicted, and the results are stitched back with a raised-cosine blend to avoid visible seams.
• If PyTorch/Transformers aren't installed or the model fails to load, the engine falls back gracefully to the classical-only path — the app still works.

app/cd_models/change_model.py contains a from-scratch Siamese U-Net as an alternative DL backbone. It only activates if a trained weights file exists at app/cd_models/weights/siamese_unet_cd.pt (none is shipped), so it's currently dormant.

---

7. Request lifecycle (auth + detect)

sequenceDiagram
    participant U as Browser
    participant A as FastAPI (main.py)
    participant Au as auth.py
    participant E as detection_engine.py
    participant D as Database

    U->>A: POST /api/auth/login {email, password}
    A->>Au: verify_password + create_access_token
    Au-->>A: JWT
    A-->>U: token (also set as httpOnly cookie)

    U->>A: POST /api/detect (before, after, method, ...) + token
    A->>Au: resolve user from token/cookie
    A->>E: run_detection(...)
    E-->>A: mask, overlay, stats, regions
    A->>D: save DetectionRun row
    A->>A: write overlay + thumbnails to data/overlays/
    A-->>U: JSON {statistics, regions, overlayBase64Png, ...}
    U->>U: app.js renders overlay + regions table

---

8. Data model

Defined in app/models.py:

• User: id, email (unique), hashed_password, full_name, created_at
• DetectionRun: id, user_id, title, method, total_pixels, changed_pixels, change_percentage, regions_count, overlay_path, before/after thumbnail paths, zone, village, regions_json (serialized regions), created_at

The database file lives at data/satellite_app.db (SQLite) and is created automatically on first run. Set DATABASE_URL to use PostgreSQL instead.

---

9. API reference

All routes are in app/main.py.

Method & path	Purpose
POST /api/auth/register	Create account {email, password, full_name} → token
POST /api/auth/login	Log in {email, password} → token (+ cookie)
POST /api/auth/logout	Clear auth cookie
POST /api/auth/reset-password	Set a new password {email, new_password}
GET /api/me	Current user (requires auth)
POST /api/detect	Main endpoint. multipart: before, after files + method, title, zone, village, enable_registration, enable_normalization, detection_sensitivity, min_region_area, notify_email
GET /api/history	List the current user's past runs
POST /api/notify/test	Send a test email
GET /api/overlay/<path>	Serve a saved overlay / thumbnail image
GET /health	Lightweight health check (no DB)
GET /	Serves the single-page UI

POST /api/detect returns: statistics (pixels, change %, threshold debug, alignment warning), regions (list with type/confidence/severity/bbox), and the overlay as base64 PNG.

---

10. Frontend

• templates/index.html is the shell: login/register forms, the upload form, history table, and the result modal.
• static/js/app.js handles everything client-side: calling the API, storing the token, submitting the detect form, and rendering results (the before/after slider, the regions table, alignment warnings, and fusion stats).
• static/css/style.css holds all styling.
• Cache-busting: the ?v=NN suffixes on the CSS/JS <link>/<script> tags are bumped when those files change so browsers don't serve stale copies.

---

11. Running locally

Option A — Python virtual environment (recommended for development)

cd change_detection_webapp

# 1. Create and activate a virtual environment
python -m venv venv
# Windows (PowerShell):
venv\Scripts\Activate.ps1
# macOS / Linux:
source venv/bin/activate

# 2. Install dependencies (this pulls CPU PyTorch + Transformers, ~couple GB)
pip install -r requirements.txt

# 3. Run the dev server (auto-reload on code changes)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Open http://localhost:8000, register an account, then upload a before/after pair.

First detection run downloads the AdaptFormer model from Hugging Face (one time). If you don't have PyTorch installed or want a lighter setup, the app still runs using the classical detection path only.

Option B — Docker (mirrors production)

cd change_detection_webapp
docker build -t change-detection .
docker run -p 7860:7860 change-detection

Open http://localhost:7860. The Docker build pre-downloads the model, so the first request is fast.

Validate the pipeline

python scripts/validate_detection.py

This runs registration/fusion/end-to-end sanity checks on synthetic images.

---

12. Configuration (environment variables)

Variable	Default	Purpose
DATABASE_URL	sqlite:///data/satellite_app.db	Use PostgreSQL by setting this
SECRET_KEY	(in auth.py)	JWT signing key — set this in production
HF_HOME	/app/.hf_cache (Docker)	Where the model is cached
EMAIL_API_URL	manager's API	Email backend; empty + SMTP_USER/SMTP_PASS for SMTP
PORT	7860	Port uvicorn binds to in the container
SPACE_ID	(set by HF)	When present, data is written to ~/data

---

13. Deployment (Hugging Face Spaces)

• The Space is a Docker Space. Pushing to its git remote triggers a rebuild.
• Hugging Face builds from the main branch. (This repo's working branch is master, so deploys push master → both master and main on the HF remote.)
• The ARG APP_BUILD=NN line in the Dockerfile is a cache-buster: bumping it forces pip to reinstall and the model to re-download on the next build.
• The YAML front-matter at the top of README.md (title, emoji, sdk: docker, app_port: 7860) is what Hugging Face reads to configure the Space.

---

14. Common tasks & gotchas

• "It's detecting too much / too little" → adjust the sensitivity slider, and make sure the before/after images are the same location, zoom, and crop. Weak alignment shows an alignment warning in the result panel.
• Changed CSS/JS but nothing updates → bump the ?v=NN query string in index.html.
• Adding a DB column → update app/models.py; the app creates tables on startup (there's lightweight migration handling in main.py).
• Don't create a folder named app/models/ → it shadows app/models.py.
• Model not loading → the app logs a warning and continues with classical detection; check the logs for the AdaptFormer load message.

---

15. Where to start reading the code

1. app/main.py — see the routes, especially POST /api/detect.
2. app/detection_engine.py — start at run_detection() at the bottom and follow the calls upward.
3. app/model_inference.py — how the DL model is loaded and run.
4. static/js/app.js — how the frontend calls the API and renders results.

Welcome to the project!