ARCHITECTURE.md

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/HF Spaces)  │
└─────────────────────┴───────────────────────────┘

---

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. Supports PostgreSQL via DATABASE_URL environment variable for production (with automatic postgres:// → postgresql:// rewrite for SQLAlchemy 2.x compatibility).
• 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
psycopg2-binary	PostgreSQL driver (for production databases)
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. SQLite database is created in data/satellite_app.db.
• Hugging Face Spaces: Push to the linked HF repo. The Dockerfile builds and deploys automatically. Database is stored at /home/appuser/data/ (ephemeral — resets on container restart).
• Production with PostgreSQL: Set DATABASE_URL environment variable to a PostgreSQL connection string. Set SECRET_KEY to a strong random value.