WhiteboxTools Version 1.5.0
Dr. John B. Lindsay © 2017-2021
Geomorphometry and Hydrogeomatics Research Group
University of Guelph
Guelph, Canada
June 01, 2021



Sponsored by:

Introduction

WhiteboxTools is an advanced geospatial data analysis platform created by Prof. John Lindsay at the University of Guelph's Geomorphometry and Hydrogeomatics Research Group (GHRG). The project began in January 2017 and quickly evolved in terms of its analytical capabilities. The WhiteboxTools homepage contains more project information and the software download site.

Project Highlights

• Contains more than 440 tools for processing various types of geospatial data.
• Many tools operate in parallel, taking full advantage of your multi-core processor.
• Written in the safe and cross-platform systems programming language Rust and compiled to highly efficient native code.
• Small stand-alone application with no external dependencies, making installation as easy as downloading the 8Mb zip file and decompressing it.
• Simple yet powerful Python scripting interface that allows users to develop custom scripted workflows.
• Embed WhiteboxTools functions into hetergenous scripting environments along with ArcPy, GDAL, and other geoprocessing libraries.
• Serves as an analytical back-end for other GIS and remote sensing software (e.g. the QGIS Whitebox for Processing plugin).
• Permissive MIT open-source license allows for ready integration with other software.
• Transparent software philosopy allows for easy source code inspection and rapid innovation and development.

What can WhiteboxTools do?

WhiteboxTools can be used to perform common geographical information systems (GIS) analysis operations, such as cost-distance analysis, distance buffering, and raster reclassification. Remote sensing and image processing tasks include image enhancement (e.g. panchromatic sharpening, contrast adjustments), image mosaicking, numerous filtering operations, simple classification (k-means clustering), and common image transformations. WhiteboxTools also contains advanced tooling for spatial hydrological analysis (e.g. flow-accumulation, watershed delineation, stream network analysis, sink removal), geomorphometric analysis (e.g. common terrain indices such as slope, curvatures, wetness index, hillshading; hypsometric analysis; multi-scale topographic position analysis), and LiDAR data processing. LiDAR point clouds can be interrogated (LidarInfo, LidarHistogram), segmented, tiled and joined, analyzed for outliers, interpolated to rasters (DEMs, intensity images), and ground-points can be classified or filtered.

WhiteboxTools is not a cartographic or spatial data visualization package; instead it is meant to serve as an analytical backend for other data visualization software, mainly GIS (e.g. Whitebox GAT and QGIS).

WhiteboxTools vs. Whitebox Geospatial Analysis Tools (GAT)

Although WhiteboxTools was first developed with to serve as a source of plugin tools for the Whitebox Geospatial Analysis Tools (GAT) open-source GIS project, the tools contained in the library are stand-alone and can run outside of the larger Whitebox GAT project. See Interacting With WhiteboxTools From the Command Prompt for further details. There have been a large number of requests to call Whitebox GAT tools and functionality from outside of the Whitebox GAT user-interface (e.g. from Python automation scripts). WhiteboxTools is intended to meet these usage requirements. For example, a WhiteboxTools plug-in for QGIS is available.

In this manual, WhiteboxTools refers to the standalone geospatial analysis library, a collection of tools contained within a compiled binary executable command-line program and the associated Python scripts that are distributed alongside the binary file (e.g. whitebox_tools.py and wb_runner.py). Whitebox Geospatial Analysis Tools and Whitebox GAT refer to the GIS software, which includes a user-interface (front-end), point-and-click tool interfaces, and cartographic data visualization capabilities. Importantly, WhiteboxTools and Whitebox GAT are related but separate projects.

Why is it named WhiteboxTools?

The project name WhiteboxTools clearly takes it inspiration from the related project Whitebox GAT. However, the name Whitebox is intended to convey opposition to a 'black box' system, one for which only the inputs and outputs may be observed and the internal workings may not be scrutinized. WhiteboxTools is inspired by the concept of open-access software, the tenants of which were described by Lindsay (2014)¹. Open-access software can be viewed as a complementary extension to the traditional open-source software (OSS) model of development. The concept of open access has been previously defined in the context of publishing scholarly literature in a way that removes financial, legal, and technical access barriers to knowledge transfer. Lindsay (2014) argued that the stated goals of reducing barriers associated with knowledge transfer applies equally to the software used in research. Open-access software is distinct from other OSS in that it has an explicitly stated design goal of reducing barriers to the transfer of knowledge to the user community. Direct insight into the workings of algorithm design and implementation allows for educational opportunities and increases the potential for rapid innovation, experimentation with algorithms, and community-directed development. This is particularly important in geomatics because many geospatial algorithms are complex and are strongly affected by implementation details. Also, there are often multiple competing algorithms for accomplishing the same task and the choice of one method over another can greatly impact the outcome of a workflow.

All OSS allow users the opportunity to download the source code and inspect the software’s internal workings. However, traditional OSS often does not lend itself to end-user source code inspection. Open-access software, by comparison, is designed from the project's inception in a way that reduces the barriers that typically discourage end-users from examining the algorithm and implementation details associated with specific software artifacts. WhiteboxTools attempts to address some of the barriers to knowledge transfer by allowing users to view the source code associated with each tool directly (e.g. --viewcode=ExtendVectorLines). This functionality removes the need to download separate, and often large, project source code files and eliminates the requisite familiarity with the project to identify the code sections related to the operation of the tool of interest. The viewcode flag is the embodiment of a design philosophy that is intended to empower the user community. Each tool included in the library has been written in a way to isolate the major functionality within a single file, thereby easing the task of interpreting the code (traditional coding style would split complex code among numerous files). This design goal is also why the developers have chosen to exclude external libraries commonly found in other similarly software (e.g. GDAL), thereby simplifying the installation process and code interpretation. This approach has the potential to encourage further community involvement and experimentation with geospatial analysis techniques.

¹: Lindsay, JB. 2014. The Whitebox Geospatial Analysis Tools project and open-access GIS. Proceedings of the GIS Research UK 22nd Annual Conference, The University of Glasgow, 16-18 April, DOI: 10.13140/RG.2.1.1010.8962.

Setting Up WhiteboxTool

WhiteboxTools is a stand-alone executable command-line program with no actual installation. Download the appropriate file for your system from the GitHub site or from the Geomorphometry and Hydrogeomatics Research Group homepage and decompress the folder. Pre-compiled binaries can be downloaded for MS Windows, MacOS, and Linux operating systems. Depending on your operating system, you may need to grant the WhiteboxTools executable file execution privileges before running it.

If you intend to use WhiteboxTools from the command prompt (i.e. a terminal application), you may wish to add the directory containing the WhiteboxTools executable file to your system PATH variable. Doing so will greatly simplify usage of the library from your terminal. Instructions for doing this depend on your operating system and can be found on the Internet.

If you intend to use the Python programming interface for WhiteboxTools you will need to have Python 3 installed. Please note that the Python interface will not work correctly with Python 2. If your system has Python 2 as the default Python version, it is possible to install Python 3 alongside your current version. You may need to use the python3 command in place of the usual python if this is the case.

Building WhiteboxTools From Source Code

Most users rely on the pre-compiled versions of WhiteboxTools and will never need to compile the software from its source code. There are two circumstances under which you may find that you need to build your own binary executable: 1) if you need a binary compiled for a platform other than the project-supported operating systems, and 2) if you require a bleeding-edge feature or bug-fix only available in the development branch. It is likely that WhiteboxTools will work on a wider variety of operating systems and architectures than those of the distributed pre-compiled binaries. If you do not find your operating system/architecture in the list of available WhiteboxTool binaries, then compilation from source code will be necessary. WhiteboxTools can be compiled from the source code with the following steps:

1. Install the Rust compiler; Rustup is recommended for this purpose. Further instruction can be found at this link.

The proper way to install Rustup depends on your operating system and instructions can be found on the Rust install page. For Unix-type OSs (including linux and MacOS), the recommended install command is:

curl https://sh.rustup.rs -sSf | sh

After installing Rustup, install the Rust compiler and tools (including the Cargo package manager and build tool):

rustup install stable

Note, you may need to install a linker in addition to the Rust compiler (e.g. MS Visual C++ 2015 Build Tools on MS Windows; XCode on MacOS).

2. Download the WhiteboxTools source code. To download the code, click the green Clone or download button on the GitHub repository site.

3. Decompress the zipped download file.

4. Open a terminal (command prompt) window and change the working directory to the whitebox_tools sub-folder, which is contained within the decompressed downloaded Whitebox GAT folder:

>> cd /path/to/folder/whitebox_tools/

5. Finally, use the rust package manager Cargo, which will be installed alongside Rust, to compile the executable:

>> cargo build --release

Depending on your system, the compilation may take several minutes. When completed, the compiled binary executable file will be contained within the whitebox_tools/target/release/ folder. Type ./whitebox_tools --help at the command prompt (after changing the directory to the containing folder) for information on how to run the executable from the terminal.

The '>>' is shorthand used in this document to denote the command prompt and is not intended to be typed.

Be sure to follow the instructions for installing Rust carefully. In particular, if you are installing on Microsoft Windows, you must have a linker installed prior to installing the Rust compiler (rustc). The Rust webpage recommends either the MS Visual C++ 2015 Build Tools or the GNU equivalent and offers details for each installation approach.

Using WhiteboxTools

Users interact with the WhiteboxTools platform either from a command prompt (i.e. terminal), through the Python, R language, or Nim interfaces, or from one of the available graphical user interfaces (GUI) applications.

Interfacing With Python

Important note: all of the following material assumes the user system is configured with Python 3. The code snippets below are not guaranteed to work with older versions of the language.

By combining the WhiteboxTools library with a high-level scripting language, such as Python, users are capable of creating powerful stand-alone geospatial applications and workflow automation scripts. In fact, WhiteboxTools functionality can be called from many different programming languages. However, given the prevalent use of the Python language in the geospatial fields, the library is distributed with several resources specifically aimed at Python scripting. This section focuses on how Python programming can be used to interact with the WhiteboxTools library.

If you use the Python package manager PIP, you may install WhiteboxTools at the command prompt with pip install whitebox. The PIP package is maintained by Prof. Qiusheng Wu. There is also an Anaconda package, which can be installed with conda install -c conda-forge whitebox_tools , although it is unclear if this package is regularly updated to reflect the latest versions of WhiteboxTools.

Using the whitebox_tools.py script

Interacting with WhiteboxTools from Python scripts is easy. To begin, each script must start by importing the WhiteboxTools class, contained with the whitebox_tools.py script; a new WhiteboxTools object can then be created:

from WBT.whitebox_tools import WhiteboxTools

wbt = WhiteboxTools()

Depending on the relative location of the WhiteboxTools directory and the script file that you are importing to, the import statement may need to be altered slightly. In the above script, it is assumed that the folder containing the WhiteboxTools files (including the whitebox_tools Python script) is named WBT (Line 1) and that the calling script that is importing WhiteboxTools is located in the parent directory of WBT. See An Example WhiteboxTools Python Project for more details on project set-up. The use of wbt to designate the WhiteboxTools object variable in the above script (Line 3) is just the convention used in this manual and other project resources. In fact, any variable name can be used for this purpose.

The WhiteboxTools class expects to find the WhiteboxTools executable file (whitebox_tools.exe on Windows and whitebox_tools on other platforms) within the same directory (WBT) as the whitebox_tools.py script. If the binary file is located in a separate directory, you will need to set the executable directory as follows:

wbt.set_whitebox_dir('/local/path/to/whitebox/binary/')

