topotoolbox.FlowObject#
- class topotoolbox.FlowObject(grid: GridObject, bc: ndarray | GridObject | None = None, hybrid: bool = True)[source]#
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)[source]#
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
unravel_index
(idxs)Unravel the provided linear indices so they can be used to index grids.
Attributes
The dimensions of the grid in the correct order for libtopotoolbox
The row and column indices of the sources of each edge in the flow network.
The row and column indices of the targets of each edge in the flow network.
- property dims#
The dimensions of the grid in the correct order for libtopotoolbox
- distance()[source]#
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)[source]#
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:
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 [source]#
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)[source]#
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:
- 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)[source]#
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))
- property source_indices: tuple[ndarray, ...]#
The row and column indices of the sources of each edge in the flow network.
- Returns:
tuple of ndarray – A tuple of arrays containing the row indices and column
indices of the sources of each edge in the flow
network. Each of these arrays is an edge attribute lists and
have a length equal to the number of edges in the flow
network. This tuple of arrays is suitable for indexing
GridObjects or arrays shaped like the GridObject from which
this FlowObject was derived.
- property target_indices: tuple[ndarray, ...]#
The row and column indices of the targets of each edge in the flow network.
- Returns:
tuple of ndarray – A tuple of arrays containing the row indices and column
indices of the sources of each edge in the flow
network. Each of these arrays is an edge attribute lists and
have a length equal to the number of edges in the flow
network. This tuple of arrays is suitable for indexing
GridObjects or arrays shaped like the GridObject from which
this FlowObject was derived.