---
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.