Individual tools can be called using the convenience methods provided in the WhiteboxTools class:

# This line performs a 5 x 5 mean filter on 'inFile.tif':
wbt.mean_filter('/file/path/inFile.tif', '/file/path/outFile.tif', 5, 5)

Each tool has a cooresponding convenience method. The listing of tools in this manual includes information about each tool's Python convienience method, including default parameter values. Parameters with default values may be optionally left off of function calls. In addition to the convenience methods, tools can be called using the run_tool() method, specifying the tool name and a list of tool arguments.

source = "source.tif"
cost = "cost.tif"
out_accum = "accum.tif"
out_backlink = "backlink.tif"
args = []
args.append("--source='{}'".format(source))
args.append("--cost='{}'".format(cost))
args.append("--out_accum='{}'".format(out_accum))
args.append("--out_backlink='{}'".format(out_backlink))
self.run_tool('cost_distance', args)

Each of the tool-specific convenience methods collect their parameters into a properly formated list and then ultimately call the run_tools() method. Notice that while internally whitebox_tools.exe uses CamelCase (e.g. MeanFilter) to denote tool names, the Python interface of whitebox_tools.py uses snake_case (e.g. mean_filter), according to Python style conventions. The only exceptions are tools with names that clash with Python keywords (e.g. And(), Not(), and Or()).

The return value can be used to check for errors during operation:

if wbt.ruggedness_index('/path/DEM.tif', '/path/ruggedness.tif') != 0:
    # Non-zero returns indicate an error.
    print('ERROR running ruggedness_index')

If your data files tend to be burried deeply in layers of sub-directories, specifying complete file names as input parameters can be tedius. In this case, the best option is setting the working directory before calling tools:

from whitebox_tools import WhiteboxTools

wbt = WhiteboxTools()
wbt.set_whitebox_dir("/path/to/data/") # Sets the Whitebox working directory

# Setting the following to True enables tools to output DEFLATE compressed GeoTIFFs.
# You only need to do this once, if you wish all tools to compress their raster
# outputs.
wbt.set_compress_rasters(True) 

# Because the working directory has been set, file arguments can be
# specified simply using file names, without paths.
wbt.d_inf_flow_accumulation("DEM.tif", "output.tif", log=True)

An advanced text editor, such as VS Code or Atom, can provide hints and autocompletion for available tool convenience methods and their parameters, including default values (Figure 1).

Sometimes it can be useful to print a complete list of available tools:

print(wbt.list_tools()) # List all tools in WhiteboxTools

The list_tools() method also takes an optional keywords list to search for tools:

# Lists tools with 'lidar' or 'LAS' in tool name or description.
print(wbt.list_tools(['lidar', 'LAS']))

To retrieve more detailed information for a specific tool, use the tool_help() method:

print(wbt.tool_help("elev_percentile"))

tool_help() prints tool details including a description, tool parameters (and their flags), and example usage at the command line prompt. The above statement prints this report:

ElevPercentile
Description:
Calculates the elevation percentile raster from a DEM.
Toolbox: Geomorphometric Analysis
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.

Example usage:
>>./whitebox_tools -r=ElevPercentile -v --wd="/path/to/data/" --dem=DEM.tif
>>-o=output.tif --filterx=25

A note on default parameter values

Each tool contains one or more parameters with default values. These will always be listed after any input parameters that do not have default values. You do not need to specify a parameter with a default value if you accept the default. That is, unless you intend to specify an input value different from the default, you may leave these parameters off of the function call. However, be mindful of the fact that Python assigns values to parameters based on order, unless parameter names are specified.

Consider the Hillshade tool as an example. The User Manual gives the following function definition for the tool:

hillshade(
dem,
output,
azimuth=315.0,
altitude=30.0,
zfactor=1.0,
callback=default_callback)

The dem and output parameters do not have default values and must be specified every time you call this function. Each of the remaining parameters have default values and can, optionally, be left off of calls to the hillshade function. As an example, say I want to accept the default values for all the parameters except altitude. I would then need to use the named-parameter form of the function call:

wbt.hillshade(
"DEM.tif",
"hillshade.tif",
altitude=20.0)

If I hadn't specified the parameter name for altitude, Python would have assumed that the value 20.0 should be assigned to the third parameter, azimuth.

Handling tool output

Tools will frequently print text to the standard output during their execution, including warnings, progress updates and other notifications. Sometimes, when users run many tools in complex workflows and in batch mode, these output messages can be undesirable. Most tools will have their outputs suppressed by setting the verbose mode to False as follows:

wbt.set_verbose_mode(False)

Alternatively, it may be helpful to capture the text output of a tool for custom processing. This is achieved by specifying a custom callback function to the tool's convenience function:

# This callback function suppresses printing progress updates,
# which always use the '%' character. The callback function
# approach is flexible and allows for any level of complex
# interaction with tool outputs.
def my_callback(value):
    if not "%" in value:
        print(value)

wbt.slope('DEM.tif', 'slope_raster.tif', callback=my_callback)

Every convienience function takes an optional callback as the last parameter. The default callback simply prints tool outputs to the standard output without any additional processing. The default callback itself can be overridden, instead of having to set callbacks in convienience functions individually:

wbt.set_default_callback(my_callback)

Callback functions can serve as a means of cancelling operations:

def my_callback(value):
    if user_selected_cancel_btn: # Assumes a 'Cancel' button on a GUI
        print('Cancelling operation...')
        wbt.cancel_op = True
    else:
        print(value)

wbt.breach_depressions('DEM.tif', 'DEM_breached.tif', callback=my_callback)

Additional functions in whitebox_tools.py

The whitebox_tools.py script provides several other functions for interacting with the WhiteboxTools library, including:

# Print the WhiteboxTools help...a listing of available commands
print(wbt.help())

# Print the WhiteboxTools license
print(wbt.license())

# Print the WhiteboxTools version
print("Version information: {}".format(wbt.version()))

# Get the toolbox associated with a tool
tb = wbt.toolbox('lidar_info')

# Retrieve a JSON object of a tool's parameters.
tp = wbt.tool_parameters('raster_histogram')

# Opens a browser and navigates to a tool's source code in the
# WhiteboxTools GitHub repository
wbt.view_code('watershed')

# Use this function to specify whether output GeoTIFF rasters should be 
# compressed using the DEFLATE compression method.
wbt.set_compress_rasters(True) 

For a working example of how to call functions and run tools from Python, see the whitebox_example.py Python script, which is distributed with the WhiteboxTools library.

Additional resources for using WhiteboxTools' Python interface can be found on the Tutorials site of the WhiteboxTools home page. This site contains in-depth tutorials on topics such as, 'Interpolating LiDAR data'.

An Example Python Project

In this section, we will create a Python project that utilizes the WhiteboxTools library to interpolate a LiDAR point-cloud, to process the resulting digital elevation model (DEM) to make it suitable for hydrological applications, and to perform a simple flow-accumulation operation. I suggest using an advanced coding text editor, such as Visual Studio Code or Atom, for this tutorial, but Python code can be written using any basic text editor.

Begin by creating a dedicated project directory called FlowAccumExample and copy WhiteboxTools binary file (i.e. the compressed file downloaded from the Geomorphometry & Hydrogeomatics Research Group website) into this folder. Using the decompression software on your computer, decompress (i.e. an operation sometimes called unzipping) the file into the newly created FlowAccumExample directory. You will find the compressed file contains a folder with contents similar to the following:

The folder contains a number of files, including the WhiteboxTools executable file, the whitebox_tools.py python script, the WhiteboxTools Runner (wb_runner.py; see below), and this user manual. It is likely that the folder has a name that reflects the operating system and architecture that the binary file was compiled for (e.g. WhiteboxTools_darwin_amd64). Rename this directory to WBT. Also note, depending on your decompression software, it may be the case that the contents of the WBT folder itself contains a sub-directory that actually holds these files. If this is the case, be sure to move the contents of the sub-directory into the WBT parent directory.

Using your text editor, create a new Python script file, called FlowAccumulation.py within the FlowAccumExample directory. We will begin by importing the WhiteboxTools class from the whitebox_tools.py script contained within the WBT sub-directory. Unfortunately, Python's module system is only able to import classes and function definitions declared in external Python scripts if these external files are contained somewhere on the Python path or in the directory containing the script file into which you are importing. This is important because based on the project structure that we have established, the whitebox_tools.py script is actually contained within a sub-directory of the FlowAccumExample directory and is therefore not directly accessible, unless you have previously installed the script on the Python path. Another, perhaps easier solution to this problem is to create a file named __init__.py (those are two leading and trailing underscore characters) within the FlowAccumExample directory. The presence of this empty file will make Python treat the WBT directory as containing packages, in this case, the whitebox_tools package. For more information, see the Python documentation on modules and packages.

At this stage, you should have a project directory structure like the following:

Many operating systems will disallow the execution of files that are downloaded directly from the Internet. As such, it is possible that you will need to explicitly give the whitebox_tools.exe permission to execute on your computer (Note: here we are referring to the compiled WhiteboxTools binary file and not the similarly named Python script whitebox_tools.py also contained in the folder). The procedure for doing this depends on your specific operating system. On MacOS, for example, this is usually achieved using the 'Security & Privacy' tab under 'System Preferences'. To test whether whitebox_tools.exe has permission to run on your system, double-click the file. If the file is configured to execute, a command terminal will automatically open and the WhiteboxTools help documentation and a listing of the available tools will be printed. If this does not occur, you likely need to give the file permission to execute.

Using your text editor, you may now add the following lines to the FlowAccumulation.py file.

from WBT.whitebox_tools import WhiteboxTools

wbt = WhiteboxTools()

In the import statement, WBT is a reference to the package folder containing the WhiteboxTools files; whitebox_tools is a reference to the whitebox_tools.py script contained with this package folder; and WhiteboxTools is a reference to the WhiteboxTools class contained within this script file. Please note that if you named your directory containing the WhiteboxTools files something other than WBT, you would need to alter the import statement accordingly.

Visit the Geomorphometry and Hydrogeomatics Research Group website and download the St. Elis Mountains and Gulf of Alaska sample data set (StElisAk.las) from the WhiteboxTools section of the site. This file contains a LiDAR point cloud that has been previously filtered to remove points associated with non-ground returns, mainly trees (Figure 4). Create a sub-directory within the project folder called 'data' and copy StElisAk.las into the folder.

Now we can complete our flow accumulation analysis with the following code:

import os
from WBT.whitebox_tools import WhiteboxTools

wbt = WhiteboxTools()

# Set the working directory, i.e. the folder containing the data,
# to the 'data' sub-directory.
wbt.set_working_dir(os.path.dirname(os.path.abspath(__file__)) + "/data/")

# When you're running mulitple tools, the outputs can be a tad
# chatty. In this case, you may want to suppress the output by
# setting the verbose mode to False.
# wbt.set_verbose_mode(False)

# Interpolate the LiDAR data using an inverse-distance weighting
# (IDW) scheme.
print("Interpolating DEM...")
wbt.lidar_idw_interpolation(
i="StElisAk.las",
output="raw_dem.tif",
parameter="elevation",
returns="last",
resolution=1.0,
weight=1.0,
radius=2.5
)

# The resulting DEM will contain NoData gaps. We need to fill
# these in by interpolating across the gap.
print("Filling missing data...")
wbt.fill_missing_data(
i="raw_dem.tif",
output="dem_nodata_filled.tif",
filter=11
)

