Geomorphometric Analysis
- AccumulationCurvature
- Aspect
- AssessRoute
- AverageHorizonDistance
- AverageNormalVectorAngularDeviation
- BreaklineMapping
- CircularVarianceOfAspect
- ContoursFromPoints
- ContoursFromRaster
- Curvedness
- DemVoidFilling
- DevFromMeanElev
- DiffFromMeanElev
- DifferenceCurvature
- DirectionalRelief
- DownslopeIndex
- EdgeDensity
- ElevAbovePit
- ElevPercentile
- ElevRelativeToMinMax
- ElevRelativeToWatershedMinMax
- EmbankmentMapping
- ExposureTowardsWindFlux
- FeaturePreservingSmoothing
- FetchAnalysis
- FillMissingData
- FindRidges
- GaussianCurvature
- GaussianScaleSpace
- GeneratingFunction
- Geomorphons
- Hillshade
- HorizonAngle
- HorizonArea
- HorizontalExcessCurvature
- HypsometricAnalysis
- HypsometricallyTintedHillshade
- LocalHypsometricAnalysis
- LocalQuadraticRegression
- MapOffTerrainObjects
- MaxAnisotropyDev
- MaxAnisotropyDevSignature
- MaxBranchLength
- MaxDifferenceFromMean
- MaxDownslopeElevChange
- MaxElevDevSignature
- MaxElevationDeviation
- MaxUpslopeElevChange
- MaximalCurvature
- MeanCurvature
- MinDownslopeElevChange
- MinimalCurvature
- MultidirectionalHillshade
- MultiscaleCurvatures
- MultiscaleElevationPercentile
- MultiscaleRoughness
- MultiscaleRoughnessSignature
- MultiscaleStdDevNormals
- MultiscaleStdDevNormalsSignature
- MultiscaleTopographicPositionImage
- NumDownslopeNeighbours
- NumUpslopeNeighbours
- Openness
- PennockLandformClass
- PercentElevRange
- PlanCurvature
- Profile
- ProfileCurvature
- RelativeAspect
- RelativeTopographicPosition
- RemoveOffTerrainObjects
- RingCurvature
- Rotor
- RuggednessIndex
- SedimentTransportIndex
- ShadowAnimation
- ShadowImage
- ShapeIndex
- SkyViewFactor
- SkylineAnalysis
- Slope
- SlopeVsAspectPlot
- SlopeVsElevationPlot
- SmoothVegetationResidual
- SphericalStdDevOfNormals
- StandardDeviationOfSlope
- StreamPowerIndex
- SurfaceAreaRatio
- TangentialCurvature
- TimeInDaylight
- TopoRender
- TopographicHachures
- TopographicPositionAnimation
- TotalCurvature
- Unsphericity
- VerticalExcessCurvature
- Viewshed
- VisibilityIndex
- WetnessIndex
AccumulationCurvature
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the accumulation curvature from a digital elevation model (DEM). Accumulation curvature is the product of profile (vertical) and tangential (horizontal) curvatures at a location (Shary, 1995). This variable has positive values, zero or greater. Florinsky (2017) states that accumulation curvature is a measure of the extent of local accumulation of flows at a given point in the topographic surface. Accumulation curvature is measured in units of m-2.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
See Also:
TangentialCurvature, ProfileCurvature, MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--log | Display output values using a log-scale |
--zfactor | Z conversion factor |
Python function:
wbt.accumulation_curvature(
dem,
output,
log=False,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=AccumulationCurvature -i=DEM.tif ^
-o=output.tif --log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 11/01/2022
Last Modified: 28/11/2022
Aspect
This tool calculates slope aspect (i.e. slope orientation in degrees clockwise from north) for each grid cell
in an input digital elevation model (DEM). The user must specify the name of the input
DEM (--dem
) and the output raster image. The Z conversion factor is only important
when the vertical and horizontal units are not the same in the DEM, and the DEM is in a projected coordinate system. When this is the case,
the algorithm will multiply each elevation in the DEM by the Z conversion factor.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
Reference:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
See Also: Slope, TangentialCurvature, PlanCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.aspect(
dem,
output,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Aspect -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 12/01/2022
AssessRoute
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool assesses the variability in slope, elevation, and visibility along a line vector, which may
be a footpath, road, river or any other route. The user must specify the name of the input line vector
(--routes
), the input raster digital elevation model file (--dem
), and the output line vector
(--output
). The algorithm initially splits the input line vector in equal-length segments (--length
).
For each line segment, the tool then calculates the average slope (AVG_SLOPE), minimum and maximum
elevations (MIN_ELEV, MAX_ELEV), the elevation range or relief (RELIEF), the path sinuosity
(SINUOSITY), the number of changes in slope direction or breaks-in-slope (CHG_IN_SLP), and the
maximum visibility (VISIBILITY). Each of these metrics are output to the attribute table of the output
vector, along with the feature identifier (FID); any attributes associated with the input parent
feature will also be copied into the output table. Slope and elevation metrics are measured along the
2D path based on the elevations of each of the row and column intersection points of the raster with
the path, estimated from linear-interpolation using the two neighbouring elevations on either side of
the path. Sinuosity is calculated as the ratio of the along-surface (i.e. 3D) path length, divided by
the 3D distance between the start and end points of the segment. CHG_IN_SLP can be thought of as a crude
measure of path roughness, although this will be very sensitive to the quality of the DEM. The visibility
metric is based on the Yokoyama et al. (2002) Openness index, which calculates the average horizon
angle in the eight cardal directions to a maximum search distance (--dist
), measured in grid cells.
Note that the input DEM must be in a projected coordinate system. The DEM and the input routes vector must be also share the same coordinate system. This tool also works best when the input DEM is of high quality and fine spatial resolution, such as those derived from LiDAR data sets.
Maximum segment visibility:
Average segment slope:
For more information about this tool, see this blog on the WhiteboxTools homepage.
See Also: SplitVectorLines, Openness
Parameters:
Flag | Description |
---|---|
--routes | Name of the input routes vector file |
--dem | Name of the input DEM raster file |
-o, --output | Name of the output lines shapefile |
--length | Maximum segment length (m) |
--dist | Search distance, in grid cells, used in visibility analysis |
Python function:
wbt.assess_route(
routes,
dem,
output,
length="",
dist=20,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=AssessRoute --routes=footpath.shp ^
--dem=DEM.tif -o=assessedRoutes.shp --length=50.0 --dist=200
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 16/05/2021
Last Modified: 16/05/2021
AverageHorizonDistance
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the spatial pattern of average distance to the horizon based on an input digital elevation model (DEM). As such, the index is a measure of landscape visibility. In the image below, lighter areas have a longer average distance to the horizon, measured in map units.
The user must specify an input DEM (dem
), the azimuth fraction (az_fraction
), the maximum search
distance (max_dist
), and the height offset of the observer (observer_hgt_offset
). The input DEM
should usually be a digital surface model (DSM) that contains significant off-terrain objects. Such a
model, for example, could be created using the first-return points of a LiDAR data set, or using the
lidar_digital_surface_model tool. The azimuth
fraction should be an even divisor of 360-degrees and must be between 1-45 degrees.
The tool operates by calculating horizon angle (see horizon_angle)
rasters from the DSM based on the user-specified azimuth fraction (az_fraction
). For example, if an azimuth
fraction of 15-degrees is specified, horizon angle rasters would be calculated for the solar azimuths 0,
15, 30, 45... A horizon angle raster evaluates the vertical angle between each grid cell in a DSM and a
distant obstacle (e.g. a mountain ridge, building, tree, etc.) that obscures the view in a specified
direction. In calculating horizon angle, the user must specify the maximum search distance (max_dist
),
in map units, beyond which the query for higher, more distant objects will cease. This parameter strongly
impacts the performance of the function, with larger values resulting in significantly longer processing-times.
The observer_hgt_offset
parameter can be used to add an increment to the source cell's elevation. For
example, the following image shows the spatial pattern derived from a LiDAR DSM using observer_hgt_offset = 0.0
:
Notice that there are several places, plarticularly on the flatter rooftops, where the local noise in the LiDAR DEM, associated with the individual scan lines, has resulted in a noisy pattern in the output. By adding a small height offset of the scale of this noise variation (0.15 m), we see that most of this noisy pattern is removed in the output below:
This feature makes the function more robust against DEM noise. As another example of the usefulness of
this additional parameter, in the image below, the observer_hgt_offset
parameter has been used to
measure the pattern of the index at a typical human height (1.7 m):
Notice how at this height the average horizon distance becomes much farther on some of the flat rooftops where a guard wall prevents further viewing areas at shorter observer heights.
The output of this function is similar to the Average View Distance provided by the Sky View tool in Saga GIS. However, for a given maximum search distance, the Whitebox tool is likely faster to compute and has the added advantage of offering the observer's height parameter, as described above.
See Also:
SkyViewFactor, HorizonArea, SkylineAnalysis, Openness, TimeInDaylight, HorizonAngle
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--az_fraction | Azimuth fraction |
--max_dist | Maximum distance (xy units) |
--observer_hgt_offset | Oberserver height offset (z units) |
Python function:
wbt.average_horizon_distance(
dem,
output,
az_fraction=5.0,
max_dist=9999.0,
observer_hgt_offset=0.05,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=AccumulationCurvature -i=DEM.tif ^
-o=output.tif --log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 09/04/2024
Last Modified: 09/04/2024
AverageNormalVectorAngularDeviation
This tool characterizes the spatial distribution of the average normal vector angular deviation, a measure of
surface roughness. Working in the field of 3D printing, Ko et al. (2016) defined a measure of surface roughness
based on quantifying the angular deviations in the direction of the normal vector of a real surface from its ideal
(i.e. smoothed) form. This measure of surface complexity is therefore in units of degrees. Specifically, roughness
is defined in this study as the neighborhood-averaged difference in the normal vectors of the original DEM and a
smoothed DEM surface. Smoothed surfaces are derived by applying a Gaussian blur of the same size as the
neighborhood (--filter
).
The MultiscaleRoughness tool calculates the same measure of surface roughness, except that it is designed to work with multiple spatial scales.
Reference:
Ko, M., Kang, H., ulrim Kim, J., Lee, Y., & Hwang, J. E. (2016, July). How to measure quality of affordable 3D printing: Cultivating quantitative index in the user community. In International Conference on Human-Computer Interaction (pp. 116-121). Springer, Cham.
Lindsay, J. B., & Newman, D. R. (2018). Hyper-scale analysis of surface roughness. PeerJ Preprints, 6, e27110v1.
See Also: MultiscaleRoughness, SphericalStdDevOfNormals, CircularVarianceOfAspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--output | Output raster file |
--filter | Size of the filter kernel |
Python function:
wbt.average_normal_vector_angular_deviation(
dem,
output,
filter=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=AverageNormalVectorAngularDeviation -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: 26/01/2019
Last Modified: 03/09/2020
BreaklineMapping
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool can be used to map breaklines in an input digital elevation model (DEM; --input
). Breaklines are
locations of high surface curvature, in any direction, measured using Curvedness. Curvedness values are
log-transformed using the resolution-dependent method proposed by Shary et al. (2002). Breaklines are coincident
with grid cells that have log-transformed curvedness values exceeding a user-specified threshold value
(--thresshold
). While curvedness is measured within the range 0 to infinity, values are typically lower.
Appropriate values for the threshold parameter are commonly in the 1 to 5 range. Lower threshold values will
result in more extensive breakline mapping and vice versa. The algorithm will vectorize breakline features and
the output of this tool (--output
) is a line vector. Line features that are less than a user-specified length
(in grid cells; --min_length
), will not be output.
Watch the breakline mapping video for an example of how to run the tool.
References:
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
See Also:
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Name of the input raster DEM file |
-o, --output | Name of the output vector lines file |
--threshold | Threshold value (0 - infinity but typcially 1 to 5 works well) |
--min_length | Minimum line length, in grid cells |
Python function:
wbt.breakline_mapping(
dem,
output,
threshold=2.0,
min_length=3,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=BreaklineMapping -i=input.tif ^
-o=output.tif --threshold=0.8 --min_length=5
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 13/01/2022
Last Modified: 13/01/2022
CircularVarianceOfAspect
This tool can be used to calculate the circular variance (i.e. one minus the mean resultant length) of aspect
for an input digital elevation model (DEM). This is a measure of how variable slope aspect is within a local
neighbourhood of a specified size (--filter
). CircularVarianceOfAspect is therefore a measure of surface
shape complexity, or texture. It will take a value of 0.0 for smooth sites and near 1.0 in areas of high surface
roughness or complex topography.
The local neighbourhood size (--filter
) must be any odd integer equal to or greater than three. Grohmann et al. (2010) found that
vector dispersion, a related measure of angular variance, increases monotonically with scale. This is the result
of the angular dispersion measure integrating (accumulating) all of the surface variance of smaller scales up to the
test scale. A more interesting scale relation can therefore be estimated by isolating the amount of surface complexity
associated with specific scale ranges. That is, at large spatial scales, the metric should reflect
the texture of large-scale landforms rather than the accumulated complexity at all smaller scales, including
microtopographic roughness. As such, this tool normalizes the surface complexity of scales that are smaller than
the filter size by applying Gaussian blur (with a standard deviation of one-third the filter size) to the DEM prior
to calculating CircularVarianceOfAspect. In this way, the resulting distribution is able to isolate and highlight
the surface shape complexity associated with landscape features of a similar scale to that of the filter size.
This tool makes extensive use of integral images (i.e. summed-area tables) and parallel processing to ensure computational efficiency. It may, however, require substantial memory resources when applied to larger DEMs.
References:
Grohmann, C. H., Smith, M. J., & Riccomini, C. (2010). Multiscale analysis of topographic surface roughness in the Midland Valley, Scotland. IEEE Transactions on Geoscience and Remote Sensing, 49(4), 1200-1213.
See Also: Aspect, SphericalStdDevOfNormals, MultiscaleRoughness, EdgeDensity, SurfaceAreaRatio, RuggednessIndex
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--output | Output raster file |
--filter | Size of the filter kernel |
Python function:
wbt.circular_variance_of_aspect(
dem,
output,
filter=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=CircularVarianceOfAspect -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: 26/01/2019
Last Modified: 03/09/2020
ContoursFromPoints
This tool creates a contour coverage from a set of input points (--input
). The user must specify the contour
interval (--interval
) and optionally, the base contour value (--base
). The degree to which contours are
smoothed is controlled by the Smoothing Filter Size parameter (--smooth
). This value, which determines
the size of a mean filter applied to the x-y position of vertices in each contour, should be an odd integer value, e.g.
3, 5, 7, 9, 11, etc. Larger values will result in smoother contour lines.
See Also: ContoursFromRaster
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector points file |
--field | Input field name in attribute table |
--use_z | Use the 'z' dimension of the Shapefile's geometry instead of an attribute field? |
-o, --output | Output vector lines file |
--max_triangle_edge_length | Optional maximum triangle edge length; triangles larger than this size will not be gridded |
--interval | Contour interval |
--base | Base contour height |
--smooth | Smoothing filter size (in num. points), e.g. 3, 5, 7, 9, 11 |
Python function:
wbt.contours_from_points(
i,
output,
field=None,
use_z=False,
max_triangle_edge_length=None,
interval=10.0,
base=0.0,
smooth=5,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ContoursFromPoints -v ^
--wd="/path/to/data/" -i=points.shp --field=HEIGHT ^
-o=contours.shp --max_triangle_edge_length=100.0 ^
--interval=100.0 --base=0.0 --smooth=11
Author: Dr. John Lindsay
Created: 26/04/2020
Last Modified: 24/06/2021
ContoursFromRaster
This tool can be used to create a vector contour coverage from an input raster surface model (--input
), such as a digital
elevation model (DEM). The user must specify the contour interval (--interval
) and optionally, the base contour value (--base
).
The degree to which contours are smoothed is controlled by the Smoothing Filter Size parameter (--smooth
). This value, which
determines the size of a mean filter applied to the x-y position of vertices in each contour, should be an odd integer value, e.g.
3, 5, 7, 9, 11, etc. Larger values will result in smoother contour lines. The tolerance parameter (--tolerance
) controls the
amount of line generalization. That is, vertices in a contour line will be selectively removed from the line if they do not result in
an angular deflection in the line's path of at least this threshold value. Increasing this value can significantly decrease the size
of the output contour vector file, at the cost of generating straighter contour line segments.
See Also: RasterToVectorPolygons
Parameters:
Flag | Description |
---|---|
-i, --input | Input surface raster file |
-o, --output | Output vector contour file |
--interval | Contour interval |
--base | Base contour height |
--smooth | Smoothing filter size (in num. points), e.g. 3, 5, 7, 9, 11 |
--tolerance | Tolerance factor, in degrees (0-45); determines generalization level |
Python function:
wbt.contours_from_raster(
i,
output,
interval=10.0,
base=0.0,
smooth=9,
tolerance=10.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ContoursFromRaster -v ^
--wd="/path/to/data/" --input=DEM.tif -o=contours.shp ^
--interval=100.0 --base=0.0 --smooth=11 --tolerance=20.0
Author: Dr. John Lindsay
Created: 22/02/2020
Last Modified: 04/03/2020
Curvedness
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the curvedness (Koenderink and van Doorn, 1992) from a digital elevation model (DEM). Curvedness is the root mean square of maximal and minimal curvatures, and measures the magnitude of surface bending, regardless of shape (Florinsky, 2017). Curvedness is characteristically low-values for flat areas and higher for areas of sharp bending (Florinsky, 2017). The index is also inversely proportional with the size of the object (Koenderink and van Doorn, 1992). Curvedness has values equal to or greater than zero and is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Raw curvedness values are often challenging to visualize given their range and magnitude,
and as such the user may opt to log-transform the output raster (--log
). Transforming the values
applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Koenderink, J. J., and Van Doorn, A. J. (1992). Surface shape and curvature scales. Image and vision computing, 10(8), 557-564.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
See Also:
ShapeIndex, MinimalCurvature, MaximalCurvature, TangentialCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--log | Display output values using a log-scale |
--zfactor | Z conversion factor |
Python function:
wbt.curvedness(
dem,
output,
log=False,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=Curvedness -i=DEM.tif -o=output.tif ^
--log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 13/01/2022
Last Modified: 28/11/2022
DemVoidFilling
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool implements a modified version of the Delta Surface Fill method of Grohman et al. (2006). It can
fill voids (i.e., data holes) contained within a digital elevation model (dem
) by fusing the data with a
second DEM (fill
) that defines the topographic surface within the void areas. The two surfaces are fused
seamlessly so that the transition from the source and fill surfaces is undetectable. The fill DEM need
not have the same resolution as the source DEM.
The algorithm works by computing a DEM-of-difference (DoD) for each valid grid cell in the source DEM that also has a valid elevation in the corresponding location within the fill DEM. This difference surface is then used to define offsets within the near void-edge locations. The fill surface elevations are then combined with interpolated offsets, with the interpolation based on near-edge offsets, and used to define a new surface within the void areas of the source DEM in such a way that the data transitions seamlessly from the source data source to the fill data. The image below provides an example of this method.
The user must specify the mean_plane_dist
parameter, which defines the distance (measured in grid cells)
within a void area from the void's edge. Grid cells within larger voids that are beyond this distance
from their edges have their vertical offsets, needed during the fusion of the DEMs, set to the mean offset
for all grid cells that have both valid source and fill elevations. Void cells that are nearer their void
edges have vertical offsets that are interpolated based on nearby offset values (i.e., the DEM of difference).
The interpolation uses inverse-distance weighted (IDW) scheme, with a user-specified weight parameter (weight_value
).
The edge_treatment
parameter describes how the data fusion operates at the edges of voids, i.e., the first line
of grid cells for which there are both source and fill elevation values. This parameter has values of "use DEM",
"use Fill", and "average". Grohman et al. (2006) state that sometimes, due to a weakened signal within these
marginal locations between the area of valid data and voids, the estimated elevation values are inaccurate. When
this is the case, it is best to use fill elevations in the transitional areas. If this isn't the case, the
"use DEM" is the better option. A compromise between the two options is to average the two elevation sources.
References:
Grohman, G., Kroenung, G. and Strebeck, J., 2006. Filling SRTM voids: The delta surface fill method. Photogrammetric Engineering and Remote Sensing, 72(3), pp.213-216.
See Also: FillMissingData
Parameters:
Flag | Description |
---|---|
--dem | Name of the input raster DEM file, containing the void areas |
--fill | Name of the input fill DEM file, containing the values used to fill the void areas in the other DEM |
-o, --output | Name of the output void-filled DEM file |
--mean_plane_dist | Distance to void edge at which the mean-plane value is used as an offset, measured in grid cells |
--edge_treatment | How should void-edge cells be treated? Options include 'use DEM' (default), 'use Fill', 'average' |
--weight_value | Weight value used for IDW interpolation (default is 2.0) |
Python function:
wbt.dem_void_filling(
dem,
fill,
output,
mean_plane_dist=20,
edge_treatment="use DEM",
weight_value=2.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=DemVoidFilling --dem=DEM.tif ^
--fill=fill_DEM.tif --output=dem_fused.tif --mean_plane_dist=25 ^
--weight_value=1.0
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 24/05/2022
Last Modified: 09/02/2023
DevFromMeanElev
This tool can be used to calculate the difference between the elevation of each grid cell and the mean elevation of the centering local neighbourhood, normalized by standard deviation. Therefore, this index of topographic residual is essentially equivalent to a local z-score. This attribute measures the relative topographic position as a fraction of local relief, and so is normalized to the local surface roughness. DevFromMeanElev utilizes an integral image approach (Crow, 1984) to ensure highly efficient filtering that is invariant with filter size.
The user must specify the name (--dem
) of the input digital elevation model (DEM), the
name of the output file (--output
), and the size of the neighbourhood in the x and y
directions (--filterx
and --filtery
), measured in grid size.
While DevFromMeanElev calculates the deviation from mean elevation (DEV) at a single, user-defined scale, the MaxElevationDeviation tool can be used to output the per-pixel maximum DEV value across a range of input scales.
See Also: DiffFromMeanElev, MaxElevationDeviation
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.dev_from_mean_elev(
dem,
output,
filterx=11,
filtery=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=DevFromMeanElev -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--filter=25
Author: Dr. John Lindsay
Created: 21/06/2017
Last Modified: 30/01/2020
DiffFromMeanElev
This tool can be used to calculate the difference between the elevation of each grid cell and the mean elevation of the centering local neighbourhood. This is similar to what a high-pass filter calculates for imagery data, but is intended to work with DEM data instead. This attribute measures the relative topographic position. DiffFromMeanElev utilizes an integral image approach (Crow, 1984) to ensure highly efficient filtering that is invariant with filter size.
The user must specify the name (--dem
) of the input digital elevation model (DEM), the
name of the output file (--output
), and the size of the neighbourhood in the x and y
directions (--filterx
and --filtery
), measured in grid size.
While DevFromMeanElev calculates the DIFF at a single, user-defined scale, the MaxDifferenceFromMean tool can be used to output the per-pixel maximum DIFF value across a range of input scales.
See Also: DevFromMeanElev, MaxDifferenceFromMean
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.diff_from_mean_elev(
dem,
output,
filterx=11,
filtery=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=DiffFromMeanElev -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--filter=25
Author: Dr. John Lindsay
Created: 25/06/2017
Last Modified: 30/01/2020
DifferenceCurvature
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the difference curvature from a digital elevation model (DEM). Difference curvature is half of the difference between profile and tangential curvatures, sometimes called the vertical and horizontal curvatures (Shary, 1995). This variable has an unbounded range that can take either positive or negative values. Florinsky (2017) states that difference curvature measures the extent to which the relative deceleration of flows (measured by kv) is higher than flow convergence at a given point of the topographic surface. Difference curvature is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
See Also:
ProfileCurvature, TangentialCurvature, Rotor, MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--log | Display output values using a log-scale |
--zfactor | Z conversion factor |
Python function:
wbt.difference_curvature(
dem,
output,
log=False,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=DifferenceCurvature -i=DEM.tif ^
-o=output.tif --log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 11/01/2022
Last Modified: 28/11/2022
DirectionalRelief
This tool calculates the relief for each grid cell in a digital elevation model (DEM) in a specified direction.
Directional relief is an index of the degree to which a DEM grid cell is higher or lower than its surroundings.
It is calculated by subtracting the elevation of a DEM grid cell from the average elevation of those cells which
lie between it and the edge of the DEM in a specified compass direction. Thus, positive values indicate that a
grid cell is lower than the average elevation of the grid cells in a specific direction (i.e. relatively sheltered),
whereas a negative directional relief indicates that the grid cell is higher (i.e. relatively exposed). The
algorithm is based on a modification of the procedure described by Lapen and Martz (1993). The modifications
include: (1) the ability to specify any direction between 0-degrees and 360-degrees (--azimuth
), and (2) the ability to use
a distance-limited search (--max_dist
), such that the ray-tracing procedure terminates before the DEM edge is
reached for longer search paths. The algorithm works by tracing a ray from each grid cell in the direction of
interest and evaluating the average elevation along the ray. Linear interpolation is used to estimate the elevation
of the surface where a ray does not intersect the DEM grid precisely at one of its nodes. The user must specify the
name of an input DEM raster file, the output raster name, and a hypothetical wind direction. Furthermore, the user
is able to constrain the maximum search distance for the ray tracing. If no maximum search distance is specified,
each ray will be traced to the edge of the DEM. The units of the output image are the same as the input DEM.
Ray-tracing is a highly computationally intensive task and therefore this tool may take considerable time to operate for larger sized DEMs. This tool is parallelized to aid with computational efficiency. NoData valued grid cells in the input image will be assigned NoData values in the output image. The output raster is of the float data type and continuous data scale. Directional relief is best displayed using the blue-white-red bipolar palette to distinguish between the positive and negative values that are present in the output.
Reference:
Lapen, D. R., & Martz, L. W. (1993). The measurement of two simple topographic indices of wind sheltering-exposure from raster digital elevation models. Computers & Geosciences, 19(6), 769-779.
See Also: FetchAnalysis, HorizonAngle, RelativeAspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--azimuth | Wind azimuth in degrees |
--max_dist | Optional maximum search distance (unspecified if none; in xy units) |
Python function:
wbt.directional_relief(
dem,
output,
azimuth=0.0,
max_dist=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=DirectionalRelief -v ^
--wd="/path/to/data/" -i='input.tif' -o=output.tif ^
--azimuth=315.0
Author: Dr. John Lindsay
Created: 07/07/2017
Last Modified: 03/09/2020
DownslopeIndex
This tool can be used to calculate the downslope index described by Hjerdt et al. (2004). The downslope index is a measure of the slope gradient between a grid cell and some downslope location (along the flowpath passing through the upslope grid cell) that represents a specified vertical drop (i.e. a potential head drop). The index has been shown to be useful for hydrological, geomorphological, and biogeochemical applications.
The user must specify the name of a digital elevaton model (DEM) raster. This DEM
should be have been pre-processed to remove artifact topographic depressions and flat
areas. The user must also specify the head potential drop (d), and the output type. The
output type can be either 'tangent
', 'degrees
', 'radians
', or 'distance
'. If
'distance
' is selected as the output type, the output grid actually represents the
downslope flowpath length required to drop d meters from each grid cell. Linear
interpolation is used when the specified drop value is encountered between two adjacent
grid cells along a flowpath traverse.
Notice that this algorithm is affected by edge contamination. That is, for some grid cells, the edge of the grid will be encountered along a flowpath traverse before the specified vertical drop occurs. In these cases, the value of the downslope index is approximated by replacing d with the actual elevation drop observed along the flowpath. To avoid this problem, the entire watershed containing an area of interest should be contained in the DEM.
Grid cells containing NoData values in any of the input images are assigned the NoData value in the output raster. The output raster is of the float data type and continuous data scale.
Reference:
Hjerdt, K.N., McDonnell, J.J., Seibert, J. Rodhe, A. (2004) A new topographic index to quantify downslope controls on local drainage, Water Resources Research, 40, W05602, doi:10.1029/2004WR003130.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--drop | Vertical drop value (default is 2.0) |
--out_type | Output type, options include 'tangent', 'degrees', 'radians', 'distance' (default is 'tangent') |
Python function:
wbt.downslope_index(
dem,
output,
drop=2.0,
out_type="tangent",
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=DownslopeIndex -v --wd="/path/to/data/" ^
--dem=pointer.tif -o=dsi.tif --drop=5.0 --out_type=distance
Author: Dr. John Lindsay
Created: July 17, 2017
Last Modified: 12/10/2018
EdgeDensity
This tool calculates the density of edges, or breaks-in-slope within an input digital elevation model (DEM).
A break-in-slope occurs between two neighbouring grid cells if the angular difference between their normal
vectors is greater than a user-specified threshold value (--norm_diff
). EdgeDensity calculates the proportion
of edge cells within the neighbouring window, of square filter dimension --filter
, surrounding each grid cell.
Therefore, EdgeDensity
is a measure of how complex the topographic surface is within a local neighbourhood.
It is therefore a measure of topographic texture. It will take a value near 0.0 for smooth sites and 1.0 in areas
of high surface roughness or complex topography.
The distribution of EdgeDensity is highly dependent upon the value of the norm_diff
used in the calculation. This
threshold may require experimentation to find an appropriate value and is likely dependent upon the topography and
source data. Nonetheless, experience has shown that EdgeDensity provides one of the best measures of surface
texture of any of the available roughness tools.
See Also: CircularVarianceOfAspect, MultiscaleRoughness, SurfaceAreaRatio, RuggednessIndex
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filter | Size of the filter kernel |
--norm_diff | Maximum difference in normal vectors, in degrees |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.edge_density(
dem,
output,
filter=11,
norm_diff=5.0,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=EdgeDensity -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --filter=15 --norm_diff=20.0 ^
--num_iter=4
Author: Dr. John Lindsay
Created: 27/01/2019
Last Modified: 03/09/2020
ElevAbovePit
This tool will calculate the elevation of each grid cell in a digital elevation model (DEM) above the nearest downslope pit cell or grid edge cell, depending on which is encountered first during the flow-path traverse. The resulting image is therefore a measure of relative landscape position. The user must specify the names of a D8 flow pointer grid, a DEM file, and the output file. The flow pointer grid must be derived using the D8 flow algorithm.
See Also: ElevationAboveStream
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.elev_above_pit(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ElevAbovePit -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 13/07/2017
Last Modified: 12/10/2018
ElevPercentile
Elevation percentile (EP) is a measure of local topographic position (LTP). It expresses the vertical position for a digital elevation model (DEM) grid cell (z0) as the percentile of the elevation distribution within the filter window, such that:
EP = counti∈C(zi > z0) x (100 / nC)
where z0 is the elevation of the window's center grid cell, zi is the elevation of cell i contained within the neighboring set C, and nC is the number of grid cells contained within the window.
EP is unsigned and expressed as a percentage, bound between 0% and 100%. Quantile-based estimates (e.g., the median and interquartile range) are often used in nonparametric statistics to provide data variability estimates without assuming the distribution is normal. Thus, EP is largely unaffected by irregularly shaped elevation frequency distributions or by outliers in the DEM, resulting in a highly robust metric of LTP. In fact, elevation distributions within small to medium sized neighborhoods often exhibit skewed, multimodal, and non-Gaussian distributions, where the occurrence of elevation errors can often result in distribution outliers. Thus, based on these statistical characteristics, EP is considered one of the most robust representation of LTP.
The algorithm implemented by this tool uses the relatively efficient running-histogram filtering algorithm of Huang
et al. (1979). Because most DEMs contain floating point data, elevation values must be rounded to be binned. The
--sig_digits
parameter is used to determine the level of precision preserved during this binning process. The
algorithm is parallelized to further aid with computational efficiency.
Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx
and --filtery
flags.
These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).
References:
Newman, D. R., Lindsay, J. B., and Cockburn, J. M. H. (2018). Evaluating metrics of local topographic position for multiscale geomorphometric analysis. Geomorphology, 312, 40-50.
Huang, T., Yang, G.J.T.G.Y. and Tang, G., 1979. A fast two-dimensional median filtering algorithm. IEEE Transactions on Acoustics, Speech, and Signal Processing, 27(1), pp.13-18.
See Also: DevFromMeanElev, DiffFromMeanElev
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
--sig_digits | Number of significant digits |
Python function:
wbt.elev_percentile(
dem,
output,
filterx=11,
filtery=11,
sig_digits=2,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ElevPercentile -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --filter=25
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 02/04/2019
ElevRelativeToMinMax
This tool can be used to express the elevation of a grid cell in a digital elevation model (DEM) as a percentage of the relief between the DEM minimum and maximum values. As such, it provides a basic measure of relative topographic position.
See Also: ElevRelativeToWatershedMinMax, ElevationAboveStream, ElevAbovePit
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.elev_relative_to_min_max(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ElevRelativeToMinMax -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 12/07/2017
Last Modified: 12/10/2018
ElevRelativeToWatershedMinMax
This tool can be used to express the elevation of a grid cell in a digital elevation model (DEM) as a percentage
of the relief between the watershed minimum and maximum values. As such, it provides a basic
measure of relative topographic position. The user must specify the names of DEM (--dem
) and watersheds (--watersheds
)
raster files.
See Also: ElevRelativeToMinMax, ElevationAboveStream, ElevAbovePit
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--watersheds | Input raster watersheds file |
-o, --output | Output raster file |
Python function:
wbt.elev_relative_to_watershed_min_max(
dem,
watersheds,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ElevRelativeToWatershedMinMax -v ^
--wd="/path/to/data/" --dem=DEM.tif --watersheds=watershed.tif ^
-o=output.tif
Author: Dr. John Lindsay
Created: 12/07/2017
Last Modified: 12/10/2018
EmbankmentMapping
This tool can be used to map and/or remove road embankments from an input fine-resolution digital elevation
model (--dem
). Fine-resolution LiDAR DEMs can represent surface features such as road and railway
embankments with high fidelity. However, transportation embankments are problematic for several
environmental modelling applications, including soil an vegetation distribution mapping, where the pre-embankment
topography is the contolling factor. The algorithm utilizes repositioned (--search_dist
) transportation
network cells, derived from rasterizing a transportation vector (--road_vec
), as seed points in a
region-growing operation. The embankment region grows based on derived morphometric parameters, including
road surface width (--min_road_width
), embankment width (--typical_width
and --max_width
), embankment
height (--max_height
), and absolute slope (--spillout_slope
). The tool can be run in two modes. By default
the tool will simply map embankment cells, with a Boolean output raster. If, however, the --remove_embankments
flag is specified, the tool will instead output a DEM for which the mapped embankment grid cells have been
excluded and new surfaces have been interpolated based on the surrounding elevation values (see below).
Hillshade from original DEM:
Hillshade from embankment-removed DEM:
References:
Van Nieuwenhuizen, N, Lindsay, JB, DeVries, B. 2021. Automated mapping of transportation embankments in fine-resolution LiDAR DEMs. Remote Sensing. 13(7), 1308; https://doi.org/10.3390/rs13071308
See Also: RemoveOffTerrainObjects, SmoothVegetationResidual
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--road_vec | Input vector polygons file |
-o, --output | Output raster file |
--search_dist | Search distance used to reposition transportation vectors onto road embankments (in map units) |
--min_road_width | Minimum road width; this is the width of the paved road surface (in map units) |
--typical_width | Typical embankment width; this is the maximum width of an embankment with roadside ditches (in map units) |
--max_height | Typical embankment maximum height; this is the height a typical embankment with roadside ditches (in map units) |
--max_width | Maximum embankment width, typically where embankments traverse steep-sided valleys (in map units) |
--max_increment | Maximum upwards increment between neighbouring cells on an embankment (in elevation units) |
--spillout_slope | Spillout slope (in degrees) |
--remove_embankments | Optional flag indicating whether to output a DEM with embankments removed (true) or an embankment raster map (false) |
Python function:
wbt.embankment_mapping(
dem,
road_vec,
output,
search_dist=2.5,
min_road_width=6.0,
typical_width=30.0,
max_height=2.0,
max_width=60.0,
max_increment=0.05,
spillout_slope=4.0,
remove_embankments=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=EmbankmentMapping -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif ^
--search_dist=1.0 --min_road_width=6.0 --typical_width=30.0 ^
--max_height=2.0 --max_width=60.0 --max_increment=0.05 ^
--spillout_slope=4.0 --remove_embankments=true
Author: Dr. John Lindsay and Nigel Van Nieuwenhuizen
Created: 21/09/2020
Last Modified: 05/10/2020
ExposureTowardsWindFlux
This tool creates a new raster in which each grid cell is assigned the exposure of the land-surface to
a hypothetical wind flux. It can be conceptualized as the angle between a plane orthogonal to the wind
and a plane that represents the local topography at a grid cell (Bohner and Antonic, 2007). The user must specify
the names of the input digital elevation model (--dem
) and output file (--output
), as well as the
dominant wind azimuth (--azimuth
) and a maximum search distance (--max_dist
) used to calclate the horizon
angle. Notice that the specified azimuth represents a regional average wind direction.
Exposure towards the sloped wind flux essentially combines the relative terrain aspect and the maximum upwind slope (i.e. horizon angle). This terrain attribute accounts for land-surface orientation, relative to the wind, and shadowing effects of distant topographic features but does not account for deflection of the wind by topography. This tool should not be used on very extensive areas over which Earth's curvature must be taken into account. DEMs in projected coordinate systems are preferred.
Algorithm Description:
Exposure is measured based on the equation presented in Antonic and Legovic (1999):
cos(E) = cos(S) sin(H) + sin(S) cos(H) cos(Az - A)
Where, E is angle between a plane defining the local terrain and a plane orthogonal to the wind flux, S is the terrain slope, A is the terrain aspect, Az is the azimuth of the wind flux, and H is the horizon angle of the wind flux, which is zero when only the horizontal component of the wind flux is accounted for.
Exposure images are best displayed using a greyscale or bipolar palette to distinguish between the positive and negative values that are present in the output.
References:
Antonić, O., & Legović, T. 1999. Estimating the direction of an unknown air pollution source using a digital elevation model and a sample of deposition. Ecological modelling, 124(1), 85-95.
Böhner, J., & Antonić, O. 2009. Land-surface parameters specific to topo-climatology. Developments in Soil Science, 33, 195-226.
See Also: RelativeAspect
Parameters:
Flag | Description |
---|---|
-d, --dem | Name of the input DEM raster file |
-o, --output | Name of the output raster file |
--azimuth | Wind azimuth, in degrees |
--max_dist | Optional maximum search distance. Minimum value is 5 x cell size |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.exposure_towards_wind_flux(
dem,
output,
azimuth="",
max_dist="",
zfactor="",
callback=default_callback
)
Command-line Interface:
-./whitebox_tools -r=ExposureTowardsWindFlux -dem=input.tif ^
-o=exposure.tif --azimuth=35.0 --max_dist=500.0
Author: Whitebox Geospatial Inc. (c)
Created: 20/07/2021
Last Modified: 20/07/2021
FeaturePreservingSmoothing
This tool implements a highly modified form of the DEM de-noising algorithm described by Sun et al. (2007). It is very effective at removing surface roughness from digital elevation models (DEMs), without significantly altering breaks-in-slope. As such, this tool should be used for smoothing DEMs rather than either smoothing with low-pass filters (e.g. mean, median, Gaussian filters) or grid size coarsening by resampling. The algorithm works by 1) calculating the surface normal 3D vector of each grid cell in the DEM, 2) smoothing the normal vector field using a filtering scheme that applies more weight to neighbours with lower angular difference in surface normal vectors, and 3) uses the smoothed normal vector field to update the elevations in the input DEM.
Sun et al.'s (2007) original method was intended to work on input point clouds and fitted triangular irregular networks (TINs). The algorithm has been modified to work with input raster DEMs instead. In so doing, this algorithm calculates surface normal vectors from the planes fitted to 3 x 3 neighbourhoods surrounding each grid cell, rather than the triangular facet. The normal vector field smoothing and elevation updating procedures are also based on raster filtering operations. These modifications make this tool more efficient than Sun's original method, but will also result in a slightly different output than what would be achieved with Sun's method.
The user must specify the values of three key parameters, including the filter size
(--filter
), the normal difference threshold (--norm_diff
), and the number of
iterations (--num_iter
). Lindsay et al. (2019) found that the degree of smoothing
was less impacted by the filter size than it was either the normal difference threshold
and the number of iterations. A filter size of 11, the default value, tends to work
well in many cases. To increase the level of smoothing applied to the DEM, consider
increasing the normal difference threshold, i.e. the angular difference in normal vectors
between the center cell of a filter window and a neighbouring cell. This parameter determines
which neighbouring values are included in a filtering operation and higher values will
result in a greater number of neighbouring cells included, and therefore smooother surfaces.
Similarly, increasing the number of iterations from the default value of 3 to upwards of
5-10 will result in significantly greater smoothing.
Before smoothing treatment:
After smoothing treatment with FPS:
For a video tutorial on how to use the FeaturePreservingSmoothing tool, please see this YouTube video.
Reference:
Lindsay JB, Francioni A, Cockburn JMH. 2019. LiDAR DEM smoothing and the preservation of drainage features. Remote Sensing, 11(16), 1926; DOI: 10.3390/rs11161926.
Sun, X., Rosin, P., Martin, R., & Langbein, F. (2007). Fast and effective feature-preserving mesh denoising. IEEE Transactions on Visualization & Computer Graphics, (5), 925-938.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filter | Size of the filter kernel |
--norm_diff | Maximum difference in normal vectors, in degrees |
--num_iter | Number of iterations |
--max_diff | Maximum allowable absolute elevation change (optional) |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.feature_preserving_smoothing(
dem,
output,
filter=11,
norm_diff=15.0,
num_iter=3,
max_diff=0.5,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=FeaturePreservingSmoothing -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif --filter=15 ^
--norm_diff=20.0 --num_iter=4
Author: Dr. John Lindsay
Created: 23/11/2017
Last Modified: 03/09/2020
FetchAnalysis
This tool creates a new raster in which each grid cell is assigned the distance, in meters, to the nearest topographic obstacle in a specified direction. It is a modification of the algorithm described by Lapen and Martz (1993). Unlike the original algorithm, Fetch Analysis is capable of analyzing fetch in any direction from 0-360 degrees. The user must specify the name of an input digital elevation model (DEM) raster file, the output raster name, a hypothetical wind direction, and a value for the height increment parameter. The algorithm searches each grid cell in a path following the specified wind direction until the following condition is met:
Ztest >= Zcore + DI
where Zcore is the elevation of the grid cell at which fetch is being determined, Ztest is the elevation of the grid cell being tested as a topographic obstacle, D is the distance between the two grid cells in meters, and I is the height increment in m/m. Lapen and Martz (1993) suggest values for I in the range of 0.025 m/m to 0.1 m/m based on their study of snow re-distribution in low-relief agricultural landscapes of the Canadian Prairies. If the directional search does not identify an obstacle grid cell before the edge of the DEM is reached, the distance between the DEM edge and Zcore is entered. Edge distances are assigned negative values to differentiate between these artificially truncated fetch values and those for which a valid topographic obstacle was identified. Notice that linear interpolation is used to estimate the elevation of the surface where a ray (i.e. the search path) does not intersect the DEM grid precisely at one of its nodes.
Ray-tracing is a highly computationally intensive task and therefore this tool may take considerable time to operate for larger sized DEMs. This tool is parallelized to aid with computational efficiency. NoData valued grid cells in the input image will be assigned NoData values in the output image. Fetch Analysis images are best displayed using the blue-white-red bipolar palette to distinguish between the positive and negative values that are present in the output.
Reference:
Lapen, D. R., & Martz, L. W. (1993). The measurement of two simple topographic indices of wind sheltering-exposure from raster digital elevation models. Computers & Geosciences, 19(6), 769-779.
See Also: DirectionalRelief, HorizonAngle, RelativeAspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--azimuth | Wind azimuth in degrees in degrees |
--hgt_inc | Height increment value |
Python function:
wbt.fetch_analysis(
dem,
output,
azimuth=0.0,
hgt_inc=0.05,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=FetchAnalysis -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif --azimuth=315.0
Author: Dr. John Lindsay
Created: 07/07/2017
Last Modified: 03/09/2020
FillMissingData
This tool can be used to fill in small gaps in a raster or digital elevation model (DEM). The gaps, or holes, must have recognized NoData values. If gaps do not currently have this characteristic, use the SetNodataValue tool and ensure that the data are stored using a raster format that supports NoData values. All valid, non-NoData values in the input raster will be assigned the same value in the output image.
The algorithm uses an inverse-distance weighted (IDW) scheme based on the valid values on the edge of
NoData gaps to estimate gap values. The user must specify the filter size (--filter
), which determines
the size of gap that is filled, and the IDW weight (--weight
).
The filter size, specified in grid cells, is used to determine how far the algorithm will search for valid, non-NoData values. Therefore, setting a larger filter size allows for the filling of larger gaps in the input raster.
The --no_edges
flag can be used to exclude NoData values that are connected to the edges of the raster. It is
usually the case that irregularly shaped DEMs have large regions of NoData values along the containing raster
edges. This flag can be used to exclude these regions from the gap-filling operation, leaving only interior gaps
for filling.
See Also: SetNodataValue
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filter | Filter size (cells) |
--weight | IDW weight value |
--no_edges | Optional flag indicating whether to exclude NoData cells in edge regions |
Python function:
wbt.fill_missing_data(
i,
output,
filter=11,
weight=2.0,
no_edges=True,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=FillMissingData -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif --filter=25 ^
--weight=1.0 --no_edges
Author: Dr. John Lindsay
Created: 14/06/2017
Last Modified: 12/10/2018
FindRidges
This tool can be used to identify ridge cells in a digital elevation model (DEM). Ridge cells are those that
have lower neighbours either to the north and south or the east and west. Line thinning can optionally be used
to create single-cell wide ridge networks by specifying the --line_thin
parameter.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--line_thin | Optional flag indicating whether post-processing line-thinning should be performed |
Python function:
wbt.find_ridges(
dem,
output,
line_thin=True,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=FindRidges -v --wd="/path/to/data/" ^
--dem=pointer.tif -o=out.tif --line_thin
Author: Dr. John Lindsay
Created: 04/12/2017
Last Modified: 18/10/2019
GaussianCurvature
This tool calculates the Gaussian curvature from a digital elevation model (DEM). Gaussian curvature is the product of maximal and minimal curvatures, and retains values in each point of the topographic surface after its bending without breaking, stretching, and compressing (Florinsky, 2017). Gaussian curvature is measured in units of m-2.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
TangentialCurvature, ProfileCurvature, PlanCurvature, MeanCurvature, MinimalCurvature, MaximalCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--log | Display output values using a log-scale |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.gaussian_curvature(
dem,
output,
log=False,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=GaussianCurvature -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 12/01/2022
Last Modified: 15/01/2022
GaussianScaleSpace
This tool uses the fast Gaussian approximation algorithm to produce scaled land-surface parameter (LSP)
measurements from an input DEM (--dem
). The algorithm iterates over scales
defined by an initial scale (--sigma
), a step size (--step) and a
number of scales (--num_steps)/. After smoothing the input DEM to the target sigma,
a 3x3 window is used to calculate a variety of LSPs (--lsp
).
LSP options include local derivatives (Elevation, Slope, Aspect, Eastness, Northness,
Mean curvature, Plan curvature, Profile curvature, Tangential curvature and Total curvature),
Hillshade, and Difference from mean elevation, all as defined in Wilson (2018), and Anisotropy
of topographic position (Newman et al., 2018), and Ruggedness (Riley et al., 1999). An initial
sigma value of 0 will compute the LSP without Gaussian smoothing. The step size can be and
positive number, however, sigam values < 0.5 and duplicated scales are skipped due to a
minimum filter size limitation, or the scale discretization of the fast gaussian approximation.
The LSP values are then transformed to z-scores using the population of values at a single
scale, are are evaluated to identify the optimal scale defined as the maximum absolute z-score
for each cell. The final outputs are three rasters: the first containing the z-score at the
optimal scale (z_opt), the sigma value at the optimal scale (g_opt), and the LSP value at the
optimal scale (v_opt). These all need to be specified using the (--output_zscore
),
(--output_scale
), and (--output
) flags respectively. Additionally, a vector file of
points (--points
) can optionally be provided to generate scale signatures for the provided point
locations.
Due to the use of the integral image, edge effects can be problematic; especially when 'NoData' values are found. It is recommended that 'NoData' holes filled during pre-processing. Irregular shaped data (i.e., non-rectangular DEMs) are buffered with a crude check for 'NoData' values at the filter edge in the 8 cardinal directions to buffer the edges. This should be adequate for most data, additional buffer masks may be required.
Reference:
Wilson, J. P. (2018). Environmental-applications-of-digital-terrain-modeling. Wiley Blackwell. Newman, D. R., Lindsay, J. B., & Cockburn, J. M. H. (2018). Measuring Hyperscale Topographic Anisotropy as a Continuous Landscape Property. Geosciences, 8(278). https://doi.org/10.3390/geosciences8080278
Riley, S. J., DeGloria, S. D., and Elliot, R. (1999). Index that quantifies topographic heterogeneity.Intermountain Journal of Sciences, 5(1-4), 23-27.
See Also: MaxDifferenceFromMean, MaxAnisotropyDev, ProfileCurvature, TangentialCurvature, RuggednessIndex
Parameters:
Flag | Description |
---|---|
-d, --dem | Name of the input DEM raster file |
-p, --points | Name of the input vector points shapefile |
-o, --output | Name of the output land-surface parameter raster file |
--output_zscore | Name of the output z-score raster file |
--output_scale | Name of the output scale raster file |
--sigma | Initial sigma value (cells) |
--step | Step size as any positive non-zero integer |
--num_steps | Number of steps |
--lsp | Output land-surface parameter; one of 'AnisotropyLTP', 'Aspect', 'DiffMeanElev', 'Eastness', 'Elevation', 'Hillshade', 'MeanCurvature', 'Northness', 'PlanCurvature', 'ProfileCurvature', 'Ruggedness', 'Slope', 'TanCurvature', 'TotalCurvature' |
--z_factor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.gaussian_scale_space(
dem,
output,
output_zscore,
output_scale,
points=None,
sigma=0.5,
step=0.5,
num_steps=10,
lsp="Slope",
z_factor=None,
callback=default_callback
)
Command-line Interface:
-./whitebox_tools -r=GaussianScaleSpace --dem=DEM.tif ^
--output=slope.tif --output_zscore=slope_z.tif ^
--output_scale=slope_scale.tif --sigma=0.5 --step=1.0 ^
--num_steps=100 --lsp='Slope'
Author: Daniel Newman
Created: 01/01/2021
Last Modified: 01/01/2021
GeneratingFunction
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the generating function (Shary and Stepanov, 1991) from a digital elevation model (DEM). Florinsky (2016) describes generating function as a measure for the deflection of tangential curvature from loci of extreme curvature of the topographic surface. Florinsky (2016) demonstrated the application of this variable for identifying landscape structural lines, i.e. ridges and thalwegs, for which the generating function takes values near zero. Ridges coincide with divergent areas where generating function is approximately zero, while thalwegs are associated with convergent areas with generating function values near zero. This variable has positive values, zero or greater and is measured in units of m-2.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Raw generating function values are often challenging to visualize given their range and magnitude,
and as such the user may opt to log-transform the output raster (--log
). Transforming the values
applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
This tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems, however, this tool cannot use the same 3x3 polynomial fitting method for equal angle grids, also described by Florinsky (2016), that is used by the other curvature tools in this software. That is because generating function uses 3rd order partial derivatives, which cannot be calculated using the 9 elevations in a 3x3; more elevation values are required (i.e. a 5x5 window). Thus, this tool uses the same 5x5 method used for DEMs in projected coordinate systems, and calculates the average linear distance between neighbouring cells in the vertical and horizontal directions using the Vincenty distance function. Note that this may cause a notable slow-down in algorithm performance and has a lower accuracy than would be achieved using an equal angle method, because it assumes a square pixel (in linear units).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Koenderink, J. J., and Van Doorn, A. J. (1992). Surface shape and curvature scales. Image and vision computing, 10(8), 557-564.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
Shary P. A. and Stepanov I. N. (1991) Application of the method of second derivatives in geology. Transactions (Doklady) of the USSR Academy of Sciences, Earth Science Sections 320: 87–92.
See Also:
ShapeIndex, MinimalCurvature, MaximalCurvature, TangentialCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--log | Display output values using a log-scale |
--zfactor | Z conversion factor |
Python function:
wbt.generating_function(
dem,
output,
log=False,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=GeneratingFunction -i=DEM.tif ^
-o=output.tif --log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 11/01/2022
Last Modified: 28/11/2022
Geomorphons
This tool can be used to perform a geomorphons landform classification based on an input digital elevation
model (--dem
). The geomorphons concept is based on line-of-sight analysis for the eight
topographic profiles in the cardinal directions surrounding each grid cell in the input DEM. The relative
sizes of the zenith angle of a profile's maximum elevation angle (i.e. horizon angle) and the nadir angle of
a profile's minimum elevation angle are then used to generate a ternary (base-3) digit: 0 when the nadir
angle is less than the zenith angle, 1 when the two angles differ by less than a user-defined flatness
threshold (--threshold
), and 2 when the nadir angle is greater than the zenith angle. A ternary number
is then derived from the digits assigned to each of the eight profiles, with digits sequenced counter-clockwise
from east. This ternary number forms the geomorphons code assigned to the grid cell. There are
38 = 6561 possible codes, although many of these codes are equivalent geomorphons through
rotations and reflections. Some of the remaining geomorphons also rarely if ever occur in natural
topography. Jasiewicz et al. (2013) identified 10 common landform types by reclassifying related
geomorphons codes. The user may choose to output these common forms (--forms
) rather than the
the raw ternary code. These landforms include:
Value | Landform Type |
---|---|
1 | Flat |
2 | Peak (summit) |
3 | Ridge |
4 | Shoulder |
5 | Spur (convex) |
6 | Slope |
7 | Hollow (concave) |
8 | Footslope |
9 | Valley |
10 | Pit (depression) |
One of the main advantages of the geomrophons method is that, being based on minimum/maximum elevation
angles, the scale used to estimate the landform type at a site adapts to the surrounding terrain.
In principle, choosing a large value of search distance (--search
) should result in
identification of a landform element regardless of its scale.
An experimental feature has been added to correct for global inclination. Global inclination
biases the flatness threshold angle becasue it is measured relative to the z-axis, especially
in locally flat areas. Including the --residuals
flag "flattens" the input by converting
elevation to residuals of a 2-d linear model.
Reference:
Jasiewicz, J., and Stepinski, T. F. (2013). Geomorphons — a pattern recognition approach to classification and mapping of landforms. Geomorphology, 182, 147-156.
See Also: PennockLandformClass
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--search | Look up distance (in cells) |
--threshold | Flatness threshold for the classification function (in degrees) |
--fdist | Distance (in cells) to begin reducing the flatness threshold to avoid problems with pseudo-flat lines-of-sight |
--skip | Distance (in cells) to begin calculating lines-of-sight |
-f, --forms | Classify geomorphons into 10 common land morphologies, else output ternary pattern |
--residuals | Convert elevation to residuals of a linear model |
Python function:
wbt.geomorphons(
dem,
output,
search=50,
threshold=0.0,
fdist=0,
skip=0,
forms=True,
residuals=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Geomorphons -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --search=50 --threshold=0.0 ^
--tdist=0.0 --forms
Author: Daniel Newman
Created: 21/09/2018
Last Modified: 07/06/2022
Hillshade
This tool performs a hillshade operation (also called shaded relief) on an input digital elevation model (DEM).
The user must specify the name of the input DEM and the output hillshade image name. Other parameters that must
be specified include the illumination source azimuth (--azimuth
), or sun direction (0-360 degrees), the
illumination source altitude (--altitude
; i.e. the elevation of the sun above the horizon, measured as an angle
from 0 to 90 degrees) and the Z conversion factor (--zfactor
). The Z conversion factor is only important
when the vertical and horizontal units are not the same in the DEM, and the DEM is in a projected coordinate system. When this is the case,
the algorithm will multiply each elevation in the DEM by the Z conversion factor. If the
DEM is in the geographic coordinate system (latitude and longitude), the following equation
is used:
zfactor = 1.0 / (111320.0 x cos(mid_lat))
where mid_lat
is the latitude of the centre of the raster, in radians.
The hillshade value (HS) of a DEM grid cell is calculate as:
HS = tan(s) / [1 - tan(s)2]0.5 x [sin(Alt) / tan(s) - cos(Alt) x sin(Az - a)]
where s and a are the local slope gradient and aspect (orientation) respectively and Alt and Az are the illumination source altitude and azimuth respectively. Slope and aspect are calculated using Horn's (1981) 3rd-order finate difference method.
Reference:
Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, in Terrain Analysis: Principles and Applications, edited by J. P. Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.
See Also: HypsometricallyTintedHillshade, MultidirectionalHillshade, Aspect, Slope
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--azimuth | Illumination source azimuth in degrees |
--altitude | Illumination source altitude in degrees |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.hillshade(
dem,
output,
azimuth=315.0,
altitude=30.0,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Hillshade -v --wd="/path/to/data/" ^
-i=DEM.tif -o=output.tif --azimuth=315.0 --altitude=30.0
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 03/09/2020
HorizonAngle
This tool calculates the horizon angle (Sx), i.e. the maximum slope along a specified azimuth (0-360 degrees) for each grid cell in an input digital elevation model (DEM). Horizon angle is sometime referred to as the maximum upwind slope in wind exposure/sheltering studies. Positive values can be considered sheltered with respect to the azimuth and negative values are exposed. Thus, Sx is a measure of exposure to a wind from a specific direction. The algorithm works by tracing a ray from each grid cell in the direction of interest and evaluating the slope for each location in which the DEM grid is intersected by the ray. Linear interpolation is used to estimate the elevation of the surface where a ray does not intersect the DEM grid precisely at one of its nodes.
The user is able to constrain the maximum search distance (--max_dist
) for the ray tracing by entering a valid maximum
search distance value (in the same units as the X-Y coordinates of the input raster DEM). If the maximum search distance
is left blank, each ray will be traced to the edge of the DEM, which will add to the computational time.
Maximum upwind slope should not be calculated for very extensive areas over which the Earth's curvature must be taken into account. Also, this index does not take into account the deflection of wind by topography. However, averaging the horizon angle over a window of directions can yield a more robust measure of exposure, compensating for the deflection of wind from its regional average by the topography. For example, if you are interested in measuring the exposure of a landscape to a northerly wind, you could perform the following calculation:
Sx(N) = [Sx(345)+Sx(350)+Sx(355)+Sx(0)+Sx(5)+Sx(10)+Sx(15)] / 7.0
Ray-tracing is a highly computationally intensive task and therefore this tool may take considerable time to operate for larger sized DEMs. Maximum upwind slope is best displayed using a Grey scale palette that is inverted.
Horizon angle is best visualized using a white-to-black palette and rescaled from approximately -10 to 70 (see below for an example of horizon angle calculated at a 150-degree azimuth).
See Also: TimeInDaylight
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--azimuth | Azimuth, in degrees |
--max_dist | Optional maximum search distance (unspecified if none; in xy units). Minimum value is 5 x cell size |
Python function:
wbt.horizon_angle(
dem,
output,
azimuth=0.0,
max_dist=100.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=HorizonAngle -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif --azimuth=315.0
Author: Dr. John Lindsay
Created: 07/07/2017
Last Modified: 03/09/2020
HorizonArea
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates horizon area, i.e., the area of the horizon polygon centered on each point in an input digital elevation model (DEM). Horizon area is therefore conceptually related to the viewhed and visibility_index functions. Horizon area can be thought of as an approximation of the viewshed area and is therefore faster to calculate a spatial distribution of compared with the visibility index. Horizon area is measured in hectares.
The user must specify an input DEM (dem
), the azimuth fraction (az_fraction
), the maximum search
distance (max_dist
), and the height offset of the observer (observer_hgt_offset
). The input DEM
should usually be a digital surface model (DSM) that contains significant off-terrain objects. Such a
model, for example, could be created using the first-return points of a LiDAR data set, or using the
lidar_digital_surface_model tool. The azimuth
fraction should be an even divisor of 360-degrees and must be between 1-45 degrees.
The tool operates by calculating horizon angle (see horizon_angle)
rasters from the DSM based on the user-specified azimuth fraction (az_fraction
). For example, if an azimuth
fraction of 15-degrees is specified, horizon angle rasters would be calculated for the solar azimuths 0,
15, 30, 45... A horizon angle raster evaluates the vertical angle between each grid cell in a DSM and a
distant obstacle (e.g. a mountain ridge, building, tree, etc.) that obscures the view in a specified
direction. In calculating horizon angle, the user must specify the maximum search distance (max_dist
),
in map units, beyond which the query for higher, more distant objects will cease. This parameter strongly
impacts the performance of the function, with larger values resulting in significantly longer processing-times.
With each evaluated direction, the coordinates of the horizon point is determined, using the azimuth and the distance to horizon, with each point then serving as a vertex in a horizon polygon. The shoelace algorithm is used to measure the area of each horizon polgon for the set of grid cells, which is then reported in the output raster.
The observer_hgt_offset
parameter can be used to add an increment to the source cell's elevation. For
example, the following image shows the spatial pattern derived from a LiDAR DSM using observer_hgt_offset = 0.0
:
Notice that there are several places, plarticularly on the flatter rooftops, where the local noise in the LiDAR DEM, associated with the individual scan lines, has resulted in a noisy pattern in the output. By adding a small height offset of the scale of this noise variation (0.15 m), we see that most of this noisy pattern is removed in the output below:
As another example, in the image below, the observer_hgt_offset
parameter has been used to measure
the pattern of the index at a typical human height (1.7 m):
Notice how at this height a much larger area becomes visible on some of the flat rooftops where a guard wall prevents further viewing areas at shorter observer heights.
See Also: SkyViewFactor, AverageHorizonDistance, SkylineAnalysis, Openness, TimeInDaylight, HorizonAngle
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--az_fraction | Azimuth fraction |
--max_dist | Maximum distance (xy units) |
--observer_hgt_offset | Oberserver height offset (z units) |
Python function:
wbt.horizon_area(
dem,
output,
az_fraction=5.0,
max_dist=9999.0,
observer_hgt_offset=0.05,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=HorizonArea -i=dem.tif -o=output.tif ^
--az_fraction=5.0 --max_dist=250.0 --observer_hgt_offset=1.75
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 09/04/2024
Last Modified: 09/04/2024
HorizontalExcessCurvature
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the horizontal excess curvature from a digital elevation model (DEM). Horizontal excess curvature is the difference of tangential (horizontal) and minimal curvatures at a location (Shary, 1995). This variable has positive values, zero or greater. Florinsky (2017) states that horizontal excess curvature measures the extent to which the bending of a normal section tangential to a contour line is larger than the minimal bending at a given point of the surface. Horizontal excess curvature is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
See Also:
TangentialCurvature, ProfileCurvature, MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--log | Display output values using a log-scale |
--zfactor | Z conversion factor |
Python function:
wbt.horizontal_excess_curvature(
dem,
output,
log=False,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=HorizontalExcessCurvature -i=DEM.tif ^
-o=output.tif --log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 11/01/2022
Last Modified: 28/11/2022
HypsometricAnalysis
This tool can be used to derive the hypsometric curve, or area-altitude curve, of one or more
input digital elevation models (DEMs) (--inputs
). A hypsometric curve is a histogram or cumulative
distribution function of elevations in a geographical area.
See Also: SlopeVsElevationPlot
Parameters:
Flag | Description |
---|---|
-i, --inputs | Input DEM files |
--watershed | Input watershed files (optional) |
-o, --output | Output HTML file (default name will be based on input file if unspecified) |
Python function:
wbt.hypsometric_analysis(
inputs,
output,
watershed=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=HypsometricAnalysis -v ^
--wd="/path/to/data/" -i="DEM1.tif;DEM2.tif" ^
--watershed="ws1.tif;ws2.tif" -o=outfile.html
Author: Dr. John Lindsay
Created: 30/01/2018
Last Modified: 12/10/2018
HypsometricallyTintedHillshade
This tool creates a hypsometrically tinted shaded relief (Swiss hillshading) image from an input digital elevation model (DEM).
The tool combines a colourized version of the DEM with varying illumination provided by a hillshade image, to
produce a composite relief model that can be used to visual topography for more effective interpretation of
landscapes. The output (--output
) of the tool is a 24-bit red-green-blue (RGB) colour image.
The user must specify the name of the input DEM and the output image name. Other parameters that must
be specified include the illumination source azimuth (--azimuth
), or sun direction (0-360 degrees), the
illumination source altitude (--altitude
; i.e. the elevation of the sun above the horizon, measured as an angle
from 0 to 90 degrees), the hillshade weight (--hs_weight
; 0-1), image brightness (--brightness
; 0-1), and atmospheric
effects (--atmospheric
; 0-1). The hillshade weight can be used to increase or subdue the relative prevalence of the
hillshading effect in the output image. The image brightness parameter is used to create an overall brighter or
darker version of the terrain rendering; note however, that very high values may over-saturate the well-illuminated
portions of the terrain. The atmospheric effects parameter can be used to introduce a haze or atmosphere effect to
the output image. It is intended to reproduce the effect of viewing mountain valley bottoms through a thicker and
more dense atmosphere. Values greater than zero will introduce a slightly blue tint, particularly at lower altitudes,
blur the hillshade edges slightly, and create a random haze-like speckle in lower areas. The user must also specify
the Z conversion factor (--zfactor
). The Z conversion factor is only important when the vertical and horizontal
units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z conversion factor. If the DEM is in the geographic coordinate system (latitude and longitude), the following equation
is used:
zfactor = 1.0 / (111320.0 x cos(mid_lat))
where mid_lat
is the latitude of the centre of the raster, in radians.
See Also: Hillshade, MultidirectionalHillshade, Aspect, Slope
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--altitude | Illumination source altitude in degrees |
--hs_weight | Weight given to hillshade relative to relief (0.0-1.0) |
--brightness | Brightness factor (0.0-1.0) |
--atmospheric | Atmospheric effects weight (0.0-1.0) |
--palette | Options include 'atlas', 'high_relief', 'arid', 'soft', 'muted', 'purple', 'viridis', 'gn_yl', 'pi_y_g', 'bl_yl_rd', and 'deep' |
--reverse | Optional flag indicating whether to use reverse the palette |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
--full_mode | Optional flag indicating whether to use full 360-degrees of illumination sources |
Python function:
wbt.hypsometrically_tinted_hillshade(
dem,
output,
altitude=45.0,
hs_weight=0.5,
brightness=0.5,
atmospheric=0.0,
palette="atlas",
reverse=False,
zfactor=None,
full_mode=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=HypsometricallyTintedHillshade -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif --altitude=45.0 ^
--hs_weight=0.3 --brightness=0.6 --atmospheric=0.2 ^
--palette=arid --full_mode
Author: Dr. John Lindsay
Created: 09/07/2020
Last Modified: 03/09/2020
LocalHypsometricAnalysis
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the hypsometric integral from the elevation distribution contained within the
local neighbourhood surrounding each grid cell in an input (--input
) DEM. The hyspometric integral (HI) is
the area under the hypsometric curve, which is a plot that relates elevation and area. This plot
is a cumulative distribution function with elevation expressed as a proportion of maximum elevation and
area expressed as the proportion of the area above. Hypsometry, or area-altitude analysis, is commonly
used by geomorphologists and geologists to characterize the erosional history of drainage basins. The
HI, ranging between 0 and 1, expresses the volume of land that lies above the lowest point within an
area, and thus has not been eroded. Relatively low HI values are indicative of more strongly eroded
surfaces.
Some researchers (e.g. Pérez‐Peña et al., 2009) have demonstrated the usefulness of applying hypsometry
in a spatially distributed fashion, rather than aggregated by basins, as it is typically applied. While
Pérez‐Peña et al. (2009) characterized spatial distributions of HI using coarse grids overlayed overtop
a digital elevation model (DEM), this tool uses a filter-based approach instead. Each grid cell in the
input DEM (--input
) has an individual HI calculation based on the elevation distribution within a
moving kernel. HI values are calculated using the elevation-relief ratio method described by Pike and
Wilson (1971).
In actuality, the tool uses a multi-scale approach, much like many of the other tools within the Geomorphometric Analysis toolbox (e.g. MaxElevationDeviation, MultiscaleStdDevNormals), such that the neighbourhood size is varied according to a range defined by user-specified input parameters. The HI that is reported within each grid cell in the output raster is the minimum HI value measured for each of the tested scales, defined by lower (rL) and upper (rU) ranges.
HImin=min{HI(r):r=rL...rU},
In this way, it represents a heterogenous, locally scale optimized map of HI distributions. A nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges, where there is often greater variability in HI values, and coarser at longer tested scales, such that:
ri = rL + [step × (i - rL)]p
Where ri is the filter radius for step i and p is the nonlinear scaling factor (--step_nonlinearity
)
and a step size (--step
) of step.
There are two outputs generated from this tool, including the HImin raster (--out_mag
)
and the rmin scale raster (--out_scale
).
References:
Pérez‐Peña, J. V., Azañón, J. M., Booth‐Rea, G., Azor, A., and Delgado, J. (2009). Differentiating geology and tectonics using a spatial autocorrelation technique for the hypsometric integral. Journal of Geophysical Research: Earth Surface, 114(F2).
Pike, R. J., and Wilson, S. E. (1971). Elevation-relief ratio, hypsometric integral, and geomorphic area-altitude analysis. Geological Society of America Bulletin, 82(4), 1079-1084.
See Also: HypsometricAnalysis, MaxElevationDeviation, MultiscaleStdDevNormals
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input raster DEM file |
--out_mag | Name of the openness output raster file |
--out_scale | Name of the openness output raster file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
--num_steps | Number of steps |
--step_nonlinearity | Step nonlinearity factor (1.0-2.0 is typical) |
Python function:
wbt.local_hypsometric_analysis(
i,
out_mag,
out_scale,
min_scale=4,
step=1,
num_steps=10,
step_nonlinearity=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=LocalHypsometricAnalysis ^
--input=DEM.tif --out_mag=HI_magnitude.tif ^
--out_scale=HI_scale.tif --min_scale=4 --step=1 --num_steps=50 ^
--step_nonlinearity=1.1
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 07/11/2021
Last Modified: 05/12/2021
LocalQuadraticRegression
This tool is an implementation of the constrained quadratic regression algorithm
using a flexible window size described in Wood (1996). A quadratic surface is fit
to local areas of input DEM (--dem
), defined by a filter size
(--filter
) using least squares regression. Note that the model is constrained such
that it must pass through the cell at the center of the filter. This is accomplished
by representing all elevations relative to the center cell, and by making the equation
constant 0.
Surface derivatives are calculated from the coefficients of the local quadratic surface once they are known. These include: Slope, Aspect, Profile convexity, Plan convexity, Longitudinal curvature, Cross-sectional curvature, and Minimum profile convexity, all as defined in Wood (1996). The goodness-of-fit (r-squared) of each local quadratic model is also returned.
Due to the fact that large filter sizes require long processing times, and that fitting the surface is the most time consuming part of the algorithm, all LSPs are output every time this tool is run. The content of each output is described by the suffixes of the output file names.
Reference:
Wood, J. (1996). The Geomorphological Characterisation of Digital Elevation Models. University of Leicester.
See Also: Aspect, Slope, PlanCurvature, ProfileCurvature
Parameters:
Flag | Description |
---|---|
-d, --dem | Name of the input DEM raster file |
-o, --output | Name of the output raster file |
--filter | Edge length of the filter kernel |
Python function:
wbt.local_quadratic_regression(
dem,
output,
filter=3,
callback=default_callback
)
Command-line Interface:
-./whitebox_tools -r=LocalQuadraticRegression --dem=DEM.tif ^
--output=out_ras.tif --filter=15
Author: Daniel Newman
Created: 22/06/2020
Last Modified: 22/06/2020
MapOffTerrainObjects
This tool can be used to map off-terrain objects in a digital surface model (DSM) based on cell-to-cell differences
in elevations and local slopes. The algorithm works by using a region-growing operation to connect neighbouring grid
cells outwards from seed cells. Two neighbouring cells are considered connected if the slope between the two cells
is less than the user-specified maximum slope value (--max_slope
). Mapped segments that are less than the minimum
feature size (--min_size
), in grid cells, are assigned a common background value. Note that this method of mapping
off-terrain objects, and thereby separating ground cells from non-ground objects in DSMs, works best with fine-resolution
DSMs that have been interpolated using a non-smoothing method, such as triangulation (TINing) or nearest-neighbour
interpolation.
See Also: RemoveOffTerrainObjects
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--max_slope | Maximum inter-cell absolute slope |
--min_size | Minimum feature size, in grid cells |
Python function:
wbt.map_off_terrain_objects(
dem,
output,
max_slope=40.0,
min_size=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MapOffTerrainObjects -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--max_diff=1.0
Author: Dr. John Lindsay
Created: 27/07/2020
Last Modified: 27/07/2020
MaxAnisotropyDev
Calculates the maximum anisotropy (directionality) in elevation deviation over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster DEVmax magnitude file |
--out_scale | Output raster DEVmax scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.max_anisotropy_dev(
dem,
out_mag,
out_scale,
max_scale,
min_scale=3,
step=2,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxAnisotropyDev -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=DEVmax_mag.tif ^
--out_scale=DEVmax_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dan Newman and John Lindsay
Created: January 26, 2018
Last Modified: 12/10/2018
MaxAnisotropyDevSignature
Calculates the anisotropy in deviation from mean for points over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--points | Input vector points file |
-o, --output | Output HTML file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.max_anisotropy_dev_signature(
dem,
points,
output,
max_scale,
min_scale=1,
step=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxAnisotropyDevSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.shp ^
--output=roughness.html --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dan Newman and John Lindsay
Created: 27/03/2018
Last Modified: 12/10/2018
MaxBranchLength
Maximum branch length (Bmax
) is the longest branch length between a grid cell's flowpath
and the flowpaths initiated at each of its neighbours. It can be conceptualized as the
downslope distance that a volume of water that is split into two portions by a drainage
divide would travel before reuniting.
If the two flowpaths of neighbouring grid cells do not intersect, Bmax
is simply the
flowpath length from the starting cell to its terminus at the edge of the grid or a cell
with undefined flow direction (i.e. a pit cell either in a topographic depression or at
the edge of a major body of water).
The pattern of Bmax
derived from a DEM should be familiar to anyone who has interpreted
upslope contributing area images. In fact, Bmax
can be thought of as the complement of
upslope contributing area. Whereas contributing area is greatest along valley bottoms and lowest at
drainage divides, Bmax
is greatest at divides and lowest along channels. The two topographic
attributes are also distinguished by their units of measurements; Bmax
is a length rather
than an area. The presence of a major drainage divide between neighbouring grid cells is apparent in
a Bmax
image as a linear feature, often two grid cells wide, of relatively high values. This
property makes Bmax
a useful land surface parameter for mapping ridges and divides.
Bmax
is useful in the study of landscape structure, particularly with respect to drainage patterns.
The index gives the relative significance of a specific location along a divide, with respect to the
dispersion of materials across the landscape, in much the same way that stream ordering can be used
to assess stream size.
See Also: FlowLengthDiff
Reference:
Lindsay JB, Seibert J. 2013. Measuring the significance of a divide to local drainage patterns. International Journal of Geographical Information Science, 27: 1453-1468. DOI: 10.1080/13658816.2012.705289
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--log | Optional flag to request the output be log-transformed |
Python function:
wbt.max_branch_length(
dem,
output,
log=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxBranchLength -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 09/07/2017
Last Modified: 18/10/2019
MaxDifferenceFromMean
Calculates the maximum difference from mean elevation over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster DIFFmax magnitude file |
--out_scale | Output raster DIFFmax scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.max_difference_from_mean(
dem,
out_mag,
out_scale,
min_scale,
max_scale,
step=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxDifferenceFromMean -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=DEVmax_mag.tif ^
--out_scale=DEVmax_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: 28/08/2018
Last Modified: 12/10/2018
MaxDownslopeElevChange
This tool calculates the maximum elevation drop between each grid cell and its neighbouring cells within
a digital elevation model (DEM). The user must specify the name of the input DEM (--dem
) and the output
(--output
) raster name.
See Also: MaxUpslopeElevChange, MinDownslopeElevChange, NumDownslopeNeighbours
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.max_downslope_elev_change(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxDownslopeElevChange -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=out.tif
Author: Dr. John Lindsay
Created: 11/07/2017
Last Modified: 12/10/2018
MaxElevDevSignature
Calculates the maximum elevation deviation over a range of spatial scales and for a set of points.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--points | Input vector points file |
-o, --output | Output HTML file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.max_elev_dev_signature(
dem,
points,
output,
min_scale,
max_scale,
step=10,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxElevDevSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.tif ^
--output=topo_position.html --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: March 1, 2018
Last Modified: 12/10/2018
MaxElevationDeviation
This tool can be used to calculate the maximum deviation from mean elevation, DEVmax (Lindsay et al. 2015) for each grid cell in a digital elevation model (DEM) across a range specified spatial scales. DEV is an elevation residual index and is essentially equivalent to a local elevation z-score. This attribute measures the relative topographic position as a fraction of local relief, and so is normalized to the local surface roughness. The multi-scaled calculation of DEVmax utilizes an integral image approach (Crow, 1984) to ensure highly efficient filtering that is invariant with filter size, which is the algorithm characteristic that allows for this densely sampled multi-scale analysis. In this way, MaxElevationDeviation allows users to estimate the locally optimal scale with which to estimate DEV on a pixel-by-pixel basis. This multi-scaled version of local topographic position can reveal significant terrain characteristics and can aid with soil, vegetation, landform, and other mapping applications that depend on geomorphometric characterization.
The user must specify the name (--dem
) of the input digital elevation model (DEM). The range of scales that are
evaluated in calculating DEVmax are determined by the user-specified --min_scale
, --max_scale
, and --step
parameters. All filter radii between the minimum and maximum scales, increasing by step
, will be evaluated.
The scale parameters are in units of grid cells and specify kernel size "radii" (r), such that:
d = 2r + 1
That is, a radii of 1, 2, 3... yields a square filters of dimension (d) 3 x 3, 5 x 5, 7 x 7...
DEV is estimated at each tested filter size and every grid cell is assigned the maximum DEV value across the evaluated scales.
The user must specify the file names of two output rasters, including the magnitude (DEVmax) and a second raster the assigns each pixel the scale at which DEVmax is encountered (DEVscale). The DEVscale raster can be very useful for revealing multi-scale landscape structure.
Reference:
Lindsay J, Cockburn J, Russell H. 2015. An integral image approach to performing multi-scale topographic position analysis. Geomorphology, 245: 51-61.
See Also: DevFromMeanElev, MaxDifferenceFromMean, MultiscaleElevationPercentile
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster DEVmax magnitude file |
--out_scale | Output raster DEVmax scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.max_elevation_deviation(
dem,
out_mag,
out_scale,
min_scale,
max_scale,
step=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxElevationDeviation -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=DEVmax_mag.tif ^
--out_scale=DEVmax_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: July 20, 2017
Last Modified: 12/10/2018
MaxUpslopeElevChange
This tool calculates the maximum elevation difference in the upslope direction between each grid cell and its neighbouring cells within
a digital elevation model (DEM). The user must specify the name of the input DEM (--dem
) and the output
(--output
) raster name.
See Also: MaxDownslopeElevChange
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.max_upslope_elev_change(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxUpslopeElevChange -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=out.tif
Author: Dr. John Lindsay
Created: 27/01/2022
Last Modified: 27/01/2022
MaximalCurvature
This tool calculates the maximal curvature from a digital elevation model (DEM). Maximal curvature is the curvature of a principal section with the highest value of curvature at a given point of the topographic surface (Florinsky, 2017). The values of this curvature are unbounded, and positive values correspond to ridge positions while negative values are indicative of closed depressions (Florinsky, 2016). Maximal curvature is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
MinimalCurvature, TangentialCurvature, ProfileCurvature, PlanCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--log | Display output values using a log-scale |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.maximal_curvature(
dem,
output,
log=False,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaximalCurvature -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 12/01/2022
Last Modified: 15/01/2022
MeanCurvature
This tool calculates the mean curvature from a digital elevation model (DEM). Mean curvature is the average of any mutually orthogonal normal sections, such as profile and tangential curvature (Wilson, 2018). This variable has an unbounded range that can take either positive or negative values. Florinsky (2017) states that mean curvature represents the two accumulation mechanisms of gravity-driven substances, convergence and relative deceleration of flows, with equal weights. Mean curvature is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
Wilson, J. P. (2018). Environmental applications of digital terrain modeling. John Wiley & Sons.
TangentialCurvature, ProfileCurvature, PlanCurvature, GaussianCurvature, MinimalCurvature, MaximalCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--log | Display output values using a log-scale |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.mean_curvature(
dem,
output,
log=False,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MeanCurvature -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/11/2021
Last Modified: 12/01/2022
MinDownslopeElevChange
This tool calculates the minimum elevation drop between each grid cell and its neighbouring cells within
a digital elevation model (DEM). The user must specify the name of the input DEM (--dem
) and the output
(--output
) raster name.
See Also: MaxDownslopeElevChange, NumDownslopeNeighbours
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.min_downslope_elev_change(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MinDownslopeElevChange -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=out.tif
Author: Dr. John Lindsay
Created: 11/07/2017
Last Modified: 12/10/2018
MinimalCurvature
This tool calculates the minimal curvature from a digital elevation model (DEM). Minimal curvature is the curvature of a principal section with the lowest value of curvature at a given point of the topographic surface (Florinsky, 2017). The values of this curvature are unbounded, and positive values correspond to hills while negative values are indicative of valley positions (Florinsky, 2016). Minimal curvature is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
MaximalCurvature, TangentialCurvature, ProfileCurvature, PlanCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--log | Display output values using a log-scale |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.minimal_curvature(
dem,
output,
log=False,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MinimalCurvature -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 12/01/2022
Last Modified: 15/01/2022
MultidirectionalHillshade
This tool performs a hillshade operation (also called shaded relief) on an input digital elevation model (DEM)
with multiple sources of illumination. The user must specify the name of the input DEM (--dem
) and the output
hillshade image name (--output
). Other parameters that must be specified include the altitude of the illumination
sources (--altitude
; i.e. the elevation of the sun above the horizon, measured as an angle
from 0 to 90 degrees) and the Z conversion factor (--zfactor
). The Z conversion factor is only important
when the vertical and horizontal units are not the same in the DEM, and the DEM is in a projected coordinate system. When this is the case,
the algorithm will multiply each elevation in the DEM by the Z conversion factor. If the
DEM is in the geographic coordinate system (latitude and longitude), the following equation
is used:
zfactor = 1.0 / (111320.0 x cos(mid_lat))
where mid_lat
is the latitude of the centre of the raster, in radians. The Z conversion factor can also be used
used to apply a vertical exageration to further emphasize landforms within the hillshade output.
The hillshade value (HS) of a DEM grid cell is calculate as:
HS = tan(s) / [1 - tan(s)2]0.5 x [sin(Alt) / tan(s) - cos(Alt) x sin(Az - a)]
where s and a are the local slope gradient and aspect (orientation) respectively and Alt and Az are the illumination source altitude and azimuth respectively. Slope and aspect are calculated using Horn's (1981) 3rd-order finate difference method.
Lastly, the user must specify whether or not to use full 360-degrees of illumination sources (--full_mode
). When this
flag is not specified, the tool will perform a weighted summation of the hillshade images from four illumination azimuth
positions at 225, 270, 315, and 360 (0) degrees, given weights of 0.1, 0.4, 0.4, and 0.1 respectively. When run in the
full 360-degree mode, eight illumination source azimuths are used to calculate the output at 0, 45, 90, 135, 180, 225,
270, and 315 degrees, with weights of 0.15, 0.125, 0.1, 0.05, 0.1, 0.125, 0.15, and 0.2 respectively.
Classic hillshade (Azimuth=315, Altitude=45.0)
Multi-directional hillshade (Altitude=45.0, Four-direction mode)
Multi-directional hillshade (Altitude=45.0, 360-degree mode)
See Also: Hillshade, HypsometricallyTintedHillshade, Aspect, Slope
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--altitude | Illumination source altitude in degrees |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
--full_mode | Optional flag indicating whether to use full 360-degrees of illumination sources |
Python function:
wbt.multidirectional_hillshade(
dem,
output,
altitude=45.0,
zfactor=None,
full_mode=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultidirectionalHillshade -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif ^
--altitude=30.0
Author: Dr. John Lindsay
Created: 19/07/2020
Last Modified: 03/09/2020
MultiscaleCurvatures
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates several multiscale curvatures and curvature-based indices from an input DEM (--dem
). There
are 18 curvature types (--curv_type
) available, including: accumulation curvature, curvedness, difference curvature,
Gaussian curvature, generating function, horizontal excess curvature, maximal curvature, mean curvature, minimal
curvature, plan curvature, profile curvature, ring curvature, rotor, shape index, tangential curvature, total
curvature, unsphericity, and vertical excess curvature. Each of these curvatures can be measured in non-multiscale
fashion using the corresponding tools available in either the WhiteboxTools open-core or the Whitebox extension.
Like many of the multi-scale land-surface parameter tools available in Whitebox, this tool can be run in two different modes: it can either be used to measure curvature at a single specific scale or to generate a curvature scale mosaic. To understand the difference between these two modes, we must first understand how curvatures are measured and how the non-multiscale curvature tools (e.g. ProfileCurvature) work. Curvatures are generally measured by fitting a mathematically defined surface to the elevation values within the local neighbourhood surrounding each grid cell in a DEM. The Whitebox curvature tools use the algorithms described Florinsky (2016), which use the 25 elevations within a 5 x 5 local neighbouhood for projected DEMs, and the nine elevations within a 3 x 3 neighbourhood for DEMs in geographic coordinate systems. This is what determines the scale at which these land-surface parameters are calculated. Because they are calculated using small local neighbourhoods (kernels), then these algorithms are heavily impacted by micro-topographic roughness and DEM noise. For example, in a fine-resolution DEM containing a great deal of micro-topographic roughness, the measured curvature value will be dominated by topographic variation at the scale of the roughness rather than the hillslopes on which that roughness is superimposed. This mis-matched scaling can be a problem in many applications, e.g. in landform classification and slope failure modelling applications.
Using the MultiscaleCurvatures tool, the user can specify a certain desired scale, larger than that defined by the grid resolution
and kernel size, over which a curvature should be characterized. The tool will then use a fast
Gaussian scale-space method to remove the topographic variation in the
DEM at scales less than the desired scale, and will then characterize the curvature using the usual method based on
this scaled DEM. To measure curvature at a single non-local scale, the user must specify a minimum search neighbourhood
radius in grid cells (--min_scale
) greater than 0.0. Note that a minimum search neighbourhood of 0.0 will replicate the non-multiscale
equivalent curvature tool and any --min_scale
value > 0.0 will apply the Gassian scale space method to eliminate
topographic variation less than the scale of the minimum search neighbourhood. The base step size (--step
), number of steps (--num_steps
), and step
nonlinearity (--step_nonlinearity
) parameters should all be left to their default values of 1 in this case. The
output curvature raster will be written to the output magnitude file (--out_mag
). The following animation shows
several multiscale curvature rasters (tangential curvature) measured from a DEM across a range of spatial scales.
Alternatively, one can use this tool to create a curvature scale mosaic. In this case, the user specifies a range of
spatial scales (i.e., a scale space) over which to measure curvature. The curvature scale-space is densely sampled
and each grid cell is assigned the maximum absolute curvature value (for the specified curvature type) across the
scale space. In this scale-mosaic mode, the user must also specify the output scale file name (--out_scale
), which
is an output raster that, for each grid cell, specifies the scale at which the maximum absolute curvature was identified.
The following is an example of a scale mosaic of unsphericity for an area in Pole Canyon, Utah (min_scale
=1.0,
step
=1, num_steps
=50, step_nonlinearity
=1.0).
Scale mosaics are useful when modelling spatial distributions of land-surface parameters, like curvatures, in complex and heterogeneous landscapes that contain an abundance of topographic variation (micro-topography, landforms, etc.) at widely varying spatial scales, often associated with different geomorphic processes. Notice how in the image above, relatively strong curvature values are being characterized for both the landforms associated with the smaller-scale mass-movement processes as well as the broader-scale fluvial erosion (i.e. valley incision and hillslopes). It would be difficult, or impossible, to achieve this effect using a single, uniform scale. Each location in a land-surface parameter scale mosaic represents the parameter measured at a characteristic scale, given the unique topography of the site and surroundings.
The properties of the sampled scale space are
determined using the --min_scale
, --step
, --num_steps
(greater than 1), and --step_nonlinearity
parameters.
Experience with multiscale curvature scales spaces has shown that they are more highly variable at shorter spatial
scales and change more gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this
tool to ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested scales,
such that:
ri = rL + [step × (i - rL)]p
Where ri is the filter radius for step i and p is the nonlinear scaling factor (--step_nonlinearity
)
and a step size (--step
) of step.
In scale-mosaic mode, the user must also decide whether or not to standardize the curvature values (--standardize
).
When this parameter is used, the algorithm will convert each curvature raster associated with each sampled region
of scale-space to z-scores (i.e. differenced from the raster-wide mean and divided by the raster-wide standard
deviation). It it usually the case that curvature values measured at broader spatial scales will on the whole
become less strongly valued. Because the scale mosaic algorithm used in this tool assigns each grid cell the
maximum absolute curvature observed within sampled scale-space, this implies that the curvature values associated
with more local-scale ranges are more likely to be selected for the final scale-mosaic raster. By standardizing
each scaled curvature raster, there is greater opportunity for the final scale-mosaic to represent broader
scale topographic variation. Whether or not this is appropriate will depend on the application. However, it
is important to stress that the sampled scale-space need not span the full range of possible scales, from the finest
scale determined by the grid resolution up to the broadest scale possible, determined by the spatial extent of
the input DEM. Often, a better approach is to use this tool to create multiple scale mosaics spanning this range,
thereby capturing variation within broadly defined scale ranges. For example, one could create a local-scale, meso-scale,
and broad-scale curvature scale mosaics, each of which would capture topographic variation and landforms that are
present in the landscape and reflective of processing operating at vastly different spatial scales. When this approach
is used, it may not be necessary to standardize each scaled curvature raster, since the gradual decline in
curvature values as scales increase is less pronounced within each of these broad scale ranges than across the
entirety of possible scale-space. Again, however, this will depend on the application and on the characteristics of
the landscape at study.
Raw curvedness values are often challenging to visualize given their range and magnitude,
and as such the user may opt to log-transform the output raster (--log
). Transforming the values
applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
See Also: GaussianScaleSpace, AccumulationCurvature, Curvedness, DifferenceCurvature, GaussianCurvature, GeneratingFunction, HorizontalExcessCurvature, MaximalCurvature, MeanCurvature, MinimalCurvature, PlanCurvature, ProfileCurvature, RingCurvature, Rotor, ShapeIndex, TangentialCurvature, TotalCurvature, Unsphericity, VerticalExcessCurvature
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Name of the input raster DEM file |
--curv_type | Curvature type |
--out_mag | Output raster magnitude file |
--out_scale | Output raster scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
--num_steps | Number of steps |
--step_nonlinearity | Step nonlinearity factor (1.0-2.0 is typical) |
--log | Display output values using a log-scale |
--standardize | Should each scale be standardized to z-scores? |
Python function:
wbt.multiscale_curvatures(
dem,
out_mag,
curv_type="ProfileCurv",
out_scale=None,
min_scale=0,
step=1,
num_steps=1,
step_nonlinearity=1.0,
log=True,
standardize=False,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=MultiscaleCurvatures --dem=dem.tif ^
--curv_type='Unsphericity' --out_mag=curv.tif --min_scale=10.0 ^
--log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 28/11/2022
Last Modified: 28/11/2022
MultiscaleElevationPercentile
This tool calculates the most elevation percentile (EP) across a range of spatial scales. EP is a measure of local topographic position (LTP) and expresses the vertical position for a digital elevation model (DEM) grid cell (z0) as the percentile of the elevation distribution within the filter window, such that:
EP = counti∈C(zi > z0) x (100 / nC)
where z0 is the elevation of the window's center grid cell, zi is the elevation of cell i contained within the neighboring set C, and nC is the number of grid cells contained within the window.
EP is unsigned and expressed as a percentage, bound between 0%
and 100%. This tool outputs two rasters, the multiscale EP magnitude (--out_mag
) and
the scale at which the most extreme EP value occurs (--out_scale
). The magnitude raster is
the most extreme EP value (i.e. the furthest from 50%) for each grid cell encountered within
the tested scales of EP.
Quantile-based estimates (e.g., the median and interquartile range) are often used in nonparametric statistics to provide data variability estimates without assuming the distribution is normal. Thus, EP is largely unaffected by irregularly shaped elevation frequency distributions or by outliers in the DEM, resulting in a highly robust metric of LTP. In fact, elevation distributions within small to medium sized neighborhoods often exhibit skewed, multimodal, and non-Gaussian distributions, where the occurrence of elevation errors can often result in distribution outliers. Thus, based on these statistical characteristics, EP is considered one of the most robust representation of LTP.
The algorithm implemented by this tool uses the relatively efficient running-histogram filtering algorithm of Huang
et al. (1979). Because most DEMs contain floating point data, elevation values must be rounded to be binned. The
--sig_digits
parameter is used to determine the level of precision preserved during this binning process. The
algorithm is parallelized to further aid with computational efficiency.
Experience with multiscale EP has shown that it is highly variable at shorter scales and changes more gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested scales, such that:
ri = rL + [step × (i - rL)]p
Where ri is the filter radius for step i and p is the nonlinear scaling factor (--step_nonlinearity
)
and a step size (--step
) of step.
References:
Newman, D. R., Lindsay, J. B., and Cockburn, J. M. H. (2018). Evaluating metrics of local topographic position for multiscale geomorphometric analysis. Geomorphology, 312, 40-50.
Huang, T., Yang, G.J.T.G.Y. and Tang, G., 1979. A fast two-dimensional median filtering algorithm. IEEE Transactions on Acoustics, Speech, and Signal Processing, 27(1), pp.13-18.
See Also:
ElevationPercentile
, MaxElevationDeviation, MaxDifferenceFromMean
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster roughness magnitude file |
--out_scale | Output raster roughness scale file |
--sig_digits | Number of significant digits |
--min_scale | Minimum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
--num_steps | Number of steps |
--step_nonlinearity | Step nonlinearity factor (1.0-2.0 is typical) |
Python function:
wbt.multiscale_elevation_percentile(
dem,
out_mag,
out_scale,
sig_digits=3,
min_scale=4,
step=1,
num_steps=10,
step_nonlinearity=1.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleElevationPercentile -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --step=5 ^
--num_steps=100 --step_nonlinearity=1.5
Author: Dr. John Lindsay
Created: 22/12/2019
Last Modified: 22/12/2019
MultiscaleRoughness
Calculates surface roughness over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster roughness magnitude file |
--out_scale | Output raster roughness scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.multiscale_roughness(
dem,
out_mag,
out_scale,
max_scale,
min_scale=1,
step=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleRoughness -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: 26/02/2018
Last Modified: 03/09/2020
MultiscaleRoughnessSignature
Calculates the surface roughness for points over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--points | Input vector points file |
-o, --output | Output HTML file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.multiscale_roughness_signature(
dem,
points,
output,
max_scale,
min_scale=1,
step=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleRoughnessSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.shp ^
--output=roughness.html --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: 27/02/2018
Last Modified: 03/09/2020
MultiscaleStdDevNormals
This tool can be used to map the spatial pattern of maximum spherical standard deviation
(σs max; --out_mag
), as well as the scale at which maximum spherical standard deviation occurs
(rmax; --out_scale
), for each grid cell in an input DEM (--dem
). This serves as a multi-scale measure
of surface roughness, or topographic complexity. The spherical standard deviation (σs) is
a measure of the angular spread among n unit vectors and is defined as:
σs = √[-2ln(R / N)] × 180 / π
Where R is the resultant vector length and is derived from the sum of the x, y, and z components of each of the n normals contained within a filter kernel, which designates a tested spatial scale. Each unit vector is a 3-dimensional measure of the surface orientation and slope at each grid cell center. The maximum spherical standard deviation is:
σs max=max{σs(r):r=rL...rU},
Experience with roughness scale signatures has shown that σs max is highly variable at shorter scales and changes more gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested scales, such that:
ri = rL + [step × (i - rL)]p
Where ri is the filter radius for step i and p is the nonlinear scaling factor (--step_nonlinearity
)
and a step size (--step
) of step.
Use the SphericalStdDevOfNormals tool if you need to calculate σs for a single scale.
Reference:
JB Lindsay, DR Newman, and A Francioni. 2019 Scale-Optimized Surface Roughness for Topographic Analysis. Geosciences, 9(322) doi: 10.3390/geosciences9070322.
See Also: SphericalStdDevOfNormals, MultiscaleStdDevNormalsSignature, MultiscaleRoughness
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster roughness magnitude file |
--out_scale | Output raster roughness scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
--num_steps | Number of steps |
--step_nonlinearity | Step nonlinearity factor (1.0-2.0 is typical) |
Python function:
wbt.multiscale_std_dev_normals(
dem,
out_mag,
out_scale,
min_scale=1,
step=1,
num_steps=10,
step_nonlinearity=1.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleStdDevNormals -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --step=5 ^
--num_steps=100 --step_nonlinearity=1.5
Author: Dr. John Lindsay
Created: 05/06/2019
Last Modified: 03/09/2020
MultiscaleStdDevNormalsSignature
Calculates the surface roughness for points over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--points | Input vector points file |
-o, --output | Output HTML file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
--num_steps | Number of steps |
--step_nonlinearity | Step nonlinearity factor (1.0-2.0 is typical) |
Python function:
wbt.multiscale_std_dev_normals_signature(
dem,
points,
output,
min_scale=1,
step=1,
num_steps=10,
step_nonlinearity=1.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleStdDevNormalsSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.shp ^
--output=roughness.html --min_scale=1 --step=5 --num_steps=100 ^
--step_nonlinearity=1.5
Author: Dr. John Lindsay
Created: 20/06/2019
Last Modified: 03/09/2020
MultiscaleTopographicPositionImage
This tool creates a multiscale topographic position (MTP) image (see here for an
example) from three DEVmax rasters of differing
spatial scale ranges. Specifically, MultiscaleTopographicPositionImage takes three DEVmax magnitude
rasters, created using the MaxElevationDeviation tool, as inputs. The three inputs should correspond to the elevation
deviations in the local (--local
), meso (--meso
), and broad (--broad
) scale ranges and will be forced into the
blue, green, and red colour components of the colour composite output (--output
) raster. The image lightness value
(--lightness
) controls the overall brightness of the output image, as depending on the topography and scale ranges,
these images can appear relatively dark. Higher values result in brighter, more colourful output images.
The user may optionally specify a hillshade image. When specified, the hillshade will be used to provide a shaded-relief overlaid on top of the coloured multi-scale information, providing a very effective visualization. Any hillshade image may be used for this purpose, but we have found that multi-directional hillshade (MultidirectionalHillshade), and specifically those derived using the 360-degree option, can be most effective for this application. However, experimentation is likely needed to find the optimal for each unique data set.
The output images can take some training to interpret correctly and a detailed explanation can be found in Lindsay et al. (2015). Sites within the landscape that occupy prominent topographic positions, either low-lying or elevated, will be apparent by their bright colouring in the MTP image. Those that are coloured more strongly in the blue are promient at the local scale range; locations that are more strongly green coloured are promient at the meso scale; and bright reds in the MTP image are associated with broad-scale landscape prominence. Of course, combination colours are also possible when topography is elevated or low-lying across multiple scale ranges. For example, a yellow area would indicated a site of prominent topographic position across the meso and broadest scale ranges.
Reference:
Lindsay J, Cockburn J, Russell H. 2015. An integral image approach to performing multi-scale topographic position analysis. Geomorphology, 245: 51-61.
See Also: MaxElevationDeviation
Parameters:
Flag | Description |
---|---|
--local | Input local-scale topographic position (DEVmax) raster file |
--meso | Input meso-scale topographic position (DEVmax) raster file |
--broad | Input broad-scale topographic position (DEVmax) raster file |
--hillshade | Input optional hillshade raster file. Note: a multi-directional (360-degree option) hillshade tends to work best in this application |
-o, --output | Output raster file |
--lightness | Image lightness value (default is 1.2) |
Python function:
wbt.multiscale_topographic_position_image(
local,
meso,
broad,
output,
hillshade=None,
lightness=1.2,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleTopographicPositionImage -v ^
--wd="/path/to/data/" --local=DEV_local.tif --meso=DEV_meso.tif ^
--broad=DEV_broad.tif -o=output.tif --lightness=1.5
Author: Dr. John Lindsay
Created: 19/07/2017
Last Modified: 30/01/2020
NumDownslopeNeighbours
This tool calculates the number of downslope neighbours of each grid cell in a raster digital elevation model (DEM).
The user must specify the name of the input DEM (--dem
) and the output (--output
) raster name. The tool examines
the eight neighbouring cells for each grid cell in a the DEM and counts the number of neighbours with an elevation
less than the centre cell of the 3 x 3 window. The output image can therefore have values raning from 0 to 8. A
raster grid cell with eight downslope neighbours is a peak and a cell with zero downslope neighbours is a pit. This
tool can be used with the NumUpslopeNeighbours tool to assess the degree of local flow divergence/convergence.
See Also: NumUpslopeNeighbours
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.num_downslope_neighbours(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=NumDownslopeNeighbours -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 12/10/2018
NumUpslopeNeighbours
This tool calculates the number of upslope neighbours of each grid cell in a raster digital elevation model (DEM).
The user must specify the name of the input DEM (--dem
) and the output (--output
) raster name. The tool examines
the eight neighbouring cells for each grid cell in a the DEM and counts the number of neighbours with an elevation
less than the centre cell of the 3 x 3 window. The output raster can therefore have values ranging from 0 to 8, although
in a DEM that has been hydrologically conditioned (i.e. depressions and flats removed), the values of the output will
not exceed seven. This tool can be used with the NumDownslopeNeighbours tool to assess the degree of local flow
divergence/convergence.
See Also: NumDownslopeNeighbours
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.num_upslope_neighbours(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=NumUpslopeNeighbours -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 12/10/2018
Openness
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the Yokoyama et al. (2002) topographic openness index from an input DEM (--input
).
Openness has two viewer perspectives, which correspond with positive and negative openness outputs (--pos_output
and --neg_output
). Positive values, expressing openness above the surface, are high for convex forms,
whereas negative values describe this attribute below the surface and are high for concave forms. Openness
is an angular value that is an average of the horizon angle in the eight cardinal directions to a maximum
search distance (--dist
), measured in grid cells. Openness rasters are best visualized using a greyscale palette.
Positive Openness:
Negative Openness:
References:
Yokoyama, R., Shirasawa, M., & Pike, R. J. (2002). Visualizing topography by openness: a new application of image processing to digital elevation models. Photogrammetric engineering and remote sensing, 68(3), 257-266.
See Also: Viewshed, HorizonAngle, TimeInDaylight, Hillshade
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input raster DEM file |
--pos_output | Name of the positive openness output raster file |
--neg_output | Name of the negative openness output raster file |
--dist | Search distance, in grid cells |
Python function:
wbt.openness(
i,
pos_output,
neg_output,
dist=20,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=Openness --input=DEM.tif ^
--pos_output=positive_openness.tif ^
--neg_output=negative_openness.tif --dist=500
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 30/03/2021
Last Modified: 30/03/2021
PennockLandformClass
Tool can be used to perform a simple landform classification based on measures of slope gradient and curvature derived from a user-specified digital elevation model (DEM). The classification scheme is based on the method proposed by Pennock, Zebarth, and DeJong (1987). The scheme divides a landscape into seven element types, including: convergent footslopes (CFS), divergent footslopes (DFS), convergent shoulders (CSH), divergent shoulders (DSH), convergent backslopes (CBS), divergent backslopes (DBS), and level terrain (L). The output raster image will record each of these base element types as:
Element Type | Code |
---|---|
CFS | 1 |
DFS | 2 |
CSH | 3 |
DSH | 4 |
CBS | 5 |
DBS | 6 |
L | 7 |
The definition of each of the elements, based on the original Pennock et al. (1987) paper, is as follows:
PROFILE | GRADIENT | PLAN | Element |
---|---|---|---|
Concave ( -0.10) | High >3.0 | Concave 0.0 | CFS |
Concave ( -0.10) | High >3.0 | Convex >0.0 | DFS |
Convex (>0.10) | High >3.0 | Concave 0.0 | CSH |
Convex (>0.10) | High >3.0 | Convex >0.0 | DSH |
Linear (-0.10...0.10) | High >3.0 | Concave 0.0 | CBS |
Linear (-0.10...0.10) | High >3.0 | Convex >0.0 | DBS |
-- | Low 3.0 | -- | L |
Where PROFILE is profile curvature, GRADIENT is the slope gradient, and PLAN is the plan curvature. Note that these values are likely landscape and data specific and can be adjusted by the user. Landscape classification schemes that are based on terrain attributes are highly sensitive to short-range topographic variability (i.e. roughness) and can benefit from pre-processing the DEM with a smoothing filter to reduce the effect of surface roughness and emphasize the longer-range topographic signal. The FeaturePreservingSmoothing tool offers excellent performance in smoothing DEMs without removing the sharpness of breaks-in-slope.
Reference:
Pennock, D.J., Zebarth, B.J., and DeJong, E. (1987) Landform classification and soil distribution in hummocky terrain, Saskatchewan, Canada. Geoderma, 40: 297-315.
See Also: FeaturePreservingSmoothing
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--slope | Slope threshold value, in degrees (default is 3.0) |
--prof | Profile curvature threshold value (default is 0.1) |
--plan | Plan curvature threshold value (default is 0.0) |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.pennock_landform_class(
dem,
output,
slope=3.0,
prof=0.1,
plan=0.0,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=PennockLandformClass -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif --slope=3.0 ^
--prof=0.1 --plan=0.0
Author: Dr. John Lindsay
Created: 12/07/2017
Last Modified: 03/09/2020
PercentElevRange
Percent elevation range (PER) is a measure of local topographic position (LTP). It expresses the vertical position for a digital elevation model (DEM) grid cell (z0) as the percentage of the elevation range within the neighbourhood filter window, such that:
PER = z0 / (zmax - zmin) x 100
where z0 is the elevation of the window's center grid cell, zmax is the maximum neighbouring elevation, and zmin is the minimum neighbouring elevation.
Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx
and --filtery
flags.
These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).
Compared with ElevPercentile and DevFromMeanElev, PER is a less robust measure of LTP that is susceptible to outliers in neighbouring elevations (e.g. the presence of off-terrain objects in the DEM).
References:
Newman, D. R., Lindsay, J. B., and Cockburn, J. M. H. (2018). Evaluating metrics of local topographic position for multiscale geomorphometric analysis. Geomorphology, 312, 40-50.
See Also: ElevPercentile, DevFromMeanElev, DiffFromMeanElev, RelativeTopographicPosition
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.percent_elev_range(
dem,
output,
filterx=3,
filtery=3,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=PercentElevRange -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif --filter=25
Author: Dr. John Lindsay
Created: 25/06/2017
Last Modified: 30/01/2020
PlanCurvature
This tool calculates the plan (or contour) curvature from a digital elevation model (DEM). Plan curvature is the curvature of a contour line at a given point on the topographic surface (Florinsky, 2017). This variable has an unbounded range that can take either positive or negative values. Positive values of the index are indicative of flow divergence while negative plan curvature values indicate flow convergence. Thus plan curvature is similar to tangential curvature, although the literature suggests that the latter is more numerically stable (Wilson, 2018). Plan curvature is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
Wilson, J. P. (2018). Environmental applications of digital terrain modeling. John Wiley & Sons.
TangentialCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature, MinimalCurvature, MaximalCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--log | Display output values using a log-scale |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.plan_curvature(
dem,
output,
log=False,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=PlanCurvature -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 01/06/2017
Last Modified: 12/01/2022
Profile
This tool can be used to plot the data profile, along a set of one or more vector lines (--lines
), in
an input (--surface
) digital elevation model (DEM), or other surface model. The data profile plots
surface height (y-axis) against distance along profile (x-axis). The tool outputs an interactive SVG line
graph embedded in an HTML document (--output
). If the vector lines file contains multiple line features,
the output plot will contain each of the input profiles.
If you want to extract the longitudinal profile of a river, use the LongProfile tool instead.
See Also: LongProfile, HypsometricAnalysis
Parameters:
Flag | Description |
---|---|
--lines | Input vector line file |
--surface | Input raster surface file |
-o, --output | Output HTML file |
Python function:
wbt.profile(
lines,
surface,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Profile -v --wd="/path/to/data/" ^
--lines=profile.shp --surface=dem.tif -o=profile.html
Author: Dr. John Lindsay
Created: 21/02/2018
Last Modified: 12/10/2018
ProfileCurvature
This tool calculates the profile (or vertical) curvature, or the rate of change in slope along a flow line, from a digital elevation model (DEM). It is the curvature of a normal section having a common tangent line with a slope line at a given point on the surface (Florinsky, 2017). This variable has an unbounded range that can take either positive or negative values. Positive values of the index are indicative of flow acceleration while negative profile curvature values indicate flow deceleration. Profile curvature is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output
raster (--output
). The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
PlanCurvature, TangentialCurvature, MeanCurvature, GaussianCurvature, MinimalCurvature, MaximalCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--log | Display output values using a log-scale |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.profile_curvature(
dem,
output,
log=False,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ProfileCurvature -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/062017
Last Modified: 15/01/2022
RelativeAspect
This tool creates a new raster in which each grid cell is assigned the terrain aspect relative to a user-specified
direction (--azimuth
). Relative terrain aspect is the angular distance (measured in degrees) between the land-surface
aspect and the assumed regional wind azimuth (Bohner and Antonic, 2007). It is bound between 0-degrees (windward direction)
and 180-degrees (leeward direction). Relative terrain aspect is the simplest of the measures of topographic exposure to
wind, taking into account terrain orientation only and neglecting the influences of topographic shadowing by distant
landforms and the deflection of wind by topography.
The user must specify the name of a digital elevation model (DEM) (--dem
) and an azimuth (i.e. a wind direction). The
Z Conversion Factor (--zfactor
) is only important when the vertical and horizontal units are not the same in the DEM, and the DEM is in a projected coordinate system.
When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor.
Reference:
Böhner, J., and Antonić, O. (2009). Land-surface parameters specific to topo-climatology. Developments in Soil Science, 33, 195-226.
See Also: Aspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--azimuth | Illumination source azimuth |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.relative_aspect(
dem,
output,
azimuth=0.0,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=RelativeAspect -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --azimuth=180.0
Author: Dr. John Lindsay
Created: 17/06/2017
Last Modified: 03/09/2020
RelativeTopographicPosition
Relative topographic position (RTP) is an index of local topographic position (i.e. how
elevated or low-lying a site is relative to its surroundings) and is a modification of percent
elevation range (PER; PercentElevRange) and accounts for the elevation distribution. Rather than
positioning the central cell's elevation solely between the filter extrema, RTP is a piece-wise
function that positions the central elevation relative to the minimum (zmin), mean (μ),
and maximum values (zmax), within a local neighbourhood of a user-specified size (--filterx
,
--filtery
), such that:
RTP = (z0 − μ) / (μ − zmin), if z0 < μ
OR
RTP = (z0 − μ) / (zmax - μ), if z0 >= μ
The resulting index is bound by the interval [−1, 1], where the sign indicates if the cell is above or below than the filter mean. Although RTP uses the mean to define two linear functions, the reliance on the filter extrema is expected to result in sensitivity to outliers. Furthermore, the use of the mean implies assumptions of unimodal and symmetrical elevation distribution.
In many cases, Elevation Percentile (ElevPercentile) and deviation from mean elevation (DevFromMeanElev) provide more suitable and robust measures of relative topographic position.
Reference:
Newman, D. R., Lindsay, J. B., and Cockburn, J. M. H. (2018). Evaluating metrics of local topographic position for multiscale geomorphometric analysis. Geomorphology, 312, 40-50.
See Also: DevFromMeanElev, DiffFromMeanElev, ElevPercentile, PercentElevRange
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.relative_topographic_position(
dem,
output,
filterx=11,
filtery=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=RelativeTopographicPosition -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--filter=25
Author: Dr. John Lindsay
Created: 06/06/2017
Last Modified: 30/01/2020
RemoveOffTerrainObjects
This tool can be used to create a bare-earth DEM from a fine-resolution digital surface model. The
tool is typically applied to LiDAR DEMs which frequently contain numerous off-terrain objects (OTOs) such
as buildings, trees and other vegetation, cars, fences and other anthropogenic objects. The algorithm
works by finding and removing steep-sided peaks within the DEM. All peaks within a sub-grid, with a
dimension of the user-specified maximum OTO size (--filter
), in pixels, are identified and removed.
Each of the edge cells of the peaks are then examined to see if they have a slope that is less than the
user-specified minimum OTO edge slope (--slope
) and a back-filling procedure is used. This ensures that
OTOs are distinguished from natural topographic features such as hills. The DEM is preprocessed using a
white top-hat transform, such that elevations are normalized for the underlying ground surface.
Note that this tool is appropriate to apply to rasterized LiDAR DEMs. Use the LidarGroundPointFilter tool to remove or classify OTOs within a LiDAR point-cloud.
Reference:
J.B. Lindsay (2018) A new method for the removal of off-terrain objects from LiDAR-derived raster surface models. Available online, DOI: 10.13140/RG.2.2.21226.62401
See Also: MapOffTerrainObjects, TophatTransform, LidarGroundPointFilter
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filter | Filter size (cells) |
--slope | Slope threshold value |
Python function:
wbt.remove_off_terrain_objects(
dem,
output,
filter=11,
slope=15.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=RemoveOffTerrainObjects -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=bare_earth_DEM.tif ^
--filter=25 --slope=10.0
Author: Dr. John Lindsay
Created: 06/06/2017
Last Modified: 07/08/2020
RingCurvature
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the ring curvature, which is the product of horizontal excess and vertical excess curvatures (Shary, 1995), from a digital elevation model (DEM). Like Rotor, ring curvature is used to measure flow line twisting. Ring curvature has values equal to or greater than zero and is measured in units of m-2.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
See Also:
Rotor, MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature, ProfileCurvature, TangentialCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--log | Display output values using a log-scale |
--zfactor | Z conversion factor |
Python function:
wbt.ring_curvature(
dem,
output,
log=False,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=RingCurvature -i=DEM.tif -o=output.tif ^
--log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 11/01/2022
Last Modified: 28/11/2022
Rotor
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the spatial pattern of rotor, which describes the degree to which a flow line twists (Shary, 1991), from a digital elevation model (DEM). Rotor has an unbounded range, with positive values indicating that a flow line turns clockwise and negative values indicating flow lines that turn counter clockwise (Florinsky, 2017). Rotor is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary PA (1991) The second derivative topographic method. In: Stepanov IN (ed) The Geometry of the Earth Surface Structures. Pushchino, USSR: Pushchino Research Centre Press, 30–60 (in Russian).
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
See Also:
RingCurvature, ProfileCurvature, TangentialCurvature, PlanCurvature, MeanCurvature, GaussianCurvature, MinimalCurvature, MaximalCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--log | Display output values using a log-scale |
--zfactor | Z conversion factor |
Python function:
wbt.rotor(
dem,
output,
log=False,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=Rotor -i=DEM.tif -o=output.tif --log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 08/01/2022
Last Modified: 28/11/2022
RuggednessIndex
The terrain ruggedness index (TRI) is a measure of local topographic relief. The TRI calculates the root-mean-square-deviation (RMSD) for each grid cell in a digital elevation model (DEM), calculating the residuals (i.e. elevation differences) between a grid cell and its eight neighbours. Notice that, unlike the output of this tool, the original Riley et al. (1999) TRI did not normalize for the number of cells in the local window (i.e. it is a root-square-deviation only). However, using the mean has the advantage of allowing for the varying number of neighbouring cells along the grid edges and in areas bordering NoData cells. This modification does however imply that the output of this tool cannot be directly compared with the index ranges of level to extremely rugged terrain provided in Riley et al. (1999)
Reference:
Riley, S. J., DeGloria, S. D., and Elliot, R. (1999). Index that quantifies topographic heterogeneity. Intermountain Journal of Sciences, 5(1-4), 23-27.
See Also: RelativeTopographicPosition, DevFromMeanElev
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.ruggedness_index(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=RuggednessIndex -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 03/09/2020
SedimentTransportIndex
This tool calculates the sediment transport index, or sometimes, length-slope (LS)
factor, based on input specific contributing area (As, i.e. the upslope
contributing area per unit contour length; --sca
) and slope gradient
(β, measured in degrees; --slope
) rasters. Moore et al. (1991) state that the physical potential for
sheet and rill erosion in upland catchments can be evaluated by the product R K LS,
a component of the Universal Soil Loss Equation (USLE), where R is a rainfall and
runoff erosivity factor, K is a soil erodibility factor, and LS is the length-slope
factor that accounts for the effects of topography on erosion. To predict erosion at a
point in the landscape the LS factor can be written as:
LS = (n + 1)(As / 22.13)n(sin(β) / 0.0896)m
where n = 0.4 (--sca_exponent
) and m = 1.3 (--slope_exponent
) in its original formulation.
This index is derived from unit stream-power theory and is sometimes used in place of the length-slope factor in the revised universal soil loss equation (RUSLE) for slope lengths less than 100 m and slope less than 14 degrees. Like many hydrological land-surface parameters SedimentTransportIndex assumes that contributing area is directly related to discharge. Notice that As must not be log-transformed prior to being used; As is commonly log-transformed to enhance visualization of the data. Also, As can be derived using any of the available flow accumulation tools, alghough better results usually result from application of multiple-flow direction algorithms such as DInfFlowAccumulation and FD8FlowAccumulation. The slope raster can be created from the base digital elevation model (DEM) using the Slope tool. The input images must have the same grid dimensions.
Reference:
Moore, I. D., Grayson, R. B., and Ladson, A. R. (1991). Digital terrain modelling: a review of hydrological, geomorphological, and biological applications. Hydrological processes, 5(1), 3-30.
See Also: StreamPowerIndex, DInfFlowAccumulation, FD8FlowAccumulation
Parameters:
Flag | Description |
---|---|
--sca | Input raster specific contributing area (SCA) file |
--slope | Input raster slope file |
-o, --output | Output raster file |
--sca_exponent | SCA exponent value |
--slope_exponent | Slope exponent value |
Python function:
wbt.sediment_transport_index(
sca,
slope,
output,
sca_exponent=0.4,
slope_exponent=1.3,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=SedimentTransportIndex -v ^
--wd="/path/to/data/" --sca='flow_accum.tif' ^
--slope='slope.tif' -o=output.tif --sca_exponent=0.5 ^
--slope_exponent=1.0
Author: Dr. John Lindsay
Created: 02/07/2017
Last Modified: 30/01/2020
ShadowAnimation
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool creates an interactive animated GIF of shadows based on an input digital surface model (DSM).
The shadow model is based on the modelled positions of the sun throughout a user-specified date (--date
)
sampling at a regular interval (--interval
), in minutes. Similar to the TimeInDaylight tool, this
tool uses calculated horizon angle (HorizonAngle) values and a solar position model to determine which
grid cells are located in shadow areas due to distant obsticles. The calculation of horizon angle, requires
the user input a maximum search distance parameter (--max_dist
).
The location parameter (--location
) should take the form Lat/Long/UTC-offset, e.g. 43.5448/-80.2482/-4/.
Note, the location need only be approximate; the postion of the central location of the input DSM raster
should suffice.
The output (--output
) of this tool is an HTML file, containing the interactive GIF animation. Users
are able to zoom and pan around the displayed DEV animation. The DSM may be rendered in one of several
available palettes (--palette
) suitable for visualization topography. The user must also
specify the image height (--height
) in the output file, the time delay (--delay
, in milliseconds) used
in the GIF animation, and an optional label (--label
), which will appear in the upper lefthand corner.
Note that the output is simply HTML, CSS, javascript code, and a GIF file, which can be readily embedded
in other documents.
Users should be aware that the outut GIF can be very large in size, depending on the size of the input DEM file. To reduce the file size of the output, it may be desirable to coarsen the input DEM resolution using image resampling (Resample).
The following is an example of what the output of this tool looks like. Click the image for an interactive example.
For more information about this tool, see this blog on the WhiteboxTools homepage.
See Also: ShadowImage, TimeInDaylight, HorizonAngle, LidarDigitalSurfaceModel
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input digital surface model (DSM) raster file |
-p, --palette | DSM image palette; options are 'atlas', 'high_relief', 'arid', 'soft', 'muted', 'light_quant', 'purple', 'viridis', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', and 'none' |
-o, --output | Name of the output HTML file (*.html) |
--max_dist | Optional maximum search distance, in xy units. Minimum value is 5 x cell size |
-d, --date | Date in format DD/MM/YYYY |
--interval | Time interval, in minutes (1-60) |
--location | Location, defined as Lat/Long/UTC-offset (e.g. 43.5448/-80.2482/-4) |
-h, --height | Image height, in pixels |
--delay | GIF time delay in milliseconds |
-l, --label | Label text (leave blank for none) |
Python function:
wbt.shadow_animation(
i,
output,
palette="atlas",
max_dist="",
date="21/06/2021",
interval=15,
location="43.5448/-80.2482/-4",
height=600,
delay=250,
label="",
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=ShadowAnimation -i=dsm.tif ^
-p='high_relief' -o=shadow_animation.html --max_dist=500 ^
--date='21/06/2021' --interval=20 --location='43.55/ -80.25/ ^
-4' --height=620 --delay=200 --label='Shadow Animation'
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 01/05/2021
Last Modified: 01/05/2021
ShadowImage
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool generates a raster of shadow areas based on an input digital surface model (DSM).
This shadow model is based on the calculated positions of the sun throughout a user-specified date (--date
),
sampling at a regular interval (--interval
), in minutes. Similar to the TimeInDaylight tool, this
tool uses calculated horizon angle (HorizonAngle) values and a solar position model to determine which
grid cells are located in shadow areas due to distant obsticles. The calculation of horizon angle, requires
the user input a maximum search distance parameter (--max_dist
).
The user must specify the date (--date
), time (--time
), and location (--location
) of the input DSM. The
date should have the format DD/MM/YYYY, e.g. 27/11/1976. The time should have the format HH::MM, e.g. 03:15AM
or 14:30. The location parameter should take the form Lat/Long/UTC-offset, e.g. 43.5448/-80.2482/-4/. Note, the
location need only be approximate; the postion of the central location of the input DSM raster should suffice.
The output (--output
) of this tool is a raster. If a palette (--palette
) is chosen, then the output
raster will be a colour composite image, containing a hysometrically tinted (i.e. elevation coloured)
shadow model. The DSM may be rendered in one of several available palettes (--palette
) suitable for
visualization topography. If the palette is set to 'none', the output image will not be a colour composite,
but rather, will be a 16-bit integer raster, and should be displayed in a grey-scale palette.
The following is an example of what the output of this tool looks like.
For more information about this tool, see this blog on the WhiteboxTools homepage.
See Also: ShadowAnimation, TimeInDaylight, HorizonAngle, LidarDigitalSurfaceModel, HypsometricallyTintedHillshade
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input digital surface model (DSM) raster file |
-o, --output | Name of the output raster file |
-p, --palette | DSM image palette; options are 'atlas', 'high_relief', 'arid', 'soft', 'muted', 'light_quant', 'purple', 'viridi', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', and 'none' |
--max_dist | Optional maximum search distance, in xy unites. Minimum value is 5 x cell size |
-d, --date | Date in format DD/MM/YYYY |
-t, --time | Time in format HH::MM, e.g. 03:15AM or 14:30 |
--location | Location, defined as Lat/Long/UTC-offset (e.g. 43.5448/-80.2482/-4) |
Python function:
wbt.shadow_image(
i,
output,
palette="soft",
max_dist="",
date="21/06/2021",
time="13:00",
location="43.5448/-80.2482/-4",
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=ShadowImage -i=dsm.tif ^
-p='high_relief' -o=shadow_animation.html --max_dist=500 ^
--date='21/06/2021' --time='14:30' --location='43.55/ -80.25/ ^
-4'
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 08/06/2021
Last Modified: 13/06/2021
ShapeIndex
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the shape index (Koenderink and van Doorn, 1992) from a digital elevation model (DEM). This variable ranges from -1 to 1, with positive values indicative of convex landforms, negative values corresponding to concave landforms (Florinsky, 2017). Absolute values from 0.5 to 1.0 are associated with elliptic surfaces (hills and closed depressions), while absolute values from 0.0 to 0.5 are typical of hyperbolic surface form (saddles). Shape index is a dimensionless variable and has utility in landform classification applications.
Koenderink and vsn Doorn (1992) make the following observations about the shape index:
-
Two shapes for which the shape index differs merely by sign represent complementary pairs that will fit together as ‘stamp’ and ‘mould’ when suitably scaled;
-
The shape for which the shape index vanishes - and consequently has indeterminate sign - represents the objects which are congruent to their own moulds;
-
Convexities and concavities find their places on opposite sides of the shape scale. These basic shapes are separated by those shapes which are neither convex nor concave, that are the saddle-like objects. The transitional shapes that divide the convexities/concavities from the saddle-shapes are the cylindrical ridge and the cylindrical rut.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Koenderink, J. J., and Van Doorn, A. J. (1992). Surface shape and curvature scales. Image and vision computing, 10(8), 557-564.
Curvedness, MinimalCurvature, MaximalCurvature, TangentialCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--zfactor | Z conversion factor |
Python function:
wbt.shape_index(
dem,
output,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=ShapeIndex -i=DEM.tif -o=output.tif
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 13/01/2022
Last Modified: 28/11/2022
SkyViewFactor
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the sky-view factor (SVF) from an input digital elevation model (DEM) or digital surface model (DSM). The SVF is the proportion of the celestial hemisphere above a point on the earth's surface that is not obstructed by the surrounding land surface. It is often used to model the diffuse light that is received at the surface and has also been applied as a relief-shading technique (Böhner et al., 2009; Zakšek et al., 2011).
The user must specify an input DEM (dem
), the azimuth fraction (az_fraction
), the maximum search
distance (max_dist
), and the height offset of the observer (observer_hgt_offset
). The input DEM
should usually be a digital surface model (DSM) that contains significant off-terrain objects. Such a
model, for example, could be created using the first-return points of a LiDAR data set, or using the
lidar_digital_surface_model tool. The azimuth
fraction should be an even divisor of 360-degrees and must be between 1-45 degrees.
The tool operates by calculating horizon angle (see horizon_angle)
rasters from the DSM based on the user-specified azimuth fraction (az_fraction
). For example, if an azimuth
fraction of 15-degrees is specified, horizon angle rasters would be calculated for the solar azimuths 0,
15, 30, 45... A horizon angle raster evaluates the vertical angle between each grid cell in a DSM and a
distant obstacle (e.g. a mountain ridge, building, tree, etc.) that obscures the view in a specified
direction. In calculating horizon angle, the user must specify the maximum search distance (max_dist
),
in map units, beyond which the query for higher, more distant objects will cease. This parameter strongly
impacts the performance of the function, with larger values resulting in significantly longer processing-times.
This tool uses the method described by Zakšek et al. (2011) to calculate SVF, which differs slightly from the method described by Böhner et al. (2009), as implemented in the Saga software. Most notably the Whitebox implementation does not involve local surface slope gradient and is closer in definition to the Saga 'Visible Sky' index.
There are other significant differences between the Whitebox and Saga implementations of SVF. For a given
maximum search distance, the Whitebox SVF will be substantially faster to calculate. Furthermore, the
Whitebox implementation has the ability to specify a height offset of the observer from the ground
surface, using the observer_hgt_offset
parameter. For example, the following image shows the spatial
pattern derived from a LiDAR DSM using observer_hgt_offset = 0.0
:
Notice that there are several places, plarticularly on the flatter rooftops, where the local noise in the LiDAR DEM, associated with the individual scan lines, has resulted in a somewhat noisy pattern in the output. By adding a small height offset of the scale of this noise variation (0.15 m), we see that most of this noisy pattern is removed in the output below:
This feature makes the function more robust against DEM noise. As another example of the usefulness of
this additional parameter, in the image below, the observer_hgt_offset
parameter has been used to
measure the pattern of the index at a typical human height (1.7 m):
Notice how overall visiblility increases at this height.
References:
Böhner, J. and Antonić, O., 2009. Land-surface parameters specific to topo-climatology. Developments in soil science, 33, pp.195-226.
Zakšek, K., Oštir, K. and Kokalj, Ž., 2011. Sky-view factor as a relief visualization technique. Remote sensing, 3(2), pp.398-415.
See Also: HorizonArea, AverageHorizonDistance, SkylineAnalysis, Openness, TimeInDaylight, HorizonAngle
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--az_fraction | Azimuth fraction |
--max_dist | Maximum distance (xy units) |
--observer_hgt_offset | Oberserver height offset (z units) |
Python function:
wbt.sky_view_factor(
dem,
output,
az_fraction=5.0,
max_dist=9999.0,
observer_hgt_offset=0.05,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=SkyViewFactor -i=dem.tif -o=output.tif ^
--az_fraction=5.0 --max_dist=250.0 --observer_hgt_offset=1.75
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 09/04/2024
Last Modified: 09/04/2024
SkylineAnalysis
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This function performs a skyline analysis for one or more observation points based on the terrain of an underlying digital elevation model (DEM). There are two outputs of the analysis, including an HTML report and a vector containing the horizon polygons associated with each observation point. The analysis report includes a summary of key characteristics of the skyline for each point, including the average zenith angle, the average horizon distance, the horizon area, the average skyline elevation, the standard deviation of skyline elevation, and the sky-view factor. The report will also include two radial charts, including the zenith angle plot and the horizon distance plot, for each observation point.
The horizon area vector output traces the skyline and is saved as a PolygonZ shapetype, with z-values taken from the input DEM surface and measures (M-values) derived from the zenith angle values. This can be thought of as an approxiate vector viewshed for the observation points, except that a viewshed may well contain internal occlusions that the horizon polygon does not. Note that it is best to use an input digital surface model, rather than a bare-earth DEM for this function.
The user must specify the input DEM and vector points file, the name of the output HTML report (which will be automatically displayed if verbose=True), the maximum distance (max_dist), the observer height (observer_hgt_offset), whether the output horizon polygon should of the PolygonZ ShapeType (if set to False the output will be of the PolyLineZ ShapeType), and the azimuth fraction (az_fraction), which determines the angular resolution of the analysis, with a default value of 1.0.
Note that the input DEM should use a projected spatial referencing system.
See Also: SkyViewFactor, HorizonArea, AverageHorizonDistance, Openness, TimeInDaylight, HorizonAngle
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
--points | Name of the input points vector file |
-o, --output | Name of the output vector file |
--output_html | Name of the output report file (*.html) |
--max_dist | Maximum distance (xy units) |
--observer_hgt_offset | Oberserver height offset (z units) |
--output_as_polygons | Are the output vectors polygons or lines |
--az_fraction | Azimuth fraction |
Python function:
wbt.skyline_analysis(
dem,
points,
output,
output_html,
max_dist=9999.0,
observer_hgt_offset=0.05,
output_as_polygons=True,
az_fraction=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=SkylineAnalysis -i=dem.tif ^
-o=output.tif --az_fraction=5.0 --max_dist=250.0 ^
--observer_hgt_offset=1.75
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 09/04/2024
Last Modified: 09/04/2024
Slope
This tool calculates slope gradient (i.e. slope steepness in degrees, radians, or percent) for each grid cell
in an input digital elevation model (DEM). The user must specify the name of the input
DEM (--dem
) and the output raster image. The Z conversion factor is only important
when the vertical and horizontal units are not the same in the DEM, and the DEM is in a projected coordinate system. When this is the case,
the algorithm will multiply each elevation in the DEM by the Z conversion factor.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
Reference:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
See Also: Aspect, TangentialCurvature, PlanCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
--units | Units of output raster; options include 'degrees', 'radians', 'percent' |
Python function:
wbt.slope(
dem,
output,
zfactor=None,
units="degrees",
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Slope -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --units="radians"
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 15/01/2022
SlopeVsAspectPlot
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool creates a slope vs. aspect plot for an input digital elevation model, or DEM (--input
).
Similar to a slope vs. elevation analysis (SlopeVsElevationPlot), the slope-aspect relation can reveal the basic
topographic character of a site. The output of this analysis is an HTML document (--output
) that contains the
slope-aspect chart, which is a radial line plot. The plot displays the median and interquartile range
of slope values for the range of aspect values from 0 - 360 degrees. In reality, the aspect range is binned
and the user must specify the bin size (--bin_size
). As slopes becomes quite shallow, the numerical
instability in aspect becomes apparent, due to the relatively small signal-to-noise ratio in these
areas of the input DEM. These shallow-gradient grid cells can have an out-sized impact on the shape
of the slope-aspect relation. Therefore, users can specify to ignore slopes less than a certain
threshold minimum slope (--min_slope
).
In interpreting the slope-aspect plots output by this tool, users should take note of asymmetries in polygonal paths taken by the percentile slope values, asymmetries in the range of slopes (i.e. the interquartile range), and anisotropy patterns (i.e. non-circularity or oval-shaped patterns). For example, asymmetries in the patterns may be indicative of landscape processes of interest, such as the differential energy balances experienced by north- and south-facing slopes at high latitudes. Increased rates of weathering on slopes with more direct sunlight at higher latitudes can result in flatter hillslopes. Asymmetry in the slope-aspect relation may also be indicative of DEM error and can be used as a quality control procedure, particularly for InSAR DEMs. Anisotropy in the slope-aspect relation may indicate a characteristic of the bedrock geology or the drainage structure of the landscape. The tool will also output the elongation ratio, a measure of anisotropy, of the mapped percentile polygons in a table.
The following are some examples of the output plots. In actuality, the outputs of the tool are interactive plots.
You may wish to smooth your DEM prior to analysis with this tool, in order to emphasis longer-scale patterns in the landscape. We would recommend using a method such as the FeaturePreservingSmoothing tool for this purpose.
The Z conversion factor (--z_factor
) is only important when the vertical and horizontal units are
not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the
DEM by the Z conversion factor. If the DEM is in the geographic coordinate system (latitude and
longitude), the following equation is used:
zfactor = 1.0 / (111320.0 x cos(mid_lat))
where mid_lat is the latitude of the centre of each raster row, in radians.
See Also: SlopeVsElevationPlot, FeaturePreservingSmoothing
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input raster image file |
-o, --output | Name of the output report file (*.html) |
--bin_size | Aspect bin size, in degrees |
--min_slope | Minimum slope, in degrees |
--zfactor | Z conversion factor |
Python function:
wbt.slope_vs_aspect_plot(
i,
output,
bin_size=2.0,
min_slope=0.1,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=SlopeVsAspectPlot --input="DEM.tif" ^
-o=slope_aspect_plot.html --bin_size=4.0
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 17/09/2021
Last Modified: 17/09/2021
SlopeVsElevationPlot
This tool can be used to create a slope versus average elevation plot for one or more digital elevation models (DEMs).
Similar to a hypsometric analysis (HypsometricAnalysis), the slope-elevation relation can reveal the basic
topographic character of a site. The output of this analysis is an HTML document (--output
) that contains the
slope-elevation chart. The tool can plot multiple slope-elevation analyses on the same chart by specifying multiple
input DEM files (--inputs
). Each input DEM can have an optional watershed in which the slope-elevation analysis is
confined by specifying the optional --watershed
flag. If multiple input DEMs are used, and a watershed is used to
confine the analysis to a sub-area, there must be the same number of input raster watershed files as input DEM files.
The order of the DEM and watershed files must the be same (i.e. the first DEM file must correspond to the first
watershed file, the second DEM file to the second watershed file, etc.). Each watershed file may contain one or more
watersheds, designated by unique identifiers.
See Also: HypsometricAnalysis, SlopeVsAspectPlot
Parameters:
Flag | Description |
---|---|
-i, --inputs | Input DEM files |
--watershed | Input watershed files (optional) |
-o, --output | Output HTML file (default name will be based on input file if unspecified) |
Python function:
wbt.slope_vs_elevation_plot(
inputs,
output,
watershed=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=SlopeVsElevationPlot -v ^
--wd="/path/to/data/" -i="DEM1.tif;DEM2.tif" ^
--watershed="ws1.tif;ws2.tif" -o=outfile.html
Author: Dr. John Lindsay
Created: 01/02/2018
Last Modified: 03/09/2020
SmoothVegetationResidual
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool can smooth the roughness due to residual vegetation cover in LiDAR digital elevation models (DEMs).
Sometimes when LiDAR data are collected under heavy forest cover, particularly conifer species, the DEM
will contain substantial roughness, even if it is interpolated using last-return points only. This tool can
be used to reduce the roughness of the ground surface under these conditions. It works by identifying grid cells
that possess deviation in mean elevation (DEV, DevFromMeanElev) values that are higher than a specified
threshold value (--dev_threshold
) for tested scales less than a specified threshold (--scale_threshold
).
DEV is measured for the input DEM (--input
) using filter radii from 1 to a user-specified maximum (--max_scale
).
The identified grid cells are then masked out and their elevations are re-interpolated using the surrounding,
non-masked values.
This method can work well under some conditions, and will further benefit from multiple passes of the tool, i.e.
run the tool using one set of parameters and then use the output (--output
) as the input for the second pass.
Alternative approaches include use of the RemoveOffTerrainObjects tool, using low-pass filters such as the
FeaturePreservingSmoothing tool, or, if the point-cloud source data are available, classifying the ground
points using LidarGroundPointFilter and excluding non-ground points from the interpolation.
The following image shows an image of a DEM that is badly impacted by heavy forest cover, with obvious vegetation residual roughness.
This image shows the impact of two-passes of the SmoothVegetationResidual tool.
See Also: RemoveOffTerrainObjects, FeaturePreservingSmoothing, LidarGroundPointFilter, DevFromMeanElev
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input digital elevation model (DEM) raster file |
-o, --output | Name of the output raster file |
--max_scale | Maximum search neighbourhood radius in grid cells |
--dev_threshold | DEVmax Threshold |
--scale_threshold | DEVmax scale threshold |
Python function:
wbt.smooth_vegetation_residual(
i,
output,
max_scale=30,
dev_threshold=1.0,
scale_threshold=5,
callback=default_callback
)
Command-line Interface:
-./whitebox_tools -r=SmoothVegetationResidual -i=DEM.tif ^
-o=smoothed_DEM.tif --max_scale=50 --dev_threshold=0.5 ^
--scale_threshold=8
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 09/05/2021
Last Modified: 09/05/2021
SphericalStdDevOfNormals
This tool can be used to calculate the spherical standard deviation of the distribution of surface normals
for an input digital elevation model (DEM; --dem
). This is a measure of the angular dispersion of the surface
normal vectors within a local neighbourhood of a specified size (--filter
). SphericalStdDevOfNormals
is therefore a measure of surface shape complexity, texture, and roughness. The
spherical standard deviation (s) is defined as:
s = √[-2ln(R / N)] × 180 / π
where R is the resultant vector length and N is the number of unit normal vectors within the local neighbourhood. s is measured in degrees and is zero for simple planes and increases infinitely with increasing surface complexity or roughness. Note that this formulation of the spherical standard deviation assumes an underlying wrapped normal distribution.
The local neighbourhood size (--filter
) must be any odd integer equal to or greater than three. Grohmann et al. (2010) found that
vector dispersion, a related measure of angular dispersion, increases monotonically with scale. This is the result
of the angular dispersion measure integrating (accumulating) all of the surface variance of smaller scales up to the
test scale. A more interesting scale relation can therefore be estimated by isolating the amount of surface complexity
associated with specific scale ranges. That is, at large spatial scales, s should reflect
the texture of large-scale landforms rather than the accumulated complexity at all smaller scales, including
microtopographic roughness. As such, this tool normalizes the surface complexity of scales that are smaller than
the filter size by applying Gaussian blur (with a standard deviation of one-third the filter size) to the DEM prior
to calculating R. In this way, the resulting distribution is able to isolate and highlight
the surface shape complexity associated with landscape features of a similar scale to that of the filter size.
This tool makes extensive use of integral images (i.e. summed-area tables) and parallel processing to ensure computational efficiency. It may, however, require substantial memory resources when applied to larger DEMs.
References:
Grohmann, C. H., Smith, M. J., & Riccomini, C. (2010). Multiscale analysis of topographic surface roughness in the Midland Valley, Scotland. IEEE Transactions on Geoscience and Remote Sensing, 49(4), 1200-1213.
Hodgson, M. E., and Gaile, G. L. (1999). A cartographic modeling approach for surface orientation-related applications. Photogrammetric Engineering and Remote Sensing, 65(1), 85-95.
Lindsay J. B., Newman* D. R., Francioni, A. 2019. Scale-optimized surface roughness for topographic analysis. Geosciences, 9(7) 322. DOI: 10.3390/geosciences9070322.
See Also: CircularVarianceOfAspect, MultiscaleRoughness, EdgeDensity, SurfaceAreaRatio, RuggednessIndex
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--output | Output raster file |
--filter | Size of the filter kernel |
Python function:
wbt.spherical_std_dev_of_normals(
dem,
output,
filter=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=SphericalStdDevOfNormals -v ^
--wd="/path/to/data/" --dem=DEM.tif --output=roughness.tif ^
--filter=15
Author: Dr. John Lindsay
Created: 22/05/2019
Last Modified: 03/09/2020
StandardDeviationOfSlope
Calculates the standard deviation of slope from an input DEM, a metric of roughness described by Grohmann et al., (2011).
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster DEM file |
-o, --output | Output raster DEM file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.standard_deviation_of_slope(
i,
output,
zfactor=None,
filterx=11,
filtery=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=StandardDeviationOfSlope -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--zfactor=1.0 --filterx=15 --filtery=15
Author: Anthony Francioni
Created: 26/05/2018
Last Modified: 03/09/2020
StreamPowerIndex
This tool can be used to calculate the relative stream power (RSP) index. This index is directly related
to the stream power if the assumption can be made that discharge is directly proportional to upslope
contributing area (As; --sca
). The index is calculated as:
RSP = Asp × tan(β)
where As is the specific catchment area (i.e. the upslope contributing area per unit
contour length) estimated using one of the available flow accumulation algorithms; β is the local
slope gradient in degrees (--slope
); and, p (--exponent
) is a user-defined exponent term that
controls the location-specific relation between contributing area and discharge. Notice that
As must not be log-transformed prior to being used; As is commonly
log-transformed to enhance visualization of the data. The slope raster can be created from the base
digital elevation model (DEM) using the Slope tool. The input images must have the same grid dimensions.
Reference:
Moore, I. D., Grayson, R. B., and Ladson, A. R. (1991). Digital terrain modelling: a review of hydrological, geomorphological, and biological applications. Hydrological processes, 5(1), 3-30.
See Also: SedimentTransportIndex, Slope, D8FlowAccumulation DInfFlowAccumulation, FD8FlowAccumulation
Parameters:
Flag | Description |
---|---|
--sca | Input raster specific contributing area (SCA) file |
--slope | Input raster slope file |
-o, --output | Output raster file |
--exponent | SCA exponent value |
Python function:
wbt.stream_power_index(
sca,
slope,
output,
exponent=1.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=StreamPowerIndex -v ^
--wd="/path/to/data/" --sca='flow_accum.tif' ^
--slope='slope.tif' -o=output.tif --exponent=1.1
Author: Dr. John Lindsay
Created: 02/07/2017
Last Modified: 30/01/2020
SurfaceAreaRatio
This tool calculates the ratio between the surface area and planar area of grid cells within digital elevation models (DEMs). The tool uses the method of Jenness (2004) to estimate the surface area of a DEM grid cell based on the elevations contained within the 3 x 3 neighbourhood surrounding each cell. The surface area ratio has a lower bound of 1.0 for perfectly flat grid cells and is greater than 1.0 for other conditions. In particular, surface area ratio is a measure of neighbourhood surface shape complexity (texture) and elevation variability (local slope).
Reference:
Jenness, J. S. (2004). Calculating landscape surface area from digital elevation models. Wildlife Society Bulletin, 32(3), 829-839.
See Also: RuggednessIndex, MultiscaleRoughness, CircularVarianceOfAspect, EdgeDensity
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.surface_area_ratio(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=SurfaceAreaRatio -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 23/01/2019
Last Modified: 23/01/2019
TangentialCurvature
This tool calculates the tangential (or horizontal) curvature, which is the curvature of an inclined plane perpendicular to both the direction of flow and the surface (Gallant and Wilson, 2000). Alternatively, it could be described as the curvature of a normal section tangential to a contour line at a given point of the topographic surface (Florinsky, 2017). This variable has an unbounded range that can be either positive or negative. Positive values are indicative of flow divergence while negative tangential curvature values indicate flow convergence. Thus tangential curvature is similar to plan curvature, although the literature suggests that the former is more numerically stable (Wilson, 2018). Tangential curvature is measured in units of m-1.
The user must specify the name of the input digital elevation model (DEM) (--dem
) and the output
raster (--output
). The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
Wilson, J. P. (2018). Environmental applications of digital terrain modeling. John Wiley & Sons.
PlanCurvature, ProfileCurvature, TotalCurvature, Slope, Aspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--log | Display output values using a log-scale |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.tangential_curvature(
dem,
output,
log=False,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=TangentialCurvature -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 15/01/2022
TimeInDaylight
This tool calculates the proportion of time a location is within daylight. That is, it calculates the
proportion of time, during a user-defined time frame, that a grid cell in an input digital elevation
model (--dem
) is outside of an area of shadow cast by a local object. The input DEM should truly be
a digital surface model (DSM) that contains significant off-terrain objects. Such a model, for example,
could be created using the first-return points of a LiDAR data set, or using the LidarDigitalSurfaceModel
tool.
The tool operates by calculating a solar almanac, which estimates the sun's position for the location, in
latitude and longitude coordinate (--lat
, --long
), of the input DSM. The algorithm then calculates
horizon angle (see HorizonAngle) rasters from the DSM based on the user-specified azimuth fraction (--az_fraction
).
For example, if an azimuth fraction of 15-degrees is specified, horizon angle rasters could be calculated for
the solar azimuths 0, 15, 30, 45... In reality, horizon angle rasters are only calculated for azimuths for which
the sun is above the horizon for some time during the tested time period. A horizon angle raster evaluates
the vertical angle between each grid cell in a DSM and a distant obstacle (e.g. a mountain ridge, building, tree, etc.) that
blocks the view along a specified direction. In calculating horizon angle, the user must specify the maximum search
distance (--max_dist
) beyond which the query for higher, more distant objects will cease. This parameter strongly
impacts the performance of the tool, with larger values resulting in significantly longer run-times. Users are advised
to set the --max_dist
based on the maximum shadow length expected in an area. For example, in a relatively flat
urban landscape, the tallest building will likely determine the longest shadow lengths. All grid cells for which the
calculated solar positions throughout the time frame are higher than the cell's horizon angle are deemed to be
illuminated during the time the sun is in the corresponding azimuth fraction.
By default, the tool calculates time-in-daylight for a time-frame spanning an entire year. That is, the solar almanac
is calculated for each hour, at 10-second intervals, and for each day of the year. Users may alternatively restrict the
time of year over which time-in-daylight is calculated by specifying a starting day (1-365; --start_day
) and ending day
(1-365; --end_day
). Similarly, by specifying start time (--start_time
) and end time (--end_time
) parameters,
the user is able to measure time-in-daylight for specific ranges of the day (e.g. for the morning or afternoon hours).
These time parameters must be specified in 24-hour time (HH:MM:SS), e.g. 15:30:00. sunrise
and sunset
are also
acceptable inputs for the start time and end time respectively. The timing of sunrise and sunset on each day in the
tested time-frame will be determined using the solar almanac.
See Also: LidarDigitalSurfaceModel, HorizonAngle
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--az_fraction | Azimuth fraction in degrees |
--max_dist | Optional maximum search distance. Minimum value is 5 x cell size |
--lat | Centre point latitude |
--long | Centre point longitude |
--utc_offset | UTC time offset, in hours (e.g. -04:00, +06:00) |
--start_day | Start day of the year (1-365) |
--end_day | End day of the year (1-365) |
--start_time | Starting hour to track shadows (e.g. 5, 5:00, 05:00:00). Assumes 24-hour time: HH:MM:SS. 'sunrise' is also a valid time |
--end_time | Ending hour to track shadows (e.g. 21, 21:00, 21:00:00). Assumes 24-hour time: HH:MM:SS. 'sunset' is also a valid time |
Python function:
wbt.time_in_daylight(
dem,
output,
lat,
long,
az_fraction=10.0,
max_dist=100.0,
utc_offset="00:00",
start_day=1,
end_day=365,
start_time="00:00:00",
end_time="23:59:59",
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=TimeInDaylight -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif --az_fraction=15.0 ^
--max_dist=100.0 --lat=43.545 --long= -80.248
Author: Dr. John Lindsay
Created: 29/07/2020
Last Modified: 03/09/2020
TopoRender
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool is used to create pseudo-3D rendering from an input DEM, for the purpose of effective topographic
visualization. The tool simulated direct radiation, diffuse radiation, and light attenuation to create an
effective topographic visualization. The user must specify the input digital elevation model (--dem
) and output (--output
) file names.
One of several named palettes (--palette
) may also be chosen, including 'atlas', 'high_relief', 'arid', 'soft',
'earthtones', 'muted', 'light_quant', 'purple', 'viridi', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', 'imhof', and 'white'.
The user may optionally reverse the palette (--rev_palette
), although this will generally not be required since
the palettes are designed to work well with topographic data as they are.
The user must also specify a number of parameters related to the lighting of the surface. These include the
light source direciton (--az
; 0-360) and altitude (--alt
; 0-90), both of which describe the 3D light source
location in decimal degrees. The light attenuation (--attenuation
) describes the rate at which the light dims
away from the source, effectively applying a gradient across the image. Values of this parameter range from 0-1,
with appropriate values in the 0.0 (no attenuation) to 0.7 range. The ambient light parameter (--ambient_light
)
is used to describe how much background (diffuse) light there is, which allows for details to be discernable within
shadow areas. Values of this parameter also range from 0-1, although generally much lower values ~0.2, produce
good results. Experimentation with each of the lighting parameter values may be needed to create a final map.
The resulting output image will have shadows cast beyond the original input DEM's grid, futher creating the
illusion of a 3D surface suspended above a background plane (see examples below). The user may accentuate this effect by setting
the vertical distance between the topographic surface and the plane (--background_hgt_offset
). Larger
values of this parameter will result in a greater distance, and the parameter values are in the z-units of the
input DEM. If the DEM contains NoData values, these sites will appear to cut through to the background plane.
In fact, the user may optionally include a clipping polygon (--polygon
) and only the parts of the DEM that
are within this polygon will be displayed. This is useful if, for example, you wish to render an individual
watershed. The user may specify the colour of the background plane (--background_clr
), as a string of RGB or
RGBA values, e.g. '[255, 240, 200, 255]'. The default colour is white, which may appear slightly greyed if a
non-zero light attentuation value is specified.
Lastly, the user must specify an elevation multiplier (--z_factor
) parameter, with a default of 1.0. This
can be useful for applying a vertical exageration (values greater than 1.0) to the elevation surface for
enchanced topographic relief. This may be important when applying this tool in relatively low-to-moderate
relief locations, or when applying it to very large spatial extents. Please note, this tool is suitable for
applying to DEMs in geographic coordinates (latitude and longitude) or projected coordinate systems.
The image that is created by this tool is a GeoTiff and can be opened in a GIS. This means that it is possible to overlay other layers on top. For example, it is possible to use the 'white' palette to create a rendered topography and then to overlay, transparently, a satellite image or air photo on top within a GIS. In the case of a fine-resolution image, however, it is important to remember that typically shadows will be visible in these images, that can be contrary to those generated by the rendered topography, which is not ideal for visualization.
The following examples demonstrate how the output of this may appear.
See Also: ShadowImage, ShadowAnimation, TimeInDaylight, HorizonAngle, HypsometricallyTintedHillshade
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Name of the input digital elevation model (DEM) raster file |
-o, --output | Name of the output raster file |
-p, --palette | Palette name; options are 'atlas', 'high_relief', 'arid', 'soft', 'earthtones', 'muted', 'light_quant', 'purple', 'viridi', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', 'imhof', and 'white' |
--rev_palette | Reverse the palette? |
--az | Light source azimuth direction (degrees, 0-360) |
--alt | Light source altitude (degrees, 0-90) |
--background_hgt_offset | Offset height of background, in z-units |
--polygon | Clipping polygon vector file (optional) |
--background_clr | Background red-green-blue (RGB) or red-green-blue-alpha (RGBA) colour, e.g. '[255, 255, 245]', '[255, 255, 245, 200]' |
--attenuation | Attenuation parameter. Range is 0-4. Zero means no attenuation |
--ambient_light | Ambient light parameter. Range is 0.0-0.7. Zero means no ambient light |
--z_factor | Elevation multiplier, or a vertical exageration |
Python function:
wbt.topo_render(
dem,
output,
palette="soft",
rev_palette=False,
az=315.0,
alt=30.0,
background_hgt_offset=10.0,
polygon=None,
background_clr="[255, 255, 255]",
attenuation=0.6,
ambient_light=0.2,
z_factor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=TopoRender -i=dsm.tif -p='high_relief' ^
-o=shadow_animation.html --max_dist=500 --date='21/06/2021' ^
--time='14:30' --location='43.55/ -80.25/ -4'
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 08/06/2021
Last Modified: 13/06/2021
TopographicHachures
This tool can be used to create a topographic hachures vector dataset from an input raster surface model (--input
), such as a digital
elevation model (DEM). Topographic hachures are short flowlines arranged along contours for cartographic relief presentation.
The first group of parameters is the same as in the ContoursFromRaster tool. The user must specify the contour interval (--interval
)
and optionally, the base contour value (--base
). The degree to which contours are smoothed is controlled by the Smoothing Filter Size
parameter (--smooth
). This value, which determines the size of a mean filter applied to the x-y position of vertices in each contour,
should be an odd integer value, e.g. 3, 5, 7, 9, 11, etc. Larger values will result in smoother contour lines. The tolerance
parameter (--tolerance
) controls the amount of line generalization. That is, vertices in a contour line will be selectively removed
from the line if they do not result in an angular deflection in the line's path of at least this threshold value. Increasing this value
will lead to straighter contour line segments.
The remaining parameters control the hachures generation process. Seed separation (--sep
) is the distance between neighboring hachures
along contours (in pixels, can be fractional). Minimum distance (--distmin
) and Maximum distance (--distmax
) determine
how much closer hachures can converge or diverge in relation to the seed separation. The hachure is approximated by polyline which
follows the flow direction, and the length of each polyline segment is controlled by Discretization (--discr
) parameter, expressed
in pixels (can be fractional). Smoother and more accurate flowlines are generated with smaller discretization. However, this will
also lead to lines that contain more vertices, and will require more storage space and visualization time. Normally, each hachure
starts at contour line and ends by the contour line which is one interval lower. However, flowline behaviour becomes unpredictable in
the areas of low slope angles. To deal with such cases, the Maximum turning angle (--turnmax
) and the Minimum slope angle
(--slopemin
) are used. If the next step in flowline tracing would violate these conditions, the process is interrupted at current point.
Finally, the Nesting depth (--depthmax
) parameter determines how deep the hachures are inserted recursively in divergence areas.
The output vector dataset (--output
) contains several attributes which are helpful during visualization. In particular, HEIGHT, SLOPE,
and ASPECT attributes contain the elevation of the hachure seed, as well as the average slope and aspect along its flowline.
Each of the remaining N, NE, E, SE, S, SW, W, and NW attributes is essentially the cosine of the angle between the
light source with corresponding direction and the aspect of the hachure. For example, the classic "shadow hachuring" technique with
northwestern illumination can be implemented by varying the line stroke width based on the (1 - NW) * SLOPE expression. Atmospheric
perspective is achieved by making the hachures more transparent (or closer to the background color) for smaller values of HEIGHT.
References:
Imhof, E., 1982. Cartographic Relief Presentation. Walter der Gruyter, Berlin.
Samsonov, T., 2014. Morphometric Mapping of Topography by Flowline Hachures. The Cartographic Journal 51, 63–74. https://doi.org/10.1179/1743277413Y.0000000036
See Also: ContoursFromRaster, RasterToVectorPolygons
Parameters:
Flag | Description |
---|---|
-i, --input | Input surface raster file |
-o, --output | Output Topographic Hachures File |
--interval | Contour interval |
--base | Base contour height |
--smooth | Smoothing filter size (in num. points), e.g. 3, 5, 7, 9, 11 |
--tolerance | Tolerance factor, in degrees (0-45); determines generalization level |
--sep | Separation distance between seed points of hachures (in pixels) |
--distmin | Minimum distance between converging flowlines (in relation to seed separation) |
--distmax | Maximum distance between diverging flowlines (in relation to seed separation) |
--discr | Discretization step used in tracing the flowline (in pixels) |
--turnmax | Maximum turning angle valid for hachure (in degrees, 0-90) |
--slopemin | Slope angle, in degrees, at which flowline tracing ends (in degrees, 0-90) |
--depthmax | Maximum depth of nested flowlines, inserted within divergence areas (0-255) |
Python function:
wbt.topographic_hachures(
i,
output,
interval=10.0,
base=0.0,
smooth=9,
tolerance=10.0,
sep=2,
distmin=0.5,
distmax=2,
discr=0.5,
turnmax=45.0,
slopemin=0.5,
depthmax=16,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=TopographicHachures -v ^
--wd="/path/to/data/" --input=DEM.tif -o=hachures.shp ^
--interval=10.0 --base=0.0 --smooth=9 --tolerance=10.0 ^
--sep=2.0 --distmin=0.5 --distmax=2.0 --discr=0.5 ^
--turnmax=45.0 --slopemin=0.5
Author: Dr. Timofey Samsonov, Dr. John Lindsay
Created: 25/03/2023
Last Modified: 26/03/2023
TopographicPositionAnimation
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool creates an interactive animation that demonstrates the variation in deviation from mean
elevation (DEV, DevFromMeanElev) as scale increases across a range for an input digital elevation
model (--input
). DEV is calculated as the difference between the elevation of each grid cell and the
mean elevation of the centering local neighbourhood, normalized by standard deviation and is a measure
of local topographic position. DEV is useful for highlighting locally prominent (either elevated or
low-lying) locations within a landscape. Topographic position animations are extemely useful for
interpreting landscape geomorphic structure across a range of scales.
The set of scales for which DEV is measured (using varying filter sizes) is determined by the three
user-specified parameters, including --min_scale
, --num_steps
, and --step_nonlinearity
. Experience
with DEV scale signatures has shown that it is highly variable at shorter scales and changes more
gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to
ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested
scales, such that:
ri = rL + (i - rL)p
Where ri is the filter radius for step i, rL is the lower range of filter sizes
(--min_scale
), and p is the nonlinear scaling factor (--step_nonlinearity
).
The tool can be run in one of two modes: using regular DEV calculations, or using DEVmax
(MaxElevationDeviation), a multiscale version of DEV that outputs the maximum absolute value of
DEV encountered across a range of tested scales. Use the --dev_max
flag to run the tool in
DEVmax mode.
The output (--output
) of this tool is an HTML file, containing the interactive GIF animation. Users
are able to zoom and pan around the displayed DEV animation. The DEV images may be rendered in one of several
available palettes (--palette
) suitable for visualization DEV. The output DEV/DEVmax
animation will also be hillshaded to further enchance topographic interpretation. The user must also
specify the image height (--height
) in the output file, the time delay (--delay
, in milliseconds) used
in the GIF animation, and an optional label (--label
), which will appear in the upper lefthand corner.
Note that the output is simply HTML, CSS, javascript code, and a GIF file, which can be readily embedded
in other documents.
Users should be aware that the outut GIF can be very large in size, depending on the size of the input DEM file. To reduce the file size of the output, it may be desirable to coarsen the input DEM resolution using image resampling (Resample).
The following is an example of what the output of this tool looks like. Click the image for an interactive example.
For more information about this tool and example outputs, see this blog on the WhiteboxTools homepage.
See Also: DevFromMeanElev, MaxElevationDeviation
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input digital elevation model (DEM) raster file |
-p, --palette | Image palette; options are 'bl_yl_rd', 'bl_w_rd', 'purple', 'gn_yl', 'pi_y_g', and 'viridis' |
-o, --output | Name of the output HTML file (*.html) |
--min_scale | Minimum search neighbourhood radius in grid cells |
--num_steps | Number of steps |
--step_nonlinearity | Step nonlinearity factor (1.0-2.0 is typical) |
--height | Image height, in pixels |
--delay | GIF time delay in milliseconds |
-l, --label | Label text (leave blank for none) |
--dev_max | Do you want to use DEVmax instead of DEV for measuring local topographic position? |
Python function:
wbt.topographic_position_animation(
i,
output,
palette="bl_yl_rd",
min_scale=1,
num_steps=100,
step_nonlinearity=1.5,
height=600,
delay=250,
label="",
dev_max=False,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=TopographicPositionAnimation -i=dem.tif ^
-p='bl_w_rd' -o=DEV_animation.html --min_scale=3 ^
--num_steps=100 --step_nonlinearity=1.2 --height=620 ^
--delay=200 --label='DEVmax for Catfish Watershed' --dev_max
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 06/05/2021
Last Modified: 10/06/2021
TotalCurvature
This tool calculates the total curvature from a digital elevation model (DEM). Total curvature measures the curvature of the topographic surface rather than the curvature of a line across the surface in some direction (Wilson, 2018). Total curvature can be positive or negative, with zero curvature indicating that the surface is either flat or the convexity in one direction is balanced by the concavity in another direction, as would occur at a saddle point. Total curvature is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Shary P. A. , Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
Wilson, J. P. (2018). Environmental applications of digital terrain modeling. John Wiley & Sons.
MinimalCurvature, MaximalCurvature, TangentialCurvature, ProfileCurvature, PlanCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--log | Display output values using a log-scale |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.total_curvature(
dem,
output,
log=False,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=TotalCurvature -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 15/01/2022
Unsphericity
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the spatial pattern of unsphericity curvature, which describes the degree to which the shape of the topographic surface is nonspherical at a given point (Shary, 1995), from a digital elevation model (DEM). It is calculated as half the difference between the MaximalCurvature and the MinimalCurvature. Unsphericity has values equal to or greater than zero and is measured in units of m-1. Larger values indicate locations that are less spherical in form.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
See Also:
MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature, ProfileCurvature, TangentialCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--log | Display output values using a log-scale |
--zfactor | Z conversion factor |
Python function:
wbt.unsphericity(
dem,
output,
log=False,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=Unsphericity -i=DEM.tif -o=output.tif ^
--log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 11/01/2022
Last Modified: 28/11/2022
VerticalExcessCurvature
Note this tool is part of a WhiteboxTools extension product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).
This tool calculates the vertical excess curvature from a digital elevation model (DEM). Vertical excess curvature is the difference of profile (vertical) and minimal curvatures at a location (Shary, 1995). This variable has positive values, zero or greater. Florinsky (2017) states that vertical excess curvature measures the extent to which the bending of a normal section having a common tangent line with a slope line is larger than the minimal bending at a given point of the surface. Vertical excess curvature is measured in units of m-1.
The user must specify the name of the input DEM (--dem
) and the output raster (--output
). The
The Z conversion factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform
the output raster (--log
). Transforming the values applies the equation by Shary et al. (2002):
Θ' = sign(Θ) ln(1 + 10n|Θ|)
where Θ is the parameter value and n is dependent on the grid cell size.
For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).
References:
Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.
Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.
Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.
Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.
See Also:
TangentialCurvature, ProfileCurvature, MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Name of the input raster DEM file |
-o, --output | Name of the output raster image file |
--log | Display output values using a log-scale |
--zfactor | Z conversion factor |
Python function:
wbt.vertical_excess_curvature(
dem,
output,
log=False,
zfactor=1.0,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=VerticalExcessCurvature -i=DEM.tif ^
-o=output.tif --log
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 11/01/2022
Last Modified: 28/11/2022
Viewshed
This tool can be used to calculate the viewshed (i.e. the visible area) from a
location (i.e. viewing station) or group of locations based on the topography defined
by an input digital elevation model (DEM). The user must specify the name of the input
DEM (--dem
), a viewing station input vector file (--stations
), the output file name
(--output
), and the viewing height (--height
).
Viewing station locations are specified as points within an input shapefile. The output
image indicates the number of stations visible from each grid cell. The viewing height
is in the same units as the elevations of the DEM and represent a height above the ground
elevation from which the viewshed is calculated.
Viewshed should be used when there are a relatively small number of target sites for which visibility needs to be assessed. If you need to assess general landscape visibility as a land-surface parameter, the VisibilityIndex tool should be used instead.
Viewshed analysis is a very computationally intensive task. Depending on the size of the input DEM grid and the number of viewing stations, this operation may take considerable time to complete. Also, this implementation of the viewshed algorithm does not account for the curvature of the Earth. This should be accounted for if viewsheds are being calculated over very extensive areas.
See Also: VisibilityIndex
Parameters:
Flag | Description |
---|---|
--dem | Input raster DEM file |
--stations | Input viewing station vector file |
-o, --output | Output raster file |
--height | Viewing station height, in z units |
Python function:
wbt.viewshed(
dem,
stations,
output,
height=2.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Viewshed -v --wd="/path/to/data/" ^
--dem='dem.tif' --stations='stations.shp' -o=output.tif ^
--height=10.0
Author: Dr. John Lindsay
Created: 10/01/2018
Last Modified: 12/10/2018
VisibilityIndex
This tool can be used to calculate a measure of landscape visibility based on the
topography of an input digital elevation model (DEM). The user must specify the name of
the input DEM (--dem
), the output file name (--output
), the viewing height (--height
),
and a resolution factor (--res_factor
).
Viewsheds are calculated for a subset of grid cells in the DEM based on the resolution
factor. The visibility index value (0.0-1.0) indicates the proportion of tested stations
(determined by the resolution factor) that each cell is visible from. The viewing height
is in the same units as the elevations of the DEM and represent a height above the ground
elevation. Each tested grid cell's viewshed will be calculated in parallel. However, visibility
index is one of the most computationally intensive geomorphometric indices to calculate.
Depending on the size of the input DEM grid and the resolution factor, this operation may take
considerable time to complete. If the task is too long-running, it is advisable to raise the
resolution factor. A resolution factor of 2 will skip every second row and every second column
(effectively evaluating the viewsheds of a quarter of the DEM's grid cells). Increasing this
value decreases the number of calculated viewshed but will result in a lower accuracy estimate
of overall visibility. In addition to the high computational costs of this index, the tool
also requires substantial memory resources to operate. Each of these limitations should be
considered before running this tool on a particular data set. This tool is best to apply
on computer systems with high core-counts and plenty of memory.
See Also: Viewshed
Parameters:
Flag | Description |
---|---|
--dem | Input raster DEM file |
-o, --output | Output raster file |
--height | Viewing station height, in z units |
--res_factor | The resolution factor determines the density of measured viewsheds |
Python function:
wbt.visibility_index(
dem,
output,
height=2.0,
res_factor=2,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=VisibilityIndex -v ^
--wd="/path/to/data/" --dem=dem.tif -o=output.tif ^
--height=10.0 --res_factor=4
Author: Dr. John Lindsay
Created: 07/04/2018
Last Modified: 12/10/2018
WetnessIndex
This tool can be used to calculate the topographic wetness index, commonly used in the TOPMODEL rainfall-runoff framework. The index describes the propensity for a site to be saturated to the surface given its contributing area and local slope characteristics. It is calculated as:
WI = Ln(As / tan(Slope))
Where As
is the specific catchment area (i.e. the upslope contributing area per unit contour length) estimated using one of
the available flow accumulation algorithms in the Hydrological Analysis toolbox. Notice that As
must not be log-transformed
prior to being used; log-transformation of As
is a common practice when visualizing the data. The slope image should be
measured in degrees and can be created from the base digital elevation model (DEM) using the Slope tool. Grid cells with a
slope of zero will be assigned NoData in the output image to compensate for the fact that division by zero is infinity.
These very flat sites likely coincide with the wettest parts of the landscape. The input images must have the same grid dimensions.
Grid cells possessing the NoData value in either of the input images are assigned NoData value in the output image. The output raster is of the float data type and continuous data scale.
See Also Slope, D8FlowAccumulation, DInfFlowAccumulation, FD8FlowAccumulation, BreachDepressionsLeastCost
Parameters:
Flag | Description |
---|---|
--sca | Input raster specific contributing area (SCA) file |
--slope | Input raster slope file (in degrees) |
-o, --output | Output raster file |
Python function:
wbt.wetness_index(
sca,
slope,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=WetnessIndex -v --wd="/path/to/data/" ^
--sca='flow_accum.tif' --slope='slope.tif' -o=output.tif
Author: Dr. John Lindsay
Created: 02/07/2017
Last Modified: 21/01/2018