Skip to content
DepthWizardDepthWizard

System overview

DepthWizard can be deployed two ways. Both run the same inference engine.

Hosted path: what the web app uses

Section titled “Hosted path: what the web app uses”
BrowserReact 19 SPAMantine UI · zustand statethree.js / R3F viewportmesh · shaders · post-FXWeb Workers (comlink)terrain mesh · analysisIndexedDB · recent projectsSame-origin proxyserver/serve.mjs · or Vercel functions/hf-space/*injects HF_TOKEN · streams SSE/overpass/<mirror>allow-listed · ≤16 KB · 55 sfetchHugging Face SpaceGradio · ZeroGPU (private)POST /gradio_api/uploadPOST /gradio_api/call/predictGET …/predict/{id} (SSE)GET /gradio_api/file=…Bearer tokenOverpass API mirrorsOpenStreetMap roads · buildings · POIsTerrarium elevation tilesAWS open data · DEM anchoringfetched directly by the browser
The browser only talks to its own origin. A thin proxy adds the Hugging Face token on the server side and streams responses from a private Gradio Space running on ZeroGPU. OpenStreetMap overlays go through an allow-listed Overpass relay, and elevation tiles for DEM anchoring are fetched directly from AWS open data.
Component Technology Responsibility
Web app React 19, TypeScript, Vite 8, Mantine 9, three.js / React Three Fiber Upload, 3D viewer, analysis, validation, scenarios, export. Heavy work runs in Web Workers
Proxy Node (server/serve.mjs) or Vercel functions (api/*.js) Same-origin routes /hf-space/* and /overpass/*. Keeps HF_TOKEN off the client
Inference Space Gradio on Hugging Face ZeroGPU (private) Upload, queue, GPU inference (@spaces.GPU, 45 s, or 120 s with TTA), result files
Overpass mirrors OpenStreetMap Roads, buildings and facilities for georeferenced scenes
Terrarium tiles AWS open data Coarse terrain for in-browser DEM anchoring

There is no database, job queue or file store in this path. The Gradio queue handles scheduling, results are fetched as files, and projects are saved client-side (.dwproj files and IndexedDB).

Self-hosted path: FastAPI service

Section titled “Self-hosted path: FastAPI service”
Clientstatic UI at /three.js viewercurl / scriptsFastAPI · uvicornserve/app.pyPOST /api/predictGET /api/job/{id}GET /api/result/{id}/{file}POST /api/reference/{id}GET /api/report/{id}Job runnerBackgroundTasks · model lockwindowed mode > 40 MPRuntimeONNX Runtime (CUDA/CPU) or PyTorchJobs directoryDW_JOBS_DIRGeoTIFF · NPY · GLB · metaDEM sourcesCopernicus GLO-30 · SRTM · cache
The FastAPI service runs jobs in the background under a model lock, writes each product to a job directory and serves results, reports and a bundled three.js viewer. It runs on ONNX Runtime (CUDA or CPU) or on a PyTorch checkpoint.

Use it for batch processing, air-gapped machines, very large scenes (windowed mode above 40 MP), absolute DSMs with a choice of DEM, and validation against a reference GeoTIFF on the server.

Comparison

Section titled “Comparison”
Hosted (Space + proxy) Self-hosted (FastAPI)
GPU ZeroGPU quota of the token’s account Your hardware, or CPU with ONNX
Input limit 512 MB upload in the app Limited by disk and RAM; windowed above 40 MP
Absolute DSM In-browser anchoring to Terrarium tiles or a DEM file Server-side, Copernicus / SRTM / NASADEM / CartoDEM / GCPs
Outputs ndsm_m.npy, meta.json, terrain.glb, previews Full GeoTIFF set, NPY, GLB/OBJ, HTML report
Auth HF_TOKEN in the proxy None built in (put it behind your own gateway)
Hosted request lifecycleSequence diagram from upload to rendered mesh.
Self-hosted serviceJob state machine, runtime options and directory layout.
API referenceGradio /predict and every FastAPI endpoint.
DeploymentEnvironment variables, Docker, Vercel and the Space.