topotoolbox.FlowObject

class topotoolbox.FlowObject(grid: GridObject, bc: ndarray | GridObject | None = None, hybrid: bool = True)

Bases: object

A class containing containing (water-) flow information about a given digital elevation model (DEM).

__init__(grid: GridObject, bc: ndarray | GridObject | None = None, hybrid: bool = True)

The constructor for the FlowObject. Takes a GridObject as input, computes flow direction information and saves them as an FlowObject.

Parameters:

• grid (GridObject) – The GridObject that will be the basis of the computation.

• 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 to fill sinks? Defaults to True. Hybrid reconstruction is faster but requires additional memory be allocated for a queue.

Notes

Large intermediate arrays are created during the initialization process, which could lead to issues when using very large DEMs.

Example

>>> dem = topotoolbox.load_dem('perfectworld')
>>> flow = topotoolbox.FlowObject(dem)

Methods

__init__(grid[, bc, hybrid])	The constructor for the FlowObject.
distance()	Compute the distance between each node in the flow network
drainagebasins([outlets])	Delineate drainage basins from a flow network.
ezgetnal(k[, dtype])	Retrieve a node attribute list
flow_accumulation([weights])	Computes the flow accumulation for a given flow network using optional weights.
flowpathextract(idx)	Extract linear indices of a single flowpath in a DEM

Attributes

dims	The dimensions of the grid in the correct order for libtopotoolbox

property dims

The dimensions of the grid in the correct order for libtopotoolbox

distance()

Compute the distance between each node in the flow network

Returns:

An array (edge attribute list) with the interpixel distance. This will be either cellsize or sqrt(2)*cellsize

Return type:

np.ndarray

Example

>>> dem = tt3.load_dem('bigtujunga')
>>> fd = tt3.FlowObject(dem)
>>> print(fd.distance())

drainagebasins(outlets=None)

Delineate drainage basins from a flow network.

Parameters:

outlets (np.ndarray) – An array containing the linear indices of the outlet nodes in column major (‘F’) order.

Returns:

An integer-valued GridObject with a unique label for each drainage basin.

Return type:

GridObject

Example

>>> dem = topotoolbox.load_dem('perfectworld')
>>> fd = topotoolbox.FlowObject(dem)
>>> basins = fd.drainagebasins()
>>> basins.shufflelabel().plot(cmap="Pastel1",interpolation="nearest")

ezgetnal(k, dtype=None) → GridObject | ndarray

Retrieve a node attribute list

Parameters:

k (GridObject or np.ndarray or scalar) – The object from which node values will be extracted. If k is a GridObject or an ndarray with the same shape as this FlowObject, then a copy is returned. If it is a scalar, an ndarray with the appropriate shape, filled with k, is returned.

Return type:

GridObject or np.ndarray

Raises:

ValueError – The supplied input is not aligned with the FlowObject.

Example

>>> dem = topotoolbox.load_dem('bigtujunga)
>>> fd = tt3.FlowObject(dem)
>>> fd.ezgetnal(dem).plot()

flow_accumulation(weights: ndarray | float = 1.0)

Computes the flow accumulation for a given flow network using optional weights. The flow accumulation represents the amount of flow each cell receives from its upstream neighbors.

Parameters:

weights (np.ndarray | float, optional) – An array of the same shape as the flow grid representing weights for each cell, or a constant float value used as the weight for all cells. If weights=1.0 (default), the flow accumulation is unweighted. If an ndarray is provided, it must match the shape of the flow grid., by default 1.0

Returns:

A new GridObject containing the flow accumulation grid.

Return type:

GridObject

Raises:

ValueError – If the shape of the weights array does not match the shape of the flow network grid.

Example

>>> dem = topotoolbox.load_dem('perfectworld')
>>> fd = topotoolbox.FlowObject(dem)
>>> acc = fd.flow_accumulation()
>>> acc.plot(cmap='Blues',norm="log")

flowpathextract(idx: int)

Extract linear indices of a single flowpath in a DEM

The flow path downstream of idx is extracted from the flow directions recorded in FlowObject.

Parameters:

idx (int) – The column-major linear index of the starting pixel of the flowpath.

Returns:

An array containing column-major linear indices into the DEM identifying the flow path.

Return type:

np.ndarray

Example

>>> dem = tt3.load_dem('bigtujunga')
>>> fd = tt3.FlowObject(dem)
>>> print(fd.flowpathextract(12345))