Hydrological Analysis

• AverageFlowpathSlope
• AverageUpslopeFlowpathLength
• Basins
• BreachDepressions
• BreachDepressionsLeastCost
• BreachSingleCellPits
• BurnStreamsAtRoads
• D8FlowAccumulation
• D8MassFlux
• D8Pointer
• DInfFlowAccumulation
• DInfMassFlux
• DInfPointer
• DepthInSink
• DownslopeDistanceToStream
• DownslopeFlowpathLength
• ElevationAboveStream
• ElevationAboveStreamEuclidean
• Fd8FlowAccumulation
• Fd8Pointer
• FillBurn
• FillDepressions
• FillDepressionsPlanchonAndDarboux
• FillDepressionsWangAndLiu
• FillSingleCellPits
• FindNoFlowCells
• FindParallelFlow
• FlattenLakes
• FloodOrder
• FlowAccumulationFullWorkflow
• FlowLengthDiff
• Hillslopes
• ImpoundmentSizeIndex
• InsertDams
• Isobasins
• JensonSnapPourPoints
• LongestFlowpath
• LowPointsOnHeadwaterDivides
• MaxUpslopeFlowpathLength
• MdInfFlowAccumulation
• NumInflowingNeighbours
• RaiseWalls
• Rho8Pointer
• Sink
• SnapPourPoints
• StochasticDepressionAnalysis
• StrahlerOrderBasins
• Subbasins
• TraceDownslopeFlowpaths
• UnnestBasins
• UpslopeDepressionStorage
• Watershed

AverageFlowpathSlope

This tool calculates the average slope gradient (i.e. slope steepness in degrees) of the flowpaths that pass through each grid cell in an input digital elevation model (DEM). The user must specify the name of a DEM raster (--dem). It is important that this DEM is pre-processed to remove all topographic depressions and flat areas using a tool such as BreachDepressions. Several intermediate rasters are created and stored in memory during the operation of this tool, which may limit the size of DEM that can be processed, depending on available system resources.

See Also: AverageUpslopeFlowpathLength, BreachDepressions

Parameters:

Python function:

