Deploy satdetect-dev with Priyanka audit/exception logs.

Orphan snapshot for Hugging Face 10 MiB limit. Includes dashboard, RBAC, and library load optimizations for online testing.

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

.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "change-detection-dev",
+      "runtimeExecutable": "venv/Scripts/python.exe",
+      "runtimeArgs": ["run.py"],
+      "port": 8000
+    }
+  ]
+}

.dockerignore

@@ -0,0 +1,8 @@
+__pycache__
+*.pyc
+.git
+.gitignore
+data/satellite_app.db
+data/overlays/*
+*.md
+.env

.env.example

@@ -0,0 +1,159 @@
+# Copy to .env and uncomment values as needed (optional for local dev).
+# python run.py sets APP_MODE=dda automatically.
+
+# APP_MODE=dda
+# REQUIRED for stable login sessions (including in production): without this,
+# a random secret is generated per process start, invalidating every existing
+# session/cookie on each restart. Generate one with:
+#   python -c "import secrets; print(secrets.token_hex(32))"
+# SECRET_KEY=change-me-to-a-long-random-string
+
+# Database (default: SQLite in data/satellite_app.db)
+# DATABASE_URL=sqlite:///./data/satellite_app.db
+#
+# MySQL (production for this project): install the driver first
+# (pip install pymysql, already in requirements.txt), then set:
+# DATABASE_URL=mysql+pymysql://user:password@host:3306/dbname
+# URL-encode special characters in the password (e.g. @ -> %40).
+#
+# PostgreSQL also supported:
+# DATABASE_URL=postgresql://user:pass@host/db
+
+# Local image library folder (default: library_sources/)
+# LOCAL_LIBRARY_ROOT=C:/path/to/your/images
+
+# Image upload limit in MB (default 15360 = 15 GB)
+# MAX_GEOTIFF_MB=15360
+# MAX_IMAGE_MB=15360
+
+# Automatic mode: identified same-area pairs can be queued on a cadence.
+# The queue does NOT start when the app launches. On the Automatic tab, set
+# interval (days) and run-at time (IST), then click Start. Manual mode is
+# still click-to-run only. The local server must stay running while the
+# schedule is armed. Set AUTO_DETECT_ENABLED=0 to hide/disable the feature.
+# AUTO_DETECT_ENABLED=1
+# AUTO_DETECT_INTERVAL_DAYS=10
+# AUTO_DETECT_RUN_AT=02:00
+
+# Max pixel dimension for detection (lower = less RAM, default 4096 local)
+# DETECTION_MAX_SIDE=4096
+
+# --- Accuracy controls (all optional; defaults preserve current behavior) ---
+# Inference mode: downscaled | fullres_tiled | auto
+# auto = fullres_tiled when before/after paths are GeoTIFF (RCA Critical #1)
+# DETECTION_INFERENCE_MODE=auto
+# Full-res cap (px) in fullres_tiled mode; 0 = native resolution
+# DETECTION_FULLRES_MAX_SIDE=8192
+# Native side (px) above which GeoTIFFs stream from disk windows (avoids OOM)
+# Default lowered 8192→4096 (RCA Significant #5)
+# DETECTION_WINDOWED_THRESHOLD=4096
+# Soft RAM budget (MB) per in-memory array before switching to windowed streaming
+# DETECTION_TILE_MEMORY_MB=1536
+# Tile size / overlap for full-res scoring (overlap default 0.35 — RCA #6 seams)
+# DETECTION_TILE_SIZE=512
+# DETECTION_TILE_OVERLAP=0.35
+# Skip SIFT registration on GPS-aligned GeoTIFF pairs: true|false|auto (RCA #4)
+# DETECTION_SKIP_REGISTRATION_GEOTIFF=auto
+# Local Delhi fine-tuned AdaptFormer (v3 frozen = Test F1 0.581 @ thr 0.2).
+# Relative paths are resolved against the repo root (not the process CWD).
+# ADAPTFORMER_WEIGHTS=models/adaptformer_delhi/v3_frozen
+# Val-calibrated DL threshold (alias: DETECTION_DL_THRESHOLD). v3 = 0.2
+# ADAPTFORMER_THRESHOLD=0.2
+# DETECTION_DL_THRESHOLD=0.2
+# Multi-scale DL fusion: off or a comma list, e.g. 0.5,1.0,1.5
+# DETECTION_MULTISCALE=off
+# Fusion strategy: smart_union | hysteresis | dl_only
+# v3 ablation (runs/v3_app_ablation): dl_only @ 0.2 ≈ Test F1 0.58;
+# smart_union/hysteresis collapsed F1 to ~0.04 — prefer dl_only with v3.
+# DETECTION_FUSION=dl_only
+# TTA: off | hflip | full | auto. Ablation: hflip ≈ same F1, ~2x slower on CPU.
+# DETECTION_TTA=off
+# Preprocessing toggles
+# DETECTION_CLAHE=true
+# DETECTION_HIST_MATCH=false
+# DETECTION_SKIP_PREBLUR=         # auto: on in fullres_tiled mode
+# Border pixels zeroed in mask cleanup (auto: 4 fullres / 12 downscaled)
+# DETECTION_BORDER_MARGIN=
+# Tiles per GPU forward pass (1 = no batching)
+# DETECTION_TILE_BATCH=1
+# Save a downsampled probability-map PNG per run for debugging
+# DETECTION_SAVE_PROB_MAP=false
+# Skip the deep model entirely on tiles that are fully unchanged between before/
+# after (worst-cell LAB distance below this value — biggest single cell diff,
+# not an average, so a small real change is never diluted away and missed).
+# Big speed win on large images where most of the scene is static background;
+# 0/unset = disabled (default). Start conservative (e.g. 3-5).
+# DETECTION_SKIP_UNCHANGED_THRESHOLD=0
+
+# --- smart_union fusion calibration (Delhi accuracy sprint, Day 4-6) ---
+# Base classical-score percentile floor for smart_union fusion. Tuned from
+# 0.92 -> 0.90 against real Delhi Sentinel-2 imagery: +53% mean F1 on the
+# 16-pair labeled eval set, verified to pass the full synthetic regression
+# suite (incl. the mandatory car-FP gate) unchanged. Lower values (0.75-0.85)
+# scored even higher on Delhi but were REJECTED — they cause false positives
+# on the parked_cars synthetic case. See runs/calibration/best_params.json
+# for the full decision record (winning + rejected configs, with reasons).
+# DETECTION_CL_Q_BASE=0.90
+# Base DL confidence floor for smart_union fusion (default 0.36). Tested
+# down to 0.10 against Delhi imagery — no meaningful effect at full-set scale
+# (the pretrained AdaptFormer model's near-zero output on this coarse-GSD,
+# out-of-domain imagery isn't a thresholding problem; needs fine-tuning, not
+# calibration). Left at default. See runs/calibration/best_params.json.
+# DETECTION_DL_FLOOR_BASE=0.15
+
+# --- Research-integration channels (KPCAMNet / IR-MAD / SRCDNet / BIT_CD) ---
+# KPCA deep features (KPCAMNet): auto (default; drives Feature-Based method),
+# on (also adds a channel to the classical score map), off
+# DETECTION_KPCA=auto
+# Analysis-resolution cap for KPCA feature extraction (CPU bound)
+# DETECTION_KPCA_MAX_SIDE=768
+# IR-MAD change statistic: auto (default) | on (adds classical channel) | off
+# DETECTION_IRMAD=auto
+# Regression radiometric normalization from IR-MAD no-change pixels
+# (off by default: reduced F1 on the LEVIR-CD gate; useful for strong
+# sensor/illumination mismatch between acquisitions)
+# DETECTION_IRMAD_NORM=false
+# Resample GeoTIFF pairs to a common (coarser) GSD before detection
+# DETECTION_GSD_HARMONIZE=true
+# Relative GSD difference that triggers harmonization/preflight warning
+# DETECTION_GSD_TOLERANCE=0.15
+# Preflight overlap gate: below this fraction of the after-image footprint,
+# a pair is rejected as not suitable for change detection (hard fail)
+# DETECTION_MIN_OVERLAP_HARD=0.02
+# Below this fraction, overlap is weak but detection still runs (soft warning)
+# DETECTION_MIN_OVERLAP_WARN=0.20
+# Ensemble AdaptFormer with BIT_CD (requires weights, see below; default off)
+# DETECTION_ENSEMBLE=off
+# BIT_CD LEVIR-CD checkpoint path. Download best_ckpt.pt from the BIT_CD
+# repo's release links (https://github.com/justchenhao/BIT_CD) and place it at
+# app/cd_models/weights/bit_cd_levir.pth (raw training checkpoints with a
+# model_G_state_dict key are accepted as-is).
+# BIT_CD_WEIGHTS=app/cd_models/weights/bit_cd_levir.pth
+
+# Public URL for report links in emails (default http://localhost:8000 locally)
+# PUBLIC_BASE_URL=http://localhost:8000
+
+# Email notifications (optional). Password reset still uses this backend.
+# EMAIL_API_URL=https://emailservice.managemybusinessess.com/api/email/send
+# Login SMS OTP: POST ToMobile/Message to SMS_API_URL (default: same host as
+# EMAIL_API_URL with /api/sms/send). Or set SMS_PROVIDER=fast2sms + SMS_API_KEY.
+# SMS_API_URL=
+# SMS_PROVIDER=
+# SMS_API_KEY=
+# LOGIN_OTP_LOG=1
+# SMTP_HOST=smtp.gmail.com
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASS=
+
+# Hugging Face model cache directory
+# HF_HOME=./.hf_cache
+
+# Department export API (optional — FR-08)
+# DEPT_API_URL=https://dept.example.gov/api/changes
+# DEPT_API_KEY=your-api-key
+
+# DDA admin account (optional — UAT / ops)
+# DDA_ADMIN_EMAIL=admin@example.com
+# DDA_ADMIN_PASSWORD=change-me
+# DDA_TRAINING_EXPORT_KEY=secret-key-for-fp-export

.gitignore

@@ -0,0 +1,44 @@
+__pycache__/
+*.pyc
+*.pyo
+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
+library_sources/**/*.TIF
+library_sources/**/*.TIFF
+data/library_sources/**/*.tif
+data/library_sources/**/*.tiff
+data/library_sources/**/*.TIF
+data/library_sources/**/*.TIFF
+data/library_sources/**/*.png
+data/library_sources/**/*.jpg
+data/library_sources/**/*.jpeg
+!library_sources/**/.gitkeep
+.env
+*.egg-info/
+dist/
+build/
+venv/
+# Generated eval/calibration outputs (masks, leaderboards, metrics)
+runs/
+# Large fine-tuned weights (export locally via scripts/export_adaptformer_delhi.py)
+models/adaptformer_delhi/best/
+models/adaptformer_delhi/*.pt
+*.safetensors
+# Local label backup from merge conflicts
+docs/delhi_eval/labels/_local_backup_*/
+# WHU reference dataset (real-data pipeline test set, not Delhi imagery — see docs/whu_reference/)
+data/whu_reference/
+data/large_geotiff_test/
+data/large_geotiff_test.zip
+# Third-party CD clones + DSIFN Drive downloads (hundreds of MB)
+third_party/
+models/dsifn_proxy/*.pt
+# Building-footprint reference data (461MB geojson — exceeds GitHub's 100MB limit)
+data/building_footprints/
+# Priyanka synthetic CD triplets (before/after/mask PNGs — local training only)
+data/synthetic_cd/

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "PowerShell: Launch Current File",
+            "type": "PowerShell",
+            "request": "launch",
+            "script": "${file}",
+            "args": []
+        }
+    ]
+}

AI_Change_Detection_Handover.md

@@ -0,0 +1,280 @@
+# AI Change Detection — Project Handover Document
+
+**Prepared by:** Development Team
+**Date:** February 7, 2026
+**Version:** 2.0
+**Live URL:** [Hugging Face Spaces — AI Change Detection](https://huggingface.co/spaces/coderuday21/satdetect)
+
+---
+
+## 1. Executive Summary
+
+AI Change Detection is a web-based application that automatically detects, classifies, and visualizes changes between two satellite or aerial images taken at different times. Users upload a "before" and "after" image, and the system identifies what changed on the ground — new buildings, deforestation, road construction, demolitions, water body changes, and more.
+
+The application provides detailed reports including change statistics, object-level classification with sub-type breakdowns, 3D building analysis (estimated height and construction stage), and an interactive visual overlay highlighting all detected changes in red.
+
+---
+
+## 2. Problem Statement
+
+Manually comparing satellite imagery to identify ground-level changes is:
+
+- **Time-consuming** — Analysts spend hours visually scanning large image pairs pixel by pixel.
+- **Error-prone** — Human eyes miss subtle changes in vegetation health, gradual construction, or surface texture shifts.
+- **Inconsistent** — Different analysts may classify the same change differently.
+- **Unscalable** — As the volume of imagery grows (urban planning, environmental monitoring, disaster response), manual review cannot keep pace.
+
+**AI Change Detection solves this** by automating the entire detection-to-classification pipeline, delivering consistent, quantified results in seconds.
+
+---
+
+## 3. Target Users
+
+| User Role | How They Use It |
+|-----------|----------------|
+| Urban planners | Track unauthorized construction, building expansion, and infrastructure changes |
+| Environmental analysts | Monitor deforestation, vegetation health decline, and land-use changes |
+| Disaster response teams | Assess structural damage after natural disasters by comparing pre/post imagery |
+| Agricultural analysts | Detect crop changes, seasonal variation, and land conversion |
+| Government agencies | Monitor compliance with zoning and environmental regulations |
+| Construction firms | Track construction progress and stage classification over time |
+
+---
+
+## 4. Key Features
+
+### 4.1 Multi-Method Change Detection
+
+The system offers four detection methods, each suited to different scenarios:
+
+| Method | Best For | Speed |
+|--------|----------|-------|
+| **Image Difference** | Quick scans where changes involve obvious color shifts (e.g., cleared forest) | Fastest |
+| **Feature-Based** | Subtle, distributed changes across large areas (e.g., gradual land-use shift) | Fast |
+| **AI-Based Deep Learning** | Highest accuracy — combines color, structure, texture, and edge analysis | Moderate |
+| **Hybrid Approach** | Maximum coverage when unsure which type of changes to expect | Slowest |
+
+Users select the method per run depending on their accuracy vs. speed needs.
+
+### 4.2 Intelligent Pre-Processing
+
+Before comparing images, the system can automatically:
+
+- **Align images** (Image Registration) — Corrects for camera angle, zoom, and position differences between the two photos so the comparison is pixel-accurate.
+- **Normalize lighting** (Radiometric Normalization) — Corrects for brightness/contrast differences caused by weather, time of day, or different cameras, preventing false positives from lighting alone.
+
+Both options are user-toggleable per run.
+
+### 4.3 Ground-Level Change Classification
+
+Every detected change region is automatically classified into one of six categories:
+
+| Category | What It Detects |
+|----------|----------------|
+| **New Construction / Building** | New structures appearing on previously empty land |
+| **Demolition / Clearing** | Structures or vegetation that have been removed |
+| **Vegetation Change** | Any change in plant cover — forests, crops, parks |
+| **Water Body Change** | New, expanded, or reduced water features |
+| **Road / Pavement Change** | New roads, widened paths, resurfaced areas |
+| **Bare Land / Soil Change** | Exposed earth, grading, land preparation |
+
+**Transient objects are automatically filtered out** — people, vehicles, animals, and shadows are excluded so only permanent ground-level changes are reported.
+
+### 4.4 Detailed Sub-Classification
+
+Each primary category is further broken down into specific sub-types by comparing the "before" and "after" regions:
+
+**Vegetation Sub-Types:**
+
+| Sub-Type | What It Means |
+|----------|---------------|
+| Deforestation / Tree Removal | Green area has been cleared — trees or vegetation removed |
+| New Vegetation / Growth | Previously bare area now has plant cover |
+| Crop / Agricultural Change | Farmland has changed crop type or land use pattern |
+| Vegetation Health Decline | Plants are browning or showing signs of drought/disease |
+| Seasonal Variation | Normal seasonal color shift, both periods still green |
+
+**Structural Sub-Types:**
+
+| Sub-Type | What It Means |
+|----------|---------------|
+| New Building | Structure appeared where none existed before |
+| Building Expansion | Existing building has been extended or enlarged |
+| Renovation / Modification | Building exists in both images but has changed appearance |
+| Partial Demolition | Part of a structure has been removed |
+| Full Demolition | Entire structure has been removed, area is now bare |
+| Infrastructure Change | Non-building structures (bridges, towers, utilities) |
+
+**Road Sub-Types:**
+
+| Sub-Type | What It Means |
+|----------|---------------|
+| New Road / Pavement | Road appeared where none existed before |
+| Road Widening | Existing road has been expanded |
+| Road Resurfacing | Road surface has been repaved (different appearance, same width) |
+| Road Deterioration | Road surface has degraded |
+
+### 4.5 3D Building Analysis
+
+For regions classified as buildings or construction, the system provides:
+
+- **Estimated Stories** — Number of floors, calculated from shadow analysis and building footprint geometry.
+- **Estimated Height** — Height in meters (based on 3m per story).
+- **Construction Stage** — Classified as Foundation, Structural, Under Construction, or Complete based on visual features.
+
+### 4.6 Interactive Visual Output
+
+- **Red overlay** — All detected changes are highlighted in red on the "after" image.
+- **Before/After slider** — A draggable comparison slider lets users visually inspect what changed by sliding between the original and the annotated result.
+- **Annotated bounding boxes** — Each detected region gets a labeled bounding box showing its sub-type, stories, and construction stage.
+
+### 4.7 User Accounts & History
+
+- **Secure login system** — Email/password registration with encrypted password storage.
+- **Detection history** — All past runs are saved with their results, overlay images, and metadata. Users can revisit or delete previous runs.
+- **Password reset** — Users can reset their password from the login screen.
+
+### 4.8 Responsive Design
+
+The application is fully functional on desktop browsers and mobile devices, with an optimized layout for smaller screens.
+
+---
+
+## 5. Technology Stack
+
+| Layer | Technology | Purpose |
+|-------|-----------|---------|
+| **Frontend** | HTML, CSS, JavaScript (Vanilla) | Single-page application — no framework dependencies |
+| **Backend** | Python, FastAPI | REST API server handling authentication and detection |
+| **Image Processing** | OpenCV, NumPy, Scikit-learn, Pillow | Core algorithms for detection, classification, and visualization |
+| **Database** | SQLite (local), PostgreSQL (production-ready) | User accounts and detection run history |
+| **Authentication** | JWT tokens, bcrypt password hashing | Secure stateless authentication |
+| **Deployment** | Docker, Hugging Face Spaces | Containerized cloud deployment |
+
+---
+
+## 6. Application Screens
+
+### Login / Registration
+- Clean login form with email and password
+- Password visibility toggle (eye icon)
+- "Forgot password" option
+- Toggle between sign-in and registration
+
+### Dashboard (Main Screen)
+- **Upload Section** — Two drag-and-drop zones for before and after images with live previews
+- **Configuration** — Method selector, run title, and optional pre-processing toggles
+- **Results Section** — Appears after running detection:
+  - Statistics bar: change percentage, changed pixels, total pixels, region count
+  - Before/after comparison slider
+  - Detailed table of all detected regions with type, sub-type, confidence, area, building data, and coordinates
+- **History Section** — List of all past runs with option to view overlay or delete
+
+---
+
+## 7. Output Data Per Detection Run
+
+Each run produces the following data:
+
+| Field | Description |
+|-------|-------------|
+| Change Percentage | Proportion of the image area that changed |
+| Changed Pixels | Total number of pixels detected as changed |
+| Total Pixels | Total image area in pixels |
+| Regions Count | Number of distinct change regions identified |
+| **Per Region:** | |
+| Change Type | Primary category (Construction, Vegetation, etc.) |
+| Sub-Type | Detailed sub-classification (New Building, Deforestation, etc.) |
+| Confidence | Classification confidence score (0–100%) |
+| Area | Region size in pixels |
+| Estimated Stories | Number of building floors (building regions only) |
+| Estimated Height | Height in meters (building regions only) |
+| Construction Stage | Foundation / Structural / Under Construction / Complete (building regions only) |
+| Center Coordinates | Location of the region center in the image |
+| Overlay Image | Annotated image with red highlights and bounding boxes |
+
+---
+
+## 8. Deployment & Access
+
+### Current Deployment
+- **Platform:** Hugging Face Spaces (free tier)
+- **URL:** https://huggingface.co/spaces/coderuday21/satdetect
+- **Container:** Docker-based, auto-deploys on code push
+- **Database:** SQLite (ephemeral — resets when the container restarts)
+
+### Limitations of Current Deployment
+| Limitation | Impact | Mitigation Path |
+|-----------|--------|-----------------|
+| Ephemeral database | User accounts and history are lost on container restart | Migrate to external PostgreSQL database |
+| No email verification on password reset | Anyone who knows an email can reset the password | Implement token-based email verification flow |
+| Single-worker server | Cannot handle high concurrent load | Scale to multiple workers with PostgreSQL |
+| Free-tier resources | Limited CPU/memory, images capped at 2000px and 20MB | Upgrade to paid hosting for larger images |
+
+### For Production Deployment
+To move from the current demo to a production environment, the following would be needed:
+1. External PostgreSQL database for persistent storage
+2. Email service integration (SendGrid, AWS SES) for password reset verification
+3. Paid cloud hosting (AWS, GCP, or Azure) for better performance
+4. HTTPS with a custom domain
+5. Environment-based secret key management
+
+---
+
+## 9. How Accuracy Works
+
+The system does **not** use a pre-trained deep learning model (no neural network). Instead, it uses a **multi-signal fusion approach** — combining multiple independent analysis methods that each measure a different aspect of change:
+
+1. **Color difference** — Measures how much the color changed at each pixel (in perceptually uniform color space).
+2. **Structural similarity** — Measures whether the patterns and structures at each pixel changed.
+3. **Texture analysis** — Measures whether the surface texture changed (smooth → rough, etc.).
+4. **Edge detection** — Measures whether structural boundaries appeared or disappeared.
+
+These four signals are weighted by their discriminative power and fused into a single change map. This approach is:
+
+- **Transparent** — Every decision can be traced to specific visual features (no "black box").
+- **Deterministic** — The same inputs always produce the same outputs.
+- **No training data required** — Works on any satellite/aerial imagery without needing labeled datasets.
+
+**Trade-off:** A trained deep learning model (e.g., U-Net, Siamese network) would likely achieve higher accuracy on specific datasets, but would require labeled training data and GPU resources. The current approach provides good accuracy out-of-the-box for general-purpose change detection.
+
+---
+
+## 10. Future Enhancement Opportunities
+
+| Enhancement | Business Value |
+|-------------|---------------|
+| Deep learning model integration (U-Net / Siamese CNN) | Significantly higher detection accuracy on trained domains |
+| Batch processing / multi-image upload | Analyze time-series imagery for trend analysis |
+| GIS integration (GeoTIFF, coordinate mapping) | Pin changes to real-world geographic coordinates |
+| PDF/Excel report export | Downloadable reports for stakeholder distribution |
+| Webhook / API integration | Automate detection as part of larger monitoring pipelines |
+| Role-based access (admin, analyst, viewer) | Team collaboration with permission controls |
+| Notification system | Alert stakeholders when significant changes are detected |
+| Cloud-optimized image storage | Handle very large satellite tiles (10,000+ pixels) |
+
+---
+
+## 11. Repository Structure
+
+```
+change_detection_webapp/
+├── app/
+│   ├── main.py              → API server and route definitions
+│   ├── auth.py              → Authentication (JWT, password hashing)
+│   ├── models.py            → Database table definitions
+│   ├── database.py          → Database connection setup
+│   └── detection_engine.py  → All image processing and classification algorithms
+├── templates/
+│   └── index.html           → Frontend page structure
+├── static/
+│   ├── css/style.css        → All visual styling
+│   └── js/app.js            → Client-side logic
+├── Dockerfile               → Container build instructions
+├── requirements.txt         → Python package dependencies
+└── ARCHITECTURE.md          → Technical architecture reference (for developers)
+```
+
+---
+
+*For technical implementation details, refer to `ARCHITECTURE.md` in the project repository.*

ARCHITECTURE.md

@@ -0,0 +1,387 @@
+# AI Change Detection — Architecture & Component Guide
+
+## Overview
+
+AI Change Detection is a full-stack web application that detects, classifies, and visualizes changes between two satellite or aerial images (before and after). It uses multi-signal image processing — combining color analysis, structural similarity, texture descriptors, and edge detection — to identify ground-level changes such as new buildings, deforestation, road construction, and more.
+
+---
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                   Browser (SPA)                  │
+│  index.html  +  style.css  +  app.js            │
+│  Login / Register / Upload / Results / History   │
+└────────────────────┬────────────────────────────┘
+                     │  REST API (JSON + multipart)
+┌────────────────────▼────────────────────────────┐
+│              FastAPI Backend (main.py)            │
+│  Auth routes  ·  Detection route  ·  History     │
+├──────────┬──────────┬───────────────────────────┤
+│ auth.py  │ models.py│  detection_engine.py       │
+│ JWT auth │ ORM      │  Image processing pipeline │
+├──────────┴──────────┤                            │
+│   database.py       │  SQLite (local) / MySQL    │
+└─────────────────────┴───────────────────────────┘
+```
+
+---
+
+## File-by-File Component Breakdown
+
+### 1. `app/main.py` — API Server & Route Definitions
+
+**Role:** The central FastAPI application. Defines all HTTP endpoints, wires together authentication, database, and the detection engine.
+
+**Use cases solved:**
+- **User registration & login** (`POST /api/auth/register`, `POST /api/auth/login`) — Creates accounts and issues JWT tokens stored as HTTP-only cookies.
+- **Session management** (`POST /api/auth/logout`, `GET /api/me`) — Clears auth cookies; returns the current authenticated user.
+- **Password reset** (`POST /api/auth/reset-password`) — Allows users to reset their password by email (no email verification — documented limitation).
+- **Change detection** (`POST /api/detect`) — Accepts two images (before/after) plus configuration options, runs the full detection pipeline, saves the overlay image to disk, stores run metadata in the database, and returns results with a base64-encoded overlay for immediate display.
+- **History** (`GET /api/history`, `DELETE /api/history/{id}`) — Lists past detection runs for the logged-in user; allows deletion of individual runs and their overlay files.
+- **Static file serving** — Mounts the `static/` directory for CSS/JS and serves `templates/index.html` as the SPA entry point.
+- **Upload size limiting** — Rejects images larger than 20 MB to prevent out-of-memory crashes.
+
+---
+
+### 2. `app/auth.py` — Authentication & Authorization
+
+**Role:** Handles password hashing, JWT token creation/validation, and user lookup.
+
+**Use cases solved:**
+- **Secure password storage** — Uses bcrypt via `passlib` to hash passwords before storing them. Plaintext passwords never touch the database.
+- **Stateless authentication** — Issues HS256 JWT tokens with a 7-day expiry. Tokens are sent as HTTP-only cookies (for browser requests) and also accepted as Bearer tokens in the Authorization header.
+- **Multi-source token resolution** — `get_current_user()` checks three sources in order: Authorization header, HTTP cookie, then form field. This ensures authentication works for both API clients and browser multipart form submissions.
+
+---
+
+### 3. `app/models.py` — Database Models (ORM)
+
+**Role:** Defines the SQLAlchemy ORM models that map to database tables.
+
+**Tables:**
+- **`users`** — Stores account data: email, bcrypt-hashed password, full name, and creation timestamp. Each user has a one-to-many relationship with detection runs.
+- **`detection_runs`** — Stores metadata for each detection run: title, method used, pixel statistics (total, changed, percentage), region count, path to the saved overlay image, and a JSON blob of all classified regions with their sub-types and 3D analysis data.
+
+**Use case solved:** Persistent storage of user accounts and detection history so users can revisit past results.
+
+---
+
+### 4. `app/database.py` — Database Connection & Session Management
+
+**Role:** Configures the SQLAlchemy engine, session factory, and data directory paths.
+
+**Use cases solved:**
+- **Environment-aware storage** — Detects Hugging Face Spaces (via `SPACE_ID` env var) and uses a writable home directory; falls back to a local `data/` directory for development.
+- **Database portability** — Defaults to SQLite for zero-config local development. Production uses MySQL via `DATABASE_URL` (`mysql+pymysql://...`); PostgreSQL is also supported (with automatic `postgres://` → `postgresql://` rewrite for SQLAlchemy 2.x compatibility). `pool_pre_ping` is enabled for any non-SQLite backend so stale/dropped remote connections are transparently recycled.
+- **Session lifecycle** — The `get_db()` generator provides request-scoped database sessions with automatic cleanup.
+
+---
+
+### 5. `app/detection_engine.py` — Image Processing & Classification Pipeline
+
+This is the core of the application. It contains all image analysis algorithms organized into a sequential pipeline.
+
+#### 5a. Pre-processing (`preprocess_image`)
+
+**Use case:** Normalizes input images to a consistent format before analysis.
+- Converts grayscale or RGBA images to RGB.
+- Downscales images larger than 2000px on any side to prevent memory issues while preserving enough detail for analysis.
+
+#### 5b. Image Registration (`register_images`)
+
+**Use case:** Aligns the "after" image to the "before" image so pixel-level comparison is meaningful.
+- Uses ORB feature detection to find matching keypoints between both images.
+- Applies Lowe's ratio test to filter spurious matches.
+- Computes a RANSAC homography to warp the after image into alignment.
+- Rejects bad alignments via inlier ratio threshold and homography determinant check (catches degenerate transforms).
+- **Why it matters:** Without alignment, even a slight camera angle difference would cause the entire image to appear "changed."
+
+#### 5c. Radiometric Normalization (`normalize_radiometry`)
+
+**Use case:** Corrects brightness and contrast differences between the two images caused by different lighting conditions, seasons, or sensors.
+- Performs histogram matching in LAB color space (perceptually uniform) so the "after" image has the same color distribution as the "before."
+- Applies CLAHE (Contrast Limited Adaptive Histogram Equalization) symmetrically to both images to enhance local contrast without introducing bias.
+- **Why it matters:** A cloudy day vs. a sunny day would otherwise create massive false-positive "changes" everywhere.
+
+#### 5d. SSIM Change Map (`compute_ssim_change_map`)
+
+**Use case:** Measures structural dissimilarity between corresponding regions of both images.
+- Computes per-pixel Structural Similarity Index (SSIM) using Gaussian-weighted windows.
+- Outputs a dissimilarity map where 0 = identical and 1 = completely different.
+- Clamps variance values to prevent numerical instability from floating-point rounding.
+- **Why it matters:** SSIM captures structural patterns (edges, textures) that simple color difference would miss.
+
+#### 5e. Texture Features (`compute_lbp`, `compute_texture_change`)
+
+**Use case:** Detects changes in surface texture (e.g., smooth road vs. rough construction rubble).
+- Computes Local Binary Patterns (LBP) — a texture descriptor that encodes the relationship between each pixel and its neighbors.
+- The absolute difference between before/after LBP maps highlights regions where surface texture changed.
+- **Why it matters:** Two regions can have similar colors but very different textures (e.g., grass vs. artificial turf, bare soil vs. concrete).
+
+#### 5f. Edge Change Detection (`compute_edge_change`)
+
+**Use case:** Identifies new or removed structural boundaries.
+- Uses Canny edge detection with adaptive thresholds based on median intensity.
+- Dilates edges so nearby edges match (tolerates minor misalignment).
+- Computes the absolute difference to find edges present in one image but not the other.
+- **Why it matters:** New buildings, roads, and demolished structures introduce or remove strong edges.
+
+#### 5g. Detection Methods (4 options)
+
+| Method | Description | Best For |
+|--------|-------------|----------|
+| **Image Difference** | LAB color space Delta-E difference with Otsu thresholding | Fast, simple comparisons with clear color changes |
+| **Feature-Based** | Multi-space (LAB + HSV) feature clustering via KMeans | Subtle, distributed changes across large areas |
+| **AI-Based Deep Learning** | Multi-signal fusion (color + SSIM + texture + edge) with entropy-weighted adaptive combination | Highest accuracy; catches both color and structural changes |
+| **Hybrid Approach** | Weighted blend of all three methods (20% difference + 30% feature + 50% AI) | Maximum coverage when unsure which method is best |
+
+**Image Difference** (`image_difference_method`):
+- Converts to LAB and computes a weighted Delta-E (CIE76) difference per pixel.
+- Applies Otsu's automatic threshold to separate "changed" from "unchanged."
+- Fast but only catches color changes — misses structural changes where color stays similar.
+
+**Feature-Based** (`feature_based_method`):
+- Extracts LAB and HSV difference features per pixel.
+- Downsamples to 250K pixels for KMeans clustering (4 clusters), then maps labels back to full resolution.
+- The cluster with the highest mean feature magnitude is labeled "change."
+- Good at finding spatially distributed or gradual changes.
+
+**AI-Based Deep Learning** (`ai_deep_learning_method`):
+- Fuses four independent signals: multi-scale LAB color difference, SSIM structural dissimilarity, LBP texture change, and Canny edge change.
+- Weights each channel by its information entropy (channels with more discriminative power get higher weight).
+- Applies Otsu thresholding followed by bilateral filtering for edge-preserving smoothing.
+- The most accurate method — captures color, structure, texture, and edge changes simultaneously.
+
+**Hybrid** (`hybrid_method`):
+- Runs all three methods and combines their masks with fixed weights.
+- AI method gets the most weight (50%) as it's most reliable.
+
+#### 5h. Post-processing (`_clean_mask`)
+
+**Use case:** Cleans up raw change masks to remove noise and fill gaps.
+- Morphological closing (fills small gaps inside detected regions).
+- Morphological opening (removes small noise speckles).
+- Contour-based hole filling (ensures detected regions are solid).
+- Sensitivity parameter controls the aggressiveness of gap-filling.
+
+#### 5i. Visualization (`visualize_changes`)
+
+**Use case:** Creates the final overlay image showing detected changes.
+- Draws a semi-transparent red overlay on all changed pixels in the "after" image.
+- Draws white bounding boxes around each classified region.
+- Annotates regions with labels showing sub-type, building stories, and construction stage.
+
+#### 5j. Object Classification (`classify_object_type`, `classify_with_ensemble`)
+
+**Use case:** Determines what kind of ground-level change each detected region represents.
+
+**Feature extraction** (`extract_advanced_features`):
+- Extracts 17 features per region: color stats (RGB, HSV, LAB means/stds), vegetation index (NDVI), texture (LBP variance, standard deviation), edges (density, orientation entropy), GLCM-like contrast, shape ratios, and color ratios.
+
+**Transient object filtering** (`_is_transient_object`):
+- Filters out non-permanent changes: people, vehicles, animals, shadows.
+- Uses area, aspect ratio, edge density, and texture variance thresholds.
+
+**Classification categories:**
+| Category | Key Indicators |
+|----------|---------------|
+| New Construction/Building | Low orientation entropy, compact shape, moderate edges, low saturation |
+| Demolition/Clearing | High texture variance, high entropy, bright, low vegetation |
+| Vegetation Change | High NDVI, green ratio, medium texture, high saturation |
+| Water Body Change | High blue ratio, low texture, smooth surface, specific hue range |
+| Road/Pavement Change | Elongated shape, homogeneous color, low saturation, low entropy |
+| Bare Land/Soil Change | High red ratio, low NDVI, low texture, earth-tone hue |
+
+**Ensemble voting** (`classify_with_ensemble`):
+- Classifies the full region plus 5 sub-regions (quadrants + center).
+- Combines votes weighted by confidence.
+- Boosts confidence when ≥60% of sub-regions agree.
+- Only excludes a region as transient if a majority of sub-regions are flagged.
+
+#### 5k. Vegetation Sub-Classification (`classify_vegetation_subtype`)
+
+**Use case:** Provides detailed breakdown of vegetation changes by comparing the before and after region crops.
+
+| Sub-Type | Detection Logic |
+|----------|----------------|
+| Deforestation/Tree Removal | Before was green (high NDVI), after is bare (NDVI dropped, brightness increased) |
+| New Vegetation/Growth | Before was bare, after is green (NDVI increased, saturation up) |
+| Crop/Agricultural Change | Regular texture patterns in either image, moderate NDVI shift, large area |
+| Vegetation Health Decline | Both images green but NDVI and saturation slightly decreased (browning/drought) |
+| Seasonal Variation | Mild color/texture shift, both images still green |
+
+#### 5l. Structural Sub-Classification (`classify_structural_subtype`)
+
+**Use case:** Provides detailed breakdown of structural and road changes by comparing before/after structure presence, edge density, and texture.
+
+| Sub-Type | Detection Logic |
+|----------|----------------|
+| New Building | No structure before, structure detected after |
+| Building Expansion | Structure in both images, but after has higher edge density |
+| Renovation/Modification | Structure in both, similar density but different appearance (brightness/saturation shift) |
+| Partial Demolition | Structure before, reduced edges after |
+| Full Demolition | Structure before, bare/empty after |
+| Infrastructure Change | Elongated shape with high geometric regularity |
+| New Road/Pavement | No structure before, structure after (for road-type regions) |
+| Road Widening | Structure in both, edge density increased |
+| Road Resurfacing | Structure in both, similar edges but brightness changed |
+| Road Deterioration | Texture increased, edges decreased (surface degradation) |
+
+#### 5m. 3D Building Analysis
+
+**Use case:** Estimates building height/stories and classifies construction stage for building-type regions.
+
+**Shadow-based height estimation** (`estimate_building_height`):
+- Detects new shadow pixels adjacent to the building by comparing brightness in the expanded bounding box area between before and after images.
+- Measures shadow length as the maximum spatial extent of the shadow cluster.
+- Combines shadow ratio, footprint geometry (compact = likely taller), and texture regularity to estimate story count.
+- Assumes 3 meters per story.
+
+**Construction stage classification** (`classify_construction_stage`):
+| Stage | Visual Indicators |
+|-------|------------------|
+| Foundation | Low texture, low edges, homogeneous, soil/concrete colors |
+| Structural | High edges, geometric regularity (low entropy), high GLCM contrast |
+| Under Construction | Mixed materials, irregular texture, medium edge density |
+| Complete | Uniform roof, clean edges, low entropy, consistent color |
+
+---
+
+### 6. `templates/index.html` — Frontend Structure
+
+**Role:** Single-page application (SPA) with four views managed by JavaScript.
+
+**Views:**
+- **Login** — Email/password form with password visibility toggle and "Forgot password" link.
+- **Register** — Account creation form with name, email, and password.
+- **Forgot Password** — Email + new password form (simplified reset without email verification).
+- **Dashboard** — The main workspace containing:
+  - **Upload zone** — Drag-and-drop or click-to-browse for before/after images with live previews.
+  - **Detection options** — Method selector, title input, image registration and radiometric normalization toggles.
+  - **Results panel** — Statistics boxes (change %, changed pixels, total pixels, region count), before/after comparison slider, and a detailed regions table with columns for change type, sub-type, confidence, area, stories, height, construction stage, and center coordinates.
+  - **History** — List of past detection runs with view and delete actions.
+
+---
+
+### 7. `static/css/style.css` — Visual Design
+
+**Role:** Complete styling for the application using CSS custom properties and a gradient theme.
+
+**Key design decisions:**
+- **Color theme** — Linear gradient from `#2e33c5` (blue) to `#cf2040` (red) applied to the navbar, footer, buttons, and accent elements. White background for content areas.
+- **Sticky navbar** — Full-viewport-width gradient bar that stays fixed at the top during scrolling.
+- **Mobile responsive** — Grid layouts collapse to single columns on screens under 768px. Font sizes, padding, and table layouts adapt to small screens.
+- **Glassmorphism dropdown** — User account menu uses a gradient background with subtle shadow for the avatar popup.
+- **Compare slider** — Custom CSS for the before/after image comparison handle with gradient accents.
+- **Stat boxes** — Responsive font sizing with `clamp()` and compact number formatting to prevent overflow.
+
+---
+
+### 8. `static/js/app.js` — Client-Side Logic
+
+**Role:** All browser-side interactivity — authentication flow, file uploads, API communication, result rendering, and UI state management.
+
+**Key responsibilities:**
+- **Authentication** — Login, register, forgot-password form handlers that call the API and store JWT tokens in localStorage. Automatic session check on page load (`init()`).
+- **File upload** — Drag-and-drop and click-to-browse handlers with live image previews.
+- **Detection submission** — Builds a FormData payload with images and settings, sends to `/api/detect`, and renders results.
+- **Result rendering** — Populates stat boxes with compact-formatted numbers, fills the regions table, sets up the before/after comparison slider, and scrolls to results.
+- **History management** — Loads past runs, renders them with view/delete actions, and handles deletion with an animated confirmation modal.
+- **UI utilities** — View switching, error/success alerts, avatar dropdown toggle, password visibility toggle, and HTML escaping.
+
+---
+
+### 9. `Dockerfile` — Container Configuration
+
+**Role:** Defines the Docker image for deployment on Hugging Face Spaces.
+
+**Key aspects:**
+- Base image: `python:3.11-slim` with OpenCV system dependencies (`libgl1`, `libglib2.0-0`, etc.).
+- Non-root user (`appuser`) as required by Hugging Face Spaces security policy.
+- Runs Gunicorn with a single Uvicorn worker on port 7860 (HF Spaces default) with 120-second timeout for long detection runs.
+- Single worker prevents SQLite write-lock race conditions.
+
+---
+
+### 10. `requirements.txt` — Python Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `fastapi` | Web framework for the REST API |
+| `uvicorn` | ASGI server (production via Gunicorn) |
+| `gunicorn` | Process manager for production deployment |
+| `python-multipart` | Handles multipart/form-data file uploads |
+| `sqlalchemy` | ORM for database operations |
+| `pymysql` | MySQL driver (production database) |
+| `python-jose` | JWT token encoding/decoding |
+| `passlib` + `bcrypt` | Password hashing (bcrypt pinned to 4.0.1 for compatibility) |
+| `pillow` | Image loading and format conversion |
+| `numpy` | Numerical array operations for image processing |
+| `opencv-python-headless` | Core image processing (registration, morphology, edge detection, color conversion) |
+| `scikit-learn` | KMeans clustering for feature-based detection; StandardScaler for normalization |
+| `scipy` | Scientific computing utilities |
+
+---
+
+## Data Flow: End-to-End Detection Run
+
+```
+1. User uploads before + after images via browser
+       │
+2. POST /api/detect (multipart form with images + settings)
+       │
+3. Authentication check (JWT from cookie/header/form)
+       │
+4. Pre-processing
+   ├── Convert to RGB, limit to 2000px
+   │
+5. Image Registration (optional)
+   ├── ORB keypoints → ratio test → RANSAC homography → warp
+   │
+6. Radiometric Normalization (optional)
+   ├── LAB histogram matching + symmetric CLAHE
+   │
+7. Change Detection (selected method)
+   ├── Image Difference: LAB Delta-E + Otsu
+   ├── Feature-Based: LAB/HSV features + KMeans clustering
+   ├── AI-Based: Multi-signal fusion (color + SSIM + texture + edge)
+   └── Hybrid: Weighted combination of all three
+       │
+8. Post-processing
+   ├── Morphological closing/opening + hole filling
+       │
+9. Region Analysis
+   ├── Connected components → bounding boxes
+   ├── Feature extraction (17 features per region)
+   ├── Transient object filtering (remove people, cars, etc.)
+   ├── Primary classification (6 ground-level categories)
+   ├── Ensemble voting (full region + 5 sub-regions)
+   │
+10. Sub-Classification
+    ├── Vegetation: Deforestation / Growth / Crop / Health / Seasonal
+    ├── Structural: New / Expansion / Renovation / Partial Demo / Full Demo / Infrastructure
+    └── Road: New / Widening / Resurfacing / Deterioration
+       │
+11. 3D Building Analysis (for construction/demolition regions)
+    ├── Shadow detection → height/stories estimation
+    └── Construction stage classification
+       │
+12. Visualization
+    ├── Red overlay on changed pixels
+    ├── Bounding boxes + annotation labels
+       │
+13. Response
+    ├── Save overlay to disk + database record
+    └── Return JSON: stats, regions, base64 overlay image
+```
+
+---
+
+## Deployment
+
+- **Local development:** Run `uvicorn app.main:app --reload` from the project root. Uses `DATABASE_URL` if set (MySQL for this project), otherwise SQLite in `data/satellite_app.db`.
+- **Hugging Face Spaces:** Push to the linked HF repo. The Dockerfile builds and deploys automatically. Falls back to SQLite at `/home/appuser/data/` (ephemeral — resets on container restart) unless `DATABASE_URL` is set.
+- **Production with MySQL:** Set `DATABASE_URL` to a `mysql+pymysql://user:pass@host:3306/dbname` connection string (`pymysql` driver is in `requirements.txt`). Set `SECRET_KEY` to a strong random value. On Render, set `DATABASE_URL` manually in the dashboard (Environment tab) — it's `sync: false` in `render.yaml`, not committed to git.
+- **Production with PostgreSQL** (also supported): same pattern with a `postgresql://` URL — requires adding `psycopg2-binary` to `requirements.txt` first (not installed by default).

DEPLOYMENT.md

@@ -0,0 +1,227 @@
+# Deployment — Two Hugging Face Spaces
+
+This project uses **two separate Hugging Face Spaces** so the live app stays stable while you build changes for a new client.
+
+| Environment | Space | Git remote | Branch | URL |
+|-------------|-------|------------|--------|-----|
+| **Production** (current clients) | `coderuday21/satdetect` | `hf` | `production` | https://huggingface.co/spaces/coderuday21/satdetect |
+| **Development** (new client work) | `coderuday21/satdetect-dev` | `hf-dev` | `master` | https://huggingface.co/spaces/coderuday21/satdetect-dev |
+
+---
+
+## One-time setup: create the dev Space
+
+1. Open **https://huggingface.co/new-space**
+2. Set:
+   - **Owner:** `coderuday21`
+   - **Space name:** `satdetect-dev`
+   - **SDK:** Docker
+   - **Visibility:** Public (or Private if you prefer)
+3. Click **Create Space**.
+
+Then add the dev remote (once):
+
+```powershell
+cd change_detection_webapp
+git remote add hf-dev https://huggingface.co/spaces/coderuday21/satdetect-dev
+```
+
+If `hf-dev` already exists, update it:
+
+```powershell
+git remote set-url hf-dev https://huggingface.co/spaces/coderuday21/satdetect-dev
+```
+
+Push the current development code to the new Space:
+
+```powershell
+git push hf-dev master:main --force
+```
+
+> **First push only:** Hugging Face creates a starter README commit when you create the Space. Use `--force` once to replace it with your app. Later pushes can omit `--force`.
+
+Or run the helper script:
+
+```powershell
+.\scripts\push_hf_dev.ps1
+```
+
+---
+
+## Branch strategy
+
+```
+production  ──► hf (satdetect)         — live app (no login; direct to detection)
+master      ──► hf-dev (satdetect-dev) — new client experiments and upcoming changes
+```
+
+- **`production`** — tracks the stable live release (currently same as `master`, no login).
+- **`master`** — active development; push to the dev Space for testing before promoting to production.
+
+Work on new client features on `master`. When ready for the live app, merge into `production` and push to `hf`.
+
+---
+
+## Deploy commands
+
+### Production (live app — no login)
+
+```powershell
+git checkout production
+git merge master
+git push hf production:main
+```
+
+Or push `master` directly to production:
+
+```powershell
+git push hf master:main
+```
+
+Helper:
+
+```powershell
+.\scripts\push_hf_production.ps1
+```
+
+### Development (new client Space)
+
+After every change you want on the dev Space:
+
+```powershell
+git checkout master
+git push hf-dev master:main
+```
+
+Helper:
+
+```powershell
+.\scripts\push_hf_dev.ps1
+```
+
+---
+
+## GitHub mirror
+
+**Repo:** https://github.com/Uday-at-Vedang/DDA.ChangeDetection  
+**Default branch on GitHub:** `main`
+
+Push the full app from local `master`:
+
+```powershell
+git push origin master:main
+```
+
+Push the production branch too:
+
+```powershell
+git push origin production:main-production
+```
+
+Set upstream (once, after first push):
+
+```powershell
+git branch --set-upstream-to=origin/main master
+```
+
+---
+
+## Environment variables (both Spaces)
+
+Set these in each Space’s **Settings → Repository secrets / Variables** if needed:
+
+| Variable | Purpose |
+|----------|---------|
+| `APP_MODE` | Set to `dda` on **satdetect-dev** only (enables Vedangsoft library UI) |
+| `STORAGE_ROOT` | Tree library root directory (default: `data/library_sources/`) |
+| `LOCAL_LIBRARY_ROOT` | Alias for storage root override |
+| `MAX_GEOTIFF_MB` | Library GeoTIFF upload cap (default **5120** = 5 GB on dev) |
+| `MAX_IMAGE_MB` | PNG/JPEG library cap (default 50 MB) |
+| `SECRET_KEY` | Optional legacy JWT setting (login disabled) |
+| `DATABASE_URL` | MySQL (production) instead of SQLite — `mysql+pymysql://user:pass@host:3306/db`; PostgreSQL also supported |
+| `SMTP_USER` / `SMTP_PASS` | Email notifications via Gmail SMTP |
+| `EMAIL_API_URL` | Custom email API (default in code) |
+| `DEPT_API_URL` / `DEPT_API_KEY` | Departmental submit API (optional) |
+| `DDA_ADMIN_EMAIL` / `DDA_ADMIN_PASSWORD` | Seed admin user on dev (role: admin) |
+| `DDA_TRAINING_EXPORT_KEY` | Header `X-DDA-Training-Key` for false-positive export |
+
+### Detection accuracy controls (optional, dev-first)
+
+All default to the previous behavior, so leaving them unset changes nothing.
+
+| Variable | Purpose |
+|----------|---------|
+| `DETECTION_MAX_SIDE` | Downscaled-path pixel cap (default 4096 local / 2048 hosted) |
+| `DETECTION_INFERENCE_MODE` | `downscaled` (default) or `fullres_tiled` (native detail) |
+| `DETECTION_FULLRES_MAX_SIDE` | Full-res cap in fullres mode; 0 = native (default 8192) |
+| `DETECTION_WINDOWED_THRESHOLD` | Native side above which GeoTIFFs stream from disk windows (default 8192) |
+| `DETECTION_TILE_MEMORY_MB` | RAM budget per array before switching to windowed streaming (default 1536) |
+| `DETECTION_TILE_SIZE` / `DETECTION_TILE_OVERLAP` | Full-res tile geometry (default 512 / 0.25) |
+| `DETECTION_MULTISCALE` | `off` or scale list e.g. `0.5,1.0,1.5` (max-fused for recall) |
+| `DETECTION_FUSION` | `smart_union` (default) or `hysteresis` |
+| `DETECTION_CLAHE` / `DETECTION_HIST_MATCH` | Preprocessing toggles (CLAHE on, hist-match off) |
+| `DETECTION_SKIP_PREBLUR` | Skip denoise (auto-on in fullres mode) |
+| `DETECTION_BORDER_MARGIN` | Mask border zeroing (auto: 4 fullres / 12 downscaled) |
+| `DETECTION_TILE_BATCH` | Tiles per GPU forward pass (default 1) |
+| `DETECTION_SAVE_PROB_MAP` | Save a per-run probability PNG for debugging (default off) |
+
+Dev Space can omit `SECRET_KEY` (login is disabled on both Spaces).
+
+---
+
+## Tree library layout (unlimited depth)
+
+Images are organized in a **configurable tree** (zone → area → year → image type, or any depth):
+
+```text
+library_sources/
+  central_delhi/
+    karol_bagh/
+      2025/
+        Images/
+          satellite.tif
+```
+
+- **API:** `GET /api/dda/tree`, `POST /api/dda/tree/nodes`, upload via `POST /api/dda/tree/nodes/{id}/images/upload`
+- **UI:** Recursive tree sidebar on Library and Change Detection tabs; **Manage** (admin) for create/rename/move/delete
+- **Storage:** Slug-based disk paths; display names in `node_path`
+- **Local folders:** Create folders under `library_sources/{zone}/{area}/…/` and drop files into `Images/`; click **Refresh** (or restart app) to sync disk → DB via `POST /api/dda/local/rescan`
+- **Legacy:** Flat `library_sources/YEAR/` files auto-migrate to `Unassigned/Legacy/{year}/Images/` on startup
+
+---
+
+## UAT checklist (satdetect-dev)
+
+Run before promoting any Vedangsoft feature to production:
+
+1. **Health** — `GET /health` returns `status: ok`, `appMode: dda`, `dda.libraryImages` ≥ 0
+2. **Tree library** — Create zone → area → year nodes (admin); upload GeoTIFF to node; tree + grid show breadcrumb
+3. **Compare** — Tree sidebar filters image grid; T1/T2 dropdowns list all images; Run Detection completes with plausible lat/lng on georeferenced TIFFs
+4. **Viewer** — Slider / T1 / T2 / Overlay modes; click region to locate
+5. **Review** — Confirm and False Positive; Export confirmed CSV; Submit confirmed
+6. **Reports** — PDF download; `/dda/reports/{id}` page; email link (if SMTP configured)
+7. **Session isolation** — Two browsers see separate history (per-session cookie)
+8. **Admin** — `GET /api/dda/admin/status` (analyst+); stale job reconcile after restart
+9. **Training export** — Mark false positives → `GET /api/dda/training/export` (admin or export key)
+10. **Security** — Path traversal blocked (`../` in library path); upload size limit enforced
+
+Sign-off: DDA stakeholder approves sample runs on dev Space before any push to `satdetect` production.
+
+---
+
+## Quick reference
+
+```powershell
+# Daily work (new client)
+git checkout master
+# ... edit code ...
+git add .
+git commit -m "Your message"
+git push hf-dev master:main
+
+# Update live app (only when ready)
+git checkout production
+git merge master          # or cherry-pick specific commits
+git push hf production:main
+git checkout master
+```

DEV_SETUP.md

@@ -0,0 +1,284 @@
+# Vedangsoft 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/` | Set to MySQL (`mysql+pymysql://...`) for production; PostgreSQL also supported |
+| `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 Vedangsoft dev UI (Home, Image Library, Change Detection, and Reports pages).
+
+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.
+5. **Review (FR-08)** — Confirm / False Positive per region, export confirmed CSV, submit to dept API (`DEPT_API_URL`).
+6. **Session users** — Each browser gets isolated history via `dda_session_id` cookie (no login required).
+7. **Admin** — Optional `DDA_ADMIN_EMAIL` / `DDA_ADMIN_PASSWORD` for admin role; `GET /api/dda/admin/status`.
+
+---
+
+## 7. Project layout (Vedangsoft)
+
+```
+app/
+  main.py              # FastAPI entry
+  detection_engine.py  # Change detection pipeline
+  dda/                 # DDA modules (library, jobs, reports, geo)
+static/js/dda/         # Dev frontend
+templates/
+  partials/navbar_dda.html, result_modal_dda.html  # shared includes
+  home_dda.html, library_dda.html, detect_dda.html, reports_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 the Vedangsoft dev UI | 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 (Vedangsoft)
+
+| 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 |
+
+---
+
+## 11. Delhi evaluation workflow (accuracy calibration)
+
+Full end-to-end reproduction of the Delhi accuracy-improvement sprint (see `Accuracy_Improvement_Plan.xlsx`). Every command below runs from the repo root.
+
+### 11.1 Curate real Delhi pairs
+
+`library_sources/` ships empty (real imagery isn't committed — see `library_sources/README.md`). Two ways to populate it:
+
+```bash
+# Free, openly-licensed Sentinel-2 imagery (10m GSD — good for large land-use
+# change, vegetation, water bodies; not reliable for individual buildings/roads)
+python scripts/build_delhi_pairs_sentinel2.py --count 32
+
+# Or, once you have your own imagery (DDA-provided GeoTIFFs, drone, etc.) in
+# library_sources/<year>/:
+python scripts/build_delhi_manifest.py --scan      # see what's available
+python scripts/build_delhi_manifest.py --add --before library_sources/2024/x.tif \
+    --after library_sources/2026/x.tif --zone "..." --change-types building,road
+python scripts/build_delhi_manifest.py --validate  # check coverage (>=30 pairs, all 4 change types)
+```
+
+### 11.2 Label ground-truth masks
+
+```bash
+# Semi-automated candidate generation (CVA + adaptive threshold + blob filter)
+python scripts/generate_candidate_masks.py
+
+# Review docs/delhi_eval/labels/candidates/previews/*.png (before | after | mask | overlay),
+# then promote or reject each one:
+python scripts/accept_candidate_mask.py --pair-id delhi_0001
+python scripts/accept_candidate_mask.py --reject --pair-id delhi_0002
+```
+Candidate masks are a starting point, not ground truth — always eyeball the preview before promoting. See `docs/delhi_eval/manifest.json` notes per pair for known limitations found during review (e.g. diffuse changes needing hand-drawn rough polygons instead).
+
+### 11.3 Run the detection harness against the labeled set
+
+```bash
+python scripts/compare_methods.py --manifest docs/delhi_eval/manifest.json \
+    --methods "AI-Based Deep Learning,Feature-Based,Hybrid Approach" --sensitivities 0.5 \
+    --out runs/delhi_baseline
+```
+Reports per-pair IoU/F1/precision/recall for every labeled pair (unlabeled pairs run without ground-truth scoring).
+
+### 11.4 Grid-search calibration
+
+```bash
+python scripts/grid_search_calibration.py --methods "AI-Based Deep Learning" \
+    --sensitivities 0.5 --cl-qs 0.80,0.85,0.90,0.92 --manifest docs/delhi_eval/manifest.json
+```
+Sweeps `sensitivity` / `DETECTION_FUSION` / `DETECTION_DL_FLOOR_BASE` / `DETECTION_CL_Q_BASE` and ranks configs by mean F1 in `runs/calibration/leaderboard.csv`. **Always verify a promising config against the synthetic regression suite (11.5) before promoting it** — the highest Delhi F1 isn't automatically safe; see `runs/calibration/best_params.json` for a real example of a config that won on Delhi but broke a regression gate.
+
+### 11.5 Synthetic regression gate (mandatory before promoting any default)
+
+```bash
+python scripts/validate_detection.py --benchmark --method "AI-Based Deep Learning" \
+    --sensitivity 0.5 --out runs/synthetic_check
+```
+Four cases: `inserted_buildings`, `brightness_only`, `misaligned_change`, `parked_cars` (the mandatory car/transient-FP guard — must stay F1=1.0). Pass `--method`/`--sensitivity` to test any calibrated config; set the relevant `DETECTION_*` env vars first to test non-default fusion parameters.
+
+**Known gap:** the plan also references a LEVIR-CD regression case and a kappa statistic (Phase 0, marked "Complete"). Neither actually exists in this codebase as of the Day 5/6 calibration pass — only the 4 synthetic cases above are real, runnable gates. Treat any claim of "LEVIR-CD gate passing" as unverified until that harness is actually built.
+
+### 11.6 Promote a verified config to production defaults
+
+Once a config passes 11.5 unchanged, hardcode it as the new default in `app/detection_config.py` (e.g. `get_cl_q_base()`'s fallback value), then re-run 11.3 and 11.5 **with no env var set** to confirm the new default behaves identically to what was verified.

Dockerfile

@@ -0,0 +1,55 @@
+FROM python:3.11-slim
+
+# Ensure build logs flush immediately (helps when HF shows “BUILDING” with no output)
+ENV PYTHONUNBUFFERED=1
+
+# System dependencies for OpenCV and image processing
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 \
+    libglib2.0-0 \
+    libsm6 \
+    libxext6 \
+    libxrender1 \
+    gdal-bin \
+    libgdal-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user (required by Hugging Face Spaces)
+RUN useradd -m -u 1000 appuser
+
+WORKDIR /app
+
+# Build-time info + cache-bust:
+# Changing APP_BUILD forces Docker to re-run subsequent layers (including pip install).
+ARG APP_BUILD=38
+ENV MAX_GEOTIFF_MB=15360
+ENV APP_BUILD=${APP_BUILD}
+ENV GDAL_CONFIG=/usr/bin/gdal-config
+RUN echo "Docker build start: APP_BUILD=${APP_BUILD}" && python -V
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir --disable-pip-version-check --default-timeout=300 -U pip setuptools wheel
+RUN pip install --no-cache-dir --disable-pip-version-check --default-timeout=300 --prefer-binary -r requirements.txt -v
+
+# Pre-download the AdaptFormer model so cold starts are instant
+ENV HF_HOME=/app/.hf_cache
+RUN python -c "from transformers import AutoImageProcessor, AutoModel; \
+    AutoImageProcessor.from_pretrained('deepang/adaptformer-LEVIR-CD', cache_dir='/app/.hf_cache', trust_remote_code=True); \
+    AutoModel.from_pretrained('deepang/adaptformer-LEVIR-CD', cache_dir='/app/.hf_cache', trust_remote_code=True); \
+    print('Model pre-downloaded successfully')"
+
+# Copy application code
+COPY . .
+
+# Create data directories with correct permissions
+RUN mkdir -p data/overlays && chown -R appuser:appuser /app
+
+USER appuser
+
+# HF Spaces generally uses 7860, but binding to $PORT is safer.
+ENV PORT=7860
+EXPOSE 7860
+
+# Bind to runtime PORT so health checks always reach the server.
+CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-7860} --log-level info --timeout-keep-alive 600"]

README.md

@@ -0,0 +1,133 @@
+---
+title: Vedangsoft Change Detection (Dev)
+emoji: 🛰️
+colorFrom: gray
+colorTo: green
+sdk: docker
+app_port: 7860
+---
+
+# Vedangsoft 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
+
+- **Vedangsoft dev UI** — Home, Library, Detection, Reports pages (when `APP_MODE=dda`)
+- **Direct access** — upload and run detection immediately (no login)
+- **Database** — SQLite by default; MySQL in production via `DATABASE_URL` (PostgreSQL also supported); stores detection runs
+- **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
+- **Region polygons** — Engine footprints (`polygon` / `polygonGeo`) in the result overlay + viewer SVG; export via `GET /api/dda/reports/{id}/export.geojson` (bbox/Point fallback for older runs). Verify: `python scripts/verify_polygon_mvp.py`
+
+## Setup (legacy summary)
+
+See **[DEV_SETUP.md](DEV_SETUP.md)** for the complete guide. Minimal steps:
+
+1. **Create a virtual environment (recommended)**
+
+   ```bash
+   cd change_detection_webapp
+   python -m venv venv
+   source venv/bin/activate   # Windows: venv\Scripts\activate
+   ```
+
+2. **Install dependencies**
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Run the app**
+
+   ```bash
+   python run.py
+   # or: uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+   ```
+
+4. Open **http://localhost:8000** in your browser.
+
+## First run
+
+- The DB (SQLite locally, or the configured `DATABASE_URL`) and `data/` (overlay images) are created automatically on first use.
+- **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` to use another DB — MySQL (production for this project): `mysql+pymysql://user:pass@host:3306/db`, or PostgreSQL: `postgresql://user:pass@host/db`. Otherwise SQLite under `data/satellite_app.db` is used.
+- **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
+│   ├── dda/                 # DDA dev modules (library, jobs, reports)
+│   └── detection_engine.py  # Change detection pipeline
+├── static/js/dda/           # DDA frontend
+├── templates/
+│   ├── partials/navbar_dda.html, result_modal_dda.html  # shared includes
+│   ├── home_dda.html, library_dda.html, detect_dda.html,
+│   │   reports_dda.html     # Vedangsoft dev UI pages
+│   ├── login_dda.html, report_dda.html
+│   └── index.html           # legacy (APP_MODE=legacy) UI
+├── library_sources/         # Local GeoTIFF library (year folders)
+├── docs/IMPLEMENTATION_PLAN_DDA.md
+├── DEV_SETUP.md             # Colleague setup guide
+├── requirements.txt
+└── run.py                   # Local launcher (APP_MODE=dda)
+```
+
+## API (Vedangsoft highlights)
+
+- `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”
+
+1. Open your Space → **Settings** → under **Build**, click **Clear build cache** → Save. Then trigger a rebuild (push a commit or click **Restart**).
+2. Check **Logs** (Build logs + App logs) for Python errors or “Killed” (out of memory).
+3. In **Settings** → **Hardware**, try a slightly larger CPU/memory if available.

WORKFLOW.md

@@ -0,0 +1,371 @@
+# 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
+
+```mermaid
+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`](app/detection_engine.py).
+
+```mermaid
+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`](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)
+
+```mermaid
+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`](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`](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`](templates/index.html) is the shell: login/register forms, the
+  upload form, history table, and the result modal.
+- [`static/js/app.js`](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`](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)
+
+```bash
+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)
+
+```bash
+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
+
+```bash
+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`](app/main.py) — see the routes, especially `POST /api/detect`.
+2. [`app/detection_engine.py`](app/detection_engine.py) — start at `run_detection()` at the
+   bottom and follow the calls upward.
+3. [`app/model_inference.py`](app/model_inference.py) — how the DL model is loaded and run.
+4. [`static/js/app.js`](static/js/app.js) — how the frontend calls the API and renders results.
+
+Welcome to the project!

app/__init__.py

@@ -0,0 +1 @@
+# Satellite Change Detection Web App

app/auth.py

@@ -0,0 +1,456 @@
+import hashlib
+import logging
+import os
+import re
+import secrets
+from datetime import datetime, timedelta, timezone
+from typing import Optional, Tuple
+
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+from fastapi import Depends, Request
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from sqlalchemy.orm import Session
+
+from .database import get_db
+from .models import User, LoginHistory, PasswordResetToken, LoginOtp
+
+logger = logging.getLogger(__name__)
+
+_env_secret = os.environ.get("SECRET_KEY", "").strip()
+if _env_secret:
+    SECRET_KEY = _env_secret
+else:
+    # Never fall back to a fixed/shared string here — a hardcoded value in
+    # source is visible to anyone with the repo, and could be used to forge a
+    # valid login cookie for any user id without ever knowing a password.
+    # A fresh random secret per process closes that hole; the trade-off is
+    # every existing session is invalidated on each restart until a
+    # persistent SECRET_KEY is set in the environment (see .env.example).
+    SECRET_KEY = secrets.token_hex(32)
+    logger.warning(
+        "SECRET_KEY env var not set — generated a random one-time secret for "
+        "this process (existing sessions will be invalidated on restart). "
+        "Set SECRET_KEY to a persistent random string in your environment, "
+        "especially in production — see .env.example."
+    )
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = 60 * 24 * 7  # 7 days
+COOKIE_NAME = "satellite_token"
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+security = HTTPBearer(auto_error=False)
+
+# Brute-force lockout thresholds. IP-based is the primary defense (an attacker
+# can't lock out a legitimate user just by failing their password from
+# elsewhere); account-based is secondary. Both env-configurable.
+LOGIN_IP_MAX_FAILURES = int(os.environ.get("LOGIN_IP_MAX_FAILURES", "20"))
+LOGIN_IP_WINDOW_MINUTES = int(os.environ.get("LOGIN_IP_WINDOW_MINUTES", "15"))
+LOGIN_ACCOUNT_MAX_FAILURES = int(os.environ.get("LOGIN_ACCOUNT_MAX_FAILURES", "5"))
+LOGIN_ACCOUNT_WINDOW_MINUTES = int(os.environ.get("LOGIN_ACCOUNT_WINDOW_MINUTES", "15"))
+
+_COOKIE_SECURE_ENV = os.environ.get("COOKIE_SECURE", "").strip().lower()
+if _COOKIE_SECURE_ENV in ("1", "true", "yes"):
+    IS_SECURE_COOKIE = True
+elif _COOKIE_SECURE_ENV in ("0", "false", "no"):
+    IS_SECURE_COOKIE = False
+else:
+    # Render sets RENDER=true on its platform (genuine HTTPS hosting).
+    # Deliberately NOT keying off SPACE_ID: this project's own .env sets
+    # SPACE_ID=local-dev/satdetect-dev for *local* HTTP dev (to force
+    # "hosted" UI behavior, unrelated to HTTPS), so treating any SPACE_ID as
+    # "we're on HTTPS" would wrongly mark local dev secure and silently drop
+    # the auth cookie (verified via smoke test — this was the actual bug).
+    # A genuine Hugging Face Spaces deployment should set COOKIE_SECURE=true
+    # explicitly via the branch above.
+    IS_SECURE_COOKIE = bool(os.environ.get("RENDER"))
+
+
+def get_client_ip(request: Request) -> str:
+    """Real client IP behind Render's proxy (no --proxy-headers on uvicorn, so
+    request.client.host would otherwise report the proxy's IP, not the visitor's)."""
+    xff = request.headers.get("x-forwarded-for", "")
+    if xff:
+        return xff.split(",")[0].strip()
+    return request.client.host if request.client else ""
+
+
+def get_user_agent(request: Request) -> str:
+    return request.headers.get("user-agent", "")[:512]
+
+
+def check_ip_throttle(db: Session, ip: str) -> bool:
+    """True if this IP has too many recent failed login attempts."""
+    if not ip:
+        return False
+    cutoff = datetime.now(timezone.utc) - timedelta(minutes=LOGIN_IP_WINDOW_MINUTES)
+    count = (
+        db.query(LoginHistory)
+        .filter(
+            LoginHistory.ip_address == ip,
+            LoginHistory.event_type == "login_failed",
+            LoginHistory.created_at >= cutoff,
+        )
+        .count()
+    )
+    return count >= LOGIN_IP_MAX_FAILURES
+
+
+def check_account_lockout(db: Session, email: str) -> bool:
+    """True if this email has too many recent failed login attempts."""
+    if not email:
+        return False
+    cutoff = datetime.now(timezone.utc) - timedelta(minutes=LOGIN_ACCOUNT_WINDOW_MINUTES)
+    count = (
+        db.query(LoginHistory)
+        .filter(
+            LoginHistory.attempted_email == email,
+            LoginHistory.event_type == "login_failed",
+            LoginHistory.created_at >= cutoff,
+        )
+        .count()
+    )
+    return count >= LOGIN_ACCOUNT_MAX_FAILURES
+
+
+def _login_event_role(db: Session, user_id: Optional[int]) -> str:
+    """Best-effort role lookup for the audit trail — mirrors the fallback in
+    app/dda/dda_auth.py::get_user_role, but avoids importing that module here
+    (it imports back from this one)."""
+    if not user_id:
+        return ""
+    try:
+        from sqlalchemy import text as sa_text
+        row = db.execute(sa_text("SELECT role FROM users WHERE id = :uid"), {"uid": user_id}).fetchone()
+        return str(row[0]) if row and row[0] else ""
+    except Exception:
+        return ""
+
+
+def record_login_event(
+    db: Session,
+    *,
+    event_type: str,
+    attempted_email: str,
+    user_id: Optional[int] = None,
+    failure_reason: Optional[str] = None,
+    ip_address: str = "",
+    user_agent: str = "",
+) -> None:
+    entry = LoginHistory(
+        user_id=user_id,
+        attempted_email=attempted_email,
+        event_type=event_type,
+        failure_reason=failure_reason,
+        ip_address=ip_address,
+        user_agent=user_agent,
+    )
+    db.add(entry)
+    try:
+        from .dda.tree.audit_service import log_action
+        log_action(
+            db, event_type,
+            action_by=attempted_email,
+            role=_login_event_role(db, user_id),
+            module="auth",
+            new_value={"failure_reason": failure_reason, "ip_address": ip_address} if failure_reason else None,
+        )
+    except Exception:
+        pass
+    db.commit()
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def get_password_hash(password: str) -> str:
+    return pwd_context.hash(password)
+
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
+    to_encode = data.copy()
+    expire = datetime.now(timezone.utc) + (expires_delta or timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES))
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+
+
+PASSWORD_RESET_TOKEN_EXPIRE_MINUTES = 30
+
+
+def _hash_reset_token(raw_token: str) -> str:
+    return hashlib.sha256(raw_token.encode()).hexdigest()
+
+
+def create_password_reset_token(db: Session, user: User) -> str:
+    """Issue a fresh one-time reset token for `user`, invalidating any
+    previous unused ones (so an old, possibly-leaked link can't still work
+    once a new reset was requested). Returns the raw token — only the caller
+    (the emailed link) ever sees it; the DB only keeps its hash."""
+    db.query(PasswordResetToken).filter(
+        PasswordResetToken.user_id == user.id,
+        PasswordResetToken.used_at.is_(None),
+    ).delete(synchronize_session=False)
+
+    raw_token = secrets.token_urlsafe(32)
+    db.add(PasswordResetToken(
+        user_id=user.id,
+        token_hash=_hash_reset_token(raw_token),
+        expires_at=datetime.now(timezone.utc) + timedelta(minutes=PASSWORD_RESET_TOKEN_EXPIRE_MINUTES),
+    ))
+    db.commit()
+    return raw_token
+
+
+def consume_password_reset_token(db: Session, raw_token: str) -> Optional[User]:
+    """Validate + burn a reset token in one step (single use). The expiry
+    comparison is done in the SQL filter, not in Python, so it's never
+    exposed to naive/aware datetime mismatches from what the DB driver hands
+    back for a stored DATETIME column."""
+    if not raw_token:
+        return None
+    now = datetime.now(timezone.utc)
+    entry = (
+        db.query(PasswordResetToken)
+        .filter(
+            PasswordResetToken.token_hash == _hash_reset_token(raw_token),
+            PasswordResetToken.used_at.is_(None),
+            PasswordResetToken.expires_at >= now,
+        )
+        .first()
+    )
+    if not entry:
+        return None
+    entry.used_at = now
+    db.commit()
+    return get_user_by_id(db, entry.user_id)
+
+
+def get_user_by_email(db: Session, email: str) -> Optional[User]:
+    """Case-insensitive email lookup with whitespace stripped.
+
+    Emails are supposed to be stored lowercase (see register()), but a) users
+    typing them in login forms may leave stray whitespace or capitalisation,
+    and b) older accounts predating the .lower() normalisation may still be
+    mixed-case. Using LOWER()/TRIM() on both sides avoids the case where the
+    same email is treated as "already exists" by one route and "not found" by
+    another.
+    """
+    if not email:
+        return None
+    from sqlalchemy import func
+    normalised = email.strip().lower()
+    return (
+        db.query(User)
+        .filter(func.lower(func.trim(User.email)) == normalised)
+        .first()
+    )
+
+
+def get_user_by_phone(db: Session, phone: str) -> Optional[User]:
+    if not phone:
+        return None
+    return db.query(User).filter(User.phone == phone).first()
+
+
+def get_user_by_id(db: Session, user_id: int) -> Optional[User]:
+    return db.query(User).filter(User.id == user_id).first()
+
+
+def normalize_phone(raw: str, country_code: Optional[str] = None) -> Optional[str]:
+    """Return the number as E.164 ("+CCXXXXXXXX"), or None if invalid.
+
+    Accepts either a raw string that already starts with '+', or a local
+    number plus a separate country dial code. India-specific rules (mobile
+    prefix must be 6-9, exactly 10 digits) are applied when the country
+    dial code resolves to '+91'; every other country is checked only for
+    total length (7–15 digits per the E.164 spec).
+    """
+    raw = (raw or "").strip()
+    cc = (country_code or "").strip()
+    if raw.startswith("+"):
+        digits = re.sub(r"\D", "", raw)
+        e164_country = ""
+        if not cc:
+            for dial in ("91", "1", "44", "61", "971", "65", "880", "94", "977", "92"):
+                if digits.startswith(dial):
+                    e164_country = "+" + dial
+                    break
+        else:
+            e164_country = "+" + re.sub(r"\D", "", cc)
+            if not digits.startswith(e164_country[1:]):
+                return None
+        local = digits[len(e164_country) - 1:] if e164_country else digits
+    else:
+        if not cc:
+            cc = "+91"
+        e164_country = "+" + re.sub(r"\D", "", cc)
+        local = re.sub(r"\D", "", raw)
+        if local.startswith(e164_country[1:]) and len(local) > 10:
+            local = local[len(e164_country) - 1:]
+    if not e164_country.startswith("+") or len(e164_country) < 2:
+        return None
+    if not local.isdigit():
+        return None
+    total = e164_country[1:] + local
+    if not (7 <= len(total) <= 15):
+        return None
+    if e164_country == "+91" and (len(local) != 10 or local[0] not in "6789"):
+        return None
+    return e164_country + local
+
+
+def mask_phone(phone: str) -> str:
+    """Mask an E.164 number for display: '+91******3210'."""
+    p = (phone or "").strip()
+    if not p:
+        return "******"
+    if p.startswith("+"):
+        digits = re.sub(r"\D", "", p)
+        if len(digits) <= 4:
+            return "+" + digits
+        for dial in ("91", "1", "44", "61", "971", "65", "880", "94", "977", "92"):
+            if digits.startswith(dial) and len(digits) > len(dial) + 3:
+                local = digits[len(dial):]
+                return f"+{dial}{'*' * max(0, len(local) - 4)}{local[-4:]}"
+        return "+" + "*" * max(0, len(digits) - 4) + digits[-4:]
+    digits = re.sub(r"\D", "", p)
+    if len(digits) < 4:
+        return "******"
+    return f"******{digits[-4:]}"
+
+
+def get_user_from_token(token: str, db: Session, *, allow_pending_otp: bool = False) -> Optional[User]:
+    """Resolve user from JWT token.
+
+    Tokens issued after password-check, before SMS OTP, carry
+    purpose=otp_pending and must not grant a session by themselves.
+    """
+    if not token:
+        return None
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        purpose = payload.get("purpose") or "session"
+        if purpose == "otp_pending" and not allow_pending_otp:
+            return None
+        if purpose not in ("session", "otp_pending"):
+            return None
+        user_id_str = payload.get("sub")
+        if user_id_str is None:
+            return None
+        try:
+            user_id = int(user_id_str)
+        except (ValueError, TypeError):
+            logger.warning("JWT 'sub' claim is not a valid integer")
+            return None
+    except JWTError:
+        return None
+    return get_user_by_id(db, user_id)
+
+
+LOGIN_OTP_EXPIRE_MINUTES = 10
+LOGIN_OTP_MAX_ATTEMPTS = 5
+LOGIN_OTP_RESEND_SECONDS = 45
+
+
+def _hash_otp(code: str) -> str:
+    return hashlib.sha256(code.encode()).hexdigest()
+
+
+def mask_email(email: str) -> str:
+    local, _, domain = (email or "").partition("@")
+    if not domain:
+        return "***"
+    shown = (local[:1] + "***") if len(local) <= 2 else (local[:2] + "***")
+    return f"{shown}@{domain}"
+
+
+def create_login_otp(db: Session, user: User) -> Tuple[LoginOtp, str]:
+    """Issue a fresh 6-digit email OTP, invalidating unused ones for this user."""
+    db.query(LoginOtp).filter(
+        LoginOtp.user_id == user.id,
+        LoginOtp.used_at.is_(None),
+    ).delete(synchronize_session=False)
+    raw = f"{secrets.randbelow(1_000_000):06d}"
+    row = LoginOtp(
+        user_id=user.id,
+        code_hash=_hash_otp(raw),
+        expires_at=datetime.now(timezone.utc) + timedelta(minutes=LOGIN_OTP_EXPIRE_MINUTES),
+        attempts=0,
+    )
+    db.add(row)
+    db.commit()
+    db.refresh(row)
+    return row, raw
+
+
+def latest_unused_otp(db: Session, user_id: int) -> Optional[LoginOtp]:
+    return (
+        db.query(LoginOtp)
+        .filter(LoginOtp.user_id == user_id, LoginOtp.used_at.is_(None))
+        .order_by(LoginOtp.id.desc())
+        .first()
+    )
+
+
+def verify_login_otp(db: Session, user: User, otp_id: int, code: str) -> str:
+    """Return '' if valid; otherwise a short error token for the caller to map."""
+    cleaned = (code or "").strip().replace(" ", "")
+    now = datetime.now(timezone.utc)
+    row = (
+        db.query(LoginOtp)
+        .filter(
+            LoginOtp.id == otp_id,
+            LoginOtp.user_id == user.id,
+            LoginOtp.used_at.is_(None),
+        )
+        .first()
+    )
+    if not row:
+        return "expired"
+    exp = row.expires_at
+    if exp.tzinfo is None:
+        exp = exp.replace(tzinfo=timezone.utc)
+    if exp < now:
+        return "expired"
+    if (row.attempts or 0) >= LOGIN_OTP_MAX_ATTEMPTS:
+        return "locked"
+    if not cleaned.isdigit() or len(cleaned) != 6 or row.code_hash != _hash_otp(cleaned):
+        row.attempts = (row.attempts or 0) + 1
+        db.commit()
+        return "invalid"
+    row.used_at = now
+    db.commit()
+    return ""
+
+
+def get_or_create_guest_user(db: Session) -> User:
+    """Shared anonymous account when login is disabled."""
+    guest_email = "__guest__@system.local"
+    user = get_user_by_email(db, guest_email)
+    if user:
+        return user
+    user = User(
+        email=guest_email,
+        hashed_password=get_password_hash("guest-not-used"),
+        full_name="Guest",
+    )
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+    return user
+
+
+def get_current_user(
+    request: Request,
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
+    db: Session = Depends(get_db),
+) -> Optional[User]:
+    if credentials:
+        user = get_user_from_token(credentials.credentials, db)
+        if user:
+            return user
+    token = request.cookies.get(COOKIE_NAME)
+    if token:
+        return get_user_from_token(token, db)
+    return None

app/cd_models/bit_cd.py

@@ -0,0 +1,386 @@
+"""BIT_CD: Bitemporal Image Transformer for change detection (vendored).
+
+Self-contained port of the ``base_transformer_pos_s4_dd8_dedim8`` network from
+https://github.com/justchenhao/BIT_CD (Chen et al., "Remote Sensing Image
+Change Detection with Transformers", TGRS 2021), rewritten without the einops
+dependency and using the torchvision ResNet18 backbone.
+
+Weights are NOT bundled. Place a LEVIR-CD checkpoint at
+``app/cd_models/weights/bit_cd_levir.pth`` (or point ``BIT_CD_WEIGHTS`` at it).
+Both the raw training checkpoint (``model_G_state_dict`` key, from the
+official repo's best_ckpt.pt) and a plain converted state_dict are accepted.
+
+Used by ``model_inference`` as an optional second model ensembled with
+AdaptFormer when ``DETECTION_ENSEMBLE=on``.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+_BIT_MODEL = None
+_BIT_DEVICE = None
+_BIT_FAILED = False
+
+WEIGHTS_DIR = Path(__file__).resolve().parent / "weights"
+DEFAULT_WEIGHTS = WEIGHTS_DIR / "bit_cd_levir.pth"
+TILE_SIZE = 256  # LEVIR-CD native patch size
+
+
+def weights_path() -> Path:
+    env = os.environ.get("BIT_CD_WEIGHTS", "").strip()
+    return Path(env) if env else DEFAULT_WEIGHTS
+
+
+def weights_available() -> bool:
+    p = weights_path()
+    return p.is_file() and p.stat().st_size > 1_000_000
+
+
+def _build_modules():
+    import torch
+    from torch import nn
+
+    class TwoLayerConv2d(nn.Sequential):
+        def __init__(self, in_channels, out_channels, kernel_size=3):
+            super().__init__(
+                nn.Conv2d(in_channels, in_channels, kernel_size=kernel_size,
+                          padding=kernel_size // 2, stride=1, bias=False),
+                nn.BatchNorm2d(in_channels),
+                nn.ReLU(),
+                nn.Conv2d(in_channels, out_channels, kernel_size=kernel_size,
+                          padding=kernel_size // 2, stride=1),
+            )
+
+    class Residual(nn.Module):
+        def __init__(self, fn):
+            super().__init__()
+            self.fn = fn
+
+        def forward(self, x, **kw):
+            return self.fn(x, **kw) + x
+
+    class Residual2(nn.Module):
+        def __init__(self, fn):
+            super().__init__()
+            self.fn = fn
+
+        def forward(self, x, m, **kw):
+            return self.fn(x, m, **kw) + x
+
+    class PreNorm(nn.Module):
+        def __init__(self, dim, fn):
+            super().__init__()
+            self.norm = nn.LayerNorm(dim)
+            self.fn = fn
+
+        def forward(self, x, **kw):
+            return self.fn(self.norm(x), **kw)
+
+    class PreNorm2(nn.Module):
+        def __init__(self, dim, fn):
+            super().__init__()
+            self.norm = nn.LayerNorm(dim)
+            self.fn = fn
+
+        def forward(self, x, m, **kw):
+            return self.fn(self.norm(x), self.norm(m), **kw)
+
+    class FeedForward(nn.Module):
+        def __init__(self, dim, hidden_dim):
+            super().__init__()
+            self.net = nn.Sequential(
+                nn.Linear(dim, hidden_dim), nn.GELU(), nn.Dropout(0.0),
+                nn.Linear(hidden_dim, dim), nn.Dropout(0.0),
+            )
+
+        def forward(self, x):
+            return self.net(x)
+
+    def _split_heads(t, heads):
+        b, n, hd = t.shape
+        d = hd // heads
+        return t.view(b, n, heads, d).permute(0, 2, 1, 3)
+
+    def _merge_heads(t):
+        b, h, n, d = t.shape
+        return t.permute(0, 2, 1, 3).reshape(b, n, h * d)
+
+    class Attention(nn.Module):
+        def __init__(self, dim, heads=8, dim_head=64):
+            super().__init__()
+            inner = dim_head * heads
+            self.heads = heads
+            self.scale = dim ** -0.5
+            self.to_qkv = nn.Linear(dim, inner * 3, bias=False)
+            self.to_out = nn.Sequential(nn.Linear(inner, dim), nn.Dropout(0.0))
+
+        def forward(self, x):
+            q, k, v = self.to_qkv(x).chunk(3, dim=-1)
+            q, k, v = (_split_heads(t, self.heads) for t in (q, k, v))
+            attn = (q @ k.transpose(-1, -2) * self.scale).softmax(dim=-1)
+            return self.to_out(_merge_heads(attn @ v))
+
+    class CrossAttention(nn.Module):
+        def __init__(self, dim, heads=8, dim_head=64, softmax=True):
+            super().__init__()
+            inner = dim_head * heads
+            self.heads = heads
+            self.scale = dim ** -0.5
+            self.softmax = softmax
+            self.to_q = nn.Linear(dim, inner, bias=False)
+            self.to_k = nn.Linear(dim, inner, bias=False)
+            self.to_v = nn.Linear(dim, inner, bias=False)
+            self.to_out = nn.Sequential(nn.Linear(inner, dim), nn.Dropout(0.0))
+
+        def forward(self, x, m):
+            q = _split_heads(self.to_q(x), self.heads)
+            k = _split_heads(self.to_k(m), self.heads)
+            v = _split_heads(self.to_v(m), self.heads)
+            dots = q @ k.transpose(-1, -2) * self.scale
+            attn = dots.softmax(dim=-1) if self.softmax else dots
+            return self.to_out(_merge_heads(attn @ v))
+
+    class Transformer(nn.Module):
+        def __init__(self, dim, depth, heads, dim_head, mlp_dim):
+            super().__init__()
+            self.layers = nn.ModuleList([
+                nn.ModuleList([
+                    Residual(PreNorm(dim, Attention(dim, heads, dim_head))),
+                    Residual(PreNorm(dim, FeedForward(dim, mlp_dim))),
+                ]) for _ in range(depth)
+            ])
+
+        def forward(self, x):
+            for attn, ff in self.layers:
+                x = attn(x)
+                x = ff(x)
+            return x
+
+    class TransformerDecoder(nn.Module):
+        def __init__(self, dim, depth, heads, dim_head, mlp_dim, softmax=True):
+            super().__init__()
+            self.layers = nn.ModuleList([
+                nn.ModuleList([
+                    Residual2(PreNorm2(dim, CrossAttention(dim, heads, dim_head, softmax))),
+                    Residual(PreNorm(dim, FeedForward(dim, mlp_dim))),
+                ]) for _ in range(depth)
+            ])
+
+        def forward(self, x, m):
+            for attn, ff in self.layers:
+                x = attn(x, m)
+                x = ff(x)
+            return x
+
+    class DilatedBasicBlock(nn.Module):
+        """torchvision BasicBlock with dilation allowed (as in BIT_CD's resnet)."""
+        expansion = 1
+
+        def __init__(self, inplanes, planes, stride=1, downsample=None, dilation=1):
+            super().__init__()
+            self.conv1 = nn.Conv2d(inplanes, planes, 3, stride=stride,
+                                   padding=dilation, dilation=dilation, bias=False)
+            self.bn1 = nn.BatchNorm2d(planes)
+            self.relu = nn.ReLU(inplace=True)
+            self.conv2 = nn.Conv2d(planes, planes, 3, padding=dilation,
+                                   dilation=dilation, bias=False)
+            self.bn2 = nn.BatchNorm2d(planes)
+            self.downsample = downsample
+
+        def forward(self, x):
+            identity = x
+            out = self.relu(self.bn1(self.conv1(x)))
+            out = self.bn2(self.conv2(out))
+            if self.downsample is not None:
+                identity = self.downsample(x)
+            return self.relu(out + identity)
+
+    class DilatedResNet18(nn.Module):
+        """ResNet18 trunk with replace_stride_with_dilation=[False, True, True].
+
+        Same module naming as torchvision so BIT_CD checkpoints load directly.
+        """
+
+        def __init__(self):
+            super().__init__()
+            self.inplanes = 64
+            self.dilation = 1
+            self.conv1 = nn.Conv2d(3, 64, 7, stride=2, padding=3, bias=False)
+            self.bn1 = nn.BatchNorm2d(64)
+            self.relu = nn.ReLU(inplace=True)
+            self.maxpool = nn.MaxPool2d(kernel_size=3, stride=2, padding=1)
+            # replace_stride_with_dilation=[False, True, True]: layer2 keeps
+            # stride 2; layers 3-4 trade stride for dilation.
+            self.layer1 = self._make_layer(64, 2, stride=1, dilate=False)
+            self.layer2 = self._make_layer(128, 2, stride=2, dilate=False)
+            self.layer3 = self._make_layer(256, 2, stride=2, dilate=True)
+            self.layer4 = self._make_layer(512, 2, stride=2, dilate=True)
+
+        def _make_layer(self, planes, blocks, stride, dilate):
+            downsample = None
+            previous_dilation = self.dilation
+            if dilate:
+                self.dilation *= stride
+                stride = 1
+            if stride != 1 or self.inplanes != planes:
+                downsample = nn.Sequential(
+                    nn.Conv2d(self.inplanes, planes, 1, stride=stride, bias=False),
+                    nn.BatchNorm2d(planes),
+                )
+            layers = [DilatedBasicBlock(self.inplanes, planes, stride,
+                                        downsample, previous_dilation)]
+            self.inplanes = planes
+            for _ in range(1, blocks):
+                layers.append(DilatedBasicBlock(planes, planes, dilation=self.dilation))
+            return nn.Sequential(*layers)
+
+    class BITTransformer(nn.Module):
+        """ResNet18 (4 stages, dilated) + token transformer + difference head."""
+
+        def __init__(self, output_nc=2, token_len=4, enc_depth=1, dec_depth=8,
+                     dim_head=64, decoder_dim_head=8):
+            super().__init__()
+            self.resnet = DilatedResNet18()
+            self.relu = nn.ReLU()
+            self.upsamplex2 = nn.Upsample(scale_factor=2)
+            self.upsamplex4 = nn.Upsample(scale_factor=4, mode="bilinear")
+            self.classifier = TwoLayerConv2d(in_channels=32, out_channels=output_nc)
+            self.conv_pred = nn.Conv2d(256, 32, kernel_size=3, padding=1)
+
+            self.token_len = token_len
+            dim = 32
+            self.conv_a = nn.Conv2d(dim, token_len, kernel_size=1, padding=0, bias=False)
+            self.pos_embedding = nn.Parameter(torch.randn(1, token_len * 2, dim))
+            self.transformer = Transformer(dim, enc_depth, 8, dim_head, 2 * dim)
+            self.transformer_decoder = TransformerDecoder(
+                dim, dec_depth, 8, decoder_dim_head, 2 * dim, softmax=True)
+
+        def forward_single(self, x):
+            x = self.resnet.conv1(x)
+            x = self.resnet.bn1(x)
+            x = self.resnet.relu(x)
+            x = self.resnet.maxpool(x)
+            x = self.resnet.layer1(x)
+            x = self.resnet.layer2(x)
+            x = self.resnet.layer3(x)  # stages_num=4 -> stop before layer4
+            x = self.upsamplex2(x)
+            return self.conv_pred(x)
+
+        def _semantic_tokens(self, x):
+            b, c, h, w = x.shape
+            att = self.conv_a(x).view(b, self.token_len, -1).softmax(dim=-1)
+            flat = x.view(b, c, -1)
+            return torch.einsum("bln,bcn->blc", att, flat)
+
+        def _decode(self, x, m):
+            b, c, h, w = x.shape
+            seq = x.flatten(2).transpose(1, 2)
+            seq = self.transformer_decoder(seq, m)
+            return seq.transpose(1, 2).reshape(b, c, h, w)
+
+        def forward(self, x1, x2):
+            x1 = self.forward_single(x1)
+            x2 = self.forward_single(x2)
+            t1 = self._semantic_tokens(x1)
+            t2 = self._semantic_tokens(x2)
+            tokens = torch.cat([t1, t2], dim=1) + self.pos_embedding
+            tokens = self.transformer(tokens)
+            t1, t2 = tokens.chunk(2, dim=1)
+            x1 = self._decode(x1, t1)
+            x2 = self._decode(x2, t2)
+            x = torch.abs(x1 - x2)
+            x = self.upsamplex4(x)
+            return self.classifier(x)
+
+    return BITTransformer
+
+
+def _extract_state_dict(checkpoint) -> dict:
+    if isinstance(checkpoint, dict):
+        for key in ("model_G_state_dict", "state_dict", "model_state_dict"):
+            if key in checkpoint and isinstance(checkpoint[key], dict):
+                checkpoint = checkpoint[key]
+                break
+    return {k[7:] if k.startswith("module.") else k: v for k, v in checkpoint.items()}
+
+
+def load_bit_model():
+    """Load BIT_CD with LEVIR weights. Returns None when unavailable."""
+    global _BIT_MODEL, _BIT_DEVICE, _BIT_FAILED
+    if _BIT_MODEL is not None:
+        return _BIT_MODEL
+    if _BIT_FAILED or not weights_available():
+        return None
+    try:
+        import torch
+
+        BITTransformer = _build_modules()
+        model = BITTransformer()
+        checkpoint = torch.load(weights_path(), map_location="cpu", weights_only=False)
+        state = _extract_state_dict(checkpoint)
+        missing, unexpected = model.load_state_dict(state, strict=False)
+        real_missing = [k for k in missing if "num_batches_tracked" not in k]
+        if len(real_missing) > 20:
+            raise RuntimeError(
+                f"checkpoint mismatch: {len(real_missing)} missing keys "
+                f"(e.g. {real_missing[:4]}), {len(unexpected)} unexpected")
+        if real_missing or unexpected:
+            logger.warning("BIT_CD loaded with %d missing / %d unexpected keys",
+                           len(real_missing), len(unexpected))
+        _BIT_DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        model.to(_BIT_DEVICE)
+        model.eval()
+        _BIT_MODEL = model
+        logger.info("BIT_CD loaded from %s on %s", weights_path(), _BIT_DEVICE)
+        return _BIT_MODEL
+    except Exception as exc:
+        _BIT_FAILED = True
+        logger.error("BIT_CD load failed: %s", exc)
+        return None
+
+
+def bit_score_map(img1: np.ndarray, img2: np.ndarray) -> Optional[np.ndarray]:
+    """Tiled BIT_CD change probability map in [0,1] at (h, w), or None."""
+    model = load_bit_model()
+    if model is None:
+        return None
+    try:
+        import torch
+
+        from .model_utils import tiled_score_map
+
+        # ImageNet-style normalization matching the BIT_CD training transforms
+        mean = np.array([0.5, 0.5, 0.5], dtype=np.float32)
+        std = np.array([0.5, 0.5, 0.5], dtype=np.float32)
+
+        def _to_tensor(arr):
+            t = (arr.astype(np.float32) / 255.0 - mean) / std
+            return torch.from_numpy(t.transpose(2, 0, 1)).unsqueeze(0).to(_BIT_DEVICE)
+
+        def _score_tile(t1, t2):
+            with torch.no_grad():
+                logits = model(_to_tensor(t1), _to_tensor(t2))
+                prob = torch.softmax(logits, dim=1)[0, 1]
+            return prob.cpu().numpy().astype(np.float32)
+
+        return tiled_score_map(_score_tile, img1, img2,
+                               tile_size=TILE_SIZE, overlap=TILE_SIZE // 4)
+    except Exception as exc:
+        logger.warning("BIT_CD scoring failed: %s", exc)
+        return None
+
+
+def bit_status() -> dict:
+    return {
+        "weightsPath": str(weights_path()),
+        "weightsAvailable": weights_available(),
+        "loaded": _BIT_MODEL is not None,
+        "loadFailed": _BIT_FAILED,
+    }

app/cd_models/change_model.py

@@ -0,0 +1,211 @@
+"""
+Siamese U-Net for satellite change detection.
+
+A lightweight Siamese encoder shares weights between before/after images,
+fuses features via concatenation + difference, and decodes into a binary
+change probability map.
+
+Designed for CPU inference (< 2s per 256x256 tile).
+"""
+import logging
+import os
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+_MODEL = None
+_DEVICE = None
+_AVAILABLE = None
+_WEIGHTS_DIR = Path(__file__).parent / "weights"
+_WEIGHTS_FILE = _WEIGHTS_DIR / "siamese_unet_cd.pt"
+
+
+def _try_torch():
+    try:
+        import torch
+        import torch.nn as nn
+        return torch, nn
+    except ImportError:
+        return None, None
+
+
+# ---------------------------------------------------------------------------
+# Model architecture
+# ---------------------------------------------------------------------------
+
+def _build_model():
+    torch, nn = _try_torch()
+    if torch is None:
+        return None
+
+    class ConvBlock(nn.Module):
+        def __init__(self, in_ch, out_ch):
+            super().__init__()
+            self.block = nn.Sequential(
+                nn.Conv2d(in_ch, out_ch, 3, padding=1, bias=False),
+                nn.BatchNorm2d(out_ch),
+                nn.ReLU(inplace=True),
+                nn.Conv2d(out_ch, out_ch, 3, padding=1, bias=False),
+                nn.BatchNorm2d(out_ch),
+                nn.ReLU(inplace=True),
+            )
+        def forward(self, x):
+            return self.block(x)
+
+    class Encoder(nn.Module):
+        def __init__(self, in_ch=3, base=32):
+            super().__init__()
+            self.enc1 = ConvBlock(in_ch, base)
+            self.enc2 = ConvBlock(base, base * 2)
+            self.enc3 = ConvBlock(base * 2, base * 4)
+            self.enc4 = ConvBlock(base * 4, base * 8)
+            self.pool = nn.MaxPool2d(2)
+
+        def forward(self, x):
+            e1 = self.enc1(x)
+            e2 = self.enc2(self.pool(e1))
+            e3 = self.enc3(self.pool(e2))
+            e4 = self.enc4(self.pool(e3))
+            return [e1, e2, e3, e4]
+
+    class SiameseUNet(nn.Module):
+        """
+        Siamese U-Net: shared encoder processes before/after images independently.
+        Decoder fuses features via concatenation of both streams + their absolute
+        difference, providing the decoder with explicit change information.
+        """
+        def __init__(self, in_ch=3, base=32, out_ch=2):
+            super().__init__()
+            self.encoder = Encoder(in_ch, base)
+            b = base
+
+            # Decoder: at each level receives [enc_a, enc_b, |enc_a-enc_b|] = 3x channels
+            self.up4 = nn.ConvTranspose2d(b * 8, b * 4, 2, stride=2)
+            self.dec4 = ConvBlock(b * 4 + b * 4 * 3, b * 4)
+
+            self.up3 = nn.ConvTranspose2d(b * 4, b * 2, 2, stride=2)
+            self.dec3 = ConvBlock(b * 2 + b * 2 * 3, b * 2)
+
+            self.up2 = nn.ConvTranspose2d(b * 2, b, 2, stride=2)
+            self.dec2 = ConvBlock(b + b * 3, b)
+
+            self.head = nn.Conv2d(b, out_ch, 1)
+
+        def forward(self, img_a, img_b):
+            feats_a = self.encoder(img_a)
+            feats_b = self.encoder(img_b)
+
+            # Bottleneck: fuse deepest features
+            bot = torch.cat([feats_a[3], feats_b[3], torch.abs(feats_a[3] - feats_b[3])], dim=1)
+
+            import torch.nn.functional as F
+            # Level 3
+            d4 = self.up4(feats_a[3])
+            skip3 = torch.cat([feats_a[2], feats_b[2], torch.abs(feats_a[2] - feats_b[2])], dim=1)
+            d4 = self.dec4(torch.cat([d4, skip3], dim=1))
+
+            # Level 2
+            d3 = self.up3(d4)
+            skip2 = torch.cat([feats_a[1], feats_b[1], torch.abs(feats_a[1] - feats_b[1])], dim=1)
+            d3 = self.dec3(torch.cat([d3, skip2], dim=1))
+
+            # Level 1
+            d2 = self.up2(d3)
+            skip1 = torch.cat([feats_a[0], feats_b[0], torch.abs(feats_a[0] - feats_b[0])], dim=1)
+            d2 = self.dec2(torch.cat([d2, skip1], dim=1))
+
+            return self.head(d2)
+
+    return SiameseUNet
+
+
+# ---------------------------------------------------------------------------
+# Model loading (singleton)
+# ---------------------------------------------------------------------------
+
+def has_siamese_weights():
+    """True only when a trained weights file is present."""
+    return _WEIGHTS_FILE.is_file()
+
+
+def is_siamese_available():
+    """PyTorch installed and pretrained weights available."""
+    global _AVAILABLE
+    if _AVAILABLE is not None:
+        return _AVAILABLE
+    torch, _ = _try_torch()
+    _AVAILABLE = torch is not None and has_siamese_weights()
+    return _AVAILABLE
+
+
+def _load_siamese():
+    global _MODEL, _DEVICE
+    if _MODEL is not None:
+        return _MODEL
+
+    torch, _ = _try_torch()
+    if torch is None:
+        raise RuntimeError("PyTorch not installed")
+
+    _DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+    ModelClass = _build_model()
+    model = ModelClass(in_ch=3, base=32, out_ch=2)
+
+    if _WEIGHTS_FILE.exists():
+        logger.info("Loading Siamese U-Net weights from %s", _WEIGHTS_FILE)
+        state = torch.load(str(_WEIGHTS_FILE), map_location=_DEVICE, weights_only=True)
+        model.load_state_dict(state)
+    else:
+        logger.info("No pretrained weights found at %s — using random init "
+                     "(model will still produce change maps but accuracy depends on "
+                     "classical fusion weighting)", _WEIGHTS_FILE)
+
+    model.to(_DEVICE)
+    model.eval()
+    _MODEL = model
+    return _MODEL
+
+
+# ---------------------------------------------------------------------------
+# Inference
+# ---------------------------------------------------------------------------
+
+_TILE = 256
+
+
+def predict_siamese(img1, img2, threshold=0.5):
+    """
+    Run Siamese U-Net inference on two RGB uint8 arrays.
+    Tile-based with overlap stitching (same pattern as AdaptFormer).
+    Returns (uint8 mask [0|255], float32 probability map [0-1]).
+    """
+    torch, _ = _try_torch()
+    model = _load_siamese()
+
+    if img1.shape != img2.shape:
+        img2 = cv2.resize(img2, (img1.shape[1], img1.shape[0]))
+
+    from .model_utils import tiled_score_map
+
+    mean = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+    std = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+
+    def _score_tile(t1, t2):
+        n1 = (t1.astype(np.float32) / 255.0 - mean) / std
+        n2 = (t2.astype(np.float32) / 255.0 - mean) / std
+        ta = torch.from_numpy(n1.transpose(2, 0, 1)).unsqueeze(0).to(_DEVICE)
+        tb = torch.from_numpy(n2.transpose(2, 0, 1)).unsqueeze(0).to(_DEVICE)
+        logits = model(ta, tb)
+        probs = torch.softmax(logits, dim=1)
+        return probs[0, 1].cpu().numpy()
+
+    with torch.no_grad():
+        avg = tiled_score_map(_score_tile, img1, img2,
+                              tile_size=_TILE, overlap=_TILE // 4)
+
+    mask = (avg >= threshold).astype(np.uint8) * 255
+    return mask, avg

app/cd_models/irmad.py

@@ -0,0 +1,212 @@
+"""IR-MAD: Iteratively Reweighted Multivariate Alteration Detection.
+
+Classical unsupervised change detection statistic (Nielsen 2007), listed among
+the strongest traditional methods in the Change-Detection-Review repository
+(https://github.com/MinZHANG-WHU/Change-Detection-Review).
+
+MAD finds paired linear combinations of the two images' bands (via canonical
+correlation analysis) whose differences maximally decorrelate; the chi-square
+sum of squared standardized MAD variates measures change. The IR step
+re-estimates the statistics using no-change weights so genuine changes don't
+bias the transform, sharpening separation between change and no-change.
+
+Pure numpy — no extra dependencies. Runs on a bounded-resolution copy for CPU
+practicality and returns both the change probability map and the final
+no-change weights (useful for regression-based radiometric normalization).
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+import cv2
+import numpy as np
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass
+class IRMADResult:
+    chi2: np.ndarray        # float32, raw chi-square statistic (analysis res)
+    change_prob: np.ndarray  # float32 [0,1], at the input resolution
+    no_change_weights: np.ndarray  # float32 [0,1], at the input resolution
+    iterations: int
+    converged: bool
+
+
+def _weighted_stats(x: np.ndarray, y: np.ndarray, w: np.ndarray):
+    """Weighted means and joint covariance of two multiband pixel matrices."""
+    wsum = float(np.sum(w)) + 1e-12
+    mx = (x * w[:, None]).sum(axis=0) / wsum
+    my = (y * w[:, None]).sum(axis=0) / wsum
+    xc = x - mx
+    yc = y - my
+    sxx = (xc * w[:, None]).T @ xc / wsum
+    syy = (yc * w[:, None]).T @ yc / wsum
+    sxy = (xc * w[:, None]).T @ yc / wsum
+    return mx, my, sxx, syy, sxy, xc, yc
+
+
+def _chi2_cdf(x: np.ndarray, k: int) -> np.ndarray:
+    """Chi-square CDF via the regularized lower incomplete gamma function."""
+    try:
+        from scipy.special import gammainc
+        return gammainc(k / 2.0, x / 2.0)
+    except Exception:
+        # Wilson–Hilferty normal approximation (good for k>=3)
+        z = ((x / k) ** (1.0 / 3.0) - (1 - 2.0 / (9 * k))) / np.sqrt(2.0 / (9 * k))
+        return 0.5 * (1.0 + np.tanh(z * 0.79788456 * (1 + 0.044715 * z * z)))
+
+
+def compute_irmad(
+    img1: np.ndarray,
+    img2: np.ndarray,
+    *,
+    max_iters: int = 10,
+    tol: float = 1e-3,
+    max_side: int = 1024,
+    eps: float = 1e-6,
+) -> Optional[IRMADResult]:
+    """Run IR-MAD on an RGB pair. Returns None on numerical failure."""
+    try:
+        if img1.shape != img2.shape or img1.ndim != 3:
+            return None
+        full_h, full_w = img1.shape[:2]
+
+        scale = min(1.0, max_side / max(full_h, full_w))
+        if scale < 1.0:
+            ah, aw = max(64, int(full_h * scale)), max(64, int(full_w * scale))
+            a = cv2.resize(img1, (aw, ah), interpolation=cv2.INTER_AREA)
+            b = cv2.resize(img2, (aw, ah), interpolation=cv2.INTER_AREA)
+        else:
+            ah, aw = full_h, full_w
+            a, b = img1, img2
+
+        bands = a.shape[2]
+        x = a.reshape(-1, bands).astype(np.float64)
+        y = b.reshape(-1, bands).astype(np.float64)
+        n = x.shape[0]
+        w = np.ones(n, dtype=np.float64)
+
+        rho_prev = None
+        converged = False
+        it = 0
+        mads_std = np.zeros_like(x)
+
+        for it in range(1, max_iters + 1):
+            _, _, sxx, syy, sxy, xc, yc = _weighted_stats(x, y, w)
+            sxx += eps * np.eye(bands)
+            syy += eps * np.eye(bands)
+
+            # CCA via generalized eigenproblem on sxx^-1 sxy syy^-1 syx
+            isxx = np.linalg.inv(sxx)
+            isyy = np.linalg.inv(syy)
+            m1 = isxx @ sxy @ isyy @ sxy.T
+            evals, evecs = np.linalg.eig(m1)
+            order = np.argsort(evals.real)[::-1]
+            rho2 = np.clip(evals.real[order], 0.0, 1.0)
+            avecs = evecs.real[:, order]
+
+            # Normalize canonical vectors: var(a^T x) = 1
+            for j in range(bands):
+                va = avecs[:, j] @ sxx @ avecs[:, j]
+                avecs[:, j] /= np.sqrt(max(va, eps))
+            bvecs = isyy @ sxy.T @ avecs
+            for j in range(bands):
+                vb = bvecs[:, j] @ syy @ bvecs[:, j]
+                bvecs[:, j] /= np.sqrt(max(vb, eps))
+
+            u = xc @ avecs
+            v = yc @ bvecs
+            # Sign alignment: positive correlation between pairs
+            for j in range(bands):
+                if np.sum(u[:, j] * v[:, j] * w) < 0:
+                    bvecs[:, j] = -bvecs[:, j]
+                    v[:, j] = -v[:, j]
+
+            mads = u - v
+            rho = np.sqrt(rho2)
+            sigma2 = np.maximum(2.0 * (1.0 - rho), eps)  # MAD variances
+            mads_std = mads / np.sqrt(sigma2)[None, :]
+
+            chi2 = np.sum(mads_std ** 2, axis=1)
+            # No-change probability = 1 - CDF (large chi2 => change)
+            w_new = 1.0 - _chi2_cdf(chi2, bands)
+            w_new = np.clip(w_new, 1e-6, 1.0)
+
+            if rho_prev is not None and np.max(np.abs(rho - rho_prev)) < tol:
+                w = w_new
+                converged = True
+                break
+            rho_prev = rho
+            w = w_new
+
+        chi2_map = np.sum(mads_std ** 2, axis=1).reshape(ah, aw)
+        # Robust quantile normalization instead of the chi-square CDF: the CDF
+        # saturates at ~1.0 for most real pixels, which destroys the graded
+        # response needed by percentile-threshold fusion downstream.
+        hi = float(np.quantile(chi2_map, 0.995))
+        if hi <= 1e-8:
+            hi = float(chi2_map.max() + 1e-8)
+        prob = np.clip(chi2_map / hi, 0.0, 1.0)
+        nc_w = w.reshape(ah, aw)
+
+        prob_full = prob.astype(np.float32)
+        ncw_full = nc_w.astype(np.float32)
+        if (ah, aw) != (full_h, full_w):
+            prob_full = cv2.resize(prob_full, (full_w, full_h), interpolation=cv2.INTER_LINEAR)
+            ncw_full = cv2.resize(ncw_full, (full_w, full_h), interpolation=cv2.INTER_LINEAR)
+
+        return IRMADResult(
+            chi2=chi2_map.astype(np.float32),
+            change_prob=np.clip(prob_full, 0.0, 1.0),
+            no_change_weights=np.clip(ncw_full, 0.0, 1.0),
+            iterations=it,
+            converged=converged,
+        )
+    except Exception as exc:
+        _log.warning("IR-MAD failed (%s)", exc)
+        return None
+
+
+def radiometric_regression_normalize(
+    img1: np.ndarray,
+    img2: np.ndarray,
+    no_change_weights: np.ndarray,
+    min_weight: float = 0.5,
+) -> Optional[np.ndarray]:
+    """Normalize img2 to img1 via weighted linear regression on no-change pixels.
+
+    Classic IR-MAD application: fit per-band ``img1 ~ a*img2 + b`` using only
+    pixels the IR-MAD iteration deemed unchanged, then map img2 through the
+    fit. More faithful than global mean/std matching because changed pixels
+    no longer skew the statistics. Returns uint8 image or None.
+    """
+    try:
+        if img1.shape != img2.shape:
+            return None
+        w = no_change_weights.astype(np.float64).ravel()
+        sel = w >= min_weight
+        if np.count_nonzero(sel) < 500:
+            return None
+        out = img2.astype(np.float64).copy()
+        for ch in range(img1.shape[2]):
+            s = img2[:, :, ch].astype(np.float64).ravel()[sel]
+            t = img1[:, :, ch].astype(np.float64).ravel()[sel]
+            ww = w[sel]
+            wsum = ww.sum() + 1e-12
+            ms, mt = (s * ww).sum() / wsum, (t * ww).sum() / wsum
+            cov = ((s - ms) * (t - mt) * ww).sum() / wsum
+            var = ((s - ms) ** 2 * ww).sum() / wsum
+            if var < 1e-6:
+                continue
+            gain = cov / var
+            if not (0.2 <= gain <= 5.0):
+                continue
+            offset = mt - gain * ms
+            out[:, :, ch] = img2[:, :, ch].astype(np.float64) * gain + offset
+        return np.clip(out, 0, 255).astype(np.uint8)
+    except Exception as exc:
+        _log.warning("IR-MAD regression normalization failed (%s)", exc)
+        return None

app/cd_models/kpca_features.py

@@ -0,0 +1,163 @@
+"""KPCAMNet-style unsupervised deep change features (Kernel-PCA convolution).
+
+Implements the core idea of "Unsupervised Change Detection in Multitemporal
+VHR Images Based on Deep Kernel PCA Convolutional Mapping Network"
+(Wu, Chen et al., IEEE TCYB 2022, https://github.com/ChenHongruixuan/KPCAMNet):
+
+1. Patch vectors from both timestamps are projected through *shared* kernel-PCA
+   mappings (siamese: identical projection for both images), stacked in layers
+   like a small convolutional network. No labels or pretraining required —
+   projections are fitted on the image pair itself.
+2. The per-pixel feature difference is mapped to a polar domain:
+   magnitude ``rho`` (change strength) and direction ``theta`` (change type).
+3. ``rho`` is thresholded (Otsu + hysteresis by the caller) for the binary
+   change mask; ``theta`` supports discriminating change types downstream.
+
+For CPU practicality the exact KPCA (O(N^2) kernel matrix) is replaced by the
+standard Nystroem approximation + linear PCA, which scales linearly in pixels
+while preserving the kernelized mapping. Layer projections are fitted on a
+random pixel sample from BOTH images so the mapping is shared (siamese).
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+import cv2
+import numpy as np
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass
+class KPCAChangeResult:
+    rho: np.ndarray            # float32 [0,1], change magnitude, input resolution
+    theta: np.ndarray          # float32 [-pi,pi], change direction, input resolution
+    n_layers: int
+    n_components: int
+    analysis_shape: Tuple[int, int]
+
+
+def _patch_stack(img: np.ndarray, patch: int) -> np.ndarray:
+    """(H,W,C) -> (H,W,C*patch*patch) neighborhood features via shifted views."""
+    h, w, c = img.shape
+    r = patch // 2
+    padded = cv2.copyMakeBorder(img, r, r, r, r, cv2.BORDER_REFLECT)
+    views = []
+    for dy in range(patch):
+        for dx in range(patch):
+            views.append(padded[dy:dy + h, dx:dx + w])
+    return np.concatenate(views, axis=2).astype(np.float32)
+
+
+def _fit_shared_projection(feat_a: np.ndarray, feat_b: np.ndarray,
+                           n_components: int, sample: int, seed: int):
+    """Fit Nystroem(RBF) + PCA on a pixel sample drawn from both images."""
+    from sklearn.decomposition import PCA
+    from sklearn.kernel_approximation import Nystroem
+    from sklearn.pipeline import Pipeline
+    from sklearn.preprocessing import StandardScaler
+
+    rng = np.random.default_rng(seed)
+    flat = np.concatenate([
+        feat_a.reshape(-1, feat_a.shape[2]),
+        feat_b.reshape(-1, feat_b.shape[2]),
+    ], axis=0)
+    take = min(sample, flat.shape[0])
+    idx = rng.choice(flat.shape[0], size=take, replace=False)
+    fit_data = flat[idx]
+
+    n_landmarks = int(min(128, max(32, take // 24)))
+    pipe = Pipeline([
+        ("scale", StandardScaler()),
+        ("nystroem", Nystroem(kernel="rbf", n_components=n_landmarks, random_state=seed)),
+        ("pca", PCA(n_components=n_components, random_state=seed)),
+    ])
+    pipe.fit(fit_data)
+    return pipe
+
+
+def _transform_image(pipe, feat: np.ndarray) -> np.ndarray:
+    h, w, c = feat.shape
+    out = pipe.transform(feat.reshape(-1, c))
+    return out.reshape(h, w, -1).astype(np.float32)
+
+
+def compute_kpca_change(
+    img1: np.ndarray,
+    img2: np.ndarray,
+    *,
+    n_components: int = 8,
+    n_layers: int = 2,
+    patch: int = 5,
+    max_side: int = 768,
+    fit_sample: int = 4000,
+    seed: int = 42,
+) -> Optional[KPCAChangeResult]:
+    """Siamese KPCA change features for an RGB image pair.
+
+    Returns rho/theta maps at the input resolution, or None on failure
+    (caller falls back to its previous behavior).
+    """
+    try:
+        if img1.shape != img2.shape or img1.ndim != 3:
+            return None
+        full_h, full_w = img1.shape[:2]
+
+        # Bounded analysis resolution keeps the Nystroem transform CPU-friendly
+        scale = min(1.0, max_side / max(full_h, full_w))
+        if scale < 1.0:
+            ah, aw = max(64, int(full_h * scale)), max(64, int(full_w * scale))
+            a = cv2.resize(img1, (aw, ah), interpolation=cv2.INTER_AREA)
+            b = cv2.resize(img2, (aw, ah), interpolation=cv2.INTER_AREA)
+        else:
+            a, b = img1, img2
+
+        a = a.astype(np.float32) / 255.0
+        b = b.astype(np.float32) / 255.0
+
+        feat_a, feat_b = a, b
+        layer_patch = patch
+        for layer in range(max(1, n_layers)):
+            stack_a = _patch_stack(feat_a, layer_patch)
+            stack_b = _patch_stack(feat_b, layer_patch)
+            pipe = _fit_shared_projection(
+                stack_a, stack_b, n_components=n_components,
+                sample=fit_sample, seed=seed + layer,
+            )
+            feat_a = _transform_image(pipe, stack_a)
+            feat_b = _transform_image(pipe, stack_b)
+            layer_patch = 3  # deeper layers use tighter neighborhoods
+
+        diff = feat_a - feat_b
+
+        # Polar mapping (KPCAMNet): magnitude over all components; direction
+        # from the two most-informative difference components.
+        rho = np.sqrt(np.sum(diff * diff, axis=2))
+        var_order = np.argsort(np.var(diff.reshape(-1, diff.shape[2]), axis=0))[::-1]
+        d1 = diff[:, :, var_order[0]]
+        d2 = diff[:, :, var_order[1]] if diff.shape[2] > 1 else np.zeros_like(d1)
+        theta = np.arctan2(d2, d1)
+
+        # Robust [0,1] normalization of magnitude
+        hi = float(np.quantile(rho, 0.995))
+        if hi <= 1e-8:
+            hi = float(rho.max() + 1e-8)
+        rho = np.clip(rho / hi, 0.0, 1.0).astype(np.float32)
+
+        if rho.shape != (full_h, full_w):
+            rho = cv2.resize(rho, (full_w, full_h), interpolation=cv2.INTER_LINEAR)
+            theta = cv2.resize(theta.astype(np.float32), (full_w, full_h),
+                               interpolation=cv2.INTER_NEAREST)
+
+        return KPCAChangeResult(
+            rho=rho.astype(np.float32),
+            theta=theta.astype(np.float32),
+            n_layers=max(1, n_layers),
+            n_components=n_components,
+            analysis_shape=(a.shape[0], a.shape[1]),
+        )
+    except Exception as exc:
+        _log.warning("KPCA change features failed (%s) — caller will fall back", exc)
+        return None

app/cd_models/kpca_method.py

@@ -0,0 +1,97 @@
+"""
+KPCA-based unsupervised change detection (KPCAMNet-inspired).
+
+Fits Kernel PCA filters on randomly sampled patches from both images (weight-
+shared/siamese, no labels needed), projects the whole image through those
+filters, then detects change via the L2 norm of the feature difference. This
+is a single-stage reconstruction of the described KPCAMNet algorithm (not a
+port of the original repo's code, which isn't part of this project) — scoped
+down for CPU feasibility: bounded processing resolution and a modest training
+patch count, since KernelPCA.transform cost scales with
+n_query_patches x n_train_patches.
+"""
+import cv2
+import numpy as np
+from numpy.lib.stride_tricks import sliding_window_view
+from sklearn.decomposition import KernelPCA
+
+
+def _extract_all_patches(img: np.ndarray, patch_size: int) -> np.ndarray:
+    """Every overlapping patch_size x patch_size patch, one per pixel (reflect-padded)."""
+    half = patch_size // 2
+    padded = np.pad(img, half, mode="reflect")
+    windows = sliding_window_view(padded, (patch_size, patch_size))
+    h, w = img.shape
+    return windows.reshape(h, w, -1)
+
+
+def _project_in_chunks(kpca: KernelPCA, flat_patches: np.ndarray, row_pixels: int,
+                       n_components: int) -> np.ndarray:
+    """KernelPCA.transform in row-chunks so memory stays bounded on large images."""
+    chunks = []
+    step = max(1, 200_000 // max(1, row_pixels)) * row_pixels
+    for i in range(0, flat_patches.shape[0], step):
+        chunks.append(kpca.transform(flat_patches[i:i + step]))
+    return np.concatenate(chunks, axis=0)
+
+
+def kpca_change_mask(img1: np.ndarray, img2: np.ndarray, patch_size: int = 5,
+                     n_components: int = 8, gamma: float = 5e-4,
+                     n_train_patches: int = 300, max_side: int = 768):
+    """
+    Returns (magnitude_map float32 [0,1] at processed resolution, debug dict).
+    Caller handles thresholding/cleanup/resize-back so this stays testable in
+    isolation without pulling in the rest of the detection pipeline.
+    """
+    if img1.shape != img2.shape:
+        img2 = cv2.resize(img2, (img1.shape[1], img1.shape[0]))
+
+    h0, w0 = img1.shape[:2]
+    scale = min(1.0, max_side / max(h0, w0, 1))
+    if scale < 1.0:
+        nh, nw = max(1, int(h0 * scale)), max(1, int(w0 * scale))
+        img1_s = cv2.resize(img1, (nw, nh), interpolation=cv2.INTER_AREA)
+        img2_s = cv2.resize(img2, (nw, nh), interpolation=cv2.INTER_AREA)
+    else:
+        img1_s, img2_s = img1, img2
+
+    gray1 = cv2.cvtColor(img1_s, cv2.COLOR_RGB2GRAY).astype(np.float32) / 255.0
+    gray2 = cv2.cvtColor(img2_s, cv2.COLOR_RGB2GRAY).astype(np.float32) / 255.0
+    # Per-image z-score standardization (matches the described preprocessing)
+    gray1 = (gray1 - gray1.mean()) / (gray1.std() + 1e-8)
+    gray2 = (gray2 - gray2.mean()) / (gray2.std() + 1e-8)
+
+    h, w = gray1.shape
+    patches1 = _extract_all_patches(gray1, patch_size)
+    patches2 = _extract_all_patches(gray2, patch_size)
+    flat1 = patches1.reshape(-1, patches1.shape[-1])
+    flat2 = patches2.reshape(-1, patches2.shape[-1])
+
+    rng = np.random.default_rng(42)
+    half_n = max(1, n_train_patches // 2)
+    idx1 = rng.choice(flat1.shape[0], size=min(half_n, flat1.shape[0]), replace=False)
+    idx2 = rng.choice(flat2.shape[0], size=min(half_n, flat2.shape[0]), replace=False)
+    train_patches = np.concatenate([flat1[idx1], flat2[idx2]], axis=0)
+
+    n_components_eff = max(1, min(n_components, train_patches.shape[0] - 1))
+    kpca = KernelPCA(n_components=n_components_eff, kernel="rbf", gamma=gamma)
+    kpca.fit(train_patches)
+
+    feat1 = _project_in_chunks(kpca, flat1, w, n_components_eff).reshape(h, w, n_components_eff)
+    feat2 = _project_in_chunks(kpca, flat2, w, n_components_eff).reshape(h, w, n_components_eff)
+
+    diff = feat1 - feat2
+    magnitude = np.linalg.norm(diff, axis=-1)
+    mag_norm = magnitude / (magnitude.max() + 1e-8)
+
+    if scale < 1.0:
+        mag_norm = cv2.resize(mag_norm.astype(np.float32), (w0, h0), interpolation=cv2.INTER_LINEAR)
+
+    debug = {
+        "n_components": int(n_components_eff),
+        "n_train_patches": int(train_patches.shape[0]),
+        "processedSide": int(max(h, w)),
+        "patchSize": int(patch_size),
+        "gamma": float(gamma),
+    }
+    return mag_norm.astype(np.float32), debug

app/cd_models/model_utils.py

@@ -0,0 +1,261 @@
+"""
+Shared utilities for model loading, tile processing, and multi-scale detection.
+"""
+import cv2
+import numpy as np
+
+
+def _tile_signature(tile: np.ndarray, size: int = 16) -> np.ndarray:
+    """Cheap, deterministic per-tile fingerprint for a fast unchanged check.
+
+    Downsamples to a tiny ``size x size`` patch in LAB space (kept as a grid,
+    not flattened). Comparing two signatures is orders of magnitude cheaper
+    than a model forward pass, so it's usable as a pre-filter ahead of the
+    real scorer.
+    """
+    small = cv2.resize(tile, (size, size), interpolation=cv2.INTER_AREA)
+    if small.ndim == 3:
+        small = cv2.cvtColor(small, cv2.COLOR_RGB2LAB)
+    return small.astype(np.float32)
+
+
+def _tiles_likely_unchanged(t1: np.ndarray, t2: np.ndarray, threshold: float) -> bool:
+    """True when two same-size tiles are near-identical everywhere.
+
+    Uses the *worst-cell* (max) per-cell LAB distance on the downsampled grid,
+    not a mean or percentile — a small localized change concentrated in just
+    one or two cells out of the grid would be washed out by averaging (mean)
+    or ignored entirely by a percentile below ~100, which risks silently
+    skipping a real small change. Max cleanly separates that from sensor
+    noise (empirically ~1 unit of noise floor vs 25+ for even an 8x8px real
+    change in a 256px tile), so this is the safe choice for a pre-filter that
+    must not increase false negatives.
+    """
+    sig1 = _tile_signature(t1)
+    sig2 = _tile_signature(t2)
+    diff = np.abs(sig1 - sig2)
+    if diff.ndim == 3:
+        diff = diff.max(axis=-1)
+    return float(diff.max()) <= threshold
+
+
+def make_blend_weights(tile_size: int, overlap: int) -> np.ndarray:
+    """Raised-cosine (trapezoid) 2D weight for seamless tile stitching.
+
+    Ramps from 0 to 1 across the overlap band on each edge and stays flat in
+    the interior, so overlapping tile predictions blend without visible seams.
+    """
+    overlap = max(0, min(overlap, tile_size // 2))
+    if overlap == 0:
+        return np.ones((tile_size, tile_size), dtype=np.float32)
+    ramp = np.linspace(0.0, 1.0, overlap, dtype=np.float32)
+    flat = np.ones(tile_size - 2 * overlap, dtype=np.float32)
+    profile = np.concatenate([ramp, flat, ramp[::-1]])
+    return np.outer(profile, profile).astype(np.float32)
+
+
+def tiled_score_map(score_tile_fn, img1, img2, tile_size: int = 256,
+                    overlap: int | None = None,
+                    score_batch_fn=None, batch: int = 1,
+                    skip_unchanged_threshold: float | None = None,
+                    stats: dict | None = None):
+    """Sliding-window tiled scoring with reflect padding + cosine blending.
+
+    ``score_tile_fn(tile1, tile2)`` must return a float32 array in [0, 1] the
+    same height/width as the input tile. Returns a float32 change-probability
+    map cropped back to the original (h, w). This is the single shared
+    implementation used by every deep model so blending stays consistent.
+
+    When ``batch > 1`` and ``score_batch_fn`` is provided, tiles are scored in
+    groups (``score_batch_fn(list[(t1, t2)]) -> list[prob]``) so GPUs can run
+    several tiles per forward pass.
+
+    When ``skip_unchanged_threshold`` is set, tiles whose before/after content
+    is near-identical skip the expensive scorer entirely and are recorded as
+    zero change — a cheap pre-filter that speeds up runs where most of the
+    scene didn't change, without affecting tiles that actually did. Pass a
+    ``stats`` dict to accumulate ``{"totalTiles", "skippedTiles"}`` into it.
+    """
+    h, w = img1.shape[:2]
+    if overlap is None:
+        overlap = tile_size // 4
+    overlap = max(0, min(overlap, tile_size // 2))
+    stride = max(1, tile_size - overlap)
+
+    pad_h = (tile_size - h % tile_size) % tile_size
+    pad_w = (tile_size - w % tile_size) % tile_size
+    # Guarantee at least one full tile even for small inputs
+    pad_h = max(pad_h, max(0, tile_size - h))
+    pad_w = max(pad_w, max(0, tile_size - w))
+    if pad_h or pad_w:
+        img1 = np.pad(img1, ((0, pad_h), (0, pad_w), (0, 0)), mode="reflect")
+        img2 = np.pad(img2, ((0, pad_h), (0, pad_w), (0, 0)), mode="reflect")
+
+    ph, pw = img1.shape[:2]
+    score_sum = np.zeros((ph, pw), dtype=np.float32)
+    count = np.zeros((ph, pw), dtype=np.float32)
+    weight_2d = make_blend_weights(tile_size, overlap)
+
+    ys = list(range(0, ph - tile_size + 1, stride))
+    xs = list(range(0, pw - tile_size + 1, stride))
+    # Ensure the far edges are always covered
+    if ys and ys[-1] != ph - tile_size:
+        ys.append(ph - tile_size)
+    if xs and xs[-1] != pw - tile_size:
+        xs.append(pw - tile_size)
+
+    coords = [(y0, x0) for y0 in ys for x0 in xs]
+
+    def _accumulate(y0, x0, prob):
+        if prob.shape != (tile_size, tile_size):
+            prob = cv2.resize(prob.astype(np.float32), (tile_size, tile_size),
+                              interpolation=cv2.INTER_LINEAR)
+        score_sum[y0:y0 + tile_size, x0:x0 + tile_size] += prob * weight_2d
+        count[y0:y0 + tile_size, x0:x0 + tile_size] += weight_2d
+
+    zero_tile = np.zeros((tile_size, tile_size), dtype=np.float32)
+    skipped = 0
+
+    def _unchanged(t1, t2):
+        return (skip_unchanged_threshold is not None
+                and _tiles_likely_unchanged(t1, t2, skip_unchanged_threshold))
+
+    use_batch = score_batch_fn is not None and batch > 1
+    if use_batch:
+        for i in range(0, len(coords), batch):
+            chunk = coords[i:i + batch]
+            pairs = []
+            kept = []
+            for (y, x) in chunk:
+                t1 = np.ascontiguousarray(img1[y:y + tile_size, x:x + tile_size])
+                t2 = np.ascontiguousarray(img2[y:y + tile_size, x:x + tile_size])
+                if _unchanged(t1, t2):
+                    skipped += 1
+                    _accumulate(y, x, zero_tile)
+                    continue
+                pairs.append((t1, t2))
+                kept.append((y, x))
+            if pairs:
+                probs = score_batch_fn(pairs)
+                for (y0, x0), prob in zip(kept, probs):
+                    _accumulate(y0, x0, prob)
+    else:
+        for (y0, x0) in coords:
+            t1 = np.ascontiguousarray(img1[y0:y0 + tile_size, x0:x0 + tile_size])
+            t2 = np.ascontiguousarray(img2[y0:y0 + tile_size, x0:x0 + tile_size])
+            if _unchanged(t1, t2):
+                skipped += 1
+                _accumulate(y0, x0, zero_tile)
+                continue
+            _accumulate(y0, x0, score_tile_fn(t1, t2))
+
+    if stats is not None:
+        stats["totalTiles"] = stats.get("totalTiles", 0) + len(coords)
+        stats["skippedTiles"] = stats.get("skippedTiles", 0) + skipped
+
+    count = np.maximum(count, 1e-6)
+    avg = score_sum / count
+    return avg[:h, :w]
+
+
+def split_into_tiles(img, tile_size=512, overlap=64):
+    """
+    Split an image into overlapping tiles.
+    Returns list of (tile, y_offset, x_offset) tuples.
+    """
+    h, w = img.shape[:2]
+    stride = tile_size - overlap
+    tiles = []
+
+    pad_h = (tile_size - h % tile_size) % tile_size if h % tile_size else 0
+    pad_w = (tile_size - w % tile_size) % tile_size if w % tile_size else 0
+    if pad_h or pad_w:
+        img = np.pad(img, ((0, pad_h), (0, pad_w), (0, 0)) if img.ndim == 3
+                     else ((0, pad_h), (0, pad_w)), mode="reflect")
+
+    ph, pw = img.shape[:2]
+    for y in range(0, ph - tile_size + 1, stride):
+        for x in range(0, pw - tile_size + 1, stride):
+            tile = img[y:y+tile_size, x:x+tile_size]
+            tiles.append((tile, y, x))
+
+    return tiles, (ph, pw), (h, w)
+
+
+def merge_tile_masks(tile_results, padded_shape, orig_shape, tile_size=512, overlap=64):
+    """
+    Merge tile-level binary masks back into a single full-resolution mask.
+    Uses raised-cosine blending to avoid tile boundary artifacts.
+    """
+    ph, pw = padded_shape
+    h, w = orig_shape
+
+    score_sum = np.zeros((ph, pw), dtype=np.float32)
+    count = np.zeros((ph, pw), dtype=np.float32)
+
+    ramp = np.linspace(0, 1, overlap)
+    flat = np.ones(tile_size - 2 * overlap)
+    profile = np.concatenate([ramp, flat, ramp[::-1]])
+    weight_2d = np.outer(profile, profile).astype(np.float32)
+
+    for (mask_tile, y, x) in tile_results:
+        score = mask_tile.astype(np.float32) / 255.0 if mask_tile.max() > 1 else mask_tile.astype(np.float32)
+        if score.shape != (tile_size, tile_size):
+            score = cv2.resize(score, (tile_size, tile_size))
+        score_sum[y:y+tile_size, x:x+tile_size] += score * weight_2d
+        count[y:y+tile_size, x:x+tile_size] += weight_2d
+
+    count = np.maximum(count, 1e-6)
+    merged = score_sum / count
+    merged = merged[:h, :w]
+    return (merged * 255).astype(np.uint8)
+
+
+def multiscale_detect(detect_fn, img1, img2, scales=(1.0, 0.5, 0.25)):
+    """
+    Run a detection function at multiple scales and combine via logical OR.
+    detect_fn(img1, img2) -> uint8 mask [0|255].
+    Captures small structures at full res and large regions at coarse scales.
+    """
+    h, w = img1.shape[:2]
+    combined = np.zeros((h, w), dtype=np.uint8)
+
+    for scale in scales:
+        if scale == 1.0:
+            s1, s2 = img1, img2
+        else:
+            sh, sw = max(64, int(h * scale)), max(64, int(w * scale))
+            s1 = cv2.resize(img1, (sw, sh), interpolation=cv2.INTER_AREA)
+            s2 = cv2.resize(img2, (sw, sh), interpolation=cv2.INTER_AREA)
+
+        mask = detect_fn(s1, s2)
+
+        if scale != 1.0:
+            mask = cv2.resize(mask, (w, h), interpolation=cv2.INTER_NEAREST)
+
+        combined = np.maximum(combined, mask)
+
+    return combined
+
+
+def build_confidence_map(channels, weights=None):
+    """
+    Build a [0-1] confidence map from multiple normalized signal channels.
+    Each channel should be a float32 array in [0,1].
+    If weights is None, uses equal weighting.
+    """
+    if not channels:
+        return None
+    if weights is None:
+        weights = [1.0 / len(channels)] * len(channels)
+    total_w = sum(weights)
+    weights = [w / total_w for w in weights]
+
+    shape = channels[0].shape
+    conf = np.zeros(shape, dtype=np.float64)
+    for ch, w in zip(channels, weights):
+        if ch.shape != shape:
+            ch = cv2.resize(ch.astype(np.float32), (shape[1], shape[0]))
+        conf += w * ch.astype(np.float64)
+
+    return np.clip(conf, 0, 1).astype(np.float32)

app/cd_models/weights/.gitkeep

@@ -0,0 +1 @@
+

app/database.py

@@ -0,0 +1,65 @@
+import os
+from pathlib import Path
+
+from sqlalchemy import create_engine, event
+from sqlalchemy.orm import sessionmaker, declarative_base
+
+BASE_DIR = Path(__file__).resolve().parent
+
+# Use /home/appuser/data on HF Spaces (writable), fall back to local data/ dir
+_home_data = Path.home() / "data"
+_local_data = BASE_DIR.parent / "data"
+DATA_DIR = _home_data if os.environ.get("SPACE_ID") else _local_data
+try:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+except Exception:
+    pass  # avoid crashing if read-only or permission issue (e.g. some HF environments)
+
+DB_PATH = DATA_DIR / "satellite_app.db"
+
+DATABASE_URL = os.environ.get("DATABASE_URL", f"sqlite:///{DB_PATH}")
+
+# Render gives postgres:// but SQLAlchemy 2.x requires postgresql://
+if DATABASE_URL.startswith("postgres://"):
+    DATABASE_URL = DATABASE_URL.replace("postgres://", "postgresql://", 1)
+
+connect_args = {}
+if DATABASE_URL.startswith("sqlite"):
+    # timeout = busy wait while another connection holds the write lock
+    # (progress updates vs the long-running detection worker).
+    connect_args = {"check_same_thread": False, "timeout": 60.0}
+
+# pool_pre_ping: checks each connection before use and transparently reconnects
+# if it's gone stale — matters for a remote DB (MySQL/Postgres) reached over
+# the network, where idle connections can be dropped by the server or a
+# firewall; irrelevant (and skipped) for local SQLite.
+engine = create_engine(
+    DATABASE_URL,
+    connect_args=connect_args,
+    pool_pre_ping=not DATABASE_URL.startswith("sqlite"),
+)
+
+
+@event.listens_for(engine, "connect")
+def _sqlite_pragmas(dbapi_conn, _connection_record):
+    if not DATABASE_URL.startswith("sqlite"):
+        return
+    cur = dbapi_conn.cursor()
+    try:
+        cur.execute("PRAGMA journal_mode=WAL")
+        cur.execute("PRAGMA busy_timeout=60000")
+        cur.execute("PRAGMA synchronous=NORMAL")
+    finally:
+        cur.close()
+
+
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+Base = declarative_base()
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

app/dda/__init__.py

@@ -0,0 +1 @@
+"""Vedangsoft change detection module (dev Space / APP_MODE=dda)."""

app/dda/admin_routes.py

@@ -0,0 +1,95 @@
+"""Vedangsoft admin diagnostics and maintenance (Phase 7)."""
+from __future__ import annotations
+
+import logging
+import shutil
+from datetime import datetime, timedelta, timezone
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from sqlalchemy.orm import Session
+
+from ..database import DATA_DIR, get_db
+from ..models import DetectionRun, User
+from .dda_auth import get_user_role
+from .job_runner import is_job_runner_busy, reconcile_stale_jobs
+from .tree.image_service import count_library_images
+from .models import DetectionJob, RegionReview
+from .rbac.permissions import require_module_permission
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+def _require_dda():
+    from .config import IS_DDA_MODE
+    if not IS_DDA_MODE:
+        raise HTTPException(status_code=404, detail="DDA mode is not enabled")
+
+
+@router.get("/admin/status")
+def admin_status(
+    request: Request,
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("admin", "view")),
+):
+    """System status for UAT / ops."""
+    _require_dda()
+
+    runs = db.query(DetectionRun).count()
+    jobs_queued = db.query(DetectionJob).filter(DetectionJob.status == "queued").count()
+    jobs_running = db.query(DetectionJob).filter(DetectionJob.status == "running").count()
+    fp_count = db.query(RegionReview).filter(RegionReview.status == "false_positive").count()
+
+    disk = shutil.disk_usage(DATA_DIR)
+    return {
+        "role": get_user_role(db, user),
+        "libraryImages": count_library_images(db),
+        "detectionRuns": runs,
+        "jobsQueued": jobs_queued,
+        "jobsRunning": jobs_running,
+        "runnerBusy": is_job_runner_busy(),
+        "falsePositiveArchive": fp_count,
+        "dataDir": str(DATA_DIR),
+        "diskFreeGb": round(disk.free / (1024 ** 3), 2),
+        "diskTotalGb": round(disk.total / (1024 ** 3), 2),
+    }
+
+
+@router.post("/admin/reconcile-jobs")
+def admin_reconcile_jobs(
+    request: Request,
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("admin", "edit")),
+):
+    _require_dda()
+    fixed = reconcile_stale_jobs(db)
+    return {"ok": True, "staleRunningFixed": fixed}
+
+
+@router.delete("/admin/purge-runs")
+def admin_purge_old_runs(
+    request: Request,
+    days: int = Query(90, ge=7, le=3650),
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("admin", "delete")),
+):
+    """Delete detection runs older than N days (admin only)."""
+    _require_dda()
+    cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+    old = db.query(DetectionRun).filter(DetectionRun.created_at < cutoff).all()
+    count = 0
+    overlays_root = DATA_DIR
+    for run in old:
+        db.query(RegionReview).filter(RegionReview.run_id == run.id).delete()
+        for job in db.query(DetectionJob).filter(DetectionJob.run_id == run.id).all():
+            job.run_id = None
+        for path_attr in ("overlay_path", "before_full_path", "before_thumb_path", "after_thumb_path", "after_full_path"):
+            path_val = getattr(run, path_attr, None)
+            if path_val:
+                f = overlays_root / path_val
+                if f.exists():
+                    f.unlink(missing_ok=True)
+        db.delete(run)
+        count += 1
+    db.commit()
+    return {"ok": True, "purgedRuns": count, "olderThanDays": days}

app/dda/applog.py

@@ -0,0 +1,130 @@
+"""In-memory + file application log so the Logs page can view recent events."""
+from __future__ import annotations
+
+import logging
+import threading
+from collections import deque
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+from ..database import DATA_DIR
+
+_LOCK = threading.Lock()
+_BUFFER: deque = deque(maxlen=4000)
+_HANDLER: Optional["RingLogHandler"] = None
+
+LOG_DIR = DATA_DIR / "logs"
+LOG_FILE = LOG_DIR / "app.log"
+
+_LEVELS = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+}
+
+
+class RingLogHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            msg = self.format(record)
+        except Exception:
+            msg = record.getMessage()
+        created = datetime.fromtimestamp(record.created, tz=timezone.utc)
+        entry = {
+            "ts": created.isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": msg,
+        }
+        with _LOCK:
+            _BUFFER.append(entry)
+
+
+def install_app_log_handler() -> None:
+    """Attach once to the root logger (and uvicorn access) for the Logs UI."""
+    global _HANDLER
+    if _HANDLER is not None:
+        return
+    try:
+        LOG_DIR.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        pass
+
+    handler = RingLogHandler(level=logging.INFO)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    _HANDLER = handler
+
+    root = logging.getLogger()
+    root.addHandler(handler)
+    if root.level > logging.INFO or root.level == logging.NOTSET:
+        root.setLevel(logging.INFO)
+
+    file_handler = None
+    try:
+        file_handler = logging.FileHandler(LOG_FILE, encoding="utf-8")
+        file_handler.setLevel(logging.INFO)
+        file_handler.setFormatter(logging.Formatter(
+            "%(asctime)s %(levelname)s [%(name)s] %(message)s"
+        ))
+        root.addHandler(file_handler)
+    except OSError:
+        file_handler = None
+
+    for name in ("uvicorn", "uvicorn.error", "uvicorn.access"):
+        logging.getLogger(name).addHandler(handler)
+        if file_handler:
+            logging.getLogger(name).addHandler(file_handler)
+
+
+def query_logs(
+    *,
+    level: str = "",
+    q: str = "",
+    logger_name: str = "",
+    limit: int = 200,
+    offset: int = 0,
+) -> dict:
+    min_level = _LEVELS.get((level or "").upper(), 0)
+    needle = (q or "").strip().lower()
+    logger_f = (logger_name or "").strip().lower()
+    with _LOCK:
+        rows = list(_BUFFER)
+    rows.reverse()
+    filtered: List[dict] = []
+    for row in rows:
+        if min_level and _LEVELS.get(row["level"], 0) < min_level:
+            continue
+        if logger_f and logger_f not in (row.get("logger") or "").lower():
+            continue
+        if needle and needle not in (row.get("message") or "").lower() and needle not in (row.get("logger") or "").lower():
+            continue
+        filtered.append(row)
+    total = len(filtered)
+    page = filtered[offset:offset + limit]
+    return {
+        "total": total,
+        "offset": offset,
+        "limit": limit,
+        "logs": page,
+        "file": str(LOG_FILE) if LOG_FILE.exists() else "",
+    }
+
+
+def clear_logs() -> dict:
+    with _LOCK:
+        _BUFFER.clear()
+    truncated = False
+    try:
+        LOG_DIR.mkdir(parents=True, exist_ok=True)
+        LOG_FILE.write_text("", encoding="utf-8")
+        truncated = True
+    except OSError:
+        pass
+    return {"ok": True, "cleared": True, "fileTruncated": truncated}
+
+
+def log_file_path() -> Path:
+    return LOG_FILE

app/dda/audit_routes.py

@@ -0,0 +1,100 @@
+"""API for the Audit Log page — user activity trail (login/logout, uploads,
+detections, reports, admin/master-data changes)."""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models import User
+from .rbac.permissions import require_module_permission
+from .tree.audit_service import isoformat_ist
+from .tree.models import AuditLog
+
+router = APIRouter()
+
+
+def _require_dda():
+    from .config import IS_DDA_MODE
+    if not IS_DDA_MODE:
+        raise HTTPException(status_code=404, detail="DDA mode is not enabled")
+
+
+def _entry_dict(entry: AuditLog) -> dict:
+    return {
+        "id": entry.id,
+        "timestamp": isoformat_ist(entry.action_date),
+        "user": entry.action_by or "",
+        "role": entry.role or "",
+        "action": entry.action,
+        "module": entry.module or "",
+        "nodeId": entry.node_id,
+        "oldValue": entry.old_value or "",
+        "newValue": entry.new_value or "",
+    }
+
+
+def _parse_date(value: Optional[str], *, end_of_day: bool = False) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        dt = datetime.fromisoformat(value)
+    except ValueError:
+        raise HTTPException(status_code=400, detail=f"Invalid date: {value!r} (expected YYYY-MM-DD)")
+    if end_of_day:
+        dt = dt.replace(hour=23, minute=59, second=59, microsecond=999999)
+    return dt
+
+
+@router.get("/audit-log")
+def list_audit_log(
+    action: str = Query(""),
+    module: str = Query(""),
+    role: str = Query(""),
+    from_date: Optional[str] = Query(None, alias="from"),
+    to_date: Optional[str] = Query(None, alias="to"),
+    limit: int = Query(100, ge=1, le=1000),
+    offset: int = Query(0, ge=0),
+    user: User = Depends(require_module_permission("audit_log", "view")),
+    db: Session = Depends(get_db),
+):
+    _require_dda()
+    q = db.query(AuditLog)
+    if action:
+        q = q.filter(AuditLog.action == action)
+    if module:
+        q = q.filter(AuditLog.module == module)
+    if role:
+        q = q.filter(AuditLog.role == role)
+    start = _parse_date(from_date)
+    if start:
+        q = q.filter(AuditLog.action_date >= start)
+    end = _parse_date(to_date, end_of_day=True)
+    if end:
+        q = q.filter(AuditLog.action_date <= end)
+
+    total = q.count()
+    rows = q.order_by(AuditLog.action_date.desc()).offset(offset).limit(limit).all()
+
+    return {
+        "logs": [_entry_dict(r) for r in rows],
+        "total": total,
+        "limit": limit,
+        "offset": offset,
+    }
+
+
+@router.get("/audit-log/filters")
+def audit_log_filters(
+    user: User = Depends(require_module_permission("audit_log", "view")),
+    db: Session = Depends(get_db),
+):
+    """Distinct action/module/role values, for populating the filter dropdowns."""
+    _require_dda()
+    actions = [r[0] for r in db.query(AuditLog.action).distinct().order_by(AuditLog.action) if r[0]]
+    modules = [r[0] for r in db.query(AuditLog.module).distinct().order_by(AuditLog.module) if r[0]]
+    roles = [r[0] for r in db.query(AuditLog.role).distinct().order_by(AuditLog.role) if r[0]]
+    return {"actions": actions, "modules": modules, "roles": roles}

app/dda/auto_detect.py

@@ -0,0 +1,614 @@
+"""Periodic automatic detection for identified same-area pairs.
+
+Manual Change Detection is unchanged (user clicks Run). Automatic mode also
+keeps Run-now; this module queues the same identified Before/After pairs on a
+cadence (default 10 days) and saves reports without anyone opening the UI.
+
+The FastAPI process must stay running for the schedule to fire.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import threading
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from sqlalchemy.orm import Session
+
+from ..database import SessionLocal
+from ..models import User
+from .models import AutoDetectSettings, AutoPairSchedule, DetectionJob
+
+logger = logging.getLogger(__name__)
+
+AUTO_SOURCE = "auto_schedule"
+
+_scheduler_lock = threading.Lock()
+_tick_lock = threading.Lock()
+_scheduler_started = False
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _aware(dt: Optional[datetime]) -> Optional[datetime]:
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+_IST = timezone(timedelta(hours=5, minutes=30))
+
+
+def parse_run_at(value: str) -> str:
+    raw = (value or "02:00").strip()
+    try:
+        parts = raw.split(":")
+        hour = int(parts[0])
+        minute = int(parts[1]) if len(parts) > 1 else 0
+    except (TypeError, ValueError):
+        hour, minute = 2, 0
+    hour = max(0, min(23, hour))
+    minute = max(0, min(59, minute))
+    return f"{hour:02d}:{minute:02d}"
+
+
+def clamp_interval_days(value: Any, default: int = 10) -> int:
+    try:
+        days = int(value)
+    except (TypeError, ValueError):
+        days = default
+    return max(1, min(365, days))
+
+
+def get_or_create_settings(db: Session) -> AutoDetectSettings:
+    row = db.query(AutoDetectSettings).filter(AutoDetectSettings.id == 1).first()
+    if row:
+        return row
+    row = AutoDetectSettings(
+        id=1,
+        running=False,
+        interval_days=clamp_interval_days(os.environ.get("AUTO_DETECT_INTERVAL_DAYS", "10")),
+        run_at=parse_run_at(os.environ.get("AUTO_DETECT_RUN_AT", "02:00")),
+        next_run_at=None,
+    )
+    db.add(row)
+    db.commit()
+    db.refresh(row)
+    return row
+
+
+def scheduler_is_armed() -> bool:
+    from .config import IS_DDA_MODE
+    if not IS_DDA_MODE:
+        return False
+    raw = os.environ.get("AUTO_DETECT_ENABLED", "1").strip().lower()
+    if raw in ("0", "false", "no", "off"):
+        return False
+    db = SessionLocal()
+    try:
+        return bool(get_or_create_settings(db).running)
+    except Exception:
+        return False
+    finally:
+        db.close()
+
+
+def auto_detect_enabled() -> bool:
+    """Feature exists in DDA mode unless explicitly disabled in env.
+
+    The background *queue* only runs when the operator clicks Start
+    (``scheduler_is_armed``). This flag only means the Automatic tab controls
+    are available.
+    """
+    from .config import IS_DDA_MODE
+    if not IS_DDA_MODE:
+        return False
+    raw = os.environ.get("AUTO_DETECT_ENABLED", "1").strip().lower()
+    return raw not in ("0", "false", "no", "off")
+
+
+def get_auto_detect_interval_days() -> int:
+    db = SessionLocal()
+    try:
+        return clamp_interval_days(get_or_create_settings(db).interval_days)
+    except Exception:
+        return clamp_interval_days(os.environ.get("AUTO_DETECT_INTERVAL_DAYS", "10"))
+    finally:
+        db.close()
+
+
+def next_run_at_from_clock(run_at: str, now: Optional[datetime] = None) -> datetime:
+    """Next future IST clock time for HH:MM. Never returns 'now' (no launch burst)."""
+    ist_now = (now or datetime.now(_IST)).astimezone(_IST)
+    hhmm = parse_run_at(run_at)
+    hour, minute = (int(p) for p in hhmm.split(":"))
+    candidate = ist_now.replace(hour=hour, minute=minute, second=0, microsecond=0)
+    if candidate <= ist_now + timedelta(seconds=45):
+        candidate += timedelta(days=1)
+    return candidate.astimezone(timezone.utc)
+
+
+def cancel_queued_auto_jobs(db: Session, reason: str) -> int:
+    cancelled = 0
+    pending = (
+        db.query(DetectionJob)
+        .filter(DetectionJob.status == "queued")
+        .all()
+    )
+    for job in pending:
+        if not is_auto_schedule_job(job):
+            continue
+        job.status = "failed"
+        job.error_message = reason[:2000]
+        job.completed_at = _utcnow()
+        cancelled += 1
+    if cancelled:
+        db.commit()
+        logger.info("Cancelled %d queued auto-detect job(s)", cancelled)
+    return cancelled
+
+
+def pair_key_for(before_path: str, after_path: str) -> str:
+    a = (before_path or "").replace("\\", "/").strip().lower()
+    b = (after_path or "").replace("\\", "/").strip().lower()
+    return hashlib.sha256(f"{a}|{b}".encode("utf-8")).hexdigest()
+
+
+def job_source(job: DetectionJob) -> str:
+    try:
+        return str(json.loads(job.params_json or "{}").get("source") or "")
+    except json.JSONDecodeError:
+        return ""
+
+
+def is_auto_schedule_job(job: Optional[DetectionJob]) -> bool:
+    return bool(job) and job_source(job) == AUTO_SOURCE
+
+
+def is_auto_schedule_run(db: Session, run_id: int) -> bool:
+    if not run_id:
+        return False
+    job = (
+        db.query(DetectionJob)
+        .filter(DetectionJob.run_id == run_id)
+        .order_by(DetectionJob.id.desc())
+        .first()
+    )
+    return is_auto_schedule_job(job)
+
+
+def user_can_access_run(db: Session, run_id: int, user_id: int) -> bool:
+    from ..models import DetectionRun
+    run = db.query(DetectionRun).filter(DetectionRun.id == run_id).first()
+    if not run:
+        return False
+    if run.user_id == user_id:
+        return True
+    return is_auto_schedule_run(db, run_id)
+
+
+def _norm_path(path: str) -> str:
+    return (path or "").replace("\\", "/").strip()
+
+
+def _paths_match(job: DetectionJob, before: str, after: str) -> bool:
+    try:
+        params = json.loads(job.params_json or "{}")
+    except json.JSONDecodeError:
+        return False
+    return (
+        _norm_path(params.get("base_path", "")) == _norm_path(before)
+        and _norm_path(params.get("comparison_path", "")) == _norm_path(after)
+    )
+
+
+def _schedule_owner_id(db: Session) -> int:
+    admin = (
+        db.query(User)
+        .filter(User.role == "admin")
+        .order_by(User.id.asc())
+        .first()
+    )
+    if admin:
+        return admin.id
+    user = (
+        db.query(User)
+        .filter(User.email.notlike("__guest__%"))
+        .order_by(User.id.asc())
+        .first()
+    )
+    if user:
+        return user.id
+    from ..auth import get_or_create_guest_user
+    return get_or_create_guest_user(db).id
+
+
+def _load_identified_pairs(db: Session) -> list[dict[str, Any]]:
+    from .tree.area_groups import load_cached_area_groups
+
+    payload = load_cached_area_groups(db)
+    pairs = []
+    for group in payload.get("groups") or []:
+        before = group.get("beforePath") or (group.get("suggestedBefore") or {}).get("path")
+        after = group.get("afterPath") or (group.get("suggestedAfter") or {}).get("path")
+        if not before or not after or _norm_path(before) == _norm_path(after):
+            continue
+        pairs.append({
+            "group_id": group.get("id") or "",
+            "label": group.get("label") or Path(before).name,
+            "before_path": _norm_path(before),
+            "after_path": _norm_path(after),
+            "before_date": group.get("beforeDate"),
+            "after_date": group.get("afterDate"),
+        })
+    return pairs
+
+
+def _sync_schedules(db: Session, pairs: list[dict[str, Any]]) -> None:
+    interval = get_auto_detect_interval_days()
+    live_keys = set()
+    now = _utcnow()
+    for pair in pairs:
+        key = pair_key_for(pair["before_path"], pair["after_path"])
+        live_keys.add(key)
+        row = db.query(AutoPairSchedule).filter(AutoPairSchedule.pair_key == key).first()
+        if row:
+            row.group_label = pair["label"]
+            row.before_path = pair["before_path"]
+            row.after_path = pair["after_path"]
+            row.interval_days = interval
+            row.enabled = True
+            row.updated_at = now
+        else:
+            db.add(AutoPairSchedule(
+                pair_key=key,
+                group_label=pair["label"],
+                before_path=pair["before_path"],
+                after_path=pair["after_path"],
+                interval_days=interval,
+                enabled=True,
+            ))
+    stale = (
+        db.query(AutoPairSchedule)
+        .filter(AutoPairSchedule.enabled.is_(True))
+        .all()
+    )
+    for row in stale:
+        if row.pair_key not in live_keys:
+            row.enabled = False
+            row.updated_at = now
+    db.commit()
+
+
+def _pending_job_for_paths(db: Session, before: str, after: str) -> Optional[DetectionJob]:
+    pending = (
+        db.query(DetectionJob)
+        .filter(DetectionJob.status.in_(("queued", "running")))
+        .order_by(DetectionJob.id.desc())
+        .limit(80)
+        .all()
+    )
+    for job in pending:
+        if _paths_match(job, before, after):
+            return job
+    return None
+
+
+def _latest_success_for_paths(db: Session, before: str, after: str) -> Optional[datetime]:
+    done = (
+        db.query(DetectionJob)
+        .filter(DetectionJob.status == "completed", DetectionJob.completed_at.isnot(None))
+        .order_by(DetectionJob.completed_at.desc())
+        .limit(80)
+        .all()
+    )
+    for job in done:
+        if _paths_match(job, before, after):
+            return _aware(job.completed_at)
+    return None
+
+
+def _is_due(row: AutoPairSchedule, last_success: Optional[datetime], now: datetime) -> bool:
+    interval = timedelta(days=max(1, int(row.interval_days or get_auto_detect_interval_days())))
+    last = _aware(row.last_completed_at) or last_success
+    if last and now < last + interval:
+        return False
+    last_enq = _aware(row.last_enqueued_at)
+    if row.last_error and last_enq and now < last_enq + timedelta(hours=12):
+        return False
+    if last_enq and last and now < last_enq + timedelta(minutes=30):
+        return False
+    return True
+
+
+def _enqueue_pair(db: Session, row: AutoPairSchedule) -> Optional[DetectionJob]:
+    from .job_runner import create_local_folder_job
+    from .local_routes import safe_resolve
+
+    try:
+        safe_resolve(row.before_path)
+        safe_resolve(row.after_path)
+    except Exception as exc:
+        row.last_error = f"Library path missing: {exc}"[:2000]
+        db.commit()
+        logger.warning("Auto-detect skip %s: %s", row.group_label, exc)
+        return None
+
+    title = f"[Auto] {row.group_label}: {Path(row.before_path).name} vs {Path(row.after_path).name}"
+    job = create_local_folder_job(
+        db,
+        base_path=row.before_path,
+        comparison_path=row.after_path,
+        title=title,
+        created_by=_schedule_owner_id(db),
+        extra_params={
+            "source": AUTO_SOURCE,
+            "pair_key": row.pair_key,
+            "group_label": row.group_label,
+        },
+    )
+    row.last_enqueued_at = _utcnow()
+    row.last_job_id = job.id
+    row.last_error = ""
+    db.commit()
+    logger.info(
+        "Auto-detect queued job %d for %s (%s → %s)",
+        job.id, row.group_label, Path(row.before_path).name, Path(row.after_path).name,
+    )
+    return job
+
+
+def tick_auto_detect() -> int:
+    """Sync identified pairs and enqueue those that are due. Returns jobs queued."""
+    if not scheduler_is_armed():
+        return 0
+    if not _tick_lock.acquire(blocking=False):
+        return 0
+    queued = 0
+    db = SessionLocal()
+    try:
+        pairs = _load_identified_pairs(db)
+        _sync_schedules(db, pairs)
+        now = _utcnow()
+        rows = (
+            db.query(AutoPairSchedule)
+            .filter(AutoPairSchedule.enabled.is_(True))
+            .order_by(AutoPairSchedule.id.asc())
+            .all()
+        )
+        for row in rows:
+            if _pending_job_for_paths(db, row.before_path, row.after_path):
+                continue
+            last_success = _latest_success_for_paths(db, row.before_path, row.after_path)
+            if last_success and (
+                row.last_completed_at is None or _aware(row.last_completed_at) < last_success
+            ):
+                row.last_completed_at = last_success
+                db.commit()
+            if not _is_due(row, last_success, now):
+                continue
+            if _enqueue_pair(db, row):
+                queued += 1
+        if queued:
+            logger.info("Auto-detect tick queued %d pair(s)", queued)
+    except Exception:
+        logger.exception("Auto-detect tick failed")
+        db.rollback()
+        queued = 0
+    finally:
+        db.close()
+        _tick_lock.release()
+    if queued:
+        from .job_runner import start_next_queued_job
+        start_next_queued_job()
+    return queued
+
+
+def mark_schedule_from_job(job_id: int, *, status: str, run_id: Optional[int], error: str = "") -> None:
+    db = SessionLocal()
+    try:
+        job = db.query(DetectionJob).filter(DetectionJob.id == job_id).first()
+        if not is_auto_schedule_job(job):
+            # Manual success for the same paths still postpones the next auto run.
+            if status == "completed" and job:
+                try:
+                    params = json.loads(job.params_json or "{}")
+                except json.JSONDecodeError:
+                    return
+                key = pair_key_for(params.get("base_path", ""), params.get("comparison_path", ""))
+                row = db.query(AutoPairSchedule).filter(AutoPairSchedule.pair_key == key).first()
+                if row:
+                    row.last_completed_at = _utcnow()
+                    row.last_job_id = job_id
+                    if run_id:
+                        row.last_run_id = run_id
+                    row.last_error = ""
+                    db.commit()
+            return
+        try:
+            params = json.loads(job.params_json or "{}")
+        except json.JSONDecodeError:
+            params = {}
+        key = params.get("pair_key") or pair_key_for(
+            params.get("base_path", ""), params.get("comparison_path", ""))
+        row = db.query(AutoPairSchedule).filter(AutoPairSchedule.pair_key == key).first()
+        if not row:
+            return
+        row.last_job_id = job_id
+        if status == "completed":
+            row.last_completed_at = _utcnow()
+            row.last_run_id = run_id
+            row.last_error = ""
+        else:
+            row.last_error = (error or "")[:2000]
+        db.commit()
+    except Exception:
+        logger.exception("Could not update auto-detect schedule for job %s", job_id)
+        db.rollback()
+    finally:
+        db.close()
+
+
+def refresh_schedule_rows() -> None:
+    """Create/update schedule rows from identified pairs without enqueueing jobs."""
+    db = SessionLocal()
+    try:
+        pairs = _load_identified_pairs(db)
+        _sync_schedules(db, pairs)
+    except Exception:
+        logger.exception("Auto-detect schedule sync failed")
+        db.rollback()
+    finally:
+        db.close()
+
+
+def schedule_status_payload(db: Session) -> dict:
+    settings = get_or_create_settings(db)
+    interval = clamp_interval_days(settings.interval_days)
+    feature_on = auto_detect_enabled()
+    armed = bool(settings.running) and feature_on
+    next_run = _aware(settings.next_run_at)
+    rows = db.query(AutoPairSchedule).order_by(AutoPairSchedule.group_label.asc()).all()
+    out = []
+    for row in rows:
+        last = _aware(row.last_completed_at)
+        job = db.query(DetectionJob).filter(DetectionJob.id == row.last_job_id).first() if row.last_job_id else None
+        out.append({
+            "pairKey": row.pair_key,
+            "label": row.group_label,
+            "beforePath": row.before_path,
+            "afterPath": row.after_path,
+            "enabled": bool(row.enabled) and armed,
+            "intervalDays": interval,
+            "lastCompletedAt": last.isoformat() if last else None,
+            "nextDueAt": next_run.isoformat() if next_run and armed else None,
+            "dueNow": False,
+            "lastJobId": row.last_job_id,
+            "lastRunId": row.last_run_id,
+            "lastJobStatus": job.status if job else None,
+            "lastError": row.last_error or "",
+        })
+    return {
+        "enabled": feature_on,
+        "running": armed,
+        "intervalDays": interval,
+        "runAt": parse_run_at(settings.run_at),
+        "nextRunAt": next_run.isoformat() if next_run and armed else None,
+        "pairs": out,
+    }
+
+
+def start_schedule(*, interval_days: int, run_at: str) -> dict:
+    if not auto_detect_enabled():
+        raise ValueError("Automatic detection is disabled on the server.")
+    db = SessionLocal()
+    try:
+        refresh_schedule_rows()
+        settings = get_or_create_settings(db)
+        settings.interval_days = clamp_interval_days(interval_days)
+        settings.run_at = parse_run_at(run_at)
+        settings.running = True
+        settings.next_run_at = next_run_at_from_clock(settings.run_at)
+        settings.updated_at = _utcnow()
+        db.commit()
+        payload = schedule_status_payload(db)
+        logger.info(
+            "Auto-detect started: interval=%d day(s) at %s IST; first queue %s (not now)",
+            settings.interval_days, settings.run_at, settings.next_run_at,
+        )
+        return payload
+    finally:
+        db.close()
+
+
+def stop_schedule() -> dict:
+    db = SessionLocal()
+    try:
+        settings = get_or_create_settings(db)
+        settings.running = False
+        settings.next_run_at = None
+        settings.updated_at = _utcnow()
+        db.commit()
+        cancel_queued_auto_jobs(
+            db,
+            "Cancelled because automatic schedule was stopped.",
+        )
+        logger.info("Auto-detect stopped; queued auto jobs cancelled")
+        return schedule_status_payload(db)
+    finally:
+        db.close()
+
+
+def _maybe_fire_scheduled_tick() -> None:
+    if not scheduler_is_armed():
+        return
+    db = SessionLocal()
+    try:
+        settings = get_or_create_settings(db)
+        due_at = _aware(settings.next_run_at)
+        if not due_at or _utcnow() < due_at:
+            return
+        slot = due_at
+        settings.next_run_at = slot + timedelta(days=clamp_interval_days(settings.interval_days))
+        db.commit()
+    except Exception:
+        logger.exception("Auto-detect schedule clock failed")
+        db.rollback()
+        return
+    finally:
+        db.close()
+    tick_auto_detect()
+
+
+def _scheduler_loop() -> None:
+    while True:
+        threading.Event().wait(20)
+        try:
+            _maybe_fire_scheduled_tick()
+        except Exception:
+            logger.exception("Auto-detect waiter failed")
+
+
+def reset_schedule_on_process_start() -> None:
+    """Disarm the queue and cancel leftover auto jobs. Safe to call twice."""
+    db = SessionLocal()
+    try:
+        settings = get_or_create_settings(db)
+        settings.running = False
+        settings.next_run_at = None
+        db.commit()
+        cancel_queued_auto_jobs(
+            db,
+            "Cancelled on server start. Automatic detection does not run until you click Start.",
+        )
+    except Exception:
+        logger.exception("Could not reset auto-detect on launch")
+        db.rollback()
+    finally:
+        db.close()
+
+
+def start_auto_detect_scheduler() -> None:
+    """Start the idle waiter. Never enqueues jobs on launch."""
+    global _scheduler_started
+    reset_schedule_on_process_start()
+
+    if not auto_detect_enabled():
+        logger.info("Automatic pair detection feature disabled")
+        return
+    with _scheduler_lock:
+        if _scheduler_started:
+            return
+        _scheduler_started = True
+    logger.info(
+        "Automatic detection is idle. Set interval/time on the Automatic tab and click Start."
+    )
+    threading.Thread(target=_scheduler_loop, daemon=True, name="dda-auto-detect").start()

app/dda/bootstrap.py

@@ -0,0 +1,217 @@
+import logging
+
+from fastapi import FastAPI
+from sqlalchemy import text as sa_text
+
+from ..database import engine
+from .config import IS_DDA_MODE, ensure_library_dirs, get_storage_root, is_hf_hosted
+from .admin_routes import router as admin_router
+from .dashboard_routes import router as dashboard_router
+from .jobs_routes import router as jobs_router
+from .library_routes import router as library_router
+from .local_routes import router as local_router
+from .reports_routes import router as reports_router
+from .review_routes import router as review_router
+from .training_routes import router as training_router
+from .tree.routes import router as tree_router
+from .rbac.routes import router as rbac_router
+from .masters_routes import router as masters_router
+from .logs_routes import router as logs_router
+from .audit_routes import router as audit_router
+from .exception_routes import router as exception_router
+from .dda_auth import seed_dda_admin
+
+logger = logging.getLogger(__name__)
+
+
+def _migrate_detection_jobs_nullable() -> None:
+    """SQLite legacy schema required image asset FKs; tree library jobs use paths only.
+
+    SQLite-only: rebuilds the table via SQLite's PRAGMA/copy-and-rename
+    pattern because SQLite can't ALTER COLUMN to drop NOT NULL directly.
+    Irrelevant on MySQL/PostgreSQL — a fresh create_all() there already
+    creates the column with the current (nullable) definition, and neither
+    speaks SQLite's PRAGMA dialect, so skip cleanly instead of erroring.
+    """
+    if engine.dialect.name != "sqlite":
+        return
+    try:
+        with engine.connect() as conn:
+            rows = conn.execute(sa_text("PRAGMA table_info(dda_detection_jobs)")).fetchall()
+            if not rows:
+                return
+            by_name = {r[1]: r for r in rows}
+            base_col = by_name.get("base_image_id")
+            if not base_col or base_col[3] == 0:
+                return
+            logger.info("Migrating dda_detection_jobs to allow NULL image IDs for path-based jobs")
+            conn.execute(sa_text("PRAGMA foreign_keys=OFF"))
+            conn.execute(sa_text("""
+                CREATE TABLE dda_detection_jobs_new (
+                    id INTEGER NOT NULL PRIMARY KEY,
+                    status VARCHAR(32),
+                    base_image_id INTEGER,
+                    comparison_image_id INTEGER,
+                    method VARCHAR(64),
+                    params_json TEXT,
+                    run_id INTEGER,
+                    error_message TEXT,
+                    notify_email VARCHAR(255),
+                    created_by INTEGER,
+                    started_at DATETIME,
+                    completed_at DATETIME,
+                    created_at DATETIME,
+                    FOREIGN KEY(base_image_id) REFERENCES dda_image_assets (id),
+                    FOREIGN KEY(comparison_image_id) REFERENCES dda_image_assets (id),
+                    FOREIGN KEY(run_id) REFERENCES detection_runs (id),
+                    FOREIGN KEY(created_by) REFERENCES users (id)
+                )
+            """))
+            conn.execute(sa_text("""
+                INSERT INTO dda_detection_jobs_new (
+                    id, status, base_image_id, comparison_image_id, method, params_json,
+                    run_id, error_message, notify_email, created_by,
+                    started_at, completed_at, created_at
+                )
+                SELECT
+                    id, status, base_image_id, comparison_image_id, method, params_json,
+                    run_id, error_message, notify_email, created_by,
+                    started_at, completed_at, created_at
+                FROM dda_detection_jobs
+            """))
+            conn.execute(sa_text("DROP TABLE dda_detection_jobs"))
+            conn.execute(sa_text("ALTER TABLE dda_detection_jobs_new RENAME TO dda_detection_jobs"))
+            conn.execute(sa_text("PRAGMA foreign_keys=ON"))
+            conn.commit()
+    except Exception as exc:
+        logger.warning("Detection jobs nullable migration skipped: %s", exc)
+
+
+def init_dda_database():
+    """Run DDA-specific startup tasks (dirs, seed, migrations)."""
+    if not IS_DDA_MODE:
+        return
+    ensure_library_dirs()
+    get_storage_root().mkdir(parents=True, exist_ok=True)
+    logger.info("DDA database dialect=%s", engine.dialect.name)
+    try:
+        with engine.connect() as conn:
+            for stmt in (
+                "ALTER TABLE users ADD COLUMN role VARCHAR(32) DEFAULT 'analyst'",
+                "ALTER TABLE users ADD COLUMN role_id INTEGER DEFAULT NULL",
+                "ALTER TABLE users ADD COLUMN totp_secret VARCHAR(64) DEFAULT NULL",
+                "ALTER TABLE users ADD COLUMN totp_enabled INTEGER DEFAULT 0",
+                "ALTER TABLE users ADD COLUMN totp_confirmed_at DATETIME DEFAULT NULL",
+                "ALTER TABLE users ADD COLUMN phone VARCHAR(20) DEFAULT NULL",
+                "ALTER TABLE detection_runs ADD COLUMN after_full_path VARCHAR(512) DEFAULT ''",
+                "ALTER TABLE dda_roles ADD COLUMN is_active BOOLEAN DEFAULT 1",
+                "ALTER TABLE dda_audit_logs ADD COLUMN role VARCHAR(64) DEFAULT ''",
+                "ALTER TABLE dda_audit_logs ADD COLUMN module VARCHAR(64) DEFAULT ''",
+            ):
+                try:
+                    conn.execute(sa_text(stmt))
+                    conn.commit()
+                except Exception:
+                    conn.rollback()
+            try:
+                conn.execute(sa_text(
+                    "CREATE UNIQUE INDEX IF NOT EXISTS ix_users_phone ON users (phone)"
+                ))
+                conn.commit()
+            except Exception:
+                conn.rollback()
+            try:
+                conn.execute(sa_text(
+                    "CREATE UNIQUE INDEX IF NOT EXISTS ix_dda_region_reviews_run_region "
+                    "ON dda_region_reviews (run_id, region_id)"
+                ))
+                conn.commit()
+            except Exception:
+                conn.rollback()
+            _migrate_detection_jobs_nullable()
+    except Exception as exc:
+        logger.warning("DDA schema migration skipped: %s", exc)
+
+    from ..database import Base, SessionLocal
+    from .tree.models import AuditLog, ExceptionLog, ImageLibrary, TreeNode  # noqa: F401
+    try:
+        Base.metadata.create_all(bind=engine, tables=[
+            TreeNode.__table__,
+            ImageLibrary.__table__,
+            AuditLog.__table__,
+            ExceptionLog.__table__,
+        ])
+    except Exception as exc:
+        logger.warning("Tree table create skipped: %s", exc)
+
+    db = SessionLocal()
+    try:
+        seed_dda_admin(db)
+        from .rbac.seed import seed_rbac
+        try:
+            seed_rbac(db)
+        except Exception as exc:
+            logger.warning("RBAC seed skipped: %s", exc)
+        try:
+            from .seed import seed_delhi_hierarchy
+            seed_delhi_hierarchy(db)
+        except Exception as exc:
+            logger.warning("Zone/village seed skipped: %s", exc)
+        from .tree.migration import run_tree_migration
+        mig = run_tree_migration(db)
+        logger.info("Tree migration: %s", mig)
+        from .auto_detect import reset_schedule_on_process_start
+        reset_schedule_on_process_start()
+        from .job_runner import reconcile_stale_jobs
+        reconcile_stale_jobs(db)
+    finally:
+        db.close()
+
+    def _fs_sync_worker():
+        from ..database import SessionLocal as SL
+        from .tree.image_service import count_library_images
+        from .tree.sync_service import sync_from_filesystem
+
+        sdb = SL()
+        try:
+            try:
+                sync_stats = sync_from_filesystem(sdb, check_orphans=False)
+                logger.info("Filesystem sync at startup: %s", sync_stats)
+            except Exception as exc:
+                logger.warning("Filesystem sync at startup failed: %s", exc)
+            try:
+                total = count_library_images(sdb)
+                logger.info(
+                    "DDA tree library ready (hosted=%s): %d images, storage=%s",
+                    is_hf_hosted(),
+                    total,
+                    get_storage_root(),
+                )
+            except Exception as exc:
+                logger.warning("Tree library scan at startup failed: %s", exc)
+        finally:
+            sdb.close()
+
+    import threading
+    threading.Thread(target=_fs_sync_worker, daemon=True, name="dda-fs-sync").start()
+
+
+def setup_dda(app: FastAPI) -> None:
+    if not IS_DDA_MODE:
+        logger.info("APP_MODE=legacy — DDA routes disabled")
+        return
+    app.include_router(tree_router, prefix="/api/dda", tags=["dda-tree"])
+    app.include_router(library_router, prefix="/api/dda", tags=["dda"])
+    app.include_router(jobs_router, prefix="/api/dda", tags=["dda-jobs"])
+    app.include_router(reports_router, prefix="/api/dda", tags=["dda-reports"])
+    app.include_router(review_router, prefix="/api/dda", tags=["dda-review"])
+    app.include_router(training_router, prefix="/api/dda", tags=["dda-training"])
+    app.include_router(admin_router, prefix="/api/dda", tags=["dda-admin"])
+    app.include_router(local_router, prefix="/api/dda", tags=["dda-local"])
+    app.include_router(rbac_router, prefix="/api/dda", tags=["dda-rbac"])
+    app.include_router(dashboard_router, prefix="/api/dda", tags=["dda-dashboard"])
+    app.include_router(masters_router, prefix="/api/dda", tags=["dda-masters"])
+    app.include_router(logs_router, prefix="/api/dda", tags=["dda-logs"])
+    app.include_router(audit_router, prefix="/api/dda", tags=["dda-audit"])
+    app.include_router(exception_router, prefix="/api/dda", tags=["dda-exceptions"])
+    logger.info("APP_MODE=dda — DDA routes enabled (tree, library, jobs, reports, review, training, admin, local, rbac, dashboard, masters, logs)")

app/dda/change_type_map.py

@@ -0,0 +1,46 @@
+"""Map internal detection_engine labels → Vedangsoft report change types (FR-04)."""
+from __future__ import annotations
+
+from typing import Optional
+
+DDA_NEW_CONSTRUCTION = "New Construction"
+DDA_DEMOLITION = "Demolition"
+DDA_EXTENSION = "Extension"
+DDA_VEGETATION = "Vegetation Change"
+DDA_OTHER = "Other"
+
+_KEYWORDS = [
+    (DDA_DEMOLITION, ("demolition", "clearing", "removed", "debris")),
+    (DDA_EXTENSION, ("expansion", "widening", "extension", "renovation", "addition")),
+    (DDA_VEGETATION, ("vegetation", "tree", "forest", "green", "crop")),
+    (DDA_NEW_CONSTRUCTION, (
+        "construction", "building", "structure", "road", "pavement",
+        "temporary", "roof", "concrete", "foundation", "solar", "panel",
+        "industrial",
+    )),
+    # Bare/soil/water only — do NOT match the substring "land" alone (too broad).
+    (DDA_OTHER, ("water body", "bare land", "bare earth", "soil change")),
+]
+
+
+def map_to_dda_change_type(internal_type: str) -> str:
+    """Return canonical Vedangsoft change type for a detection_engine object_type string."""
+    if not internal_type:
+        return DDA_OTHER
+    lower = internal_type.lower()
+    for dda_type, keywords in _KEYWORDS:
+        if any(kw in lower for kw in keywords):
+            return dda_type
+    if "new" in lower:
+        return DDA_NEW_CONSTRUCTION
+    return DDA_OTHER
+
+
+def enrich_region_for_dda(region: dict, *, dda_change_type: Optional[str] = None) -> dict:
+    """Add Vedangsoft report fields to a serialized region dict."""
+    internal = region.get("objectType") or region.get("object_type") or ""
+    out = dict(region)
+    out["ddaChangeType"] = dda_change_type or map_to_dda_change_type(internal)
+    out["internalObjectType"] = internal
+    out["reviewStatus"] = region.get("reviewStatus", "pending")
+    return out

app/dda/config.py

@@ -0,0 +1,138 @@
+import os
+from pathlib import Path
+from typing import List
+
+from ..database import DATA_DIR
+
+APP_MODE_RAW = os.environ.get("APP_MODE", "").strip().lower()
+_SPACE_ID = os.environ.get("SPACE_ID", "").strip().lower()
+
+
+def is_hf_hosted() -> bool:
+    return bool(_SPACE_ID)
+
+
+def _is_dda_mode() -> bool:
+    if APP_MODE_RAW == "legacy":
+        return False
+    if APP_MODE_RAW == "dda":
+        return True
+    # APP_MODE unset: auto-enable on satdetect-dev only (production satdetect stays legacy)
+    return _SPACE_ID.endswith("/satdetect-dev")
+
+
+def get_public_base_url() -> str:
+    """Public URL for deep links (email, share). Override with PUBLIC_BASE_URL."""
+    explicit = os.environ.get("PUBLIC_BASE_URL", "").strip().rstrip("/")
+    if explicit:
+        return explicit
+    if _SPACE_ID:
+        return f"https://{_SPACE_ID.replace('/', '-')}.hf.space"
+    return "http://localhost:7860"
+
+
+IS_DDA_MODE = _is_dda_mode()
+APP_MODE = APP_MODE_RAW or ("dda" if IS_DDA_MODE else "legacy")
+
+
+# Project root: change_detection_webapp/
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+
+
+def get_writable_library_root() -> Path:
+    """Persistent folder for uploads (HF: /home/appuser/data/library_sources)."""
+    return (DATA_DIR / "library_sources").resolve()
+
+
+def get_storage_root() -> Path:
+    """Tree library root (doc: root_directory / STORAGE_ROOT)."""
+    explicit = os.environ.get("STORAGE_ROOT", "").strip()
+    if explicit:
+        return Path(explicit).resolve()
+    if os.environ.get("LOCAL_LIBRARY_ROOT"):
+        return Path(os.environ["LOCAL_LIBRARY_ROOT"]).resolve()
+    return get_writable_library_root()
+
+
+def get_library_roots() -> List[Path]:
+    """Folders scanned for library images (tree storage root)."""
+    roots: List[Path] = []
+    sr = get_storage_root()
+    if sr not in roots:
+        roots.append(sr)
+    if os.environ.get("LOCAL_LIBRARY_ROOT"):
+        p = Path(os.environ["LOCAL_LIBRARY_ROOT"]).resolve()
+        if p not in roots:
+            roots.append(p)
+    if is_hf_hosted():
+        wr = get_writable_library_root()
+        if wr not in roots:
+            roots.append(wr)
+    for candidate in (get_writable_library_root(), PROJECT_ROOT / "library_sources"):
+        resolved = candidate.resolve()
+        if resolved not in roots:
+            roots.append(resolved)
+    return roots
+
+
+# Primary root (shown in UI) — first entry from get_library_roots()
+LOCAL_LIBRARY_ROOT = get_library_roots()[0]
+
+LIBRARY_DIR = DATA_DIR / "library"
+THUMBS_DIR = LIBRARY_DIR / "thumbs"
+PREVIEWS_DIR = LIBRARY_DIR / "previews"
+LOCAL_THUMB_CACHE = DATA_DIR / "library_cache" / "thumbs"
+
+# Library upload limit (default 15 GB; override with MAX_GEOTIFF_MB / MAX_IMAGE_MB)
+_MAX_UPLOAD_MB_DEFAULT = "15360"  # 15 * 1024
+MAX_GEOTIFF_BYTES = int(os.environ.get("MAX_GEOTIFF_MB", _MAX_UPLOAD_MB_DEFAULT)) * 1024 * 1024
+
+# PNG/JPEG use the same cap unless MAX_IMAGE_MB is set separately
+MAX_IMAGE_BYTES = int(os.environ.get("MAX_IMAGE_MB", _MAX_UPLOAD_MB_DEFAULT)) * 1024 * 1024
+
+ALLOWED_EXTENSIONS = {".tif", ".tiff", ".png", ".jpg", ".jpeg"}
+
+
+def ensure_library_dirs() -> None:
+    for root in get_library_roots():
+        try:
+            root.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            pass
+    for d in (LIBRARY_DIR, THUMBS_DIR, PREVIEWS_DIR, LOCAL_THUMB_CACHE):
+        try:
+            d.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            pass
+
+
+def ensure_local_year_folders() -> None:
+    """Create default year folders under each library root if missing."""
+    from datetime import datetime
+    current = datetime.now().year
+    for root in get_library_roots():
+        for year in (current - 1, current, current + 1):
+            try:
+                (root / str(year)).mkdir(parents=True, exist_ok=True)
+            except OSError:
+                pass
+
+
+def max_upload_bytes_for_extension(ext: str) -> int:
+    if ext in (".tif", ".tiff"):
+        return MAX_GEOTIFF_BYTES
+    return MAX_IMAGE_BYTES
+
+
+def geotiff_io_available() -> bool:
+    try:
+        import rasterio  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def get_detection_max_side() -> int:
+    """Max pixel dimension for GeoTIFF load + detection pipeline (higher = sharper, more RAM)."""
+    from ..detection_config import get_detection_max_side as _central
+    return _central()

app/dda/dashboard_routes.py

@@ -0,0 +1,343 @@
+"""Dashboard aggregation API.
+
+Backs the app's home dashboard (Change Detection Overview, region/village
+breakdowns, location comparisons, trend, recent reports). Scoped to the
+requesting user the same way /api/history and reports.js are — own runs
+plus any auto-scheduled runs everyone can see — so two different users see
+different dashboards, exactly like they already see different Reports lists.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import or_
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models import DetectionRun, User
+from .auto_detect import is_auto_schedule_job
+from .dda_auth import current_dda_user
+from .models import DetectionJob
+from .review_service import bulk_classification_counts
+
+router = APIRouter()
+
+UNASSIGNED = "Unassigned"
+DEFAULT_ROLE = "analyst"
+
+# Matches DEFAULT_ROLES rank order in app/dda/rbac/seed.py — keeps the role
+# breakdown in a stable, meaningful order instead of alphabetical/count order.
+ROLE_ORDER = ["viewer", "uploader", "analyst", "admin"]
+
+MONTH_NAMES = ["", "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+
+_IST = timezone(timedelta(hours=5, minutes=30))
+
+
+def _isoformat_ist(dt):
+    """Same conversion as detect_service._isoformat_ist, duplicated locally
+    to avoid importing detect_service (which pulls in geo_regions) just for
+    date formatting."""
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(_IST).isoformat()
+
+
+def _require_dda():
+    from .config import IS_DDA_MODE
+    if not IS_DDA_MODE:
+        raise HTTPException(status_code=404, detail="DDA mode is not enabled")
+
+
+def _run_thumbs(run: DetectionRun) -> dict:
+    return {
+        "overlayUrl": f"/api/overlay/{run.overlay_path}" if run.overlay_path else None,
+        "beforeThumbUrl": f"/api/overlay/{run.before_thumb_path}" if (run.before_thumb_path or "").strip() else None,
+        "afterThumbUrl": f"/api/overlay/{run.after_thumb_path}" if (run.after_thumb_path or "").strip() else None,
+    }
+
+
+def _run_summary(row: dict) -> dict:
+    run = row["run"]
+    return {
+        "id": run.id,
+        "title": run.title,
+        "zone": row["zone"],
+        "village": row["village"],
+        "role": row["role"],
+        "method": run.method,
+        "changePercentage": run.change_percentage,
+        "regionsCount": run.regions_count or 0,
+        "unclassified": row["unclassified"],
+        "confirmed": row["confirmed"],
+        "falsePositive": row["falsePositive"],
+        "createdAt": _isoformat_ist(run.created_at),
+        **_run_thumbs(run),
+    }
+
+
+def _accessible_run_filter(db: Session, user: User):
+    """Same run-visibility rule as GET /api/history in app/main.py: the
+    user's own runs, plus any run that came from the auto-schedule (visible
+    to everyone, not just whoever happened to be logged in when it fired)."""
+    auto_ids = [
+        j.run_id for j in (
+            db.query(DetectionJob)
+            .filter(DetectionJob.run_id.isnot(None))
+            .order_by(DetectionJob.id.desc())
+            .limit(200)
+            .all()
+        )
+        if is_auto_schedule_job(j)
+    ]
+    filt = DetectionRun.user_id == user.id
+    if auto_ids:
+        filt = or_(filt, DetectionRun.id.in_(auto_ids))
+    return filt
+
+
+def _load_dataset(db: Session, user: User) -> list[dict]:
+    """One query for every accessible run + one grouped query for
+    classification counts; every endpoint below aggregates from this in
+    Python — mirrors the simple query style already used by
+    admin_routes.admin_status(). Runs with a blank zone/village are bucketed
+    under "Unassigned" so totals reconcile.
+    """
+    runs = (
+        db.query(DetectionRun)
+        .filter(_accessible_run_filter(db, user))
+        .order_by(DetectionRun.created_at.asc())
+        .all()
+    )
+    counts = bulk_classification_counts(db)
+    # Same role resolution as dda_auth.get_user_role (raw User.role string,
+    # falling back to "analyst") but bulk-loaded to avoid a query per run.
+    roles_by_user = {uid: (role or DEFAULT_ROLE) for uid, role in db.query(User.id, User.role).all()}
+    rows = []
+    for run in runs:
+        c = counts.get(run.id, {})
+        classified = c.get("confirmed", 0) + c.get("false_positive", 0) + c.get("submitted", 0)
+        unclassified = max(0, (run.regions_count or 0) - classified)
+        rows.append({
+            "run": run,
+            "zone": (run.zone or "").strip() or UNASSIGNED,
+            "village": (run.village or "").strip() or UNASSIGNED,
+            "role": roles_by_user.get(run.user_id, DEFAULT_ROLE),
+            "confirmed": c.get("confirmed", 0),
+            "falsePositive": c.get("false_positive", 0),
+            "submitted": c.get("submitted", 0),
+            "unclassified": unclassified,
+        })
+    return rows
+
+
+@router.get("/dashboard/summary")
+def dashboard_summary(db: Session = Depends(get_db), user: User = Depends(current_dda_user)):
+    _require_dda()
+    rows = _load_dataset(db, user)
+
+    total_detected = sum((r["run"].regions_count or 0) for r in rows)
+    pct_values = [r["run"].change_percentage for r in rows if r["run"].change_percentage is not None]
+    zones = {r["zone"] for r in rows}
+    villages = {(r["zone"], r["village"]) for r in rows}
+
+    return {
+        "totalRuns": len(rows),
+        "totalDetectedChanges": total_detected,
+        "totalUnclassified": sum(r["unclassified"] for r in rows),
+        "totalConfirmed": sum(r["confirmed"] for r in rows),
+        "totalFalsePositive": sum(r["falsePositive"] for r in rows),
+        "totalSubmitted": sum(r["submitted"] for r in rows),
+        "avgChangePercentage": round(sum(pct_values) / len(pct_values), 2) if pct_values else None,
+        "totalRegions": len(zones),
+        "totalVillages": len(villages),
+        "jobsQueued": db.query(DetectionJob).filter(DetectionJob.status == "queued", DetectionJob.created_by == user.id).count(),
+        "jobsRunning": db.query(DetectionJob).filter(DetectionJob.status == "running", DetectionJob.created_by == user.id).count(),
+        "latestRun": _run_summary(rows[-1]) if rows else None,
+    }
+
+
+@router.get("/dashboard/regions")
+def dashboard_regions(db: Session = Depends(get_db), user: User = Depends(current_dda_user)):
+    _require_dda()
+    rows = _load_dataset(db, user)
+    by_zone: dict[str, list] = defaultdict(list)
+    for r in rows:
+        by_zone[r["zone"]].append(r)
+
+    out = []
+    for zone, items in by_zone.items():
+        pct_values = [i["run"].change_percentage for i in items if i["run"].change_percentage is not None]
+        out.append({
+            "zone": zone,
+            "runsCount": len(items),
+            "detectedChanges": sum((i["run"].regions_count or 0) for i in items),
+            "unclassified": sum(i["unclassified"] for i in items),
+            "confirmed": sum(i["confirmed"] for i in items),
+            "falsePositive": sum(i["falsePositive"] for i in items),
+            "avgChangePercentage": round(sum(pct_values) / len(pct_values), 2) if pct_values else None,
+            "villagesCount": len({i["village"] for i in items}),
+            "lastDetectionAt": _isoformat_ist(max(i["run"].created_at for i in items)),
+        })
+    out.sort(key=lambda x: x["runsCount"], reverse=True)
+    return {"regions": out}
+
+
+@router.get("/dashboard/roles")
+def dashboard_roles(db: Session = Depends(get_db), user: User = Depends(current_dda_user)):
+    """Detection activity grouped by the role of the user who ran it."""
+    _require_dda()
+    rows = _load_dataset(db, user)
+    by_role: dict[str, list] = defaultdict(list)
+    for r in rows:
+        by_role[r["role"]].append(r)
+
+    def _rank(role: str) -> int:
+        return ROLE_ORDER.index(role) if role in ROLE_ORDER else len(ROLE_ORDER)
+
+    out = []
+    for role, items in by_role.items():
+        pct_values = [i["run"].change_percentage for i in items if i["run"].change_percentage is not None]
+        out.append({
+            "role": role,
+            "runsCount": len(items),
+            "detectedChanges": sum((i["run"].regions_count or 0) for i in items),
+            "unclassified": sum(i["unclassified"] for i in items),
+            "confirmed": sum(i["confirmed"] for i in items),
+            "falsePositive": sum(i["falsePositive"] for i in items),
+            "avgChangePercentage": round(sum(pct_values) / len(pct_values), 2) if pct_values else None,
+            "usersCount": len({i["run"].user_id for i in items}),
+            "lastDetectionAt": _isoformat_ist(max(i["run"].created_at for i in items)),
+        })
+    out.sort(key=lambda x: (_rank(x["role"]), x["role"]))
+    return {"roles": out}
+
+
+@router.get("/dashboard/villages")
+def dashboard_villages(
+    zone: Optional[str] = Query(None),
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    _require_dda()
+    rows = _load_dataset(db, user)
+    if zone:
+        rows = [r for r in rows if r["zone"] == zone]
+    by_village: dict[tuple, list] = defaultdict(list)
+    for r in rows:
+        by_village[(r["zone"], r["village"])].append(r)
+
+    out = []
+    for (z, v), items in by_village.items():
+        pct_values = [i["run"].change_percentage for i in items if i["run"].change_percentage is not None]
+        out.append({
+            "zone": z,
+            "village": v,
+            "runsCount": len(items),
+            "detectedChanges": sum((i["run"].regions_count or 0) for i in items),
+            "unclassified": sum(i["unclassified"] for i in items),
+            "confirmed": sum(i["confirmed"] for i in items),
+            "falsePositive": sum(i["falsePositive"] for i in items),
+            "avgChangePercentage": round(sum(pct_values) / len(pct_values), 2) if pct_values else None,
+            "lastDetectionAt": _isoformat_ist(max(i["run"].created_at for i in items)),
+        })
+    out.sort(key=lambda x: x["runsCount"], reverse=True)
+    return {"villages": out}
+
+
+@router.get("/dashboard/trend")
+def dashboard_trend(
+    months: int = Query(6, ge=1, le=24),
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    _require_dda()
+    rows = _load_dataset(db, user)
+
+    now = datetime.now(timezone.utc)
+    keys = []
+    y, m = now.year, now.month
+    for _ in range(months):
+        keys.append((y, m))
+        m -= 1
+        if m == 0:
+            m, y = 12, y - 1
+    keys.reverse()
+
+    counts = {k: {"runsCount": 0, "detectedChanges": 0} for k in keys}
+    for r in rows:
+        dt = r["run"].created_at
+        if dt is None:
+            continue
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        key = (dt.year, dt.month)
+        if key in counts:
+            counts[key]["runsCount"] += 1
+            counts[key]["detectedChanges"] += (r["run"].regions_count or 0)
+
+    buckets = [
+        {
+            "period": f"{y}-{m:02d}",
+            "label": f"{MONTH_NAMES[m]} {y}",
+            "runsCount": counts[(y, m)]["runsCount"],
+            "detectedChanges": counts[(y, m)]["detectedChanges"],
+        }
+        for (y, m) in keys
+    ]
+    return {"buckets": buckets}
+
+
+@router.get("/dashboard/location")
+def dashboard_location(
+    zone: str = Query(...),
+    village: str = Query(...),
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    _require_dda()
+    rows = _load_dataset(db, user)
+    items = [r for r in rows if r["zone"] == zone and r["village"] == village]
+    items.sort(key=lambda r: r["run"].created_at)
+
+    history = [_run_summary(i) for i in items]
+    latest = history[-1] if history else None
+    previous = history[-2] if len(history) > 1 else None
+
+    comparison = None
+    if latest and previous:
+        comparison = {
+            "changePercentageDelta": (
+                round(latest["changePercentage"] - previous["changePercentage"], 2)
+                if latest["changePercentage"] is not None and previous["changePercentage"] is not None
+                else None
+            ),
+            "regionsCountDelta": latest["regionsCount"] - previous["regionsCount"],
+        }
+
+    return {
+        "zone": zone,
+        "village": village,
+        "runsCount": len(items),
+        "latest": latest,
+        "previous": previous,
+        "comparison": comparison,
+        "history": list(reversed(history)),
+    }
+
+
+@router.get("/dashboard/recent-reports")
+def dashboard_recent_reports(
+    limit: int = Query(8, ge=1, le=50),
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    _require_dda()
+    rows = _load_dataset(db, user)
+    rows.sort(key=lambda r: r["run"].created_at, reverse=True)
+    return {"reports": [_run_summary(r) for r in rows[:limit]]}

app/dda/dda_auth.py

@@ -0,0 +1,131 @@
+"""Vedangsoft session users and RBAC (Phase 7)."""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from fastapi import Depends, HTTPException, Request
+from sqlalchemy.orm import Session
+
+from ..auth import get_user_from_token
+from ..database import get_db
+from ..models import User
+
+COOKIE_NAME = "satellite_token"
+
+ROLE_RANK = {
+    "viewer": 0,
+    "uploader": 1,
+    "analyst": 2,
+    "admin": 3,
+}
+
+TRAINING_EXPORT_KEY = os.environ.get("DDA_TRAINING_EXPORT_KEY", "").strip()
+
+
+def get_user_role(db: Session, user: User) -> str:
+    role = getattr(user, "role", None)
+    if role:
+        return str(role)
+    try:
+        from sqlalchemy import text as sa_text
+        row = db.execute(
+            sa_text("SELECT role FROM users WHERE id = :uid"),
+            {"uid": user.id},
+        ).fetchone()
+        if row and row[0]:
+            return str(row[0])
+    except Exception:
+        pass
+    return "analyst"
+
+
+def get_dda_user(request: Request, db: Session) -> User:
+    """Resolve the logged-in user from a Bearer token or the auth cookie.
+
+    Login is required — no anonymous per-browser session or shared-guest
+    fallback anymore (removed; see git history for the prior behavior).
+    """
+    auth_header = request.headers.get("authorization", "")
+    if auth_header.lower().startswith("bearer "):
+        token = auth_header.split(" ", 1)[1].strip()
+        user = get_user_from_token(token, db)
+        if user:
+            return user
+
+    token = request.cookies.get(COOKIE_NAME)
+    if token:
+        user = get_user_from_token(token, db)
+        if user and not user.email.startswith("__guest__"):
+            return user
+
+    raise HTTPException(status_code=401, detail="Not authenticated")
+
+
+def current_dda_user(request: Request, db: Session = Depends(get_db)) -> User:
+    return get_dda_user(request, db)
+
+
+def _role_rank_from_db(db: Session, role_name: str) -> Optional[int]:
+    """Rank now lives on the dda_roles table (app/dda/rbac/models.py) so admins
+    can add/reorder roles without a code change. Falls back to None (caller
+    uses ROLE_RANK) if the table isn't seeded yet or the name isn't found."""
+    try:
+        from .rbac.models import Role
+        row = db.query(Role).filter(Role.name == role_name).first()
+        return row.rank if row else None
+    except Exception:
+        return None
+
+
+def require_min_role(user: User, db: Session, minimum: str) -> None:
+    role = get_user_role(db, user)
+    need = _role_rank_from_db(db, minimum)
+    if need is None:
+        need = ROLE_RANK.get(minimum, 99)
+    have = _role_rank_from_db(db, role)
+    if have is None:
+        have = ROLE_RANK.get(role, 0)
+    if have < need:
+        raise HTTPException(
+            status_code=403,
+            detail=f"Role '{role}' cannot perform this action (requires {minimum} or higher).",
+        )
+
+
+def require_admin_or_key(request: Request, user: User, db: Session) -> None:
+    key = request.headers.get("x-dda-training-key", "").strip()
+    if TRAINING_EXPORT_KEY and key == TRAINING_EXPORT_KEY:
+        return
+    require_min_role(user, db, "admin")
+
+
+def seed_dda_admin(db: Session) -> None:
+    """Optional admin account from env (dev/UAT)."""
+    email = os.environ.get("DDA_ADMIN_EMAIL", "").strip()
+    password = os.environ.get("DDA_ADMIN_PASSWORD", "").strip()
+    if not email or not password:
+        return
+    from ..auth import get_password_hash, get_user_by_email
+    user = get_user_by_email(db, email)
+    if not user:
+        from ..auth import normalize_phone
+        admin_phone = normalize_phone(os.environ.get("DDA_ADMIN_PHONE", ""))
+        user = User(
+            email=email,
+            hashed_password=get_password_hash(password),
+            full_name=os.environ.get("DDA_ADMIN_NAME", "Vedangsoft Admin"),
+            phone=admin_phone,
+        )
+        db.add(user)
+        db.commit()
+        db.refresh(user)
+    try:
+        from sqlalchemy import text as sa_text
+        db.execute(
+            sa_text("UPDATE users SET role = 'admin' WHERE id = :uid"),
+            {"uid": user.id},
+        )
+        db.commit()
+    except Exception:
+        db.rollback()

app/dda/dept_export.py

@@ -0,0 +1,151 @@
+"""Department export adapter — API or file fallback (FR-08)."""
+from __future__ import annotations
+
+import csv
+import io
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from ..models import DetectionRun
+from .geo_regions import region_lat_lng
+
+logger = logging.getLogger(__name__)
+
+DEPT_API_URL = os.environ.get("DEPT_API_URL", "").strip()
+DEPT_API_KEY = os.environ.get("DEPT_API_KEY", "").strip()
+
+
+@dataclass
+class ExportResult:
+    ok: bool
+    mode: str  # api | file
+    message: str
+    submitted_count: int = 0
+    download_path: Optional[str] = None
+    detail: Optional[Dict[str, Any]] = None
+
+
+def regions_to_csv_rows(run: DetectionRun, regions: List[dict]) -> str:
+    """Build CSV string for export."""
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    writer.writerow([
+        "run_id", "run_title", "zone", "village", "region_id",
+        "dda_change_type", "internal_type", "confidence", "area_px",
+        "latitude", "longitude", "area_sq_m", "review_status", "notes",
+    ])
+    for r in regions:
+        lat, lng = region_lat_lng(r)
+        writer.writerow([
+            run.id,
+            run.title,
+            run.zone or "",
+            run.village or "",
+            r.get("id", ""),
+            r.get("ddaChangeType") or "",
+            r.get("internalObjectType") or r.get("objectType") or "",
+            f'{(r.get("confidence") or 0):.4f}',
+            r.get("area", ""),
+            lat if lat is not None else "",
+            lng if lng is not None else "",
+            r.get("areaSqM") if r.get("areaSqM") is not None else "",
+            r.get("reviewStatus") or "pending",
+            r.get("reviewNotes") or "",
+        ])
+    return buf.getvalue()
+
+
+class FileExporter:
+    """Fallback — client downloads CSV via API."""
+
+    def submit(self, run: DetectionRun, regions: List[dict]) -> ExportResult:
+        if not regions:
+            return ExportResult(
+                ok=False,
+                mode="file",
+                message="No confirmed regions to export.",
+                submitted_count=0,
+            )
+        return ExportResult(
+            ok=True,
+            mode="file",
+            message=f"{len(regions)} confirmed region(s) ready for CSV download.",
+            submitted_count=len(regions),
+            download_path=f"/api/dda/reports/{run.id}/export.csv?confirmed=1",
+        )
+
+
+class ApiExporter:
+    """POST confirmed changes to departmental API."""
+
+    def __init__(self, url: str, api_key: str = ""):
+        self.url = url.rstrip("/")
+        self.api_key = api_key
+
+    def submit(self, run: DetectionRun, regions: List[dict]) -> ExportResult:
+        if not regions:
+            return ExportResult(
+                ok=False,
+                mode="api",
+                message="No confirmed regions to submit.",
+            )
+        payload = {
+            "runId": run.id,
+            "title": run.title,
+            "zone": run.zone or "",
+            "village": run.village or "",
+            "changePercentage": run.change_percentage,
+            "regions": [
+                {
+                    "id": r.get("id"),
+                    "ddaChangeType": r.get("ddaChangeType"),
+                    "objectType": r.get("objectType"),
+                    "confidence": r.get("confidence"),
+                    "area": r.get("area"),
+                    "latitude": r.get("latitude") or (r.get("latLng") or {}).get("lat"),
+                    "longitude": r.get("longitude") or (r.get("latLng") or {}).get("lng"),
+                    "areaSqM": r.get("areaSqM"),
+                }
+                for r in regions
+            ],
+        }
+        headers = {"Content-Type": "application/json", "Accept": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        try:
+            resp = requests.post(self.url, json=payload, headers=headers, timeout=60)
+            if 200 <= resp.status_code < 300:
+                detail = None
+                try:
+                    detail = resp.json()
+                except Exception:
+                    detail = {"body": resp.text[:500]}
+                return ExportResult(
+                    ok=True,
+                    mode="api",
+                    message=f"Submitted {len(regions)} confirmed region(s) to departmental system.",
+                    submitted_count=len(regions),
+                    detail=detail,
+                )
+            return ExportResult(
+                ok=False,
+                mode="api",
+                message=f"Department API returned {resp.status_code}: {resp.text[:200]}",
+            )
+        except Exception as exc:
+            logger.exception("Department API submit failed")
+            return ExportResult(
+                ok=False,
+                mode="api",
+                message=f"Department API error: {exc}",
+            )
+
+
+def get_exporter() -> FileExporter | ApiExporter:
+    if DEPT_API_URL:
+        return ApiExporter(DEPT_API_URL, DEPT_API_KEY)
+    return FileExporter()

app/dda/detect_service.py

@@ -0,0 +1,490 @@
+"""Run change detection and persist results (shared by upload + library paths)."""
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import uuid
+from datetime import timezone
+from pathlib import Path
+from typing import Optional
+
+from PIL import Image
+from sqlalchemy.orm import Session
+
+from ..auth import get_or_create_guest_user
+from ..database import DATA_DIR
+from ..models import DetectionRun
+from ..notifier import send_notification
+from .geo_regions import enrich_regions_geo, resolve_geo_context
+
+logger = logging.getLogger(__name__)
+
+OVERLAYS_DIR = DATA_DIR / "overlays"
+THUMB_MAX_SIZE = 200
+
+
+MAX_POLYGON_VERTICES = 100
+
+
+def _serialize_polygon(raw) -> Optional[list]:
+    """Normalize an engine polygon to ``[[x, y], ...]`` ints, or None.
+
+    The engine emits an outer ring in detection-image pixels. Defensively caps
+    the vertex count (the extractor also limits, but region JSON is stored per
+    run and a runaway contour would bloat every report that loads it) by
+    keeping evenly-spaced vertices so the footprint's shape survives.
+    """
+    if not raw:
+        return None
+    try:
+        pts = [(int(round(float(p[0]))), int(round(float(p[1])))) for p in raw]
+    except (TypeError, ValueError, IndexError):
+        logger.warning("Ignoring malformed polygon on region")
+        return None
+    if len(pts) < 3:
+        return None
+    if len(pts) > MAX_POLYGON_VERTICES:
+        step = len(pts) / float(MAX_POLYGON_VERTICES)
+        pts = [pts[min(len(pts) - 1, int(i * step))] for i in range(MAX_POLYGON_VERTICES)]
+    return [[x, y] for x, y in pts]
+
+
+def _serialize_regions(change_regions) -> list:
+    out = []
+    for r in change_regions:
+        entry = {
+            "id": int(r["id"]),
+            "area": int(r["area"]),
+            "center": {"x": round(float(r["center"][0])), "y": round(float(r["center"][1]))},
+            "bbox": {
+                "x": int(r["bbox"][0]),
+                "y": int(r["bbox"][1]),
+                "w": int(r["bbox"][2]),
+                "h": int(r["bbox"][3]),
+            },
+            "objectType": str(r["object_type"]),
+            "confidence": float(r["confidence"]),
+            "severity": r.get("severity", "minor"),
+            "subType": r.get("sub_type"),
+            "subTypeConfidence": float(r["sub_type_confidence"])
+            if r.get("sub_type_confidence") is not None
+            else None,
+            "estimatedStories": r.get("estimated_stories"),
+            "estimatedHeightM": float(r["estimated_height_m"])
+            if r.get("estimated_height_m") is not None
+            else None,
+            "constructionStage": r.get("construction_stage"),
+        }
+        # Polygon is optional: regions without one serialize exactly as before,
+        # and every consumer falls back to bbox.
+        polygon = _serialize_polygon(r.get("polygon"))
+        if polygon:
+            entry["polygon"] = polygon
+        out.append(entry)
+    return out
+
+
+def _filter_weak_other_regions(regions: list) -> list:
+    """Optionally mark tiny low-conf Other blobs — never drop report rows.
+
+    History: a hard conf floor (DDA_OTHER_MIN_CONF=0.5) deleted 13/15 Grid_54
+    regions from ``regions_json`` while the overlay still drew them, so the
+    report disagreed with detection. Regions must match the engine list; ops
+    can hide noise in review instead of deleting at save time.
+
+    Set ``DDA_OTHER_MIN_CONF>0`` and ``DDA_SUPPRESS_WEAK_OTHER=1`` to flag
+    (not remove) tiny Other blobs with ``suppressed=true``.
+    """
+    import os
+    raw = os.environ.get("DDA_OTHER_MIN_CONF", "0").strip()
+    try:
+        floor = float(raw)
+    except ValueError:
+        floor = 0.0
+    try:
+        min_area = int(float(os.environ.get("DDA_OTHER_MIN_AREA", "1200")))
+    except ValueError:
+        min_area = 1200
+    suppress = os.environ.get("DDA_SUPPRESS_WEAK_OTHER", "").strip().lower() in (
+        "1", "true", "yes", "on",
+    )
+    if floor <= 0:
+        for r in regions:
+            r.setdefault("suppressed", False)
+        return regions
+
+    kept = []
+    flagged = 0
+    for r in regions:
+        dda = (r.get("ddaChangeType") or "").strip()
+        conf = float(r.get("confidence") or 0.0)
+        area = int(r.get("area") or 0)
+        weak = dda == "Other" and conf < floor and area < min_area
+        r = dict(r)
+        r["suppressed"] = bool(weak and suppress)
+        if weak and suppress:
+            flagged += 1
+        # Never drop — always keep in report JSON
+        kept.append(r)
+    if flagged:
+        logger.info("Flagged %d weak Other regions as suppressed (still in report)", flagged)
+    return kept
+
+
+def _isoformat_ist(dt):
+    from datetime import timedelta
+    if dt is None:
+        return None
+    _IST = timezone(timedelta(hours=5, minutes=30))
+    if dt.tzinfo is None:
+        from datetime import timezone as tz
+        dt = dt.replace(tzinfo=tz.utc)
+    return dt.astimezone(_IST).isoformat()
+
+
+def _alignment_warning(before_pil, after_pil, before_tif, after_tif):
+    """Operator-facing warning when a pair is identical or poorly aligned.
+
+    Runs the pre-detection guard (``app.dda.pair_align``) to catch the two
+    silent-failure modes that otherwise yield an empty or garbage change mask
+    with no explanation: (1) the same image uploaded twice, and (2) raw drone
+    frames from different viewpoints that never register onto a common grid.
+    Returns ``None`` when the pair looks fine or the check cannot run, so this
+    can never block or crash a detection job.
+    """
+    try:
+        import numpy as np
+
+        from .pair_align import are_identical, assess_alignment, geo_align_pair
+
+        b = np.asarray(before_pil.convert("RGB"))
+        a = np.asarray(after_pil.convert("RGB"))
+        if b.shape == a.shape and are_identical(b, a):
+            return ("Before and after are the same image (identical pixels). There is "
+                    "no change to detect - please check that two different dates were "
+                    "selected.")
+        # The NCC misalignment check only makes sense on georeferenced pairs, where
+        # both can be placed on a common grid. For plain uploads the engine's own
+        # SIFT/ECC registration handles alignment, so comparing the raw (pre-
+        # registration) frames here would raise false alarms.
+        if before_tif and after_tif:
+            aligned = geo_align_pair(Path(before_tif), Path(after_tif))
+            if aligned is not None:
+                bb, aa, _overlap = aligned
+                status, ncc = assess_alignment(bb, aa)
+                if status == "low_quality":
+                    return (f"The before/after images do not align well (NCC={ncc:.2f}). "
+                            "They look like raw drone frames from different viewpoints "
+                            "rather than orthomosaics on a common grid, so detected "
+                            "changes may be unreliable. For accurate results, export both "
+                            "dates as north-up orthomosaics on the same grid.")
+        return None
+    except Exception as exc:
+        logger.warning("Alignment guard skipped: %s", exc)
+        return None
+
+
+def run_detection_and_save(
+    db: Session,
+    before_pil: Image.Image,
+    after_pil: Image.Image,
+    *,
+    method: str = "AI-Based Deep Learning",
+    title: str = "Untitled run",
+    zone: str = "",
+    village: str = "",
+    enable_registration: bool = True,
+    enable_normalization: bool = True,
+    detection_sensitivity: float = 0.5,
+    min_region_area: Optional[int] = None,
+    notify_email: Optional[str] = None,
+    max_size: Optional[int] = None,
+    geo_bounds_path: Optional[Path] = None,
+    comparison_file: Optional[Path] = None,
+    base_path: str = "",
+    comparison_path: str = "",
+    user_id: Optional[int] = None,
+    job_id: Optional[int] = None,
+    gsd_debug: Optional[dict] = None,
+    shape_mode: str = "polygon",
+    preflight_warnings: Optional[list] = None,
+) -> dict:
+    from ..detection_engine import run_detection
+    from .job_progress import update_job_progress
+
+    def _report(pct: int, stage: str) -> None:
+        if job_id is not None:
+            update_job_progress(job_id, pct, stage)
+
+    if user_id:
+        from ..auth import get_user_by_id
+        user = get_user_by_id(db, user_id)
+        if not user:
+            user = get_or_create_guest_user(db)
+    else:
+        user = get_or_create_guest_user(db)
+    db.commit()
+    detection_sensitivity = max(0.0, min(1.0, float(detection_sensitivity)))
+    if min_region_area is not None:
+        min_region_area = int(max(50, min(10000, min_region_area)))
+
+    def _on_engine_progress(engine_pct: int, stage: str) -> None:
+        # Map engine 0–100% into job 15–78%
+        job_pct = 15 + int(engine_pct * 0.63)
+        _report(job_pct, stage)
+
+    _report(15, "Running detection")
+
+    def _geotiff_path(p: Optional[Path]) -> Optional[str]:
+        if p is not None and str(p).lower().endswith((".tif", ".tiff")):
+            return str(p)
+        return None
+
+    change_mask, result_image, stats, change_regions = run_detection(
+        before_pil,
+        after_pil,
+        method=method,
+        enable_registration=enable_registration,
+        enable_normalization=enable_normalization,
+        detection_sensitivity=detection_sensitivity,
+        min_region_area=min_region_area,
+        max_size=max_size,
+        on_progress=_on_engine_progress,
+        before_path=_geotiff_path(geo_bounds_path),
+        after_path=_geotiff_path(comparison_file),
+        shape_mode=shape_mode,
+    )
+    # Record the choice so the viewer can match the baked overlay's style.
+    if isinstance(stats.get("params"), dict):
+        stats["params"]["shape_mode"] = shape_mode
+
+    # Pre-detection guard: surface identical / poorly-aligned pairs to the operator
+    # instead of returning a silent empty or garbage mask (the UI already renders
+    # stats["alignment_warning"] as a banner). Never overrides an existing warning.
+    if not stats.get("alignment_warning"):
+        align_warn = _alignment_warning(
+            before_pil, after_pil,
+            _geotiff_path(geo_bounds_path), _geotiff_path(comparison_file),
+        )
+        if align_warn:
+            stats["alignment_warning"] = align_warn
+            logger.info("Alignment guard flagged pair: %s", align_warn)
+
+    if gsd_debug and isinstance(stats.get("threshold_debug"), dict):
+        stats["threshold_debug"]["gsdHarmonization"] = gsd_debug
+
+    if preflight_warnings:
+        stats["preflightWarnings"] = list(preflight_warnings)
+
+    _report(80, "Saving results")
+
+    base_name = f"{user.id}_{uuid.uuid4().hex}"
+    overlay_filename = base_name + ".png"
+    overlay_path = OVERLAYS_DIR / overlay_filename
+    overlay_path.parent.mkdir(parents=True, exist_ok=True)
+    Image.fromarray(result_image).save(overlay_path)
+    relative_overlay = f"overlays/{overlay_filename}"
+
+    relative_prob = ""
+    try:
+        from ..detection_config import get_save_prob_map
+        score_map = stats.pop("_score_map", None)
+        if get_save_prob_map() and score_map is not None:
+            import numpy as _np
+            prob_u8 = _np.clip(score_map * 255.0, 0, 255).astype("uint8")
+            prob_img = Image.fromarray(prob_u8)
+            prob_img.thumbnail((1024, 1024), Image.Resampling.LANCZOS)
+            prob_file = OVERLAYS_DIR / f"{base_name}_prob.png"
+            prob_img.save(prob_file)
+            relative_prob = f"overlays/{base_name}_prob.png"
+    except Exception as exc:
+        logger.warning("Probability map export failed: %s", exc)
+
+    relative_before_full = ""
+    relative_before_thumb = ""
+    relative_after_thumb = ""
+    relative_after_full = ""
+    before_for_slider = None
+    try:
+        # Prefer the detection working grid (registered + same resolution as
+        # region polygons). Falling back to a fresh preprocess only if the
+        # engine did not provide slider frames (keeps older callers safe).
+        slider_before = stats.pop("_slider_before", None)
+        slider_after = stats.pop("_slider_after", None)
+        if slider_before is not None and slider_after is not None:
+            before_for_slider = Image.fromarray(slider_before)
+            after_for_slider = Image.fromarray(slider_after)
+        else:
+            from ..detection_engine import preprocess_image, get_detection_max_size
+            before_for_slider = Image.fromarray(
+                preprocess_image(before_pil, max_size=max_size or get_detection_max_size())
+            )
+            after_for_slider = Image.fromarray(
+                preprocess_image(after_pil, max_size=max_size or get_detection_max_size())
+            )
+        before_full_file = OVERLAYS_DIR / f"{base_name}_before.png"
+        before_for_slider.save(before_full_file)
+        relative_before_full = f"overlays/{base_name}_before.png"
+        after_full_file = OVERLAYS_DIR / f"{base_name}_after.png"
+        after_for_slider.save(after_full_file)
+        relative_after_full = f"overlays/{base_name}_after.png"
+        before_thumb_pil = before_pil.copy()
+        before_thumb_pil.thumbnail((THUMB_MAX_SIZE, THUMB_MAX_SIZE), Image.Resampling.LANCZOS)
+        before_thumb_pil.save(OVERLAYS_DIR / f"{base_name}_before_thumb.png")
+        after_thumb_pil = after_pil.copy()
+        after_thumb_pil.thumbnail((THUMB_MAX_SIZE, THUMB_MAX_SIZE), Image.Resampling.LANCZOS)
+        after_thumb_pil.save(OVERLAYS_DIR / f"{base_name}_after_thumb.png")
+        relative_before_thumb = f"overlays/{base_name}_before_thumb.png"
+        relative_after_thumb = f"overlays/{base_name}_after_thumb.png"
+    except Exception as exc:
+        logger.warning("Failed to save thumbnails: %s", exc)
+        # Ensure det size fallback still has a slider image reference
+        from ..detection_engine import preprocess_image, get_detection_max_size
+        before_for_slider = Image.fromarray(
+            preprocess_image(before_pil, max_size=max_size or get_detection_max_size())
+        )
+
+    regions_serializable = _serialize_regions(change_regions)
+    det_w = int(stats.get("image_width") or 0)
+    det_h = int(stats.get("image_height") or 0)
+    if det_w <= 0 or det_h <= 0:
+        if before_for_slider is not None:
+            det_w, det_h = before_for_slider.size
+        else:
+            det_w, det_h = before_pil.size
+
+    geo_ctx = None
+    bounds = None
+    if geo_bounds_path:
+        rel_path = (base_path or "").replace("\\", "/").strip().lstrip("/")
+        if not rel_path:
+            try:
+                from .config import get_storage_root
+                rel_path = geo_bounds_path.resolve().relative_to(get_storage_root().resolve()).as_posix()
+            except Exception:
+                rel_path = geo_bounds_path.name
+        geo_ctx = resolve_geo_context(db, rel_path, geo_bounds_path)
+        bounds = geo_ctx.bounds
+
+    regions_serializable = enrich_regions_geo(
+        regions_serializable,
+        img_width=det_w,
+        img_height=det_h,
+        bounds=bounds,
+        geo=geo_ctx,
+    )
+    # Ops filter: PDF report (Grid_54 vs H43X2E1) showed many low-conf "Other"
+    # blobs at thr~0.2 — quarantine weak unclassified FPs without raising DL thr.
+    before_n = len(regions_serializable)
+    regions_serializable = _filter_weak_other_regions(regions_serializable)
+    dropped_other = before_n - len(regions_serializable)
+    if dropped_other:
+        logger.info("Filtered %d low-confidence Other regions", dropped_other)
+    regions_with_coords = sum(1 for r in regions_serializable if r.get("latLng"))
+    geo_debug = {
+        "source": geo_ctx.source if geo_ctx else "none",
+        "crs": str(geo_ctx.georef.crs) if (geo_ctx and geo_ctx.georef and geo_ctx.georef.crs) else "",
+        "bounds": list(bounds) if bounds else None,
+        "georefWidth": geo_ctx.georef_width if geo_ctx else 0,
+        "georefHeight": geo_ctx.georef_height if geo_ctx else 0,
+        "detectionWidth": det_w,
+        "detectionHeight": det_h,
+        "regionsWithCoords": regions_with_coords,
+        "regionsTotal": len(regions_serializable),
+    }
+    logger.info("Geo debug for run: %s", geo_debug)
+    total_px = int(stats["total_pixels"])
+    changed_px = int(stats["changed_pixels"])
+    change_pct = float(stats["change_percentage"])
+
+    run = DetectionRun(
+        user_id=user.id,
+        title=title,
+        method=method,
+        zone=zone,
+        village=village,
+        total_pixels=total_px,
+        changed_pixels=changed_px,
+        change_percentage=change_pct,
+        regions_count=len(regions_serializable),
+        overlay_path=relative_overlay,
+        before_full_path=relative_before_full,
+        before_thumb_path=relative_before_thumb,
+        after_thumb_path=relative_after_thumb,
+        after_full_path=relative_after_full,
+        regions_json=json.dumps(regions_serializable),
+    )
+    db.add(run)
+    db.commit()
+    db.refresh(run)
+
+    try:
+        from .dda_auth import get_user_role
+        from .tree.audit_service import log_action
+        log_action(
+            db, "run_detection", action_by=getattr(user, "email", "") or "",
+            role=get_user_role(db, user), module="detect",
+            new_value={"run_id": run.id, "method": method, "zone": zone, "village": village,
+                       "change_percentage": change_pct},
+        )
+        db.commit()
+    except Exception:
+        logger.exception("Failed to write audit log for detection run %s", run.id)
+
+    _report(90, "Preparing report")
+    overlay_b64 = base64.b64encode(overlay_path.read_bytes()).decode("utf-8")
+    notification_sent = False
+    notification_error = None
+    if notify_email and notify_email.strip():
+        _report(95, "Sending notification")
+        from .config import IS_DDA_MODE, get_public_base_url
+        report_url = f"{get_public_base_url()}/dda/reports/{run.id}" if IS_DDA_MODE else ""
+        notification_sent, notification_error = send_notification(
+            recipient=notify_email.strip(),
+            title=title,
+            method=method,
+            zone=zone,
+            village=village,
+            change_pct=change_pct,
+            changed_px=changed_px,
+            total_px=total_px,
+            regions=regions_serializable,
+            report_url=report_url,
+        )
+
+    _report(100, "Complete")
+
+    return {
+        "id": run.id,
+        "title": run.title,
+        "method": run.method,
+        "zone": run.zone or "",
+        "village": run.village or "",
+        "basePath": base_path,
+        "comparisonPath": comparison_path,
+        "statistics": {
+            "totalPixels": total_px,
+            "changedPixels": changed_px,
+            "unchangedPixels": int(stats["unchanged_pixels"]),
+            "changePercentage": change_pct,
+            "thresholdDebug": stats.get("threshold_debug", {}),
+            "params": stats.get("params", {}),
+            "alignmentWarning": stats.get("alignment_warning"),
+            "registrationOk": stats.get("params", {}).get("registration_ok"),
+            "preflightWarnings": stats.get("preflightWarnings") or [],
+            "geo": geo_debug,
+            "probabilityMapUrl": f"/api/overlay/{relative_prob}" if relative_prob else None,
+        },
+        "regions": regions_serializable,
+        "overlayBase64Png": overlay_b64,
+        "overlayUrl": f"/api/overlay/{relative_overlay}",
+        "beforeFullUrl": f"/api/overlay/{relative_before_full}" if relative_before_full else None,
+        "beforeThumbUrl": f"/api/overlay/{relative_before_thumb}" if relative_before_thumb else None,
+        "afterThumbUrl": f"/api/overlay/{relative_after_thumb}" if relative_after_thumb else None,
+        "afterFullUrl": f"/api/overlay/{relative_after_full}" if relative_after_full else None,
+        "notificationSent": notification_sent,
+        "notificationError": notification_error,
+        "createdAt": _isoformat_ist(run.created_at),
+        "detectionMaxSide": max_size,
+    }

app/dda/exception_routes.py

@@ -0,0 +1,132 @@
+"""API for the Exception Log page — system errors captured by the global
+FastAPI exception handlers in app/main.py."""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models import User
+from .rbac.permissions import require_module_permission
+from .tree.audit_service import isoformat_ist
+from .tree.models import ExceptionLog
+
+router = APIRouter()
+
+
+def _require_dda():
+    from .config import IS_DDA_MODE
+    if not IS_DDA_MODE:
+        raise HTTPException(status_code=404, detail="DDA mode is not enabled")
+
+
+def _entry_dict(entry: ExceptionLog, *, with_traceback: bool = False) -> dict:
+    d = {
+        "id": entry.id,
+        "timestamp": isoformat_ist(entry.created_at),
+        "type": entry.exception_type,
+        "message": entry.message or "",
+        "path": entry.path or "",
+        "method": entry.method or "",
+        "statusCode": entry.status_code,
+        "handled": bool(entry.handled),
+        "userEmail": entry.user_email or "",
+    }
+    if with_traceback:
+        d["traceback"] = entry.traceback or ""
+    return d
+
+
+def _parse_date(value: Optional[str], *, end_of_day: bool = False) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        dt = datetime.fromisoformat(value)
+    except ValueError:
+        raise HTTPException(status_code=400, detail=f"Invalid date: {value!r} (expected YYYY-MM-DD)")
+    if end_of_day:
+        dt = dt.replace(hour=23, minute=59, second=59, microsecond=999999)
+    return dt
+
+
+@router.get("/exception-log")
+def list_exception_log(
+    exception_type: str = Query("", alias="type"),
+    status_code: Optional[int] = Query(None),
+    from_date: Optional[str] = Query(None, alias="from"),
+    to_date: Optional[str] = Query(None, alias="to"),
+    limit: int = Query(100, ge=1, le=1000),
+    offset: int = Query(0, ge=0),
+    user: User = Depends(require_module_permission("exception_log", "view")),
+    db: Session = Depends(get_db),
+):
+    _require_dda()
+    q = db.query(ExceptionLog)
+    if exception_type:
+        q = q.filter(ExceptionLog.exception_type == exception_type)
+    if status_code is not None:
+        q = q.filter(ExceptionLog.status_code == status_code)
+    start = _parse_date(from_date)
+    if start:
+        q = q.filter(ExceptionLog.created_at >= start)
+    end = _parse_date(to_date, end_of_day=True)
+    if end:
+        q = q.filter(ExceptionLog.created_at <= end)
+
+    total = q.count()
+    page_rows = q.order_by(ExceptionLog.created_at.desc()).offset(offset).limit(limit).all()
+
+    # Stat cards summarize the *filtered* result set (matching the reference UI's
+    # "(this page)" labels), computed on the full filtered query, not just page_rows.
+    filtered = q
+    errors_500 = filtered.filter(ExceptionLog.status_code >= 500).count()
+    errors_other = total - errors_500
+    unhandled = filtered.filter(ExceptionLog.handled.is_(False)).count()
+
+    return {
+        "logs": [_entry_dict(r) for r in page_rows],
+        "total": total,
+        "limit": limit,
+        "offset": offset,
+        "stats": {"errors500": errors_500, "errorsOther": errors_other, "unhandled": unhandled},
+    }
+
+
+@router.get("/exception-log/filters")
+def exception_log_filters(
+    user: User = Depends(require_module_permission("exception_log", "view")),
+    db: Session = Depends(get_db),
+):
+    _require_dda()
+    types = [r[0] for r in db.query(ExceptionLog.exception_type).distinct().order_by(ExceptionLog.exception_type) if r[0]]
+    codes = sorted({r[0] for r in db.query(ExceptionLog.status_code).distinct() if r[0] is not None})
+    return {"types": types, "statusCodes": codes}
+
+
+@router.get("/exception-log/{entry_id}")
+def get_exception_log_entry(
+    entry_id: int,
+    user: User = Depends(require_module_permission("exception_log", "view")),
+    db: Session = Depends(get_db),
+):
+    _require_dda()
+    entry = db.query(ExceptionLog).filter(ExceptionLog.id == entry_id).first()
+    if not entry:
+        raise HTTPException(status_code=404, detail="Exception log entry not found")
+    return _entry_dict(entry, with_traceback=True)
+
+
+@router.delete("/exception-log/old")
+def clear_old_exception_log(
+    days: int = Query(30, ge=1, le=3650),
+    user: User = Depends(require_module_permission("exception_log", "delete")),
+    db: Session = Depends(get_db),
+):
+    _require_dda()
+    cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+    deleted = db.query(ExceptionLog).filter(ExceptionLog.created_at < cutoff).delete(synchronize_session=False)
+    db.commit()
+    return {"ok": True, "deleted": deleted}

app/dda/geo_regions.py

@@ -0,0 +1,335 @@
+"""Pixel coordinates → WGS84 lat/lng for geo-referenced images (FR-04, FR-06)."""
+from __future__ import annotations
+
+import json
+import logging
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from sqlalchemy.orm import Session
+
+from .change_type_map import enrich_region_for_dda
+from .geotiff_io import GeorefInfo, inspect_image, pixel_to_geo_wgs84, read_georef
+
+logger = logging.getLogger(__name__)
+
+BoundsWGS84 = Tuple[float, float, float, float]  # west, south, east, north
+
+
+@dataclass
+class GeoContext:
+    bounds: Optional[BoundsWGS84]
+    georef: Optional[GeorefInfo]
+    georef_width: int
+    georef_height: int
+    source: str = "none"  # embedded | worldfile | manual | linear | none
+
+
+def _bounds_in_range(b: Optional[BoundsWGS84]) -> bool:
+    if not b:
+        return False
+    w, s, e, n = b
+    return abs(w) <= 180 and abs(e) <= 180 and abs(s) <= 90 and abs(n) <= 90
+
+
+def parse_bounds(bounds: Any) -> Optional[BoundsWGS84]:
+    if bounds is None:
+        return None
+    if isinstance(bounds, (list, tuple)) and len(bounds) == 4:
+        return tuple(float(x) for x in bounds)
+    if isinstance(bounds, dict):
+        try:
+            return (
+                float(bounds["west"]),
+                float(bounds["south"]),
+                float(bounds["east"]),
+                float(bounds["north"]),
+            )
+        except (KeyError, TypeError, ValueError):
+            return None
+    if isinstance(bounds, str) and bounds.strip():
+        try:
+            data = json.loads(bounds)
+            return parse_bounds(data)
+        except json.JSONDecodeError:
+            parts = [float(x.strip()) for x in bounds.replace("[", "").replace("]", "").split(",")]
+            if len(parts) == 4:
+                return tuple(parts)
+    return None
+
+
+def bounds_from_image_path(path: Path) -> Optional[BoundsWGS84]:
+    try:
+        meta = inspect_image(path)
+        return meta.bounds_wgs84
+    except Exception as exc:
+        logger.warning("Could not read bounds for %s: %s", path.name, exc)
+        return None
+
+
+def resolve_geo_context(
+    db: Session,
+    base_path: str,
+    base_file: Path,
+) -> GeoContext:
+    """Resolve bounds and affine georef for detection geo enrichment.
+
+    Priority: embedded/world-file affine georef → DB manual bounds → linear
+    bounds inferred from the image sidecars. Tracks which source was used.
+    """
+    georef = read_georef(base_file)
+    bounds = georef.bounds_wgs84 if georef else None
+    georef_width = georef.width if georef else 0
+    georef_height = georef.height if georef else 0
+    source = getattr(georef, "source", "embedded") if georef else "none"
+
+    if not bounds:
+        from .tree.image_service import get_image_by_file_path
+
+        rel = base_path.replace("\\", "/").strip().lstrip("/")
+        img = get_image_by_file_path(db, rel)
+        if img and img.bounds_json:
+            db_bounds = parse_bounds(img.bounds_json)
+            if db_bounds:
+                bounds = db_bounds
+                source = "manual"
+
+    if not bounds:
+        bounds = bounds_from_image_path(base_file)
+        if bounds:
+            source = "linear"
+
+    if (georef_width <= 0 or georef_height <= 0) and bounds:
+        meta = inspect_image(base_file)
+        georef_width = meta.width or georef_width
+        georef_height = meta.height or georef_height
+
+    return GeoContext(
+        bounds=bounds,
+        georef=georef,
+        georef_width=georef_width or 0,
+        georef_height=georef_height or 0,
+        source=source if bounds else "none",
+    )
+
+
+def pixel_to_lat_lng(
+    x: float,
+    y: float,
+    img_width: int,
+    img_height: int,
+    bounds: BoundsWGS84,
+    *,
+    geo: Optional[GeoContext] = None,
+) -> Optional[Dict[str, float]]:
+    if img_width <= 0 or img_height <= 0:
+        return None
+
+    if geo and geo.georef:
+        coords = pixel_to_geo_wgs84(
+            x, y, geo.georef,
+            detection_width=img_width,
+            detection_height=img_height,
+        )
+        if coords:
+            lng, lat = coords
+            # Guard against bad transforms emitting impossible coordinates
+            if abs(lat) <= 90 and abs(lng) <= 180:
+                return {"lat": round(lat, 6), "lng": round(lng, 6)}
+            logger.warning("Affine produced out-of-range lat/lng (%.3f,%.3f); using linear", lat, lng)
+
+    if not bounds:
+        return None
+
+    west, south, east, north = bounds
+    ref_w = geo.georef_width if geo and geo.georef_width > 0 else img_width
+    ref_h = geo.georef_height if geo and geo.georef_height > 0 else img_height
+    scale_x = ref_w / float(img_width)
+    scale_y = ref_h / float(img_height)
+    px = float(x) * scale_x
+    py = float(y) * scale_y
+    lng = west + (px / ref_w) * (east - west)
+    lat = north - (py / ref_h) * (north - south)
+    return {"lat": round(lat, 6), "lng": round(lng, 6)}
+
+
+def _ground_m_per_px(
+    img_width: int,
+    img_height: int,
+    bounds: BoundsWGS84,
+    *,
+    geo: Optional[GeoContext] = None,
+) -> Optional[Tuple[float, float]]:
+    """Metres per detection-image pixel along X (east) and Y (south)."""
+    if img_width <= 0 or img_height <= 0 or not bounds:
+        return None
+    west, south, east, north = bounds
+    ref_w = geo.georef_width if geo and geo.georef_width > 0 else img_width
+    ref_h = geo.georef_height if geo and geo.georef_height > 0 else img_height
+    if ref_w <= 0 or ref_h <= 0:
+        return None
+    scale_x = ref_w / float(img_width)
+    scale_y = ref_h / float(img_height)
+    mid_lat = (north + south) / 2.0
+    lat_scale = 111_320.0
+    lng_scale = 111_320.0 * math.cos(math.radians(mid_lat))
+    m_per_px_x = abs(east - west) / ref_w * scale_x * lng_scale
+    m_per_px_y = abs(north - south) / ref_h * scale_y * lat_scale
+    if m_per_px_x <= 0 or m_per_px_y <= 0:
+        return None
+    return m_per_px_x, m_per_px_y
+
+
+def bbox_area_sq_m(
+    bbox: Dict[str, int],
+    img_width: int,
+    img_height: int,
+    bounds: BoundsWGS84,
+    *,
+    geo: Optional[GeoContext] = None,
+) -> Optional[float]:
+    """Approximate region area in square metres using the axis-aligned bbox."""
+    scales = _ground_m_per_px(img_width, img_height, bounds, geo=geo)
+    if not scales:
+        return None
+    m_per_px_x, m_per_px_y = scales
+    w_m = float(bbox.get("w", 0)) * m_per_px_x
+    h_m = float(bbox.get("h", 0)) * m_per_px_y
+    return round(w_m * h_m, 1)
+
+
+def polygon_area_px(polygon: Optional[List]) -> Optional[float]:
+    """Shoelace area of an image-pixel ring (absolute value, closed or open)."""
+    if not polygon or len(polygon) < 3:
+        return None
+    try:
+        pts = [(float(p[0]), float(p[1])) for p in polygon]
+    except (TypeError, ValueError, IndexError):
+        return None
+    if pts[0] == pts[-1]:
+        pts = pts[:-1]
+    if len(pts) < 3:
+        return None
+    area2 = 0.0
+    n = len(pts)
+    for i in range(n):
+        x1, y1 = pts[i]
+        x2, y2 = pts[(i + 1) % n]
+        area2 += x1 * y2 - x2 * y1
+    return abs(area2) * 0.5
+
+
+def polygon_area_sq_m(
+    polygon: Optional[List],
+    img_width: int,
+    img_height: int,
+    bounds: Optional[BoundsWGS84],
+    *,
+    geo: Optional[GeoContext] = None,
+) -> Optional[float]:
+    """Ground area of a pixel-space polygon footprint (preferred over bbox)."""
+    if not bounds:
+        return None
+    scales = _ground_m_per_px(img_width, img_height, bounds, geo=geo)
+    if not scales:
+        return None
+    m_per_px_x, m_per_px_y = scales
+    px_area = polygon_area_px(polygon)
+    if px_area is None:
+        return None
+    return round(px_area * m_per_px_x * m_per_px_y, 1)
+
+
+def polygon_to_lat_lng(
+    polygon: List[List[float]],
+    img_width: int,
+    img_height: int,
+    bounds: Optional[BoundsWGS84],
+    *,
+    geo: Optional[GeoContext] = None,
+) -> Optional[List[Dict[str, float]]]:
+    """Project a pixel-space polygon ring to WGS84, vertex by vertex.
+
+    Uses the same transform as the bbox-centre ``latLng`` so a polygon and its
+    region always agree. Returns None when any vertex fails to project, since a
+    partially-projected ring would draw a wrong footprint on a map.
+    """
+    if not polygon:
+        return None
+    ring: List[Dict[str, float]] = []
+    for point in polygon:
+        try:
+            x, y = float(point[0]), float(point[1])
+        except (TypeError, ValueError, IndexError):
+            return None
+        coords = pixel_to_lat_lng(x, y, img_width, img_height, bounds, geo=geo)
+        if not coords:
+            return None
+        ring.append(coords)
+    return ring or None
+
+
+def enrich_regions_geo(
+    regions: List[dict],
+    *,
+    img_width: int,
+    img_height: int,
+    bounds: Optional[BoundsWGS84],
+    geo: Optional[GeoContext] = None,
+) -> List[dict]:
+    """Add latLng, polygonGeo, areaSqM, and Vedangsoft change type to each region."""
+    effective_bounds = bounds or (geo.bounds if geo else None)
+    out = []
+    for region in regions:
+        enriched = enrich_region_for_dda(region)
+        center = region.get("center") or {}
+        cx = center.get("x", 0)
+        cy = center.get("y", 0)
+        poly = region.get("polygon")
+        poly_px = polygon_area_px(poly)
+        if poly_px is not None:
+            enriched["polygonAreaPx"] = round(poly_px, 1)
+        if effective_bounds or (geo and geo.georef):
+            lat_lng = pixel_to_lat_lng(
+                cx, cy, img_width, img_height, effective_bounds,
+                geo=geo,
+            )
+            if lat_lng:
+                enriched["latLng"] = lat_lng
+            polygon_geo = polygon_to_lat_lng(
+                poly, img_width, img_height, effective_bounds,
+                geo=geo,
+            )
+            if polygon_geo:
+                enriched["polygonGeo"] = polygon_geo
+            bbox = region.get("bbox") or {}
+            if effective_bounds:
+                # Prefer true polygon footprint area; bbox is the fallback.
+                area_sq_m = polygon_area_sq_m(
+                    poly, img_width, img_height, effective_bounds, geo=geo,
+                )
+                if area_sq_m is None:
+                    area_sq_m = bbox_area_sq_m(
+                        bbox, img_width, img_height, effective_bounds, geo=geo,
+                    )
+                if area_sq_m is not None:
+                    enriched["areaSqM"] = area_sq_m
+        else:
+            enriched["latLng"] = None
+        out.append(enriched)
+    return out
+
+
+def region_lat_lng(region: dict) -> tuple[Optional[float], Optional[float]]:
+    """Read lat/lng from region dict (supports latLng object or flat keys)."""
+    ll = region.get("latLng") or {}
+    lat = region.get("latitude", ll.get("lat") if isinstance(ll, dict) else None)
+    lng = region.get("longitude", ll.get("lng") if isinstance(ll, dict) else None)
+    if lat is None or lng is None:
+        return None, None
+    try:
+        return float(lat), float(lng)
+    except (TypeError, ValueError):
+        return None, None

app/dda/geotiff_io.py

@@ -0,0 +1,666 @@
+"""GeoTIFF ingest and preview generation (FR-02). Rasterio optional at import time."""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional, Tuple
+
+from PIL import Image, ImageOps
+
+from .config import get_detection_max_side
+
+logger = logging.getLogger(__name__)
+
+# World-file extensions per image type (ESRI convention + generic .wld)
+_WORLD_FILE_EXTS = {
+    ".tif": (".tfw", ".tifw", ".wld"),
+    ".tiff": (".tfw", ".tifw", ".wld"),
+    ".jpg": (".jgw", ".jpgw", ".wld"),
+    ".jpeg": (".jgw", ".jpgw", ".wld"),
+    ".png": (".pgw", ".pngw", ".wld"),
+}
+
+
+@dataclass
+class IngestResult:
+    width: int
+    height: int
+    has_georef: bool
+    crs: str
+    bounds_wgs84: Optional[Tuple[float, float, float, float]]  # west, south, east, north
+    format: str
+    georef_source: str = "none"  # embedded | worldfile | none
+
+
+def _find_world_file(path: Path) -> Optional[Path]:
+    """Locate an ESRI world file or generic .wld sidecar next to an image."""
+    ext = path.suffix.lower()
+    candidates = []
+    for wext in _WORLD_FILE_EXTS.get(ext, (".wld",)):
+        candidates.append(path.with_suffix(wext))
+    # e.g. photo.jpg.wld
+    candidates.append(Path(str(path) + ".wld"))
+    for cand in candidates:
+        if cand.is_file():
+            return cand
+    return None
+
+
+def _read_prj_crs(path: Path):
+    """Read a .prj sidecar (WKT) and return a rasterio CRS, or default EPSG:4326."""
+    try:
+        from rasterio.crs import CRS
+    except Exception:
+        return None
+    prj = path.with_suffix(".prj")
+    if prj.is_file():
+        try:
+            return CRS.from_wkt(prj.read_text(encoding="utf-8", errors="ignore").strip())
+        except Exception as exc:
+            logger.warning("Could not parse .prj for %s: %s", path.name, exc)
+    try:
+        return CRS.from_epsg(4326)
+    except Exception:
+        return None
+
+
+def _world_file_georef(path: Path, width: int, height: int):
+    """Build (transform, crs, bounds_wgs84) from a world file sidecar, or None."""
+    wf = _find_world_file(path)
+    if wf is None:
+        return None
+    try:
+        from rasterio.transform import Affine, array_bounds
+        from rasterio.warp import transform_bounds
+
+        nums = [float(x.strip()) for x in wf.read_text().split() if x.strip()]
+        if len(nums) < 6:
+            return None
+        a, d, b, e, c, f = nums[:6]
+        # World file stores center of top-left pixel; shift to corner for GDAL/affine
+        gt_c = c - a / 2.0 - b / 2.0
+        gt_f = f - d / 2.0 - e / 2.0
+        transform = Affine(a, b, gt_c, d, e, gt_f)
+        crs = _read_prj_crs(path)
+        west, south, east, north = array_bounds(height, width, transform)
+        if crs is not None and str(crs) not in ("EPSG:4326", "OGC:CRS84"):
+            west, south, east, north = transform_bounds(crs, "EPSG:4326", west, south, east, north)
+        return transform, crs, (float(west), float(south), float(east), float(north))
+    except Exception as exc:
+        logger.warning("World-file georef failed for %s: %s", path.name, exc)
+        return None
+
+
+def _read_with_rasterio(path: Path) -> IngestResult:
+    import rasterio
+    from rasterio.warp import transform_bounds
+
+    with rasterio.open(path) as src:
+        crs = str(src.crs) if src.crs else ""
+        has_georef = src.crs is not None
+        bounds = None
+        if has_georef and src.bounds:
+            try:
+                w, s, e, n = transform_bounds(src.crs, "EPSG:4326", *src.bounds)
+                bounds = (float(w), float(s), float(e), float(n))
+            except Exception as exc:
+                logger.warning("Could not transform bounds to WGS84: %s", exc)
+        ext = path.suffix.lower()
+        return IngestResult(
+            width=int(src.width),
+            height=int(src.height),
+            has_georef=has_georef,
+            crs=crs,
+            bounds_wgs84=bounds,
+            format="geotiff" if ext in (".tif", ".tiff") else "image",
+            georef_source="embedded" if has_georef else "none",
+        )
+
+
+def _read_with_pillow(path: Path) -> IngestResult:
+    with Image.open(path) as img:
+        w, h = img.size
+    ext = path.suffix.lower()
+    fmt = "geotiff" if ext in (".tif", ".tiff") else "image"
+    # Try a world-file sidecar for plain images / non-georeferenced TIFFs
+    wf = _world_file_georef(path, w, h)
+    if wf is not None:
+        _, crs, bounds = wf
+        return IngestResult(
+            width=w, height=h, has_georef=bounds is not None,
+            crs=str(crs) if crs else "", bounds_wgs84=bounds,
+            format=fmt, georef_source="worldfile" if bounds else "none",
+        )
+    return IngestResult(
+        width=w,
+        height=h,
+        has_georef=False,
+        crs="",
+        bounds_wgs84=None,
+        format=fmt,
+        georef_source="none",
+    )
+
+
+def inspect_image(path: Path) -> IngestResult:
+    """Read dimensions + georeferencing for any raster (TIFF/PNG/JPEG).
+
+    Tries rasterio first (honors embedded CRS, world files and GDAL .aux.xml for
+    all formats), then falls back to Pillow + explicit world-file parsing.
+    Corrupt / truncated GeoTIFFs must not crash library rescan — callers get a
+    zero-size stub and should skip indexing.
+    """
+    try:
+        res = _read_with_rasterio(path)
+        # rasterio opened but found no embedded georef: try explicit world file
+        if not res.has_georef:
+            wf = _world_file_georef(path, res.width, res.height)
+            if wf is not None and wf[2] is not None:
+                _, crs, bounds = wf
+                res.has_georef = True
+                res.crs = str(crs) if crs else ""
+                res.bounds_wgs84 = bounds
+                res.georef_source = "worldfile"
+        return res
+    except ImportError:
+        logger.warning("rasterio not installed — georef metadata limited")
+    except Exception as exc:
+        logger.warning("rasterio read failed (%s), falling back to Pillow", exc)
+    try:
+        return _read_with_pillow(path)
+    except Exception as exc:
+        # Common for truncated / BigTIFF files Pillow cannot parse
+        # ("Invalid dimensions"). Don't abort the whole library sync.
+        logger.warning("Pillow inspect failed for %s: %s", path.name, exc)
+        ext = path.suffix.lower()
+        return IngestResult(
+            width=0,
+            height=0,
+            has_georef=False,
+            crs="",
+            bounds_wgs84=None,
+            format="geotiff" if ext in (".tif", ".tiff") else "image",
+            georef_source="none",
+        )
+
+
+def write_placeholder_png(dest_path: Path, label: str = "Image", max_side: int = 256) -> None:
+    """Fallback thumb when GeoTIFF is too large or rasterio is unavailable."""
+    from PIL import ImageDraw
+
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+    img = Image.new("RGB", (max_side, max_side), color=(32, 40, 52))
+    draw = ImageDraw.Draw(img)
+    lines = [label[:28], "preview N/A"]
+    y = max_side // 2 - 20
+    for line in lines:
+        draw.text((12, y), line, fill=(100, 200, 170))
+        y += 18
+    img.save(dest_path, format="PNG")
+
+
+def _rasterio_read_rgb(path: Path, max_side: int):
+    import numpy as np
+    import rasterio
+    from rasterio.enums import Resampling
+
+    with rasterio.open(path) as src:
+        count = min(3, src.count)
+        scale = min(1.0, max_side / max(src.width, src.height, 1))
+        out_h = max(1, int(src.height * scale))
+        out_w = max(1, int(src.width * scale))
+
+        read_kwargs = {
+            "indexes": list(range(1, count + 1)),
+            "out_shape": (count, out_h, out_w),
+            "resampling": Resampling.bilinear,
+        }
+        try:
+            data = src.read(**read_kwargs)
+        except Exception:
+            # Fallback: read from coarsest overview when full decimation fails
+            if src.overviews(1):
+                with rasterio.open(path, overview_level=len(src.overviews(1))) as ov_src:
+                    ocount = min(3, ov_src.count)
+                    data = ov_src.read(
+                        indexes=list(range(1, ocount + 1)),
+                        out_shape=(ocount, out_h, out_w),
+                        resampling=Resampling.bilinear,
+                    )
+            else:
+                raise
+
+        if count == 1:
+            rgb = np.stack([data[0], data[0], data[0]])
+        else:
+            rgb = data[:3]
+        rgb = np.transpose(rgb, (1, 2, 0)).astype("float32")
+        if rgb.max() > 255 or rgb.min() < 0:
+            lo, hi = np.percentile(rgb, (2, 98))
+            rgb = np.clip((rgb - lo) / max(hi - lo, 1e-6), 0, 1) * 255
+        return Image.fromarray(rgb.astype("uint8"), mode="RGB")
+
+
+def read_native_size(path: Path) -> Optional[Tuple[int, int]]:
+    """Return (width, height) of a GeoTIFF without decoding pixels, or None."""
+    ext = path.suffix.lower()
+    if ext not in (".tif", ".tiff"):
+        return None
+    try:
+        import rasterio
+        with rasterio.open(path) as src:
+            return int(src.width), int(src.height)
+    except Exception:
+        return None
+
+
+def _normalize_window_rgb(data):
+    """Convert a rasterio (bands, h, w) window read to RGB uint8 (h, w, 3)."""
+    import numpy as np
+    count = data.shape[0]
+    if count == 1:
+        rgb = np.stack([data[0], data[0], data[0]])
+    else:
+        rgb = data[:3]
+    rgb = np.transpose(rgb, (1, 2, 0)).astype("float32")
+    if rgb.max() > 255 or rgb.min() < 0:
+        lo, hi = np.percentile(rgb, (2, 98))
+        rgb = np.clip((rgb - lo) / max(hi - lo, 1e-6), 0, 1) * 255
+    return rgb.astype("uint8")
+
+
+def iter_geotiff_window_pairs(path_a: Path, path_b: Path,
+                              tile_size: int = 512, overlap: float = 0.25):
+    """Stream paired native-resolution RGB windows from two GeoTIFFs.
+
+    Reads windows from disk via rasterio so very large rasters never load
+    fully into RAM. Yields ``(tile_a, tile_b, y0, x0, full_h, full_w)`` where
+    tiles are RGB uint8 on **path_a's** pixel grid.
+
+    Same-size pairs use direct window reads. Different pixel sizes (common for
+    same-bounds DDA pairs with slight GSD drift) reproject ``path_b`` into each
+    ``path_a`` window via georef so windowed full-res inference still works.
+    """
+    import numpy as np
+    import rasterio
+    from rasterio.enums import Resampling
+    from rasterio.warp import reproject
+    from rasterio.windows import Window, transform as window_transform
+
+    tile_size = max(64, int(tile_size))
+    ov = min(0.5, max(0.0, float(overlap)))
+    step = max(1, int(round(tile_size * (1.0 - ov))))
+
+    with rasterio.open(path_a) as src_a, rasterio.open(path_b) as src_b:
+        full_w, full_h = int(src_a.width), int(src_a.height)
+        same_grid = (src_a.width, src_a.height) == (src_b.width, src_b.height)
+        bands_a = list(range(1, min(3, src_a.count) + 1))
+        bands_b = list(range(1, min(3, src_b.count) + 1))
+        n_bands = len(bands_a)
+
+        ys = list(range(0, max(1, full_h - tile_size + 1), step))
+        xs = list(range(0, max(1, full_w - tile_size + 1), step))
+        if ys[-1] != full_h - tile_size and full_h > tile_size:
+            ys.append(full_h - tile_size)
+        if xs[-1] != full_w - tile_size and full_w > tile_size:
+            xs.append(full_w - tile_size)
+
+        for y0 in ys:
+            for x0 in xs:
+                wh = min(tile_size, full_h - y0)
+                ww = min(tile_size, full_w - x0)
+                win = Window(x0, y0, ww, wh)
+                da = src_a.read(indexes=bands_a, window=win)
+
+                if same_grid:
+                    db = src_b.read(indexes=bands_b, window=win)
+                else:
+                    # Warp after → before window CRS/transform/size
+                    dst = np.zeros((n_bands, wh, ww), dtype=np.float32)
+                    dst_transform = window_transform(win, src_a.transform)
+                    for i, band in enumerate(bands_b[:n_bands]):
+                        reproject(
+                            source=rasterio.band(src_b, band),
+                            destination=dst[i],
+                            src_transform=src_b.transform,
+                            src_crs=src_b.crs,
+                            dst_transform=dst_transform,
+                            dst_crs=src_a.crs,
+                            resampling=Resampling.bilinear,
+                        )
+                    db = dst
+
+                yield (_normalize_window_rgb(da), _normalize_window_rgb(db),
+                       y0, x0, full_h, full_w)
+
+
+def load_rgb_pil(path: Path, max_side: Optional[int] = None) -> Image.Image:
+    """Load image as RGB PIL, downscaling large GeoTIFFs via rasterio."""
+    if max_side is None:
+        max_side = get_detection_max_side()
+    ext = path.suffix.lower()
+    if ext in (".tif", ".tiff"):
+        try:
+            img = _rasterio_read_rgb(path, max_side)
+            return img.copy()
+        except ImportError as exc:
+            raise RuntimeError(
+                "GeoTIFF support requires rasterio. Install with: pip install rasterio"
+            ) from exc
+        except Exception as exc:
+            raise RuntimeError(f"Could not read GeoTIFF: {exc}") from exc
+    with Image.open(path) as img:
+        img = ImageOps.exif_transpose(img)
+        img = img.convert("RGB")
+        if max(img.size) > max_side:
+            img.thumbnail((max_side, max_side), Image.Resampling.LANCZOS)
+        return img.copy()
+
+
+def parse_roi(roi) -> Optional[dict]:
+    """Validate a fractional ROI ``{x, y, w, h}`` (all in [0, 1]).
+
+    Returns a normalized dict (w/h clamped so the box stays inside the image),
+    or ``None`` when ``roi`` is empty/falsey. Raises ``ValueError`` on a
+    malformed or out-of-bounds ROI so callers can turn it into an HTTP 400.
+    """
+    if not roi:
+        return None
+    try:
+        x, y = float(roi["x"]), float(roi["y"])
+        w, h = float(roi["w"]), float(roi["h"])
+    except (KeyError, TypeError, ValueError):
+        raise ValueError("roi must have numeric x, y, w, h")
+    if not (0.0 <= x < 1.0 and 0.0 <= y < 1.0):
+        raise ValueError("roi x, y must be in [0, 1)")
+    if not (0.0 < w <= 1.0 and 0.0 < h <= 1.0):
+        raise ValueError("roi w, h must be in (0, 1]")
+    if x + w > 1.0 + 1e-6 or y + h > 1.0 + 1e-6:
+        raise ValueError("roi extends past image bounds (x+w or y+h > 1)")
+    return {"x": x, "y": y, "w": min(w, 1.0 - x), "h": min(h, 1.0 - y)}
+
+
+def _rasterio_read_roi(path: Path, roi: dict, max_side: int) -> Image.Image:
+    """Read only the ROI window of a GeoTIFF natively (fast, low memory)."""
+    import rasterio
+    from rasterio.enums import Resampling
+    from rasterio.windows import Window
+
+    with rasterio.open(path) as src:
+        W, H = int(src.width), int(src.height)
+        col0 = int(round(roi["x"] * W))
+        row0 = int(round(roi["y"] * H))
+        cw = min(max(1, int(round(roi["w"] * W))), W - col0)
+        ch = min(max(1, int(round(roi["h"] * H))), H - row0)
+        win = Window(col0, row0, cw, ch)
+        count = min(3, src.count)
+        scale = min(1.0, max_side / max(cw, ch, 1))
+        out_h = max(1, int(ch * scale))
+        out_w = max(1, int(cw * scale))
+        data = src.read(
+            indexes=list(range(1, count + 1)), window=win,
+            out_shape=(count, out_h, out_w), resampling=Resampling.bilinear,
+        )
+    return Image.fromarray(_normalize_window_rgb(data), mode="RGB")
+
+
+def load_rgb_roi(path: Path, roi, max_side: Optional[int] = None) -> Image.Image:
+    """Load only a fractional ROI window of an image as RGB PIL.
+
+    ``roi = {x, y, w, h}`` are fractions in [0, 1] of the image's own pixel
+    grid. For GeoTIFFs the window is read natively from disk (so a small ROI on
+    a huge raster stays fast and low-memory), then downscaled to ``max_side``;
+    other formats are opened, cropped, and downscaled. When ``roi`` is empty,
+    falls back to a full-image load.
+    """
+    if max_side is None:
+        max_side = get_detection_max_side()
+    roi = parse_roi(roi)
+    if roi is None:
+        return load_rgb_pil(path, max_side=max_side)
+    ext = path.suffix.lower()
+    if ext in (".tif", ".tiff"):
+        try:
+            return _rasterio_read_roi(path, roi, max_side).copy()
+        except ImportError as exc:
+            raise RuntimeError(
+                "GeoTIFF support requires rasterio. Install with: pip install rasterio"
+            ) from exc
+        except Exception as exc:
+            raise RuntimeError(f"Could not read GeoTIFF ROI: {exc}") from exc
+    with Image.open(path) as img:
+        img = ImageOps.exif_transpose(img).convert("RGB")
+        W, H = img.size
+        left = int(round(roi["x"] * W))
+        top = int(round(roi["y"] * H))
+        right = max(left + 1, int(round((roi["x"] + roi["w"]) * W)))
+        bottom = max(top + 1, int(round((roi["y"] + roi["h"]) * H)))
+        crop = img.crop((left, top, right, bottom))
+        if max(crop.size) > max_side:
+            crop.thumbnail((max_side, max_side), Image.Resampling.LANCZOS)
+        return crop.copy()
+
+
+def raster_to_preview_png(src_path: Path, dest_path: Path, max_side: int = 512) -> None:
+    """Create RGB thumbnail/preview — uses decimated read for large GeoTIFFs."""
+    ext = src_path.suffix.lower()
+    if ext in (".tif", ".tiff"):
+        try:
+            img = _rasterio_read_rgb(src_path, max_side)
+            if max(img.size) > max_side:
+                img.thumbnail((max_side, max_side), Image.Resampling.LANCZOS)
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+            img.save(dest_path, format="PNG")
+            return
+        except Exception as exc:
+            logger.warning("GeoTIFF preview failed for %s: %s", src_path.name, exc)
+            write_placeholder_png(dest_path, src_path.name, max_side)
+            return
+
+    try:
+        with Image.open(src_path) as img:
+            img = ImageOps.exif_transpose(img)
+            img = img.convert("RGB")
+            img.thumbnail((max_side, max_side), Image.Resampling.LANCZOS)
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+            img.save(dest_path, format="PNG")
+    except Exception as exc:
+        logger.warning("Preview failed for %s: %s", src_path.name, exc)
+        write_placeholder_png(dest_path, src_path.name, max_side)
+
+
+@dataclass
+class GeorefInfo:
+    transform: Any
+    crs: Any
+    width: int
+    height: int
+    bounds_wgs84: Optional[Tuple[float, float, float, float]]
+    source: str = "embedded"  # embedded | worldfile
+
+
+def read_georef(path: Path) -> Optional[GeorefInfo]:
+    """Read raster affine transform + WGS84 bounds for any raster format.
+
+    Honors embedded CRS (GeoTIFF), GDAL .aux.xml sidecars, and ESRI world files
+    for TIFF/PNG/JPEG. Returns None when no georeferencing can be resolved.
+    """
+    width = height = 0
+    try:
+        import rasterio
+        from rasterio.warp import transform_bounds
+
+        with rasterio.open(path) as src:
+            width, height = int(src.width), int(src.height)
+            if src.crs is not None:
+                bounds = None
+                try:
+                    w, s, e, n = transform_bounds(src.crs, "EPSG:4326", *src.bounds)
+                    bounds = (float(w), float(s), float(e), float(n))
+                except Exception as exc:
+                    logger.warning("Could not transform bounds for %s: %s", path.name, exc)
+                return GeorefInfo(
+                    transform=src.transform, crs=src.crs,
+                    width=width, height=height, bounds_wgs84=bounds, source="embedded",
+                )
+    except ImportError:
+        return None
+    except Exception as exc:
+        logger.warning("read_georef rasterio open failed for %s: %s", path.name, exc)
+
+    # No embedded CRS — try an explicit world-file sidecar
+    if width <= 0 or height <= 0:
+        try:
+            with Image.open(path) as img:
+                width, height = img.size
+        except Exception:
+            return None
+    wf = _world_file_georef(path, width, height)
+    if wf is not None and wf[2] is not None:
+        transform, crs, bounds = wf
+        return GeorefInfo(
+            transform=transform, crs=crs,
+            width=width, height=height, bounds_wgs84=bounds, source="worldfile",
+        )
+    return None
+
+
+def read_gsd_meters(path: Path) -> Optional[float]:
+    """Ground sample distance (meters/pixel) from the raster's georeferencing.
+
+    For geographic CRS (degrees) the pixel size is converted to meters at the
+    raster's center latitude. Returns None when no usable georef exists.
+    """
+    info = read_georef(path)
+    if info is None or info.transform is None:
+        return None
+    try:
+        px_x = abs(float(info.transform.a))
+        px_y = abs(float(info.transform.e))
+        if px_x <= 0 or px_y <= 0:
+            return None
+        gsd = (px_x + px_y) / 2.0
+        crs = info.crs
+        is_geographic = False
+        try:
+            is_geographic = bool(crs is not None and crs.is_geographic)
+        except Exception:
+            is_geographic = bool(crs is not None and "4326" in str(crs))
+        if is_geographic:
+            import math
+            lat = 0.0
+            if info.bounds_wgs84:
+                lat = (info.bounds_wgs84[1] + info.bounds_wgs84[3]) / 2.0
+            meters_per_deg = 111320.0 * max(0.2, math.cos(math.radians(lat)))
+            gsd *= meters_per_deg
+        return float(gsd) if gsd > 0 else None
+    except Exception as exc:
+        logger.warning("read_gsd_meters failed for %s: %s", path.name, exc)
+        return None
+
+
+def harmonize_pair_gsd(
+    before_pil: Image.Image,
+    after_pil: Image.Image,
+    before_path: Path,
+    after_path: Path,
+):
+    """Resample a loaded image pair to a common (coarser) ground resolution.
+
+    SRCDNet motivation: when the two acquisitions have different GSDs, naive
+    pixel-grid alignment upsamples the coarser image and the interpolated
+    texture produces spurious "changes". Downsampling BOTH to the coarser GSD
+    (area-weighted) avoids hallucinated texture diffs.
+
+    Accounts for any load-time downscaling by scaling each file's native GSD
+    with its loaded/native width ratio. Returns ``(before, after, debug)``
+    where debug is None when harmonization was skipped or not needed.
+    """
+    from ..detection_config import get_gsd_harmonize, get_gsd_tolerance
+
+    if not get_gsd_harmonize():
+        return before_pil, after_pil, None
+    try:
+        gsd_b = read_gsd_meters(before_path)
+        gsd_a = read_gsd_meters(after_path)
+        if not gsd_b or not gsd_a:
+            return before_pil, after_pil, None
+
+        native_b = read_native_size(before_path)
+        native_a = read_native_size(after_path)
+        if not native_b or not native_a:
+            return before_pil, after_pil, None
+
+        # Effective GSD of the in-memory image after load-time downscaling
+        eff_b = gsd_b * (native_b[0] / float(before_pil.size[0]))
+        eff_a = gsd_a * (native_a[0] / float(after_pil.size[0]))
+
+        rel_diff = abs(eff_b - eff_a) / max(eff_b, eff_a)
+        tolerance = get_gsd_tolerance()
+        debug = {
+            "gsdBefore": round(eff_b, 4),
+            "gsdAfter": round(eff_a, 4),
+            "relDiff": round(rel_diff, 4),
+            "tolerance": tolerance,
+            "harmonized": False,
+        }
+        if rel_diff <= tolerance:
+            return before_pil, after_pil, debug
+
+        target = max(eff_b, eff_a)  # coarser resolution wins
+        out = []
+        for img, eff in ((before_pil, eff_b), (after_pil, eff_a)):
+            scale = eff / target
+            if scale < 0.999:
+                new_size = (max(64, round(img.size[0] * scale)),
+                            max(64, round(img.size[1] * scale)))
+                # BOX = area-weighted downsample (no hallucinated texture)
+                img = img.resize(new_size, Image.Resampling.BOX)
+            out.append(img)
+        debug["harmonized"] = True
+        debug["targetGsd"] = round(target, 4)
+        debug["sizeBefore"] = list(out[0].size)
+        debug["sizeAfter"] = list(out[1].size)
+        logger.info("GSD harmonized to %.3f m/px (before %.3f, after %.3f)",
+                    target, eff_b, eff_a)
+        return out[0], out[1], debug
+    except Exception as exc:
+        logger.warning("GSD harmonization failed: %s", exc)
+        return before_pil, after_pil, None
+
+
+def pixel_to_geo_wgs84(
+    x: float,
+    y: float,
+    georef: GeorefInfo,
+    *,
+    detection_width: int,
+    detection_height: int,
+) -> Optional[Tuple[float, float]]:
+    """Map detection pixel (x=col, y=row) to WGS84 (lng, lat)."""
+    if detection_width <= 0 or detection_height <= 0:
+        return None
+    try:
+        from rasterio.transform import xy as transform_xy
+        from rasterio.warp import transform as warp_transform
+
+        scale_x = georef.width / float(detection_width)
+        scale_y = georef.height / float(detection_height)
+        col = float(x) * scale_x
+        row = float(y) * scale_y
+        geo_x, geo_y = transform_xy(georef.transform, row, col, offset="center")
+        if georef.crs and str(georef.crs) != "EPSG:4326":
+            lngs, lats = warp_transform(georef.crs, "EPSG:4326", [geo_x], [geo_y])
+            return float(lngs[0]), float(lats[0])
+        return float(geo_x), float(geo_y)
+    except Exception as exc:
+        logger.warning("pixel_to_geo_wgs84 failed: %s", exc)
+        return None
+
+
+def bounds_to_json(bounds: Optional[Tuple[float, float, float, float]]) -> str:
+    if not bounds:
+        return ""
+    return json.dumps({"west": bounds[0], "south": bounds[1], "east": bounds[2], "north": bounds[3]})

app/dda/job_progress.py

@@ -0,0 +1,47 @@
+"""Persist detection job progress for UI polling."""
+from __future__ import annotations
+
+import json
+import logging
+
+from ..database import SessionLocal
+from .models import DetectionJob
+
+logger = logging.getLogger(__name__)
+
+
+def update_job_progress(job_id: int, pct: int, stage: str) -> None:
+    """Update progress_pct and progress_stage in job params_json."""
+    db = SessionLocal()
+    try:
+        job = db.query(DetectionJob).filter(DetectionJob.id == job_id).first()
+        if not job or job.status not in ("queued", "running"):
+            return
+        params = {}
+        try:
+            params = json.loads(job.params_json or "{}")
+        except json.JSONDecodeError:
+            pass
+        params["progress_pct"] = max(0, min(100, int(pct)))
+        params["progress_stage"] = stage or ""
+        job.params_json = json.dumps(params)
+        db.commit()
+    except Exception as exc:
+        logger.warning("Could not update job %d progress: %s", job_id, exc)
+        db.rollback()
+    finally:
+        db.close()
+
+
+def get_job_progress(params: dict, status: str) -> tuple[int, str]:
+    pct = params.get("progress_pct")
+    stage = params.get("progress_stage") or ""
+    if status == "completed":
+        return 100, stage or "Complete"
+    if status == "failed":
+        return int(pct) if pct is not None else 0, stage or "Failed"
+    if status == "queued":
+        return int(pct) if pct is not None else 0, stage or "Queued"
+    if pct is None:
+        return 10, stage or "Running"
+    return int(pct), stage or "Running"

app/dda/job_runner.py

@@ -0,0 +1,373 @@
+"""Background detection job runner (FR-04 async pipeline)."""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from PIL import Image
+from sqlalchemy.orm import Session
+
+from ..auth import get_or_create_guest_user
+from ..database import SessionLocal
+from ..models import DetectionRun
+from .detect_service import run_detection_and_save
+from .geotiff_io import load_rgb_pil
+from .job_progress import update_job_progress
+from .local_routes import safe_resolve
+from .models import DetectionJob
+from .preflight import PreflightResult
+
+logger = logging.getLogger(__name__)
+
+_runner_lock = threading.Lock()
+_active_job_id: Optional[int] = None
+
+
+def _utcnow():
+    return datetime.now(timezone.utc)
+
+
+def _load_pair(
+    db: Session, base_path: str, comparison_path: str, roi: Optional[dict] = None,
+) -> tuple[Image.Image, Image.Image, Path, Optional[dict], PreflightResult]:
+    from ..detection_config import get_load_max_side
+    from .geotiff_io import load_rgb_roi
+    from .preflight import run_preflight_checks
+    base_file = safe_resolve(base_path)
+    comp_file = safe_resolve(comparison_path)
+
+    preflight = run_preflight_checks(db, base_file, comp_file, base_path, comparison_path, roi=roi)
+    if preflight.hard_fail:
+        raise ValueError(preflight.fail_reason)
+
+    max_side = get_load_max_side()
+    if roi:
+        # Crop both images to the same fractional window before detection so a
+        # small ROI on a huge raster runs fast and at full detail.
+        before_pil = load_rgb_roi(base_file, roi, max_side=max_side)
+        after_pil = load_rgb_roi(comp_file, roi, max_side=max_side)
+    else:
+        before_pil = load_rgb_pil(base_file, max_side=max_side)
+        after_pil = load_rgb_pil(comp_file, max_side=max_side)
+
+    gsd_debug = None
+    try:
+        from .geotiff_io import harmonize_pair_gsd
+        before_pil, after_pil, gsd_debug = harmonize_pair_gsd(
+            before_pil, after_pil, base_file, comp_file)
+    except Exception as exc:
+        logger.warning("GSD harmonization skipped: %s", exc)
+
+    if before_pil.size != after_pil.size:
+        after_pil = after_pil.resize(before_pil.size, Image.Resampling.LANCZOS)
+    return before_pil, after_pil, base_file, gsd_debug, preflight
+
+
+def _parse_params(job: DetectionJob) -> Dict[str, Any]:
+    try:
+        return json.loads(job.params_json or "{}")
+    except json.JSONDecodeError:
+        return {}
+
+
+def _run_job_sync(job_id: int) -> None:
+    global _active_job_id
+    db = SessionLocal()
+    try:
+        job = db.query(DetectionJob).filter(DetectionJob.id == job_id).first()
+        if not job or job.status not in ("queued", "running"):
+            return
+
+        job.status = "running"
+        job.started_at = _utcnow()
+        job.error_message = ""
+        params = _parse_params(job)
+        method = job.method or params.get("method", "AI-Based Deep Learning")
+        created_by = job.created_by
+        notify_email = job.notify_email or params.get("notify_email")
+        db.commit()
+        # Detach the job row so this session cannot overwrite progress_pct
+        # written by update_job_progress() on another connection, and so we
+        # do not hold a SQLite/InnoDB transaction across the long CPU work.
+        db.expunge_all()
+        update_job_progress(job_id, 5, "Starting job")
+
+        base_path = params.get("base_path", "")
+        comparison_path = params.get("comparison_path", "")
+        if not base_path or not comparison_path:
+            raise ValueError("Job missing base_path or comparison_path in params_json")
+
+        roi = params.get("roi")
+        update_job_progress(job_id, 8, "Cropping ROI" if roi else "Loading images")
+        before_pil, after_pil, base_file, gsd_debug, preflight = _load_pair(
+            db, base_path, comparison_path, roi=roi)
+        comp_file = safe_resolve(comparison_path)
+        if preflight.warnings:
+            params["preflightWarnings"] = preflight.warnings
+            job = db.query(DetectionJob).filter(DetectionJob.id == job_id).first()
+            if job:
+                job.params_json = json.dumps(params)
+                db.commit()
+                db.expunge_all()
+        if roi:
+            logger.info("Job %d ROI crop %s -> working size %s",
+                        job_id, roi, before_pil.size)
+        update_job_progress(job_id, 12, "Images loaded")
+        title = params.get("title") or f"{Path(base_path).name} vs {Path(comparison_path).name}"
+        from ..detection_config import get_load_max_side
+        # Must use fullres load cap — get_detection_max_side() is 4096 and was
+        # silently downscaling overnight "max res" runs back to preview size.
+        detect_max = get_load_max_side(base_path, comparison_path)
+        logger.info(
+            "Job %d detection max_size=%d (loaded %s)",
+            job_id, detect_max, before_pil.size,
+        )
+        result = run_detection_and_save(
+            db,
+            before_pil,
+            after_pil,
+            method=method,
+            title=title,
+            zone=params.get("zone", ""),
+            village=params.get("village", ""),
+            enable_registration=bool(params.get("enable_registration", True)),
+            enable_normalization=bool(params.get("enable_normalization", True)),
+            detection_sensitivity=float(params.get("detection_sensitivity", 0.45)),
+            min_region_area=params.get("min_region_area"),
+            notify_email=notify_email,
+            max_size=detect_max,
+            geo_bounds_path=base_file,
+            comparison_file=comp_file,
+            base_path=base_path,
+            comparison_path=comparison_path,
+            user_id=created_by,
+            job_id=job_id,
+            gsd_debug=gsd_debug,
+            shape_mode=params.get("shape_mode", "polygon"),
+            preflight_warnings=preflight.warnings,
+        )
+
+        update_job_progress(job_id, 100, "Complete")
+
+        job = db.query(DetectionJob).filter(DetectionJob.id == job_id).first()
+        if not job:
+            logger.error("Detection job %d vanished after completion", job_id)
+            return
+        job.status = "completed"
+        job.run_id = result["id"]
+        job.completed_at = _utcnow()
+        db.commit()
+        logger.info("Detection job %d completed → run %s", job_id, result["id"])
+        from .auto_detect import mark_schedule_from_job
+        mark_schedule_from_job(job_id, status="completed", run_id=result["id"])
+    except Exception as exc:
+        logger.exception("Detection job %d failed", job_id)
+        try:
+            job = db.query(DetectionJob).filter(DetectionJob.id == job_id).first()
+            if job:
+                job.status = "failed"
+                job.error_message = str(exc)[:2000]
+                job.completed_at = _utcnow()
+                db.commit()
+            from .auto_detect import mark_schedule_from_job
+            mark_schedule_from_job(job_id, status="failed", run_id=None, error=str(exc)[:2000])
+        except Exception:
+            db.rollback()
+    finally:
+        with _runner_lock:
+            if _active_job_id == job_id:
+                _active_job_id = None
+        db.close()
+
+
+def _job_worker(job_id: int) -> None:
+    global _active_job_id
+    with _runner_lock:
+        _active_job_id = job_id
+    try:
+        _run_job_sync(job_id)
+    finally:
+        with _runner_lock:
+            if _active_job_id == job_id:
+                _active_job_id = None
+        try:
+            start_next_queued_job()
+        except Exception:
+            logger.exception("Could not start next queued detection job")
+
+
+def enqueue_detection_job(job_id: int) -> bool:
+    """Start job in a background thread. Returns False if another job is running."""
+    global _active_job_id
+    with _runner_lock:
+        if _active_job_id is not None:
+            return False
+        _active_job_id = job_id
+    thread = threading.Thread(target=_job_worker, args=(job_id,), daemon=True, name=f"dda-job-{job_id}")
+    thread.start()
+    return True
+
+
+def is_job_runner_busy() -> bool:
+    with _runner_lock:
+        return _active_job_id is not None
+
+
+def start_next_queued_job() -> bool:
+    """Start the oldest queued job if the runner is idle.
+
+    Auto-scheduled jobs stay queued until the operator has clicked Start.
+    """
+    if is_job_runner_busy():
+        return False
+    from .auto_detect import is_auto_schedule_job, scheduler_is_armed
+    armed = scheduler_is_armed()
+    db = SessionLocal()
+    try:
+        pending = (
+            db.query(DetectionJob)
+            .filter(DetectionJob.status == "queued")
+            .order_by(DetectionJob.created_at.asc())
+            .all()
+        )
+        for job in pending:
+            if is_auto_schedule_job(job) and not armed:
+                continue
+            return enqueue_detection_job(job.id)
+        return False
+    finally:
+        db.close()
+
+
+def reconcile_stale_jobs(db: Session, max_running_hours: float = 3.0) -> int:
+    """Mark orphaned / stuck running jobs failed; re-queue oldest queued job.
+
+    - Orphans: status=running but no in-process worker (server restart).
+    - Stuck: status=running longer than ``max_running_hours`` (crashed worker).
+    """
+    from datetime import timedelta
+
+    fixed = 0
+    busy = is_job_runner_busy()
+    cutoff = _utcnow() - timedelta(hours=max_running_hours)
+    running = db.query(DetectionJob).filter(DetectionJob.status == "running").all()
+    for job in running:
+        started = job.started_at or job.created_at
+        # Normalize naive datetimes from SQLite
+        if started is not None and started.tzinfo is None:
+            started = started.replace(tzinfo=timezone.utc)
+        stale_by_age = started is not None and started < cutoff
+        orphaned = not busy
+        if not (orphaned or stale_by_age):
+            continue
+        job.status = "failed"
+        if stale_by_age and busy:
+            job.error_message = (
+                f"Job timed out after {max_running_hours:g}h with no completion. "
+                "Please run detection again."
+            )
+        else:
+            job.error_message = "Job interrupted (server restarted). Please run detection again."
+        job.completed_at = _utcnow()
+        fixed += 1
+    if fixed:
+        db.commit()
+        logger.info("Reconciled %d stale running job(s)", fixed)
+
+    if not is_job_runner_busy():
+        start_next_queued_job()
+    return fixed
+
+
+def create_local_folder_job(
+    db: Session,
+    *,
+    base_path: str,
+    comparison_path: str,
+    method: str = "AI-Based Deep Learning",
+    title: str = "",
+    zone: str = "",
+    village: str = "",
+    enable_registration: bool = True,
+    enable_normalization: bool = True,
+    detection_sensitivity: float = 0.45,
+    min_region_area: Optional[int] = 150,
+    notify_email: str = "",
+    created_by: Optional[int] = None,
+    roi: Optional[dict] = None,
+    shape_mode: str = "polygon",
+    extra_params: Optional[Dict[str, Any]] = None,
+) -> DetectionJob:
+    user = get_or_create_guest_user(db)
+    params = {
+        "source": "local_folder",
+        "base_path": base_path.replace("\\", "/"),
+        "comparison_path": comparison_path.replace("\\", "/"),
+        "method": method,
+        "title": title,
+        "zone": zone,
+        "village": village,
+        "enable_registration": enable_registration,
+        "enable_normalization": enable_normalization,
+        "detection_sensitivity": detection_sensitivity,
+        "min_region_area": min_region_area,
+    }
+    if extra_params:
+        params.update(extra_params)
+    if roi:
+        params["roi"] = roi
+    params["shape_mode"] = shape_mode
+    job = DetectionJob(
+        status="queued",
+        base_image_id=None,
+        comparison_image_id=None,
+        method=method,
+        params_json=json.dumps(params),
+        notify_email=notify_email or "",
+        created_by=created_by or user.id,
+    )
+    db.add(job)
+    db.commit()
+    db.refresh(job)
+    return job
+
+
+def job_to_dict(job: DetectionJob, run: Optional[DetectionRun] = None) -> dict:
+    from .job_progress import get_job_progress
+
+    params = _parse_params(job)
+    progress_pct, progress_stage = get_job_progress(params, job.status)
+    out = {
+        "id": job.id,
+        "status": job.status,
+        "method": job.method,
+        "basePath": params.get("base_path", ""),
+        "comparisonPath": params.get("comparison_path", ""),
+        "title": params.get("title", ""),
+        "runId": job.run_id,
+        "errorMessage": job.error_message or "",
+        "notifyEmail": job.notify_email or "",
+        "preflightWarnings": params.get("preflightWarnings", []),
+        "progressPct": progress_pct,
+        "progressStage": progress_stage,
+        "createdAt": job.created_at.isoformat() if job.created_at else None,
+        "startedAt": job.started_at.isoformat() if job.started_at else None,
+        "completedAt": job.completed_at.isoformat() if job.completed_at else None,
+        "source": params.get("source") or "",
+        "autoScheduled": params.get("source") == "auto_schedule",
+        "zone": params.get("zone") or (getattr(run, "zone", None) if run else "") or "",
+        "village": params.get("village") or (getattr(run, "village", None) if run else "") or "",
+    }
+    if run:
+        out["report"] = {
+            "id": run.id,
+            "title": run.title,
+            "changePercentage": run.change_percentage,
+            "regionsCount": run.regions_count,
+            "overlayUrl": f"/api/overlay/{run.overlay_path}" if run.overlay_path else None,
+        }
+    return out

app/dda/jobs_routes.py

@@ -0,0 +1,288 @@
+"""Async detection job API (FR-04)."""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Form, HTTPException, Query, Request
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models import DetectionRun, User
+from .dda_auth import current_dda_user
+from .job_runner import (
+    create_local_folder_job,
+    enqueue_detection_job,
+    is_job_runner_busy,
+    job_to_dict,
+    reconcile_stale_jobs,
+)
+from .local_routes import safe_resolve
+from .models import DetectionJob
+from .rbac.permissions import require_module_permission
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+def _require_dda():
+    from .config import IS_DDA_MODE
+    if not IS_DDA_MODE:
+        raise HTTPException(status_code=404, detail="DDA mode is not enabled")
+
+
+@router.post("/jobs")
+async def create_job(
+    base_path: str = Form(...),
+    comparison_path: str = Form(...),
+    method: str = Form("AI-Based Deep Learning"),
+    title: str = Form(""),
+    zone: str = Form(""),
+    village: str = Form(""),
+    enable_registration: bool = Form(True),
+    enable_normalization: bool = Form(True),
+    detection_sensitivity: float = Form(0.45),
+    min_region_area: Optional[int] = Form(150),
+    notify_email: Optional[str] = Form(None),
+    roi: Optional[str] = Form(None),
+    shape_mode: str = Form("polygon"),
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("detect", "create")),
+):
+    """Queue async detection from local library paths. Returns immediately with jobId.
+
+    ``roi`` (optional) is a JSON object ``{"x","y","w","h"}`` with fractional
+    coordinates in [0,1]; when present, detection runs only on that cropped
+    window (fast "test on a small area").
+    """
+    _require_dda()
+    base_norm = base_path.replace("\\", "/").strip()
+    comp_norm = comparison_path.replace("\\", "/").strip()
+    if not base_norm or not comp_norm:
+        raise HTTPException(status_code=400, detail="base_path and comparison_path are required")
+    if base_norm == comp_norm:
+        raise HTTPException(status_code=400, detail="Base and comparison images must be different")
+
+    roi_dict = None
+    if roi and roi.strip():
+        import json as _json
+
+        from .geotiff_io import parse_roi
+        try:
+            roi_dict = parse_roi(_json.loads(roi))
+        except (ValueError, _json.JSONDecodeError) as exc:
+            raise HTTPException(status_code=400, detail=f"Invalid roi: {exc}") from exc
+
+    try:
+        safe_resolve(base_norm)
+        safe_resolve(comp_norm)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid library path: {exc}") from exc
+
+    if is_job_runner_busy():
+        raise HTTPException(
+            status_code=409,
+            detail="Another detection job is already running. Wait for it to finish, then try again.",
+        )
+
+    # Clear DB orphans left after UI timeout / server restart so new jobs can start
+    reconcile_stale_jobs(db)
+
+    if is_job_runner_busy():
+        raise HTTPException(
+            status_code=409,
+            detail="Another detection job is already running. Wait for it to finish, then try again.",
+        )
+
+    if not title.strip():
+        from pathlib import Path
+        title = f"{Path(base_norm).name} vs {Path(comp_norm).name}"
+
+    job = create_local_folder_job(
+        db,
+        base_path=base_norm,
+        comparison_path=comp_norm,
+        method=method,
+        title=title,
+        zone=zone,
+        village=village,
+        enable_registration=enable_registration,
+        enable_normalization=enable_normalization,
+        detection_sensitivity=detection_sensitivity,
+        min_region_area=min_region_area,
+        notify_email=notify_email or "",
+        created_by=user.id,
+        roi=roi_dict,
+        shape_mode=shape_mode,
+    )
+
+    if not enqueue_detection_job(job.id):
+        job.status = "failed"
+        job.error_message = "Could not start background worker"
+        db.commit()
+        raise HTTPException(status_code=503, detail="Job queue is busy")
+
+    return {"jobId": job.id, "status": "queued", "message": "Detection job queued. Poll GET /api/dda/jobs/{id} for status."}
+
+
+@router.get("/jobs/{job_id}")
+def get_job(job_id: int, db: Session = Depends(get_db), user: User = Depends(current_dda_user)):
+    _require_dda()
+    from .auto_detect import is_auto_schedule_job, is_auto_schedule_run
+
+    job = db.query(DetectionJob).filter(DetectionJob.id == job_id).first()
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+    if job.created_by and job.created_by != user.id and not is_auto_schedule_job(job):
+        raise HTTPException(status_code=403, detail="Not allowed to view this job")
+
+    run = None
+    if job.run_id:
+        run = db.query(DetectionRun).filter(DetectionRun.id == job.run_id).first()
+
+    data = job_to_dict(job, run=run)
+    if job.status == "completed" and run:
+        try:
+            data["result"] = _run_detail(db, run, user.id)
+            if data.get("preflightWarnings"):
+                data["result"].setdefault("statistics", {})["preflightWarnings"] = data["preflightWarnings"]
+        except HTTPException:
+            raise
+        except Exception as exc:
+            logger.warning("Could not load full run for job %s: %s", job_id, exc)
+            data["resultError"] = str(exc)[:500]
+    return data
+
+
+def _run_detail(db: Session, run: DetectionRun, user_id: int) -> dict:
+    import base64
+
+    from ..database import DATA_DIR
+    from .auto_detect import is_auto_schedule_run
+
+    if run.user_id != user_id and not is_auto_schedule_run(db, run.id):
+        raise HTTPException(status_code=403, detail="Not allowed")
+
+    regions = json.loads(run.regions_json or "[]")
+    from .review_service import merge_reviews
+    regions = merge_reviews(db, run.id, regions)
+    overlay_b64 = ""
+    if run.overlay_path:
+        overlay_file = DATA_DIR / run.overlay_path
+        if overlay_file.exists():
+            overlay_b64 = base64.b64encode(overlay_file.read_bytes()).decode("utf-8")
+
+    from ..detection_config import get_load_max_side
+    from .detect_service import _isoformat_ist
+
+    return {
+        "id": run.id,
+        "title": run.title,
+        "method": run.method,
+        "zone": run.zone or "",
+        "village": run.village or "",
+        "statistics": {
+            "totalPixels": run.total_pixels,
+            "changedPixels": run.changed_pixels,
+            "unchangedPixels": run.total_pixels - run.changed_pixels,
+            "changePercentage": run.change_percentage,
+        },
+        "regions": regions,
+        "overlayBase64Png": overlay_b64,
+        "overlayUrl": f"/api/overlay/{run.overlay_path}" if run.overlay_path else None,
+        "beforeFullUrl": f"/api/overlay/{run.before_full_path}" if run.before_full_path else None,
+        "beforeThumbUrl": f"/api/overlay/{run.before_thumb_path}" if run.before_thumb_path else None,
+        "afterThumbUrl": f"/api/overlay/{run.after_thumb_path}" if run.after_thumb_path else None,
+        "afterFullUrl": f"/api/overlay/{run.after_full_path}" if getattr(run, "after_full_path", None) else None,
+        "createdAt": _isoformat_ist(run.created_at),
+        "detectionMaxSide": get_load_max_side(),
+    }
+
+
+@router.get("/jobs")
+def list_jobs(
+    status: Optional[str] = Query(None),
+    limit: int = Query(20, ge=1, le=100),
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    """Recent detection jobs for in-app notifications / reports feed (FR-05 partial)."""
+    _require_dda()
+    from .job_runner import reconcile_stale_jobs
+    reconcile_stale_jobs(db)
+    from .auto_detect import is_auto_schedule_job
+    q = db.query(DetectionJob).filter(DetectionJob.created_by == user.id)
+    if status:
+        q = q.filter(DetectionJob.status == status)
+    jobs = q.order_by(DetectionJob.created_at.desc()).limit(limit).all()
+    seen = {job.id for job in jobs}
+    extra = (
+        db.query(DetectionJob)
+        .order_by(DetectionJob.created_at.desc())
+        .limit(80)
+        .all()
+    )
+    for job in extra:
+        if job.id in seen:
+            continue
+        if not is_auto_schedule_job(job):
+            continue
+        if status and job.status != status:
+            continue
+        jobs.append(job)
+        seen.add(job.id)
+    jobs.sort(key=lambda j: j.id, reverse=True)
+    jobs = jobs[:limit]
+    out = []
+    for job in jobs:
+        run = db.query(DetectionRun).filter(DetectionRun.id == job.run_id).first() if job.run_id else None
+        out.append(job_to_dict(job, run=run))
+    return {"jobs": out, "runnerBusy": is_job_runner_busy()}
+
+
+@router.get("/auto-detect")
+def auto_detect_status(db: Session = Depends(get_db), user: User = Depends(current_dda_user)):
+    """Schedule for identified same-area pairs (Automatic mode)."""
+    _require_dda()
+    from .auto_detect import refresh_schedule_rows, schedule_status_payload
+
+    try:
+        refresh_schedule_rows()
+    except Exception as exc:
+        logger.warning("Auto-detect schedule sync skipped: %s", exc)
+    return schedule_status_payload(db)
+
+
+class AutoDetectStartBody(BaseModel):
+    intervalDays: int = Field(10, ge=1, le=365)
+    runAt: str = "02:00"
+
+
+@router.post("/auto-detect/start")
+def auto_detect_start(
+    body: AutoDetectStartBody,
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("detect", "create")),
+):
+    """Arm the automatic queue. Does not enqueue jobs immediately."""
+    _require_dda()
+    from .auto_detect import start_schedule
+    try:
+        return start_schedule(interval_days=body.intervalDays, run_at=body.runAt)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@router.post("/auto-detect/stop")
+def auto_detect_stop(
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("detect", "create")),
+):
+    """Stop the automatic queue and cancel queued auto jobs."""
+    _require_dda()
+    from .auto_detect import stop_schedule
+    return stop_schedule()

app/dda/library_routes.py

@@ -0,0 +1,273 @@
+import json
+import logging
+import shutil
+import uuid
+from datetime import date, datetime
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Query, UploadFile
+from fastapi.responses import FileResponse
+from sqlalchemy.orm import Session
+
+from ..auth import get_or_create_guest_user
+from ..database import get_db
+from ..models import User
+from .dda_auth import current_dda_user
+from .config import (
+    ALLOWED_EXTENSIONS,
+    IS_DDA_MODE,
+    LIBRARY_DIR,
+    PREVIEWS_DIR,
+    THUMBS_DIR,
+    ensure_library_dirs,
+    geotiff_io_available,
+    max_upload_bytes_for_extension,
+)
+from .geotiff_io import bounds_to_json, inspect_image, raster_to_preview_png
+from .models import DdaVillage, DdaZone, ImageAsset
+from .upload_io import stream_upload_to_file
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+def _require_dda():
+    if not IS_DDA_MODE:
+        raise HTTPException(status_code=404, detail="DDA mode is not enabled on this server")
+
+
+def _image_to_dict(asset: ImageAsset, zone_name: str = "", village_name: str = "") -> dict:
+    return {
+        "id": asset.id,
+        "uuid": asset.uuid,
+        "zoneId": asset.zone_id,
+        "zoneName": zone_name,
+        "villageId": asset.village_id,
+        "villageName": village_name,
+        "areaName": asset.area_name or "",
+        "year": asset.year,
+        "gridId": asset.grid_id or "",
+        "captureDate": asset.capture_date.isoformat() if asset.capture_date else None,
+        "source": asset.source,
+        "format": asset.format,
+        "originalFilename": asset.original_filename,
+        "hasGeoref": asset.has_georef,
+        "crs": asset.crs or "",
+        "bounds": json.loads(asset.bounds_json) if asset.bounds_json else None,
+        "width": asset.width,
+        "height": asset.height,
+        "fileSizeBytes": asset.file_size_bytes,
+        "thumbUrl": f"/api/dda/images/{asset.id}/thumb" if asset.thumb_path else None,
+        "createdAt": asset.created_at.isoformat() if asset.created_at else None,
+    }
+
+
+@router.get("/config")
+def dda_config():
+    _require_dda()
+    from .config import MAX_GEOTIFF_BYTES, MAX_IMAGE_BYTES, get_library_roots, get_storage_root
+    max_gb = MAX_GEOTIFF_BYTES / (1024 ** 3)
+    return {
+        "mode": "dda",
+        "appMode": "dda",
+        "maxUploadMb": MAX_GEOTIFF_BYTES // (1024 * 1024),
+        "maxUploadGb": round(max_gb, 2),
+        "maxGeotiffMb": MAX_GEOTIFF_BYTES // (1024 * 1024),
+        "maxGeotiffBytes": MAX_GEOTIFF_BYTES,
+        "maxImageMb": MAX_IMAGE_BYTES // (1024 * 1024),
+        "maxImageBytes": MAX_IMAGE_BYTES,
+        "geotiffEnabled": geotiff_io_available(),
+        "allowedExtensions": sorted(ALLOWED_EXTENSIONS),
+        "hierarchyMode": "tree",
+        "librarySource": "tree_library",
+        "storageRoot": str(get_storage_root()),
+        "localLibraryPaths": [str(r) for r in get_library_roots()],
+    }
+
+
+@router.get("/hierarchy")
+def get_hierarchy(db: Session = Depends(get_db), user: User = Depends(current_dda_user)):
+    _require_dda()
+    from .tree.tree_service import build_tree
+    return {"tree": build_tree(db)}
+
+
+@router.get("/images")
+def list_images(
+    zone_id: Optional[int] = Query(None),
+    village_id: Optional[int] = Query(None),
+    year: Optional[int] = Query(None),
+    q: Optional[str] = Query(None),
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    _require_dda()
+    query = db.query(ImageAsset).order_by(ImageAsset.created_at.desc())
+    if zone_id:
+        query = query.filter(ImageAsset.zone_id == zone_id)
+    if village_id:
+        query = query.filter(ImageAsset.village_id == village_id)
+    if year:
+        query = query.filter(ImageAsset.year == year)
+    if q:
+        like = f"%{q.strip()}%"
+        query = query.filter(
+            (ImageAsset.area_name.ilike(like))
+            | (ImageAsset.original_filename.ilike(like))
+            | (ImageAsset.grid_id.ilike(like))
+        )
+    assets = query.limit(200).all()
+    zone_map = {z.id: z.name for z in db.query(DdaZone).all()}
+    village_map = {v.id: v.name for v in db.query(DdaVillage).all()}
+    return [
+        _image_to_dict(
+            a,
+            zone_name=zone_map.get(a.zone_id, ""),
+            village_name=village_map.get(a.village_id, ""),
+        )
+        for a in assets
+    ]
+
+
+@router.get("/images/{image_id}")
+def get_image(image_id: int, db: Session = Depends(get_db), user: User = Depends(current_dda_user)):
+    _require_dda()
+    asset = db.query(ImageAsset).filter(ImageAsset.id == image_id).first()
+    if not asset:
+        raise HTTPException(status_code=404, detail="Image not found")
+    zone_name = ""
+    village_name = ""
+    if asset.zone_id:
+        z = db.query(DdaZone).filter(DdaZone.id == asset.zone_id).first()
+        zone_name = z.name if z else ""
+    if asset.village_id:
+        v = db.query(DdaVillage).filter(DdaVillage.id == asset.village_id).first()
+        village_name = v.name if v else ""
+    return _image_to_dict(asset, zone_name=zone_name, village_name=village_name)
+
+
+@router.get("/images/{image_id}/thumb")
+def get_image_thumb(image_id: int, db: Session = Depends(get_db), user: User = Depends(current_dda_user)):
+    _require_dda()
+    asset = db.query(ImageAsset).filter(ImageAsset.id == image_id).first()
+    if not asset or not asset.thumb_path:
+        raise HTTPException(status_code=404, detail="Thumbnail not found")
+    path = LIBRARY_DIR.parent / asset.thumb_path
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="Thumbnail file missing")
+    return FileResponse(path, media_type="image/png")
+
+
+@router.post("/images/upload")
+async def upload_image(
+    file: UploadFile = File(...),
+    zone_id: int = Form(...),
+    village_id: int = Form(...),
+    area_name: str = Form(""),
+    year: int = Form(...),
+    capture_date: str = Form(...),
+    source: str = Form("satellite"),
+    grid_id: str = Form(""),
+    manual_bounds_json: str = Form(""),
+    db: Session = Depends(get_db),
+):
+    _require_dda()
+    raise HTTPException(
+        status_code=410,
+        detail="Deprecated: use POST /api/dda/tree/nodes/{node_id}/images/upload",
+    )
+    ensure_library_dirs()
+    user = get_or_create_guest_user(db)
+
+    zone = db.query(DdaZone).filter(DdaZone.id == zone_id).first()
+    village = db.query(DdaVillage).filter(DdaVillage.id == village_id, DdaVillage.zone_id == zone_id).first()
+    if not zone or not village:
+        raise HTTPException(status_code=400, detail="Invalid zone or village")
+
+    original = file.filename or "upload"
+    ext = Path(original).suffix.lower()
+    if ext not in ALLOWED_EXTENSIONS:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unsupported format. Allowed: {', '.join(sorted(ALLOWED_EXTENSIONS))}",
+        )
+
+    try:
+        cap_date = date.fromisoformat(capture_date.strip())
+    except ValueError:
+        raise HTTPException(status_code=400, detail="capture_date must be YYYY-MM-DD")
+
+    if source not in ("satellite", "drone"):
+        raise HTTPException(status_code=400, detail="source must be satellite or drone")
+
+    asset_uuid = uuid.uuid4().hex
+    stored_name = f"{asset_uuid}{ext}"
+    dest_file = LIBRARY_DIR / str(year) / stored_name
+    max_bytes = max_upload_bytes_for_extension(ext)
+    file_size = await stream_upload_to_file(file, dest_file, max_bytes)
+
+    ingest = inspect_image(dest_file)
+    has_georef = ingest.has_georef
+    manual_location = manual_bounds_json.strip()
+
+    if ext in (".tif", ".tiff") and not has_georef and not manual_location:
+        dest_file.unlink(missing_ok=True)
+        raise HTTPException(
+            status_code=400,
+            detail="GeoTIFF has no embedded georeferencing. Provide manual_bounds_json (west,south,east,north in WGS84).",
+        )
+
+    thumb_file = THUMBS_DIR / f"{asset_uuid}.png"
+    preview_file = PREVIEWS_DIR / f"{asset_uuid}.png"
+    try:
+        raster_to_preview_png(dest_file, thumb_file, max_side=256)
+        raster_to_preview_png(dest_file, preview_file, max_side=1024)
+    except Exception as exc:
+        dest_file.unlink(missing_ok=True)
+        raise HTTPException(status_code=400, detail=f"Could not generate preview: {exc}")
+
+    rel_file = str(dest_file.relative_to(LIBRARY_DIR.parent))
+    rel_thumb = str(thumb_file.relative_to(LIBRARY_DIR.parent))
+    rel_preview = str(preview_file.relative_to(LIBRARY_DIR.parent))
+
+    bounds_json = bounds_to_json(ingest.bounds_wgs84)
+    if not bounds_json and manual_location:
+        try:
+            parts = [float(x.strip()) for x in manual_location.replace("[", "").replace("]", "").split(",")]
+            if len(parts) == 4:
+                bounds_json = bounds_to_json(tuple(parts))
+        except (ValueError, TypeError):
+            pass
+
+    asset = ImageAsset(
+        uuid=asset_uuid,
+        zone_id=zone_id,
+        village_id=village_id,
+        area_name=area_name.strip(),
+        year=year,
+        grid_id=grid_id.strip(),
+        capture_date=cap_date,
+        source=source,
+        format=ingest.format,
+        original_filename=original,
+        file_path=rel_file,
+        thumb_path=rel_thumb,
+        preview_path=rel_preview,
+        crs=ingest.crs,
+        bounds_json=bounds_json,
+        has_georef=has_georef or bool(bounds_json),
+        manual_location_json=manual_location,
+        width=ingest.width,
+        height=ingest.height,
+        file_size_bytes=file_size,
+        uploaded_by=user.id,
+    )
+    db.add(asset)
+    db.commit()
+    db.refresh(asset)
+
+    return {
+        "status": "success",
+        "image": _image_to_dict(asset, zone_name=zone.name, village_name=village.name),
+    }

app/dda/local_library.py

@@ -0,0 +1,202 @@
+"""
+Read satellite/drone images from local year-based folders.
+
+Folder layout (under library_sources/):
+
+    library_sources/
+      2024/
+        image_a.tif
+      2025/
+        image_c.tif
+
+Copy files into library_sources/YEAR/ in the project folder (or data/library_sources/ on HF).
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+from urllib.parse import quote
+
+from fastapi import HTTPException
+
+from .config import ALLOWED_EXTENSIONS, LOCAL_THUMB_CACHE, get_library_roots
+from .geotiff_io import inspect_image, raster_to_preview_png, write_placeholder_png
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LocalImageEntry:
+    path: str  # relative posix path, e.g. 2025/aerial.tif
+    root: Path
+    year: int
+    filename: str
+    file_size_bytes: int
+
+
+def _is_year_dir(name: str) -> bool:
+    return len(name) == 4 and name.isdigit() and 1990 <= int(name) <= 2100
+
+
+def _iter_image_files(root: Path, year: Optional[int] = None):
+    if not root.exists():
+        return
+    if year is not None:
+        year_dirs = [root / str(year)] if (root / str(year)).is_dir() else []
+    else:
+        year_dirs = [d for d in sorted(root.iterdir()) if d.is_dir() and _is_year_dir(d.name)]
+    for ydir in year_dirs:
+        y = int(ydir.name)
+        for path in sorted(ydir.rglob("*")):
+            if not path.is_file():
+                continue
+            ext = path.suffix.lower()
+            if ext not in ALLOWED_EXTENSIONS:
+                logger.debug("Skipped (extension %s): %s", ext, path)
+                continue
+            yield root, y, path
+
+
+def safe_resolve(relative_path: str) -> Path:
+    """Resolve a library-relative path across all configured roots."""
+    rel = relative_path.replace("\\", "/").lstrip("/")
+    if not rel or ".." in rel.split("/"):
+        raise HTTPException(status_code=400, detail="Invalid image path")
+    for root in get_library_roots():
+        full = (root / rel).resolve()
+        try:
+            full.relative_to(root.resolve())
+        except ValueError:
+            continue
+        if full.is_file() and full.suffix.lower() in ALLOWED_EXTENSIONS:
+            return full
+    raise HTTPException(status_code=404, detail="Image file not found")
+
+
+def scan_years() -> List[dict]:
+    """List year folders and image counts (merged across all roots)."""
+    ensure_root()
+    counts: dict[int, int] = {}
+    for root in get_library_roots():
+        if not root.exists():
+            continue
+        for entry in sorted(root.iterdir()):
+            if not entry.is_dir() or not _is_year_dir(entry.name):
+                continue
+            y = int(entry.name)
+            n = sum(1 for _ in _iter_image_files(root, year=y))
+            counts[y] = counts.get(y, 0) + n
+    return [{"year": y, "imageCount": counts[y]} for y in sorted(counts)]
+
+
+def scan_images(year: Optional[int] = None, query: Optional[str] = None) -> List[LocalImageEntry]:
+    """Scan all library roots for images."""
+    ensure_root()
+    results: List[LocalImageEntry] = []
+    seen_paths: set[str] = set()
+    q = (query or "").strip().lower()
+
+    for root in get_library_roots():
+        for r, y, path in _iter_image_files(root, year=year):
+            rel = path.relative_to(r).as_posix()
+            if rel in seen_paths:
+                continue
+            if q and q not in rel.lower():
+                continue
+            try:
+                size = path.stat().st_size
+            except OSError:
+                continue
+            seen_paths.add(rel)
+            results.append(
+                LocalImageEntry(
+                    path=rel,
+                    root=r,
+                    year=y,
+                    filename=path.name,
+                    file_size_bytes=size,
+                )
+            )
+    return results
+
+
+def entry_to_dict(entry: LocalImageEntry, include_meta: bool = False) -> dict:
+    encoded_path = quote(entry.path, safe="/")
+    out = {
+        "path": entry.path,
+        "year": entry.year,
+        "filename": entry.filename,
+        "fileSizeBytes": entry.file_size_bytes,
+        "thumbUrl": f"/api/dda/local/thumb?path={encoded_path}",
+        "source": "local_folder",
+        "rootPath": str(entry.root),
+    }
+    if include_meta:
+        try:
+            full = safe_resolve(entry.path)
+            meta = inspect_image(full)
+            out.update({
+                "width": meta.width,
+                "height": meta.height,
+                "hasGeoref": meta.has_georef,
+                "format": meta.format,
+            })
+        except Exception as exc:
+            logger.warning("Metadata read failed for %s: %s", entry.path, exc)
+    return out
+
+
+def thumb_cache_path(relative_path: str) -> Path:
+    key = hashlib.sha256(relative_path.encode("utf-8")).hexdigest()[:32]
+    return LOCAL_THUMB_CACHE / f"{key}.png"
+
+
+def get_or_build_thumb(relative_path: str, max_side: int = 256) -> Path:
+    full = safe_resolve(relative_path)
+    cache = thumb_cache_path(relative_path)
+    try:
+        if cache.exists() and cache.stat().st_mtime >= full.stat().st_mtime:
+            return cache
+        cache.parent.mkdir(parents=True, exist_ok=True)
+        raster_to_preview_png(full, cache, max_side=max_side)
+        return cache
+    except Exception as exc:
+        logger.warning("Thumb build failed for %s: %s", relative_path, exc)
+        write_placeholder_png(cache, Path(relative_path).name, max_side)
+        return cache
+
+
+def ensure_root() -> None:
+    for root in get_library_roots():
+        root.mkdir(parents=True, exist_ok=True)
+    LOCAL_THUMB_CACHE.mkdir(parents=True, exist_ok=True)
+
+
+def library_debug_info() -> dict:
+    """Diagnostics for troubleshooting missing images."""
+    roots_info = []
+    for root in get_library_roots():
+        info = {
+            "path": str(root),
+            "exists": root.exists(),
+            "years": [],
+            "otherFiles": [],
+        }
+        if root.exists():
+            for entry in sorted(root.iterdir()):
+                if entry.is_dir() and _is_year_dir(entry.name):
+                    files = []
+                    for _, _, p in _iter_image_files(root, year=int(entry.name)):
+                        files.append({"name": p.name, "size": p.stat().st_size})
+                    info["years"].append({"year": entry.name, "files": files})
+                elif entry.is_file() and entry.name not in ("README.md", ".gitkeep"):
+                    info["otherFiles"].append(entry.name)
+        roots_info.append(info)
+    return {
+        "roots": roots_info,
+        "allowedExtensions": sorted(ALLOWED_EXTENSIONS),
+        "totalImages": len(scan_images()),
+    }

app/dda/local_routes.py

@@ -0,0 +1,485 @@
+"""Slim local helpers: thumb, resolve, detect — backed by tree library."""
+import logging
+from pathlib import Path
+from typing import Optional
+from urllib.parse import unquote
+
+from fastapi import APIRouter, Depends, Form, HTTPException, Query, Request
+from fastapi.responses import FileResponse, Response
+from PIL import Image
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models import User
+from .dda_auth import current_dda_user
+from .detect_service import run_detection_and_save
+from .geotiff_io import load_rgb_pil
+from .rbac.permissions import require_module_permission, user_can
+
+from .config import (
+    IS_DDA_MODE,
+    MAX_GEOTIFF_BYTES,
+    MAX_IMAGE_BYTES,
+    geotiff_io_available,
+    get_detection_max_side,
+    get_library_roots,
+    get_storage_root,
+    is_hf_hosted,
+)
+from .tree.image_service import (
+    count_library_images,
+    delete_library_image,
+    get_or_build_preview,
+    get_or_build_thumb,
+    list_all_images,
+)
+from .tree.path_service import resolve_file
+from .tree.tree_service import build_tree
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+class LocalImageDeleteBody(BaseModel):
+    path: str
+
+
+def _normalize_library_path(path: str) -> str:
+    return unquote((path or "").replace("\\", "/").strip().lstrip("/"))
+
+
+def _delete_image_by_path(db: Session, user: User, rel: str) -> dict:
+    if not user_can(user, db, "library", "delete"):
+        raise HTTPException(status_code=403, detail="Missing 'delete' permission on 'library'.")
+    if not rel:
+        raise HTTPException(status_code=400, detail="path is required")
+    result = delete_library_image(
+        db, relative_path=rel, action_by=user.email or str(user.id),
+    )
+    return {"ok": True, **result}
+
+
+def _require_dda():
+    if not IS_DDA_MODE:
+        raise HTTPException(
+            status_code=404,
+            detail="DDA mode is not enabled. On HF dev Space this is automatic; locally use: python run.py",
+        )
+
+
+def safe_resolve(relative_path: str) -> Path:
+    try:
+        return resolve_file(relative_path)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="Image file not found")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.get("/local/config")
+def local_library_config(user: User = Depends(current_dda_user)):
+    _require_dda()
+    storage = str(get_storage_root())
+    hosted = is_hf_hosted()
+    instructions = (
+        "Select a node in the tree, choose image type, and upload. "
+        "Files are stored under {zone}/{area}/…/Images/ in persistent storage."
+        if hosted
+        else "Use the tree library to organize images by zone/area/year, or upload via the form."
+    )
+    return {
+        "source": "tree_library",
+        "isHosted": hosted,
+        "spaceId": __import__("os").environ.get("SPACE_ID", ""),
+        "appMode": "dda" if IS_DDA_MODE else "legacy",
+        "rootPath": storage,
+        "rootPaths": [str(r) for r in get_library_roots()],
+        "writablePath": storage,
+        "storageRoot": storage,
+        "instructions": instructions,
+        "geotiffEnabled": geotiff_io_available(),
+        "detectionMaxSide": get_detection_max_side(),
+        "maxGeotiffMb": MAX_GEOTIFF_BYTES // (1024 * 1024),
+        "maxGeotiffBytes": MAX_GEOTIFF_BYTES,
+        "maxImageMb": MAX_IMAGE_BYTES // (1024 * 1024),
+        "maxImageBytes": MAX_IMAGE_BYTES,
+        "maxUploadGb": round(MAX_GEOTIFF_BYTES / (1024 ** 3), 2),
+    }
+
+
+@router.get("/local/images")
+def local_images(
+    node_id: Optional[int] = Query(None),
+    q: Optional[str] = Query(None),
+    limit: Optional[int] = Query(None, ge=1, le=500),
+    offset: int = Query(0, ge=0),
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    _require_dda()
+    return list_all_images(
+        db,
+        node_id=node_id,
+        query=q,
+        include_bounds=False,
+        slim=True,
+        limit=limit,
+        offset=offset,
+    )
+
+
+@router.get("/local/area-groups")
+def local_area_groups(
+    node_id: Optional[int] = Query(None),
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    """Images covering the same place, with oldest → Before and newest → After."""
+    _require_dda()
+    from .tree.area_groups import filter_area_groups_for_node, load_cached_area_groups
+    from .tree.tree_service import get_node_or_404
+
+    payload = load_cached_area_groups(db)
+    if node_id:
+        node = get_node_or_404(db, node_id)
+        return filter_area_groups_for_node(payload, node)
+    return payload
+
+
+@router.get("/local/thumb")
+def local_thumb(path: str = Query(...), user: User = Depends(current_dda_user)):
+    _require_dda()
+    path = _normalize_library_path(path)
+    try:
+        thumb = get_or_build_thumb(path)
+        return FileResponse(
+            thumb,
+            media_type="image/png",
+            headers={"Cache-Control": "private, max-age=86400"},
+        )
+    except Exception as exc:
+        logger.warning("Thumb endpoint fallback for %s: %s", path, exc)
+        from .config import LOCAL_THUMB_CACHE
+        from .geotiff_io import write_placeholder_png
+
+        cache = LOCAL_THUMB_CACHE / "fallback.png"
+        write_placeholder_png(cache, Path(path).name)
+        return FileResponse(cache, media_type="image/png")
+
+
+@router.get("/local/preview")
+def local_preview(
+    path: str = Query(...),
+    max: int = Query(1600, ge=256, le=4096),
+    user: User = Depends(current_dda_user),
+):
+    """Full-size preview for library image viewer (cached PNG)."""
+    _require_dda()
+    path = _normalize_library_path(path)
+    try:
+        preview = get_or_build_preview(path, max_side=max)
+        return FileResponse(
+            preview,
+            media_type="image/png",
+            headers={"Cache-Control": "private, max-age=86400"},
+        )
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="Image file not found")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception as exc:
+        logger.warning("Preview endpoint failed for %s: %s", path, exc)
+        raise HTTPException(status_code=500, detail=f"Could not build preview: {exc}") from exc
+
+
+@router.get("/local/map-basemaps")
+def local_map_basemaps(user: User = Depends(current_dda_user)):
+    """XYZ basemap presets (OSM, Google Satellite, custom URL)."""
+    _require_dda()
+    from .map_tiles import BASEMAP_PRESETS
+    return {"basemaps": BASEMAP_PRESETS}
+
+
+@router.get("/local/map-info")
+def local_map_info(
+    path: str = Query(...),
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    """WGS84 bounds + tile URL for overlaying a library raster on a web map."""
+    _require_dda()
+    path = _normalize_library_path(path)
+    try:
+        from .map_tiles import build_map_info
+        return build_map_info(path, db=db)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="Image file not found")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception as exc:
+        logger.warning("map-info failed for %s: %s", path, exc)
+        raise HTTPException(status_code=500, detail=f"Could not read georef: {exc}") from exc
+
+
+@router.get("/local/map-tiles/{z}/{x}/{y}.png")
+def local_map_tile(
+    z: int,
+    x: int,
+    y: int,
+    path: str = Query(...),
+    user: User = Depends(current_dda_user),
+):
+    """XYZ tile of a georeferenced GeoTIFF warped to Web Mercator."""
+    _require_dda()
+    path = _normalize_library_path(path)
+    try:
+        from .map_tiles import render_xyz_tile
+        png = render_xyz_tile(path, z, x, y)
+        return Response(
+            content=png,
+            media_type="image/png",
+            headers={"Cache-Control": "public, max-age=86400"},
+        )
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="Image file not found")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.get("/local/map-overview")
+def local_map_overview(
+    path: str = Query(...),
+    max: int = Query(2048, ge=256, le=4096),
+    user: User = Depends(current_dda_user),
+):
+    """Web-Mercator overview PNG for distortion-free overlay on XYZ basemaps."""
+    _require_dda()
+    path = _normalize_library_path(path)
+    try:
+        from .map_tiles import render_mercator_overview
+        png = render_mercator_overview(path, max_side=max)
+        return Response(
+            content=png,
+            media_type="image/png",
+            headers={"Cache-Control": "public, max-age=86400"},
+        )
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="Image file not found")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception as exc:
+        logger.warning("map-overview failed for %s: %s", path, exc)
+        raise HTTPException(status_code=500, detail=f"Could not build overlay: {exc}") from exc
+
+
+@router.post("/local/images/delete")
+def local_delete_image_post(
+    body: LocalImageDeleteBody,
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    """Delete a library image (preferred — works reliably across browsers)."""
+    _require_dda()
+    return _delete_image_by_path(db, user, _normalize_library_path(body.path))
+
+
+@router.delete("/local/images")
+def local_delete_image(
+    body: Optional[LocalImageDeleteBody] = None,
+    path: Optional[str] = Query(None),
+    db: Session = Depends(get_db),
+    user: User = Depends(current_dda_user),
+):
+    _require_dda()
+    rel = _normalize_library_path(body.path if body and body.path else (path or ""))
+    return _delete_image_by_path(db, user, rel)
+
+
+@router.post("/local/rescan")
+def local_rescan(db: Session = Depends(get_db), user: User = Depends(require_module_permission("library", "edit"))):
+    _require_dda()
+    from .tree.sync_service import sync_from_filesystem
+
+    try:
+        sync_stats = sync_from_filesystem(db, check_orphans=True)
+    except Exception as exc:
+        logger.exception("Filesystem rescan failed")
+        raise HTTPException(status_code=500, detail=f"Rescan failed: {exc}") from exc
+    tree = build_tree(db)
+    return {
+        "ok": True,
+        "tree": tree,
+        "totalImages": count_library_images(db),
+        "storageRoot": str(get_storage_root()),
+        "sync": sync_stats,
+    }
+
+
+@router.post("/detect/preflight")
+async def detect_preflight(
+    base_path: str = Form(...),
+    comparison_path: str = Form(...),
+    roi: Optional[str] = Form(None),
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("detect", "create")),
+):
+    """Check a library image pair (CRS/GSD/bands/georef/overlap) without running detection.
+
+    Lets the UI ask "is this pair suitable?" up front and show the user any
+    warnings before committing to a multi-minute detection run. ``roi``
+    (optional) narrows the overlap check to the selected crop window.
+    """
+    _require_dda()
+    base_norm = base_path.replace("\\", "/").strip()
+    comp_norm = comparison_path.replace("\\", "/").strip()
+    if not base_norm or not comp_norm:
+        raise HTTPException(status_code=400, detail="base_path and comparison_path are required")
+    if base_norm == comp_norm:
+        raise HTTPException(status_code=400, detail="Base and comparison images must be different")
+
+    try:
+        base_file = safe_resolve(base_norm)
+        comp_file = safe_resolve(comp_norm)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid library path: {exc}") from exc
+
+    roi_dict = None
+    if roi and roi.strip():
+        import json as _json
+
+        from .geotiff_io import parse_roi
+        try:
+            roi_dict = parse_roi(_json.loads(roi))
+        except (ValueError, _json.JSONDecodeError) as exc:
+            raise HTTPException(status_code=400, detail=f"Invalid roi: {exc}") from exc
+
+    from .preflight import run_preflight_checks
+    preflight = run_preflight_checks(db, base_file, comp_file, base_norm, comp_norm, roi=roi_dict)
+    return {
+        "hardFail": preflight.hard_fail,
+        "failReason": preflight.fail_reason,
+        "warnings": preflight.warnings,
+    }
+
+
+@router.post("/detect/from-library")
+async def detect_from_library(
+    request: Request,
+    base_path: str = Form(...),
+    comparison_path: str = Form(...),
+    method: str = Form("AI-Based Deep Learning"),
+    title: str = Form("Untitled run"),
+    zone: str = Form(""),
+    village: str = Form(""),
+    enable_registration: bool = Form(True),
+    enable_normalization: bool = Form(True),
+    detection_sensitivity: float = Form(0.5),
+    min_region_area: Optional[int] = Form(150),
+    notify_email: Optional[str] = Form(None),
+    roi: Optional[str] = Form(None),
+    shape_mode: str = Form("polygon"),
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("detect", "create")),
+):
+    """Run change detection on two library images by relative path.
+
+    ``roi`` (optional) is a JSON ``{"x","y","w","h"}`` fractional window in
+    [0,1]; when present, only that cropped region is detected.
+    """
+    _require_dda()
+    base_norm = base_path.replace("\\", "/").strip()
+    comp_norm = comparison_path.replace("\\", "/").strip()
+    if not base_norm or not comp_norm:
+        raise HTTPException(status_code=400, detail="base_path and comparison_path are required")
+    if base_norm == comp_norm:
+        raise HTTPException(status_code=400, detail="Base and comparison images must be different")
+
+    try:
+        base_file = safe_resolve(base_norm)
+        comp_file = safe_resolve(comp_norm)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid library path: {exc}") from exc
+
+    roi_dict = None
+    if roi and roi.strip():
+        import json as _json
+
+        from .geotiff_io import parse_roi
+        try:
+            roi_dict = parse_roi(_json.loads(roi))
+        except (ValueError, _json.JSONDecodeError) as exc:
+            raise HTTPException(status_code=400, detail=f"Invalid roi: {exc}") from exc
+
+    from .preflight import run_preflight_checks
+    preflight = run_preflight_checks(db, base_file, comp_file, base_norm, comp_norm, roi=roi_dict)
+    if preflight.hard_fail:
+        raise HTTPException(status_code=400, detail=preflight.fail_reason)
+
+    try:
+        from ..detection_config import get_load_max_side
+        from .geotiff_io import load_rgb_roi
+        load_side = get_load_max_side()
+        if roi_dict:
+            before_pil = load_rgb_roi(base_file, roi_dict, max_side=load_side)
+            after_pil = load_rgb_roi(comp_file, roi_dict, max_side=load_side)
+        else:
+            before_pil = load_rgb_pil(base_file, max_side=load_side)
+            after_pil = load_rgb_pil(comp_file, max_side=load_side)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Could not load images: {exc}") from exc
+
+    gsd_debug = None
+    try:
+        from .geotiff_io import harmonize_pair_gsd
+        before_pil, after_pil, gsd_debug = harmonize_pair_gsd(
+            before_pil, after_pil, base_file, comp_file)
+    except Exception as exc:
+        logger.warning("GSD harmonization skipped: %s", exc)
+
+    if before_pil.size != after_pil.size:
+        after_pil = after_pil.resize(before_pil.size, Image.Resampling.LANCZOS)
+
+    if title == "Untitled run":
+        title = f"{Path(base_norm).name} vs {Path(comp_norm).name}"
+
+    try:
+        # Use fullres load cap (up to DETECTION_FULLRES_MAX_SIDE), not the
+        # legacy 4096 downscaled cap — otherwise max-res config is ignored.
+        detect_max = load_side
+        logger.info(
+            "Library detection max_size=%d (loaded %s)",
+            detect_max, before_pil.size,
+        )
+        return run_detection_and_save(
+            db,
+            before_pil,
+            after_pil,
+            method=method,
+            title=title,
+            zone=zone,
+            village=village,
+            enable_registration=enable_registration,
+            enable_normalization=enable_normalization,
+            detection_sensitivity=detection_sensitivity,
+            min_region_area=min_region_area,
+            notify_email=notify_email,
+            max_size=detect_max,
+            geo_bounds_path=base_file,
+            comparison_file=comp_file,
+            base_path=base_norm,
+            comparison_path=comp_norm,
+            user_id=user.id,
+            gsd_debug=gsd_debug,
+            shape_mode=shape_mode,
+            preflight_warnings=preflight.warnings,
+        )
+    except Exception as exc:
+        logger.exception("Library detection failed for %s vs %s", base_norm, comp_norm)
+        raise HTTPException(status_code=500, detail=f"Detection failed: {exc}") from exc

app/dda/logs_routes.py

@@ -0,0 +1,50 @@
+"""API for the application Logs page."""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi.responses import FileResponse, PlainTextResponse
+
+from ..models import User
+from .applog import clear_logs, log_file_path, query_logs
+from .rbac.permissions import require_module_permission
+
+router = APIRouter()
+
+
+def _require_dda():
+    from .config import IS_DDA_MODE
+    if not IS_DDA_MODE:
+        raise HTTPException(status_code=404, detail="DDA mode is not enabled")
+
+
+@router.get("/logs")
+def list_logs(
+    level: str = Query(""),
+    q: str = Query(""),
+    logger: str = Query(""),
+    limit: int = Query(200, ge=1, le=1000),
+    offset: int = Query(0, ge=0),
+    user: User = Depends(require_module_permission("logs", "view")),
+):
+    _require_dda()
+    return query_logs(level=level, q=q, logger_name=logger, limit=limit, offset=offset)
+
+
+@router.get("/logs/download")
+def download_logs(user: User = Depends(require_module_permission("logs", "view"))):
+    _require_dda()
+    path = log_file_path()
+    if path.exists() and path.stat().st_size:
+        return FileResponse(path, filename="app.log", media_type="text/plain")
+    data = query_logs(limit=1000, offset=0)
+    body = "\n".join(
+        f"{row['ts']} {row['level']} [{row['logger']}] {row['message']}"
+        for row in reversed(data["logs"])
+    ) or "(no log entries yet)"
+    return PlainTextResponse(body, headers={"Content-Disposition": 'attachment; filename="app.log"'})
+
+
+@router.delete("/logs")
+def api_clear_logs(user: User = Depends(require_module_permission("logs", "delete"))):
+    _require_dda()
+    return clear_logs()

app/dda/map_tiles.py

@@ -0,0 +1,418 @@
+"""XYZ map tiles for georeferenced library rasters (QGIS-style overlay)."""
+from __future__ import annotations
+
+import hashlib
+import io
+import logging
+import math
+from pathlib import Path
+from typing import Any, Optional, Tuple
+from urllib.parse import quote
+
+from PIL import Image
+
+from .config import LOCAL_THUMB_CACHE
+from .geotiff_io import inspect_image, read_georef
+from .tree.path_service import resolve_file
+
+logger = logging.getLogger(__name__)
+
+TILE_SIZE = 256
+MAX_ZOOM = 22
+WEB_MERCATOR_ORIGIN = 20037508.342789244
+_EMPTY_PNG: Optional[bytes] = None
+
+BoundsWGS84 = Tuple[float, float, float, float]
+
+
+def empty_tile_png() -> bytes:
+    global _EMPTY_PNG
+    if _EMPTY_PNG is None:
+        buf = io.BytesIO()
+        Image.new("RGBA", (TILE_SIZE, TILE_SIZE), (0, 0, 0, 0)).save(buf, format="PNG")
+        _EMPTY_PNG = buf.getvalue()
+    return _EMPTY_PNG
+
+
+def xyz_bounds_3857(z: int, x: int, y: int) -> Tuple[float, float, float, float]:
+    """Web Mercator bounds of an XYZ tile (minx, miny, maxx, maxy)."""
+    n = 2 ** int(z)
+    tile_w = (2.0 * WEB_MERCATOR_ORIGIN) / n
+    minx = -WEB_MERCATOR_ORIGIN + x * tile_w
+    maxx = -WEB_MERCATOR_ORIGIN + (x + 1) * tile_w
+    maxy = WEB_MERCATOR_ORIGIN - y * tile_w
+    miny = WEB_MERCATOR_ORIGIN - (y + 1) * tile_w
+    return minx, miny, maxx, maxy
+
+
+def _rects_intersect(a: Tuple[float, float, float, float],
+                     b: Tuple[float, float, float, float]) -> bool:
+    return not (a[2] <= b[0] or a[0] >= b[2] or a[3] <= b[1] or a[1] >= b[3])
+
+
+def _max_native_zoom(bounds: Optional[BoundsWGS84], width: int, height: int) -> int:
+    """Leaflet maxNativeZoom from raster GSD (approx, WGS84)."""
+    if not bounds or width <= 0 or height <= 0:
+        return 18
+    west, south, east, north = bounds
+    lat = max(-85.0, min(85.0, (south + north) / 2.0))
+    # metres per pixel along the longer raster side
+    m_per_deg_lat = 111_320.0
+    m_per_deg_lng = 111_320.0 * max(0.05, math.cos(math.radians(lat)))
+    gsd = min(
+        abs(east - west) * m_per_deg_lng / max(width, 1),
+        abs(north - south) * m_per_deg_lat / max(height, 1),
+    )
+    gsd = max(gsd, 0.02)
+    mpp_z0 = 156543.03392804097 * math.cos(math.radians(lat))
+    z = int(round(math.log2(max(mpp_z0 / gsd, 1.0))))
+    return max(12, min(MAX_ZOOM, z))
+
+
+def _bounds_dict(bounds: Optional[BoundsWGS84]) -> Optional[dict]:
+    if not bounds:
+        return None
+    west, south, east, north = bounds
+    return {
+        "west": west,
+        "south": south,
+        "east": east,
+        "north": north,
+        "latLng": [[south, west], [north, east]],
+    }
+
+
+def build_map_info(relative_path: str, db=None) -> dict:
+    """Metadata the browser needs to overlay a library raster on XYZ basemaps."""
+    rel = (relative_path or "").replace("\\", "/").strip().lstrip("/")
+    full = resolve_file(rel)
+    meta = inspect_image(full)
+    georef = read_georef(full)
+    bounds = meta.bounds_wgs84
+    source = meta.georef_source or "none"
+    can_tile = bool(georef and georef.crs and bounds)
+
+    if not bounds and db is not None:
+        from .geo_regions import parse_bounds
+        from .tree.image_service import get_image_by_file_path
+
+        img = get_image_by_file_path(db, rel)
+        if img and img.bounds_json:
+            parsed = parse_bounds(img.bounds_json)
+            if parsed:
+                bounds = parsed
+                source = "manual"
+                can_tile = bool(georef and georef.crs)
+
+    encoded = quote(rel, safe="/")
+    merc_bounds = _mercator_aligned_wgs84(full) if can_tile else None
+    overlay_bounds = merc_bounds or bounds
+    return {
+        "path": rel,
+        "filename": Path(rel).name,
+        "hasGeoref": bool(overlay_bounds),
+        "canTile": can_tile,
+        "georefSource": source if overlay_bounds else "none",
+        "crs": str(georef.crs) if (georef and georef.crs) else (meta.crs or ""),
+        "bounds": _bounds_dict(overlay_bounds),
+        "width": meta.width,
+        "height": meta.height,
+        "maxNativeZoom": _max_native_zoom(overlay_bounds, meta.width, meta.height),
+        "tileUrl": f"/api/dda/local/map-tiles/{{z}}/{{x}}/{{y}}.png?path={encoded}",
+        "overviewUrl": (
+            f"/api/dda/local/map-overview?path={encoded}&max=2048" if can_tile else None
+        ),
+        "previewUrl": f"/api/dda/local/preview?path={encoded}&max=2048",
+    }
+
+
+def _tile_cache_path(relative_path: str, src: Path, z: int, x: int, y: int) -> Path:
+    key = hashlib.sha256(relative_path.encode("utf-8")).hexdigest()[:24]
+    mtime = int(src.stat().st_mtime)
+    return (
+        LOCAL_THUMB_CACHE
+        / "map-tiles"
+        / f"{key}_{mtime}"
+        / str(z)
+        / str(x)
+        / f"{y}.png"
+    )
+
+
+def _to_rgba(data, mask) -> Image.Image:
+    import numpy as np
+
+    count = int(data.shape[0])
+    if count == 1:
+        rgb = np.stack([data[0], data[0], data[0]])
+    else:
+        rgb = data[:3]
+    rgb = np.transpose(rgb, (1, 2, 0)).astype("float32")
+    if data.dtype != np.uint8 or float(np.nanmax(rgb) if rgb.size else 0) > 255:
+        lo, hi = np.percentile(rgb, (2, 98)) if rgb.size else (0, 1)
+        rgb = np.clip((rgb - lo) / max(hi - lo, 1e-6), 0, 1) * 255
+    rgb_u8 = np.clip(rgb, 0, 255).astype("uint8")
+    if mask is None:
+        alpha = np.full(rgb_u8.shape[:2], 255, dtype="uint8")
+    else:
+        alpha = np.asarray(mask)
+        if alpha.ndim == 3:
+            alpha = alpha[0]
+        if alpha.shape != rgb_u8.shape[:2]:
+            alpha = np.full(rgb_u8.shape[:2], 255, dtype="uint8")
+        else:
+            alpha = np.where(alpha > 0, 255, 0).astype("uint8")
+    rgba = np.dstack([rgb_u8, alpha])
+    return Image.fromarray(rgba, mode="RGBA")
+
+
+def render_xyz_tile(relative_path: str, z: int, x: int, y: int) -> bytes:
+    """Warp one Web-Mercator XYZ tile from a georeferenced raster."""
+    if z < 0 or z > MAX_ZOOM:
+        return empty_tile_png()
+    n = 2 ** z
+    if x < 0 or y < 0 or x >= n or y >= n:
+        return empty_tile_png()
+
+    rel = (relative_path or "").replace("\\", "/").strip().lstrip("/")
+    src_path = resolve_file(rel)
+    cache = _tile_cache_path(rel, src_path, z, x, y)
+    try:
+        if cache.exists() and cache.stat().st_mtime >= src_path.stat().st_mtime:
+            return cache.read_bytes()
+    except OSError:
+        pass
+
+    png = _render_tile_uncached(src_path, z, x, y)
+    if png == empty_tile_png():
+        return png
+    try:
+        cache.parent.mkdir(parents=True, exist_ok=True)
+        tmp = cache.with_suffix(".tmp.png")
+        tmp.write_bytes(png)
+        tmp.replace(cache)
+    except OSError as exc:
+        logger.debug("Map tile cache write skipped: %s", exc)
+    return png
+
+
+def _mercator_aligned_wgs84(src_path: Path) -> Optional[BoundsWGS84]:
+    """WGS84 box of the raster's Web-Mercator envelope (matches Google XYZ tiles)."""
+    try:
+        import rasterio
+        from rasterio.crs import CRS
+        from rasterio.warp import transform_bounds
+    except ImportError:
+        return None
+    try:
+        with rasterio.open(src_path) as src:
+            if src.crs is None:
+                return None
+            web = CRS.from_epsg(3857)
+            wgs = CRS.from_epsg(4326)
+            crs = _crs_2d(src.crs)
+            minx, miny, maxx, maxy = transform_bounds(crs, web, *src.bounds, densify_pts=21)
+            west, south, east, north = transform_bounds(web, wgs, minx, miny, maxx, maxy)
+            return (float(west), float(south), float(east), float(north))
+    except Exception as exc:
+        logger.debug("mercator-aligned bounds failed for %s: %s", src_path.name, exc)
+        return None
+
+
+def render_mercator_overview(relative_path: str, max_side: int = 2048) -> bytes:
+    """North-up Web-Mercator PNG so Leaflet ImageOverlay matches Google tiles."""
+    rel = (relative_path or "").replace("\\", "/").strip().lstrip("/")
+    src_path = resolve_file(rel)
+    max_side = max(256, min(int(max_side), 4096))
+    key = hashlib.sha256(f"{rel}:overview:{max_side}".encode("utf-8")).hexdigest()[:24]
+    mtime = int(src_path.stat().st_mtime)
+    cache = LOCAL_THUMB_CACHE / "map-overview" / f"{key}_{mtime}_{max_side}.png"
+    try:
+        if cache.exists() and cache.stat().st_mtime >= src_path.stat().st_mtime:
+            return cache.read_bytes()
+    except OSError:
+        pass
+    png = _render_mercator_overview_uncached(src_path, max_side)
+    try:
+        cache.parent.mkdir(parents=True, exist_ok=True)
+        tmp = cache.with_suffix(".tmp.png")
+        tmp.write_bytes(png)
+        tmp.replace(cache)
+    except OSError as exc:
+        logger.debug("Overview cache write skipped: %s", exc)
+    return png
+
+
+def _render_mercator_overview_uncached(src_path: Path, max_side: int) -> bytes:
+    import numpy as np
+    import rasterio
+    from rasterio.crs import CRS
+    from rasterio.enums import Resampling
+    from rasterio.transform import from_bounds as affine_from_bounds
+    from rasterio.warp import reproject, transform_bounds
+
+    web = CRS.from_epsg(3857)
+    with rasterio.open(src_path) as src:
+        if src.crs is None:
+            raise ValueError("raster has no CRS")
+        src_crs = _crs_2d(src.crs)
+        minx, miny, maxx, maxy = transform_bounds(src_crs, web, *src.bounds, densify_pts=21)
+        width_m = max(maxx - minx, 1e-6)
+        height_m = max(maxy - miny, 1e-6)
+        if width_m >= height_m:
+            out_w = max_side
+            out_h = max(1, int(round(max_side * height_m / width_m)))
+        else:
+            out_h = max_side
+            out_w = max(1, int(round(max_side * width_m / height_m)))
+        count = min(3, src.count)
+        indexes = list(range(1, count + 1))
+        dst_transform = affine_from_bounds(minx, miny, maxx, maxy, out_w, out_h)
+        src_nodata = src.nodata
+        if src_nodata is not None and 0 <= float(src_nodata) <= 255:
+            src_nodata = None
+        sentinel = -1.0
+        dst = np.full((count, out_h, out_w), sentinel, dtype=np.float32)
+        reproject(
+            source=rasterio.band(src, indexes),
+            destination=dst,
+            src_transform=src.transform,
+            src_crs=src_crs,
+            dst_transform=dst_transform,
+            dst_crs=web,
+            resampling=Resampling.bilinear,
+            src_nodata=src_nodata,
+            dst_nodata=sentinel,
+        )
+        valid = dst[0] != sentinel
+        if not np.any(valid):
+            return empty_tile_png()
+        rgb = dst.copy()
+        rgb[:, ~valid] = 0
+        mask = np.where(valid, 255, 0).astype(np.uint8)
+    img = _to_rgba(rgb, mask)
+    buf = io.BytesIO()
+    img.save(buf, format="PNG", optimize=False)
+    return buf.getvalue()
+
+
+def _crs_2d(crs):
+    try:
+        if hasattr(crs, "to_2d"):
+            two = crs.to_2d()
+            if two:
+                return two
+    except Exception:
+        pass
+    return crs
+
+
+def _render_tile_uncached(src_path: Path, z: int, x: int, y: int) -> bytes:
+    try:
+        import numpy as np
+        import rasterio
+        from rasterio.crs import CRS
+        from rasterio.enums import Resampling
+        from rasterio.transform import from_bounds as affine_from_bounds
+        from rasterio.warp import reproject, transform_bounds
+    except ImportError:
+        logger.warning("rasterio missing — cannot render map tiles")
+        return empty_tile_png()
+
+    minx, miny, maxx, maxy = xyz_bounds_3857(z, x, y)
+    web_merc = CRS.from_epsg(3857)
+
+    try:
+        with rasterio.open(src_path) as src:
+            if src.crs is None:
+                return empty_tile_png()
+            src_crs = _crs_2d(src.crs)
+            try:
+                src_3857 = transform_bounds(src_crs, web_merc, *src.bounds, densify_pts=21)
+            except Exception:
+                try:
+                    src_3857 = transform_bounds(src.crs, web_merc, *src.bounds, densify_pts=21)
+                    src_crs = src.crs
+                except Exception:
+                    return empty_tile_png()
+            if not _rects_intersect(src_3857, (minx, miny, maxx, maxy)):
+                return empty_tile_png()
+
+            count = min(3, src.count)
+            indexes = list(range(1, count + 1))
+            dst_transform = affine_from_bounds(minx, miny, maxx, maxy, TILE_SIZE, TILE_SIZE)
+            # RGB 0 is valid (shadows/black roofs). Only treat a true nodata
+            # that is outside 0–255, otherwise GDAL punches holes in the overlay.
+            src_nodata = src.nodata
+            if src_nodata is not None and 0 <= float(src_nodata) <= 255:
+                src_nodata = None
+            sentinel = -1.0
+            dst = np.full((count, TILE_SIZE, TILE_SIZE), sentinel, dtype=np.float32)
+            reproject(
+                source=rasterio.band(src, indexes),
+                destination=dst,
+                src_transform=src.transform,
+                src_crs=src_crs,
+                dst_transform=dst_transform,
+                dst_crs=web_merc,
+                resampling=Resampling.bilinear,
+                src_nodata=src_nodata,
+                dst_nodata=sentinel,
+            )
+            valid = dst[0] != sentinel
+            if not np.any(valid):
+                return empty_tile_png()
+            rgb = dst.copy()
+            rgb[:, ~valid] = 0
+            mask = np.where(valid, 255, 0).astype(np.uint8)
+        img = _to_rgba(rgb, mask)
+        buf = io.BytesIO()
+        img.save(buf, format="PNG", optimize=False)
+        return buf.getvalue()
+    except Exception as exc:
+        logger.warning("Map tile %s z=%s x=%s y=%s failed: %s", src_path.name, z, x, y, exc)
+        return empty_tile_png()
+
+
+BASEMAP_PRESETS: list[dict[str, Any]] = [
+    {
+        "id": "osm",
+        "label": "OpenStreetMap",
+        "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
+        "attribution": "&copy; OpenStreetMap contributors",
+        "maxZoom": 19,
+        "subdomains": "",
+    },
+    {
+        "id": "google-satellite",
+        "label": "Google Satellite",
+        "url": "https://mt{s}.google.com/vt/lyrs=s&x={x}&y={y}&z={z}",
+        "attribution": "Imagery &copy; Google",
+        "maxZoom": 21,
+        "subdomains": "0123",
+    },
+    {
+        "id": "google-hybrid",
+        "label": "Google Hybrid",
+        "url": "https://mt{s}.google.com/vt/lyrs=y&x={x}&y={y}&z={z}",
+        "attribution": "Imagery &copy; Google",
+        "maxZoom": 21,
+        "subdomains": "0123",
+    },
+    {
+        "id": "esri-imagery",
+        "label": "Esri World Imagery",
+        "url": "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
+        "attribution": "Tiles &copy; Esri",
+        "maxZoom": 19,
+        "subdomains": "",
+    },
+    {
+        "id": "custom-xyz",
+        "label": "Custom XYZ…",
+        "url": "",
+        "attribution": "",
+        "maxZoom": 22,
+        "subdomains": "",
+    },
+]

app/dda/masters_routes.py

@@ -0,0 +1,241 @@
+"""Zone / District and Village / Location master data."""
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models import User
+from .models import DdaVillage, DdaZone, ImageAsset
+from .rbac.permissions import require_module_permission
+from .seed import seed_delhi_hierarchy
+
+router = APIRouter()
+
+
+def _require_dda():
+    from .config import IS_DDA_MODE
+    if not IS_DDA_MODE:
+        raise HTTPException(status_code=404, detail="DDA mode is not enabled")
+
+
+def _log_masters_action(db: Session, action: str, user: User, new_value: Optional[dict] = None) -> None:
+    try:
+        from .dda_auth import get_user_role
+        from .tree.audit_service import log_action
+        log_action(
+            db, action, action_by=getattr(user, "email", "") or "",
+            role=get_user_role(db, user), module="masters", new_value=new_value,
+        )
+        db.commit()
+    except Exception:
+        import logging
+        logging.getLogger(__name__).exception("Failed to write audit log for masters action %s", action)
+
+
+class ZoneBody(BaseModel):
+    name: str = Field(..., min_length=1, max_length=128)
+    mode: str = Field("admin", max_length=32)
+
+
+class VillageBody(BaseModel):
+    name: str = Field(..., min_length=1, max_length=128)
+    zone_id: int
+
+
+def _zone_dict(zone: DdaZone, village_count: int = 0) -> dict:
+    return {
+        "id": zone.id,
+        "name": zone.name,
+        "mode": zone.mode or "admin",
+        "villageCount": village_count,
+        "createdAt": zone.created_at.isoformat() if zone.created_at else None,
+    }
+
+
+def _village_dict(village: DdaVillage, zone: Optional[DdaZone] = None) -> dict:
+    z = zone or village.zone
+    return {
+        "id": village.id,
+        "name": village.name,
+        "zoneId": village.zone_id,
+        "zoneName": z.name if z else "",
+        "createdAt": village.created_at.isoformat() if village.created_at else None,
+    }
+
+
+@router.get("/masters/zones")
+def list_zones(
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("masters", "view")),
+):
+    _require_dda()
+    seed_delhi_hierarchy(db)
+    zones = db.query(DdaZone).order_by(DdaZone.name).all()
+    counts = {}
+    for v in db.query(DdaVillage).all():
+        counts[v.zone_id] = counts.get(v.zone_id, 0) + 1
+    return {"zones": [_zone_dict(z, counts.get(z.id, 0)) for z in zones]}
+
+
+@router.post("/masters/zones")
+def create_zone(
+    body: ZoneBody,
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("masters", "create")),
+):
+    _require_dda()
+    name = body.name.strip()
+    if db.query(DdaZone).filter(DdaZone.name == name).first():
+        raise HTTPException(status_code=409, detail="A zone with this name already exists.")
+    zone = DdaZone(name=name, mode=(body.mode or "admin").strip() or "admin")
+    db.add(zone)
+    db.commit()
+    db.refresh(zone)
+    _log_masters_action(db, "create_zone", user, {"zone_id": zone.id, "name": zone.name})
+    return {"ok": True, "zone": _zone_dict(zone, 0)}
+
+
+@router.put("/masters/zones/{zone_id}")
+def update_zone(
+    zone_id: int,
+    body: ZoneBody,
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("masters", "edit")),
+):
+    _require_dda()
+    zone = db.query(DdaZone).filter(DdaZone.id == zone_id).first()
+    if not zone:
+        raise HTTPException(status_code=404, detail="Zone not found")
+    name = body.name.strip()
+    clash = db.query(DdaZone).filter(DdaZone.name == name, DdaZone.id != zone_id).first()
+    if clash:
+        raise HTTPException(status_code=409, detail="A zone with this name already exists.")
+    zone.name = name
+    zone.mode = (body.mode or zone.mode or "admin").strip()
+    db.commit()
+    _log_masters_action(db, "update_zone", user, {"zone_id": zone.id, "name": zone.name})
+    count = db.query(DdaVillage).filter(DdaVillage.zone_id == zone.id).count()
+    return {"ok": True, "zone": _zone_dict(zone, count)}
+
+
+@router.delete("/masters/zones/{zone_id}")
+def delete_zone(
+    zone_id: int,
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("masters", "delete")),
+):
+    _require_dda()
+    zone = db.query(DdaZone).filter(DdaZone.id == zone_id).first()
+    if not zone:
+        raise HTTPException(status_code=404, detail="Zone not found")
+    in_use = db.query(ImageAsset).filter(ImageAsset.zone_id == zone_id).count()
+    if in_use:
+        raise HTTPException(status_code=409, detail="This zone is used by library images and cannot be deleted.")
+    zone_name = zone.name
+    db.query(DdaVillage).filter(DdaVillage.zone_id == zone_id).delete(synchronize_session=False)
+    db.delete(zone)
+    db.commit()
+    _log_masters_action(db, "delete_zone", user, {"zone_id": zone_id, "name": zone_name})
+    return {"ok": True}
+
+
+@router.get("/masters/villages")
+def list_villages(
+    zone_id: Optional[int] = None,
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("masters", "view")),
+):
+    _require_dda()
+    seed_delhi_hierarchy(db)
+    q = db.query(DdaVillage).order_by(DdaVillage.name)
+    if zone_id:
+        q = q.filter(DdaVillage.zone_id == zone_id)
+    villages = q.all()
+    zones = {z.id: z for z in db.query(DdaZone).all()}
+    return {
+        "villages": [_village_dict(v, zones.get(v.zone_id)) for v in villages],
+        "zones": [_zone_dict(z) for z in sorted(zones.values(), key=lambda z: z.name)],
+    }
+
+
+@router.post("/masters/villages")
+def create_village(
+    body: VillageBody,
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("masters", "create")),
+):
+    _require_dda()
+    zone = db.query(DdaZone).filter(DdaZone.id == body.zone_id).first()
+    if not zone:
+        raise HTTPException(status_code=404, detail="Zone not found")
+    name = body.name.strip()
+    clash = (
+        db.query(DdaVillage)
+        .filter(DdaVillage.zone_id == zone.id, DdaVillage.name == name)
+        .first()
+    )
+    if clash:
+        raise HTTPException(status_code=409, detail="That location already exists in this zone.")
+    village = DdaVillage(zone_id=zone.id, name=name)
+    db.add(village)
+    db.commit()
+    db.refresh(village)
+    _log_masters_action(db, "create_village", user, {"village_id": village.id, "name": village.name, "zone_id": zone.id})
+    return {"ok": True, "village": _village_dict(village, zone)}
+
+
+@router.put("/masters/villages/{village_id}")
+def update_village(
+    village_id: int,
+    body: VillageBody,
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("masters", "edit")),
+):
+    _require_dda()
+    village = db.query(DdaVillage).filter(DdaVillage.id == village_id).first()
+    if not village:
+        raise HTTPException(status_code=404, detail="Location not found")
+    zone = db.query(DdaZone).filter(DdaZone.id == body.zone_id).first()
+    if not zone:
+        raise HTTPException(status_code=404, detail="Zone not found")
+    name = body.name.strip()
+    clash = (
+        db.query(DdaVillage)
+        .filter(
+            DdaVillage.zone_id == zone.id,
+            DdaVillage.name == name,
+            DdaVillage.id != village_id,
+        )
+        .first()
+    )
+    if clash:
+        raise HTTPException(status_code=409, detail="That location already exists in this zone.")
+    village.name = name
+    village.zone_id = zone.id
+    db.commit()
+    _log_masters_action(db, "update_village", user, {"village_id": village.id, "name": village.name, "zone_id": zone.id})
+    return {"ok": True, "village": _village_dict(village, zone)}
+
+
+@router.delete("/masters/villages/{village_id}")
+def delete_village(
+    village_id: int,
+    db: Session = Depends(get_db),
+    user: User = Depends(require_module_permission("masters", "delete")),
+):
+    _require_dda()
+    village = db.query(DdaVillage).filter(DdaVillage.id == village_id).first()
+    if not village:
+        raise HTTPException(status_code=404, detail="Location not found")
+    in_use = db.query(ImageAsset).filter(ImageAsset.village_id == village_id).count()
+    if in_use:
+        raise HTTPException(status_code=409, detail="This location is used by library images and cannot be deleted.")
+    village_name = village.name
+    db.delete(village)
+    db.commit()
+    _log_masters_action(db, "delete_village", user, {"village_id": village_id, "name": village_name})
+    return {"ok": True}

app/dda/models.py

@@ -0,0 +1,137 @@
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import Boolean, Column, Date, DateTime, Float, ForeignKey, Integer, String, Text
+from sqlalchemy.orm import relationship
+
+from ..database import Base
+
+
+def _utcnow():
+    return datetime.now(timezone.utc)
+
+
+class DdaZone(Base):
+    __tablename__ = "dda_zones"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(128), unique=True, nullable=False, index=True)
+    mode = Column(String(32), default="admin")  # admin | grid_parent
+    created_at = Column(DateTime, default=_utcnow)
+
+    villages = relationship("DdaVillage", back_populates="zone", cascade="all, delete-orphan")
+
+
+class DdaVillage(Base):
+    __tablename__ = "dda_villages"
+
+    id = Column(Integer, primary_key=True, index=True)
+    zone_id = Column(Integer, ForeignKey("dda_zones.id"), nullable=False, index=True)
+    name = Column(String(128), nullable=False, index=True)
+    created_at = Column(DateTime, default=_utcnow)
+
+    zone = relationship("DdaZone", back_populates="villages")
+    images = relationship("ImageAsset", back_populates="village")
+
+
+class ImageAsset(Base):
+    """Centralized satellite / drone image (FR-01, FR-02)."""
+    __tablename__ = "dda_image_assets"
+
+    id = Column(Integer, primary_key=True, index=True)
+    uuid = Column(String(36), unique=True, nullable=False, default=lambda: str(uuid.uuid4()), index=True)
+    zone_id = Column(Integer, ForeignKey("dda_zones.id"), nullable=True, index=True)
+    village_id = Column(Integer, ForeignKey("dda_villages.id"), nullable=True, index=True)
+    area_name = Column(String(128), default="")
+    year = Column(Integer, nullable=True, index=True)
+    grid_id = Column(String(64), default="", index=True)
+
+    capture_date = Column(Date, nullable=True)
+    source = Column(String(32), default="satellite")  # satellite | drone
+    format = Column(String(32), default="geotiff")
+    original_filename = Column(String(255), default="")
+
+    file_path = Column(String(512), nullable=False)
+    thumb_path = Column(String(512), default="")
+    preview_path = Column(String(512), default="")
+
+    crs = Column(String(64), default="")
+    bounds_json = Column(Text, default="")  # WGS84 [west, south, east, north]
+    has_georef = Column(Boolean, default=False)
+    manual_location_json = Column(Text, default="")
+
+    width = Column(Integer, default=0)
+    height = Column(Integer, default=0)
+    file_size_bytes = Column(Integer, default=0)
+
+    uploaded_by = Column(Integer, ForeignKey("users.id"), nullable=True)
+    created_at = Column(DateTime, default=_utcnow)
+
+    zone = relationship("DdaZone")
+    village = relationship("DdaVillage", back_populates="images")
+
+
+class AutoDetectSettings(Base):
+    """Singleton (id=1): automatic queue is opt-in and does not start on launch."""
+    __tablename__ = "dda_auto_detect_settings"
+
+    id = Column(Integer, primary_key=True)
+    running = Column(Boolean, default=False)
+    interval_days = Column(Integer, default=10)
+    run_at = Column(String(8), default="02:00")
+    next_run_at = Column(DateTime, nullable=True)
+    updated_at = Column(DateTime, default=_utcnow, onupdate=_utcnow)
+
+
+class AutoPairSchedule(Base):
+    """Periodic automatic detection for an identified same-area pair."""
+    __tablename__ = "dda_auto_pair_schedules"
+
+    id = Column(Integer, primary_key=True, index=True)
+    pair_key = Column(String(64), unique=True, nullable=False, index=True)
+    group_label = Column(String(255), default="")
+    before_path = Column(String(512), nullable=False)
+    after_path = Column(String(512), nullable=False)
+    interval_days = Column(Integer, default=10)
+    enabled = Column(Boolean, default=True)
+    last_enqueued_at = Column(DateTime, nullable=True)
+    last_completed_at = Column(DateTime, nullable=True)
+    last_job_id = Column(Integer, nullable=True)
+    last_run_id = Column(Integer, nullable=True)
+    last_error = Column(Text, default="")
+    created_at = Column(DateTime, default=_utcnow)
+    updated_at = Column(DateTime, default=_utcnow, onupdate=_utcnow)
+
+
+class DetectionJob(Base):
+    """Async change detection job (FR-04 skeleton)."""
+    __tablename__ = "dda_detection_jobs"
+
+    id = Column(Integer, primary_key=True, index=True)
+    status = Column(String(32), default="queued", index=True)  # queued|running|completed|failed
+    base_image_id = Column(Integer, ForeignKey("dda_image_assets.id"), nullable=True)
+    comparison_image_id = Column(Integer, ForeignKey("dda_image_assets.id"), nullable=True)
+    method = Column(String(64), default="AI-Based Deep Learning")
+    params_json = Column(Text, default="{}")
+    run_id = Column(Integer, ForeignKey("detection_runs.id"), nullable=True)
+    error_message = Column(Text, default="")
+    notify_email = Column(String(255), default="")
+    created_by = Column(Integer, ForeignKey("users.id"), nullable=True)
+    started_at = Column(DateTime, nullable=True)
+    completed_at = Column(DateTime, nullable=True)
+    created_at = Column(DateTime, default=_utcnow)
+
+
+class RegionReview(Base):
+    """Per-region human review state (FR-08)."""
+    __tablename__ = "dda_region_reviews"
+
+    id = Column(Integer, primary_key=True, index=True)
+    run_id = Column(Integer, ForeignKey("detection_runs.id"), nullable=False, index=True)
+    region_id = Column(Integer, nullable=False, index=True)
+    status = Column(String(32), default="pending")  # pending|confirmed|false_positive|submitted
+    reviewer_id = Column(Integer, ForeignKey("users.id"), nullable=True)
+    notes = Column(Text, default="")
+    reviewed_at = Column(DateTime, nullable=True)
+    submitted_at = Column(DateTime, nullable=True)
+    created_at = Column(DateTime, default=_utcnow)

app/dda/pair_align.py

@@ -0,0 +1,273 @@
+"""Before/after pair pre-alignment and input-quality guard.
+
+This module sits *in front of* the detection engine and answers one question
+that the engine currently assumes rather than checks: **are these two images
+actually a comparable, co-registered pair of the same ground?**
+
+Three real-world failure modes motivated it (all observed on drone GeoTIFFs):
+
+1. **Identical inputs** — the same file uploaded twice. The engine dutifully
+   reports "no change"; the operator reads that as a detection failure. We
+   catch it up front with a cheap content hash.
+2. **Different pixel grids** — two georeferenced rasters of the same place at
+   different GSD / extent / band count. Naive ``cv2.resize`` to a common shape
+   *stretches* rather than *aligns*, so static ground shows up as change. We
+   reproject BOTH onto one common grid (their geographic overlap, at the finer
+   resolution) so a pixel means the same ground in both.
+3. **Un-registerable frames** — raw (non-orthorectified) frames shot from
+   different viewpoints. No 2D transform aligns them (parallax). We can't fix
+   that here, but we *measure* it and emit an honest warning instead of a
+   silent garbage mask.
+
+The engine's detection path is untouched; callers opt in. A CLI is provided so
+the alignment of any pair can be checked without running a full job:
+
+    python -m app.dda.pair_align before.tif after.tif [--out DIR]
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Optional, Tuple
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Result container
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PairAlignResult:
+    """Outcome of aligning + assessing a before/after pair.
+
+    ``status`` is the single field a caller should branch on:
+      * ``"identical"``   — inputs are the same image; there is nothing to detect.
+      * ``"ok"``          — aligned and alignment quality is adequate.
+      * ``"low_quality"`` — aligned but residual misalignment is high; detection
+                            will be unreliable (likely raw/un-orthorectified
+                            frames). Results should be shown with a warning.
+      * ``"error"``       — alignment could not be attempted (see ``message``).
+    """
+    status: str
+    message: str
+    ncc: float = 0.0
+    method: str = "none"
+    grid: Optional[Tuple[int, int]] = None  # (width, height) of aligned output
+    overlap_frac: float = 0.0
+
+    def to_json(self) -> dict:
+        d = asdict(self)
+        if self.grid is not None:
+            d["grid"] = list(self.grid)
+        return d
+
+
+# ---------------------------------------------------------------------------
+# 1. Identical-input guard
+# ---------------------------------------------------------------------------
+
+def content_hash(arr: np.ndarray) -> str:
+    """Stable MD5 of raw pixel bytes — cheap identical-pair detector."""
+    return hashlib.md5(np.ascontiguousarray(arr).tobytes()).hexdigest()
+
+
+def are_identical(before: np.ndarray, after: np.ndarray) -> bool:
+    """True when the two arrays are pixel-for-pixel identical."""
+    if before.shape != after.shape:
+        return False
+    return content_hash(before) == content_hash(after)
+
+
+# ---------------------------------------------------------------------------
+# 2. Geographic grid alignment (the correct alignment for georeferenced pairs)
+# ---------------------------------------------------------------------------
+
+def geo_align_pair(before_path: Path, after_path: Path
+                   ) -> Optional[Tuple[np.ndarray, np.ndarray, float]]:
+    """Reproject both rasters onto one common grid over their geographic overlap.
+
+    Returns ``(before_rgb, after_rgb, overlap_frac)`` as HxWx3 uint8 arrays on
+    an identical grid, or ``None`` when either input is not georeferenced or the
+    footprints do not overlap. ``overlap_frac`` is the overlap area as a
+    fraction of the *after* footprint — a low value means the two rasters barely
+    cover the same ground.
+    """
+    try:
+        import rasterio
+        from rasterio.transform import from_origin
+        from rasterio.warp import Resampling, reproject
+    except ImportError:
+        logger.warning("rasterio unavailable — cannot geo-align pair")
+        return None
+
+    try:
+        b = rasterio.open(str(before_path))
+        a = rasterio.open(str(after_path))
+    except Exception as exc:
+        logger.warning("geo_align_pair: could not open rasters: %s", exc)
+        return None
+
+    with b, a:
+        if b.crs is None or a.crs is None:
+            return None
+        # Work in the after image's CRS; transform the before bounds into it.
+        try:
+            from rasterio.warp import transform_bounds
+            b_in_a = transform_bounds(b.crs, a.crs, *b.bounds)
+        except Exception:
+            b_in_a = b.bounds
+
+        left = max(b_in_a[0], a.bounds.left)
+        bottom = max(b_in_a[1], a.bounds.bottom)
+        right = min(b_in_a[2], a.bounds.right)
+        top = min(b_in_a[3], a.bounds.top)
+        if right <= left or top <= bottom:
+            return None  # no geographic overlap
+
+        a_area = (a.bounds.right - a.bounds.left) * (a.bounds.top - a.bounds.bottom)
+        overlap_frac = ((right - left) * (top - bottom)) / max(a_area, 1e-9)
+
+        res_x, res_y = a.res
+        width = max(1, int(round((right - left) / res_x)))
+        height = max(1, int(round((top - bottom) / res_y)))
+        dst_transform = from_origin(left, top, res_x, res_y)
+
+        def _warp(src) -> np.ndarray:
+            out = np.zeros((3, height, width), dtype=np.uint8)
+            for i in range(3):  # first three bands = RGB; ignore any alpha
+                reproject(
+                    source=rasterio.band(src, i + 1),
+                    destination=out[i],
+                    src_transform=src.transform, src_crs=src.crs,
+                    dst_transform=dst_transform, dst_crs=a.crs,
+                    resampling=Resampling.bilinear,
+                )
+            return np.ascontiguousarray(out.transpose(1, 2, 0))
+
+        return _warp(b), _warp(a), float(overlap_frac)
+
+
+# ---------------------------------------------------------------------------
+# 3. Alignment-quality assessment
+# ---------------------------------------------------------------------------
+
+def _ncc(gray1: np.ndarray, gray2: np.ndarray) -> float:
+    """Normalized cross-correlation of two same-size grayscale images."""
+    a = gray1.astype(np.float32).ravel()
+    b = gray2.astype(np.float32).ravel()
+    if a.size != b.size or a.size < 64:
+        return 0.0
+    c = np.corrcoef(a, b)[0, 1]
+    return float(c) if np.isfinite(c) else 0.0
+
+
+def assess_alignment(before: np.ndarray, after: np.ndarray,
+                     ncc_ok: float = 0.45) -> Tuple[str, float]:
+    """Judge whether an already-same-grid pair is well enough aligned to detect.
+
+    Uses global NCC on the shared region. A well-registered VHR pair — even with
+    genuine change present — keeps most of the static scene correlated, so NCC
+    stays high; two frames off by rotation/parallax collapse toward zero. Returns
+    ``(status, ncc)`` where status is ``"ok"`` or ``"low_quality"``.
+    """
+    if before.shape != after.shape:
+        after = cv2.resize(after, (before.shape[1], before.shape[0]))
+    g1 = cv2.cvtColor(before, cv2.COLOR_RGB2GRAY)
+    g2 = cv2.cvtColor(after, cv2.COLOR_RGB2GRAY)
+    ncc = _ncc(g1, g2)
+    return ("ok" if ncc >= ncc_ok else "low_quality"), ncc
+
+
+# ---------------------------------------------------------------------------
+# Top-level entry point
+# ---------------------------------------------------------------------------
+
+def prepare_pair(before_path: Path, after_path: Path
+                 ) -> Tuple[Optional[np.ndarray], Optional[np.ndarray], PairAlignResult]:
+    """Load, guard, and align a pair for detection.
+
+    Returns ``(before_rgb, after_rgb, result)``. When ``result.status`` is
+    ``"identical"`` or ``"error"`` the arrays may be ``None`` — callers should
+    surface ``result.message`` to the operator instead of running detection.
+    On ``"ok"``/``"low_quality"`` the arrays are on a common grid and ready for
+    the engine (detection still runs on ``"low_quality"``, just with a warning).
+    """
+    before_path, after_path = Path(before_path), Path(after_path)
+
+    aligned = geo_align_pair(before_path, after_path)
+    if aligned is not None:
+        before, after, overlap = aligned
+        method = "geo_reproject"
+    else:
+        # No georeferencing: fall back to a plain load + resize-to-match so the
+        # engine's own SIFT/ORB/ECC registration can still take over downstream.
+        from .geotiff_io import load_rgb_pil
+        before = np.array(load_rgb_pil(before_path))[:, :, :3]
+        after = np.array(load_rgb_pil(after_path))[:, :, :3]
+        if before.shape != after.shape:
+            before = cv2.resize(before, (after.shape[1], after.shape[0]))
+        overlap = 1.0
+        method = "resize_only"
+
+    if are_identical(before, after):
+        return None, None, PairAlignResult(
+            status="identical",
+            message=("Before and after are the same image (identical pixels). "
+                     "There is no change to detect - check that two different "
+                     "dates were selected."),
+            method=method, grid=(before.shape[1], before.shape[0]),
+            overlap_frac=overlap,
+        )
+
+    status, ncc = assess_alignment(before, after)
+    grid = (before.shape[1], before.shape[0])
+    if status == "ok":
+        msg = f"Pair aligned via {method} (NCC={ncc:.2f}, overlap={overlap:.0%})."
+    else:
+        msg = (f"Pair is poorly aligned (NCC={ncc:.2f}). The two images do not "
+               "register - likely raw drone frames from different viewpoints "
+               "rather than orthomosaics on a common grid. Detection will be "
+               "unreliable; export both dates as north-up orthomosaics on the "
+               "same grid for accurate results.")
+    return before, after, PairAlignResult(
+        status=status, message=msg, ncc=round(ncc, 4),
+        method=method, grid=grid, overlap_frac=round(overlap, 4),
+    )
+
+
+def _main(argv=None) -> int:
+    import argparse
+
+    from PIL import Image
+
+    ap = argparse.ArgumentParser(description="Check before/after pair alignment.")
+    ap.add_argument("before")
+    ap.add_argument("after")
+    ap.add_argument("--out", help="dir to write aligned before/after PNGs")
+    args = ap.parse_args(argv)
+
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    before, after, res = prepare_pair(Path(args.before), Path(args.after))
+    print(f"status      : {res.status}")
+    print(f"message     : {res.message}")
+    print(f"method      : {res.method}")
+    print(f"ncc         : {res.ncc}")
+    print(f"overlap     : {res.overlap_frac}")
+    print(f"grid (w x h): {res.grid}")
+    if args.out and before is not None:
+        out = Path(args.out)
+        out.mkdir(parents=True, exist_ok=True)
+        Image.fromarray(before).save(out / "aligned_before.png")
+        Image.fromarray(after).save(out / "aligned_after.png")
+        print(f"wrote aligned PNGs to {out}")
+    return 0 if res.status in ("ok", "low_quality") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

app/dda/preflight.py

@@ -0,0 +1,317 @@
+"""Preflight image-pair validation: CRS, GSD, RGB bands, overlap, georeferencing.
+
+Runs once per detection request, right after library paths are resolved but
+before either image is pixel-decoded — all checks here are cheap header-only
+reads, so a genuinely unusable pair (unreadable file, unsupported band
+layout, no ground overlap) is rejected in milliseconds instead of after
+minutes of registration + model inference. Lesser issues (grayscale input,
+manual-bounds-only georeferencing, GSD mismatch, weak overlap) don't block
+detection — they're collected as warnings and surfaced on the result instead.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from sqlalchemy.orm import Session
+
+from ..detection_config import (
+    get_gsd_tolerance,
+    get_max_aspect_ratio_diff,
+    get_min_overlap_hard,
+    get_min_overlap_warn,
+)
+from .geo_regions import BoundsWGS84, resolve_geo_context
+from .geotiff_io import inspect_image, read_georef, read_gsd_meters
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+_MODE_BAND_COUNTS = {
+    "1": 1, "L": 1, "I": 1, "F": 1,
+    "LA": 2,
+    "RGB": 3, "YCbCr": 3, "P": 3,
+    "RGBA": 4, "CMYK": 4,
+}
+
+_NON_RGB_BAND_KEYWORDS = ("nir", "infrared", "swir", "thermal", "alpha", "panchromatic")
+
+
+@dataclass
+class CheckResult:
+    name: str        # readability|bands|georef|crs|gsd|overlap
+    status: str       # pass|warn|fail
+    message: str = ""
+
+
+@dataclass
+class PreflightResult:
+    hard_fail: bool = False
+    fail_reason: str = ""
+    warnings: List[str] = field(default_factory=list)
+    checks: List[CheckResult] = field(default_factory=list)
+
+
+def read_band_count(path: Path) -> Optional[int]:
+    """Raster band count via rasterio, falling back to a Pillow mode→band map."""
+    try:
+        import rasterio
+        with rasterio.open(path) as src:
+            return int(src.count)
+    except ImportError:
+        pass
+    except Exception as exc:
+        logger.warning("read_band_count rasterio failed for %s: %s", path.name, exc)
+    try:
+        from PIL import Image
+        with Image.open(path) as img:
+            return _MODE_BAND_COUNTS.get(img.mode, len(img.getbands()))
+    except Exception as exc:
+        logger.warning("read_band_count Pillow failed for %s: %s", path.name, exc)
+        return None
+
+
+def _rect_overlap_frac(
+    before_bounds: Optional[BoundsWGS84],
+    after_bounds: Optional[BoundsWGS84],
+) -> Optional[float]:
+    """Intersection area / after-footprint area, as a plain WGS84 rectangle."""
+    if not before_bounds or not after_bounds:
+        return None
+    bw, bs, be, bn = before_bounds
+    aw, asf, ae, an = after_bounds
+    ix0, iy0 = max(bw, aw), max(bs, asf)
+    ix1, iy1 = min(be, ae), min(bn, an)
+    inter_w, inter_h = max(0.0, ix1 - ix0), max(0.0, iy1 - iy0)
+    inter_area = inter_w * inter_h
+    after_area = max(1e-12, abs(ae - aw) * abs(an - asf))
+    return inter_area / after_area
+
+
+def _apply_roi_to_bounds(
+    bounds: Optional[BoundsWGS84], roi: Optional[dict],
+) -> Optional[BoundsWGS84]:
+    """Crop a WGS84 rectangle to a fractional {x,y,w,h} ROI window.
+
+    Mirrors ``load_rgb_roi``'s convention: x/y are the top-left corner and
+    y grows downward in the image's own pixel grid, i.e. y=0 is the image's
+    top edge (north when north-up). The same fractional window is applied to
+    both images by the caller (matching how detection itself crops both
+    images to the same fractional ROI), so overlap is checked on the actual
+    selected area rather than the full footprint.
+    """
+    if not bounds or not roi:
+        return bounds
+    west, south, east, north = bounds
+    x, y, w, h = roi["x"], roi["y"], roi["w"], roi["h"]
+    roi_west = west + x * (east - west)
+    roi_east = west + (x + w) * (east - west)
+    roi_north = north - y * (north - south)
+    roi_south = north - (y + h) * (north - south)
+    return (roi_west, roi_south, roi_east, roi_north)
+
+
+def read_band_descriptions(path: Path) -> Optional[List[str]]:
+    """First-3-band GDAL band descriptions, when the file has any set."""
+    try:
+        import rasterio
+        with rasterio.open(path) as src:
+            return list(src.descriptions[:3])
+    except Exception:
+        return None
+
+
+def _suspicious_band_order(descriptions: Optional[List[Optional[str]]]) -> bool:
+    """Best-effort hint only — most files carry no band descriptions at all,
+    so this stays silent far more often than it fires. There is no reliable
+    way to verify true RGB band *order* from metadata alone; this only flags
+    the case where a sensor explicitly labelled a leading band as non-visible
+    (e.g. NIR), which is worth a second look before trusting on-screen color.
+    """
+    if not descriptions:
+        return False
+    for d in descriptions:
+        if not d:
+            continue
+        low = d.lower()
+        if any(kw in low for kw in _NON_RGB_BAND_KEYWORDS):
+            return True
+    return False
+
+
+def run_preflight_checks(
+    db: Session,
+    before_path: Path,
+    after_path: Path,
+    before_rel: str,
+    after_rel: str,
+    roi: Optional[dict] = None,
+) -> PreflightResult:
+    """Validate a (before, after) library image pair before decoding pixels.
+
+    ``roi`` (optional fractional ``{x,y,w,h}``) narrows the overlap check to
+    the actually-selected crop window instead of the full image footprints,
+    matching what detection itself will run on when a ROI is set.
+    """
+    result = PreflightResult()
+
+    # 1. Readability
+    before_meta = inspect_image(before_path)
+    after_meta = inspect_image(after_path)
+    if before_meta.width <= 0 or before_meta.height <= 0:
+        result.hard_fail = True
+        result.fail_reason = f"Before image could not be read: {before_path.name}"
+        result.checks.append(CheckResult("readability", "fail", result.fail_reason))
+        return result
+    if after_meta.width <= 0 or after_meta.height <= 0:
+        result.hard_fail = True
+        result.fail_reason = f"After image could not be read: {after_path.name}"
+        result.checks.append(CheckResult("readability", "fail", result.fail_reason))
+        return result
+    result.checks.append(CheckResult("readability", "pass"))
+
+    # 2. RGB bands
+    before_bands = read_band_count(before_path)
+    after_bands = read_band_count(after_path)
+    for label, bands, path in (
+        ("Before", before_bands, before_path),
+        ("After", after_bands, after_path),
+    ):
+        if not bands:
+            result.hard_fail = True
+            result.fail_reason = f"{label} image band layout could not be determined: {path.name}"
+            result.checks.append(CheckResult("bands", "fail", result.fail_reason))
+            return result
+        if bands == 2:
+            result.hard_fail = True
+            result.fail_reason = f"{label} image has an unsupported 2-band layout: {path.name}"
+            result.checks.append(CheckResult("bands", "fail", result.fail_reason))
+            return result
+    band_msgs = []
+    if before_bands == 1 or after_bands == 1:
+        band_msgs.append(
+            "One or both images are single-band (grayscale) — detection runs on a tripled grayscale channel.")
+    extra_band_labels = [
+        label for label, bands in (("Before", before_bands), ("After", after_bands)) if bands > 3
+    ]
+    if extra_band_labels:
+        band_msgs.append(
+            f"{' and '.join(extra_band_labels)} image has more than 3 bands — "
+            "only the first 3 are used for detection.")
+    suspicious_labels = [
+        label for label, path in (("Before", before_path), ("After", after_path))
+        if _suspicious_band_order(read_band_descriptions(path))
+    ]
+    if suspicious_labels:
+        band_msgs.append(
+            f"{' and '.join(suspicious_labels)} image band descriptions suggest non-RGB content "
+            "(e.g. NIR/infrared) in the first bands — verify band order before relying on colors.")
+    if band_msgs:
+        for msg in band_msgs:
+            result.warnings.append(msg)
+            result.checks.append(CheckResult("bands", "warn", msg))
+    else:
+        result.checks.append(CheckResult("bands", "pass"))
+
+    # 3. Georeferencing (also feeds the CRS/GSD/overlap checks below)
+    before_geo = resolve_geo_context(db, before_rel, before_path)
+    after_geo = resolve_geo_context(db, after_rel, after_path)
+
+    if before_geo.source == "none" and after_geo.source == "none":
+        # Plain, non-georeferenced photo pair — an already-supported use case
+        # (pair_align's resize_only fallback). Skip CRS/GSD/overlap entirely
+        # rather than penalize a mode the app deliberately allows.
+        result.checks.append(CheckResult(
+            "georef", "pass", "Neither image is georeferenced — treated as a plain photo pair."))
+        result.checks.append(CheckResult("crs", "pass"))
+        result.checks.append(CheckResult("gsd", "pass"))
+        # With no georeferencing, overlap can't be checked geographically — but
+        # detection still force-resizes "after" to "before"'s pixel dimensions
+        # regardless, so a large aspect-ratio gap is worth flagging here instead.
+        ratio_b = before_meta.width / before_meta.height if before_meta.height else 0.0
+        ratio_a = after_meta.width / after_meta.height if after_meta.height else 0.0
+        if ratio_b > 0 and ratio_a > 0:
+            rel_diff = abs(ratio_b - ratio_a) / max(ratio_b, ratio_a)
+            if rel_diff > get_max_aspect_ratio_diff():
+                msg = (
+                    f"Images have different aspect ratios (before {before_meta.width}x{before_meta.height}, "
+                    f"after {after_meta.width}x{after_meta.height}) — the after image will be stretched "
+                    "to match, which may distort content.")
+                result.warnings.append(msg)
+                result.checks.append(CheckResult("aspect_ratio", "warn", msg))
+            else:
+                result.checks.append(CheckResult("aspect_ratio", "pass"))
+        result.checks.append(CheckResult("overlap", "pass"))
+        return result
+
+    if before_geo.source == "none" or after_geo.source == "none":
+        msg = "Only one image is georeferenced — geographic overlap could not be verified."
+        result.warnings.append(msg)
+        result.checks.append(CheckResult("georef", "warn", msg))
+    elif before_geo.source == "manual" or after_geo.source == "manual":
+        msg = "One or both images rely on manually-entered bounds rather than embedded georeferencing."
+        result.warnings.append(msg)
+        result.checks.append(CheckResult("georef", "warn", msg))
+    else:
+        result.checks.append(CheckResult("georef", "pass"))
+
+    # 4. CRS — present but unreprojectable is distinguishable from absent
+    before_georef = read_georef(before_path)
+    after_georef = read_georef(after_path)
+    broken_crs = [
+        label for label, gi in (("Before", before_georef), ("After", after_georef))
+        if gi is not None and gi.crs is not None and gi.bounds_wgs84 is None
+    ]
+    if broken_crs:
+        msg = (f"{' and '.join(broken_crs)} image CRS is present but could not be reprojected "
+               "to WGS84 — verify the coordinate system.")
+        result.warnings.append(msg)
+        result.checks.append(CheckResult("crs", "warn", msg))
+    else:
+        result.checks.append(CheckResult("crs", "pass"))
+
+    # 5. GSD — never a hard fail, only harmonization is affected downstream
+    gsd_b = read_gsd_meters(before_path)
+    gsd_a = read_gsd_meters(after_path)
+    if gsd_b and gsd_a:
+        rel_diff = abs(gsd_b - gsd_a) / max(gsd_b, gsd_a)
+        tolerance = get_gsd_tolerance()
+        if rel_diff > tolerance:
+            msg = (f"Ground sample distance differs by {rel_diff * 100:.0f}% "
+                   f"(before {gsd_b:.2f} m/px, after {gsd_a:.2f} m/px) — "
+                   "the finer image will be resampled to match.")
+            result.warnings.append(msg)
+            result.checks.append(CheckResult("gsd", "warn", msg))
+        else:
+            result.checks.append(CheckResult("gsd", "pass"))
+    else:
+        result.checks.append(CheckResult("gsd", "pass"))
+
+    # 6. Overlap — cropped to the selected ROI when one is set, so the check
+    # reflects the area detection will actually run on, not the full images.
+    before_bounds = _apply_roi_to_bounds(before_geo.bounds, roi)
+    after_bounds = _apply_roi_to_bounds(after_geo.bounds, roi)
+    roi_note = " within the selected area" if roi else ""
+    overlap_frac = _rect_overlap_frac(before_bounds, after_bounds)
+    if overlap_frac is not None:
+        hard_min = get_min_overlap_hard()
+        warn_min = get_min_overlap_warn()
+        if overlap_frac < hard_min:
+            result.hard_fail = True
+            result.fail_reason = (
+                f"Images do not overlap on the ground{roi_note} (overlap {overlap_frac * 100:.1f}% "
+                "of the after-image footprint) — not suitable for change detection.")
+            result.checks.append(CheckResult("overlap", "fail", result.fail_reason))
+            return result
+        if overlap_frac < warn_min:
+            msg = f"Weak geographic overlap{roi_note} ({overlap_frac * 100:.1f}% of the after-image footprint)."
+            result.warnings.append(msg)
+            result.checks.append(CheckResult("overlap", "warn", msg))
+        else:
+            result.checks.append(CheckResult("overlap", "pass"))
+    else:
+        result.checks.append(CheckResult("overlap", "pass"))
+
+    return result