Architecture

The application follows a modular pipeline architecture:

Geocode Location
       |
       v
Resolve AOI (GAUL District / OSM City)
       |
       v
Fetch Sentinel 2 Composite (Before)
       |
       v
Fetch Sentinel 2 Composite (After)
       |
       v
Build Dynamic World Probability Maps (Before + After)
       |
       v
Detect Changes (Rule Engine + Spectral Cross Validation)
       |
       v
Compute Land Cover Statistics
       |
       v
Generate AI Explanation (Groq LLM)

Pipeline Steps

1. Geocoding: Resolves user provided location strings to lat/lon coordinates via Nominatim.
2. AOI Resolution: Looks up the corresponding FAO GAUL Level 2 district boundary, or uses OSM to find a city/town polygon.
3. Composite Building: Fetches Sentinel 2 SR Harmonized scenes, applies cloud filtering and SCL masking, then computes a median composite for each time period.
4. Dynamic World Processing: Medians Dynamic World probability bands to create stable per pixel class distributions.
5. Signature Mapping: Maps 9 band DW probabilities into a 5 class schema (Water, Forest, Bare Land, Agriculture, Urban) with dominance margins and confidence floors.
6. Change Detection: Applies a three gate rule engine per approved transition:
   • Confidence gate: both endpoints must exceed minimum class proportion
   • Surge gate: target class probability must increase significantly
   • Spectral gate: NDVI/NDWI cross validation to reject false positives
7. Statistics: Computes per class pixel counts and percentages using GEE reduceRegion.
8. Explanation: Formats results and land cover stats into a prompt for the Groq LLM to generate natural language insights.

Installation

Prerequisites

• Python 3.10 or higher
• A Google Earth Engine account with a registered cloud project
• A Groq API key (for AI explanations and chat features)

Setup

1. Clone the repository:

git clone https://github.com/Vedant-Git-dev/GeoVision.git

2. Install dependencies:

pip install -r requirements.txt

3. Authenticate with Google Earth Engine:

earthengine authenticate

4. Configure environment variables:

cp .env.example .env
# Edit .env and set your EE_PROJECT_ID and GROQ_API_KEY

5. Run the application:

python app.py

The server will start on http://127.0.0.1:5000.

Configuration

Configuration is centralized in geovision/config.py. Key settings include:

API Endpoints

POST /generate

Runs the satellite change detection pipeline synchronously.

Request Body:

{
  "location": "Pune, India",
  "before_date": "2023-11-01",
  "after_date": "2024-11-01",
  "question": "What changed?"
}

Response:

{
  "success": true,
  "config": {
    "center": [18.5936, 73.7301],
    "before_tiles": "https://...",
    "after_tiles": "https://...",
    "change_mask_tiles": "https://...",
    "land_cover_before_tiles": "https://...",
    "land_cover_after_tiles": "https://...",
    "land_cover_stats": { ... },
    "aoi": { ... },
    "area_name": "Pune",
    "settlements": [ ... ]
  },
  "explanation": "AI generated summary..."
}

POST /generate/stream

Same as /generate but streams progress as Server Sent Events.

Event Types:

• progress: Pipeline step updates with step name, number, and total
• result: Final analysis result
• error: Error details if the pipeline fails

POST /api/chat

Processes a natural language chat message and returns an analysis or conversational reply.

Request Body:

{
  "message": "What changed in Mumbai between 2020 and 2024?",
  "history": []
}

POST /api/chat/stream

Chat endpoint with SSE streaming for real time pipeline progress.

Project Structure

.
├── app.py                          # Flask application entry point
├── requirements.txt                # Python dependencies
├── .env.example                    # Environment variable template
├── public/                         # Static frontend assets
│   ├── chat.html                   # Main chat interface
│   ├── chat.css                    # Chat styles with light/dark themes
│   ├── chat.js                     # Client side chat logic
│   └── style.css                   # Additional styles
└── geovision/                      # Core application package
    ├── __init__.py                 # Package initialization and logging
    ├── config.py                   # Centralized constants and settings
    ├── pipeline.py                 # Main pipeline orchestrator
    ├── chat.py                     # Natural language intent parser and orchestrator
    ├── explain.py                  # LLM explanation generator
    ├── ee_init.py                  # Google Earth Engine initialization
    ├── geocode.py                  # Nominatim geocoding wrapper
    ├── boundary.py                 # FAO GAUL and OSM boundary lookup
    ├── composite.py                # Sentinel 2 cloud masking and compositing
    ├── dynamic_world.py            # Dynamic World probability compositing
    ├── signature.py                # DW to 5 class signature mapping
    ├── changes.py                  # Change detection rule engine
    ├── stats.py                    # Land cover statistics computation
    ├── settlements.py              # OSM settlement discovery
    ├── spectral.py                 # Spectral index computation (NDVI/NDWI)
    └── types.py                    # Core data types (Location, DateRange)

Change Detection Methodology

GeoVision uses a rigorous multi gate approach to minimize false positives:

Approved Transitions

The system monitors these specific land cover transitions:

Three Gate Validation

For a pixel to register as a valid transition, it must pass all three gates:

1. Confidence Gate: Both the source and target class proportions must exceed MIN_CLASS_CONF (0.45) in their respective timelines. This ensures both endpoints are decisive classifications rather than noisy mixed pixels.

2. Surge Gate: The target class's raw Dynamic World probability must have increased by at least MIN_PROB_SURGE (0.25) between the before and after periods. This catches genuine transitions rather than classification noise at the boundary.

3. Spectral Gate: Independent spectral indices cross validate the Dynamic World labels. Transitions to forest require NDVI >= 0.3, and transitions to water require NDWI >= 0.1. This rejects shadows misclassified as water and senescent vegetation misclassified as bare land.

Signature Mapping

Dynamic World provides 9 probability bands per pixel. GeoVision maps these to a simplified 5 class schema using raw (non normalized) probabilities with a dominance margin check. A class is only assigned if it beats every other class by at least 0.05 and has a raw proportion of at least 0.25. This prevents "tallest dwarf" errors where all classes have low confidence but one happens to be highest.

Land Cover Classes

AI Chat Features

The chat interface supports natural language queries such as:

• "What changed in Mumbai between 2020 and 2024?"
• "Show me deforestation in Amazon 2019 to 2023"
• "Analyze urban growth in Bangalore from 2018 to 2024"
• "How has the coastline changed in Dubai since 2017?"

The chat parser maintains conversation history, reuses previously established parameters, and asks clarifying questions when location or dates are missing. It also supports city level granularity when users specify sub areas (e.g., "Kharadi, Pune" or "Whitefield, Bangalore").

Dependencies

See requirements.txt for the full list. Key dependencies include: