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