README.md

metadata

title: SingleViewHeigthEstimation
emoji: 🐢
colorFrom: pink
colorTo: pink
sdk: gradio
sdk_version: 6.27.0
python_version: '3.12'
app_file: app.py
pinned: false
license: mit

Single View Height Estimation

Per-pixel above-ground height from one optical aerial or satellite image, with an interactive 3D inspector for the result.

Using the Space

Upload an image, state its ground sampling distance in metres per pixel, and run. The GSD is not cosmetic — every height, slope and distance the viewer reports is derived from it, so a wrong GSD gives a plausible-looking surface with wrong numbers. A georeferenced GeoTIFF carries its own resolution; leave the field at its default to use that, or set it to override.

Optional test-time augmentation flip-averages the prediction. It is steadier on noisy input; all 8 views of each tile run in a single GPU batch, so it costs 8× the compute but far less than 8× the wall time on a large GPU.

What comes back

• DSM viewer & 3D flythrough — the same standalone viewer that ships in viewer/, inlined into the page. Orbit, first-person (F) and cinematic drone cameras; an optical / height-colormap / hillshade drape; vertical exaggeration; a movable sun with cast shadows; a 2-D map pane with optional contours; and click-to-probe, which reports a height, and on a second click a ground distance, slope and elevation profile between the two points.
• Derived rasters — the turbo height colormap and a 315°/45° hillshade. Hillshade is the honest test of a DSM: flat ground has to read as flat.
• Height16 — the height field as an 8-bit PNG carrying 16 bits of precision across its red and green channels: height_m = min + (R·256 + G) / 65535 · (max − min). This is what the viewer decodes, because a browser down-converts a true 16-bit PNG to 8 bits — which would quantise a 0–60 m scene into 0.23 m steps before anything is drawn.
• Artefacts — a zip plus the headline files: ndsm_m.npy (bit-exact float32 metres), meta.json (the full contract, including the encoding affine), terrain.glb (a self-contained binary glTF with the optical image as its base-colour texture — opens in any glTF viewer), terrain.obj + .mtl + texture.png for MeshLab or Blender, and the two rasters.
• Object classes — seg.png, the segmentation head's class per pixel on the height grid (8-bit greyscale ids; the id → name legend is meta.json classes: other, ground, low_veg, building, water, road, tree), plus a colour preview in the gallery.
• 3D objects — objects.json (infer/objects.py): trees as {x, y, h, r} (crown centre, top height, crown radius), buildings as footprint polygons with a median roof height, and water outlines. Positions are pixels on the height grid; heights and radii are metres. Trees are split into crowns by a watershed on the smoothed canopy seeded at its peaks, so touching crowns come out as separate trees. The gallery's "Detected trees, buildings and water" overlay is the check: every circle should sit on a tree. A failure in this step is reported in the status and never costs the height map.

Heights are metres above local ground (nDSM). An input without georeferencing yields a relative surface (rDSM); meta.json says which you got, and does not publish an affine transform for a scene the demo resampled.

Layout

path	what it is
app.py	the Space: inference, encodings, artefacts, and the viewer iframe
infer/, dwdata/, models/	the model and the preprocessing contract stored in the checkpoint
infer/objects.py	class map + height map → trees / buildings / water (objects.json)
tests/	CPU-only unit tests for the object step (pytest -q; no torch needed)
viz/	figure primitives, the mesh writers, and the standalone validation report
viewer/	the dual-pane DSM inspector — index.html + app.js + vendored three.js
predict_image.py	single-image CLI, writing the older phase0_viewer.html

viewer/index.html has no build step and no network dependency: opened straight off disk it behaves exactly as it does in the Space, and takes a prediction three ways — its file picker, a ?result=<directory> URL, or an inlined payload, which is how app.py hands it a result.

Running the model

The Space reads its checkpoint from /data/best.pt, so a Hugging Face bucket containing best.pt must be mounted at /data, and HF_TOKEN must be set as a Space secret for the DINOv3 encoder download.

Area mode (GeoLibre plugin)

Two API-only endpoints serve the DepthWizard GeoLibre plugin:

• /catalog — the tile repository's footprints (GeoJSON).
• /predict_area(bbox_json, tta) — "[west, south, east, north]" in WGS84. The tiles under the box are stitched onto a 0.5 m UTM grid (tiles/mosaic.py), run through the same model, and returned georeferenced: ndsm_m.tif, height_overlay.png (map overlay, corners in the result's corners_wgs84), objects.geojson (WGS84), ndsm_rgb.png + imagery.jpg (Terrain-RGB heights and their texture on the same corners, for the GeoLibre plugin's 3D view), plus the usual artefacts. A partly covered box is processed over its covered part (coverage < 1); an uncovered one returns status: "not_available".

The repository is a folder at DW_TILES_DIR (default /data/tiles, i.e. the mounted bucket): catalog.geojson + one COG per tile, built from GeoTIFFs with python -m tiles.build_catalog <tifs> --out <dir>. pytest tests/test_tiles.py covers it without torch.