topotoolbox.GridObject#

class topotoolbox.GridObject[source]#

Bases: object

A class containing all information of a Digital Elevation Model (DEM).

__init__() → None[source]#: Initialize a GridObject instance.

Methods

`__init__`()	Initialize a GridObject instance.
`curvature`([ctype, meanfilt])	curvature returns the second numerical derivative (curvature) of a digital elevation model.
`dilate`([size, footprint, structure])	A simple wrapper around th scipy.ndimage.grey_dilation function, that also handles NaNs in the input GridObject.
`erode`([size, footprint, structure])	Apply a morphological erosion operation to the GridObject.
`evansslope`([partial_derivatives, mode, modified])	Evans method fits a second-order polynomial to 3x3 subgrids.
`excesstopography`([threshold, method])	Compute the two-dimensional excess topography using the specified method.
`fillsinks`([bc, hybrid])	Fill sinks in the digital elevation model (DEM).
`filter`([method, kernelsize])	The function filter is a wrapper around various image filtering algorithms.
`gradient8`([unit, multiprocessing])	Compute the gradient of a digital elevation model (DEM) using an 8-direction algorithm.
`identifyflats`([raw, output])	Identifies flats and sills in a digital elevation model (DEM).
`info`()	Prints all variables of a GridObject.
`reproject`(crs[, resolution, resampling])	Reproject GridObject to a new coordinate system.
`show`([cmap])	Display the GridObject instance as an image using Matplotlib.

Attributes

`columns`	The size of the second dimension of the grid
`rows`	The size of the first dimension of the grid
`shape`	Tuple of grid dimensions

property columns#: The size of the second dimension of the grid

curvature(ctype='profc', meanfilt=False) → GridObject[source]#

curvature returns the second numerical derivative (curvature) of a digital elevation model. By default, curvature returns the profile curvature (profc).

Parameters:

ctype (str, optional) – What type of curvature will be computed, by default ‘profc’ - ‘profc’ : profile curvature [m^(-1)], - ‘planc’ : planform curvature [m^(-1))], - ‘tangc’ : tangential curvature [m^(-1)], - ‘meanc’ : mean curvature [m^(-1)], - ‘total’ : total curvature [m^(-2)]
meanfilt (bool, optional) – True if a mean filter will be applied before comuting the curvature, by default False

Returns:

A GridObject storing the computed values.

Return type:

GridObject

Raises:

ValueError – If wrong ctype has been used.

Examples

>>> dem = topotoolbox.load_dem('tibet')
>>> curv = dem.curvature()
>>> curv.show()

dilate(size: tuple | None = None, footprint: ndarray | None = None, structure: ndarray | None = None) → GridObject[source]#

A simple wrapper around th scipy.ndimage.grey_dilation function, that also handles NaNs in the input GridObject. Either size, footprint or structure has to be passed to this function. If nothing is provided, the function will raise an error.

sizetuple of ints, optional: A tuple of ints containing the shape of the structuring element. Only needed if neither footprint nor structure is provided. Will result in a full and flat structuring element. Defaults to None
footprintnp.ndarray of ints, optional: A array defining the footprint of the erosion operation. Non-zero elements define the neighborhood over which the erosion is applied. Defaults to None
structurenp.ndarray of ints, optional: A array defining the structuring element used for the erosion. This defines the connectivity of the elements. Defaults to None

Returns:: A GridObject storing the computed values.
Return type:: GridObject
Raises:: ValueError – If size, structure and footprint are all None.

erode(size: tuple | None = None, footprint: ndarray | None = None, structure: ndarray | None = None) → GridObject[source]#

Apply a morphological erosion operation to the GridObject. Either size, footprint or structure has to be passed to this function. If nothing is provided, the function will raise an error.

Parameters:

size (tuple of ints) – A tuple of ints containing the shape of the structuring element. Only needed if neither footprint nor structure is provided. Will result in a full and flat structuring element. Defaults to None
footprint (np.ndarray of ints, optional) – A array defining the footprint of the erosion operation. Non-zero elements define the neighborhood over which the erosion is applied. Defaults to None
structure (np.ndarray of ints, optional) – A array defining the structuring element used for the erosion. This defines the connectivity of the elements. Defaults to None

Returns:

A GridObject storing the computed values.

Return type:

GridObject

Raises:

ValueError – If size, structure and footprint are all None.

evansslope(partial_derivatives: bool = False, mode: str = 'nearest', modified: bool = False) → GridObject | Tuple[GridObject, GridObject][source]#

Evans method fits a second-order polynomial to 3x3 subgrids. The parameters of the polynomial are the partial derivatives which are used to calculate the surface slope = sqrt(Gx**2 + Gy**2).

Evans method approximates the surface by regression surfaces. Gradients are thus less susceptible to noise in the DEM.

Parameters:

mode (str, optional) – The mode parameter determines how the input DEM is extended beyond its boundaries: [‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’, ‘grid-mirror’, ‘grid-constant’, ‘grid-wrap’]. See scipy.ndimage.convolve for more information, by default ‘nearest’
modified (bool, optional) – If True, the surface is weakly smoothed before gradients are calculated (see Shary et al., 2002), by default False
partial_derivatives (bool, optional) – If True, both partial derivatives [fx, fy] will be returned as GridObjects instead of just the evansslope, by default False

Returns:

A GridObject containing the computed evansslope data.

Return type:

GridObject

excesstopography(threshold: float | int | ndarray | GridObject = 0.2, method: str = 'fsm2d') → GridObject[source]#

Compute the two-dimensional excess topography using the specified method.

Parameters:

threshold (float, int, GridObject, or np.ndarray, optional) – Threshold value or array to determine slope limits, by default 0.2. If a float or int, the same threshold is applied to the entire DEM. If a GridObject or np.ndarray, it must match the shape of the DEM.
method (str, optional) –
Method to compute the excess topography, by default ‘fsm2d’. Options are:
- ’fsm2d’: Uses the fast sweeping method.
- ’fmm2d’: Uses the fast marching method.

Returns:

A new GridObject with the computed excess topography.

Return type:

GridObject

Raises:

ValueError – If method is not one of [‘fsm2d’, ‘fmm2d’]. If threshold is an np.ndarray and doesn’t match the shape of the DEM.
TypeError – If threshold is not a float, int, GridObject, or np.ndarray.

fillsinks(bc: ndarray | GridObject | None = None, hybrid: bool = True) → GridObject[source]#

Fill sinks in the digital elevation model (DEM).

Parameters:

bc (ndarray or GridObject, optional) – Boundary conditions for sink filling. bc should be an array of np.uint8 that matches the shape of the DEM. Values of 1 indicate pixels that should be fixed to their values in the original DEM and values of 0 indicate pixels that should be filled.
hybrid (bool, optional) – Should hybrid reconstruction algorithm be used? Defaults to True. Hybrid reconstruction is faster but requires additional memory be allocated for a queue.

Returns:

The filled DEM.

Return type:

GridObject

filter(method: str = 'mean', kernelsize: int = 3) → GridObject[source]#

The function filter is a wrapper around various image filtering algorithms. Only filters with rectangular kernels of uneven dimensions are supported.

Parameters:

method (str, optional) – Which method will be used to filter the DEM: [‘mean’, ‘average’, ‘median’, ‘sobel’, ‘scharr’, ‘wiener’, ‘std’], by default ‘mean’
kernelsize (int, optional) – Size of the kernel that will be applied. Note that [‘sobel’, ‘scharr’] require that the kernelsize is 3, by default 3

Returns:

The filtered DEM as a GridObject.

Return type:

GridObject

Raises:

ValueError – If the kernelsize does not match the requirements of this function or the selected method is not implemented in the function.

gradient8(unit: str = 'tangent', multiprocessing: bool = True)[source]#

Compute the gradient of a digital elevation model (DEM) using an 8-direction algorithm.

Parameters:

unit (str, optional) – The unit of the gradient to be calculated. Options are: - ‘tangent’ : Calculate the gradient as a tangent (default). - ‘radian’ : Calculate the gradient in radians. - ‘degree’ : Calculate the gradient in degrees. - ‘sine’ : Calculate the gradient as the sine of the angle. - ‘percent’ : Calculate the gradient as a percentage.
multiprocessing (bool, optional) – If True, use multiprocessing for computation. Default is True.

Returns:

A new GridObject with the calculated gradient.

Return type:

GridObject

identifyflats(raw: bool = False, output: list[str] | None = None) → tuple[source]#

Identifies flats and sills in a digital elevation model (DEM).

Parameters:

raw (bool, optional) – If True, returns the raw output grid as np.ndarray. Defaults to False.
output (list of str, optional) – List of strings indicating desired output types. Possible values are ‘sills’, ‘flats’. Order of inputs in list are irrelevant, first entry in output will always be sills. Defaults to [‘sills’, ‘flats’].

Returns:

A tuple containing copies of the DEM with identified flats and/or sills.

Return type:

tuple

Notes

Flats are identified as 1s, sills as 2s, and presills as 5s (since they are also flats) in the output grid. Only relevant when using raw=True.

info() → None[source]#: Prints all variables of a GridObject.

reproject(crs: CRS, resolution: float | None = None, resampling: Resampling = Resampling.bilinear)[source]#

Reproject GridObject to a new coordinate system.

Parameters:

crs (rasterio.CRS) – Target coordinate system
resolution (float, optional) – Target resolution. If one is not provided, a resolution that approximately matches that of the source coordinate system will be used.
resampling (rasterio.enums.Resampling, optional) – Resampling method. The default is bilinear resampling.

Returns:

The reprojected data.

Return type:

GridObject

property rows#: The size of the first dimension of the grid

property shape#: Tuple of grid dimensions

show(cmap='terrain') → None[source]#

Display the GridObject instance as an image using Matplotlib.

Parameters:: cmap (str, optional) – Matplotlib colormap that will be used in the plot.

topotoolbox.GridObject

Contents

topotoolbox.GridObject#