WatershedScope

Application of Geospatial Techniques for Visualization and Analysis to Interpret Geo-Coded Images to Enhance Watershed Development Outcomes

WatershedScope is a full-stack geospatial web application for watershed delineation, satellite-image analysis, thematic mapping, and field verification.

The application allows users to select a pour point, delineate an upstream watershed using Digital Elevation Model (DEM) data, discover Sentinel-2 satellite scenes, generate vegetation and water-related indices, extract drainage networks, perform watershed-level statistics, and visualize geo-coded field photographs on an interactive map.

The system is primarily designed as a research and educational demonstrator for watershed monitoring, particularly for semi-arid regions of India.

Why It Matters

Watershed development requires reliable spatial information about:

Land use and land cover
Drainage networks
Vegetation condition
Surface water
Elevation and terrain
Changes over time
Field-level observations

Traditional watershed monitoring often depends heavily on manual field surveys. While geo-coded field photographs are routinely collected, they are frequently treated only as documentation rather than as spatially connected evidence.

WatershedScope connects these field observations with remotely sensed and terrain data through a single interactive geospatial interface.

Key Capabilities

Cloud-Based Raster Access — Reads Sentinel-2 and Copernicus DEM data through HTTP range requests instead of downloading complete datasets.
On-Demand Watershed Delineation — Generates catchment boundaries from a user-selected pour point.
Drainage Extraction — Derives stream networks from flow-accumulation data.
Thematic Mapping — Generates RGB, NDVI, NDWI, MNDWI, water-mask, and land-cover layers.
Temporal Analysis — Compares vegetation conditions between satellite scenes.
Field Verification — Maps geo-coded photographs to their geographic locations.
Watershed Statistics — Provides summary statistics for the selected watershed.

Features

Feature	Description
Watershed Delineation	Select a pour point and generate the upstream catchment boundary using DEM-derived hydrological analysis.
Drainage Network	Extract stream networks using configurable flow-accumulation thresholds.
Satellite Scene Discovery	Discover available Sentinel-2 L2A scenes for a selected location and date range.
Thematic Layers	Generate True Color, NDVI, NDWI, MNDWI, Water Mask, and Land Cover layers.
Change Detection	Calculate NDVI differences between two selected satellite scenes.
Zonal Statistics	Calculate watershed area, mean NDVI, vegetation fraction, water fraction, land-cover distribution, and elevation statistics.
Geo-Coded Image Registry	Upload field photographs and automatically extract GPS information from EXIF metadata when available.
Interactive Mapping	Visualize watershed boundaries, drainage networks, satellite-derived layers, and field photographs together.
Basemap Integration	Uses ESRI World Imagery as the default satellite basemap.

