Terrain data
By default autk-map renders the map on a flat ground plane. Terrain mode replaces that plane with a heightfield built from an elevation raster, so buildings, roads, parks, and water drape over real topography instead of floating on a flat surface. This is useful whenever the relief itself carries information — hillside neighborhoods, visibility over ridges, or simply a more faithful urban context.
Terrain is driven by a single raster band. The elevation values are converted to a local-space heightfield aligned with the map origin, and the standard layer render path is swapped for the terrain render path. All existing layers, thematic coloring, and interactions keep working; they are just sampled against the heightfield.
Workflow
Terrain requires three ingredients: a vector context to render, an elevation raster to sample, and the map in an initialized state. The typical sequence is:
- Load the physical context with
autk-db.loadOsm()so the standard layers (surface,parks,water,roads,buildings) are available. - Load elevation with
autk-db.loadGeoTiff(). The GeoTIFF is stored as a compact raster table whose bands can be exported on demand. - Initialize the map and load the vector layers with
AutkMap.loadCollection(), the same as in Layers data. - Export the raster with
autk-db.getRaster(), which returns a packed rasterFeatureCollectioncontaining flat band arrays (band_1,band_2, ...) and resolution metadata. - Enable terrain with
AutkMap.enableTerrainMode(), passing the raster collection and the dot-path of the band to use as height.
| Step | Call | Purpose |
|---|---|---|
| 1 | db.loadOsm(...) | Build the physical vector context. |
| 2 | db.loadGeoTiff(...) | Ingest an elevation GeoTIFF as a raster table. |
| 3 | map.loadCollection(...) | Push each vector layer onto the map. |
| 4 | db.getRaster(tableName) | Export the raster as a renderable feature collection. |
| 5 | map.enableTerrainMode(fc, "band_1") | Swap the flat plane for a heightfield. |
Coordinate system
The elevation raster and the vector layers must share the same projected CRS so the heightfield aligns with the map origin. The default autk-db workspace uses EPSG:3395 (World Mercator). Pass coordinateFormat to loadGeoTiff() when the source GeoTIFF is in a different CRS so it is reprojected on load.
Loading the elevation raster
loadGeoTiff() ingests a GeoTIFF and stores it as a compact raster table — flat in-memory band arrays plus resolution and bbox metadata. Large rasters are downsampled automatically so browser memory stays bounded. You only need to provide a URL (or ArrayBuffer), a table name, and, when the source is not in the workspace CRS, a coordinateFormat:
The live example below loads /data/niteroi-elevation.tif with coordinateFormat: "EPSG:3395" and outputTableName: "elevation". Its complete code can be edited and executed.
A GeoTIFF can carry several bands. The compact table keeps them as band_1, band_2, and so on, so a single load can feed different terrain views (for example, elevation vs. a derived surface).
Enabling terrain
Once the raster table exists, getRaster() exports it as a packed raster FeatureCollection ready for rendering. enableTerrainMode() takes that collection and a property path pointing to the band that holds the heights:
The live example exports db.getRaster("elevation") and passes it to map.enableTerrainMode(elevation, "band_1") after loading the vector context.
After this call the flat render path is replaced with the terrain render path. Rendering samples the heightfield, and any layers loaded afterwards are also draped over the terrain. If on-demand rendering has already started, enabling terrain requests a frame automatically. The terrain resources are initialized immediately, so enableTerrainMode() is synchronous.
Order matters
Call map.init() before enableTerrainMode(). The heightfield is built relative to the map origin, which is only known once the map is initialized and at least one layer has been loaded to establish the spatial extent. Enabling terrain before any layer is loaded throws.
Returning to the flat map
Call disableTerrainMode() to release terrain resources and restore the flat render path. Existing layers remain loaded:
Use Switch to flat map in the live example below to execute map.disableTerrainMode() followed by map.resetCamera(). The same button can re-enable terrain without reloading the data.
If rendering has already started, disabling terrain requests a frame with the flat view automatically; a continuous loop is not required. To enable terrain again, call enableTerrainMode(elevation, 'band_1') with a valid raster collection, then resetCamera() to frame the terrain. There is no need to reload the vector context.
Live example
Explore the hills of Niterói's Praias da Baía region below. The example loads a bundled OSM extract and a real elevation GeoTIFF, renders the vector context, then enables terrain from band_1. Both datasets are served by this site; no Overpass query or external elevation service is needed.
The elevation raster is a lightweight 439 × 512 crop in EPSG:3395, with heights in meters, derived from the Autark gallery dataset sourced from Mapzen Terrarium elevation tiles. See dataset metadata for provenance and sampling details.
Explore and edit
Drag to navigate the map and use the mouse wheel to zoom. Use Switch to flat map to compare both modes, or edit the code and click Run. The example deliberately omits buildings so the terrain and draped roads/parks are easier to inspect.
Browser support
The example requires WebGPU. If initialization fails, check the browser support requirements.
