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.
`dependencemap`(l)	Delineate upslope area for specific locations in a DEM.
`distance`()	Compute the distance between each node in the flow network
`downstream_distance`()	Calculates the horizontal distance from outlets and ridges along the flow network in the downstream direction.
`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
`influencemap`(l)	Delineate downslope area for specific locations in a DEM.
`unravel_index`(idxs)	Unravel the provided linear indices so they can be used to index grids.
`upstream_distance`()	Calculates the horizontal distance from outlets and ridges along the flow network in the upstream direction.

Attributes

`dims`	The dimensions of the grid in the correct order for libtopotoolbox
`source_indices`	The row and column indices of the sources of each edge in the flow network.
`target_indices`	The row and column indices of the targets of each edge in the flow network.

dependencemap(l) → GridObject[source]#

Delineate upslope area for specific locations in a DEM.

Parameters:

fd (FlowObject)
l (GridObject) – logical grid

Returns:

i – logical influence grid (GRIDobj)

Return type:

GridObject

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())

downstream_distance() → GridObject[source]#

Calculates the horizontal distance from outlets and ridges along the flow network in the downstream direction.

Returns:: down_d – A new GridObject containing the distance grid
Return type:: GridObject

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:: 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[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:: 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)[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))

influencemap(l) → GridObject[source]#

Delineate downslope area for specific locations in a DEM.

Parameters:

fd (FlowObject)
l (GridObject) – logical grid

Returns:

i – logical influence grid (GRIDobj)

Return type:

GridObject

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.

unravel_index(idxs: int | ndarray) → tuple[ndarray, ...][source]#

Unravel the provided linear indices so they can be used to index grids.

Returns:

tuple of ndarray – A tuple of arrays containing the row indices and column
indices of the sources of each pixel in the idxs array.

upstream_distance() → GridObject[source]#

Calculates the horizontal distance from outlets and ridges along the flow network in the upstream direction.

Returns:: up_d – A new GridObject containing the distance grid
Return type:: GridObject

topotoolbox.FlowObject

Contents

topotoolbox.FlowObject#