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.

Methods

__init__(grid[, bc, hybrid])	The constructor for the FlowObject.
distance()	Compute the distance between each node in the flow network
drainagebasins()	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

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

drainagebasins()

Delineate drainage basins from a flow network.

Returns:

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

Return type:

GridObject

ezgetnal(k, dtype=None)

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.

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.

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