wbt.average_flowpath_slope(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AverageFlowpathSlope -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/07/2017

Last Modified: 17/01/2019

AverageUpslopeFlowpathLength

This tool calculates the average length of the flowpaths that run through each grid cell (in map horizontal units) in in an input digital elevation model (DEM). The user must specify the name of a DEM raster (--dem). It is important that this DEM is pre-processed to remove all topographic depressions and flat areas using a tool such as BreachDepressions. Several intermediate rasters are created and stored in memory during the operation of this tool, which may limit the size of DEM that can be processed, depending on available system resources.

See Also: MaxUpslopeFlowpathLength, AverageFlowpathSlope, BreachDepressions

Parameters:

Python function:

wbt.average_upslope_flowpath_length(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AverageUpslopeFlowpathLength -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/07/2017

Last Modified: 17/01/2019

Basins

This tool can be used to delineate all of the drainage basins contained within a local drainage direction, or flow pointer raster (--d8_pntr), and draining to the edge of the data. The flow pointer raster must be derived using the D8Pointer tool and should have been extracted from a digital elevation model (DEM) that has been hydrologically pre-processed to remove topographic depressions and flat areas, e.g. using the BreachDepressions tool. By default, the flow pointer raster is assumed to use the clockwise indexing method used by WhiteboxTools:

If the pointer file contains ESRI flow direction values instead, the --esri_pntr parameter must be specified.

The Basins and Watershed tools are similar in function but while the Watershed tool identifies the upslope areas that drain to one or more user-specified outlet points, the Basins tool automatically sets outlets to all grid cells situated along the edge of the data that do not have a defined flow direction (i.e. they do not have a lower neighbour). Notice that these edge outlets need not be situated along the edges of the flow-pointer raster, but rather along the edges of the region of valid data. That is, the DEM from which the flow-pointer has been extracted may incompletely fill the containing raster, if it is irregular shaped, and NoData regions may occupy the peripherals. Thus, the entire region of valid data in the flow pointer raster will be divided into a set of mutually exclusive basins using this tool.

See Also: Watershed, D8Pointer, BreachDepressions

Parameters:

Python function:

wbt.basins(
    d8_pntr, 
    output, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Basins -v --wd="/path/to/data/" ^
--d8_pntr='d8pntr.tif' -o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 18/10/2019

BreachDepressions

This tool can be used to remove the depressions in a digital elevation model (DEM), a common requirement of spatial hydrological operations such as flow accumulation and watershed modelling. The tool based on on the efficient hybrid depression breaching algorithm described by Lindsay (2016). It uses a breach-first, fill-second approach to resolving continous flowpaths through depressions.

Notice that when the input DEM (--dem) contains deep, single-cell pits, it can be useful to raise the pits elevation to that of the lowest neighbour (--fill_pits), to avoid the creation of deep breach trenches. Deep pits can be common in DEMs containing speckle-type noise. This option, however, does add slightly to the computation time of the tool.

The user may optionally (--flat_increment) override the default value applied to increment elevations on flat areas (often formed by the subsequent depression filling operation). The default value is dependent upon the elevation range in the input DEM and is generally a very small elevation value (e.g. 0.001). It may be necessary to override the default elevation increment value in landscapes where there are extensive flat areas resulting from depression filling (and along breach channels). Values in the range 0.00001 to 0.01 are generally appropriate. increment values that are too large can result in obvious artifacts along flattened sites, which may extend beyond the flats, and values that are too small (i.e. smaller than the numerical precision) may result in the presence of grid cells with no downslope neighbour in the output DEM. The output DEM will always use 64-bit floating point values for storing elevations because of the need to precisely represent small elevation differences along flats. Therefore, if the input DEM is stored at a lower level of precision (e.g. 32-bit floating point elevations), this may result in a doubling of the size of the DEM.

In comparison with the BreachDepressionsLeastCost tool, this breaching method often provides a less satisfactory, higher impact, breaching solution and is often less efficient. It has been provided to users for legacy reasons and it is advisable that users try the BreachDepressionsLeastCost tool to remove depressions from their DEMs first. The BreachDepressionsLeastCost tool is particularly well suited to breaching through road embankments. Nonetheless, there are applications for which full depression filling using the FillDepressions tool may be preferred.

Reference:

Lindsay JB. 2016. Efficient hybrid breaching-filling sink removal methods for flow path enforcement in digital elevation models. Hydrological Processes, 30(6): 846–857. DOI: 10.1002/hyp.10648

See Also: BreachDepressionsLeastCost, FillDepressions, FillSingleCellPits

Parameters:

Python function:

wbt.breach_depressions(
    dem, 
    output, 
    max_depth=None, 
    max_length=None, 
    flat_increment=None, 
    fill_pits=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BreachDepressions -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 24/11/2019

BreachDepressionsLeastCost

This tool can be used to perform a type of optimal depression breaching to prepare a digital elevation model (DEM) for hydrological analysis. Depression breaching is a common alternative to depression filling (FillDepressions) and often offers a lower-impact solution to the removal of topographic depressions. This tool implements a method that is loosely based on the algorithm described by Lindsay and Dhun (2015), furthering the earlier algorithm with efficiency optimizations and other significant enhancements. The approach uses a least-cost path analysis to identify the breach channel that connects pit cells (i.e. grid cells for which there is no lower neighbour) to some distant lower cell. Here, the cost of a breach path is determined by the amount of elevation lowering needed to cut the breach channel through the surrounding topography.

The user must specify the name of the input DEM file (--dem), the output breached DEM file (--output), the maximum search window radius (--radius), the optional maximum breach cost (--max_cost), and an optional flat height increment value (--flat_increment). Notice that if the --flat_increment parameter is not specified, the small number used to ensure flow across flats will be calculated automatically, which should be preferred in most applications of the tool. The tool operates by performing a least-cost path analysis for each pit cell, radiating outward until the operation identifies a potential breach destination cell or reaches the maximum breach length parameter. If a value is specified for the optional --max_cost parameter, then least-cost breach paths that would require digging a channel that is more costly than this value will be left unbreached. The flat increment value is used to ensure that there is a monotonically descending path along breach channels to satisfy the necessary condition of a downslope gradient for flowpath modelling. It is best for this value to be a small value. If left unspecified, the tool with determine an appropriate value based on the range of elevation values in the input DEM, which should be the case in most applications. Notice that the need to specify these very small elevation increment values is one of the reasons why the output DEM will always be of a 64-bit floating-point data type, which will often double the storage requirements of a DEM (DEMs are often store with 32-bit precision). Lastly, the user may optionally choose to apply depression filling (--fill) on any depressions that remain unresolved by the earlier depression breaching operation. This filling step uses an efficient filling method based on flooding depressions from their pit cells until outlets are identified and then raising the elevations of flooded cells back and away from the outlets.

The tool can be run in two modes, based on whether the --min_dist is specified. If the --min_dist flag is specified, the accumulated cost (accum₂) of breaching from cell1 to cell2 along a channel issuing from pit is calculated using the traditional cost-distance function:

cost₁ = z₁ - (z_pit + l × s)

cost₂ = z₂ - [z_pit + (l + 1)s]

accum₂ = accum₁ + g(cost₁ + cost₂) / 2.0

where cost₁ and cost₂ are the costs associated with moving through cell1 and cell2 respectively, z₁ and z₂ are the elevations of the two cells, z_pit is the elevation of the pit cell, l is the length of the breach channel to cell1, g is the grid cell distance between cells (accounting for diagonal distances), and s is the small number used to ensure flow across flats. If the --min_dist flag is not present, the accumulated cost is calculated as:

accum₂ = accum₁ + cost₂

That is, without the --min_dist flag, the tool works to minimize elevation changes to the DEM caused by breaching, without considering the distance of breach channels. Notice that the value --max_cost, if specified, should account for this difference in the way cost/cost-distances are calculated. The first cell in the least-cost accumulation operation that is identified for which cost₂ <= 0.0 is the target cell to which the breach channel will connect the pit along the least-cost path.

In comparison with the BreachDepressions tool, this breaching method often provides a more satisfactory, lower impact, breaching solution and is often more efficient. It is therefore advisable that users try the BreachDepressionsLeastCost tool to remove depressions from their DEMs first. This tool is particularly well suited to breaching through road embankments. There are instances when a breaching solution is inappropriate, e.g. when a very deep depression such as an open-pit mine occurs in the DEM and long, deep breach paths are created. Often restricting breaching with the --max_cost parameter, combined with subsequent depression filling (--fill) can provide an adequate solution in these cases. Nonetheless, there are applications for which full depression filling using the FillDepressions tool may be preferred.

Reference:

Lindsay J, Dhun K. 2015. Modelling surface drainage patterns in altered landscapes using LiDAR. International Journal of Geographical Information Science, 29: 1-15. DOI: 10.1080/13658816.2014.975715

See Also: BreachDepressions, FillDepressions, CostPathway

Parameters:

Python function:

wbt.breach_depressions_least_cost(
    dem, 
    output, 
    dist, 
    max_cost=None, 
    min_dist=True, 
    flat_increment=None, 
    fill=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BreachDepressionsLeastCost -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif --dist=1000 ^
--max_cost=100.0 --min_dist 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/11/2019

Last Modified: 24/11/2019

BreachSingleCellPits

This tool can be used to remove pits from a digital elevation model (DEM). Pits are single grid cells with no downslope neighbours. They are important because they impede overland flow-paths. This tool will remove any pit in the input DEM (--dem) that can be resolved by lowering one of the eight neighbouring cells such that a flow-path can be created linking the pit to a second-order neighbour, i.e. a neighbouring cell of a neighbouring cell. Notice that this tool can be a useful pre-processing technique before running one of the more robust depression filling or breaching techniques (e.g. FillDepressions and BreachDepressions), which are designed to remove larger depression features.

See Also: FillDepressions, BreachDepressions, FillSingleCellPits

Parameters:

Python function:

wbt.breach_single_cell_pits(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BreachSingleCellPits -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 12/10/2018

BurnStreamsAtRoads

This tool decrements (lowers) the elevations of pixels within an input digital elevation model (DEM) (--dem) along an input vector stream network (--streams) at the sites of road (--roads) intersections. In addition to the input data layers, the user must specify the output raster DEM (--output), and the maximum road embankment width (--width), in map units. The road width parameter is used to determine the length of channel along stream lines, at the junctions between streams and roads, that the burning (i.e. decrementing) operation occurs. The algorithm works by identifying stream-road intersection cells, then traversing along the rasterized stream path in the upstream and downstream directions by half the maximum road embankment width. The minimum elevation in each stream traversal is identified and then elevations that are higher than this value are lowered to the minimum elevation during a second stream traversal.

Reference:

Lindsay JB. 2016. The practice of DEM stream burning revisited. Earth Surface Processes and Landforms, 41(5): 658–668. DOI: 10.1002/esp.3888

See Also: RasterStreamsToVector, RasterizeStreams

Parameters:

Python function:

wbt.burn_streams_at_roads(
    dem, 
    streams, 
    roads, 
    output, 
    width=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BurnStreamsAtRoads -v ^
--wd="/path/to/data/" --dem=raster.tif --streams=streams.shp ^
--roads=roads.shp -o=output.tif --width=50.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 30/10/2019

Last Modified: 29/12/2019

D8FlowAccumulation

This tool is used to generate a flow accumulation grid (i.e. catchment area) using the D8 (O'Callaghan and Mark, 1984) algorithm. This algorithm is an example of single-flow-direction (SFD) method because the flow entering each grid cell is routed to only one downslope neighbour, i.e. flow divergence is not permitted. The user must specify the name of the input digital elevation model (DEM) or flow pointer raster (--input) derived using the D8 or Rho8 method (D8Pointer, Rho8Pointer). If an input DEM is used, it must have been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achieved using the BreachDepressionsLeastCost or FillDepressions tools. If a D8 pointer raster is input, the user must also specify the optional --pntr flag. If the D8 pointer follows the Esri pointer scheme, rather than the default WhiteboxTools scheme, the user must also specify the optional --esri_pntr flag.

In addition to the input DEM/pointer, the user must specify the output type. The output flow-accumulation can be 1) cells (i.e. the number of inflowing grid cells), catchment area (i.e. the upslope area), or specific contributing area (i.e. the catchment area divided by the flow width. The default value is cells. The user must also specify whether the output flow-accumulation grid should be log-tranformed (--log), i.e. the output, if this option is selected, will be the natural-logarithm of the accumulated flow value. This is a transformation that is often performed to better visualize the contributing area distribution. Because contributing areas tend to be very high along valley bottoms and relatively low on hillslopes, when a flow-accumulation image is displayed, the distribution of values on hillslopes tends to be 'washed out' because the palette is stretched out to represent the highest values. Log-transformation provides a means of compensating for this phenomenon. Importantly, however, log-transformed flow-accumulation grids must not be used to estimate other secondary terrain indices, such as the wetness index, or relative stream power index.

Grid cells possessing the NoData value in the input DEM/pointer raster are assigned the NoData value in the output flow-accumulation image.

See Also: Rho8Pointer, D8Pointer, DInfPointer, DInfFlowAccumulation, BreachDepressionsLeastCost, FillDepressions

Parameters:

Python function:

wbt.d8_flow_accumulation(
    i, 
    output, 
    out_type="cells", 
    log=False, 
    clip=False, 
    pntr=False, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=D8FlowAccumulation -v ^
--wd="/path/to/data/" --input=DEM.tif -o=output.tif ^
--out_type='cells'
>>./whitebox_tools -r=D8FlowAccumulation -v ^
--wd="/path/to/data/" --input=DEM.tif -o=output.tif ^
--out_type='specific catchment area' --log --clip 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/016/2017

Last Modified: 21/02/2020

D8MassFlux

This tool can be used to perform a mass flux calculation using DEM-based surface flow-routing techniques. For example, it could be used to model the distribution of sediment or phosphorous within a catchment. Flow-routing is based on a D8 flow pointer (i.e. flow direction) derived from an input depresionless DEM (--dem). The user must also specify the names of loading (--loading), efficiency (--efficiency), and absorption (--absorption) rasters, as well as the output raster. Mass Flux operates very much like a flow-accumulation operation except that rather than accumulating catchment areas the algorithm routes a quantity of mass, the spatial distribution of which is specified within the loading image. The efficiency and absorption rasters represent spatial distributions of losses to the accumulation process, the difference being that the efficiency raster is a proportional loss (e.g. only 50% of material within a particular grid cell will be directed downslope) and the absorption raster is an loss specified as a quantity in the same units as the loading image. The efficiency image can range from 0 to 1, or alternatively, can be expressed as a percentage. The equation for determining the mass sent from one grid cell to a neighbouring grid cell is:

Outflowing Mass = (Loading - Absorption + Inflowing Mass) × Efficiency

This tool assumes that each of the three input rasters have the same number of rows and columns and that any NoData cells present are the same among each of the inputs.

See Also: DInfMassFlux

Parameters:

Python function:

wbt.d8_mass_flux(
    dem, 
    loading, 
    efficiency, 
    absorption, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=D8MassFlux -v --wd="/path/to/data/" ^
--dem=DEM.tif --loading=load.tif --efficiency=eff.tif ^
--absorption=abs.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: Dec. 29, 2017

Last Modified: 12/10/2018

D8Pointer

This tool is used to generate a flow pointer grid using the simple D8 (O'Callaghan and Mark, 1984) algorithm. The user must specify the name (--dem) of a digital elevation model (DEM) that has been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achived using either the BreachDepressions or FillDepressions tool. The local drainage direction raster output (--output) by this tool serves as a necessary input for several other spatial hydrology and stream network analysis tools in the toolset. Some tools will calculate this flow pointer raster directly from the input DEM.

By default, D8 flow pointers use the following clockwise, base-2 numeric index convention:

Notice that grid cells that have no lower neighbours are assigned a flow direction of zero. In a DEM that has been pre-processed to remove all depressions and flat areas, this condition will only occur along the edges of the grid. If the pointer file contains ESRI flow direction values instead, the --esri_pntr parameter must be specified.

Grid cells possessing the NoData value in the input DEM are assigned the NoData value in the output image.

Reference:

O'Callaghan, J. F., & Mark, D. M. (1984). The extraction of drainage networks from digital elevation data. Computer vision, graphics, and image processing, 28(3), 323-344.

See Also: DInfPointer, FD8Pointer, BreachDepressions, FillDepressions

Parameters:

Python function:

wbt.d8_pointer(
    dem, 
    output, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=D8Pointer -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/06/2017

Last Modified: 18/10/2019

DInfFlowAccumulation

This tool is used to generate a flow accumulation grid (i.e. contributing area) using the D-infinity algorithm (Tarboton, 1997). This algorithm is an examples of a multiple-flow-direction (MFD) method because the flow entering each grid cell is routed to one or two downslope neighbour, i.e. flow divergence is permitted. The user must specify the name of the input digital elevation model or D-infinity pointer raster (--input). If an input DEM is specified, the DEM should have been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achieved using the BreachDepressionsLeastCost or FillDepressions tool.

In addition to the input DEM/pointer raster name, the user must specify the output type (--out_type). The output flow-accumulation can be 1) specific catchment area (SCA), which is the upslope contributing area divided by the contour length (taken as the grid resolution), 2) total catchment area in square-metres, or 3) the number of upslope grid cells. The user must also specify whether the output flow-accumulation grid should be log-tranformed, i.e. the output, if this option is selected, will be the natural-logarithm of the accumulated area. This is a transformation that is often performed to better visualize the contributing area distribution. Because contributing areas tend to be very high along valley bottoms and relatively low on hillslopes, when a flow-accumulation image is displayed, the distribution of values on hillslopes tends to be 'washed out' because the palette is stretched out to represent the highest values. Log-transformation (--log) provides a means of compensating for this phenomenon. Importantly, however, log-transformed flow-accumulation grids must not be used to estimate other secondary terrain indices, such as the wetness index, or relative stream power index.

Grid cells possessing the NoData value in the input DEM/pointer raster are assigned the NoData value in the output flow-accumulation image. The output raster is of the float data type and continuous data scale.

Reference:

Tarboton, D. G. (1997). A new method for the determination of flow directions and upslope areas in grid digital elevation models. Water resources research, 33(2), 309-319.

See Also: DInfPointer, MDInfFlowAccumulation, BreachDepressionsLeastCost, FillDepressions,`

Parameters:

Python function:

wbt.d_inf_flow_accumulation(
    i, 
    output, 
    out_type="Specific Contributing Area", 
    threshold=None, 
    log=False, 
    clip=False, 
    pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DInfFlowAccumulation -v ^
--wd="/path/to/data/" --input=DEM.tif -o=output.tif ^
--out_type=sca
>>./whitebox_tools -r=DInfFlowAccumulation -v ^
--wd="/path/to/data/" --input=DEM.tif -o=output.tif ^
--out_type=sca --threshold=10000 --log --clip 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/06/2017

Last Modified: 21/02/2020

DInfMassFlux

This tool can be used to perform a mass flux calculation using DEM-based surface flow-routing techniques. For example, it could be used to model the distribution of sediment or phosphorous within a catchment. Flow-routing is based on a D-Infinity flow pointer derived from an input DEM (--dem). The user must also specify the names of loading (--loading), efficiency (--efficiency), and absorption (--absorption) rasters, as well as the output raster. Mass Flux operates very much like a flow-accumulation operation except that rather than accumulating catchment areas the algorithm routes a quantity of mass, the spatial distribution of which is specified within the loading image. The efficiency and absorption rasters represent spatial distributions of losses to the accumulation process, the difference being that the efficiency raster is a proportional loss (e.g. only 50% of material within a particular grid cell will be directed downslope) and the absorption raster is an loss specified as a quantity in the same units as the loading image. The efficiency image can range from 0 to 1, or alternatively, can be expressed as a percentage. The equation for determining the mass sent from one grid cell to a neighbouring grid cell is:

Outflowing Mass = (Loading - Absorption + Inflowing Mass) × Efficiency

This tool assumes that each of the three input rasters have the same number of rows and columns and that any NoData cells present are the same among each of the inputs.

See Also: D8MassFlux

Parameters:

Python function:

wbt.d_inf_mass_flux(
    dem, 
    loading, 
    efficiency, 
    absorption, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DInfMassFlux -v --wd="/path/to/data/" ^
--dem=DEM.tif --loading=load.tif --efficiency=eff.tif ^
--absorption=abs.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: Dec. 29, 2017

Last Modified: 12/10/2018

DInfPointer

This tool is used to generate a flow pointer grid (i.e. flow direction) using the D-infinity (Tarboton, 1997) algorithm. Dinf is a multiple-flow-direction (MFD) method because the flow entering each grid cell is routed one or two downslope neighbours, i.e. flow divergence is permitted. The user must specify the name of a digital elevation model (DEM; --dem) that has been hydrologically corrected to remove all spurious depressions and flat areas (BreachDepressions, FillDepressions). DEM pre-processing is usually achieved using the BreachDepressions or FillDepressions tool1. Flow directions are specified in the output flow-pointer grid (--output) as azimuth degrees measured from north, i.e. any value between 0 and 360 degrees is possible. A pointer value of -1 is used to designate a grid cell with no flow-pointer. This occurs when a grid cell has no downslope neighbour, i.e. a pit cell or topographic depression. Like aspect grids, Dinf flow-pointer grids are best visualized using a circular greyscale palette.

Grid cells possessing the NoData value in the input DEM are assigned the NoData value in the output image. The output raster is of the float data type and continuous data scale.

Reference:

Tarboton, D. G. (1997). A new method for the determination of flow directions and upslope areas in grid digital elevation models. Water resources research, 33(2), 309-319.

See Also: DInfFlowAccumulation, BreachDepressions, FillDepressions

Parameters:

Python function:

wbt.d_inf_pointer(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DInfPointer -v --wd="/path/to/data/" ^
--dem=DEM.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 13/02/2020

DepthInSink

This tool measures the depth that each grid cell in an input (--dem) raster digital elevation model (DEM) lies within a sink feature, i.e. a closed topographic depression. A sink, or depression, is a bowl-like landscape feature, which is characterized by interior drainage and groundwater recharge. The DepthInSink tool operates by differencing a filled DEM, using the same depression filling method as FillDepressions, and the original surface model.

In addition to the names of the input DEM (--dem) and the output raster (--output), the user must specify whether the background value (i.e. the value assigned to grid cells that are not contained within sinks) should be set to 0.0 (--zero_background) Without this optional parameter specified, the tool will use the NoData value as the background value.

Reference:

Antonić, O., Hatic, D., & Pernar, R. (2001). DEM-based depth in sink as an environmental estimator. Ecological Modelling, 138(1-3), 247-254.

See Also: FillDepressions

Parameters:

Python function:

wbt.depth_in_sink(
    dem, 
    output, 
    zero_background=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DepthInSink -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 05/12/2019

DownslopeDistanceToStream

This tool can be used to calculate the distance from each grid cell in a raster to the nearest stream cell, measured along the downslope flowpath. The user must specify the name of an input digital elevation model (--dem) and streams raster (--streams). The DEM must have been pre-processed to remove artifact topographic depressions and flat areas (see BreachDepressions). The streams raster should have been created using one of the DEM-based stream mapping methods, i.e. contributing area thresholding. Stream cells are designated in this raster as all non-zero values. The output of this tool, along with the ElevationAboveStream tool, can be useful for preliminary flood plain mapping when combined with high-accuracy DEM data.

By default, this tool calculates flow-path using the D8 flow algorithm. However, the user may specify (--dinf) that the tool should use the D-infinity algorithm instead.

See Also: ElevationAboveStream, DistanceToOutlet

Parameters:

Python function:

wbt.downslope_distance_to_stream(
    dem, 
    streams, 
    output, 
    dinf=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DownslopeDistanceToStream -v ^
--wd="/path/to/data/" --dem='dem.tif' --streams='streams.tif' ^
-o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 9/07/2017

Last Modified: 04/10/2019

DownslopeFlowpathLength

This tool can be used to calculate the downslope flowpath length from each grid cell in a raster to an outlet cell either at the edge of the grid or at the outlet point of a watershed. The user must specify the name of a flow pointer grid (--d8_pntr) derived using the D8 flow algorithm (D8Pointer). This grid should be derived from a digital elevation model (DEM) that has been pre-processed to remove artifact topographic depressions and flat areas (BreachDepressions, FillDepressions). The user may also optionally provide watershed (--watersheds) and weights (--weights) images. The optional watershed image can be used to define one or more irregular-shaped watershed boundaries. Flowpath lengths are measured within each watershed in the watershed image (each defined by a unique identifying number) as the flowpath length to the watershed's outlet cell.

The optional weight image is multiplied by the flow-length through each grid cell. This can be useful when there is a need to convert the units of the output image. For example, the default unit of flowpath lengths is the same as the input image(s). Thus, if the input image has X-Y coordinates measured in metres, the output image will likely contain very large values. A weight image containing a value of 0.001 for each grid cell will effectively convert the output flowpath lengths into kilometres. The weight image can also be used to convert the flowpath distances into travel times by multiplying the flow distance through a grid cell by the average velocity.

NoData valued grid cells in any of the input images will be assigned NoData values in the output image. The output raster is of the float data type and continuous data scale.

See Also: D8Pointer, ElevationAboveStream, BreachDepressions, FillDepressions, Watershed

Parameters:

Python function:

wbt.downslope_flowpath_length(
    d8_pntr, 
    output, 
    watersheds=None, 
    weights=None, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DownslopeFlowpathLength -v ^
--wd="/path/to/data/" --d8_pntr=pointer.tif ^
-o=flowpath_len.tif
>>./whitebox_tools ^
-r=DownslopeFlowpathLength -v --wd="/path/to/data/" ^
--d8_pntr=pointer.tif --watersheds=basin.tif ^
--weights=weights.tif -o=flowpath_len.tif --esri_pntr 

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/07/2017

Last Modified: 18/10/2019

ElevationAboveStream

This tool can be used to calculate the elevation of each grid cell in a raster above the nearest stream cell, measured along the downslope flowpath. This terrain index, a measure of relative topographic position, is essentially equivalent to the 'height above drainage' (HAND), as described by Renno et al. (2008). The user must specify the name of an input digital elevation model (--dem) and streams raster (--streams). The DEM must have been pre-processed to remove artifact topographic depressions and flat areas (see BreachDepressions). The streams raster should have been created using one of the DEM-based stream mapping methods, i.e. contributing area thresholding. Stream cells are designated in this raster as all non-zero values. The output of this tool, along with the DownslopeDistanceToStream tool, can be useful for preliminary flood plain mapping when combined with high-accuracy DEM data.

The difference between ElevationAboveStream and ElevationAboveStreamEuclidean is that the former calculates distances along drainage flow-paths while the latter calculates straight-line distances to streams channels.

Reference:

Renno, C. D., Nobre, A. D., Cuartas, L. A., Soares, J. V., Hodnett, M. G., Tomasella, J., & Waterloo, M. J. (2008). HAND, a new terrain descriptor using SRTM-DEM: Mapping terra-firme rainforest environments in Amazonia. Remote Sensing of Environment, 112(9), 3469-3481.

See Also: ElevationAboveStreamEuclidean, DownslopeDistanceToStream, ElevAbovePit, BreachDepressions

Parameters:

Python function:

wbt.elevation_above_stream(
    dem, 
    streams, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ElevationAboveStream -v ^
--wd="/path/to/data/" --dem='dem.tif' --streams='streams.tif' ^
-o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: July 9, 2017

Last Modified: 12/10/2018

ElevationAboveStreamEuclidean

This tool can be used to calculate the elevation of each grid cell in a raster above the nearest stream cell, measured along the straight-line distance. This terrain index, a measure of relative topographic position, is related to the 'height above drainage' (HAND), as described by Renno et al. (2008). HAND is generally estimated with distances measured along drainage flow-paths, which can be calculated using the ElevationAboveStream tool. The user must specify the name of an input digital elevation model (--dem) and streams raster (--streams). Stream cells are designated in this raster as all non-zero values. The output of this tool, along with the DownslopeDistanceToStream tool, can be useful for preliminary flood plain mapping when combined with high-accuracy DEM data.

The difference between ElevationAboveStream and ElevationAboveStreamEuclidean is that the former calculates distances along drainage flow-paths while the latter calculates straight-line distances to streams channels.

Reference:

Renno, C. D., Nobre, A. D., Cuartas, L. A., Soares, J. V., Hodnett, M. G., Tomasella, J., & Waterloo, M. J. (2008). HAND, a new terrain descriptor using SRTM-DEM: Mapping terra-firme rainforest environments in Amazonia. Remote Sensing of Environment, 112(9), 3469-3481.

See Also: ElevationAboveStream, DownslopeDistanceToStream, ElevAbovePit

Parameters:

Python function:

wbt.elevation_above_stream_euclidean(
    dem, 
    streams, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ElevationAboveStreamEuclidean -v ^
--wd="/path/to/data/" -i=DEM.tif --streams=streams.tif ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/03/2018

Last Modified: 12/10/2018

Fd8FlowAccumulation

This tool is used to generate a flow accumulation grid (i.e. contributing area) using the FD8 algorithm (Freeman, 1991). This algorithm is an examples of a multiple-flow-direction (MFD) method because the flow entering each grid cell is routed to each downslope neighbour, i.e. flow divergence is permitted. The user must specify the name (--dem) of the input digital elevation model (DEM). The DEM must have been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achived using either the BreachDepressions or FillDepressions tool. A value must also be specified for the exponent parameter (--exponent), a number that controls the degree of dispersion in the resulting flow-accumulation grid. A lower value yields greater apparent flow dispersion across divergent hillslopes. Some experimentation suggests that a value of 1.1 is appropriate (Freeman, 1991), although this is almost certainly landscape-dependent.

In addition to the input DEM, the user must specify the output type. The output flow-accumulation can be 1) cells (i.e. the number of inflowing grid cells), catchment area (i.e. the upslope area), or specific contributing area (i.e. the catchment area divided by the flow width. The default value is cells. The user must also specify whether the output flow-accumulation grid should be log-tranformed (--log), i.e. the output, if this option is selected, will be the natural-logarithm of the accumulated flow value. This is a transformation that is often performed to better visualize the contributing area distribution. Because contributing areas tend to be very high along valley bottoms and relatively low on hillslopes, when a flow-accumulation image is displayed, the distribution of values on hillslopes tends to be 'washed out' because the palette is stretched out to represent the highest values. Log-transformation provides a means of compensating for this phenomenon. Importantly, however, log-transformed flow-accumulation grids must not be used to estimate other secondary terrain indices, such as the wetness index, or relative stream power index.

The non-dispersive threshold (--threshold) is a flow-accumulation value (measured in upslope grid cells, which is directly proportional to area) above which flow dispersion is not longer permited. Grid cells with flow-accumulation values above this threshold will have their flow routed in a manner that is similar to the D8 single-flow-direction algorithm, directing all flow towards the steepest downslope neighbour. This is usually done under the assumption that flow dispersion, whilst appropriate on hillslope areas, is not realistic once flow becomes channelized.

Grid cells possessing the NoData value in the input flow-pointer grid are assigned the NoData value in the output flow-accumulation image.

Reference:

Freeman, T. G. (1991). Calculating catchment area with divergent flow based on a regular grid. Computers and Geosciences, 17(3), 413-422.

See Also: D8FlowAccumulation, DInfFlowAccumulation

Parameters:

Python function:

wbt.fd8_flow_accumulation(
    dem, 
    output, 
    out_type="specific contributing area", 
    exponent=1.1, 
    threshold=None, 
    log=False, 
    clip=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FD8FlowAccumulation -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--out_type='cells'
>>./whitebox_tools -r=FD8FlowAccumulation -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--out_type='catchment area' --exponent=1.5 --threshold=10000 ^
--log --clip 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 21/02/2020

Fd8Pointer

This tool is used to generate a flow pointer grid (i.e. flow direction) using the FD8 (Freeman, 1991) algorithm. FD8 is a multiple-flow-direction (MFD) method because the flow entering each grid cell is routed one or more downslope neighbours, i.e. flow divergence is permitted. The user must specify the name of a digital elevation model (DEM; --dem) that has been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achived using the BreachDepressions or FillDepressions tools.

By default, D8 flow pointers use the following clockwise, base-2 numeric index convention:

In the case of the FD8 algorithm, some portion of the flow entering a grid cell will be sent to each downslope neighbour. Thus, the FD8 flow-pointer value is the sum of each of the individual pointers for all downslope neighbours. For example, if a grid cell has downslope neighbours to the northeast, east, and south the corresponding FD8 flow-pointer value will be 1 + 2 + 8 = 11. Using the naming convention above, this is the only combination of flow-pointers that will result in the combined value of 11. Using the base-2 naming convention allows for the storage of complex combinations of flow-points using a single numeric value, which is the reason for using this somewhat odd convention.

Reference:

Freeman, T. G. (1991). Calculating catchment area with divergent flow based on a regular grid. Computers and Geosciences, 17(3), 413-422.

See Also: FD8FlowAccumulation, D8Pointer, DInfPointer, BreachDepressions, FillDepressions

Parameters:

Python function:

wbt.fd8_pointer(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FD8Pointer -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 12/10/2018

FillBurn

Burns streams into a DEM using the FillBurn (Saunders, 1999) method. This tool uses the algorithm described in:

Lindsay JB. 2016. The practice of DEM stream burning revisited. Earth Surface Processes and Landforms, 41(5): 658-668. DOI: 10.1002/esp.3888

And:

Saunders, W. 1999. Preparation of DEMs for use in environmental modeling analysis, in: ESRI User Conference. pp. 24-30.

Parameters:

Python function:

wbt.fill_burn(
    dem, 
    streams, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FillBurn -v --wd="/path/to/data/" ^
--dem=DEM.tif --streams=streams.shp -o=dem_burned.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/04/2018

Last Modified: 22/10/2019

FillDepressions

This tool can be used to fill all of the depressions in a digital elevation model (DEM) and to remove the flat areas. This is a common pre-processing step required by many flow-path analysis tools to ensure continuous flow from each grid cell to an outlet located along the grid edge. The FillDepressions algorithm operates by first identifying single-cell pits, that is, interior grid cells with no lower neighbouring cells. Each pit cell is then visited from highest to lowest and a priority region-growing operation is initiated. The area of monotonically increasing elevation, starting from the pit cell and growing based on flood order, is identified. Once a cell, that has not been previously visited and possessing a lower elevation than its discovering neighbour cell, is identified the discovering neighbour is labelled as an outlet (spill point) and the outlet elevation is noted. The algorithm then back-fills the labelled region, raising the elevation in the output DEM (--output) to that of the outlet. Once this process is completed for each pit cell (noting that nested pit cells are often solved by prior pits) the flat regions of filled pits are optionally treated (--fix_flats) with an applied small slope gradient away from outlets (note, more than one outlet cell may exist for each depression). The user may optionally specify the size of the elevation increment used to solve flats (--flat_increment), although it is best to not specify this optional value and to let the algorithm determine the most suitable value itself. The flat-fixing method applies a small gradient away from outlets using another priority region-growing operation (i.e. based on a priority queue operation), where priorities are set by the elevations in the input DEM (--input). This in effect ensures a gradient away from outlet cells but also following the natural pre-conditioned topography internal to depression areas. For example, if a large filled area occurs upstream of a damming road-embankment, the filled DEM will possess flow directions that are similar to the un-flooded valley, with flow following the valley bottom. In fact, the above case is better handled using the BreachDepressionsLeastCost tool, which would simply cut through the road embankment at the likely site of a culvert. However, the flat-fixing method of FillDepressions does mean that this common occurrence in LiDAR DEMs is less problematic.

The BreachDepressionsLeastCost, while slightly less efficient than either other hydrological preprocessing methods, often provides a lower impact solution to topographic depressions and should be preferred in most applications. In comparison with the BreachDepressionsLeastCost tool, the depression filling method often provides a less satisfactory, higher impact solution. It is advisable that users try the BreachDepressionsLeastCost tool to remove depressions from their DEMs before using FillDepressions. Nonetheless, there are applications for which full depression filling using the FillDepressions tool may be preferred.

Note that this tool will not fill in NoData regions within the DEM. It is advisable to remove such regions using the FillMissingData tool prior to application.

See Also: BreachDepressionsLeastCost, BreachDepressions, Sink, DepthInSink, FillMissingData

Parameters:

Python function:

wbt.fill_depressions(
    dem, 
    output, 
    fix_flats=True, 
    flat_increment=None, 
    max_depth=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FillDepressions -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--fix_flats 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 12/12/2019

FillDepressionsPlanchonAndDarboux

This tool can be used to fill all of the depressions in a digital elevation model (DEM) and to remove the flat areas using the Planchon and Darboux (2002) method. This is a common pre-processing step required by many flow-path analysis tools to ensure continuous flow from each grid cell to an outlet located along the grid edge. This tool is currently not the most efficient depression-removal algorithm available in WhiteboxTools; FillDepressions and BreachDepressionsLeastCost are both more efficient and often produce better, lower-impact results.

The user may optionally specify the size of the elevation increment used to solve flats (--flat_increment), although it is best not to specify this optional value and to let the algorithm determine the most suitable value itself.

Reference:

Planchon, O. and Darboux, F., 2002. A fast, simple and versatile algorithm to fill the depressions of digital elevation models. Catena, 46(2-3), pp.159-176.

See Also: FillDepressions, BreachDepressionsLeastCost

Parameters:

Python function:

wbt.fill_depressions_planchon_and_darboux(
    dem, 
    output, 
    fix_flats=True, 
    flat_increment=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FillDepressionsPlanchonAndDarboux -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--fix_flats 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/02/2020

Last Modified: 02/02/2020

FillDepressionsWangAndLiu

This tool can be used to fill all of the depressions in a digital elevation model (DEM) and to remove the flat areas. This is a common pre-processing step required by many flow-path analysis tools to ensure continuous flow from each grid cell to an outlet located along the grid edge. The FillDepressionsWangAndLiu algorithm is based on the computationally efficient approach of examining each cell based on its spill elevation, starting from the edge cells, and visiting cells from lowest order using a priority queue. As such, it is based on the algorithm first proposed by Wang and Liu (2006). However, it is currently not the most efficient depression-removal algorithm available in WhiteboxTools; FillDepressions and BreachDepressionsLeastCost are both more efficient and often produce better, lower-impact results.

If the input DEM has gaps, or missing-data holes, that contain NoData values, it is better to use the FillMissingData tool to repair these gaps. This tool will interpolate values across the gaps and produce a more natural-looking surface than the flat areas that are produced by depression filling. Importantly, the FillDepressions tool algorithm implementation assumes that there are no 'donut hole' NoData gaps within the area of valid data. Any NoData areas along the edge of the grid will simply be ignored and will remain NoData areas in the output image.

The user may optionally specify the size of the elevation increment used to solve flats (--flat_increment), although it is best not to specify this optional value and to let the algorithm determine the most suitable value itself.

Reference:

Wang, L. and Liu, H. 2006. An efficient method for identifying and filling surface depressions in digital elevation models for hydrologic analysis and modelling. International Journal of Geographical Information Science, 20(2): 193-213.

See Also: FillDepressions, BreachDepressionsLeastCost, BreachDepressions, FillMissingData

Parameters:

Python function:

wbt.fill_depressions_wang_and_liu(
    dem, 
    output, 
    fix_flats=True, 
    flat_increment=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FillDepressionsWangAndLiu -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--fix_flats 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 05/12/2019

FillSingleCellPits

This tool can be used to remove pits from a digital elevation model (DEM). Pits are single grid cells with no downslope neighbours. They are important because they impede overland flow-paths. This tool will remove any pits in the input DEM that can be resolved by raising the elevation of the pit such that flow will continue past the pit cell to one of the downslope neighbours. Notice that this tool can be a useful pre-processing technique before running one of the more robust depression breaching (BreachDepressions) or filling (FillDepressions) techniques, which are designed to remove larger depression features.

See Also: BreachDepressions, FillDepressions, BreachSingleCellPits

Parameters:

Python function:

wbt.fill_single_cell_pits(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FillSingleCellPits -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=NewRaster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

FindNoFlowCells

This tool can be used to find cells with undefined flow, i.e. no valid flow direction, based on the D8 flow direction algorithm (D8Pointer). These cells are therefore either at the bottom of a topographic depression or in the interior of a flat area. In a digital elevation model (DEM) that has been pre-processed to remove all depressions and flat areas (BreachDepressions), this condition will only occur along the edges of the grid, otherwise no-flow grid cells can be situation in the interior. The user must specify the name (--dem) of the DEM.

See Also: D8Pointer, BreachDepressions

Parameters:

Python function:

wbt.find_no_flow_cells(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FindNoFlowCells -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=NewRaster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

FindParallelFlow

This tool can be used to find cells in a stream network grid that possess parallel flow directions based on an input D8 flow-pointer grid (D8Pointer). Because streams rarely flow in parallel for significant distances, these areas are likely errors resulting from the biased assignment of flow direction based on the D8 method.

See Also: D8Pointer

Parameters:

Python function:

wbt.find_parallel_flow(
    d8_pntr, 
    streams, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FindParallelFlow -v ^
--wd="/path/to/data/" --d8_pntr=pointer.tif ^
-o=out.tif
>>./whitebox_tools -r=FindParallelFlow -v ^
--wd="/path/to/data/" --d8_pntr=pointer.tif -o=out.tif ^
--streams='streams.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

FlattenLakes

This tool can be used to set the elevations contained in a set of input vector lake polygons (--lakes) to a consistent value within an input (--dem) digital elevation model (DEM). Lake flattening is a common pre-processing step for DEMs intended for use in hydrological applications. This algorithm determines lake elevation automatically based on the minimum perimeter elevation for each lake polygon. The minimum perimeter elevation is assumed to be the lake outlet elevation and is assigned to the entire interior region of lake polygons, excluding island geometries. Note, this tool will not provide satisfactory results if the input vector polygons contain wide river features rather than true lakes. When this is the case, the tool will lower the entire river to the elevation of its mouth, leading to the creation of an artifical gorge.

See Also: FillDepressions

Parameters:

Python function:

wbt.flatten_lakes(
    dem, 
    lakes, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FlattenLakes -v --wd="/path/to/data/" ^
--dem='DEM.tif' --lakes='lakes.shp' -o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 29/03/2018

Last Modified: 28/05/2020

FloodOrder

This tool takes an input digital elevation model (DEM) and creates an output raster where every grid cell contains the flood order of that cell within the DEM. The flood order is the sequence of grid cells that are encountered during a search, starting from the raster grid edges and the lowest grid cell, moving inward at increasing elevations. This is in fact similar to how the highly efficient Wang and Liu (2006) depression filling algorithm and the Breach Depressions (Fast) operates. The output flood order raster contains the sequential order, from lowest edge cell to the highest pixel in the DEM.

Like the FillDepressions tool, FloodOrder will read the entire DEM into memory. This may make the algorithm ill suited to processing massive DEMs except where the user's computer has substantial memory (RAM) resources.

Reference:

Wang, L., and Liu, H. (2006). An efficient method for identifying and filling surface depressions in digital elevation models for hydrologic analysis and modelling. International Journal of Geographical Information Science, 20(2), 193-213.

See Also: FillDepressions

Parameters:

Python function:

wbt.flood_order(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FloodOrder -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/07/2017

Last Modified: 12/10/2018

FlowAccumulationFullWorkflow

Resolves all of the depressions in a DEM, outputting a breached DEM, an aspect-aligned non-divergent flow pointer, and a flow accumulation raster.

Parameters:

Python function:

wbt.flow_accumulation_full_workflow(
    dem, 
    out_dem, 
    out_pntr, 
    out_accum, 
    out_type="Specific Contributing Area", 
    log=False, 
    clip=False, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FlowAccumulationFullWorkflow -v ^
--wd="/path/to/data/" --dem='DEM.tif' ^
--out_dem='DEM_filled.tif' --out_pntr='pointer.tif' ^
--out_accum='accum.tif' --out_type=sca --log --clip 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 18/10/2019

FlowLengthDiff

FlowLengthDiff calculates the local maximum absolute difference in downslope flowpath length, which is useful in mapping drainage divides and ridges.

See Also: MaxBranchLength

Parameters:

Python function:

wbt.flow_length_diff(
    d8_pntr, 
    output, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FlowLengthDiff -v --wd="/path/to/data/" ^
--d8_pntr=pointer.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/07/2017

Last Modified: 18/10/2019

Hillslopes

This tool will identify the hillslopes associated with a user-specified stream network. Hillslopes include the catchment areas draining to the left and right sides of each stream link in the network as well as the catchment areas draining to all channel heads. Hillslopes are conceptually similar to Subbasins, except that sub-basins do not distinguish between the right-bank and left-bank catchment areas of stream links. The Subbasins tool simply assigns a unique identifier to each stream link in a stream network. Each hillslope output by this tool is assigned a unique, positive identifier value. All grid cells in the output raster that coincide with a stream cell are assigned an idenifiter of zero, i.e. stream cells do not belong to any hillslope.

The user must specify the name of a flow pointer (flow direction) raster (--d8_pntr), a streams raster (--streams), and the output raster (--output). The flow pointer and streams rasters should be generated using the D8Pointer algorithm. This will require a depressionless DEM, processed using either the BreachDepressions or FillDepressions tool.

By default, the pointer raster is assumed to use the clockwise indexing method used by WhiteboxTools. If the pointer file contains ESRI flow direction values instead, the --esri_pntr parameter must be specified.

NoData values in the input flow pointer raster are assigned NoData values in the output image.

See Also: StreamLinkIdentifier, Watershed, Subbasins, D8Pointer, BreachDepressions, FillDepressions

Parameters:

Python function:

wbt.hillslopes(
    d8_pntr, 
    streams, 
    output, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Hillslopes -v --wd="/path/to/data/" ^
--d8_pntr='d8pntr.tif' --streams='streams.tif' ^
-o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/07/2017

Last Modified: 18/10/2019

ImpoundmentSizeIndex

This tool can be used to calculate the impoundment size index (ISI) from a digital elevation model (DEM). The ISI is a land-surface parameter related to the size of the impoundment that would result from inserting a dam of a user-specified maximum length (--damlength) into each DEM grid cell. In addition to an output dam-height raster (same name as --output file but with an _dam_height suffix appended), the tool outputs a measure of impoundment size (--out_type) related to impoundment average depth, total volume, or flooded area.

Please note that this tool performs an extremely complex and computationally intensive flow-accumulation operation. As such, it may take a substantial amount of processing time and may encounter issues (including memory issues) when applied to very large DEMs. It is not necessary to pre-process the input DEM (--dem) to remove topographic depressions and flat areas. The internal flow-accumulation operation will not be confounded by the presence of these features.

Reference:

Lindsay, JB (2015) Modelling the spatial pattern of potential impoundment size from DEMs. Online resource: Whitebox Blog

See Also: InsertDams, StochasticDepressionAnalysis

Parameters:

Python function:

wbt.impoundment_size_index(
    dem, 
    output, 
    damlength, 
    out_type="mean depth", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ImpoundmentSizeIndex -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=out.tif ^
--out_type='max depth' --damlength=11 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/05/2018

Last Modified: 12/10/2018

InsertDams

This tool can be used to insert dams at one or more user-specified points (--dam_pts), and of a maximum length (--damlength), within an input digital elevation model (DEM) (--dem). This tool can be thought of as providing the impoundment feature that is calculated internally during a run of the the impoundment size index (ISI) tool for a set of points of interest. from a (DEM).

Reference:

Lindsay, JB (2015) Modelling the spatial pattern of potential impoundment size from DEMs. Online resource: Whitebox Blog

See Also: ImpoundmentSizeIndex, StochasticDepressionAnalysis

Parameters:

Python function:

wbt.insert_dams(
    dem, 
    dam_pts, 
    output, 
    damlength, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=InsertDams -v --wd="/path/to/data/" ^
--dem=DEM.tif --dam_pts=dams.shp -o=out.tif --damlength=11 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/02/2020

Last Modified: 20/02/2020

Isobasins

This tool can be used to divide a landscape into a group of nearly equal-sized watersheds, known as isobasins. The user must specify the name (--dem) of a digital elevation model (DEM), the output raster name (--output), and the isobasin target area (--size) specified in units of grid cells. The DEM must have been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achived using either the BreachDepressions or FillDepressions tool. Several temporary rasters are created during the execution and stored in memory of this tool.

The tool can optionally (--connections) output a CSV table that contains the upstream/downstream connections among isobasins. That is, this table will identify the downstream basin of each isobasin, or will list N/A in the event that there is no downstream basin, i.e. if it drains to an edge. The output CSV file will have the same name as the output raster, but with a *.csv file extension.

See Also: Watershed, Basins, BreachDepressions, FillDepressions

Parameters:

Python function:

wbt.isobasins(
    dem, 
    output, 
    size, 
    connections=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Isobasins -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --size=1000 

Source code on GitHub

Author: Dr. John Lindsay

Created: 03/12/2017

Last Modified: 24/07/2020

JensonSnapPourPoints

The JensonSnapPourPoints tool can be used to move the location of vector pour points (i.e. outlets used in a Watershed operation) (--pour_pts) to the location coincident with the nearest stream cell (--stream) value within a specified maximum distance (--snap_dist). The pour points file (--pour_pts) must be a vector file of Point ShapeType.

If the output of the JensonSnapPourPoints tool is to be used with the Watershed tool, the streams raster should be generated by extracting the streams using the D8FlowAccumulation algorithm. The snap distance (--snap_dist), measured in map units (e.g meters), must also be specified. This distance will serve as the search radius placed around each pour point during the search for the nearst stream cell.

Lindsay et al. (2008) provide a detailed discussion of the JensonSnapPourPoints technique, and other less sophisticated but commonly used techniques (SnapPourPoints) for adjusting pour point locations used in watershedding operations. In most cases, the JensonSnapPourPoints tool should be prefered over SnapPourPoints for applications of repositioning outlet points used in watershedding operations onto the digital stream lines contained in local drainage direction rasters. Jenson's method relocates outlet points to the nearest stream cell while SnapPourPoints relocated outlets to the largest stream (designated by the largest flow accumulation value). In the common situation where outlet cells are position near the confluence point of smaller tributary streams, the SnapPourPoints tool may re-position outlets on the main-trunk stream, which will result in watershed delineation of incorrect sub-basins.

Reference:

Jenson, S. K. (1991), Applications of hydrological information automati-cally extracted from digital elevation models, Hydrological Processes, 5, 31–44, doi:10.1002/hyp.3360050104.

Lindsay JB, Rothwell JJ, and Davies H. 2008. Mapping outlet points used for watershed delineation onto DEM-derived stream networks, Water Resources Research, 44, W08442, doi:10.1029/2007WR006507.

See Also: Watershed, SnapPourPoints, D8FlowAccumulation

Parameters:

Python function:

wbt.jenson_snap_pour_points(
    pour_pts, 
    streams, 
    output, 
    snap_dist, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=JensonSnapPourPoints -v ^
--wd="/path/to/data/" --pour_pts='pour_pts.shp' ^
--streams='streams.tif' -o='output.shp' --snap_dist=15.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 12/10/2018

LongestFlowpath

This tool delineates the longest flowpaths for a group of subbasins or watersheds. Flowpaths are initiated along drainage divides and continue along the D8-defined flow direction until either the subbasin outlet or DEM edge is encountered. Each input subbasin/watershed will have an associated vector flowpath in the output image. LongestFlowpath is similar to the r.lfp plugin tool for GRASS GIS. The length of the longest flowpath draining to an outlet is related to the time of concentration, which is a parameter used in certain hydrological models.

The user must input the filename of a digital elevation model (DEM), a basins raster, and the output vector. The DEM must be depressionless and should have been pre-processed using the BreachDepressions or FillDepressions tool. The basins raster must contain features that are delineated by categorical (integer valued) unique identifier values. All non-NoData, non-zero valued grid cells in the basins raster are interpreted as belonging to features. In practice, this tool is usual run using either a single watershed, a group of contiguous non-overlapping watersheds, or a series of nested subbasins. These are often derived using the Watershed tool, based on a series of input outlets, or the Subbasins tool, based on an input stream network. If subbasins are input to LongestFlowpath, each traced flowpath will include only the non-overlapping portions within nested areas. Therefore, this can be a convenient method of delineating the longest flowpath to each bifurcation in a stream network.

The output vector file will contain fields in the attribute table that identify the associated basin unique identifier (BASIN), the elevation of the flowpath source point on the divide (UP_ELEV), the elevation of the outlet point (DN_ELEV), the length of the flowpath (LENGTH), and finally, the average slope (AVG_SLOPE) along the flowpath, measured as a percent grade.

See Also: MaxUpslopeFlowpathLength, BreachDepressions, FillDepressions, Watershed, Subbasins

Parameters:

Python function:

wbt.longest_flowpath(
    dem, 
    basins, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LongestFlowpath -v ^
--wd="/path/to/data/" -i=DEM.tif --basins=basins.tif ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 29/10/2018

Last Modified: 29/10/2018

LowPointsOnHeadwaterDivides

Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).

This tool locates low points, or passes, on the drainage divides between subbasins that are situated on headwater divides. A subbasin is the catchment draining to a link in a stream network. A headwater catchment is the portion of a subbasin that drains to the channel head. Only first-order streams contain channel heads and headwater catchments are sometimes referred to as zero-order basins. The lowest points along a zero-order catchment is likely to coincide with mountain passes in alpine environments.

The user must input a depressionless DEM (i.e. a DEM that has been pre-processed to remove all topographic depressions) and a raster stream network. The tool will work best if the raster stream network, generally derived by thresholding a flow-accumulation raster, is processed to remove shorter headwater streams. You can use the RemoveShortStreams tool remove shorter streams in the input raster. It is recommended to remove streams shorter than 2 or 3 grid cells in length. The algorithm proceeds by first deriving the D8 flow pointer from the input DEM. It then identifies all channel head cells in the input streams raster and the zero-order basins that drain to them. The stream network is then processed to assign a unique identifier to each segment, which is then used to extract subbasins. Lastly, zero-order basin edge cells are identified and the location of lowest grid cells for each pair of neighbouring basins is entered into the output vector file.

See Also: RemoveShortStreams

Parameters:

Python function:

wbt.low_points_on_headwater_divides(
    dem, 
    streams, 
    output, 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=LowPointsOnHeadwaterDivides -i=input.tif ^
-s=streams.tif -o=new.tif 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 12/04/2021

Last Modified: 12/04/2021

MaxUpslopeFlowpathLength

This tool calculates the maximum length of the flowpaths that run through each grid cell (in map horizontal units) in an input digital elevation model (--dem). The tool works by first calculating the D8 flow pointer (D8Pointer) from the input DEM. The DEM must be depressionless and should have been pre-processed using the BreachDepressions or FillDepressions tool. The user must also specify the name of output raster (--output).

See Also: D8Pointer, BreachDepressions, FillDepressions, AverageUpslopeFlowpathLength, DownslopeFlowpathLength, DownslopeDistanceToStream

Parameters:

Python function:

wbt.max_upslope_flowpath_length(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MaxUpslopeFlowpathLength -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 28/10/2019

MdInfFlowAccumulation

This tool is used to generate a flow accumulation grid (i.e. contributing area) using the MD-infinity algorithm (Seibert and McGlynn, 2007). This algorithm is an examples of a multiple-flow-direction (MFD) method because the flow entering each grid cell is routed to one or two downslope neighbour, i.e. flow divergence is permitted. The user must specify the name of the input digital elevation model (--dem). The DEM should have been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achieved using the BreachDepressions or FillDepressions tool.

In addition to the input flow-pointer grid name, the user must specify the output type (--out_type). The output flow-accumulation can be 1) specific catchment area (SCA), which is the upslope contributing area divided by the contour length (taken as the grid resolution), 2) total catchment area in square-metres, or 3) the number of upslope grid cells. The user must also specify whether the output flow-accumulation grid should be log-tranformed, i.e. the output, if this option is selected, will be the natural-logarithm of the accumulated area. This is a transformation that is often performed to better visualize the contributing area distribution. Because contributing areas tend to be very high along valley bottoms and relatively low on hillslopes, when a flow-accumulation image is displayed, the distribution of values on hillslopes tends to be 'washed out' because the palette is stretched out to represent the highest values. Log-transformation (--log) provides a means of compensating for this phenomenon. Importantly, however, log-transformed flow-accumulation grids must not be used to estimate other secondary terrain indices, such as the wetness index, or relative stream power index.

Grid cells possessing the NoData value in the input DEM raster are assigned the NoData value in the output flow-accumulation image. The output raster is of the float data type and continuous data scale.

Reference:

Seibert, J. and McGlynn, B.L., 2007. A new triangular multiple flow direction algorithm for computing upslope areas from gridded digital elevation models. Water resources research, 43(4).

See Also: D8FlowAccumulation, DInfFlowAccumulation, FD8FlowAccumulation, BreachDepressions

Parameters:

Python function:

wbt.md_inf_flow_accumulation(
    dem, 
    output, 
    out_type="specific contributing area", 
    exponent=1.1, 
    threshold=None, 
    log=False, 
    clip=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MDInfFlowAccumulation -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--out_type='cells'
>>./whitebox_tools -r=MDInfFlowAccumulation ^
-v --wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--out_type='catchment area' --exponent=1.5 --threshold=10000 ^
--log --clip 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/02/2020

Last Modified: 12/02/2020

NumInflowingNeighbours

This tool calculates the number of inflowing neighbours for each grid cell in a raster file. The user must specify the names of an input digital elevation model (DEM) file (--dem) and the output raster file (--output). The tool calculates the D8 pointer file internally in order to identify inflowing neighbouring cells.

Grid cells in the input DEM that contain the NoData value will be assigned the NoData value in the output image. The output image is of the integer data type and continuous data scale.

See Also: NumDownslopeNeighbours, NumUpslopeNeighbours

Parameters:

Python function:

wbt.num_inflowing_neighbours(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NumInflowingNeighbours -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 12/10/2018

RaiseWalls

This tool is used to increment the elevations in a digital elevation model (DEM) along the boundaries of a vector lines or polygon layer. The user must specify the name of the raster DEM (--dem), the vector file (--input), the output file name (--output), the increment height (--height), and an optional breach lines vector layer (--breach). The breach lines layer can be used to breach a whole in the raised walls at intersections with the wall layer.

Parameters:

Python function:

wbt.raise_walls(
    i, 
    dem, 
    output, 
    breach=None, 
    height=100.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RaiseWalls -v --wd="/path/to/data/" ^
-i=watershed.shp --dem=dem.tif -o=output.tif ^
--height=25.0
>>./whitebox_tools -r=RaiseWalls -v ^
--wd="/path/to/data/" -i=watershed.shp --breach=outlet.shp ^
--dem=dem.tif -o=output.tif --height=25.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/04/2018

Last Modified: 22/10/2019

Rho8Pointer

This tool is used to generate a flow pointer grid (i.e. flow direction) using the stochastic Rho8 (J. Fairfield and P. Leymarie, 1991) algorithm. Like the D8 flow algorithm (D8Pointer), Rho8 is a single-flow-direction (SFD) method because the flow entering each grid cell is routed to only one downslope neighbour, i.e. flow divergence is not permitted. The user must specify the name of a digital elevation model (DEM) file (--dem) that has been hydrologically corrected to remove all spurious depressions and flat areas (BreachDepressions, FillDepressions).

By default, the Rho8 flow pointers use the following clockwise, base-2 numeric index convention:

Notice that grid cells that have no lower neighbours are assigned a flow direction of zero. In a DEM that has been pre-processed to remove all depressions and flat areas, this condition will only occur along the edges of the grid. If the pointer file contains ESRI flow direction values instead, the --esri_pntr parameter must be specified.

Grid cells possessing the NoData value in the input DEM are assigned the NoData value in the output image.

References:

Fairfield, J., & Leymarie, P. (1991). Drainage networks from grid digital elevation models. Water Resources Research, 27(5), 709-717.

See Also: D8Pointer, FD8Pointer, DInfPointer, BreachDepressions, FillDepressions

Parameters:

Python function:

wbt.rho8_pointer(
    dem, 
    output, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Rho8Pointer -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/07/2017

Last Modified: 18/10/2019

Sink

This tool identifies each sink (i.e. topographic depression) in a raster digital elevation model (DEM). A sink, or depression, is a bowl-like landscape feature, which is characterized by interior drainage. Each identified sink in the input DEM is assigned a unique, non-zero, positive value in the ouput raster. The Sink tool essentially runs the FillDepressions tool followed by the Clump tool on all modified grid cells.

See Also: FillDepressions, Clump

Parameters:

Python function:

wbt.sink(
    i, 
    output, 
    zero_background=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Sink -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=filled_dem.tif --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 05/12/2019

SnapPourPoints

The SnapPourPoints tool can be used to move the location of vector pour points (i.e. outlets used in a Watershed operation) (--pour_pts) to the location coincident with the highest flow accumulation (--flow_accum) value within a specified maximum distance (--snap_dist). The pour points file (--pour_pts) must be a vector file of Point ShapeType.

If the output of the SnapPourPoints tool is to be used with the Watershed tool, the flow accumulation raster should be generated using the D8FlowAccumulation algorithm. The snap distance (--snap_dist), measured in map units (e.g. meters), must also be specified. This distance will serve as the search radius placed around each pour point during the search for the maximum flow accumulation. In general, each outlet will be relocated the distance specified by the snap distance.

Lindsay et al. (2008) provide a detailed discussion of the SnapPourPoints technique, and other more sophisticated techniques for adjusting pour point locations used in watershedding operations including Jenson's snap pour points (JensonSnapPourPoints) method. In most cases, the JensonSnapPourPoints tool should be prefered for applications of repositioning outlet points used in watershedding operations onto the digital stream lines contained in local drainage direction rasters. Jenson's method relocates outlet points to the nearest stream cell while SnapPourPoints relocated outlets to the largest stream (designated by the largest flow accumulation value). In the common situation where outlet cells are position near the confluence point of smaller tributary streams, the SnapPourPoints tool may re-position outlets on the main-trunk stream, which will result in watershed delineation of incorrect sub-basins.

Reference:

Lindsay JB, Rothwell JJ, and Davies H. 2008. Mapping outlet points used for watershed delineation onto DEM-derived stream networks, Water Resources Research, 44, W08442, doi:10.1029/2007WR006507.

See Also: Watershed, JensonSnapPourPoints, D8FlowAccumulation

Parameters:

Python function:

wbt.snap_pour_points(
    pour_pts, 
    flow_accum, 
    output, 
    snap_dist, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SnapPourPoints -v --wd="/path/to/data/" ^
--pour_pts='pour_pts.shp' --flow_accum='d8accum.tif' ^
-o='output.shp' --snap_dist=15.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/072017

Last Modified: 12/10/2018

StochasticDepressionAnalysis

This tool performs a stochastic analysis of depressions within a DEM, calculating the probability of each cell belonging to a depression. This land-surface prameter (p_dep) has been widely applied in wetland and bottom-land mapping applications.

This tool differs from the original Whitebox GAT tool in a few significant ways:

1. The Whitebox GAT tool took an error histogram as an input. In practice people found it difficult to create this input. Usually they just generated a normal distribution in a spreadsheet using information about the DEM root-mean-square-error (RMSE). As such, this tool takes a RMSE input and generates the histogram internally. This is more convienent for most applications but loses the flexibility of specifying the error distribution more completely.

2. The Whitebox GAT tool generated the error fields using the turning bands method. This tool generates a random Gaussian error field with no spatial autocorrelation and then applies local spatial averaging using a Gaussian filter (the size of which depends of the error autocorrelation length input) to increase the level of autocorrelation. We use the Fast Almost Gaussian Filter of Peter Kovesi (2010), which uses five repeat passes of a mean filter, based on an integral image. This filter method is highly efficient. This results in a significant performance increase compared with the original tool.

3. Parts of the tool's workflow utilize parallel processing. However, the depression filling operation, which is the most time-consuming part of the workflow, is not parallelized.

In addition to the input DEM (--dem) and output p_dep file name (--output), the user must specify the nature of the error model, including the root-mean-square error (--rmse) and the error field correlation length (--range, in map units). These parameters determine the statistical frequency distribution and spatial characteristics of the modeled error fields added to the DEM in each iteration of the simulation. The user must also specify the number of iterations (--iterations). A larger number of iterations will produce a smoother p_dep raster.

This tool creates several temporary rasters in memory and, as a result, is very memory hungry. This will necessarily limit the size of DEMs that can be processed on more memory-constrained systems. As a rough guide for usage, the computer system will need 6-10 times more memory than the file size of the DEM. If your computer possesses insufficient memory, you may consider splitting the input DEM apart into smaller tiles.

Reference:

Lindsay, J. B., & Creed, I. F. (2005). Sensitivity of digital landscapes to artifact depressions in remotely-sensed DEMs. Photogrammetric Engineering & Remote Sensing, 71(9), 1029-1036.

See Also: ImpoundmentSizeIndex, FastAlmostGaussianFilter

Parameters:

Python function:

wbt.stochastic_depression_analysis(
    dem, 
    output, 
    rmse, 
    range, 
    iterations=100, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=StochasticDepressionAnalysis -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=out.tif --rmse=10.0 ^
--range=850.0 --iterations=2500 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/05/2018

Last Modified: 29/03/2019

StrahlerOrderBasins

This tool will identify the catchment areas of each Horton-Strahler stream order link in a user-specified stream network (--streams), i.e. the network's Strahler basins. The tool effectively performs a Horton-Strahler stream ordering operation (HortonStreamOrder) followed by by a Watershed operation. The user must specify the name of a flow pointer (flow direction) raster (--d8_pntr), a streams raster (--streams), and the output raster (--output). The flow pointer and streams rasters should be generated using the D8Pointer algorithm. This will require a depressionless DEM, processed using either the BreachDepressions or FillDepressions tool.

By default, the pointer raster is assumed to use the clockwise indexing method used by WhiteboxTools. If the pointer file contains ESRI flow direction values instead, the --esri_pntr parameter must be specified.

NoData values in the input flow pointer raster are assigned NoData values in the output image.

See Also: HortonStreamOrder, Watershed, D8Pointer, BreachDepressions, FillDepressions

Parameters:

Python function:

wbt.strahler_order_basins(
    d8_pntr, 
    streams, 
    output, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=StrahlerOrderBasins -v ^
--wd="/path/to/data/" --d8_pntr='d8pntr.tif' ^
--streams='streams.tif' -o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/07/2017

Last Modified: 18/10/2019

Subbasins

This tool will identify the catchment areas to each link in a user-specified stream network, i.e. the network's sub-basins. Subbasins effectively performs a stream link ID operation (StreamLinkIdentifier) followed by a Watershed operation. The user must specify the name of a flow pointer (flow direction) raster (--d8_pntr), a streams raster (--streams), and the output raster (--output). The flow pointer and streams rasters should be generated using the D8Pointer algorithm. This will require a depressionless DEM, processed using either the BreachDepressions or FillDepressions tool.

Hillslopes are conceptually similar to sub-basins, except that sub-basins do not distinguish between the right-bank and left-bank catchment areas of stream links. The Sub-basins tool simply assigns a unique identifier to each stream link in a stream network.

By default, the pointer raster is assumed to use the clockwise indexing method used by WhiteboxTools. If the pointer file contains ESRI flow direction values instead, the --esri_pntr parameter must be specified.

NoData values in the input flow pointer raster are assigned NoData values in the output image.

See Also: StreamLinkIdentifier, Watershed, Hillslopes, D8Pointer, BreachDepressions, FillDepressions

Parameters:

Python function:

wbt.subbasins(
    d8_pntr, 
    streams, 
    output, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Subbasins -v --wd="/path/to/data/" ^
--d8_pntr='d8pntr.tif' --streams='streams.tif' ^
-o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 13/02/2020

TraceDownslopeFlowpaths

This tool can be used to mark the flowpath initiated from user-specified locations downslope and terminating at either the grid's edge or a grid cell with undefined flow direction. The user must input the name of a D8 flow pointer grid (--d8_pntr) and an input vector file indicating the location of one or more initiation points, i.e. 'seed points' (--seed_pts). The seed point file must be a vector of the POINT ShapeType. Note that the flow pointer should be generated from a DEM that has been processed to remove all topographic depression (see BreachDepressions and FillDepressions) and created using the D8 flow algorithm (D8Pointer).

See Also: D8Pointer, BreachDepressions, FillDepressions, DownslopeFlowpathLength, DownslopeDistanceToStream

Parameters:

Python function:

wbt.trace_downslope_flowpaths(
    seed_pts, 
    d8_pntr, 
    output, 
    esri_pntr=False, 
    zero_background=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=TraceDownslopeFlowpaths -v ^
--wd="/path/to/data/" --seed_pts=seeds.shp ^
--flow_dir=flow_directions.tif --output=flow_paths.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/07/2017

Last Modified: 18/10/2019

UnnestBasins

In some applications it is necessary to relate a measured variable for a group of hydrometric stations (e.g. characteristics of flow timing and duration or water chemistry) to some characteristics of each outlet's catchment (e.g. mean slope, area of wetlands, etc.). When the group of outlets are nested, i.e. some stations are located downstream of others, then performing a watershed operation will result in inappropriate watershed delineation. In particular, the delineated watersheds of each nested outlet will not include the catchment areas of upstream outlets. This creates a serious problem for this type of application.

The Unnest Basin tool can be used to perform a watershedding operation based on a group of specified pour points, i.e. outlets or target cells, such that each complete watershed is delineated. The user must specify the name of a flow pointer (flow direction) raster, a pour point raster, and the name of the output rasters. Multiple numbered outputs will be created, one for each nesting level. Pour point, or target, cells are denoted in the input pour-point image as any non-zero, non-NoData value. The flow pointer raster should be generated using the D8 algorithm.

Parameters:

Python function:

wbt.unnest_basins(
    d8_pntr, 
    pour_pts, 
    output, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=UnnestBasins -v --wd="/path/to/data/" ^
--d8_pntr='d8pntr.tif' --pour_pts='pour_pts.shp' ^
-o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/04/2018

Last Modified: 18/10/2019

UpslopeDepressionStorage

This tool estimates the average upslope depression storage depth using the FD8 flow algorithm. The input DEM (--dem) need not be hydrologically corrected; the tool will internally map depression storage and resolve flowpaths using depression filling. This input elevation model should be of a fine resolution (< 2 m), and is ideally derived using LiDAR. The tool calculates the total upslope depth of depression storage, which is divided by the number of upslope cells in the final step of the process, yielding the average upslope depression depth. Roughened surfaces tend to have higher values compared with smoothed surfaces. Values, particularly on hillslopes, may be very small (< 0.01 m).

See Also: FD8FlowAccumulation, FillDepressions, DepthInSink

Parameters:

Python function:

wbt.upslope_depression_storage(
    dem, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=UpslopeDepressionStorage -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/11/2019

Last Modified: 21/11/2019

Watershed

This tool will perform a watershedding operation based on a group of input vector pour points (--pour_pts), i.e. outlets or points-of-interest, or a raster containing point points. Watershedding is a procedure that identifies all of the cells upslope of a cell of interest (pour point) that are connected to the pour point by a flow-path. The user must specify the name of a D8-derived flow pointer (flow direction) raster (--d8_pntr), a vector pour point file (--pour_pts), and the output raster (--output). The pour points must be of a Point ShapeType (i.e. Point, PointZ, PointM, MultiPoint, MultiPointZ, MultiPointM). Watersheds will be assigned the input pour point FID value. The flow pointer raster must be generated using the D8 algorithm, D8Pointer.

Pour point vectors can be attained by on-screen digitizing to designate these points-of-interest locations. Because pour points are usually, although not always, situated on a stream network, it is recommended that you use Jenson's method (JensonSnapPourPoints) to snap pour points on the stream network. This will ensure that the digitized outlets are coincident with the digital stream contained within the DEM flowpaths. If this is not done prior to inputting a pour-point set to the Watershed tool, anomalously small watersheds may be ouput, as pour points that fall off of the main flow path (even by one cell) in the D8 pointer will yield very different catchment areas.

If a raster pour point is specified instead of vector points, the watershed labels will derive their IDs from the grid cell values of all non-zero, non-NoData valued grid cells in the pour points file. Notice that this file can contain any integer data. For example, if a lakes raster, with each lake possessing a unique ID, is used as the pour points raster, the tool will map the watersheds draining to each of the input lake features. Similarly, a pour points raster may actually be a streams file, such as what is generated by the StreamLinkIdentifier tool.

By default, the pointer raster is assumed to use the clockwise indexing method used by WhiteboxTools. If the pointer file contains ESRI flow direction values instead, the --esri_pntr parameter must be specified.

There are several tools that perform similar watershedding operations in WhiteboxTools. Watershed is appropriate to use when you have a set of specific locations for which you need to derive the watershed areas. Use the Basins tool instead when you simply want to find the watersheds draining to each outlet situated along the edge of a DEM. The Isobasins tool can be used to divide a landscape into roughly equally sized watersheds. The Subbasins and StrahlerOrderBasins are useful when you need to find the areas draining to each link within a stream network. Finally, Hillslopes can be used to idenfity the areas draining the each of the left and right banks of a stream network.

Reference:

Jenson, S. K. (1991), Applications of hydrological information automati-cally extracted from digital elevation models, Hydrological Processes, 5, 31–44, doi:10.1002/hyp.3360050104.

Lindsay JB, Rothwell JJ, and Davies H. 2008. Mapping outlet points used for watershed delineation onto DEM-derived stream networks, Water Resources Research, 44, W08442, doi:10.1029/2007WR006507.

See Also: D8Pointer, Basins, Subbasins, Isobasins, StrahlerOrderBasins, Hillslopes, JensonSnapPourPoints, BreachDepressions, FillDepressions

Parameters:

Python function:

wbt.watershed(
    d8_pntr, 
    pour_pts, 
    output, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Watershed -v --wd="/path/to/data/" ^
--d8_pntr='d8pntr.tif' --pour_pts='pour_pts.shp' ^
-o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 14/02/2020