# This DEM will contain grid cells that have no lower neighbours.
# This condition is unsuited for flow-path modelling applications
# because these operations assume that each interior cell in the
# DEM has at least one downslope neighour. We'll use an operation
# called depression breaching to 'fix' the elevations within the
# DEM to enforce continuous flow.
print("Performing flow enforcement...")
wbt.breach_depressions(
dem="dem_nodata_filled.tif",
output="dem_hydro_enforced.tif"
)

# Lastly, perform the flow accumulation operation using the
# D-infinity flow algorithm.
print("Performing flow accumulation...")
wbt.d_inf_flow_accumulation(
dem="dem_hydro_enforced.tif",
output="flow_accum.tif",
log=True
)

print("Complete!")

To run the above script, open a terminal (command prompt), cd to the script containing folder, and run the following command:

>>python FlowAccumulation.py

If Python 3 is not your default Python version, substitute python3 for python in the above command line. The final D-infinity flow accumulation raster can be displayed in any GIS software of choice and should look similar to Figure 5.

Interfacing With R

In addition to the Python interface, the WhiteboxTools library is also accessible from an R language package. R is a common programming language used within the statistical and scientific computing communities and the R WhiteboxTools package targets these groups. Prof. Qiusheng Wu, at Binghamton University (SUNY) maintains the R package.

Installation

WhiteboxTools is available on R-Forge and can be installed with the command:

install.packages("whitebox", repos="http://R-Forge.R-project.org")

You can alternatively install the development version of the R package whitebox from the GitHub repository as follows:

if (!require(devtools)) install.packages('devtools')
devtools::install_github("giswqs/whiteboxR")

You will also need to make sure your machine is able to build packages from source. See Package Development Prerequisites for the tools needed for your operating system.

Usage

A complete list of functions available in the whitebox R package can be found within the GitHub repository. A comprehensive demonstration, complete with detailed examples, is also available from this site.

About WhiteboxTools

library(whitebox)

# Prints the whitebox-tools help...a listing of available commands
print(wbt_help())

# Prints the whitebox-tools license
print(wbt_license())

# Prints the whitebox-tools version
print(wbt_version())

# Prints the toolbox for a specific tool.
print(wbt_toolbox())

# List all available tools in whitebox-tools
print(wbt_list_tools())

# Lists tools with 'lidar' in tool name or description.
print(wbt_list_tools("lidar"))

# Prints the help for a specific tool.
print(wbt_tool_help("lidar_info"))

# Retrieves the tool parameter descriptions for a specific tool.
print(wbt_tool_parameters("slope"))

# View the source code for a specific tool on the source code repository.
print(wbt_view_code("breach_depressions"))

How to run tools?

Tool names in the whitebox R package can be called using the snake_case (e.g. lidar_info). A comprehensive list of all available function tools can be found on the package repository site. For example:

library(whitebox)

# Set input raster DEM file
dem <- system.file("extdata", "DEM.tif", package="whitebox")

# Run tools
feature_preserving_denoise(dem, "./smoothed.tif", filter=9)
breach_depressions("./smoothed.tif", "./breached.tif")
d_inf_flow_accumulation(dem, "./flow_accum.tif", verbose_mode=FALSE)

Interfacing With Nim

Nim is a statically compiled programming language that has Python-like syntax (e.g. significant whitespace) and c-level efficiency. It has been used by Python programmers who are looking for a faster, more efficient language but don't want to give up the elegant and terse syntax of Python.

wbt_nim is a Nim-based application programming interface (API) used to call WhiteboxTools functionality from Nim programs. The documentation for wbt_nim can be found on GitHub. To use this API, simply copy the source file into your Nim project and import wbt_nim. You will need to ensure that the WhiteboxTools binary, pre-compiled for your operating system, is also within the same directory. Otherwise, use the setExecutableDirectory function to tell wbt_nim where the WhiteboxTools binary is located on your system.

The Nim interface is very similar to the Python API:

import wbt_nim
import options, strformat, strutils

proc main() =
    # Create a new WhiteboxTools object
    var wbt = newWhiteboxTools()

    # Tell the wbt object where to find the WhiteboxTools executable.
    # If you don't do this, it assumes that it is in the same directory as 
    # your Nim code.
    wbt.setExecutableDirectory("/Users/johnlindsay/Documents/programming/whitebox-tools/")

    # Set the working directory
    let wd = "/Users/johnlindsay/Documents/data/LakeErieLidar/"
    wbt.setWorkingDirectory(wd)

    # Set the verbose mode. By default it is 'true', which prints all output
    # from WBT. If you need to make it less chatty, set it to false.
    wbt.setVerboseMode(false)

    # By default, all GeoTiff outputs of tools will be compressed. You can 
    # modify this with the following:
    wbt.setCompressRasters(false)

    # Print out the version of WBT:
    echo(wbt.getVersionInfo())

    # WhiteboxTools is open-access software. If you'd like to see the source 
    # code for any tool, simply use the following:
    discard wbt.viewCode("balanceContrastEnhancement")

    # To get a brief description of a tool and it's parameters:
    echo(wbt.getToolHelp("breachDepressionsLeastCost"))

    # If you'd like to see more detailed help documentation:
    discard wbt.viewHelpPage("breachDepressionsLeastCost")
    # This will open the default browser and navigate to the relevant tool help.

    # Here's an example of how to run a tool:
    if wbt.hillshade(
        dem="90m_DEM.tif",
        output="tmp1.tif",
        azimuth=180.0,
        altitude=45.0,
        zFactor=1.0
    ) != 0:
        echo("Error while running hillshade.")

    # If you haven't previously set the working directory, you need to include
    # full file path names.

    # You can capture tool output by creating a custom callback function
    proc myCallback(value: string) =
        if not value.contains("%"):
            echo(value)
        else:
            let s = value.replace("%", "").strip()
            echo(fmt"{s} percent")

    wbt.setCallback(myCallback)
    
    # And to reset the default callback, which just prints to stdout
    wbt.setDefaultCallback()

main()

WhiteboxTools Runner

There is a Python script contained within the WhiteboxTools directory called 'wb_runner.py'. This script is intended to provide a very basic user-interface, WhiteboxTools Runner, for running the tools contained within the WhiteboxTools library. The user-interface uses Python's TkInter GUI library and is cross-platform. The user interface is currently experimental and is under heavy testing. Please report any issues that you experience in using it.

The script must be run from a directory that also contains the 'whitebox_tools.py' Python script and the 'whitebox_tools' executable file.

To launch the runner application, open a terminal and issue issue the following commands:

cd /path/to/whitebox_runner/script/
python3 wb_runner.py

If you recieve No module named '_tkinter' error when running the WhiteboxTools Runner on Linux, you likely need to install the python3-tk package:

• For Ubuntu, Linux Mint, try sudo apt-get install python3-tk
• For Manjaro, Arch Linux, try sudo pacman -S tk

QGIS Plugin

WhiteboxTools functionality can also be accessed conveniently through the popular open-source geospatial software QGIS. QGIS developer Alexander Bruy maintains a plugin for the toolbox called Whitebox For Processing.

The Whitebox for QGIS plugin works QGIS v3 but cannot be installed on the earlier v2 series.

Installation of the Plugin

1. From the Plugins menu, select Manage and Install Plugins....
2. Select the Settings tab and press the Add button.
3. In the Repository details dialog box, enter something logical, such as Alex Bruy Plugins in the Name textbox.
4. In the URL textbox, enter https://plugins.bruy.me/plugins/plugins.xml and press OK.

4. Select the All tab and enter the word 'whitebox' in the search box. Whitebox for Processing should appear the search listing. Select and check this toolbox and press the Install buttton.

Note that the QGIS plugin does not come with a copy of the WhiteboxTools executable and so you will still need to download WhiteboxTools from either the Geomorphometry and Hydrogeomatics Research Group website or the WhiteboxTools Github repository prior to running the plugin.

5. Once you've downloaded WhiteboxTools and decompressed (unzipped) the folder, select Options from under the Settings menu in QGIS.

6. Select the Processing tab and the Providers list item. You should find the WhiteboxTools entry there. Select the down arrow, and check the Activate and Log commands output checkboxes. Lastly, enter full file name of the WhiteboxTools executable file contained within the decompressed WhiteboxTools folder that you downloaded previously (see note above). If you are using a Mac or Linux computer, note that this may require you to 1) select a file contained in the folder that is not the executable (QGIS seems to exclude files without extensions, which the WhiteboxTools executable is on MacOS and Linux) then delete the file extension (see below). You will also need to leave the textbox by selecting any other feature on the dialog box before pressing the OK button.

You should now see the Whitebox toolbox within the Processing Toolbox at the right-hand side of the QGIS interface, as in the screenshots above.

ArcGIS Plugin

WhiteboxTools functionality can also be accessed conveniently through the ArcGIS. This WhiteboxTools front-end has been developed and is maintained by Prof. Qiusheng Wu, of Binghamton University (SUNY). This front-end is available from the Gihub repository. The plugin works for ArcGIS 10.6 and ArcGIS Pro; other version of ArcGIS have not been tested for support. Detailed instructions on installing and setting-up the ArcGIS toolbox can be found on the GitHub site.

Command-Line Interface

WhiteboxTools is a command-line program and can be run either by calling it from a terminal application with appropriate commands and arguments, or, more conveniently, by calling it from a script. The following commands are recognized by the WhiteboxTools library:

Generally, the Unix convention is that single-letter arguments (options) use a single hyphen (e.g. -h) while word-arguments (longer, more descriptive argument names) use double hyphens (e.g. --help). The same rule is used for passing arguments to tools as well. Use the --toolhelp argument to print information about a specific tool (e.g. --toolhelp=Clump).

Tool names can be specified either using the snake_case or CamelCase convention (e.g. lidar_info or LidarInfo).

The following is an example of calling the WhiteboxTools binary executable file directly from the command prompt:

>>./whitebox_tools --wd='/Users/johnlindsay/Documents/data/' ^
--run=DevFromMeanElev --input='DEM clipped.tif' ^
--output='DEV raster.tif' -v

Notice the quotation marks (single or double) used around directories and filenames, and string tool arguments in general. After the --run flag, used to call a tool, a series of tool-specific flags are provided to indicate the values of various input parameters. Note that the order of these flags is unimportant. Use the '-v' flag (run in verbose mode) to force the tool to print output to the command prompt. Please note that the whitebox_tools executable file must have permission to be executed; on some systems, this may require setting special permissions. Also, the above example uses the forward slash character (/), the directory path separator used on unix based systems. On Windows, users should use the back slash character (\) instead. Also, it is sometimes necessary to break (^) commands across multiple lines, as above, in order to better fit with the documents format. Actual command prompts (>>) should be contained to a single line.

Tools Reference

The WhiteboxTools library currently contains approximately 400 tools, which are organized into themed toolboxes, including:

• Data Tools
• Geomorphometric Analysis
• GIS Analysis
• Hydrological Analysis
• Image Analysis
• LiDAR Analysis
• Mathematical and Statistical Analysis
• Precision Agriculture
• Stream Network Analysis

To retrieve detailed information about a tool's input arguments and example usage, either use the toolhelp command from the terminal, or the wbt.tool_help('tool_name') function from the whitebox_tools.py script. The following is a complete listing of available tools, with brief descriptions, tool parameter, and example usage.

The Tool Index located at the end of the user manual contains a complete alphabetical listing of the available tools.

Data Tools

