Skip to content

Terrain

geobn.terrain computes terrain derivatives from a source of elevations in metres. Each function returns a DerivedSource, which is passed to set_input() like any other source:

dem = geobn.WCSSource(
    url="https://hoydedata.no/arcgis/services/las_dtm_somlos/ImageServer/WCSServer",
    layer="las_dtm",
    version="1.0.0",
    valid_range=(-500.0, 9000.0),
    cache_dir="cache/",
)

bn.set_input("slope_angle", geobn.terrain.slope(dem))
bn.set_input("aspect",      geobn.terrain.aspect(dem))
bn.set_input("roughness",   geobn.terrain.roughness(dem, size=5))
bn.set_input("tpi",         geobn.terrain.tpi(dem, size=9))

The elevations are aligned to the reference grid before the derivative is taken, so the result describes the terrain at the grid's resolution. A slope computed on a 200 m grid is gentler than one computed on the 10 m DTM behind it and then aggregated.

Slope and aspect

Slope and aspect come from the elevation gradient. The distance between neighbouring pixel centres is measured along the WGS84 ellipsoid, so the result is correct on a grid in degrees, where a pixel is narrower east–west than north–south away from the equator, and on a projected grid, whatever its scale factor. The distances and directions are measured exactly on a lattice of up to 65 × 65 pixels and interpolated linearly in between.

Aspect is the compass bearing the terrain faces, the direction of steepest descent, in degrees clockwise from true north. On a grid whose columns do not point east, such as a UTM zone away from its central meridian, a rotated grid or a polar grid, the gradient is turned into true east and north components before the bearing is taken.

A pixel next to a NaN pixel uses a one-sided difference instead of the central one. The edge of the data, such as a coastline in a land DTM, therefore does not appear as a cliff. A pixel with no valid neighbour along a row or a column is NaN.

Level ground has no aspect. aspect() returns NaN there by default. Pass flat= to give such pixels a value of their own, for instance -1.0, and a state in the discretization.

Roughness and TPI

Roughness and the topographic position index work on a square window of size × size pixels, and ignore NaN pixels within it. Roughness is the largest elevation difference in the window. TPI is the pixel's elevation minus the mean of the other pixels in the window: positive on ridges and hilltops, negative in valleys and hollows. Both follow the definitions used by GDAL's gdaldem.

Function reference

slope

slope(source, units='degrees')

Slope of the terrain.

Parameters

source: Elevation in metres. units: "degrees" (default), from 0 to 90, or "percent", the rise over the run times 100.

Returns

DerivedSource NaN where the elevation is NaN, or where a pixel has no valid neighbour along a row or a column.

aspect

aspect(source, flat=np.nan)

Compass direction the terrain faces, i.e. of steepest descent.

Parameters

source: Elevation in metres. flat: Value for pixels where the terrain is exactly level, which face no direction. The default NaN treats them as NoData. Pass a value outside 0–360, such as -1.0, to give them a state of their own in the discretization.

Returns

DerivedSource Degrees clockwise from true north, from 0 up to 360: 0 faces north, 90 east, 180 south and 270 west. NaN where the elevation is NaN, or where a pixel has no valid neighbour along a row or a column.

roughness

roughness(source, size=3)

Largest elevation difference within a window around each pixel.

This is the maximum minus the minimum elevation over a size × size window centred on the pixel, the definition used by GDAL's gdaldem roughness (Wilson et al. 2007).

Parameters

source: Elevation in metres. size: Window width in pixels: an odd integer, at least 3.

Returns

DerivedSource In the units of the elevation. NaN where the elevation is NaN. NaN pixels within the window are ignored.

tpi

tpi(source, size=3)

Topographic position index: elevation relative to its surroundings.

This is the pixel's elevation minus the mean elevation of the other pixels in a size × size window around it, as in GDAL's gdaldem TPI (Weiss 2001). Positive values mark ridges and hilltops, negative values valleys and hollows, and values near zero flat ground or an even slope.

Parameters

source: Elevation in metres. size: Window width in pixels: an odd integer, at least 3. A wider window picks out larger landforms.

Returns

DerivedSource In the units of the elevation. NaN where the elevation is NaN or no other pixel in the window has data. NaN pixels within the window are ignored.