README.md

metadata

title: DepthWizard
emoji: 🏔️
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.15.0
app_file: app.py
pinned: false
license: mit

DepthWizard — 3D Surface Reconstruction & Elevation Extraction from Monocular Remote Sensing

---

📌 Overview

DepthWizard is an end-to-end AI and geospatial engine designed to derive dense, accurate Digital Surface Models (DSMs) and interactive 3D terrain reconstructions from single-view optical remote sensing imagery.

By bridging state-of-the-art self-supervised Vision Transformers (Depth Anything V2) with physical geospatial geodesy, shadow cue geometry (M4), and ground control point (GCP) / SRTM DEM anchoring (M2), DepthWizard provides continuous metric 3D elevation in seconds without requiring expensive multi-view stereo passes or airborne LiDAR flights.

---

🚀 Key Features

• Monocular Depth Backbone: High-resolution spatial disparity estimation using DINOv2 Vision Transformers.
• Metric Calibration Engine ($H = a \cdot D + b$): Closed-form Ordinary Least Squares (OLS) solver mapping relative disparity into physical elevation (meters) via sparse GCP anchors or SRTM DEM percentile anchoring.
• Zero-Fabrication Safety Contract: If no geospatial reference or elevation anchors are provided, the system strictly outputs normalized relative surface models ($\text{rDSM} \in [0, 1]$), preventing hallucinated metric measurements.
• Invariant Shadow Geometry: Employs solar azimuth and elevation angles ($\theta$) to derive physical building relief ($h = L \cdot \tan\theta$) and validate structural vertical boundaries.
• 60 FPS 3D WebGL Visualization: Real-time Three.js viewport featuring interactive orbit, cinematic flythrough, live raycast elevation cursor HUD, dynamic topographic transects, and surface overlays (RGB / Slope / Confidence / Error Map).
• Standard GIS Export: Native export of 32-bit Float GeoTIFFs preserving spatial reference systems (CRS) and affine geotransforms for seamless use in QGIS and ArcGIS.

---

🏗️ System Architecture

                                  [ Optical Image ]
                               (GeoTIFF / PNG / JPG)
                                         │
                 ┌───────────────────────┴───────────────────────┐
                 ▼                                               ▼
     [ Depth Anything V2 ]                            [ Metadata & Shadows ]
   (DINOv2 Feature Encoder)                         (CRS, GSD, Solar Geometry)
                 │                                               │
                 ▼                                               ▼
      [ Disparity Map D(x,y) ]                         [ Ground Anchors (GCP/DEM) ]
                 └───────────────────────┬───────────────────────┘
                                         ▼
                             [ Metric Calibration ]
                           H(x,y) = a · D(x,y) + b
                                         │
                 ┌───────────────────────┴───────────────────────┐
                 ▼                                               ▼
       [ 32-bit Float GeoTIFF ]                       [ Three.js 3D WebGL ]
         (QGIS / ArcGIS DSM)                        (60 FPS Flythrough & HUD)

---

💻 Tech Stack

• Deep Learning: PyTorch, Hugging Face Transformers, Depth Anything V2, DINOv2
• Geospatial & Remote Sensing: GDAL, Rasterio, PROJ, NumPy, SciPy, OpenCV, Shapely
• Backend API: FastAPI (Async ASGI Engine), Uvicorn, Pydantic
• Frontend & 3D: HTML5 Canvas, Vanilla CSS3, Three.js (WebGL), OrbitControls

---

⚡ Quickstart Guide

1. Prerequisites & Installation

Clone the repository and install dependencies:

git clone https://github.com/mehersoni/DepthWizard.git
cd DepthWizard

python -m venv venv
# On Windows:
.\venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate

pip install -r requirements.txt

2. Launching the Live 3D Web Console

Start the FastAPI application:

python api_server.py

Open your browser and navigate to:

• Landing Page & Console: http://127.0.0.1:8000/index.html
• Interactive 3D Demo: http://127.0.0.1:8000/demo.html
• Advanced M6 Elevation Console: http://127.0.0.1:8000/m6_dashboard.html

---

📊 Scientific Verification & Benchmarks

The system has been evaluated against the ISPRS Potsdam Urban Benchmark (high-resolution true orthophotos paired with airborne LiDAR ground truth):

Metric	Uncalibrated rDSM	SRTM Anchored	Sparse GCP Calibrated (4 pts)
Correlation ($R^2$)	—	0.81	0.92
Mean Absolute Error (MAE)	Scale-Agnostic	3.72 m	0.68 m
Processing Latency	< 2.5s (CPU)	< 2.8s (CPU)	< 2.4s (CPU) / < 250ms (GPU)

---

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.