System Architecture

                 ┌──────────────────────────────────────┐
                 │       React + Leaflet SPA            │
                 │             Vite : 5173              │
                 └──────────────────┬───────────────────┘
                                    │
                              /api/* Proxy
                                    │
                                    ▼
                 ┌──────────────────────────────────────┐
                 │          FastAPI Backend              │
                 │              Port 8000                │
                 └───────────────┬──────────────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
              ▼                  ▼                  ▼
      ┌───────────────┐  ┌──────────────┐  ┌────────────────┐
      │ Analysis      │  │ Tile Renderer │  │ SQLite Store   │
      │ Engine        │  │              │  │                │
      │               │  │ Raster → PNG │  │ Jobs           │
      │ pysheds       │  │ Web Mercator │  │ Watersheds     │
      │ NumPy         │  │              │  │ Geo-coded      │
      │ scikit-image  │  │              │  │ Images         │
      └───────┬───────┘  └──────┬───────┘  └────────────────┘
              │                  │
              └──────────────────┘
                       │
                       ▼
          ┌─────────────────────────────────────┐
          │       Remote Cloud Raster Data      │
          │                                     │
          │  • Sentinel-2 L2A                   │
          │  • Copernicus DEM 30 m              │
          └─────────────────────────────────────┘

Remote Data Sources

WatershedScope is designed to read raster data dynamically rather than downloading complete datasets.

Sentinel-2

Sentinel-2 Level-2A imagery is used for:

True Color visualization
NDVI
NDWI
MNDWI
Water detection
Land-cover clustering
Temporal change detection

Copernicus DEM

Copernicus DEM 30 m data is used for:

Elevation analysis
Flow-direction calculation
Flow-accumulation calculation
Watershed delineation
Drainage-network extraction

The application accesses remote Cloud Optimized GeoTIFF (COG) resources using GDAL/rasterio HTTP range requests where supported.

The application avoids downloading complete source datasets locally. Only the raster windows required for the current analysis are requested, while processing may still require temporary memory or local resources.

Getting Started

Prerequisites

Python 3.10+
Node.js 18+
npm
Git

1. Start the Backend

cd backend

pip install -r requirements.txt

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

The API will be available at:

http://localhost:8000

FastAPI documentation:

http://localhost:8000/docs

2. Start the Frontend

cd frontend

npm install
npm run dev

The frontend will be available at:

http://localhost:5173

The Vite development server proxies /api requests to the FastAPI backend.

Tests

Install the test dependencies:

cd backend

pip install pytest httpx

Run the test suite:

python -m pytest tests/ -q

API Overview

Long-running operations such as watershed delineation and satellite-scene discovery are handled through background jobs.

A typical workflow is:

Create Job
    ↓
Receive Job ID
    ↓
Poll /api/jobs/{id}
    ↓
Job Running
    ↓
Job Succeeded / Failed
    ↓
Read Result

Endpoints

Method	Endpoint	Description
`POST`	`/api/watershed/delineate`	Creates a watershed delineation job from `{lat, lon}`.
`GET`	`/api/watershed/{id}`	Returns persisted watershed GeoJSON.
`GET`	`/api/watershed/{id}/stats?scene=`	Calculates watershed statistics for a selected scene.
`GET`	`/api/drainage/{id}?threshold=`	Returns the extracted drainage network as GeoJSON.
`GET`	`/api/scenes?lat=&lon=&start=&end=`	Discovers Sentinel-2 scenes for a location and date range.
`GET`	`/api/jobs/{id}`	Returns the status and result of a background job.
`GET`	`/api/jobs?limit=`	Returns recent jobs.
`GET`	`/api/layers/{scene}/{kind}/{z}/{x}/{y}.png`	Returns a rendered thematic map tile.
`GET`	`/api/change/{sceneA}/{sceneB}/ndvi/{z}/{x}/{y}.png`	Returns an NDVI change-detection tile.
`GET`	`/api/images`	Lists registered geo-coded images.
`POST`	`/api/images`	Uploads and registers a field photograph.
`DELETE`	`/api/images/{id}`	Deletes a registered image.

Implementation note: If /api/scenes actually creates a background job, consider changing this endpoint to POST /api/scenes for clearer REST semantics. If the current GET implementation is intentional, keep the existing endpoint and document that behavior explicitly.

How to Use

1. Select a Pour Point

Click anywhere on the map to place the pour point.

2. Delineate the Watershed

Click Delineate Watershed.

The backend processes the DEM and returns the upstream catchment boundary.

3. Discover Satellite Scenes

Click Discover Scenes and specify the required date range.

Available Sentinel-2 scenes are displayed for the selected location.

4. Explore Thematic Layers

Select a satellite scene and enable layers such as:

True Color
NDVI
NDWI
MNDWI
Water Mask
Land Cover

5. Analyze Drainage

Click Drainage Network to extract and display streams based on the configured flow-accumulation threshold.

6. Calculate Statistics

Use Compute Statistics to calculate watershed-level metrics including vegetation, water, elevation, and land-cover information.

7. Add Field Observations

Upload geo-coded photographs through the Geo-Coded Images panel.

When GPS coordinates are present in EXIF metadata, they can be associated with the photograph and displayed on the map.

Analysis Workflow

The main geospatial processing pipeline is:

Pour Point
    │
    ▼
Copernicus DEM
    │
    ▼
DEM Preprocessing
    │
    ├── Depression Filling
    │
    ├── Flow Direction
    │
    └── Flow Accumulation
    │
    ▼
Watershed Delineation
    │
    ├── Catchment Boundary
    │
    └── Drainage Network
    │
    ▼
Sentinel-2 Scene Selection
    │
    ├── NDVI
    ├── NDWI
    ├── MNDWI
    ├── Water Mask
    └── Land Cover
    │
    ▼
Watershed Statistics
    │
    └── Temporal Change Analysis

Project Structure

backend/
├── app/
│   ├── main.py          # FastAPI application and API routes
│   ├── jobs.py          # SQLite-backed background job management
│   ├── watershed.py     # Watershed delineation and drainage extraction
│   ├── dem.py           # Copernicus DEM data access
│   ├── sentinel.py      # Sentinel-2 scene discovery
│   ├── analysis.py      # Spectral indices, clustering, change detection
│   ├── tiles.py         # Dynamic Web Mercator tile rendering
│   ├── stats.py         # Watershed statistics
│   ├── images.py        # Image registry and EXIF GPS extraction
│   └── config.py        # Application and data-source configuration
│
├── tests/
│   └── ...              # Backend tests
│
└── requirements.txt

frontend/
├── src/
│   ├── App.jsx          # Main application interface
│   ├── api.js           # Backend API client
│   └── styles.css       # Application styles
│
├── package.json
└── vite.config.js       # Vite configuration and API proxy

docs/
└── superpowers/
    └── specs/
        └── ...          # Application design documentation

Technical Stack

Frontend

React
Vite
Leaflet
JavaScript / JSX
CSS

Backend

FastAPI
Python
SQLite
rasterio
GDAL
NumPy
pysheds
scikit-image
scikit-learn

Geospatial Data

Sentinel-2 Level-2A
Copernicus DEM 30 m
Cloud Optimized GeoTIFFs
GeoJSON
Web Mercator map tiles

Important Limitations

WatershedScope is a research and educational demonstrator, not production-grade hydrological or surveying software.

Results can be affected by:

DEM resolution and quality
Pour-point accuracy
Hydrological preprocessing
Flow-accumulation threshold selection
Satellite-image availability
Cloud contamination
Spatial resolution of satellite bands
Land-cover clustering assumptions
Coordinate transformations and area calculations

The generated watershed boundaries and derived thematic layers should therefore be treated as analytical estimates rather than authoritative engineering or regulatory products.

Performance Considerations

Remote raster processing can be slower than processing locally cached datasets.

In particular:

First-time DEM requests may take longer.
Satellite scene discovery may take approximately 30–60 seconds depending on the query and remote data source.
Large watershed extents require more raster data to be read and processed.
Thematic tiles may require repeated raster reads.
Application-level caching can improve repeated requests.

Geographic Coverage

WatershedScope is primarily designed around watershed-analysis use cases in India, including semi-arid regions.

The underlying geospatial workflow can also operate in other regions where suitable DEM and Sentinel-2 data are available, subject to data availability, coordinate systems, and processing limitations.

License

This project is licensed under the MIT License.

Disclaimer

WatershedScope is intended for research, education, experimentation, and visualization.

It should not be used as the sole basis for:

Engineering decisions
Flood-risk certification
Government watershed boundaries
Land or property disputes
Regulatory decisions
Infrastructure design
Survey-grade measurements

Always validate analytical results against authoritative datasets and appropriate field measurements before making operational decisions.

Name		Name	Last commit message	Last commit date
backend		backend
docs/superpowers/specs		docs/superpowers/specs
frontend		frontend
.gitignore		.gitignore
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation