demeter

A browser-based 3D atlas of Davao City's growth — see how the city has expanded over a decade through a land-cover classification model trained on Sentinel-2 satellite imagery.

Drag the time slider from 2015 to 2026 and watch built area, vegetation, agriculture, and water shift across the city; click any barangay for its growth statistics; pan a 3D terrain from sea level to Mt. Apo with OSM building extrusion.

Why

Davao has grown fast — but how fast, where, at the expense of what? Generic city dashboards don't answer this. Public satellite imagery (ESA's Sentinel-2) goes back to 2015 and is free; a properly trained land-cover model can quantify what's actually changed on the ground.

demeter is a real ML pipeline (semantic segmentation on Sentinel-2) wrapped in a 3D map: not a tile viewer with pretty data — a model trained on Davao for Davao, deployed interactively so any resident, urbanist, or researcher can explore it.

Named for Demeter — the Greek goddess of the harvest, the earth, and the cycle of seasons. Fitting for a tool that watches land change over time.

Status

🚧 In design / pre-alpha. Public repo is up so the design can iterate in the open. Implementation begins shortly.

v1 Scope

Coverage

• Davao City region (administrative boundary + buffer)
• Annual Sentinel-2 composites from 2015 to 2026 (cloud-masked, median-composited)

Model

• Land-cover semantic segmentation: built / vegetation / water / agriculture / bare
• UNet-style architecture trained with segmentation_models_pytorch
• Trained on a hand-labeled tile set + transfer-learned from a public LULC dataset (e.g., ESA WorldCover)

Frontend

• 3D terrain from Copernicus DEM
• OSM building extrusion layer
• Time slider (2015 → 2026) animating the classified raster overlay
• Click any barangay → growth stats: built area Δ, vegetation Δ, agriculture Δ
• Click any building → OSM details
• Layer toggles: classified raster, NDVI heat, building extrusion, barangay choropleth

Deferred to later: forecasting (predicting future expansion), other PH cities, alternate sensors (Landsat, Sentinel-1 radar), per-pixel uncertainty, change-detection alerts.

Stack

Backend — Python

• Python 3.12+ managed with uv
• FastAPI — API + analytics endpoints
• rasterio + xarray + rioxarray — raster I/O & processing
• sentinelhub-py or stackstac via Microsoft Planetary Computer STAC — imagery access
• PyTorch + segmentation_models_pytorch — land-cover model
• geopandas + shapely — vector ops (barangay aggregation)
• titiler — Cloud-Optimized GeoTIFF tile serving

Frontend — TypeScript / React

• Vite — dev server & bundling
• MapLibre GL JS — base map
• deck.gl — 3D terrain, building extrusion, raster overlays, time-animated layers
• Zustand — state
• Tailwind CSS — UI
• Vitest — tests
• Biome — lint + format

Architecture

A two-phase setup:

Offline pipeline (run once, re-run yearly):

1. Pull Sentinel-2 imagery for Davao region from Planetary Computer STAC
2. Cloud-mask + median-composite each year into a Cloud-Optimized GeoTIFF
3. Run the segmentation model over each composite → write classified COGs
4. Aggregate per-barangay statistics → JSON

Live serving:

• titiler serves classified COGs as web-mercator tiles
• FastAPI serves: barangay stats endpoint, model metadata, on-demand single-tile classification
• Static frontend hosted on Cloudflare Pages
• COG tiles + analytics on Render / Fly.io (or self-hosted)

Install (when v1 ships)

Live demo at demeter.<TBD>.dev.

Self-host:

docker compose up

Development

# Backend
cd backend
uv sync
uv run uvicorn demeter.api:app --reload

# Frontend
cd frontend
pnpm install && pnpm dev

(Once scaffolded.)

License

MIT