Add Delhi zone/village dropdowns, location tracking, and project documentation

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,386 @@
+# 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.

app/main.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import Optional
 
 import numpy as np
+from sqlalchemy import text as sa_text
 from fastapi import FastAPI, Depends, File, Form, HTTPException, Request, UploadFile
 from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
@@ -29,7 +30,18 @@ from .detection_engine import run_detection
 
 Base.metadata.create_all(bind=engine, checkfirst=True)
 
-app = FastAPI(title="Satellite Change Detection", version="1.0.0")
+# Lightweight migration: add columns introduced after initial schema
+with engine.connect() as conn:
+    for col, col_type in [("zone", "VARCHAR(128) DEFAULT ''"),
+                          ("village", "VARCHAR(128) DEFAULT ''")]:
+        try:
+            conn.execute(sa_text(
+                f"ALTER TABLE detection_runs ADD COLUMN {col} {col_type}"))
+            conn.commit()
+        except Exception:
+            conn.rollback()
+
+app = FastAPI(title="AI Change Detection", version="2.0.0")
 
 # Mount static files
 STATIC_DIR = Path(__file__).resolve().parent.parent / "static"
@@ -159,6 +171,8 @@ async def detect(
     after: UploadFile = File(...),
     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),
     access_token: Optional[str] = Form(None),