• AddPointCoordinatesToTable
• CleanVector
• ConvertNodataToZero
• ConvertRasterFormat
• CsvPointsToVector
• ExportTableToCsv
• JoinTables
• LinesToPolygons
• MergeTableWithCsv
• MergeVectors
• ModifyNoDataValue
• MultiPartToSinglePart
• NewRasterFromBase
• PolygonsToLines
• PrintGeoTiffTags
• RasterToVectorLines
• RasterToVectorPoints
• RasterToVectorPolygons
• ReinitializeAttributeTable
• RemovePolygonHoles
• SetNodataValue
• SinglePartToMultiPart
• VectorLinesToRaster
• VectorPointsToRaster
• VectorPolygonsToRaster

AddPointCoordinatesToTable

This tool modifies the attribute table of a vector of POINT ShapeType by adding two fields, XCOORD and YCOORD, containing each point's X and Y coordinates respectively.

Parameters:

Python function:

wbt.add_point_coordinates_to_table(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AddPointCoordinatesToTable -v ^
--wd="/path/to/data/" --input=points.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/09/2018

Last Modified: 12/10/2018

CleanVector

This tool can be used to remove all features in Shapefiles that are of the null ShapeType. It also removes line features with fewer than two vertices and polygon features with fewer than three vertices.

Parameters:

Python function:

wbt.clean_vector(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CleanVector -v --wd="/path/to/data/" ^
-i=input.shp -o=output.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 30/06/2019

Last Modified: 27/05/2020

ConvertNodataToZero

This tool can be used to change the value within the grid cells of a raster file (--input) that contain NoData to zero. The most common reason for using this tool is to change the background region of a raster image such that it can be included in analysis since NoData values are usually ignored by by most tools. This change, however, will result in the background no longer displaying transparently in most GIS. This change can be reversed using the SetNoDataValue tool.

See Also: SetNoDataValue, IsNoData

Parameters:

Python function:

wbt.convert_nodata_to_zero(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ConvertNodataToZero -v ^
--wd="/path/to/data/" --input=in.tif -o=NewRaster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

ConvertRasterFormat

This tool converts raster data from one format to another. It determines input/output raster formats based on extensions, but due to file extension naming collisions, it would be good to add user hints. For example, the extension 'grd' could belong to a SurferAscii or a Surfer7Binary. This is more important for distinguishing output files since input files can be read and distiguishing features idenfitied from the file structure. At the moment, this tool does not support user hints however.

Parameters:

Python function:

wbt.convert_raster_format(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: July 6, 2017

Last Modified: 12/10/2018

CsvPointsToVector

This tool can be used to import a series of points contained within a comma-separated values (*.csv) file (--input) into a vector shapefile of a POINT ShapeType. The input file must be an ASCII text file with a .csv extensions. The tool will automatically detect the field data type; for numeric fields, it will also determine the appropriate length and precision. The user must specify the x-coordinate (--xfield) and y-coordiante (--yfield) fields. All fields are imported as attributes in the output (--output) vector file. The tool assumes that the first line of the file is a header line from which field names are retreived.

See Also: MergeTableWithCsv, ExportTableToCsv

Parameters:

Python function:

wbt.csv_points_to_vector(
    i, 
    output, 
    xfield=0, 
    yfield=1, 
    epsg=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CsvPointsToVector -v ^
--wd="/path/to/data/" -i=points.csv -o=points.shp --xfield=0 ^
--yfield=1 --epsg=4326 

Source code on GitHub

Author: Prof. John Lindsay

Created: 07/08/2019

Last Modified: 28/01/2020

ExportTableToCsv

This tool can be used to export a vector's attribute table to a comma separated values (CSV) file. CSV files stores tabular data (numbers and text) in plain-text form such that each row corresponds to a record and each column to a field. Fields are typically separated by commas within records. The user must specify the name of the vector (and associated attribute file), the name of the output CSV file, and whether or not to include the field names as a header column in the output CSV file.

See Also: MergeTableWithCsv

Parameters:

Python function:

wbt.export_table_to_csv(
    i, 
    output, 
    headers=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ExportTableToCsv -v ^
--wd="/path/to/data/" -i=lines.shp -o=output.csv --headers 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/04/2018

Last Modified: 18/10/2019

JoinTables

This tool can be used to join (i.e. merge) a vector's attribute table with a second table. The user must specify the name of the vector file (and associated attribute file) as well as the primary key within the table. The primary key (--pkey flag) is the field within the table that is being appended to that serves as the identifier. Additionally, the user must specify the name of a second vector from which the data appended into the first table will be derived. The foreign key (--fkey flag), the identifying field within the second table that corresponds with the data contained within the primary key in the table, must be specified. Both the primary and foreign keys should either be strings (text) or integer values. Fields containing decimal values are not good candidates for keys. Lastly, the names of the field within the second file to include in the merge operation can also be input (--import_field). If the --import_field field is not input, all fields in the attribute table of the second file, that are not the foreign key nor FID, will be imported to the first table.

Merging works for one-to-one and many-to-one database relations. A one-to-one relations exists when each record in the attribute table corresponds to one record in the second table and each primary key is unique. Since each record in the attribute table is associated with a geospatial feature in the vector, an example of a one-to-one relation may be where the second file contains AREA and PERIMETER fields for each polygon feature in the vector. This is the most basic type of relation. A many-to-one relation would exist when each record in the first attribute table corresponds to one record in the second file and the primary key is NOT unique. Consider as an example a vector and attribute table associated with a world map of countries. Each country has one or more more polygon features in the shapefile, e.g. Canada has its mainland and many hundred large islands. You may want to append a table containing data about the population and area of each country. In this case, the COUNTRY columns in the attribute table and the second file serve as the primary and foreign keys respectively. While there may be many duplicate primary keys (all of those Canadian polygons) each will correspond to only one foreign key containing the population and area data. This is a many-to-one relation. The JoinTables tool does not support one-to-many nor many-to-many relations.

See Also: MergeTableWithCsv, ReinitializeAttributeTable, ExportTableToCsv

Parameters:

Python function:

wbt.join_tables(
    input1, 
    pkey, 
    input2, 
    fkey, 
    import_field, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=JoinTables -v --wd="/path/to/data/" ^
--i1=properties.shp --pkey=TYPE --i2=land_class.shp ^
--fkey=VALUE --import_field=NEW_VALUE 

Source code on GitHub

Author: Prof. John Lindsay

Created: 07/10/2018

Last Modified: 22/11/2018

LinesToPolygons

This tool converts vector polylines into polygons. Note that this tool will close polygons that are open and will ensure that the first part of an input line is interpreted as the polygon hull and subsequent parts are considered holes. The tool does not examine input lines for line crossings (self intersections), which are topological errors.

See Also: PolygonsToLines

Parameters:

Python function:

wbt.lines_to_polygons(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LinesToPolygons -v ^
--wd="/path/to/data/" -i=input.shp -o=output.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/09/2018

Last Modified: 12/10/2018

MergeTableWithCsv

This tool can be used to merge a vector's attribute table with data contained within a comma separated values (CSV) text file. CSV files stores tabular data (numbers and text) in plain-text form such that each row is a record and each column a field. Fields are typically separated by commas although the tool will also support seimi-colon, tab, and space delimited files. The user must specify the name of the vector (and associated attribute file) as well as the primary key within the table. The primary key (--pkey flag) is the field within the table that is being appended to that serves as the unique identifier. Additionally, the user must specify the name of a CSV text file with either a *.csv or *.txt extension. The file must possess a header row, i.e. the first row must contain information about the names of the various fields. The foreign key (--fkey flag), that is the identifying field within the CSV file that corresponds with the data contained within the primary key in the table, must also be specified. Both the primary and foreign keys should either be strings (text) or integer values. Fields containing decimal values are not good candidates for keys. Lastly, the user may optionally specify the name of a field within the CSV file to import in the merge operation (--import_field flag). If this flag is not specified, all of the fields within the CSV, with the exception of the foreign key, will be appended to the attribute table.

Merging works for one-to-one and many-to-one database relations. A one-to-one relations exists when each record in the attribute table corresponds to one record in the second table and each primary key is unique. Since each record in the attribute table is associated with a geospatial feature in the vector, an example of a one-to-one relation may be where the second file contains AREA and PERIMETER fields for each polygon feature in the vector. This is the most basic type of relation. A many-to-one relation would exist when each record in the first attribute table corresponds to one record in the second file and the primary key is NOT unique. Consider as an example a vector and attribute table associated with a world map of countries. Each country has one or more more polygon features in the shapefile, e.g. Canada has its mainland and many hundred large islands. You may want to append a table containing data about the population and area of each country. In this case, the COUNTRY columns in the attribute table and the second file serve as the primary and foreign keys respectively. While there may be many duplicate primary keys (all of those Canadian polygons) each will correspond to only one foreign key containing the population and area data. This is a many-to-one relation. The JoinTables tool does not support one-to-many nor many-to-many relations.

See Also: JoinTables, ReinitializeAttributeTable, ExportTableToCsv

Parameters:

Python function:

wbt.merge_table_with_csv(
    i, 
    pkey, 
    csv, 
    fkey, 
    import_field=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MergeTableWithCsv -v ^
--wd="/path/to/data/" -i=properties.shp --pkey=TYPE ^
--csv=land_class.csv --fkey=VALUE ^
--import_field=NEW_VALUE
>>./whitebox_tools -r=MergeTableWithCsv ^
-v --wd="/path/to/data/" -i=properties.shp --pkey=TYPE ^
--csv=land_class.csv --fkey=VALUE 

Source code on GitHub

Author: Prof. John Lindsay

Created: 11/10/2018

Last Modified: 09/03/2020

MergeVectors

Combines two or more input vectors of the same ShapeType creating a single, new output vector. Importantly, the attribute table of the output vector will contain the ubiquitous file-specific FID, the parent file name, the parent FID, and the list of attribute fields that are shared among each of the input files. For a field to be considered common between tables, it must have the same name and field_type (i.e. data type and precision).

Overlapping features will not be identified nor handled in the merging. If you have significant areas of overlap, it is advisable to use one of the vector overlay tools instead.

The difference between MergeVectors and the Append tool is that merging takes two or more files and creates one new file containing the features of all inputs, and Append places the features of a single vector into another existing (appended) vector.

This tool only operates on vector files. Use the Mosaic tool to combine raster data.

See Also: Append, Mosaic

Parameters:

Python function:

wbt.merge_vectors(
    inputs, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MergeVectors -v --wd="/path/to/data/" ^
-i='polys1.shp;polys2.shp;polys3.shp' -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/10/2018

Last Modified: 12/10/2018

ModifyNoDataValue

This tool can be used to modify the value of pixels containing the NoData value for an input raster image. This operation differs from the SetNodataValue tool, which sets the NoData value for an image in the image header without actually modifying pixel values. Also, SetNodataValue does not overwrite the input file, while the ModifyNoDataValue tool does.

See Also: SetNodataValue, ConvertNodataToZero

Parameters:

Python function:

wbt.modify_no_data_value(
    i, 
    new_value="-32768.0", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ModifyNoDataValue -v ^
--wd="/path/to/data/" --input=in.tif --new_value= -999.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/09/2019

Last Modified: 08/09/2019

MultiPartToSinglePart

This tool can be used to convert a vector file containing multi-part features into a vector containing only single-part features. Any multi-part polygons or lines within the input vector file will be split into seperate features in the output file, each possessing their own entry in the associated attribute file. For polygon-type vectors, the user may optionally choose to exclude hole-parts from being separated from their containing polygons. That is, with the --exclude_holes flag, hole parts in the input vector will continue to belong to their enclosing polygon in the output vector. The tool will also convert MultiPoint Shapefiles into single Point vectors.

See Also: SinglePartToMultiPart

Parameters:

Python function:

wbt.multi_part_to_single_part(
    i, 
    output, 
    exclude_holes=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MultiPartToSinglePart -v ^
--wd="/path/to/data/" -i=input.shp -o=output.shp ^
--exclude_holes 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/09/2018

Last Modified: 16/06/2020

NewRasterFromBase

This tool can be used to create a new raster with the same coordinates and dimensions (i.e. rows and columns) as an existing base image. The user must specify the name of the base image (--base), the value that the new grid will be filled with (--value flag; default of NoData), and the data type (--data_type flag; options include 'double', 'float', and 'integer'). Notice that the functionality of this tool is the same as multiplying the base image by zero and adding the constant value.

See Also: RasterCellAssignment

Parameters:

Python function:

wbt.new_raster_from_base(
    base, 
    output, 
    value="nodata", 
    data_type="float", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NewRasterFromBase -v ^
--wd="/path/to/data/" --base=base.tif -o=NewRaster.tif ^
--value=0.0 --data_type=integer
>>./whitebox_tools ^
-r=NewRasterFromBase -v --wd="/path/to/data/" --base=base.tif ^
-o=NewRaster.tif --value=nodata 

Source code on GitHub

Author: Dr. John Lindsay

Created: July 11, 2017

Last Modified: 12/10/2018

PolygonsToLines

This tool converts vector polygons into polylines, simply by modifying the Shapefile geometry type.

See Also: LinesToPolygons

Parameters:

Python function:

wbt.polygons_to_lines(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PolygonsToLines -v ^
--wd="/path/to/data/" -i=input.shp -o=output.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/09/2018

Last Modified: 12/10/2018

PrintGeoTiffTags

This tool can be used to view the tags contained within a GeoTiff file. Viewing the tags of a GeoTiff file can be useful when trying to import the GeoTiff to different software environments. The user must specify the name of a GeoTiff file and the tag information will be output to the StdOut output stream (e.g. console). Note that tags that contain greater than 100 values will be truncated in the output. GeoKeys will also be interpreted as per the GeoTIFF specification.

Parameters:

Python function:

wbt.print_geo_tiff_tags(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PrintGeoTiffTags -v ^
--wd="/path/to/data/" --input=DEM.tiff 

Source code on GitHub

Author: Dr. John Lindsay

Created: March 2, 2018

Last Modified: March 2, 2018

RasterToVectorLines

This tool converts raster lines features into a vector of the POLYLINE ShapeType. Grid cells associated with line features will contain non-zero, non-NoData cell values. The algorithm requires three passes of the raster. The first pass counts the number of line neighbours of each line cell; the second pass traces line segments starting from line ends (i.e. line cells with only one neighbouring line cell); lastly, the final pass traces any remaining line segments, which are likely forming closed loops (and therefore do not have line ends).

If the line raster contains streams, it is preferable to use the RasterStreamsToVector instead. This tool will use knowledge of flow directions to ensure connections between stream segments at confluence sites, whereas RasterToVectorLines will not.

See Also: RasterToVectorPolygons, RasterToVectorPoints, RasterStreamsToVector

Parameters:

Python function:

wbt.raster_to_vector_lines(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterToVectorLines -v ^
--wd="/path/to/data/" -i=lines.tif -o=lines.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/10/2018

Last Modified: 12/10/2018

RasterToVectorPoints

Converts a raster data set to a vector of the POINT shapetype. The user must specify the name of a raster file (--input) and the name of the output vector (--output). Points will correspond with grid cell centre points. All grid cells containing non-zero, non-NoData values will be considered a point. The vector's attribute table will contain a field called 'VALUE' that will contain the cell value for each point feature.

See Also: RasterToVectorPolygons, RasterToVectorLines

Parameters:

Python function:

wbt.raster_to_vector_points(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterToVectorPoints -v ^
--wd="/path/to/data/" --input=points.tif -o=out.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/09/2018

Last Modified: 12/10/2018

RasterToVectorPolygons

Converts a raster data set to a vector of the POLYGON geometry type. The user must specify the name of a raster file (--input) and the name of the output (--output) vector. All grid cells containing non-zero, non-NoData values will be considered part of a polygon feature. The vector's attribute table will contain a field called 'VALUE' that will contain the cell value for each polygon feature, in addition to the standard feature ID (FID) attribute.

See Also: RasterToVectorPoints, RasterToVectorLines

Parameters:

Python function:

wbt.raster_to_vector_polygons(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterToVectorPolygons -v ^
--wd="/path/to/data/" --input=points.tif -o=out.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/02/2020

Last Modified: 05/03/2020

ReinitializeAttributeTable

Reinitializes a vector's attribute table deleting all fields but the feature ID (FID). Caution: this tool overwrites the input file's attribute table.

Parameters:

Python function:

wbt.reinitialize_attribute_table(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ReinitializeAttributeTable -v ^
--wd="/path/to/data/" -i=input.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/09/2018

Last Modified: 12/10/2018

RemovePolygonHoles

This tool can be used to remove holes from the features within a vector polygon file. The user must specify the name of the input vector file, which must be of a polygon shapetype, and the name of the output file.

Parameters:

Python function:

wbt.remove_polygon_holes(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RemovePolygonHoles -v ^
--wd="/path/to/data/" --input=polygons.shp ^
--output=no_holes.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/09/2018

Last Modified: 12/10/2018

SetNodataValue

This tool will re-assign a user-defined background value in an input raster image the NoData value. More precisely, the NoData value will be changed to the specified background value and any existing grid cells containing the previous NoData value, if it had been defined, will be changed to this new value. Most WhiteboxTools tools recognize NoData grid cells and treat them specially. NoData grid cells are also often displayed transparently by GIS software. The user must specify the names of the input and output rasters and the background value. The default background value is zero, although any numeric value is possible.

This tool differs from the ModifyNoDataValue tool in that it simply updates the NoData value in the raster header, without modifying pixel values. The ModifyNoDataValue tool will update the value in the header, and then modify each existing NoData pixel to contain this new value. Also, SetNodataValue does not overwrite the input file, while the ModifyNoDataValue tool does.

See Also: ModifyNoDataValue, ConvertNodataToZero, IsNoData

Parameters:

Python function:

wbt.set_nodata_value(
    i, 
    output, 
    back_value=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SetNodataValue -v --wd="/path/to/data/" ^
-i=in.tif -o=newRaster.tif --back_value=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/09/2017

Last Modified: 24/01/2019

SinglePartToMultiPart

This tool can be used to convert a vector file containing single-part features into a vector containing multi-part features. The user has the option to either group features based on an ID Field (--field flag), which is a categorical field within the vector's attribute table. The ID Field should either be of String (text) or Integer type. Fields containing decimal values are not good candidates for the ID Field. If no --field flag is specified, all features will be grouped together into one large multi-part vector.

This tool works for vectors containing either point, line, or polygon features. Since vectors of a POINT ShapeType cannot represent multi-part features, the ShapeType of the output file will be modified to a MULTIPOINT ShapeType if the input file is of a POINT ShapeType. If the input vector is of a POLYGON ShapeType, the user can optionally set the algorithm to search for polygons that should be represented as hole parts. In the case of grouping based on an ID Field, hole parts are polygon features contained within larger polygons of the same ID Field value. Please note that searching for polygon holes may significantly increase processing time for larger polygon coverages.

See Also: MultiPartToSinglePart

Parameters:

Python function:

wbt.single_part_to_multi_part(
    i, 
    output, 
    field=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SinglePartToMultiPart -v ^
--wd="/path/to/data/" -i=input.shp -o=output.shp ^
--field='COUNTRY' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/09/2018

Last Modified: 12/10/2018

VectorLinesToRaster

This tool can be used to convert a vector lines or polygon file into a raster grid of lines. If a vector of one of the polygon ShapeTypes is selected, the resulting raster will outline the polygons without filling these features. Use the VectorPolygonToRaster tool if you need to fill the polygon features.

The user must specify the name of the input vector (--input) and the output raster file (--output). The Field Name (--field) is the field from the attributes table, from which the tool will retrieve the information to assign to grid cells in the output raster. Note that if this field contains numerical data with no decimals, the output raster data type will be INTEGER; if it contains decimals it will be of a FLOAT data type. The field must contain numerical data. If the user does not supply a Field Name parameter, each feature in the raster will be assigned the record number of the feature. The assignment operation determines how the situation of multiple points contained within the same grid cell is handled. The background value is the value that is assigned to grid cells in the output raster that do not correspond to the location of any points in the input vector. This value can be any numerical value (e.g. 0) or the string 'NoData', which is the default.

If the user optionally specifies the --cell_size parameter then the coordinates will be determined by the input vector (i.e. the bounding box) and the specified Cell Size. This will also determine the number of rows and columns in the output raster. If the user instead specifies the optional base raster file parameter (--base), the output raster's coordinates (i.e. north, south, east, west) and row and column count will be the same as the base file. If the user does not specify either of these two optional parameters, the tool will determine the cell size automatically as the maximum of the north-south extent (determined from the shapefile's bounding box) or the east-west extent divided by 500.

See Also: VectorPointsToRaster, VectorPolygonsToRaster

Parameters:

Python function:

wbt.vector_lines_to_raster(
    i, 
    output, 
    field="FID", 
    nodata=True, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=VectorLinesToRaster -v ^
--wd="/path/to/data/" -i=lines.shp --field=ELEV -o=output.tif ^
--nodata --cell_size=10.0
        >>./whitebox_tools ^
-r=VectorLinesToRaster -v --wd="/path/to/data/" -i=lines.shp ^
--field=FID -o=output.tif --base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/04/2018

Last Modified: 22/10/2019

VectorPointsToRaster

This tool can be used to convert a vector points file into a raster grid. The user must specify the name of the input vector and the output raster file. The field name (--field) is the field from the attributes table from which the tool will retrieve the information to assign to grid cells in the output raster. The field must contain numerical data. If the user does not supply a field name parameter, each feature in the raster will be assigned the record number of the feature. The assignment operation determines how the situation of multiple points contained within the same grid cell is handled. The background value is zero by default but can be set to NoData optionally using the --nodata value.

If the user optionally specifies the grid cell size parameter (--cell_size) then the coordinates will be determined by the input vector (i.e. the bounding box) and the specified cell size. This will also determine the number of rows and columns in the output raster. If the user instead specifies the optional base raster file parameter (--base), the output raster's coordinates (i.e. north, south, east, west) and row and column count will be the same as the base file.

In the case that multiple points are contained within a single grid cell, the output can be assigned (--assign) the first, last (default), min, max, or sum of the contained points.

See Also: VectorPolygonsToRaster, VectorLinesToRaster

Parameters:

Python function:

wbt.vector_points_to_raster(
    i, 
    output, 
    field="FID", 
    assign="last", 
    nodata=True, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=VectorPointsToRaster -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--assign=min --nodata ^
--cell_size=10.0
        >>./whitebox_tools ^
-r=VectorPointsToRaster -v --wd="/path/to/data/" -i=points.shp ^
--field=FID -o=output.tif --assign=last ^
--base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/04/2018

Last Modified: 18/10/2019

VectorPolygonsToRaster

Converts a vector containing polygons into a raster.

Parameters:

Python function:

wbt.vector_polygons_to_raster(
    i, 
    output, 
    field="FID", 
    nodata=True, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=VectorPolygonsToRaster -v ^
--wd="/path/to/data/" -i=lakes.shp --field=ELEV -o=output.tif ^
--nodata --cell_size=10.0
        >>./whitebox_tools ^
-r=VectorPolygonsToRaster -v --wd="/path/to/data/" ^
-i=lakes.shp --field=ELEV -o=output.tif ^
--base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 17/04/2018

Last Modified: 18/10/2019

Geomorphometric Analysis

• Aspect
• AssessRoute
• AverageNormalVectorAngularDeviation
• CircularVarianceOfAspect
• ContoursFromPoints
• ContoursFromRaster
• DevFromMeanElev
• DiffFromMeanElev
• DirectionalRelief
• DownslopeIndex
• EdgeDensity
• ElevAbovePit
• ElevPercentile
• ElevRelativeToMinMax
• ElevRelativeToWatershedMinMax
• EmbankmentMapping
• FeaturePreservingSmoothing
• FetchAnalysis
• FillMissingData
• FindRidges
• Hillshade
• HorizonAngle
• HypsometricAnalysis
• HypsometricallyTintedHillshade
• MapOffTerrainObjects
• MaxAnisotropyDev
• MaxAnisotropyDevSignature
• MaxBranchLength
• MaxDifferenceFromMean
• MaxDownslopeElevChange
• MaxElevDevSignature
• MaxElevationDeviation
• MinDownslopeElevChange
• MultidirectionalHillshade
• MultiscaleElevationPercentile
• MultiscaleRoughness
• MultiscaleRoughnessSignature
• MultiscaleStdDevNormals
• MultiscaleStdDevNormalsSignature
• MultiscaleTopographicPositionImage
• NumDownslopeNeighbours
• NumUpslopeNeighbours
• Openness
• PennockLandformClass
• PercentElevRange
• PlanCurvature
• Profile
• ProfileCurvature
• RelativeAspect
• RelativeTopographicPosition
• RemoveOffTerrainObjects
• RuggednessIndex
• SedimentTransportIndex
• ShadowAnimation
• Slope
• SlopeVsElevationPlot
• SmoothVegetationResidual
• SphericalStdDevOfNormals
• StandardDeviationOfSlope
• StreamPowerIndex
• SurfaceAreaRatio
• TangentialCurvature
• TimeInDaylight
• TopographicPositionAnimation
• TotalCurvature
• Viewshed
• VisibilityIndex
• WetnessIndex

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. 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 tool uses Horn's (1981) 3rd-order finite difference method to estimate slope. Given the following clock-type grid cell numbering scheme (Gallant and Wilson, 2000),

| 7 | 8 | 1 |
| 6 | 9 | 2 |
| 5 | 4 | 3 |

aspect = 180 - arctan(f_y / f_x) + 90(f_x / |f_x|)

where,

f_x = (z₃ - z₅ + 2(z₂ - z₆) + z₁ - z₇) / 8 * Δx

and,

f_y = (z₇ - z₅ + 2(z₈ - z₄) + z₁ - z₃) / 8 * Δy

Δx and Δy are the grid resolutions in the x and y direction respectively

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: Slope, PlanCurvature, ProfileCurvature

Parameters:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 01/03/2021

AssessRoute

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

This tool 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:

See Also: SplitVectorLines, Openness

Parameters:

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

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/01/2019

Last Modified: 03/09/2020

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/04/2020

Last Modified: 26/04/2020

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/02/2020

Last Modified: 04/03/2020

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 30/01/2020

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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 (z₀) as the percentile of the elevation distribution within the filter window, such that:

EP = count_i∈C(z_i > z₀) x (100 / n_C)

where z₀ is the elevation of the window's center grid cell, z_i is the elevation of cell i contained within the neighboring set C, and n_C 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 --filteryflags. 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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay and Nigel Van Nieuwenhuizen

Created: 21/09/2020

Last Modified: 05/10/2020

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:

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:

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 

Source code on GitHub

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:

Z_test >= Z_core + DI

where Z_core is the elevation of the grid cell at which fetch is being determined, Z_test 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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/12/2017

Last Modified: 18/10/2019

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)²]^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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 07/07/2017

Last Modified: 03/09/2020

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/07/2020

Last Modified: 03/09/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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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: MinDownslopeElevChange, NumDownslopeNeighbours

Parameters:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: July 20, 2017

Last Modified: 12/10/2018

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

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)²]^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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/07/2020

Last Modified: 03/09/2020

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 (z₀) as the percentile of the elevation distribution within the filter window, such that:

EP = count_i∈C(z_i > z₀) x (100 / n_C)

where z₀ is the elevation of the window's center grid cell, z_i is the elevation of cell i contained within the neighboring set C, and n_C 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:

r_i = r_L + [step × (i - r_L)]^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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/12/2019

Last Modified: 22/12/2019

MultiscaleRoughness

Calculates surface roughness over a range of spatial scales.

Parameters:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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 (r_max; --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=r_L...r_U},

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:

r_i = r_L + [step × (i - r_L)]^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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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 DEV_max rasters of differing spatial scale ranges. Specifically, MultiscaleTopographicPositionImage takes three DEV_max 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 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:

Python function:

wbt.multiscale_topographic_position_image(
    local, 
    meso, 
    broad, 
    output, 
    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 

Source code on GitHub

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 12/10/2018

Openness

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

This tool 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:

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:

The definition of each of the elements, based on the original Pennock et al. (1987) paper, is as follows:

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:

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 

Source code on GitHub

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 (z₀) as the percentage of the elevation range within the neighbourhood filter window, such that:

PER = z₀ / (z_max - z_min) x 100

where z₀ is the elevation of the window's center grid cell, z_max is the maximum neighbouring elevation, and z_min is the minimum neighbouring elevation.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filteryflags. 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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 30/01/2020

PlanCurvature

This tool calculates the plan curvature (i.e. contour curvature), or the rate of change in aspect along a contour line, from a digital elevation model (DEM). Curvature is the second derivative of the topographic surface defined by a DEM. Plan curvature characterizes the degree of flow convergence or divergence within the landscape (Gallant and Wilson, 2000). The user must specify the name of the input DEM (--dem) and the output raster image. WhiteboxTools reports curvature in degrees multiplied by 100 for easier interpretation. 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. 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 algorithm uses the same formula for the calculation of plan curvature as Gallant and Wilson (2000). Plan curvature is negative for diverging flow along ridges and positive for convergent areas, e.g. along valley bottoms.

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: ProfileCurvature, TangentialCurvature, TotalCurvature, Slope, Aspect

Parameters:

Python function:

wbt.plan_curvature(
    dem, 
    output, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/06/2017

Last Modified: 01/03/2021

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/02/2018

Last Modified: 12/10/2018

ProfileCurvature

This tool calculates the profile curvature, or the rate of change in slope along a flow line, from a digital elevation model (DEM). Curvature is the second derivative of the topographic surface defined by a DEM. Profile curvature characterizes the degree of downslope acceleration or deceleration within the landscape (Gallant and Wilson, 2000). The user must specify the name of the input DEM (--dem) and the output raster image. WhiteboxTools reports curvature in degrees multiplied by 100 for easier interpretation because curvature values are typically very small. 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. 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 algorithm uses the same formula for the calculation of plan curvature as Gallant and Wilson (2000). Profile curvature is negative for slope increasing downhill (convex flow profile, typical of upper slopes) and positive for slope decreasing downhill (concave, typical of lower slopes).

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: ProfileCurvature, TangentialCurvature, TotalCurvature, Slope, Aspect

Parameters:

Python function:

wbt.profile_curvature(
    dem, 
    output, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/062017

Last Modified: 01/03/2021

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:

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 

Source code on GitHub

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 (z_min), mean (μ), and maximum values (z_max), within a local neighbourhood of a user-specified size (--filterx, --filtery), such that:

RTP = (z₀ − μ) / (μ − z_min), if z₀ < μ

OR

RTP = (z₀ − μ) / (z_max - μ), if z₀ >= μ

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/06/2017

Last Modified: 07/08/2020

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 ouput 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:

Python function:

wbt.ruggedness_index(
    dem, 
    output, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

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 (A_s, 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)(A_s / 22.13)ⁿ(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 A_s must not be log-transformed prior to being used; A_s is commonly log-transformed to enhance visualization of the data. Also, A_s 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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/07/2017

Last Modified: 30/01/2020

ShadowAnimation

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

This tool 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 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.

See Also: TimeInDaylight, HorizonAngle

Parameters:

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

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. 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 tool uses Horn's (1981) 3rd-order finite difference method to estimate slope. Given the following clock-type grid cell numbering scheme (Gallant and Wilson, 2000),

| 7 | 8 | 1 |
| 6 | 9 | 2 |
| 5 | 4 | 3 |

slope = arctan(f_x² + f_y²)^0.5

where,

f_x = (z₃ - z₅ + 2(z₂ - z₆) + z₁ - z₇) / 8 * Δx

and,

f_y = (z₇ - z₅ + 2(z₈ - z₄) + z₁ - z₃) / * Δy

Δx and Δy are the grid resolutions in the x and y direction respectively

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: Aspect, PlanCurvature, ProfileCurvature

Parameters:

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" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 01/03/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

Parameters:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/02/2018

Last Modified: 03/09/2020

SmoothVegetationResidual

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

This tool 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:

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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

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 (A_s; --sca). The index is calculated as:

RSP = A_s^p × tan(β)

where A_s 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 A_s must not be log-transformed prior to being used; A_s 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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 23/01/2019

Last Modified: 23/01/2019

TangentialCurvature

This tool calculates the tangential curvature, which is the curvature of an inclined plan perpendicular to both the direction of flow and the surface (Gallant and Wilson, 2000). Curvature is a second derivative of the topographic surface defined by a digital elevation model (DEM). The user must specify the name of the input DEM (--dem) and the output raster image (--output). The output reports curvature in degrees multiplied by 100 for easier interpretation, as curvature values are often very small. 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. If the DEM is in the geographic coordinate system (latitude and longitude), with XY units measured in degrees, an appropriate Z Conversion Factor is calculated internally based on site latitude.

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.

PlanCurvature, ProfileCurvature, TotalCurvature, Slope, Aspect

Parameters:

Python function:

wbt.tangential_curvature(
    dem, 
    output, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 01/03/2021

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 29/07/2020

Last Modified: 03/09/2020

TopographicPositionAnimation

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

This tool 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:

r_i = r_L + (i - r_L)^p

Where ri is the filter radius for step i, r_L 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 DEV_max (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 DEV_max 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/DEV_max 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.

See Also: DevFromMeanElev, MaxElevationDeviation

Parameters:

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: 06/05/2021

TotalCurvature

This tool calculates the total curvature, which measures the curvature of the topographic surface rather than the curvature of a line across the surface in some direction (Gallant and Wilson, 2000). 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. Curvature is a second derivative of the topographic surface defined by a digital elevation model (DEM). The user must specify the name of the input DEM (--dem) and the output raster image (--output). The output reports curvature in degrees multiplied by 100 for easier interpretation, as curvature values are often very small. 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. If the DEM is in the geographic coordinate system (latitude and longitude), with XY units measured in degrees, an appropriate Z Conversion Factor is calculated internally based on site latitude.

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.

PlanCurvature, ProfileCurvature, TangentialCurvature, Slope, Aspect

Parameters:

Python function:

wbt.total_curvature(
    dem, 
    output, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 03/09/2020

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:

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 

Source code on GitHub

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 calcuated 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:

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 

Source code on GitHub

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:

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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/07/2017

Last Modified: 21/01/2018

GIS Analysis

• AggregateRaster
• BlockMaximumGridding
• BlockMinimumGridding
• Centroid
• CentroidVector
• Clump
• ConstructVectorTin
• CreateHexagonalVectorGrid
• CreatePlane
• CreateRectangularVectorGrid
• Dissolve
• EliminateCoincidentPoints
• ExtendVectorLines
• ExtractNodes
• ExtractRasterValuesAtPoints
• FilterRasterFeaturesByArea
• FindLowestOrHighestPoints
• IdwInterpolation
• LayerFootprint
• Medoid
• MinimumBoundingBox
• MinimumBoundingCircle
• MinimumBoundingEnvelope
• MinimumConvexHull
• NaturalNeighbourInterpolation
• NearestNeighbourGridding
• PolygonArea
• PolygonLongAxis
• PolygonPerimeter
• PolygonShortAxis
• RadialBasisFunctionInterpolation
• RasterArea
• RasterCellAssignment
• RasterPerimeter
• Reclass
• ReclassEqualInterval
• ReclassFromFile
• SmoothVectors
• SplitVectorLines
• TinGridding
• VectorHexBinning
• VoronoiDiagram

AggregateRaster

This tool can be used to reduce the grid resolution of a raster by a user specified amount. For example, using an aggregation factor (--agg_factor) of 2 would result in a raster with half the number of rows and columns. The grid cell values (--type) in the output image will consist of the mean, sum, maximum, minimum, or range of the overlapping grid cells in the input raster (four cells in the case of an aggregation factor of 2).

See Also: Resample

Parameters:

Python function:

wbt.aggregate_raster(
    i, 
    output, 
    agg_factor=2, 
    type="mean", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AggregateRaster -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif ^
--output_text 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/12/2017

Last Modified: 20/01/2019

BlockMaximumGridding

Creates a raster grid based on a set of vector points and assigns grid values using a block maximum scheme.

Parameters:

Python function:

wbt.block_maximum_gridding(
    i, 
    field, 
    output, 
    use_z=False, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BlockMaximumGridding -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--cell_size=1.0
>>./whitebox_tools -r=BlockMaximumGridding -v ^
--wd="/path/to/data/" -i=points.shp --use_z -o=output.tif ^
--base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/10/2018

Last Modified: 09/12/2019

BlockMinimumGridding

Creates a raster grid based on a set of vector points and assigns grid values using a block minimum scheme.

Parameters:

Python function:

wbt.block_minimum_gridding(
    i, 
    field, 
    output, 
    use_z=False, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BlockMinimumGridding -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--cell_size=1.0
>>./whitebox_tools -r=BlockMinimumGridding -v ^
--wd="/path/to/data/" -i=points.shp --use_z -o=output.tif ^
--base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/10/2018

Last Modified: 09/12/2019

Centroid

This tool calculates the centroid, or average location, of raster polygon objects. For vector features, use the CentroidVector tool instead.

See Also: CentroidVector

Parameters:

Python function:

wbt.centroid(
    i, 
    output, 
    text_output=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Centroid -v --wd="/path/to/data/" ^
-i=polygons.tif -o=output.tif
>>./whitebox_tools -r=Centroid ^
-v --wd="/path/to/data/" -i=polygons.tif -o=output.tif ^
--text_output 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/07/2017

Last Modified: 18/10/2019

CentroidVector

This can be used to identify the centroid point of a vector polyline or polygon feature or a group of vector points. The output is a vector shapefile of points. For multi-part polyline or polygon features, the user can optionally specify whether to identify the centroid of each part. The default is to treat multi-part features a single entity.

For raster features, use the Centroid tool instead.

See Also: Centroid, Medoid

Parameters:

Python function:

wbt.centroid_vector(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CentroidVector -v --wd="/path/to/data/" ^
-i=in_file.shp -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 20/09/2018

Last Modified: 24/07/2020

Clump

This tool re-categorizes data in a raster image by grouping cells that form discrete, contiguous areas into unique categories. Essentially this will produce a patch map from an input categorical raster, assigning each feature unique identifiers. The input raster should either be Boolean (1's and 0's) or categorical. The input raster could be created using the Reclass tool or one of the comparison operators (GreaterThan, LessThan, EqualTo, NotEqualTo). Use the treat zeros as background cells options (--zero_back) if you would like to only assigned contiguous groups of non-zero values in the raster unique identifiers. Additionally, inter-cell connectivity can optionally include diagonally neighbouring cells if the --diag flag is specified.

See Also: Reclass, GreaterThan, LessThan, EqualTo, NotEqualTo

Parameters:

Python function:

wbt.clump(
    i, 
    output, 
    diag=True, 
    zero_back=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Clump -v --wd="/path/to/data/" ^
-i=input.tif -o=output.tif --diag 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 18/10/2019

ConstructVectorTin

This tool creates a vector triangular irregular network (TIN) for a set of vector points (--input) using a 2D Delaunay triangulation algorithm. TIN vertex heights can be assigned based on either a field in the vector's attribute table (--field), or alternatively, if the vector is of a z-dimension ShapeTypeDimension, the point z-values may be used for vertex heights (--use_z). For LiDAR points, use the LidarConstructVectorTIN tool instead.

Triangulation often creates very long, narrow triangles near the edges of the data coverage, particularly in convex regions along the data boundary. To avoid these spurious triangles, the user may optionally specify the maximum allowable edge length of a triangular facet (--max_triangle_edge_length).

See Also: LidarConstructVectorTIN

Parameters:

Python function:

wbt.construct_vector_tin(
    i, 
    output, 
    field=None, 
    use_z=False, 
    max_triangle_edge_length=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ConstructVectorTIN -v ^
--wd="/path/to/data/" -i=points.shp --field=HEIGHT ^
-o=tin.shp
>>./whitebox_tools -r=ConstructVectorTIN -v ^
--wd="/path/to/data/" -i=points.shp --use_z -o=tin.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/09/2018

Last Modified: 07/12/2019

CreateHexagonalVectorGrid

This tool can be used to create a hexagonal vector grid. The extent of the hexagonal grid is based on the extent of a user-specified base file (any supported raster format, shapefiles, or LAS files). The user must also specify the hexagonal cell width (--width) and whether the hexagonal orientation (--orientation) is horizontal or vertical.

See Also: CreateRectangularVectorGrid

Parameters:

Python function:

wbt.create_hexagonal_vector_grid(
    i, 
    output, 
    width, 
    orientation="horizontal", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CreateHexagonalVectorGrid -v ^
--wd="/path/to/data/" -i=file.shp -o=outfile.shp --width=10.0 ^
--orientation=vertical 

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/09/2018

Last Modified: 19/05/2020

CreatePlane

This tool can be used to create a new raster with values that are determined by the equation of a simple plane. The user must specify the name of a base raster (--base) from which the output raster coordinate and dimensional information will be taken. In addition the user must specify the values of the planar slope gradient (S; --gradient; --aspect) in degrees, the planar slope direction or aspect (A; 0 to 360 degrees), and an constant value (k; --constant). The equation of the plane is as follows:

Z = tan(S) × sin(A - 180) × X + tan(S) × cos(A - 180) × Y + k

where X and Y are the X and Y coordinates of each grid cell in the grid. Notice that A is the direction, or azimuth, that the plane is facing

Parameters:

Python function:

wbt.create_plane(
    base, 
    output, 
    gradient=15.0, 
    aspect=90.0, 
    constant=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CreatePlane -v --wd="/path/to/data/" ^
--base=base.tif -o=NewRaster.tif --gradient=15.0 ^
--aspect=315.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 30/01/2020

CreateRectangularVectorGrid

This tool can be used to create a rectangular vector grid. The extent of the rectangular grid is based on the extent of a user-specified base file (any supported raster format, shapefiles, or LAS files). The user must also specify the origin of the grid (--xorig and --yorig) and the grid cell width and height (--width and --height).

See Also: CreateHexagonalVectorGrid

Parameters:

Python function:

wbt.create_rectangular_vector_grid(
    i, 
    output, 
    width, 
    height, 
    xorig=0, 
    yorig=0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CreateRectangularVectorGrid -v ^
--wd="/path/to/data/" -i=file.shp -o=outfile.shp --width=10.0 ^
--height=10.0 --xorig=0.0 --yorig=0.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/09/2018

Last Modified: 19/05/2020

Dissolve

This tool can be used to remove the interior, or shared, boundaries within a vector polygon coverage. You can either dissolve all interior boundaries or dissolve those boundaries along polygons with the same value of a user-specified attribute within the vector's attribute table. It may be desirable to use the VectorCleaning tool to correct any topological errors resulting from the slight misalignment of nodes along shared boundaries in the vector coverage before performing the Dissolve operation.

See Also: Clip, Erase, Polygonize

Parameters:

Python function:

wbt.dissolve(
    i, 
    output, 
    field=None, 
    snap=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Dissolve -v --wd="/path/to/data/" ^
-input=layer1.shp --field=SIZE -o=out_file.shp ^
--snap=0.0000001 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/11/2018

Last Modified: 22/11/2018

EliminateCoincidentPoints

This tool can be used to remove any coincident, or nearly coincident, points from a vector points file. The user must specify the name of the input file, which must be of a POINTS ShapeType, the output file name, and the tolerance distance. All points that are within the specified tolerance distance will be eliminated from the output file. A tolerance distance of 0.0 indicates that points must be exactly coincident to be removed.

See Also: LidarRemoveDuplicates

Parameters:

Python function:

wbt.eliminate_coincident_points(
    i, 
    output, 
    tolerance, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=EliminateCoincidentPoints -v ^
--wd="/path/to/data/" -i=input_file.shp -o=out_file.shp ^
--tolerance=0.01 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/09/2018

Last Modified: 13/10/2018

ExtendVectorLines

This tool can be used to extend vector lines by a specified distance. The user must input the names of the input and output shapefiles, the distance to extend features by, and whether to extend both ends, line starts, or line ends. The input shapefile must be of a POLYLINE base shape type and should be in a projected coordinate system.

Parameters:

Python function:

wbt.extend_vector_lines(
    i, 
    output, 
    dist, 
    extend="both ends", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ExtendVectorLines -v ^
--wd="/path/to/data/" -i=in_file.shp -o=out_file.shp ^
--dist=10.0 --extend='both ends' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 20/09/2018

Last Modified: 13/10/2018

ExtractNodes

This tool converts vector lines or polygons into vertex points. The user must specify the name of the input vector, which must be of a polyline or polygon base shape type, and the name of the output point-type vector.

Parameters:

Python function:

wbt.extract_nodes(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ExtractNodes -v --wd="/path/to/data/" ^
-i=file.shp -o=outfile.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/09/2018

Last Modified: 13/10/2018

ExtractRasterValuesAtPoints

This tool can be used to extract the values of one or more rasters (--inputs) at the sites of a set of vector points. By default, the data is output to the attribute table of the input points (--points) vector; however, if the --out_text parameter is specified, the tool will additionally output point values as text data to standard output (stdout). Attribute fields will be added to the table of the points file, with field names, VALUE1, VALUE2, VALUE3, etc. each corresponding to the order of input rasters.

If you need to plot a chart of values from a raster stack at a set of points, the ImageStackProfile may be more suitable for this application.

See Also: ImageStackProfile, FindLowestOrHighestPoints

Parameters:

Python function:

wbt.extract_raster_values_at_points(
    inputs, 
    points, 
    out_text=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ExtractRasterValuesAtPoints -v ^
--wd="/path/to/data/" -i='image1.tif;image2.tif;image3.tif' ^
-points=points.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 17/06/2018

Last Modified: 18/10/2019

FilterRasterFeaturesByArea

This tool takes an input raster (--input) containing integer-labelled features, such as the output of the Clump tool, and removes all features that are smaller than a user-specified size (--threshold), measured in grid cells. The user must specify the replacement value for removed features using the --background parameter, which can be either zero or nodata.

See Also: Clump

Parameters:

Python function:

wbt.filter_raster_features_by_area(
    i, 
    output, 
    threshold, 
    background="zero", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FilterRasterFeaturesByArea -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif ^
--background=zero 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 18/10/2019

FindLowestOrHighestPoints

This tool locates the lowest and/or highest cells in a raster and outputs these locations to a vector points file. The user must specify the name of the input raster (--input) and the name of the output vector file (--output). The user also has the option (--out_type) to locate either the lowest value, highest value, or both values. The output vector's attribute table will contain fields for the points XY coordinates and their values.

See Also: ExtractRasterValuesAtPoints

Parameters:

Python function:

wbt.find_lowest_or_highest_points(
    i, 
    output, 
    out_type="lowest", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FindLowestOrHighestPoints -v ^
--wd="/path/to/data/" --input=DEM.tif -o=out.shp ^
--out_type=highest 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/06/2018

Last Modified: 13/10/2018

IdwInterpolation

points or a fixed neighbourhood size. This tool is currently configured to perform the later only, using a FixedRadiusSearch structure. Using a fixed number of neighbours will require use of a KD-tree structure. I've been testing one Rust KD-tree library but its performance does not appear to be satisfactory compared to the FixedRadiusSearch. I will need to explore other options here.

Another change that will need to be implemented is the use of a nodal function. The original Whitebox GAT tool allows for use of a constant or a quadratic. This tool only allows the former. This tool interpolates vector points into a raster surface using an inverse-distance weighted scheme.

Parameters:

Python function:

wbt.idw_interpolation(
    i, 
    field, 
    output, 
    use_z=False, 
    weight=2.0, 
    radius=None, 
    min_points=None, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=IdwInterpolation -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--weight=2.0 --radius=4.0 --min_points=3 ^
--cell_size=1.0
>>./whitebox_tools -r=IdwInterpolation -v ^
--wd="/path/to/data/" -i=points.shp --use_z -o=output.tif ^
--weight=2.0 --radius=4.0 --min_points=3 ^
--base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/05/2018

Last Modified: 9/12/2019

LayerFootprint

This tool creates a vector polygon footprint of the area covered by a raster grid or vector layer. It will create a vector rectangle corresponding to the bounding box. The user must specify the name of the input file, which may be either a Whitebox raster or a vector, and the name of the output file.

If an input raster grid is specified which has an irregular shape, i.e. it contains NoData values at the edges, the resulting vector will still correspond to the full grid extent, ignoring the irregular boundary. If this is not the desired effect, you should reclass the grid such that all cells containing valid values are assigned some positive, non-zero value, and then use the RasterToVectorPolygons tool to vectorize the irregular-shaped extent boundary.

See Also: MinimumBoundingEnvelope, RasterToVectorPolygons

Parameters:

Python function:

wbt.layer_footprint(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LayerFootprint -v --wd="/path/to/data/" ^
-i=file.shp -o=outfile.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 31/09/2018

Last Modified: 13/10/2018

Medoid

This tool calculates the medoid for a series of vector features contained in a shapefile. The medoid of a two-dimensional feature is conceptually similar its centroid, or mean position, but the medoid is always a members of the input feature data set. Thus, the medoid is a measure of central tendency that is robust in the presence of outliers. If the input vector is of a POLYLINE or POLYGON ShapeType, the nodes of each feature will be used to estimate the feature medoid. If the input vector is of a POINT base ShapeType, the medoid will be calculated for the collection of points. While there are more than one competing method of calculating the medoid, this tool uses an algorithm that works as follows:

1. The x-coordinate and y-coordinate of each point/node are placed into two arrays.
2. The x- and y-coordinate arrays are then sorted and the median x-coordinate (Med X) and median y-coordinate (Med Y) are calculated.
3. The point/node in the dataset that is nearest the point (Med X, Med Y) is identified as the medoid.

See Also: CentroidVector

Parameters:

Python function:

wbt.medoid(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Medoid -v --wd="/path/to/data/" ^
-i=in_file.shp -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 20/09/2018

Last Modified: 24/07/2020

MinimumBoundingBox

This tool delineates the minimum bounding box (MBB) for a group of vectors. The MBB is the smallest box to completely enclose a feature. The algorithm works by rotating the feature, calculating the axis-aligned bounding box for each rotation, and finding the box with the smallest area, length, width, or perimeter. The MBB is needed to compute several shape indices, such as the Elongation Ratio. The MinimumBoundingEnvelop tool can be used to calculate the axis-aligned bounding rectangle around each feature in a vector file.

See Also: MinimumBoundingCircle, MinimumBoundingEnvelope, MinimumConvexHull

Parameters:

Python function:

wbt.minimum_bounding_box(
    i, 
    output, 
    criterion="area", 
    features=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MinimumBoundingBox -v ^
--wd="/path/to/data/" -i=file.shp -o=outfile.shp ^
--criterion=length --features 

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/09/2018

Last Modified: 18/10/2019

MinimumBoundingCircle

This tool delineates the minimum bounding circle (MBC) for a group of vectors. The MBC is the smallest enclosing circle to completely enclose a feature.

See Also: MinimumBoundingBox, MinimumBoundingEnvelope, MinimumConvexHull

Parameters:

Python function:

wbt.minimum_bounding_circle(
    i, 
    output, 
    features=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MinimumBoundingCircle -v ^
--wd="/path/to/data/" -i=file.shp -o=outfile.shp --features 

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/09/2018

Last Modified: 18/10/2019

MinimumBoundingEnvelope

This tool delineates the minimum bounding axis-aligned box for a group of vector features. The is the smallest rectangle to completely enclose a feature, in which the sides of the envelope are aligned with the x and y axis of the coordinate system. The MinimumBoundingBox can be used instead to find the smallest possible non-axis aligned rectangular envelope.

See Also: MinimumBoundingBox, MinimumBoundingCircle, MinimumConvexHull

Parameters:

Python function:

wbt.minimum_bounding_envelope(
    i, 
    output, 
    features=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MinimumBoundingEnvelope -v ^
--wd="/path/to/data/" -i=file.shp -o=outfile.shp --features 

Source code on GitHub

Author: Dr. John Lindsay

Created: 31/09/2018

Last Modified: 18/10/2019

MinimumConvexHull

This tool creates a vector convex polygon around vector features. The convex hull is a convex closure of a set of points or polygon verticies and can be may be conceptualized as the shape enclosed by a rubber band stretched around the point set. The convex hull has many applications and is most notably used in various shape indices. The Delaunay triangulation of a point set and its dual, the Voronoi diagram, are mathematically related to convex hulls.

See Also: MinimumBoundingBox, MinimumBoundingCircle, MinimumBoundingEnvelope

Parameters:

Python function:

wbt.minimum_convex_hull(
    i, 
    output, 
    features=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MinimumConvexHull -v ^
--wd="/path/to/data/" -i=file.shp -o=outfile.shp --features 

Source code on GitHub

Author: Dr. John Lindsay

Created: 03/09/2018

Last Modified: 18/10/2019

NaturalNeighbourInterpolation

This tool can be used to interpolate a set of input vector points (--input) onto a raster grid using Sibson's (1981) natural neighbour method. Similar to inverse-distance-weight interpolation (IdwInterpolation), the natural neighbour method performs a weighted averaging of nearby point values to estimate the attribute (--field) value at grid cell intersections in the output raster (--output). However, the two methods differ quite significantly in the way that neighbours are identified and in the weighting scheme. First, natural neigbhour identifies neighbours to be used in the interpolation of a point by finding the points connected to the estimated value location in a Delaunay triangulation, that is, the so-called natural neighbours. This approach has the main advantage of not having to specify an arbitrary search distance or minimum number of nearest neighbours like many other interpolators do. Weights in the natural neighbour scheme are determined using an area-stealing approach, whereby the weight assigned to a neighbour's value is determined by the proportion of its Voronoi polygon that would be lost by inserting the interpolation point into the Voronoi diagram. That is, inserting the interpolation point into the Voronoi diagram results in the creation of a new polygon and shrinking the sizes of the Voronoi polygons associated with each of the natural neighbours. The larger the area by which a neighbours polygon is reduced through the insertion, relative to the polygon of the interpolation point, the greater the weight given to the neighbour point's value in the interpolation. Interpolation weights sum to one because the sum of the reduced polygon areas must account for the entire area of the interpolation points polygon.

The user must specify the attribute field containing point values (--field). Alternatively, if the input Shapefile contains z-values, the interpolation may be based on these values (--use_z). Either an output grid resolution (--cell_size) must be specified or alternatively an existing base file (--base) can be used to determine the output raster's (--output) resolution and spatial extent. Natural neighbour interpolation generally produces a satisfactorily smooth surface within the region of data points but can produce spurious breaks in the surface outside of this region. Thus, it is recommended that the output surface be clipped to the convex hull of the input points (--clip).

Reference:

Sibson, R. (1981). "A brief description of natural neighbor interpolation (Chapter 2)". In V. Barnett (ed.). Interpolating Multivariate Data. Chichester: John Wiley. pp. 21–36.

See Also: IdwInterpolation, NearestNeighbourGridding

Parameters:

Python function:

wbt.natural_neighbour_interpolation(
    i, 
    output, 
    field=None, 
    use_z=False, 
    cell_size=None, 
    base=None, 
    clip=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NaturalNeighbourInterpolation -v ^
--wd="/path/to/data/" -i=points.shp --field=HEIGHT ^
-o=surface.tif --resolution=10.0 --clip 

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/12/2019

Last Modified: 10/12/2019

NearestNeighbourGridding

Creates a raster grid based on a set of vector points and assigns grid values using the nearest neighbour.

Parameters:

Python function:

wbt.nearest_neighbour_gridding(
    i, 
    field, 
    output, 
    use_z=False, 
    cell_size=None, 
    base=None, 
    max_dist=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NearestNeighbourGridding -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--cell_size=1.0
>>./whitebox_tools -r=NearestNeighbourGridding ^
-v --wd="/path/to/data/" -i=points.shp --use_z -o=output.tif ^
--base=existing_raster.tif --max_dist=5.5 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/10/2018

Last Modified: 09/12/2019

PolygonArea

This tool calculates the area of vector polygons, adding the result to the vector's attribute table (AREA field). The area calculation will account for any holes contained within polygons. The vector should be in a projected coordinate system.

To calculate the area of raster polygons, use the RasterArea tool instead.

See Also: RasterArea

Parameters:

Python function:

wbt.polygon_area(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PolygonArea -v --wd="/path/to/data/" ^
--input=polygons.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/09/2018

Last Modified: 13/10/2018

PolygonLongAxis

This tool can be used to map the long axis of polygon features. The long axis is the longer of the two primary axes of the minimum bounding box (MBB), i.e. the smallest box to completely enclose a feature. The long axis is drawn for each polygon in the input vector file such that it passes through the centre point of the MBB. The output file is therefore a vector of simple two-point polylines forming a vector field.

Parameters:

Python function:

wbt.polygon_long_axis(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PolygonLongAxis -v ^
--wd="/path/to/data/" -i=file.shp -o=outfile.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/09/2018

Last Modified: 03/03/2020