@@ -221,6 +235,8 @@ async def detect(
         user_id=user.id,
         title=title,
         method=method,
+        zone=zone,
+        village=village,
         total_pixels=total_px,
         changed_pixels=changed_px,
         change_percentage=change_pct,
@@ -240,6 +256,8 @@ async def detect(
         "id": run.id,
         "title": run.title,
         "method": run.method,
+        "zone": run.zone or "",
+        "village": run.village or "",
         "statistics": {
             "totalPixels": total_px,
             "changedPixels": changed_px,
@@ -281,6 +299,8 @@ def history(
             "id": r.id,
             "title": r.title,
             "method": r.method,
+            "zone": r.zone or "",
+            "village": r.village or "",
             "changePercentage": r.change_percentage,
             "regionsCount": r.regions_count,
             "overlayUrl": f"/api/overlay/{r.overlay_path}" if r.overlay_path else None,

app/models.py

@@ -29,6 +29,8 @@ class DetectionRun(Base):
     change_percentage = Column(Float, nullable=False)
     regions_count = Column(Integer, default=0)
     overlay_path = Column(String(512), default="")  # optional: path to saved overlay image
+    zone = Column(String(128), default="")
+    village = Column(String(128), default="")
     regions_json = Column(Text, default="[]")  # JSON list of regions
     created_at = Column(DateTime, default=datetime.utcnow)
 

static/css/style.css

@@ -448,6 +448,29 @@ input:focus, select:focus, textarea:focus {
   font-size: 0.9rem;
 }
 
+/* ---- Location row ---- */
+.location-row {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+  margin-bottom: 1.25rem;
+}
+.location-row label {
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+}
+.location-row label svg {
+  color: var(--grad-start);
+  flex-shrink: 0;
+}
+.location-row select {
+  width: 100%;
+}
+@media (max-width: 640px) {
+  .location-row { grid-template-columns: 1fr; }
+}
+
 /* ---- Upload zones ---- */
 .upload-grid {
   display: grid;
@@ -562,6 +585,15 @@ input:focus, select:focus, textarea:focus {
   letter-spacing: 0.06em;
   margin-top: 0.2rem;
 }
+.stat-box-wide {
+  grid-column: span 2;
+}
+.stat-box .value-sm {
+  font-size: clamp(0.75rem, 3vw, 1.05rem);
+}
+@media (max-width: 640px) {
+  .stat-box-wide { grid-column: span 1; }
+}
 
 /* ---- Compare slider ---- */
 .compare-slider {
@@ -729,6 +761,12 @@ input:focus, select:focus, textarea:focus {
   color: var(--text-muted);
   margin-right: 0.3rem;
 }
+.history-meta .tag-loc {
+  background: linear-gradient(135deg, var(--grad-start), var(--grad-end));
+  color: #fff;
+  border-color: transparent;
+  font-family: var(--font);
+}
 
 .history-actions {
   display: flex;

static/js/app.js

@@ -182,6 +182,97 @@ function setupUploadZone(inputId, nameId, zoneId, previewId) {
 setupUploadZone('file-before', 'name-before', 'zone-before', 'preview-before');
 setupUploadZone('file-after', 'name-after', 'zone-after', 'preview-after');
 
+// ---- Delhi Zone → Village cascading dropdowns ----
+const DELHI_ZONES = {
+  "Central Delhi": [
+    "Karol Bagh", "Paharganj", "Daryaganj", "Rajinder Nagar", "Patel Nagar",
+    "Anand Parbat", "Bapa Nagar", "Prasad Nagar", "Dev Nagar", "Old Rajinder Nagar"
+  ],
+  "New Delhi": [
+    "Connaught Place", "Chanakyapuri", "Lodhi Road", "Mandi House",
+    "India Gate", "Khan Market", "Barakhamba", "Gole Market", "Sansad Marg"
+  ],
+  "North Delhi": [
+    "Civil Lines", "Model Town", "Sadar Bazaar", "Timarpur", "Gulabi Bagh",
+    "Kamla Nagar", "Shakti Nagar", "Roop Nagar", "Vijay Nagar", "Mukherjee Nagar",
+    "GTB Nagar", "Adarsh Nagar", "Azadpur", "Wazirabad"
+  ],
+  "North West Delhi": [
+    "Rohini", "Narela", "Bawana", "Alipur", "Shalimar Bagh",
+    "Pitampura", "Kanjhawala", "Mundka", "Sultanpuri", "Mangolpuri",
+    "Begumpur", "Pooth Kalan", "Holambi Kalan", "Bankner", "Siraspur"
+  ],
+  "North East Delhi": [
+    "Seelampur", "Jafrabad", "Mustafabad", "Babarpur", "Gokulpuri",
+    "Yamuna Vihar", "Karawal Nagar", "Dayalpur", "Khajuri Khas",
+    "Bhajanpura", "Harsh Vihar", "Brahmpuri", "Ghonda"
+  ],
+  "East Delhi": [
+    "Preet Vihar", "Laxmi Nagar", "Mayur Vihar Phase I", "Mayur Vihar Phase II",
+    "Mayur Vihar Phase III", "Patparganj", "Pandav Nagar", "Shakarpur",
+    "Mandawali", "Kalyanpuri", "Trilokpuri", "Kondli", "Gharoli",
+    "Khichripur", "Anand Vihar"
+  ],
+  "Shahdara": [
+    "Shahdara", "Vivek Vihar", "Dilshad Garden", "Seema Puri", "New Seelampur",
+    "Nand Nagri", "Harsh Vihar", "Jhilmil Colony", "Mansarovar Park"
+  ],
+  "South Delhi": [
+    "Hauz Khas", "Mehrauli", "Saket", "Kalkaji", "Greater Kailash",
+    "Malviya Nagar", "Vasant Kunj", "Chattarpur", "Lado Sarai",
+    "Fatehpur Beri", "Mandi Village", "Dera Village", "Aaya Nagar",
+    "Sultanpur", "Ghitorni", "Satbari", "Jonapur", "Asola"
+  ],
+  "South East Delhi": [
+    "Defence Colony", "Okhla", "Jamia Nagar", "Badarpur", "Jaitpur",
+    "Madanpur Khadar", "Sarita Vihar", "Jasola", "Sukhdev Vihar",
+    "Tughlakabad", "Sangam Vihar", "Mithapur", "Pul Pehlad"
+  ],
+  "South West Delhi": [
+    "Dwarka", "Najafgarh", "Kapashera", "Palam", "Dabri",
+    "Mahavir Enclave", "Bindapur", "Uttam Nagar", "Nasirpur",
+    "Chhawla", "Dichaon Kalan", "Ghumanhera", "Jhatikara",
+    "Rawta", "Pochanpur", "Bijwasan", "Sarangpur", "Paprawat"
+  ],
+  "West Delhi": [
+    "Rajouri Garden", "Janakpuri", "Tilak Nagar", "Vikaspuri",
+    "Hari Nagar", "Subhash Nagar", "Tagore Garden", "Moti Nagar",
+    "Kirti Nagar", "Punjabi Bagh", "Nangloi Jat", "Nilothi",
+    "Mundka", "Madipur", "Paschim Vihar"
+  ]
+};
+
+(function initZoneVillage() {
+  const zoneSel = document.getElementById('detect-zone');
+  const villageSel = document.getElementById('detect-village');
+  if (!zoneSel || !villageSel) return;
+
+  Object.keys(DELHI_ZONES).sort().forEach(z => {
+    const opt = document.createElement('option');
+    opt.value = z;
+    opt.textContent = z;
+    zoneSel.appendChild(opt);
+  });
+
+  zoneSel.addEventListener('change', () => {
+    const zone = zoneSel.value;
+    villageSel.innerHTML = '';
+    if (!zone) {
+      villageSel.disabled = true;
+      villageSel.innerHTML = '<option value="">— Select Zone first —</option>';
+      return;
+    }
+    villageSel.disabled = false;
+    villageSel.innerHTML = '<option value="">— Select Village / Area —</option>';
+    (DELHI_ZONES[zone] || []).forEach(v => {
+      const opt = document.createElement('option');
+      opt.value = v;
+      opt.textContent = v;
+      villageSel.appendChild(opt);
+    });
+  });
+})();
+
 // ---- Run detection ----
 document.getElementById('form-detect')?.addEventListener('submit', async (e) => {
   e.preventDefault();
@@ -204,6 +295,8 @@ document.getElementById('form-detect')?.addEventListener('submit', async (e) =>
   form.append('after', after);
   form.append('method', document.getElementById('detect-method').value);
   form.append('title', document.getElementById('detect-title').value || 'Untitled run');
+  form.append('zone', document.getElementById('detect-zone').value || '');
+  form.append('village', document.getElementById('detect-village').value || '');
   form.append('enable_registration', document.getElementById('detect-registration').checked);
   form.append('enable_normalization', document.getElementById('detect-normalization').checked);
   if (token) form.append('access_token', token);
@@ -247,11 +340,15 @@ function showResult(data) {
   const statsEl = document.getElementById('result-stats');
   const tbody = document.getElementById('regions-tbody');
 
+  const locParts = [data.village, data.zone].filter(Boolean);
+  const locLabel = locParts.length ? locParts.join(', ') : '—';
+
   statsEl.innerHTML = `
     <div class="stat-box"><div class="value">${data.statistics.changePercentage.toFixed(2)}%</div><div class="label">Changed</div></div>
     <div class="stat-box"><div class="value" title="${data.statistics.changedPixels.toLocaleString()}">${formatCompact(data.statistics.changedPixels)}</div><div class="label">Changed px</div></div>
     <div class="stat-box"><div class="value" title="${data.statistics.totalPixels.toLocaleString()}">${formatCompact(data.statistics.totalPixels)}</div><div class="label">Total px</div></div>
     <div class="stat-box"><div class="value">${(data.regions || []).length}</div><div class="label">Regions</div></div>
+    <div class="stat-box stat-box-wide"><div class="value value-sm" title="${locLabel}">${locLabel}</div><div class="label">Location</div></div>
   `;
 
   const beforeImg = document.getElementById('compare-before-img');
@@ -331,12 +428,15 @@ async function loadHistory() {
       list.innerHTML = '<div class="history-empty">No detection runs yet. Upload images above to get started.</div>';
       return;
     }
-    list.innerHTML = items.map((r) => `
+    list.innerHTML = items.map((r) => {
+      const loc = [r.village, r.zone].filter(Boolean).join(', ');
+      return `
       <div class="history-item" data-id="${r.id}">
         <div class="history-info">
           <div class="history-title">${escapeHtml(r.title)}</div>
           <div class="history-meta">
             <span class="tag">${r.method}</span>
+            ${loc ? `<span class="tag tag-loc">${escapeHtml(loc)}</span>` : ''}
             ${r.changePercentage.toFixed(2)}% changed &middot; ${r.regionsCount} regions &middot; ${formatDate(r.createdAt)}
           </div>
         </div>
@@ -346,8 +446,8 @@ async function loadHistory() {
             <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6v14a2 2 0 01-2 2H7a2 2 0 01-2-2V6m3 0V4a2 2 0 012-2h4a2 2 0 012 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>
           </button>
         </div>
-      </div>
-    `).join('');
+      </div>`;
+    }).join('');
   } catch (_) {
     list.innerHTML = '<div class="history-empty">Could not load history.</div>';
   }

templates/index.html

@@ -167,6 +167,26 @@
           <h3>New Detection Run</h3>
         </div>
         <form id="form-detect">
+          <div class="location-row">
+            <div class="form-group">
+              <label for="detect-zone">
+                <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 10c0 7-9 13-9 13s-9-6-9-13a9 9 0 0118 0z"/><circle cx="12" cy="10" r="3"/></svg>
+                Zone
+              </label>
+              <select id="detect-zone">
+                <option value="">— Select Zone —</option>
+              </select>
+            </div>
+            <div class="form-group">
+              <label for="detect-village">
+                <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 9l9-7 9 7v11a2 2 0 01-2 2H5a2 2 0 01-2-2z"/><polyline points="9 22 9 12 15 12 15 22"/></svg>
+                Village / Area
+              </label>
+              <select id="detect-village" disabled>
+                <option value="">— Select Zone first —</option>
+              </select>
+            </div>
+          </div>
           <div class="upload-grid">
             <div class="upload-zone" id="zone-before">
               <input type="file" id="file-before" accept="image/png,image/jpeg,image/jpg" />
@@ -292,6 +312,6 @@
     </div>
   </div>
 
-  <script src="/static/js/app.js?v=12"></script>
+  <script src="/static/js/app.js?v=13"></script>
 </body>
 </html>