drawing


www.whiteboxgeo.com | support@whiteboxgeo.com

WhiteboxTools Version 2.3.0
Dr. John B. Lindsay © 2017-2023
Geomorphometry and Hydrogeomatics Research Group
University of Guelph
Guelph, Canada
March 25, 2023


Sponsored by:
drawing

drawing

drawing

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 about the platform and the software download site.

Project Highlights

  • Contains more than 480 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.
  • Powerful extension products are available to further enhance WhiteboxTools' capabilites in areas such as DEM processing, LiDAR data analysis, remote sensing, spatial hydrology, and crop yield data analysis.

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.

The WhiteboxTools Extensions extend the platform's capabilities even further.

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)1. 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.

1: 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 WhiteboxTools 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.

Information about how to install any of the WhiteboxTools extension products can be found on www.whiteboxgeo.com or by watching this YouTube video.

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

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

  2. Decompress the zipped download file.

  3. 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/
  1. 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_working_dir("/path/to/data/") # Sets the 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).

Autocompletion in Atom text editor makes calling WhiteboxTools functions easier.

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:

Folder contents of *WhiteboxTools* compressed download file

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:

Example project set-up

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.

Download the St. Elis Mountains and Gulf of Alaska sample data set (StElisAk.laz) from the WhiteboxTools section of the site and decompress the zip file. 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.laz into the folder.

St. Elis Mountains LiDAR point cloud, visualized using the plas.io software

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.laz",
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.

Output of the flow accumulation script for the St. Elis Mountains data set.

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

Whitebox Runner

There is an application file (executable) contained within the WhiteboxTools WBT directory called 'whitebox_runner'. This application is intended to provide a very basic user-interface, known as the Whitebox Runner or simply WbRunner, for running the tools contained within the WhiteboxTools library. The user-interface is cross-platform and has been compiled for Windows, Linux, and macOS.

The Whitebox Runner user-interface

To launch the runner application, you should simply need to double-click the executable file. The application has a dark-mode theme (seen above) as well as a light-mode theme (seen below). Like WhiteboxTools itself, WbRunner is developed using pure Rust code and is a native application. It is therefore very performant, especially when compared with the previous version of the Runner, which was a Python interface application.

The Whitebox Runner user-interface

Even if you typically use other Whitebox front-ends, WbRunner can be useful at times. For example, unlike many of the other front-end applications, the WbRunner is always up-to-date with your current version of the WhiteboxTools back-end. You may always access the latest tools in Whitebox using the WbRunner. It is also the preferred way to install the Whitebox Toolset Extension. Furthermore, because WbRunner is developed in-house at Whitebox Geospatial Inc., unlike many of the other Whitebox front-ends, the tools interface with the front-end exactly as they are intended to without having to compromise for limitations on front-end design. For example, tools output directly to an output window embedded in the tool's dialog. Progress bars update as the tool is running. The help button links to the appropriate tool documentation in the user manual and the cancel button works as expected (except for plugin tools, which cannot be directly cancelled).

QGIS Plugin

WhiteboxTools functionality can be accessed conveniently through the popular open-source geospatial software QGIS. Historically, the QGIS WhiteboxTools plugin was developed by Alexander Bruy.

Please note, as of February 2022, Alex Bruy, the original developer of the QGIS WhiteboxTools plugin, is no longer distributing any of his numerous QGIS open-source plugins, in protest of the war in Ukraine. As such, we are currently developing the WhiteboxTools plugin for QGIS in-house at Whitebox Geospatial Inc.

The Whitebox for QGIS plugin works QGIS v3 but cannot be installed on the earlier v2 series. The minimum QGIS version supported by the plugins is currently 3.18.0. If you are using an older version of QGIS, you will need to update before the following procedure for installation will work.

Installation of the Plugin

For detailed instructions on how to install and configure the Whitebox plugin for QGIS, please watch this short video. Note that installing the Whitebox plugin does not automatically install the open-source WhiteboxTools back-end, nor any of the commercial extension products. You will need to visit the Whitebox Geospatial homepage and download the WhiteboxTools binary executable before installing the QGIS plugin. The Whitebox Toolset Extension (WTE) can also be downloaded from the site, although a valid license is required to run the extension.

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.

The WhiteboxTools ArcGIS plugin toolbox

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:

CommandDescription
--cd, --wdChanges the working directory; used in conjunction with --run flag.
--compress_rastersSets the compress_raster option in the settings.json file; determines if newly created rasters are compressed. e.g. --compress_rasters=true
-h, --helpPrints help information.
-l, --licensePrints the whitebox-tools license.
--listtoolsLists all available tools, with tool descriptions. Keywords may also be used, --listtools slope.
--max_procsSets the maximum number of processors used. -1 = all available processors. e.g. --max_procs=2
-r, --runRuns a tool; used in conjunction with --cd flag; -r="LidarInfo".
--toolboxPrints the toolbox associated with a tool; --toolbox=Slope.
--toolhelpPrints the help associated with a tool; --toolhelp="LidarInfo".
--toolparametersPrints the parameters (in json form) for a specific tool; e.g. --toolparameters="FeaturePreservingDenoise".
-vVerbose mode. With this flag set to false, tool outputs will not be printed. -v=true, -v=false
--viewcodeOpens the source code of a tool in a web browser; --viewcode="LidarInfo".
--versionPrints the version information.

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.

WhiteboxTools Extensions

Whitebox Geospatial Inc. currently offers one extension for WhiteboxTools, known as the Whitebox Toolset Extension. This product contains plugins that extend the functionality of the open-core of WhiteboxTools. The list of the plugin tools and there descriptions is found here. While managed separately from the open-core, the extension easily integrate into your current WhiteboxTools environment. Please contact support@whiteboxgeo.com for further details, or visit www.whiteboxgeo.com for current pricing information.

If you are using the WhiteboxTools Python API, you may install any of the Whitebox Extensions with the following script:

from WBT.whitebox_tools import WhiteboxTools

wbt = WhiteboxTools()

wbt.install_wbt_extension()

After running the above script, Python will prompt you, from the command line terminal application, which extension you would like to install. Options include 'gte' (General Toolset Extension), 'lidar' (LiDAR and Remote Sensing Extension), 'dem' (DEM and Spatial Analysis Extension), and 'agri' (Agriculture Extension). Once you specify the extension you would like installed, the application will download and install the appropriate plugin tools (this requires an Internet connect), and then prompt the user whether they would like to activate a license key. This is a necessary step before you can use the newly installed plugin tools.

Extension installation

If you are using the WhiteboxTools Runner, you may instead press the 'Install Whitebox Extension' button at the bottom of the Settings panel.

Extension installation through the WhiteboxTools Runner

Tools Reference

The WhiteboxTools platform currently contains approximately 485 tools organized into thematic toolboxes and including tools both within the WhiteboxTools open-core and the various extensions. The thematic toolboxes include:

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

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:

FlagDescription
-i, --inputInput vector Points file

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:

FlagDescription
-i, --inputInput vector file
-o, --outputOutput vector file

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:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

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:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

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 retrieved.

See Also: MergeTableWithCsv, ExportTableToCsv

Parameters:

FlagDescription
-i, --inputInput CSV file (i.e. source of data to be imported)
-o, --outputOutput vector file
--xfieldX field number (e.g. 0 for first field)
--yfieldY field number (e.g. 1 for second field)
--epsgEPSG projection (e.g. 2958)

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:

FlagDescription
-i, --inputInput vector file
-o, --outputOutput csv file
--headersExport field names as file header?

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

FixDanglingArcs

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

This tool can be used to fix undershot and overshot arcs, two common topological errors, in an input vector lines file (--input). In addition to the input lines vector, the user must also specify the output vector (--output) and the snap distance (--snap). All dangling arcs that are within this threshold snap distance of another line feature will be connected to the neighbouring feature. If the input lines network is a vector stream network, users are advised to apply the RepairStreamVectorTopology tool instead.

See Also: RepairStreamVectorTopology, CleanVector

Parameters:

FlagDescription
-i, --inputName of the input lines vector file
-o, --outputName of the output lines vector file
--snap, --distSnap distance, in xy units (metres)

Python function:

wbt.fix_dangling_arcs(
    i, 
    output, 
    dist="", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=FixDanglingArcs --input=streams.shp ^
--output=streams_snapped.shp --dist=2.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 03/08/2021

Last Modified: 03/08/2021

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:

FlagDescription
--i1, --input1Input primary vector file (i.e. the table to be modified)
--pkeyPrimary key field
--i2, --input2Input foreign vector file (i.e. source of data to be imported)
--fkeyForeign key field
--import_fieldImported field (all fields will be imported if not specified)

Python function:

wbt.join_tables(
    input1, 
    pkey, 
    input2, 
    fkey, 
    import_field=None, 
    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:

FlagDescription
-i, --inputInput vector line file
-o, --outputOutput vector polygon file

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:

FlagDescription
-i, --inputInput primary vector file (i.e. the table to be modified)
--pkeyPrimary key field
--csvInput CSV file (i.e. source of data to be imported)
--fkeyForeign key field
--import_fieldImported field (all fields will be imported if not specified)

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:

FlagDescription
-i, --inputsInput vector files
-o, --outputOutput vector file

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. This tool cannot modify the input image data type, which is important to note since it may cause an unexpected behaviour if the new NoData value is negative and the input image data type is an unsigned integer type.

See Also: SetNodataValue, ConvertNodataToZero

Parameters:

FlagDescription
-i, --inputInput raster file
--new_valueNew NoData value

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

FlagDescription
-i, --inputInput vector line or polygon file
-o, --outputOutput vector line or polygon file
--exclude_holesExclude hole parts from the feature splitting? (holes will continue to belong to their features in output.)

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, or the same spatial extent as an input vector file. The user must specify the name of the base file (--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'). If an input vector base file is used, then it is necessary to specify a value for the optional grid cell size (--cell_size) input parameter.

See Also: RasterCellAssignment

Parameters:

FlagDescription
-i, --baseInput base raster file
-o, --outputOutput raster file
--valueConstant value to fill raster with; either 'nodata' or numeric value
--data_typeOutput raster data type; options include 'double' (64-bit), 'float' (32-bit), and 'integer' (signed 16-bit) (default is 'float')
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified

Python function:

wbt.new_raster_from_base(
    base, 
    output, 
    value="nodata", 
    data_type="float", 
    cell_size=None, 
    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: 11/07/2017

Last Modified: 27/08/2021

PolygonsToLines

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

See Also: LinesToPolygons

Parameters:

FlagDescription
-i, --inputInput vector polygon file
-o, --outputOutput vector lines file

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:

FlagDescription
-i, --inputInput GeoTIFF file

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:

FlagDescription
-i, --inputInput raster lines file
-o, --outputOutput raster file

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:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput vector points file

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:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput vector polygons file

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:

FlagDescription
-i, --inputInput vector file

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:

FlagDescription
-i, --inputInput vector polygon file
-o, --outputOutput vector polygon file

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

RemoveRasterPolygonHoles

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

This tool can be used to remove holes in raster polygons. Holes are areas of background values (either zero or NoData), completely surrounded by foreground values (any value other than zero or NoData). Therefore, this tool can somewhat be considered to be the raster equivalent to the vector-based RemovePolygonHoles tool. Users may optionally remove holes less than a specified threshold size (--threshold), measured in grid cells. Hole size is determined using a clumping operation, similar to what is used by the Clump tool. Users may also optionally specify whether or not to included 8-cell diagonal connectedness during the clumping operation (--use_diagonals).

Some GIS professionals have previously used a closing operation to lessen the extent of polygon holes in raster data. A closing is a mathematical morphology operation that involves expanding the raster polygons using a dialation filter (MaximumFilter), followed by a dialation filter (MinimumFilter) on the resulting image. While this common image processing technique can be helpful for reducing the prevalance of polygon holes, it can also have considerable impact on non-hole features within the image. The RemoveRasterPolygonHoles tool, by comparison, will only affect hole features and does not impact the boundaries of other polygons at all. The following image compares the removal of polygon holes (islands in a lake polygon) using a closing operation (middle) calculated using an 11x11 convolution filter and the output of the RemoveRasterPolygonHoles tool. Notice how the convolution operation impacts the edges of the polygon, particularly in convex regions, compared with the RemoveRasterPolygonHoles.

Here is a video that demonstrates how to apply this tool to a classified Sentinel-2 multi-spectral satellite imagery data set.

See Also: Closing, RemovePolygonHoles, Clump, GeneralizeClassifiedRaster

Parameters:

FlagDescription
-i, --inputName of the input raster image file
-o, --outputName of the output raster file
--thresholdMaximum size of removed holes, in grid cells. Blank for no threshold, i.e. remove all holes
--use_diagonalsUse diagonal neighbours during clumping operation

Python function:

wbt.remove_raster_polygon_holes(
    i, 
    output, 
    threshold=3, 
    use_diagonals=True, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RemoveRasterPolygonHoles -i=input.tif ^
-o=output.tif --threshold=25 --use_diagonals 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 29/10/2022

Last Modified: 29/10/2022

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.

This tool may result in a change in the data type of the output image compared with the input image, if the background value is set to a negative value and the input image data type is an unsigned integer. In some cases, this may result in a doubling of the storage size of the output image.

See Also: ModifyNoDataValue, ConvertNodataToZero, IsNoData

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--back_valueBackground value to set to nodata

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: 14/03/2023

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:

FlagDescription
-i, --inputInput vector line or polygon file
--fieldGrouping ID field name in attribute table
-o, --outputOutput vector line or polygon file

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:

FlagDescription
-i, --inputInput vector lines file
--fieldInput field name in attribute table
-o, --outputOutput raster file
--nodataBackground value to set to NoData. Without this flag, it will be set to 0.0
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified

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, sum, mean, or number of the contained points.

See Also: VectorPolygonsToRaster, VectorLinesToRaster

Parameters:

FlagDescription
-i, --inputInput vector Points file
--fieldInput field name in attribute table
-o, --outputOutput raster file
--assignAssignment operation, where multiple points are in the same grid cell; options include 'first', 'last' (default), 'min', 'max', 'sum', 'number'
--nodataBackground value to set to NoData. Without this flag, it will be set to 0.0
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified

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: 19/04/2023

VectorPolygonsToRaster

Converts a vector containing polygons into a raster.

Parameters:

FlagDescription
-i, --inputInput vector polygons file
--fieldInput field name in attribute table
-o, --outputOutput raster file
--nodataBackground value to set to NoData. Without this flag, it will be set to 0.0
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified

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

AccumulationCurvature

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

This tool calculates the accumulation curvature from a digital elevation model (DEM). Accumulation curvature is the product of profile (vertical) and tangential (horizontal) curvatures at a location (Shary, 1995). This variable has positive values, zero or greater. Florinsky (2017) states that accumulation curvature is a measure of the extent of local accumulation of flows at a given point in the topographic surface. Accumulation curvature is measured in units of m-2.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

See Also:

TangentialCurvature, ProfileCurvature, MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demName of the input raster DEM file
-o, --outputName of the output raster image file
--logDisplay output values using a log-scale
--zfactorZ conversion factor

Python function:

wbt.accumulation_curvature(
    dem, 
    output, 
    log=False, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=AccumulationCurvature -i=DEM.tif ^
-o=output.tif --log 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 11/01/2022

Last Modified: 28/11/2022

Aspect

This tool calculates slope aspect (i.e. slope orientation in degrees clockwise from north) for each grid cell in an input digital elevation model (DEM). The user must specify the name of the input DEM (--dem) and the output raster image. The Z conversion factor is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z conversion factor.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

Reference:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

See Also: Slope, TangentialCurvature, PlanCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 12/01/2022

AssessRoute

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

This tool assesses the variability in slope, elevation, and visibility along a line vector, which may be a footpath, road, river or any other route. The user must specify the name of the input line vector (--routes), the input raster digital elevation model file (--dem), and the output line vector (--output). The algorithm initially splits the input line vector in equal-length segments (--length). For each line segment, the tool then calculates the average slope (AVG_SLOPE), minimum and maximum elevations (MIN_ELEV, MAX_ELEV), the elevation range or relief (RELIEF), the path sinuosity (SINUOSITY), the number of changes in slope direction or breaks-in-slope (CHG_IN_SLP), and the maximum visibility (VISIBILITY). Each of these metrics are output to the attribute table of the output vector, along with the feature identifier (FID); any attributes associated with the input parent feature will also be copied into the output table. Slope and elevation metrics are measured along the 2D path based on the elevations of each of the row and column intersection points of the raster with the path, estimated from linear-interpolation using the two neighbouring elevations on either side of the path. Sinuosity is calculated as the ratio of the along-surface (i.e. 3D) path length, divided by the 3D distance between the start and end points of the segment. CHG_IN_SLP can be thought of as a crude measure of path roughness, although this will be very sensitive to the quality of the DEM. The visibility metric is based on the Yokoyama et al. (2002) Openness index, which calculates the average horizon angle in the eight cardal directions to a maximum search distance (--dist), measured in grid cells.

Note that the input DEM must be in a projected coordinate system. The DEM and the input routes vector must be also share the same coordinate system. This tool also works best when the input DEM is of high quality and fine spatial resolution, such as those derived from LiDAR data sets.

Maximum segment visibility:

Average segment slope:

For more information about this tool, see this blog on the WhiteboxTools homepage.

See Also: SplitVectorLines, Openness

Parameters:

FlagDescription
--routesName of the input routes vector file
--demName of the input DEM raster file
-o, --outputName of the output lines shapefile
--lengthMaximum segment length (m)
--distSearch distance, in grid cells, used in visibility analysis

Python function:

wbt.assess_route(
    routes, 
    dem, 
    output, 
    length="", 
    dist=20, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=AssessRoute --routes=footpath.shp ^
--dem=DEM.tif -o=assessedRoutes.shp --length=50.0 --dist=200 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 16/05/2021

Last Modified: 16/05/2021

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:

FlagDescription
-i, --demInput raster DEM file
--outputOutput raster file
--filterSize of the filter kernel

Python function:

wbt.average_normal_vector_angular_deviation(
    dem, 
    output, 
    filter=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AverageNormalVectorAngularDeviation -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/01/2019

Last Modified: 03/09/2020

BreaklineMapping

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

This tool can be used to map breaklines in an input digital elevation model (DEM; --input). Breaklines are locations of high surface curvature, in any direction, measured using Curvedness. Curvedness values are log-transformed using the resolution-dependent method proposed by Shary et al. (2002). Breaklines are coincident with grid cells that have log-transformed curvedness values exceeding a user-specified threshold value (--thresshold). While curvedness is measured within the range 0 to infinity, values are typically lower. Appropriate values for the threshold parameter are commonly in the 1 to 5 range. Lower threshold values will result in more extensive breakline mapping and vice versa. The algorithm will vectorize breakline features and the output of this tool (--output) is a line vector. Line features that are less than a user-specified length (in grid cells; --min_length), will not be output.

Watch the breakline mapping video for an example of how to run the tool.

References:

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

See Also:

Curvedness

Parameters:

FlagDescription
-i, --input, --demName of the input raster image file
-o, --outputName of the output vector lines file
--thresholdThreshold value (0 - infinity but typcially 1 to 5 works well)
--min_lengthMinimum line length, in grid cells

Python function:

wbt.breakline_mapping(
    dem, 
    output, 
    threshold=2.0, 
    min_length=3, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=BreaklineMapping -i=input.tif ^
-o=output.tif --threshold=0.8 --min_length=5 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 13/01/2022

Last Modified: 13/01/2022

CircularVarianceOfAspect

This tool can be used to calculate the circular variance (i.e. one minus the mean resultant length) of aspect for an input digital elevation model (DEM). This is a measure of how variable slope aspect is within a local neighbourhood of a specified size (--filter). CircularVarianceOfAspect is therefore a measure of surface shape complexity, or texture. It will take a value of 0.0 for smooth sites and near 1.0 in areas of high surface roughness or complex topography.

The local neighbourhood size (--filter) must be any odd integer equal to or greater than three. Grohmann et al. (2010) found that vector dispersion, a related measure of angular variance, increases monotonically with scale. This is the result of the angular dispersion measure integrating (accumulating) all of the surface variance of smaller scales up to the test scale. A more interesting scale relation can therefore be estimated by isolating the amount of surface complexity associated with specific scale ranges. That is, at large spatial scales, the metric should reflect the texture of large-scale landforms rather than the accumulated complexity at all smaller scales, including microtopographic roughness. As such, this tool normalizes the surface complexity of scales that are smaller than the filter size by applying Gaussian blur (with a standard deviation of one-third the filter size) to the DEM prior to calculating CircularVarianceOfAspect. In this way, the resulting distribution is able to isolate and highlight the surface shape complexity associated with landscape features of a similar scale to that of the filter size.

This tool makes extensive use of integral images (i.e. summed-area tables) and parallel processing to ensure computational efficiency. It may, however, require substantial memory resources when applied to larger DEMs.

References:

Grohmann, C. H., Smith, M. J., & Riccomini, C. (2010). Multiscale analysis of topographic surface roughness in the Midland Valley, Scotland. IEEE Transactions on Geoscience and Remote Sensing, 49(4), 1200-1213.

See Also: Aspect, SphericalStdDevOfNormals, MultiscaleRoughness, EdgeDensity, SurfaceAreaRatio, RuggednessIndex

Parameters:

FlagDescription
-i, --demInput raster DEM file
--outputOutput raster file
--filterSize of the filter kernel

Python function:

wbt.circular_variance_of_aspect(
    dem, 
    output, 
    filter=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CircularVarianceOfAspect -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5 

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:

FlagDescription
-i, --inputInput vector points file
--fieldInput field name in attribute table
--use_zUse the 'z' dimension of the Shapefile's geometry instead of an attribute field?
-o, --outputOutput vector lines file
--max_triangle_edge_lengthOptional maximum triangle edge length; triangles larger than this size will not be gridded
--intervalContour interval
--baseBase contour height
--smoothSmoothing filter size (in num. points), e.g. 3, 5, 7, 9, 11

Python function:

wbt.contours_from_points(
    i, 
    output, 
    field=None, 
    use_z=False, 
    max_triangle_edge_length=None, 
    interval=10.0, 
    base=0.0, 
    smooth=5, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ContoursFromPoints -v ^
--wd="/path/to/data/" -i=points.shp --field=HEIGHT ^
-o=contours.shp --max_triangle_edge_length=100.0 ^
--interval=100.0 --base=0.0 --smooth=11 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/04/2020

Last Modified: 24/06/2021

ContoursFromRaster

This tool can be used to create a vector contour coverage from an input raster surface model (--input), such as a digital elevation model (DEM). The user must specify the contour interval (--interval) and optionally, the base contour value (--base). The degree to which contours are smoothed is controlled by the Smoothing Filter Size parameter (--smooth). This value, which determines the size of a mean filter applied to the x-y position of vertices in each contour, should be an odd integer value, e.g. 3, 5, 7, 9, 11, etc. Larger values will result in smoother contour lines. The tolerance parameter (--tolerance) controls the amount of line generalization. That is, vertices in a contour line will be selectively removed from the line if they do not result in an angular deflection in the line's path of at least this threshold value. Increasing this value can significantly decrease the size of the output contour vector file, at the cost of generating straighter contour line segments.

See Also: RasterToVectorPolygons

Parameters:

FlagDescription
-i, --inputInput surface raster file
-o, --outputOutput vector contour file
--intervalContour interval
--baseBase contour height
--smoothSmoothing filter size (in num. points), e.g. 3, 5, 7, 9, 11
--toleranceTolerance factor, in degrees (0-45); determines generalization level

Python function:

wbt.contours_from_raster(
    i, 
    output, 
    interval=10.0, 
    base=0.0, 
    smooth=9, 
    tolerance=10.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ContoursFromRaster -v ^
--wd="/path/to/data/" --input=DEM.tif -o=contours.shp ^
--interval=100.0 --base=0.0 --smooth=11 --tolerance=20.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/02/2020

Last Modified: 04/03/2020

Curvedness

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

This tool calculates the curvedness (Koenderink and van Doorn, 1992) from a digital elevation model (DEM). Curvedness is the root mean square of maximal and minimal curvatures, and measures the magnitude of surface bending, regardless of shape (Florinsky, 2017). Curvedness is characteristically low-values for flat areas and higher for areas of sharp bending (Florinsky, 2017). The index is also inversely proportional with the size of the object (Koenderink and van Doorn, 1992). Curvedness has values equal to or greater than zero and is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Raw curvedness values are often challenging to visualize given their range and magnitude, and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Koenderink, J. J., and Van Doorn, A. J. (1992). Surface shape and curvature scales. Image and vision computing, 10(8), 557-564.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

See Also:

ShapeIndex, MinimalCurvature, MaximalCurvature, TangentialCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demName of the input raster DEM file
-o, --outputName of the output raster image file
--logDisplay output values using a log-scale
--zfactorZ conversion factor

Python function:

wbt.curvedness(
    dem, 
    output, 
    log=False, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=Curvedness -i=DEM.tif -o=output.tif ^
--log 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 13/01/2022

Last Modified: 28/11/2022

DemVoidFilling

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

This tool implements a modified version of the Delta Surface Fill method of Grohman et al. (2006). It can fill voids (i.e., data holes) contained within a digital elevation model (dem) by fusing the data with a second DEM (fill) that defines the topographic surface within the void areas. The two surfaces are fused seamlessly so that the transition from the source and fill surfaces is undetectable. The fill DEM need not have the same resolution as the source DEM.

The algorithm works by computing a DEM-of-difference (DoD) for each valid grid cell in the source DEM that also has a valid elevation in the corresponding location within the fill DEM. This difference surface is then used to define offsets within the near void-edge locations. The fill surface elevations are then combined with interpolated offsets, with the interpolation based on near-edge offsets, and used to define a new surface within the void areas of the source DEM in such a way that the data transitions seamlessly from the source data source to the fill data. The image below provides an example of this method.

The user must specify the mean_plane_dist parameter, which defines the distance (measured in grid cells) within a void area from the void's edge. Grid cells within larger voids that are beyond this distance from their edges have their vertical offsets, needed during the fusion of the DEMs, set to the mean offset for all grid cells that have both valid source and fill elevations. Void cells that are nearer their void edges have vertical offsets that are interpolated based on nearby offset values (i.e., the DEM of difference). The interpolation uses inverse-distance weighted (IDW) scheme, with a user-specified weight parameter (weight_value).

The edge_treatment parameter describes how the data fusion operates at the edges of voids, i.e., the first line of grid cells for which there are both source and fill elevation values. This parameter has values of "use DEM", "use Fill", and "average". Grohman et al. (2006) state that sometimes, due to a weakened signal within these marginal locations between the area of valid data and voids, the estimated elevation values are inaccurate. When this is the case, it is best to use fill elevations in the transitional areas. If this isn't the case, the "use DEM" is the better option. A compromise between the two options is to average the two elevation sources.

References:

Grohman, G., Kroenung, G. and Strebeck, J., 2006. Filling SRTM voids: The delta surface fill method. Photogrammetric Engineering and Remote Sensing, 72(3), pp.213-216.

See Also: FillMissingData

Parameters:

FlagDescription
--demName of the input raster DEM file, containing the void areas
--fillName of the input fill DEM file, containing the values used to fill the void areas in the other DEM
-o, --outputName of the output void-filled DEM file
--mean_plane_distDistance to void edge at which the mean-plane value is used as an offset, measured in grid cells
--edge_treatmentHow should void-edge cells be treated? Options include 'use DEM' (default), 'use Fill', 'average'
--weight_valueWeight value used for IDW interpolation (default is 2.0)

Python function:

wbt.dem_void_filling(
    dem, 
    fill, 
    output, 
    mean_plane_dist=20, 
    edge_treatment="use DEM", 
    weight_value=2.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=DemVoidFilling --dem=DEM.tif ^
--fill=fill_DEM.tif --output=dem_fused.tif --mean_plane_dist=25 ^
--weight_value=1.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 24/05/2022

Last Modified: 09/02/2023

DevFromMeanElev

This tool can be used to calculate the difference between the elevation of each grid cell and the mean elevation of the centering local neighbourhood, normalized by standard deviation. Therefore, this index of topographic residual is essentially equivalent to a local z-score. This attribute measures the relative topographic position as a fraction of local relief, and so is normalized to the local surface roughness. DevFromMeanElev utilizes an integral image approach (Crow, 1984) to ensure highly efficient filtering that is invariant with filter size.

The user must specify the name (--dem) of the input digital elevation model (DEM), the name of the output file (--output), and the size of the neighbourhood in the x and y directions (--filterx and --filtery), measured in grid size.

While DevFromMeanElev calculates the deviation from mean elevation (DEV) at a single, user-defined scale, the MaxElevationDeviation tool can be used to output the per-pixel maximum DEV value across a range of input scales.

See Also: DiffFromMeanElev, MaxElevationDeviation

Parameters:

FlagDescription
-i, --input, --demInput raster DEM file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.dev_from_mean_elev(
    dem, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

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

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:

FlagDescription
-i, --input, --demInput raster DEM file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.diff_from_mean_elev(
    dem, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 30/01/2020

DifferenceCurvature

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

This tool calculates the difference curvature from a digital elevation model (DEM). Difference curvature is half of the difference between profile and tangential curvatures, sometimes called the vertical and horizontal curvatures (Shary, 1995). This variable has an unbounded range that can take either positive or negative values. Florinsky (2017) states that difference curvature measures the extent to which the relative deceleration of flows (measured by kv) is higher than flow convergence at a given point of the topographic surface. Difference curvature is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

See Also:

ProfileCurvature, TangentialCurvature, Rotor, MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demName of the input raster DEM file
-o, --outputName of the output raster image file
--logDisplay output values using a log-scale
--zfactorZ conversion factor

Python function:

wbt.difference_curvature(
    dem, 
    output, 
    log=False, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=DifferenceCurvature -i=DEM.tif ^
-o=output.tif --log 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 11/01/2022

Last Modified: 28/11/2022

DirectionalRelief

This tool calculates the relief for each grid cell in a digital elevation model (DEM) in a specified direction. Directional relief is an index of the degree to which a DEM grid cell is higher or lower than its surroundings. It is calculated by subtracting the elevation of a DEM grid cell from the average elevation of those cells which lie between it and the edge of the DEM in a specified compass direction. Thus, positive values indicate that a grid cell is lower than the average elevation of the grid cells in a specific direction (i.e. relatively sheltered), whereas a negative directional relief indicates that the grid cell is higher (i.e. relatively exposed). The algorithm is based on a modification of the procedure described by Lapen and Martz (1993). The modifications include: (1) the ability to specify any direction between 0-degrees and 360-degrees (--azimuth), and (2) the ability to use a distance-limited search (--max_dist), such that the ray-tracing procedure terminates before the DEM edge is reached for longer search paths. The algorithm works by tracing a ray from each grid cell in the direction of interest and evaluating the average elevation along the ray. Linear interpolation is used to estimate the elevation of the surface where a ray does not intersect the DEM grid precisely at one of its nodes. The user must specify the name of an input DEM raster file, the output raster name, and a hypothetical wind direction. Furthermore, the user is able to constrain the maximum search distance for the ray tracing. If no maximum search distance is specified, each ray will be traced to the edge of the DEM. The units of the output image are the same as the input DEM.

Ray-tracing is a highly computationally intensive task and therefore this tool may take considerable time to operate for larger sized DEMs. This tool is parallelized to aid with computational efficiency. NoData valued grid cells in the input image will be assigned NoData values in the output image. The output raster is of the float data type and continuous data scale. Directional relief is best displayed using the blue-white-red bipolar palette to distinguish between the positive and negative values that are present in the output.

Reference:

Lapen, D. R., & Martz, L. W. (1993). The measurement of two simple topographic indices of wind sheltering-exposure from raster digital elevation models. Computers & Geosciences, 19(6), 769-779.

See Also: FetchAnalysis, HorizonAngle, RelativeAspect

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--azimuthWind azimuth in degrees
--max_distOptional maximum search distance (unspecified if none; in xy units)

Python function:

wbt.directional_relief(
    dem, 
    output, 
    azimuth=0.0, 
    max_dist=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DirectionalRelief -v ^
--wd="/path/to/data/" -i='input.tif' -o=output.tif ^
--azimuth=315.0 

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--dropVertical drop value (default is 2.0)
--out_typeOutput type, options include 'tangent', 'degrees', 'radians', 'distance' (default is 'tangent')

Python function:

wbt.downslope_index(
    dem, 
    output, 
    drop=2.0, 
    out_type="tangent", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DownslopeIndex -v --wd="/path/to/data/" ^
--dem=pointer.tif -o=dsi.tif --drop=5.0 --out_type=distance 

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--filterSize of the filter kernel
--norm_diffMaximum difference in normal vectors, in degrees
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.edge_density(
    dem, 
    output, 
    filter=11, 
    norm_diff=5.0, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=EdgeDensity -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --filter=15 --norm_diff=20.0 ^
--num_iter=4 

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

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

EP = counti∈C(zi > z0) x (100 / nC)

where z0 is the elevation of the window's center grid cell, zi is the elevation of cell i contained within the neighboring set C, and nC is the number of grid cells contained within the window.

EP is unsigned and expressed as a percentage, bound between 0% and 100%. Quantile-based estimates (e.g., the median and interquartile range) are often used in nonparametric statistics to provide data variability estimates without assuming the distribution is normal. Thus, EP is largely unaffected by irregularly shaped elevation frequency distributions or by outliers in the DEM, resulting in a highly robust metric of LTP. In fact, elevation distributions within small to medium sized neighborhoods often exhibit skewed, multimodal, and non-Gaussian distributions, where the occurrence of elevation errors can often result in distribution outliers. Thus, based on these statistical characteristics, EP is considered one of the most robust representation of LTP.

The algorithm implemented by this tool uses the relatively efficient running-histogram filtering algorithm of Huang et al. (1979). Because most DEMs contain floating point data, elevation values must be rounded to be binned. The --sig_digits parameter is used to determine the level of precision preserved during this binning process. The algorithm is parallelized to further aid with computational efficiency.

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

FlagDescription
-i, --input, --demInput raster DEM file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction
--sig_digitsNumber of significant digits

Python function:

wbt.elev_percentile(
    dem, 
    output, 
    filterx=11, 
    filtery=11, 
    sig_digits=2, 
    callback=default_callback
)

Command-line Interface:

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

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

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:

FlagDescription
-i, --demInput raster DEM file
--watershedsInput raster watersheds file
-o, --outputOutput raster file

Python function:

wbt.elev_relative_to_watershed_min_max(
    dem, 
    watersheds, 
    output, 
    callback=default_callback
)

Command-line Interface:

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

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:

FlagDescription
-i, --demInput raster DEM file
--road_vecInput vector polygons file
-o, --outputOutput raster file
--search_distSearch distance used to reposition transportation vectors onto road embankments (in map units)
--min_road_widthMinimum road width; this is the width of the paved road surface (in map units)
--typical_widthTypical embankment width; this is the maximum width of an embankment with roadside ditches (in map units)
--max_heightTypical embankment maximum height; this is the height a typical embankment with roadside ditches (in map units)
--max_widthMaximum embankment width, typically where embankments traverse steep-sided valleys (in map units)
--max_incrementMaximum upwards increment between neighbouring cells on an embankment (in elevation units)
--spillout_slopeSpillout slope (in degrees)
--remove_embankmentsOptional flag indicating whether to output a DEM with embankments removed (true) or an embankment raster map (false)

Python function:

wbt.embankment_mapping(
    dem, 
    road_vec, 
    output, 
    search_dist=2.5, 
    min_road_width=6.0, 
    typical_width=30.0, 
    max_height=2.0, 
    max_width=60.0, 
    max_increment=0.05, 
    spillout_slope=4.0, 
    remove_embankments=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=EmbankmentMapping -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif ^
--search_dist=1.0 --min_road_width=6.0 --typical_width=30.0 ^
--max_height=2.0 --max_width=60.0 --max_increment=0.05 ^
--spillout_slope=4.0 --remove_embankments=true 

Source code on GitHub

Author: Dr. John Lindsay and Nigel Van Nieuwenhuizen

Created: 21/09/2020

Last Modified: 05/10/2020

ExposureTowardsWindFlux

This tool creates a new raster in which each grid cell is assigned the exposure of the land-surface to a hypothetical wind flux. It can be conceptualized as the angle between a plane orthogonal to the wind and a plane that represents the local topography at a grid cell (Bohner and Antonic, 2007). The user must specify the names of the input digital elevation model (--dem) and output file (--output), as well as the dominant wind azimuth (--azimuth) and a maximum search distance (--max_dist) used to calclate the horizon angle. Notice that the specified azimuth represents a regional average wind direction.

Exposure towards the sloped wind flux essentially combines the relative terrain aspect and the maximum upwind slope (i.e. horizon angle). This terrain attribute accounts for land-surface orientation, relative to the wind, and shadowing effects of distant topographic features but does not account for deflection of the wind by topography. This tool should not be used on very extensive areas over which Earth's curvature must be taken into account. DEMs in projected coordinate systems are preferred.

Algorithm Description:

Exposure is measured based on the equation presented in Antonic and Legovic (1999):

cos(E) = cos(S) sin(H) + sin(S) cos(H) cos(Az - A)

Where, E is angle between a plane defining the local terrain and a plane orthogonal to the wind flux, S is the terrain slope, A is the terrain aspect, Az is the azimuth of the wind flux, and H is the horizon angle of the wind flux, which is zero when only the horizontal component of the wind flux is accounted for.

Exposure images are best displayed using a greyscale or bipolar palette to distinguish between the positive and negative values that are present in the output.

References:

Antonić, O., & Legović, T. 1999. Estimating the direction of an unknown air pollution source using a digital elevation model and a sample of deposition. Ecological modelling, 124(1), 85-95.

Böhner, J., & Antonić, O. 2009. Land-surface parameters specific to topo-climatology. Developments in Soil Science, 33, 195-226.

See Also: RelativeAspect

Parameters:

FlagDescription
-d, --demName of the input DEM raster file
-o, --outputName of the output raster file
--azimuthWind azimuth, in degrees
--max_distOptional maximum search distance. Minimum value is 5 x cell size
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.exposure_towards_wind_flux(
    dem, 
    output, 
    azimuth="", 
    max_dist="", 
    zfactor="", 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=ExposureTowardsWindFlux -dem=input.tif ^
-o=exposure.tif --azimuth=35.0 --max_dist=500.0 

Source code on GitHub

Author: Whitebox Geospatial Inc. (c)

Created: 20/07/2021

Last Modified: 20/07/2021

FeaturePreservingSmoothing

This tool implements a highly modified form of the DEM de-noising algorithm described by Sun et al. (2007). It is very effective at removing surface roughness from digital elevation models (DEMs), without significantly altering breaks-in-slope. As such, this tool should be used for smoothing DEMs rather than either smoothing with low-pass filters (e.g. mean, median, Gaussian filters) or grid size coarsening by resampling. The algorithm works by 1) calculating the surface normal 3D vector of each grid cell in the DEM, 2) smoothing the normal vector field using a filtering scheme that applies more weight to neighbours with lower angular difference in surface normal vectors, and 3) uses the smoothed normal vector field to update the elevations in the input DEM.

Sun et al.'s (2007) original method was intended to work on input point clouds and fitted triangular irregular networks (TINs). The algorithm has been modified to work with input raster DEMs instead. In so doing, this algorithm calculates surface normal vectors from the planes fitted to 3 x 3 neighbourhoods surrounding each grid cell, rather than the triangular facet. The normal vector field smoothing and elevation updating procedures are also based on raster filtering operations. These modifications make this tool more efficient than Sun's original method, but will also result in a slightly different output than what would be achieved with Sun's method.

The user must specify the values of three key parameters, including the filter size (--filter), the normal difference threshold (--norm_diff), and the number of iterations (--num_iter). Lindsay et al. (2019) found that the degree of smoothing was less impacted by the filter size than it was either the normal difference threshold and the number of iterations. A filter size of 11, the default value, tends to work well in many cases. To increase the level of smoothing applied to the DEM, consider increasing the normal difference threshold, i.e. the angular difference in normal vectors between the center cell of a filter window and a neighbouring cell. This parameter determines which neighbouring values are included in a filtering operation and higher values will result in a greater number of neighbouring cells included, and therefore smooother surfaces. Similarly, increasing the number of iterations from the default value of 3 to upwards of 5-10 will result in significantly greater smoothing.

Before smoothing treatment:

After smoothing treatment with FPS:

For a video tutorial on how to use the FeaturePreservingSmoothing tool, please see this YouTube video.

Reference:

Lindsay JB, Francioni A, Cockburn JMH. 2019. LiDAR DEM smoothing and the preservation of drainage features. Remote Sensing, 11(16), 1926; DOI: 10.3390/rs11161926.

Sun, X., Rosin, P., Martin, R., & Langbein, F. (2007). Fast and effective feature-preserving mesh denoising. IEEE Transactions on Visualization & Computer Graphics, (5), 925-938.

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--filterSize of the filter kernel
--norm_diffMaximum difference in normal vectors, in degrees
--num_iterNumber of iterations
--max_diffMaximum allowable absolute elevation change (optional)
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.feature_preserving_smoothing(
    dem, 
    output, 
    filter=11, 
    norm_diff=15.0, 
    num_iter=3, 
    max_diff=0.5, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FeaturePreservingSmoothing -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif --filter=15 ^
--norm_diff=20.0 --num_iter=4 

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:

Ztest >= Zcore + DI

where Zcore is the elevation of the grid cell at which fetch is being determined, Ztest is the elevation of the grid cell being tested as a topographic obstacle, D is the distance between the two grid cells in meters, and I is the height increment in m/m. Lapen and Martz (1993) suggest values for I in the range of 0.025 m/m to 0.1 m/m based on their study of snow re-distribution in low-relief agricultural landscapes of the Canadian Prairies. If the directional search does not identify an obstacle grid cell before the edge of the DEM is reached, the distance between the DEM edge and Zcore is entered. Edge distances are assigned negative values to differentiate between these artificially truncated fetch values and those for which a valid topographic obstacle was identified. Notice that linear interpolation is used to estimate the elevation of the surface where a ray (i.e. the search path) does not intersect the DEM grid precisely at one of its nodes.

Ray-tracing is a highly computationally intensive task and therefore this tool may take considerable time to operate for larger sized DEMs. This tool is parallelized to aid with computational efficiency. NoData valued grid cells in the input image will be assigned NoData values in the output image. Fetch Analysis images are best displayed using the blue-white-red bipolar palette to distinguish between the positive and negative values that are present in the output.

Reference:

Lapen, D. R., & Martz, L. W. (1993). The measurement of two simple topographic indices of wind sheltering-exposure from raster digital elevation models. Computers & Geosciences, 19(6), 769-779.

See Also: DirectionalRelief, HorizonAngle, RelativeAspect

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--azimuthWind azimuth in degrees in degrees
--hgt_incHeight increment value

Python function:

wbt.fetch_analysis(
    dem, 
    output, 
    azimuth=0.0, 
    hgt_inc=0.05, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FetchAnalysis -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif --azimuth=315.0 

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:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterFilter size (cells)
--weightIDW weight value
--no_edgesOptional flag indicating whether to exclude NoData cells in edge regions

Python function:

wbt.fill_missing_data(
    i, 
    output, 
    filter=11, 
    weight=2.0, 
    no_edges=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FillMissingData -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif --filter=25 ^
--weight=1.0 --no_edges 

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--line_thinOptional flag indicating whether post-processing line-thinning should be performed

Python function:

wbt.find_ridges(
    dem, 
    output, 
    line_thin=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FindRidges -v --wd="/path/to/data/" ^
--dem=pointer.tif -o=out.tif --line_thin 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/12/2017

Last Modified: 18/10/2019

GaussianCurvature

This tool calculates the Gaussian curvature from a digital elevation model (DEM). Gaussian curvature is the product of maximal and minimal curvatures, and retains values in each point of the topographic surface after its bending without breaking, stretching, and compressing (Florinsky, 2017). Gaussian curvature is measured in units of m-2.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

TangentialCurvature, ProfileCurvature, PlanCurvature, MeanCurvature, MinimalCurvature, MaximalCurvature

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--logDisplay output values using a log-scale
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.gaussian_curvature(
    dem, 
    output, 
    log=False, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/01/2022

Last Modified: 15/01/2022

GaussianScaleSpace

This tool uses the fast Gaussian approximation algorithm to produce scaled land-surface parameter (LSP) measurements from an input DEM (--dem). The algorithm iterates over scales defined by an initial scale (--sigma), a step size (--step) and a number of scales (--num_steps)/. After smoothing the input DEM to the target sigma, a 3x3 window is used to calculate a variety of LSPs (--lsp). LSP options include local derivatives (Elevation, Slope, Aspect, Eastness, Northness, Mean curvature, Plan curvature, Profile curvature, Tangential curvature and Total curvature), Hillshade, and Difference from mean elevation, all as defined in Wilson (2018), and Anisotropy of topographic position (Newman et al., 2018), and Ruggedness (Riley et al., 1999). An initial sigma value of 0 will compute the LSP without Gaussian smoothing. The step size can be and positive number, however, sigam values < 0.5 and duplicated scales are skipped due to a minimum filter size limitation, or the scale discretization of the fast gaussian approximation.

The LSP values are then transformed to z-scores using the population of values at a single scale, are are evaluated to identify the optimal scale defined as the maximum absolute z-score for each cell. The final outputs are three rasters: the first containing the z-score at the optimal scale (z_opt), the sigma value at the optimal scale (g_opt), and the LSP value at the optimal scale (v_opt). These all need to be specified using the (--output_zscore), (--output_scale), and (--output) flags respectively. Additionally, a vector file of points (--points) can optionally be provided to generate scale signatures for the provided point locations.

Due to the use of the integral image, edge effects can be problematic; especially when 'NoData' values are found. It is recommended that 'NoData' holes filled during pre-processing. Irregular shaped data (i.e., non-rectangular DEMs) are buffered with a crude check for 'NoData' values at the filter edge in the 8 cardinal directions to buffer the edges. This should be adequate for most data, additional buffer masks may be required.

Reference:

Wilson, J. P. (2018). Environmental-applications-of-digital-terrain-modeling. Wiley Blackwell. Newman, D. R., Lindsay, J. B., & Cockburn, J. M. H. (2018). Measuring Hyperscale Topographic Anisotropy as a Continuous Landscape Property. Geosciences, 8(278). https://doi.org/10.3390/geosciences8080278

Riley, S. J., DeGloria, S. D., and Elliot, R. (1999). Index that quantifies topographic heterogeneity.Intermountain Journal of Sciences, 5(1-4), 23-27.

See Also: MaxDifferenceFromMean, MaxAnisotropyDev, ProfileCurvature, TangentialCurvature, RuggednessIndex

Parameters:

FlagDescription
-d, --demName of the input DEM raster file
-p, --pointsName of the input vector points shapefile
-o, --outputName of the output land-surface parameter raster file
--output_zscoreName of the output z-score raster file
--output_scaleName of the output scale raster file
--sigmaInitial sigma value (cells)
--stepStep size as any positive non-zero integer
--num_stepsNumber of steps
--lspOutput land-surface parameter; one of 'AnisotropyLTP', 'Aspect', 'DiffMeanElev', 'Eastness', 'Elevation', 'Hillshade', 'MeanCurvature', 'Northness', 'PlanCurvature', 'ProfileCurvature', 'Ruggedness', 'Slope', 'TanCurvature', 'TotalCurvature'
--z_factorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.gaussian_scale_space(
    dem, 
    output, 
    output_zscore, 
    output_scale, 
    points=None, 
    sigma=0.5, 
    step=0.5, 
    num_steps=10, 
    lsp="Slope", 
    z_factor=None, 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=GaussianScaleSpace --dem=DEM.tif ^
--output=slope.tif --output_zscore=slope_z.tif ^
--output_scale=slope_scale.tif --sigma=0.5 --step=1.0 ^
--num_steps=100 --lsp='Slope' 

Source code on GitHub

Author: Daniel Newman

Created: 01/01/2021

Last Modified: 01/01/2021

GeneratingFunction

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

This tool calculates the generating function (Shary and Stepanov, 1991) from a digital elevation model (DEM). Florinsky (2016) describes generating function as a measure for the deflection of tangential curvature from loci of extreme curvature of the topographic surface. Florinsky (2016) demonstrated the application of this variable for identifying landscape structural lines, i.e. ridges and thalwegs, for which the generating function takes values near zero. Ridges coincide with divergent areas where generating function is approximately zero, while thalwegs are associated with convergent areas with generating function values near zero. This variable has positive values, zero or greater and is measured in units of m-2.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Raw generating function values are often challenging to visualize given their range and magnitude, and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

This tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems, however, this tool cannot use the same 3x3 polynomial fitting method for equal angle grids, also described by Florinsky (2016), that is used by the other curvature tools in this software. That is because generating function uses 3rd order partial derivatives, which cannot be calculated using the 9 elevations in a 3x3; more elevation values are required (i.e. a 5x5 window). Thus, this tool uses the same 5x5 method used for DEMs in projected coordinate systems, and calculates the average linear distance between neighbouring cells in the vertical and horizontal directions using the Vincenty distance function. Note that this may cause a notable slow-down in algorithm performance and has a lower accuracy than would be achieved using an equal angle method, because it assumes a square pixel (in linear units).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Koenderink, J. J., and Van Doorn, A. J. (1992). Surface shape and curvature scales. Image and vision computing, 10(8), 557-564.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

Shary P. A. and Stepanov I. N. (1991) Application of the method of second derivatives in geology. Transactions (Doklady) of the USSR Academy of Sciences, Earth Science Sections 320: 87–92.

See Also:

ShapeIndex, MinimalCurvature, MaximalCurvature, TangentialCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demName of the input raster DEM file
-o, --outputName of the output raster image file
--logDisplay output values using a log-scale
--zfactorZ conversion factor

Python function:

wbt.generating_function(
    dem, 
    output, 
    log=False, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=GeneratingFunction -i=DEM.tif ^
-o=output.tif --log 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 11/01/2022

Last Modified: 28/11/2022

Geomorphons

This tool can be used to perform a geomorphons landform classification based on an input digital elevation model (--dem). The geomorphons concept is based on line-of-sight analysis for the eight topographic profiles in the cardinal directions surrounding each grid cell in the input DEM. The relative sizes of the zenith angle of a profile's maximum elevation angle (i.e. horizon angle) and the nadir angle of a profile's minimum elevation angle are then used to generate a ternary (base-3) digit: 0 when the nadir angle is less than the zenith angle, 1 when the two angles differ by less than a user-defined flatness threshold (--threshold), and 2 when the nadir angle is greater than the zenith angle. A ternary number is then derived from the digits assigned to each of the eight profiles, with digits sequenced counter-clockwise from east. This ternary number forms the geomorphons code assigned to the grid cell. There are 38 = 6561 possible codes, although many of these codes are equivalent geomorphons through rotations and reflections. Some of the remaining geomorphons also rarely if ever occur in natural topography. Jasiewicz et al. (2013) identified 10 common landform types by reclassifying related geomorphons codes. The user may choose to output these common forms (--forms) rather than the the raw ternary code. These landforms include:

ValueLandform Type
1Flat
2Peak (summit)
3Ridge
4Shoulder
5Spur (convex)
6Slope
7Hollow (concave)
8Footslope
9Valley
10Pit (depression)

One of the main advantages of the geomrophons method is that, being based on minimum/maximum elevation angles, the scale used to estimate the landform type at a site adapts to the surrounding terrain. In principle, choosing a large value of search distance (--search) should result in identification of a landform element regardless of its scale.

An experimental feature has been added to correct for global inclination. Global inclination biases the flatness threshold angle becasue it is measured relative to the z-axis, especially in locally flat areas. Including the --residuals flag "flattens" the input by converting elevation to residuals of a 2-d linear model.

Reference:

Jasiewicz, J., and Stepinski, T. F. (2013). Geomorphons — a pattern recognition approach to classification and mapping of landforms. Geomorphology, 182, 147-156.

See Also: PennockLandformClass

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--searchLook up distance (in cells)
--thresholdFlatness threshold for the classification function (in degrees)
--fdistDistance (in cells) to begin reducing the flatness threshold to avoid problems with pseudo-flat lines-of-sight
--skipDistance (in cells) to begin calculating lines-of-sight
-f, --formsClassify geomorphons into 10 common land morphologies, else output ternary pattern
--residualsConvert elevation to residuals of a linear model

Python function:

wbt.geomorphons(
    dem, 
    output, 
    search=50, 
    threshold=0.0, 
    fdist=0, 
    skip=0, 
    forms=True, 
    residuals=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Geomorphons -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --search=50 --threshold=0.0 ^
--tdist=0.0 --forms 

Source code on GitHub

Author: Daniel Newman

Created: 21/09/2018

Last Modified: 07/06/2022

Hillshade

This tool performs a hillshade operation (also called shaded relief) on an input digital elevation model (DEM). The user must specify the name of the input DEM and the output hillshade image name. Other parameters that must be specified include the illumination source azimuth (--azimuth), or sun direction (0-360 degrees), the illumination source altitude (--altitude; i.e. the elevation of the sun above the horizon, measured as an angle from 0 to 90 degrees) and the Z conversion factor (--zfactor). The Z conversion factor is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z conversion factor. If the DEM is in the geographic coordinate system (latitude and longitude), the following equation is used:

zfactor = 1.0 / (111320.0 x cos(mid_lat))

where mid_lat is the latitude of the centre of the raster, in radians.

The hillshade value (HS) of a DEM grid cell is calculate as:

HS = tan(s) / [1 - tan(s)2]0.5 x [sin(Alt) / tan(s) - cos(Alt) x sin(Az - a)]

where s and a are the local slope gradient and aspect (orientation) respectively and Alt and Az are the illumination source altitude and azimuth respectively. Slope and aspect are calculated using Horn's (1981) 3rd-order finate difference method.

Reference:

Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, in Terrain Analysis: Principles and Applications, edited by J. P. Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.

See Also: HypsometricallyTintedHillshade, MultidirectionalHillshade, Aspect, Slope

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--azimuthIllumination source azimuth in degrees
--altitudeIllumination source altitude in degrees
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.hillshade(
    dem, 
    output, 
    azimuth=315.0, 
    altitude=30.0, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Hillshade -v --wd="/path/to/data/" ^
-i=DEM.tif -o=output.tif --azimuth=315.0 --altitude=30.0 

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--azimuthAzimuth, in degrees
--max_distOptional maximum search distance (unspecified if none; in xy units). Minimum value is 5 x cell size

Python function:

wbt.horizon_angle(
    dem, 
    output, 
    azimuth=0.0, 
    max_dist=100.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HorizonAngle -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif --azimuth=315.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 07/07/2017

Last Modified: 03/09/2020

HorizontalExcessCurvature

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

This tool calculates the horizontal excess curvature from a digital elevation model (DEM). Horizontal excess curvature is the difference of tangential (horizontal) and minimal curvatures at a location (Shary, 1995). This variable has positive values, zero or greater. Florinsky (2017) states that horizontal excess curvature measures the extent to which the bending of a normal section tangential to a contour line is larger than the minimal bending at a given point of the surface. Horizontal excess curvature is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

See Also:

TangentialCurvature, ProfileCurvature, MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demName of the input raster DEM file
-o, --outputName of the output raster image file
--logDisplay output values using a log-scale
--zfactorZ conversion factor

Python function:

wbt.horizontal_excess_curvature(
    dem, 
    output, 
    log=False, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=HorizontalExcessCurvature -i=DEM.tif ^
-o=output.tif --log 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 11/01/2022

Last Modified: 28/11/2022

HypsometricAnalysis

This tool can be used to derive the hypsometric curve, or area-altitude curve, of one or more input digital elevation models (DEMs) (--inputs). A hypsometric curve is a histogram or cumulative distribution function of elevations in a geographical area.

See Also: SlopeVsElevationPlot

Parameters:

FlagDescription
-i, --inputsInput DEM files
--watershedInput watershed files (optional)
-o, --outputOutput HTML file (default name will be based on input file if unspecified)

Python function:

wbt.hypsometric_analysis(
    inputs, 
    output, 
    watershed=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HypsometricAnalysis -v ^
--wd="/path/to/data/" -i="DEM1.tif;DEM2.tif" ^
--watershed="ws1.tif;ws2.tif" -o=outfile.html 

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--altitudeIllumination source altitude in degrees
--hs_weightWeight given to hillshade relative to relief (0.0-1.0)
--brightnessBrightness factor (0.0-1.0)
--atmosphericAtmospheric effects weight (0.0-1.0)
--paletteOptions include 'atlas', 'high_relief', 'arid', 'soft', 'muted', 'purple', 'viridis', 'gn_yl', 'pi_y_g', 'bl_yl_rd', and 'deep'
--reverseOptional flag indicating whether to use reverse the palette
--zfactorOptional multiplier for when the vertical and horizontal units are not the same
--full_modeOptional flag indicating whether to use full 360-degrees of illumination sources

Python function:

wbt.hypsometrically_tinted_hillshade(
    dem, 
    output, 
    altitude=45.0, 
    hs_weight=0.5, 
    brightness=0.5, 
    atmospheric=0.0, 
    palette="atlas", 
    reverse=False, 
    zfactor=None, 
    full_mode=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HypsometricallyTintedHillshade -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif --altitude=45.0 ^
--hs_weight=0.3 --brightness=0.6 --atmospheric=0.2 ^
--palette=arid --full_mode 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/07/2020

Last Modified: 03/09/2020

LocalHypsometricAnalysis

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

This tool calculates the hypsometric integral from the elevation distribution contained within the local neighbourhood surrounding each grid cell in an input (--input) DEM. The hyspometric integral (HI) is the area under the hypsometric curve, which is a plot that relates elevation and area. This plot is a cumulative distribution function with elevation expressed as a proportion of maximum elevation and area expressed as the proportion of the area above. Hypsometry, or area-altitude analysis, is commonly used by geomorphologists and geologists to characterize the erosional history of drainage basins. The HI, ranging between 0 and 1, expresses the volume of land that lies above the lowest point within an area, and thus has not been eroded. Relatively low HI values are indicative of more strongly eroded surfaces.

Some researchers (e.g. Pérez‐Peña et al., 2009) have demonstrated the usefulness of applying hypsometry in a spatially distributed fashion, rather than aggregated by basins, as it is typically applied. While Pérez‐Peña et al. (2009) characterized spatial distributions of HI using coarse grids overlayed overtop a digital elevation model (DEM), this tool uses a filter-based approach instead. Each grid cell in the input DEM (--input) has an individual HI calculation based on the elevation distribution within a moving kernel. HI values are calculated using the elevation-relief ratio method described by Pike and Wilson (1971).

In actuality, the tool uses a multi-scale approach, much like many of the other tools within the Geomorphometric Analysis toolbox (e.g. MaxElevationDeviation, MultiscaleStdDevNormals), such that the neighbourhood size is varied according to a range defined by user-specified input parameters. The HI that is reported within each grid cell in the output raster is the minimum HI value measured for each of the tested scales, defined by lower (rL) and upper (rU) ranges.

HImin=min{HI(r):r=rL...rU},

In this way, it represents a heterogenous, locally scale optimized map of HI distributions. A nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges, where there is often greater variability in HI values, and coarser at longer tested scales, such that:

ri = rL + [step × (i - rL)]p

Where ri is the filter radius for step i and p is the nonlinear scaling factor (--step_nonlinearity) and a step size (--step) of step.

There are two outputs generated from this tool, including the HImin raster (--out_mag) and the rmin scale raster (--out_scale).

References:

Pérez‐Peña, J. V., Azañón, J. M., Booth‐Rea, G., Azor, A., and Delgado, J. (2009). Differentiating geology and tectonics using a spatial autocorrelation technique for the hypsometric integral. Journal of Geophysical Research: Earth Surface, 114(F2).

Pike, R. J., and Wilson, S. E. (1971). Elevation-relief ratio, hypsometric integral, and geomorphic area-altitude analysis. Geological Society of America Bulletin, 82(4), 1079-1084.

See Also: HypsometricAnalysis, MaxElevationDeviation, MultiscaleStdDevNormals

Parameters:

FlagDescription
-i, --inputName of the input raster DEM file
--out_magName of the openness output raster file
--out_scaleName of the openness output raster file
--min_scaleMinimum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer
--num_stepsNumber of steps
--step_nonlinearityStep nonlinearity factor (1.0-2.0 is typical)

Python function:

wbt.local_hypsometric_analysis(
    i, 
    out_mag, 
    out_scale, 
    min_scale=4, 
    step=1, 
    num_steps=10, 
    step_nonlinearity=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LocalHypsometricAnalysis ^
--input=DEM.tif --out_mag=HI_magnitude.tif ^
--out_scale=HI_scale.tif --min_scale=4 --step=1 --num_steps=50 ^
--step_nonlinearity=1.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 07/11/2021

Last Modified: 05/12/2021

LocalQuadraticRegression

This tool is an implementation of the constrained quadratic regression algorithm using a flexible window size described in Wood (1996). A quadratic surface is fit to local areas of input DEM (--dem), defined by a filter size (--filter) using least squares regression. Note that the model is constrained such that it must pass through the cell at the center of the filter. This is accomplished by representing all elevations relative to the center cell, and by making the equation constant 0.

Surface derivatives are calculated from the coefficients of the local quadratic surface once they are known. These include: Slope, Aspect, Profile convexity, Plan convexity, Longitudinal curvature, Cross-sectional curvature, and Minimum profile convexity, all as defined in Wood (1996). The goodness-of-fit (r-squared) of each local quadratic model is also returned.

Due to the fact that large filter sizes require long processing times, and that fitting the surface is the most time consuming part of the algorithm, all LSPs are output every time this tool is run. The content of each output is described by the suffixes of the output file names.

Reference:

Wood, J. (1996). The Geomorphological Characterisation of Digital Elevation Models. University of Leicester.

See Also: Aspect, Slope, PlanCurvature, ProfileCurvature

Parameters:

FlagDescription
-d, --demName of the input DEM raster file
-o, --outputName of the output raster file
--filterEdge length of the filter kernel

Python function:

wbt.local_quadratic_regression(
    dem, 
    output, 
    filter=3, 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=LocalQuadraticRegression --dem=DEM.tif ^
--output=out_ras.tif --filter=15 

Source code on GitHub

Author: Daniel Newman

Created: 22/06/2020

Last Modified: 22/06/2020

MapOffTerrainObjects

This tool can be used to map off-terrain objects in a digital surface model (DSM) based on cell-to-cell differences in elevations and local slopes. The algorithm works by using a region-growing operation to connect neighbouring grid cells outwards from seed cells. Two neighbouring cells are considered connected if the slope between the two cells is less than the user-specified maximum slope value (--max_slope). Mapped segments that are less than the minimum feature size (--min_size), in grid cells, are assigned a common background value. Note that this method of mapping off-terrain objects, and thereby separating ground cells from non-ground objects in DSMs, works best with fine-resolution DSMs that have been interpolated using a non-smoothing method, such as triangulation (TINing) or nearest-neighbour interpolation.

See Also: RemoveOffTerrainObjects

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--max_slopeMaximum inter-cell absolute slope
--min_sizeMinimum feature size, in grid cells

Python function:

wbt.map_off_terrain_objects(
    dem, 
    output, 
    max_slope=40.0, 
    min_size=1, 
    callback=default_callback
)

Command-line Interface:

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

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:

FlagDescription
-i, --demInput raster DEM file
--out_magOutput raster DEVmax magnitude file
--out_scaleOutput raster DEVmax scale file
--min_scaleMinimum search neighbourhood radius in grid cells
--max_scaleMaximum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer

Python function:

wbt.max_anisotropy_dev(
    dem, 
    out_mag, 
    out_scale, 
    max_scale, 
    min_scale=3, 
    step=2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MaxAnisotropyDev -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=DEVmax_mag.tif ^
--out_scale=DEVmax_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5 

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:

FlagDescription
-i, --demInput raster DEM file
--pointsInput vector points file
-o, --outputOutput HTML file
--min_scaleMinimum search neighbourhood radius in grid cells
--max_scaleMaximum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer

Python function:

wbt.max_anisotropy_dev_signature(
    dem, 
    points, 
    output, 
    max_scale, 
    min_scale=1, 
    step=1, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MaxAnisotropyDevSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.shp ^
--output=roughness.html --min_scale=1 --max_scale=1000 ^
--step=5 

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--logOptional flag to request the output be log-transformed

Python function:

wbt.max_branch_length(
    dem, 
    output, 
    log=False, 
    callback=default_callback
)

Command-line Interface:

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

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:

FlagDescription
-i, --demInput raster DEM file
--out_magOutput raster DIFFmax magnitude file
--out_scaleOutput raster DIFFmax scale file
--min_scaleMinimum search neighbourhood radius in grid cells
--max_scaleMaximum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer

Python function:

wbt.max_difference_from_mean(
    dem, 
    out_mag, 
    out_scale, 
    min_scale, 
    max_scale, 
    step=1, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MaxDifferenceFromMean -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=DEVmax_mag.tif ^
--out_scale=DEVmax_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5 

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

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

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:

FlagDescription
-i, --demInput raster DEM file
--pointsInput vector points file
-o, --outputOutput HTML file
--min_scaleMinimum search neighbourhood radius in grid cells
--max_scaleMaximum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer

Python function:

wbt.max_elev_dev_signature(
    dem, 
    points, 
    output, 
    min_scale, 
    max_scale, 
    step=10, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MaxElevDevSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.tif ^
--output=topo_position.html --min_scale=1 --max_scale=1000 ^
--step=5 

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:

FlagDescription
-i, --demInput raster DEM file
--out_magOutput raster DEVmax magnitude file
--out_scaleOutput raster DEVmax scale file
--min_scaleMinimum search neighbourhood radius in grid cells
--max_scaleMaximum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer

Python function:

wbt.max_elevation_deviation(
    dem, 
    out_mag, 
    out_scale, 
    min_scale, 
    max_scale, 
    step=1, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MaxElevationDeviation -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=DEVmax_mag.tif ^
--out_scale=DEVmax_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5 

Source code on GitHub

Author: Dr. John Lindsay

Created: July 20, 2017

Last Modified: 12/10/2018

MaxUpslopeElevChange

This tool calculates the maximum elevation difference in the upslope direction between each grid cell and its neighbouring cells within a digital elevation model (DEM). The user must specify the name of the input DEM (--dem) and the output (--output) raster name.

See Also: MaxDownslopeElevChange

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/01/2022

Last Modified: 27/01/2022

MaximalCurvature

This tool calculates the maximal curvature from a digital elevation model (DEM). Maximal curvature is the curvature of a principal section with the highest value of curvature at a given point of the topographic surface (Florinsky, 2017). The values of this curvature are unbounded, and positive values correspond to ridge positions while negative values are indicative of closed depressions (Florinsky, 2016). Maximal curvature is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

MinimalCurvature, TangentialCurvature, ProfileCurvature, PlanCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--logDisplay output values using a log-scale
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.maximal_curvature(
    dem, 
    output, 
    log=False, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/01/2022

Last Modified: 15/01/2022

MeanCurvature

This tool calculates the mean curvature from a digital elevation model (DEM). Mean curvature is the average of any mutually orthogonal normal sections, such as profile and tangential curvature (Wilson, 2018). This variable has an unbounded range that can take either positive or negative values. Florinsky (2017) states that mean curvature represents the two accumulation mechanisms of gravity-driven substances, convergence and relative deceleration of flows, with equal weights. Mean curvature is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

Wilson, J. P. (2018). Environmental applications of digital terrain modeling. John Wiley & Sons.

TangentialCurvature, ProfileCurvature, PlanCurvature, GaussianCurvature, MinimalCurvature, MaximalCurvature

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--logDisplay output values using a log-scale
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.mean_curvature(
    dem, 
    output, 
    log=False, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/11/2021

Last Modified: 12/01/2022

MinDownslopeElevChange

This tool calculates the minimum elevation drop between each grid cell and its neighbouring cells within a digital elevation model (DEM). The user must specify the name of the input DEM (--dem) and the output (--output) raster name.

See Also: MaxDownslopeElevChange, NumDownslopeNeighbours

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

MinimalCurvature

This tool calculates the minimal curvature from a digital elevation model (DEM). Minimal curvature is the curvature of a principal section with the lowest value of curvature at a given point of the topographic surface (Florinsky, 2017). The values of this curvature are unbounded, and positive values correspond to hills while negative values are indicative of valley positions (Florinsky, 2016). Minimal curvature is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

MaximalCurvature, TangentialCurvature, ProfileCurvature, PlanCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--logDisplay output values using a log-scale
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.minimal_curvature(
    dem, 
    output, 
    log=False, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/01/2022

Last Modified: 15/01/2022

MultidirectionalHillshade

This tool performs a hillshade operation (also called shaded relief) on an input digital elevation model (DEM) with multiple sources of illumination. The user must specify the name of the input DEM (--dem) and the output hillshade image name (--output). Other parameters that must be specified include the altitude of the illumination sources (--altitude; i.e. the elevation of the sun above the horizon, measured as an angle from 0 to 90 degrees) and the Z conversion factor (--zfactor). The Z conversion factor is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z conversion factor. If the DEM is in the geographic coordinate system (latitude and longitude), the following equation is used:

zfactor = 1.0 / (111320.0 x cos(mid_lat))

where mid_lat is the latitude of the centre of the raster, in radians. The Z conversion factor can also be used used to apply a vertical exageration to further emphasize landforms within the hillshade output.

The hillshade value (HS) of a DEM grid cell is calculate as:

HS = tan(s) / [1 - tan(s)2]0.5 x [sin(Alt) / tan(s) - cos(Alt) x sin(Az - a)]

where s and a are the local slope gradient and aspect (orientation) respectively and Alt and Az are the illumination source altitude and azimuth respectively. Slope and aspect are calculated using Horn's (1981) 3rd-order finate difference method.

Lastly, the user must specify whether or not to use full 360-degrees of illumination sources (--full_mode). When this flag is not specified, the tool will perform a weighted summation of the hillshade images from four illumination azimuth positions at 225, 270, 315, and 360 (0) degrees, given weights of 0.1, 0.4, 0.4, and 0.1 respectively. When run in the full 360-degree mode, eight illumination source azimuths are used to calculate the output at 0, 45, 90, 135, 180, 225, 270, and 315 degrees, with weights of 0.15, 0.125, 0.1, 0.05, 0.1, 0.125, 0.15, and 0.2 respectively.

Classic hillshade (Azimuth=315, Altitude=45.0)

Multi-directional hillshade (Altitude=45.0, Four-direction mode)

Multi-directional hillshade (Altitude=45.0, 360-degree mode)

See Also: Hillshade, HypsometricallyTintedHillshade, Aspect, Slope

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--altitudeIllumination source altitude in degrees
--zfactorOptional multiplier for when the vertical and horizontal units are not the same
--full_modeOptional flag indicating whether to use full 360-degrees of illumination sources

Python function:

wbt.multidirectional_hillshade(
    dem, 
    output, 
    altitude=45.0, 
    zfactor=None, 
    full_mode=False, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/07/2020

Last Modified: 03/09/2020

MultiscaleCurvatures

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

This tool calculates several multiscale curvatures and curvature-based indices from an input DEM (--dem). There are 18 curvature types (--curv_type) available, including: accumulation curvature, curvedness, difference curvature, Gaussian curvature, generating function, horizontal excess curvature, maximal curvature, mean curvature, minimal curvature, plan curvature, profile curvature, ring curvature, rotor, shape index, tangential curvature, total curvature, unsphericity, and vertical excess curvature. Each of these curvatures can be measured in non-multiscale fashion using the corresponding tools available in either the WhiteboxTools open-core or the Whitebox extension.

Like many of the multi-scale land-surface parameter tools available in Whitebox, this tool can be run in two different modes: it can either be used to measure curvature at a single specific scale or to generate a curvature scale mosaic. To understand the difference between these two modes, we must first understand how curvatures are measured and how the non-multiscale curvature tools (e.g. ProfileCurvature) work. Curvatures are generally measured by fitting a mathematically defined surface to the elevation values within the local neighbourhood surrounding each grid cell in a DEM. The Whitebox curvature tools use the algorithms described Florinsky (2016), which use the 25 elevations within a 5 x 5 local neighbouhood for projected DEMs, and the nine elevations within a 3 x 3 neighbourhood for DEMs in geographic coordinate systems. This is what determines the scale at which these land-surface parameters are calculated. Because they are calculated using small local neighbourhoods (kernels), then these algorithms are heavily impacted by micro-topographic roughness and DEM noise. For example, in a fine-resolution DEM containing a great deal of micro-topographic roughness, the measured curvature value will be dominated by topographic variation at the scale of the roughness rather than the hillslopes on which that roughness is superimposed. This mis-matched scaling can be a problem in many applications, e.g. in landform classification and slope failure modelling applications.

Using the MultiscaleCurvatures tool, the user can specify a certain desired scale, larger than that defined by the grid resolution and kernel size, over which a curvature should be characterized. The tool will then use a fast Gaussian scale-space method to remove the topographic variation in the DEM at scales less than the desired scale, and will then characterize the curvature using the usual method based on this scaled DEM. To measure curvature at a single non-local scale, the user must specify a minimum search neighbourhood radius in grid cells (--min_scale) greater than 0.0. Note that a minimum search neighbourhood of 0.0 will replicate the non-multiscale equivalent curvature tool and any --min_scale value > 0.0 will apply the Gassian scale space method to eliminate topographic variation less than the scale of the minimum search neighbourhood. The base step size (--step), number of steps (--num_steps), and step nonlinearity (--step_nonlinearity) parameters should all be left to their default values of 1 in this case. The output curvature raster will be written to the output magnitude file (--out_mag). The following animation shows several multiscale curvature rasters (tangential curvature) measured from a DEM across a range of spatial scales.

Alternatively, one can use this tool to create a curvature scale mosaic. In this case, the user specifies a range of spatial scales (i.e., a scale space) over which to measure curvature. The curvature scale-space is densely sampled and each grid cell is assigned the maximum absolute curvature value (for the specified curvature type) across the scale space. In this scale-mosaic mode, the user must also specify the output scale file name (--out_scale), which is an output raster that, for each grid cell, specifies the scale at which the maximum absolute curvature was identified. The following is an example of a scale mosaic of unsphericity for an area in Pole Canyon, Utah (min_scale=1.0, step=1, num_steps=50, step_nonlinearity=1.0).

Scale mosaics are useful when modelling spatial distributions of land-surface parameters, like curvatures, in complex and heterogeneous landscapes that contain an abundance of topographic variation (micro-topography, landforms, etc.) at widely varying spatial scales, often associated with different geomorphic processes. Notice how in the image above, relatively strong curvature values are being characterized for both the landforms associated with the smaller-scale mass-movement processes as well as the broader-scale fluvial erosion (i.e. valley incision and hillslopes). It would be difficult, or impossible, to achieve this effect using a single, uniform scale. Each location in a land-surface parameter scale mosaic represents the parameter measured at a characteristic scale, given the unique topography of the site and surroundings.

The properties of the sampled scale space are determined using the --min_scale, --step, --num_steps (greater than 1), and --step_nonlinearity parameters. Experience with multiscale curvature scales spaces has shown that they are more highly variable at shorter spatial scales and change more gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested scales, such that:

ri = rL + [step × (i - rL)]p

Where ri is the filter radius for step i and p is the nonlinear scaling factor (--step_nonlinearity) and a step size (--step) of step.

In scale-mosaic mode, the user must also decide whether or not to standardize the curvature values (--standardize). When this parameter is used, the algorithm will convert each curvature raster associated with each sampled region of scale-space to z-scores (i.e. differenced from the raster-wide mean and divided by the raster-wide standard deviation). It it usually the case that curvature values measured at broader spatial scales will on the whole become less strongly valued. Because the scale mosaic algorithm used in this tool assigns each grid cell the maximum absolute curvature observed within sampled scale-space, this implies that the curvature values associated with more local-scale ranges are more likely to be selected for the final scale-mosaic raster. By standardizing each scaled curvature raster, there is greater opportunity for the final scale-mosaic to represent broader scale topographic variation. Whether or not this is appropriate will depend on the application. However, it is important to stress that the sampled scale-space need not span the full range of possible scales, from the finest scale determined by the grid resolution up to the broadest scale possible, determined by the spatial extent of the input DEM. Often, a better approach is to use this tool to create multiple scale mosaics spanning this range, thereby capturing variation within broadly defined scale ranges. For example, one could create a local-scale, meso-scale, and broad-scale curvature scale mosaics, each of which would capture topographic variation and landforms that are present in the landscape and reflective of processing operating at vastly different spatial scales. When this approach is used, it may not be necessary to standardize each scaled curvature raster, since the gradual decline in curvature values as scales increase is less pronounced within each of these broad scale ranges than across the entirety of possible scale-space. Again, however, this will depend on the application and on the characteristics of the landscape at study.

Raw curvedness values are often challenging to visualize given their range and magnitude, and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

See Also: GaussianScaleSpace, AccumulationCurvature, Curvedness, DifferenceCurvature, GaussianCurvature, GeneratingFunction, HorizontalExcessCurvature, MaximalCurvature, MeanCurvature, MinimalCurvature, PlanCurvature, ProfileCurvature, RingCurvature, Rotor, ShapeIndex, TangentialCurvature, TotalCurvature, Unsphericity, VerticalExcessCurvature

Parameters:

FlagDescription
-i, --input, --demName of the input raster DEM file
--curv_typeCurvature type
--out_magOutput raster magnitude file
--out_scaleOutput raster scale file
--min_scaleMinimum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer
--num_stepsNumber of steps
--step_nonlinearityStep nonlinearity factor (1.0-2.0 is typical)
--logDisplay output values using a log-scale
--standardizeShould each scale be standardized to z-scores?

Python function:

wbt.multiscale_curvatures(
    dem, 
    out_mag, 
    curv_type="ProfileCurv", 
    out_scale=None, 
    min_scale=0, 
    step=1, 
    num_steps=1, 
    step_nonlinearity=1.0, 
    log=True, 
    standardize=False, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=MultiscaleCurvatures --dem=dem.tif ^
--curv_type='Unsphericity' --out_mag=curv.tif --min_scale=10.0 ^
--log 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 28/11/2022

Last Modified: 28/11/2022

MultiscaleElevationPercentile

This tool calculates the most elevation percentile (EP) across a range of spatial scales. EP is a measure of local topographic position (LTP) and expresses the vertical position for a digital elevation model (DEM) grid cell (z0) as the percentile of the elevation distribution within the filter window, such that:

EP = counti∈C(zi > z0) x (100 / nC)

where z0 is the elevation of the window's center grid cell, zi is the elevation of cell i contained within the neighboring set C, and nC is the number of grid cells contained within the window.

EP is unsigned and expressed as a percentage, bound between 0% and 100%. This tool outputs two rasters, the multiscale EP magnitude (--out_mag) and the scale at which the most extreme EP value occurs (--out_scale). The magnitude raster is the most extreme EP value (i.e. the furthest from 50%) for each grid cell encountered within the tested scales of EP.

Quantile-based estimates (e.g., the median and interquartile range) are often used in nonparametric statistics to provide data variability estimates without assuming the distribution is normal. Thus, EP is largely unaffected by irregularly shaped elevation frequency distributions or by outliers in the DEM, resulting in a highly robust metric of LTP. In fact, elevation distributions within small to medium sized neighborhoods often exhibit skewed, multimodal, and non-Gaussian distributions, where the occurrence of elevation errors can often result in distribution outliers. Thus, based on these statistical characteristics, EP is considered one of the most robust representation of LTP.

The algorithm implemented by this tool uses the relatively efficient running-histogram filtering algorithm of Huang et al. (1979). Because most DEMs contain floating point data, elevation values must be rounded to be binned. The --sig_digits parameter is used to determine the level of precision preserved during this binning process. The algorithm is parallelized to further aid with computational efficiency.

Experience with multiscale EP has shown that it is highly variable at shorter scales and changes more gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested scales, such that:

ri = rL + [step × (i - rL)]p

Where ri is the filter radius for step i and p is the nonlinear scaling factor (--step_nonlinearity) and a step size (--step) of step.

References:

Newman, D. R., Lindsay, J. B., and Cockburn, J. M. H. (2018). Evaluating metrics of local topographic position for multiscale geomorphometric analysis. Geomorphology, 312, 40-50.

Huang, T., Yang, G.J.T.G.Y. and Tang, G., 1979. A fast two-dimensional median filtering algorithm. IEEE Transactions on Acoustics, Speech, and Signal Processing, 27(1), pp.13-18.

See Also: ElevationPercentile, MaxElevationDeviation, MaxDifferenceFromMean

Parameters:

FlagDescription
-i, --demInput raster DEM file
--out_magOutput raster roughness magnitude file
--out_scaleOutput raster roughness scale file
--sig_digitsNumber of significant digits
--min_scaleMinimum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer
--num_stepsNumber of steps
--step_nonlinearityStep nonlinearity factor (1.0-2.0 is typical)

Python function:

wbt.multiscale_elevation_percentile(
    dem, 
    out_mag, 
    out_scale, 
    sig_digits=3, 
    min_scale=4, 
    step=1, 
    num_steps=10, 
    step_nonlinearity=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MultiscaleElevationPercentile -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --step=5 ^
--num_steps=100 --step_nonlinearity=1.5 

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:

FlagDescription
-i, --demInput raster DEM file
--out_magOutput raster roughness magnitude file
--out_scaleOutput raster roughness scale file
--min_scaleMinimum search neighbourhood radius in grid cells
--max_scaleMaximum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer

Python function:

wbt.multiscale_roughness(
    dem, 
    out_mag, 
    out_scale, 
    max_scale, 
    min_scale=1, 
    step=1, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MultiscaleRoughness -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5 

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:

FlagDescription
-i, --demInput raster DEM file
--pointsInput vector points file
-o, --outputOutput HTML file
--min_scaleMinimum search neighbourhood radius in grid cells
--max_scaleMaximum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer

Python function:

wbt.multiscale_roughness_signature(
    dem, 
    points, 
    output, 
    max_scale, 
    min_scale=1, 
    step=1, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MultiscaleRoughnessSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.shp ^
--output=roughness.html --min_scale=1 --max_scale=1000 ^
--step=5 

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 (rmax; --out_scale), for each grid cell in an input DEM (--dem). This serves as a multi-scale measure of surface roughness, or topographic complexity. The spherical standard deviation (σs) is a measure of the angular spread among n unit vectors and is defined as:

σs = √[-2ln(R / N)] × 180 / π

Where R is the resultant vector length and is derived from the sum of the x, y, and z components of each of the n normals contained within a filter kernel, which designates a tested spatial scale. Each unit vector is a 3-dimensional measure of the surface orientation and slope at each grid cell center. The maximum spherical standard deviation is:

σs max=max{σs(r):r=rL...rU},

Experience with roughness scale signatures has shown that σs max is highly variable at shorter scales and changes more gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested scales, such that:

ri = rL + [step × (i - rL)]p

Where ri is the filter radius for step i and p is the nonlinear scaling factor (--step_nonlinearity) and a step size (--step) of step.

Use the SphericalStdDevOfNormals tool if you need to calculate σs for a single scale.

Reference:

JB Lindsay, DR Newman, and A Francioni. 2019 Scale-Optimized Surface Roughness for Topographic Analysis. Geosciences, 9(322) doi: 10.3390/geosciences9070322.

See Also: SphericalStdDevOfNormals, MultiscaleStdDevNormalsSignature, MultiscaleRoughness

Parameters:

FlagDescription
-i, --demInput raster DEM file
--out_magOutput raster roughness magnitude file
--out_scaleOutput raster roughness scale file
--min_scaleMinimum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer
--num_stepsNumber of steps
--step_nonlinearityStep nonlinearity factor (1.0-2.0 is typical)

Python function:

wbt.multiscale_std_dev_normals(
    dem, 
    out_mag, 
    out_scale, 
    min_scale=1, 
    step=1, 
    num_steps=10, 
    step_nonlinearity=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MultiscaleStdDevNormals -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --step=5 ^
--num_steps=100 --step_nonlinearity=1.5 

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:

FlagDescription
-i, --demInput raster DEM file
--pointsInput vector points file
-o, --outputOutput HTML file
--min_scaleMinimum search neighbourhood radius in grid cells
--stepStep size as any positive non-zero integer
--num_stepsNumber of steps
--step_nonlinearityStep nonlinearity factor (1.0-2.0 is typical)

Python function:

wbt.multiscale_std_dev_normals_signature(
    dem, 
    points, 
    output, 
    min_scale=1, 
    step=1, 
    num_steps=10, 
    step_nonlinearity=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MultiscaleStdDevNormalsSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.shp ^
--output=roughness.html --min_scale=1 --step=5 --num_steps=100 ^
--step_nonlinearity=1.5 

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 DEVmax rasters of differing spatial scale ranges. Specifically, MultiscaleTopographicPositionImage takes three DEVmax magnitude rasters, created using the MaxElevationDeviation tool, as inputs. The three inputs should correspond to the elevation deviations in the local (--local), meso (--meso), and broad (--broad) scale ranges and will be forced into the blue, green, and red colour components of the colour composite output (--output) raster. The image lightness value (--lightness) controls the overall brightness of the output image, as depending on the topography and scale ranges, these images can appear relatively dark. Higher values result in brighter, more colourful output images.

The user may optionally specify a hillshade image. When specified, the hillshade will be used to provide a shaded-relief overlaid on top of the coloured multi-scale information, providing a very effective visualization. Any hillshade image may be used for this purpose, but we have found that multi-directional hillshade (MultidirectionalHillshade), and specifically those derived using the 360-degree option, can be most effective for this application. However, experimentation is likely needed to find the optimal for each unique data set.

The output images can take some training to interpret correctly and a detailed explanation can be found in Lindsay et al. (2015). Sites within the landscape that occupy prominent topographic positions, either low-lying or elevated, will be apparent by their bright colouring in the MTP image. Those that are coloured more strongly in the blue are promient at the local scale range; locations that are more strongly green coloured are promient at the meso scale; and bright reds in the MTP image are associated with broad-scale landscape prominence. Of course, combination colours are also possible when topography is elevated or low-lying across multiple scale ranges. For example, a yellow area would indicated a site of prominent topographic position across the meso and broadest scale ranges.

Reference:

Lindsay J, Cockburn J, Russell H. 2015. An integral image approach to performing multi-scale topographic position analysis. Geomorphology, 245: 51-61.

See Also: MaxElevationDeviation

Parameters:

FlagDescription
--localInput local-scale topographic position (DEVmax) raster file
--mesoInput meso-scale topographic position (DEVmax) raster file
--broadInput broad-scale topographic position (DEVmax) raster file
--hillshadeInput optional hillshade raster file. Note: a multi-directional (360-degree option) hillshade tends to work best in this application
-o, --outputOutput raster file
--lightnessImage lightness value (default is 1.2)

Python function:

wbt.multiscale_topographic_position_image(
    local, 
    meso, 
    broad, 
    output, 
    hillshade=None, 
    lightness=1.2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MultiscaleTopographicPositionImage -v ^
--wd="/path/to/data/" --local=DEV_local.tif --meso=DEV_meso.tif ^
--broad=DEV_broad.tif -o=output.tif --lightness=1.5 

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

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 product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).

This tool calculates the Yokoyama et al. (2002) topographic openness index from an input DEM (--input). Openness has two viewer perspectives, which correspond with positive and negative openness outputs (--pos_output and --neg_output). Positive values, expressing openness above the surface, are high for convex forms, whereas negative values describe this attribute below the surface and are high for concave forms. Openness is an angular value that is an average of the horizon angle in the eight cardinal directions to a maximum search distance (--dist), measured in grid cells. Openness rasters are best visualized using a greyscale palette.

Positive Openness:

Negative Openness:

References:

Yokoyama, R., Shirasawa, M., & Pike, R. J. (2002). Visualizing topography by openness: a new application of image processing to digital elevation models. Photogrammetric engineering and remote sensing, 68(3), 257-266.

See Also: Viewshed, HorizonAngle, TimeInDaylight, Hillshade

Parameters:

FlagDescription
-i, --inputName of the input raster DEM file
--pos_outputName of the positive openness output raster file
--neg_outputName of the negative openness output raster file
--distSearch distance, in grid cells

Python function:

wbt.openness(
    i, 
    pos_output, 
    neg_output, 
    dist=20, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=Openness --input=DEM.tif ^
--pos_output=positive_openness.tif ^
--neg_output=negative_openness.tif --dist=500 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 30/03/2021

Last Modified: 30/03/2021

PennockLandformClass

Tool can be used to perform a simple landform classification based on measures of slope gradient and curvature derived from a user-specified digital elevation model (DEM). The classification scheme is based on the method proposed by Pennock, Zebarth, and DeJong (1987). The scheme divides a landscape into seven element types, including: convergent footslopes (CFS), divergent footslopes (DFS), convergent shoulders (CSH), divergent shoulders (DSH), convergent backslopes (CBS), divergent backslopes (DBS), and level terrain (L). The output raster image will record each of these base element types as:

Element TypeCode
CFS1
DFS2
CSH3
DSH4
CBS5
DBS6
L7

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

PROFILEGRADIENTPLANElement
Concave ( -0.10)High >3.0Concave 0.0CFS
Concave ( -0.10)High >3.0Convex >0.0DFS
Convex (>0.10)High >3.0Concave 0.0CSH
Convex (>0.10)High >3.0Convex >0.0DSH
Linear (-0.10...0.10)High >3.0Concave 0.0CBS
Linear (-0.10...0.10)High >3.0Convex >0.0DBS
--Low 3.0--L

Where PROFILE is profile curvature, GRADIENT is the slope gradient, and PLAN is the plan curvature. Note that these values are likely landscape and data specific and can be adjusted by the user. Landscape classification schemes that are based on terrain attributes are highly sensitive to short-range topographic variability (i.e. roughness) and can benefit from pre-processing the DEM with a smoothing filter to reduce the effect of surface roughness and emphasize the longer-range topographic signal. The FeaturePreservingSmoothing tool offers excellent performance in smoothing DEMs without removing the sharpness of breaks-in-slope.

Reference:

Pennock, D.J., Zebarth, B.J., and DeJong, E. (1987) Landform classification and soil distribution in hummocky terrain, Saskatchewan, Canada. Geoderma, 40: 297-315.

See Also: FeaturePreservingSmoothing

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--slopeSlope threshold value, in degrees (default is 3.0)
--profProfile curvature threshold value (default is 0.1)
--planPlan curvature threshold value (default is 0.0)
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.pennock_landform_class(
    dem, 
    output, 
    slope=3.0, 
    prof=0.1, 
    plan=0.0, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PennockLandformClass -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif --slope=3.0 ^
--prof=0.1 --plan=0.0 

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

PER = z0 / (zmax - zmin) x 100

where z0 is the elevation of the window's center grid cell, zmax is the maximum neighbouring elevation, and zmin is the minimum neighbouring elevation.

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

FlagDescription
-i, --input, --demInput raster DEM file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.percent_elev_range(
    dem, 
    output, 
    filterx=3, 
    filtery=3, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 30/01/2020

PlanCurvature

This tool calculates the plan (or contour) curvature from a digital elevation model (DEM). Plan curvature is the curvature of a contour line at a given point on the topographic surface (Florinsky, 2017). This variable has an unbounded range that can take either positive or negative values. Positive values of the index are indicative of flow divergence while negative plan curvature values indicate flow convergence. Thus plan curvature is similar to tangential curvature, although the literature suggests that the latter is more numerically stable (Wilson, 2018). Plan curvature is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

Wilson, J. P. (2018). Environmental applications of digital terrain modeling. John Wiley & Sons.

TangentialCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature, MinimalCurvature, MaximalCurvature

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--logDisplay output values using a log-scale
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/06/2017

Last Modified: 12/01/2022

Profile

This tool can be used to plot the data profile, along a set of one or more vector lines (--lines), in an input (--surface) digital elevation model (DEM), or other surface model. The data profile plots surface height (y-axis) against distance along profile (x-axis). The tool outputs an interactive SVG line graph embedded in an HTML document (--output). If the vector lines file contains multiple line features, the output plot will contain each of the input profiles.

If you want to extract the longitudinal profile of a river, use the LongProfile tool instead.

See Also: LongProfile, HypsometricAnalysis

Parameters:

FlagDescription
--linesInput vector line file
--surfaceInput raster surface file
-o, --outputOutput HTML file

Python function:

wbt.profile(
    lines, 
    surface, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Profile -v --wd="/path/to/data/" ^
--lines=profile.shp --surface=dem.tif -o=profile.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/02/2018

Last Modified: 12/10/2018

ProfileCurvature

This tool calculates the profile (or vertical) curvature, or the rate of change in slope along a flow line, from a digital elevation model (DEM). It is the curvature of a normal section having a common tangent line with a slope line at a given point on the surface (Florinsky, 2017). This variable has an unbounded range that can take either positive or negative values. Positive values of the index are indicative of flow acceleration while negative profile curvature values indicate flow deceleration. Profile curvature is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

PlanCurvature, TangentialCurvature, MeanCurvature, GaussianCurvature, MinimalCurvature, MaximalCurvature

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--logDisplay output values using a log-scale
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/062017

Last Modified: 15/01/2022

RelativeAspect

This tool creates a new raster in which each grid cell is assigned the terrain aspect relative to a user-specified direction (--azimuth). Relative terrain aspect is the angular distance (measured in degrees) between the land-surface aspect and the assumed regional wind azimuth (Bohner and Antonic, 2007). It is bound between 0-degrees (windward direction) and 180-degrees (leeward direction). Relative terrain aspect is the simplest of the measures of topographic exposure to wind, taking into account terrain orientation only and neglecting the influences of topographic shadowing by distant landforms and the deflection of wind by topography.

The user must specify the name of a digital elevation model (DEM) (--dem) and an azimuth (i.e. a wind direction). The Z Conversion Factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. 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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--azimuthIllumination source azimuth
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.relative_aspect(
    dem, 
    output, 
    azimuth=0.0, 
    zfactor=None, 
    callback=default_callback
)

Command-line Interface:

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

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

RTP = (z0 − μ) / (μ − zmin), if z0 < μ

OR

RTP = (z0 − μ) / (zmax - μ), if z0 >= μ 

The resulting index is bound by the interval [−1, 1], where the sign indicates if the cell is above or below than the filter mean. Although RTP uses the mean to define two linear functions, the reliance on the filter extrema is expected to result in sensitivity to outliers. Furthermore, the use of the mean implies assumptions of unimodal and symmetrical elevation distribution.

In many cases, Elevation Percentile (ElevPercentile) and deviation from mean elevation (DevFromMeanElev) provide more suitable and robust measures of relative topographic position.

Reference:

Newman, D. R., Lindsay, J. B., and Cockburn, J. M. H. (2018). Evaluating metrics of local topographic position for multiscale geomorphometric analysis. Geomorphology, 312, 40-50.

See Also: DevFromMeanElev, DiffFromMeanElev, ElevPercentile, PercentElevRange

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.relative_topographic_position(
    dem, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

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

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:

FlagDescription
-i, --input, --demInput raster DEM file
-o, --outputOutput raster file
--filterFilter size (cells)
--slopeSlope threshold value

Python function:

wbt.remove_off_terrain_objects(
    dem, 
    output, 
    filter=11, 
    slope=15.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RemoveOffTerrainObjects -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=bare_earth_DEM.tif ^
--filter=25 --slope=10.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/06/2017

Last Modified: 07/08/2020

RingCurvature

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

This tool calculates the ring curvature, which is the product of horizontal excess and vertical excess curvatures (Shary, 1995), from a digital elevation model (DEM). Like Rotor, ring curvature is used to measure flow line twisting. Ring curvature has values equal to or greater than zero and is measured in units of m-2.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

See Also:

Rotor, MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature, ProfileCurvature, TangentialCurvature

Parameters:

FlagDescription
-i, --demName of the input raster DEM file
-o, --outputName of the output raster image file
--logDisplay output values using a log-scale
--zfactorZ conversion factor

Python function:

wbt.ring_curvature(
    dem, 
    output, 
    log=False, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RingCurvature -i=DEM.tif -o=output.tif ^
--log 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 11/01/2022

Last Modified: 28/11/2022

Rotor

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

This tool calculates the spatial pattern of rotor, which describes the degree to which a flow line twists (Shary, 1991), from a digital elevation model (DEM). Rotor has an unbounded range, with positive values indicating that a flow line turns clockwise and negative values indicating flow lines that turn counter clockwise (Florinsky, 2017). Rotor is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary PA (1991) The second derivative topographic method. In: Stepanov IN (ed) The Geometry of the Earth Surface Structures. Pushchino, USSR: Pushchino Research Centre Press, 30–60 (in Russian).

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

See Also:

RingCurvature, ProfileCurvature, TangentialCurvature, PlanCurvature, MeanCurvature, GaussianCurvature, MinimalCurvature, MaximalCurvature

Parameters:

FlagDescription
-i, --demName of the input raster DEM file
-o, --outputName of the output raster image file
--logDisplay output values using a log-scale
--zfactorZ conversion factor

Python function:

wbt.rotor(
    dem, 
    output, 
    log=False, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=Rotor -i=DEM.tif -o=output.tif --log



Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 08/01/2022

Last Modified: 28/11/2022

RuggednessIndex

The terrain ruggedness index (TRI) is a measure of local topographic relief. The TRI calculates the root-mean-square-deviation (RMSD) for each grid cell in a digital elevation model (DEM), calculating the residuals (i.e. elevation differences) between a grid cell and its eight neighbours. Notice that, unlike the output of this tool, the original Riley et al. (1999) TRI did not normalize for the number of cells in the local window (i.e. it is a root-square-deviation only). However, using the mean has the advantage of allowing for the varying number of neighbouring cells along the grid edges and in areas bordering NoData cells. This modification does however imply that the output of this tool cannot be directly compared with the index ranges of level to extremely rugged terrain provided in Riley et al. (1999)

Reference:

Riley, S. J., DeGloria, S. D., and Elliot, R. (1999). Index that quantifies topographic heterogeneity. Intermountain Journal of Sciences, 5(1-4), 23-27.

See Also: RelativeTopographicPosition, DevFromMeanElev

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

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 (As, i.e. the upslope contributing area per unit contour length; --sca) and slope gradient (β, measured in degrees; --slope) rasters. Moore et al. (1991) state that the physical potential for sheet and rill erosion in upland catchments can be evaluated by the product R K LS, a component of the Universal Soil Loss Equation (USLE), where R is a rainfall and runoff erosivity factor, K is a soil erodibility factor, and LS is the length-slope factor that accounts for the effects of topography on erosion. To predict erosion at a point in the landscape the LS factor can be written as:

LS = (n + 1)(As / 22.13)n(sin(β) / 0.0896)m

where n = 0.4 (--sca_exponent) and m = 1.3 (--slope_exponent) in its original formulation.

This index is derived from unit stream-power theory and is sometimes used in place of the length-slope factor in the revised universal soil loss equation (RUSLE) for slope lengths less than 100 m and slope less than 14 degrees. Like many hydrological land-surface parameters SedimentTransportIndex assumes that contributing area is directly related to discharge. Notice that As must not be log-transformed prior to being used; As is commonly log-transformed to enhance visualization of the data. Also, As can be derived using any of the available flow accumulation tools, alghough better results usually result from application of multiple-flow direction algorithms such as DInfFlowAccumulation and FD8FlowAccumulation. The slope raster can be created from the base digital elevation model (DEM) using the Slope tool. The input images must have the same grid dimensions.

Reference:

Moore, I. D., Grayson, R. B., and Ladson, A. R. (1991). Digital terrain modelling: a review of hydrological, geomorphological, and biological applications. Hydrological processes, 5(1), 3-30.

See Also: StreamPowerIndex, DInfFlowAccumulation, FD8FlowAccumulation

Parameters:

FlagDescription
--scaInput raster specific contributing area (SCA) file
--slopeInput raster slope file
-o, --outputOutput raster file
--sca_exponentSCA exponent value
--slope_exponentSlope exponent value

Python function:

wbt.sediment_transport_index(
    sca, 
    slope, 
    output, 
    sca_exponent=0.4, 
    slope_exponent=1.3, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SedimentTransportIndex -v ^
--wd="/path/to/data/" --sca='flow_accum.tif' ^
--slope='slope.tif' -o=output.tif --sca_exponent=0.5 ^
--slope_exponent=1.0 

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 product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).

This tool creates an interactive animated GIF of shadows based on an input digital surface model (DSM). The shadow model is based on the modelled positions of the sun throughout a user-specified date (--date) sampling at a regular interval (--interval), in minutes. Similar to the TimeInDaylight tool, this tool uses calculated horizon angle (HorizonAngle) values and a solar position model to determine which grid cells are located in shadow areas due to distant obsticles. The calculation of horizon angle, requires the user input a maximum search distance parameter (--max_dist).

The location parameter (--location) should take the form Lat/Long/UTC-offset, e.g. 43.5448/-80.2482/-4/. Note, the location need only be approximate; the postion of the central location of the input DSM raster should suffice.

The output (--output) of this tool is an HTML file, containing the interactive GIF animation. Users are able to zoom and pan around the displayed DEV animation. The DSM may be rendered in one of several available palettes (--palette) suitable for visualization topography. The user must also specify the image height (--height) in the output file, the time delay (--delay, in milliseconds) used in the GIF animation, and an optional label (--label), which will appear in the upper lefthand corner. Note that the output is simply HTML, CSS, javascript code, and a GIF file, which can be readily embedded in other documents.

Users should be aware that the outut GIF can be very large in size, depending on the size of the input DEM file. To reduce the file size of the output, it may be desirable to coarsen the input DEM resolution using image resampling (Resample).

The following is an example of what the output of this tool looks like. Click the image for an interactive example.

For more information about this tool, see this blog on the WhiteboxTools homepage.

See Also: ShadowImage, TimeInDaylight, HorizonAngle, LidarDigitalSurfaceModel

Parameters:

FlagDescription
-i, --inputName of the input digital surface model (DSM) raster file
-p, --paletteDSM image palette; options are 'atlas', 'high_relief', 'arid', 'soft', 'muted', 'light_quant', 'purple', 'viridis', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', and 'none'
-o, --outputName of the output HTML file (*.html)
--max_distOptional maximum search distance, in xy units. Minimum value is 5 x cell size
-d, --dateDate in format DD/MM/YYYY
--intervalTime interval, in minutes (1-60)
--locationLocation, defined as Lat/Long/UTC-offset (e.g. 43.5448/-80.2482/-4)
-h, --heightImage height, in pixels
--delayGIF time delay in milliseconds
-l, --labelLabel text (leave blank for none)

Python function:

wbt.shadow_animation(
    i, 
    output, 
    palette="atlas", 
    max_dist="", 
    date="21/06/2021", 
    interval=15, 
    location="43.5448/-80.2482/-4", 
    height=600, 
    delay=250, 
    label="", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ShadowAnimation -i=dsm.tif ^
-p='high_relief' -o=shadow_animation.html --max_dist=500 ^
--date='21/06/2021' --interval=20 --location='43.55/ -80.25/ ^
-4' --height=620 --delay=200 --label='Shadow Animation' 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 01/05/2021

Last Modified: 01/05/2021

ShadowImage

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

This tool generates a raster of shadow areas based on an input digital surface model (DSM). This shadow model is based on the calculated positions of the sun throughout a user-specified date (--date), sampling at a regular interval (--interval), in minutes. Similar to the TimeInDaylight tool, this tool uses calculated horizon angle (HorizonAngle) values and a solar position model to determine which grid cells are located in shadow areas due to distant obsticles. The calculation of horizon angle, requires the user input a maximum search distance parameter (--max_dist).

The user must specify the date (--date), time (--time), and location (--location) of the input DSM. The date should have the format DD/MM/YYYY, e.g. 27/11/1976. The time should have the format HH::MM, e.g. 03:15AM or 14:30. The location parameter should take the form Lat/Long/UTC-offset, e.g. 43.5448/-80.2482/-4/. Note, the location need only be approximate; the postion of the central location of the input DSM raster should suffice.

The output (--output) of this tool is a raster. If a palette (--palette) is chosen, then the output raster will be a colour composite image, containing a hysometrically tinted (i.e. elevation coloured) shadow model. The DSM may be rendered in one of several available palettes (--palette) suitable for visualization topography. If the palette is set to 'none', the output image will not be a colour composite, but rather, will be a 16-bit integer raster, and should be displayed in a grey-scale palette.

The following is an example of what the output of this tool looks like.

For more information about this tool, see this blog on the WhiteboxTools homepage.

See Also: ShadowAnimation, TimeInDaylight, HorizonAngle, LidarDigitalSurfaceModel, HypsometricallyTintedHillshade

Parameters:

FlagDescription
-i, --inputName of the input digital surface model (DSM) raster file
-p, --paletteDSM image palette; options are 'atlas', 'high_relief', 'arid', 'soft', 'muted', 'light_quant', 'purple', 'viridi', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', and 'none'
-o, --outputName of the output raster file
--max_distOptional maximum search distance, in xy unites. Minimum value is 5 x cell size
-d, --dateDate in format DD/MM/YYYY
-t, --timeTime in format HH::MM, e.g. 03:15AM or 14:30
--locationLocation, defined as Lat/Long/UTC-offset (e.g. 43.5448/-80.2482/-4)

Python function:

wbt.shadow_image(
    i, 
    output, 
    palette="soft", 
    max_dist="", 
    date="21/06/2021", 
    time="13:00", 
    location="43.5448/-80.2482/-4", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ShadowImage -i=dsm.tif ^
-p='high_relief' -o=shadow_animation.html --max_dist=500 ^
--date='21/06/2021' --time='14:30' --location='43.55/ -80.25/ ^
-4' 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 08/06/2021

Last Modified: 13/06/2021

ShapeIndex

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

This tool calculates the shape index (Koenderink and van Doorn, 1992) from a digital elevation model (DEM). This variable ranges from -1 to 1, with positive values indicative of convex landforms, negative values corresponding to concave landforms (Florinsky, 2017). Absolute values from 0.5 to 1.0 are associated with elliptic surfaces (hills and closed depressions), while absolute values from 0.0 to 0.5 are typical of hyperbolic surface form (saddles). Shape index is a dimensionless variable and has utility in landform classification applications.

Koenderink and vsn Doorn (1992) make the following observations about the shape index:

  • Two shapes for which the shape index differs merely by sign represent complementary pairs that will fit together as ‘stamp’ and ‘mould’ when suitably scaled;

  • The shape for which the shape index vanishes - and consequently has indeterminate sign - represents the objects which are congruent to their own moulds;

  • Convexities and concavities find their places on opposite sides of the shape scale. These basic shapes are separated by those shapes which are neither convex nor concave, that are the saddle-like objects. The transitional shapes that divide the convexities/concavities from the saddle-shapes are the cylindrical ridge and the cylindrical rut.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Koenderink, J. J., and Van Doorn, A. J. (1992). Surface shape and curvature scales. Image and vision computing, 10(8), 557-564.

Curvedness, MinimalCurvature, MaximalCurvature, TangentialCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demName of the input raster DEM file
-o, --outputName of the output raster image file
--zfactorZ conversion factor

Python function:

wbt.shape_index(
    dem, 
    output, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ShapeIndex -i=DEM.tif -o=output.tif



Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 13/01/2022

Last Modified: 28/11/2022

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. When this is the case, the algorithm will multiply each elevation in the DEM by the Z conversion factor.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

Reference:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

See Also: Aspect, TangentialCurvature, PlanCurvature, ProfileCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--zfactorOptional multiplier for when the vertical and horizontal units are not the same
--unitsUnits of output raster; options include 'degrees', 'radians', 'percent'

Python function:

wbt.slope(
    dem, 
    output, 
    zfactor=None, 
    units="degrees", 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 15/01/2022

SlopeVsAspectPlot

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

This tool creates a slope vs. aspect plot for an input digital elevation model, or DEM (--input). Similar to a slope vs. elevation analysis (SlopeVsElevationPlot), the slope-aspect relation can reveal the basic topographic character of a site. The output of this analysis is an HTML document (--output) that contains the slope-aspect chart, which is a radial line plot. The plot displays the median and interquartile range of slope values for the range of aspect values from 0 - 360 degrees. In reality, the aspect range is binned and the user must specify the bin size (--bin_size). As slopes becomes quite shallow, the numerical instability in aspect becomes apparent, due to the relatively small signal-to-noise ratio in these areas of the input DEM. These shallow-gradient grid cells can have an out-sized impact on the shape of the slope-aspect relation. Therefore, users can specify to ignore slopes less than a certain threshold minimum slope (--min_slope).

In interpreting the slope-aspect plots output by this tool, users should take note of asymmetries in polygonal paths taken by the percentile slope values, asymmetries in the range of slopes (i.e. the interquartile range), and anisotropy patterns (i.e. non-circularity or oval-shaped patterns). For example, asymmetries in the patterns may be indicative of landscape processes of interest, such as the differential energy balances experienced by north- and south-facing slopes at high latitudes. Increased rates of weathering on slopes with more direct sunlight at higher latitudes can result in flatter hillslopes. Asymmetry in the slope-aspect relation may also be indicative of DEM error and can be used as a quality control procedure, particularly for InSAR DEMs. Anisotropy in the slope-aspect relation may indicate a characteristic of the bedrock geology or the drainage structure of the landscape. The tool will also output the elongation ratio, a measure of anisotropy, of the mapped percentile polygons in a table.

The following are some examples of the output plots. In actuality, the outputs of the tool are interactive plots.

You may wish to smooth your DEM prior to analysis with this tool, in order to emphasis longer-scale patterns in the landscape. We would recommend using a method such as the FeaturePreservingSmoothing tool for this purpose.

The Z conversion factor (--z_factor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z conversion factor. If the DEM is in the geographic coordinate system (latitude and longitude), the following equation is used:

zfactor = 1.0 / (111320.0 x cos(mid_lat))

where mid_lat is the latitude of the centre of each raster row, in radians.

See Also: SlopeVsElevationPlot, FeaturePreservingSmoothing

Parameters:

FlagDescription
-i, --inputName of the input raster image file
-o, --outputName of the output report file (*.html)
--bin_sizeAspect bin size, in degrees
--min_slopeMinimum slope, in degrees
--zfactorZ conversion factor

Python function:

wbt.slope_vs_aspect_plot(
    i, 
    output, 
    bin_size=2.0, 
    min_slope=0.1, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=SlopeVsAspectPlot --input="DEM.tif" ^
-o=slope_aspect_plot.html --bin_size=4.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 17/09/2021

Last Modified: 17/09/2021

SlopeVsElevationPlot

This tool can be used to create a slope versus average elevation plot for one or more digital elevation models (DEMs). Similar to a hypsometric analysis (HypsometricAnalysis), the slope-elevation relation can reveal the basic topographic character of a site. The output of this analysis is an HTML document (--output) that contains the slope-elevation chart. The tool can plot multiple slope-elevation analyses on the same chart by specifying multiple input DEM files (--inputs). Each input DEM can have an optional watershed in which the slope-elevation analysis is confined by specifying the optional --watershed flag. If multiple input DEMs are used, and a watershed is used to confine the analysis to a sub-area, there must be the same number of input raster watershed files as input DEM files. The order of the DEM and watershed files must the be same (i.e. the first DEM file must correspond to the first watershed file, the second DEM file to the second watershed file, etc.). Each watershed file may contain one or more watersheds, designated by unique identifiers.

See Also: HypsometricAnalysis, SlopeVsAspectPlot

Parameters:

FlagDescription
-i, --inputsInput DEM files
--watershedInput watershed files (optional)
-o, --outputOutput HTML file (default name will be based on input file if unspecified)

Python function:

wbt.slope_vs_elevation_plot(
    inputs, 
    output, 
    watershed=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SlopeVsElevationPlot -v ^
--wd="/path/to/data/" -i="DEM1.tif;DEM2.tif" ^
--watershed="ws1.tif;ws2.tif" -o=outfile.html 

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 product. Please visit Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com/extension-pricing/).

This tool can smooth the roughness due to residual vegetation cover in LiDAR digital elevation models (DEMs). Sometimes when LiDAR data are collected under heavy forest cover, particularly conifer species, the DEM will contain substantial roughness, even if it is interpolated using last-return points only. This tool can be used to reduce the roughness of the ground surface under these conditions. It works by identifying grid cells that possess deviation in mean elevation (DEV, DevFromMeanElev) values that are higher than a specified threshold value (--dev_threshold) for tested scales less than a specified threshold (--scale_threshold). DEV is measured for the input DEM (--input) using filter radii from 1 to a user-specified maximum (--max_scale). The identified grid cells are then masked out and their elevations are re-interpolated using the surrounding, non-masked values.

This method can work well under some conditions, and will further benefit from multiple passes of the tool, i.e. run the tool using one set of parameters and then use the output (--output) as the input for the second pass. Alternative approaches include use of the RemoveOffTerrainObjects tool, using low-pass filters such as the FeaturePreservingSmoothing tool, or, if the point-cloud source data are available, classifying the ground points using LidarGroundPointFilter and excluding non-ground points from the interpolation.

The following image shows an image of a DEM that is badly impacted by heavy forest cover, with obvious vegetation residual roughness.

This image shows the impact of two-passes of the SmoothVegetationResidual tool.

See Also: RemoveOffTerrainObjects, FeaturePreservingSmoothing, LidarGroundPointFilter, DevFromMeanElev

Parameters:

FlagDescription
-i, --inputName of the input digital elevation model (DEM) raster file
-o, --outputName of the output raster file
--max_scaleMaximum search neighbourhood radius in grid cells
--dev_thresholdDEVmax Threshold
--scale_thresholdDEVmax scale threshold

Python function:

wbt.smooth_vegetation_residual(
    i, 
    output, 
    max_scale=30, 
    dev_threshold=1.0, 
    scale_threshold=5, 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=SmoothVegetationResidual -i=DEM.tif ^
-o=smoothed_DEM.tif --max_scale=50 --dev_threshold=0.5 ^
--scale_threshold=8 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 09/05/2021

Last Modified: 09/05/2021

SphericalStdDevOfNormals

This tool can be used to calculate the spherical standard deviation of the distribution of surface normals for an input digital elevation model (DEM; --dem). This is a measure of the angular dispersion of the surface normal vectors within a local neighbourhood of a specified size (--filter). SphericalStdDevOfNormals is therefore a measure of surface shape complexity, texture, and roughness. The spherical standard deviation (s) is defined as:

s = √[-2ln(R / N)] × 180 / π

where R is the resultant vector length and N is the number of unit normal vectors within the local neighbourhood. s is measured in degrees and is zero for simple planes and increases infinitely with increasing surface complexity or roughness. Note that this formulation of the spherical standard deviation assumes an underlying wrapped normal distribution.

The local neighbourhood size (--filter) must be any odd integer equal to or greater than three. Grohmann et al. (2010) found that vector dispersion, a related measure of angular dispersion, increases monotonically with scale. This is the result of the angular dispersion measure integrating (accumulating) all of the surface variance of smaller scales up to the test scale. A more interesting scale relation can therefore be estimated by isolating the amount of surface complexity associated with specific scale ranges. That is, at large spatial scales, s should reflect the texture of large-scale landforms rather than the accumulated complexity at all smaller scales, including microtopographic roughness. As such, this tool normalizes the surface complexity of scales that are smaller than the filter size by applying Gaussian blur (with a standard deviation of one-third the filter size) to the DEM prior to calculating R. In this way, the resulting distribution is able to isolate and highlight the surface shape complexity associated with landscape features of a similar scale to that of the filter size.

This tool makes extensive use of integral images (i.e. summed-area tables) and parallel processing to ensure computational efficiency. It may, however, require substantial memory resources when applied to larger DEMs.

References:

Grohmann, C. H., Smith, M. J., & Riccomini, C. (2010). Multiscale analysis of topographic surface roughness in the Midland Valley, Scotland. IEEE Transactions on Geoscience and Remote Sensing, 49(4), 1200-1213.

Hodgson, M. E., and Gaile, G. L. (1999). A cartographic modeling approach for surface orientation-related applications. Photogrammetric Engineering and Remote Sensing, 65(1), 85-95.

Lindsay J. B., Newman* D. R., Francioni, A. 2019. Scale-optimized surface roughness for topographic analysis. Geosciences, 9(7) 322. DOI: 10.3390/geosciences9070322.

See Also: CircularVarianceOfAspect, MultiscaleRoughness, EdgeDensity, SurfaceAreaRatio, RuggednessIndex

Parameters:

FlagDescription
-i, --demInput raster DEM file
--outputOutput raster file
--filterSize of the filter kernel

Python function:

wbt.spherical_std_dev_of_normals(
    dem, 
    output, 
    filter=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SphericalStdDevOfNormals -v ^
--wd="/path/to/data/" --dem=DEM.tif --output=roughness.tif ^
--filter=15 

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:

FlagDescription
-i, --inputInput raster DEM file
-o, --outputOutput raster DEM file
--zfactorOptional multiplier for when the vertical and horizontal units are not the same
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.standard_deviation_of_slope(
    i, 
    output, 
    zfactor=None, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=StandardDeviationOfSlope -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--zfactor=1.0 --filterx=15 --filtery=15 

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

RSP = Asp × tan(β)

where As is the specific catchment area (i.e. the upslope contributing area per unit contour length) estimated using one of the available flow accumulation algorithms; β is the local slope gradient in degrees (--slope); and, p (--exponent) is a user-defined exponent term that controls the location-specific relation between contributing area and discharge. Notice that As must not be log-transformed prior to being used; As is commonly log-transformed to enhance visualization of the data. The slope raster can be created from the base digital elevation model (DEM) using the Slope tool. The input images must have the same grid dimensions.

Reference:

Moore, I. D., Grayson, R. B., and Ladson, A. R. (1991). Digital terrain modelling: a review of hydrological, geomorphological, and biological applications. Hydrological processes, 5(1), 3-30.

See Also: SedimentTransportIndex, Slope, D8FlowAccumulation DInfFlowAccumulation, FD8FlowAccumulation

Parameters:

FlagDescription
--scaInput raster specific contributing area (SCA) file
--slopeInput raster slope file
-o, --outputOutput raster file
--exponentSCA exponent value

Python function:

wbt.stream_power_index(
    sca, 
    slope, 
    output, 
    exponent=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=StreamPowerIndex -v ^
--wd="/path/to/data/" --sca='flow_accum.tif' ^
--slope='slope.tif' -o=output.tif --exponent=1.1 

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:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 23/01/2019

Last Modified: 23/01/2019

TangentialCurvature

This tool calculates the tangential (or horizontal) curvature, which is the curvature of an inclined plane perpendicular to both the direction of flow and the surface (Gallant and Wilson, 2000). Alternatively, it could be described as the curvature of a normal section tangential to a contour line at a given point of the topographic surface (Florinsky, 2017). This variable has an unbounded range that can be either positive or negative. Positive values are indicative of flow divergence while negative tangential curvature values indicate flow convergence. Thus tangential curvature is similar to plan curvature, although the literature suggests that the former is more numerically stable (Wilson, 2018). Tangential curvature is measured in units of m-1.

The user must specify the name of the input digital elevation model (DEM) (--dem) and the output raster (--output). The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

Wilson, J. P. (2018). Environmental applications of digital terrain modeling. John Wiley & Sons.

PlanCurvature, ProfileCurvature, TotalCurvature, Slope, Aspect

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--logDisplay output values using a log-scale
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 15/01/2022

TimeInDaylight

This tool calculates the proportion of time a location is within daylight. That is, it calculates the proportion of time, during a user-defined time frame, that a grid cell in an input digital elevation model (--dem) is outside of an area of shadow cast by a local object. The input DEM should truly be a digital surface model (DSM) that contains significant off-terrain objects. Such a model, for example, could be created using the first-return points of a LiDAR data set, or using the LidarDigitalSurfaceModel tool.

The tool operates by calculating a solar almanac, which estimates the sun's position for the location, in latitude and longitude coordinate (--lat, --long), of the input DSM. The algorithm then calculates horizon angle (see HorizonAngle) rasters from the DSM based on the user-specified azimuth fraction (--az_fraction). For example, if an azimuth fraction of 15-degrees is specified, horizon angle rasters could be calculated for the solar azimuths 0, 15, 30, 45... In reality, horizon angle rasters are only calculated for azimuths for which the sun is above the horizon for some time during the tested time period. A horizon angle raster evaluates the vertical angle between each grid cell in a DSM and a distant obstacle (e.g. a mountain ridge, building, tree, etc.) that blocks the view along a specified direction. In calculating horizon angle, the user must specify the maximum search distance (--max_dist) beyond which the query for higher, more distant objects will cease. This parameter strongly impacts the performance of the tool, with larger values resulting in significantly longer run-times. Users are advised to set the --max_dist based on the maximum shadow length expected in an area. For example, in a relatively flat urban landscape, the tallest building will likely determine the longest shadow lengths. All grid cells for which the calculated solar positions throughout the time frame are higher than the cell's horizon angle are deemed to be illuminated during the time the sun is in the corresponding azimuth fraction.

By default, the tool calculates time-in-daylight for a time-frame spanning an entire year. That is, the solar almanac is calculated for each hour, at 10-second intervals, and for each day of the year. Users may alternatively restrict the time of year over which time-in-daylight is calculated by specifying a starting day (1-365; --start_day) and ending day (1-365; --end_day). Similarly, by specifying start time (--start_time) and end time (--end_time) parameters, the user is able to measure time-in-daylight for specific ranges of the day (e.g. for the morning or afternoon hours). These time parameters must be specified in 24-hour time (HH:MM:SS), e.g. 15:30:00. sunrise and sunset are also acceptable inputs for the start time and end time respectively. The timing of sunrise and sunset on each day in the tested time-frame will be determined using the solar almanac.

See Also: LidarDigitalSurfaceModel, HorizonAngle

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--az_fractionAzimuth fraction in degrees
--max_distOptional maximum search distance. Minimum value is 5 x cell size
--latCentre point latitude
--longCentre point longitude
--utc_offsetUTC time offset, in hours (e.g. -04:00, +06:00)
--start_dayStart day of the year (1-365)
--end_dayEnd day of the year (1-365)
--start_timeStarting hour to track shadows (e.g. 5, 5:00, 05:00:00). Assumes 24-hour time: HH:MM:SS. 'sunrise' is also a valid time
--end_timeEnding hour to track shadows (e.g. 21, 21:00, 21:00:00). Assumes 24-hour time: HH:MM:SS. 'sunset' is also a valid time

Python function:

wbt.time_in_daylight(
    dem, 
    output, 
    lat, 
    long, 
    az_fraction=10.0, 
    max_dist=100.0, 
    utc_offset="00:00", 
    start_day=1, 
    end_day=365, 
    start_time="00:00:00", 
    end_time="23:59:59", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=TimeInDaylight -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif --az_fraction=15.0 ^
--max_dist=100.0 --lat=43.545 --long= -80.248 

Source code on GitHub

Author: Dr. John Lindsay

Created: 29/07/2020

Last Modified: 03/09/2020

TopoRender

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

This tool is used to create pseudo-3D rendering from an input DEM, for the purpose of effective topographic visualization. The tool simulated direct radiation, diffuse radiation, and light attenuation to create an effective topographic visualization. The user must specify the input digital elevation model (--dem) and output (--output) file names. One of several named palettes (--palette) may also be chosen, including 'atlas', 'high_relief', 'arid', 'soft', 'earthtones', 'muted', 'light_quant', 'purple', 'viridi', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', 'imhof', and 'white'. The user may optionally reverse the palette (--rev_palette), although this will generally not be required since the palettes are designed to work well with topographic data as they are.

The user must also specify a number of parameters related to the lighting of the surface. These include the light source direciton (--az; 0-360) and altitude (--alt; 0-90), both of which describe the 3D light source location in decimal degrees. The light attenuation (--attenuation) describes the rate at which the light dims away from the source, effectively applying a gradient across the image. Values of this parameter range from 0-1, with appropriate values in the 0.0 (no attenuation) to 0.7 range. The ambient light parameter (--ambient_light) is used to describe how much background (diffuse) light there is, which allows for details to be discernable within shadow areas. Values of this parameter also range from 0-1, although generally much lower values ~0.2, produce good results. Experimentation with each of the lighting parameter values may be needed to create a final map.

The resulting output image will have shadows cast beyond the original input DEM's grid, futher creating the illusion of a 3D surface suspended above a background plane (see examples below). The user may accentuate this effect by setting the vertical distance between the topographic surface and the plane (--background_hgt_offset). Larger values of this parameter will result in a greater distance, and the parameter values are in the z-units of the input DEM. If the DEM contains NoData values, these sites will appear to cut through to the background plane. In fact, the user may optionally include a clipping polygon (--polygon) and only the parts of the DEM that are within this polygon will be displayed. This is useful if, for example, you wish to render an individual watershed. The user may specify the colour of the background plane (--background_clr), as a string of RGB or RGBA values, e.g. '[255, 240, 200, 255]'. The default colour is white, which may appear slightly greyed if a non-zero light attentuation value is specified.

Lastly, the user must specify an elevation multiplier (--z_factor) parameter, with a default of 1.0. This can be useful for applying a vertical exageration (values greater than 1.0) to the elevation surface for enchanced topographic relief. This may be important when applying this tool in relatively low-to-moderate relief locations, or when applying it to very large spatial extents. Please note, this tool is suitable for applying to DEMs in geographic coordinates (latitude and longitude) or projected coordinate systems.

The image that is created by this tool is a GeoTiff and can be opened in a GIS. This means that it is possible to overlay other layers on top. For example, it is possible to use the 'white' palette to create a rendered topography and then to overlay, transparently, a satellite image or air photo on top within a GIS. In the case of a fine-resolution image, however, it is important to remember that typically shadows will be visible in these images, that can be contrary to those generated by the rendered topography, which is not ideal for visualization.

The following examples demonstrate how the output of this may appear.

See Also: ShadowImage, ShadowAnimation, TimeInDaylight, HorizonAngle, HypsometricallyTintedHillshade

Parameters:

FlagDescription
-i, --input, --demName of the input digital elevation model (DEM) raster file
-o, --outputName of the output raster file
-p, --palettePalette name; options are 'atlas', 'high_relief', 'arid', 'soft', 'earthtones', 'muted', 'light_quant', 'purple', 'viridi', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', 'imhof', and 'white'
--rev_paletteReverse the palette?
--azLight source azimuth direction (degrees, 0-360)
--altLight source altitude (degrees, 0-90)
--background_hgt_offsetOffset height of background, in z-units
--polygonClipping polygon vector file (optional)
--background_clrBackground red-green-blue (RGB) or red-green-blue-alpha (RGBA) colour, e.g. '[255, 255, 245]', '[255, 255, 245, 200]'
--attenuationAttenuation parameter. Range is 0-4. Zero means no attenuation
--ambient_lightAmbient light parameter. Range is 0.0-0.7. Zero means no ambient light
--z_factorElevation multiplier, or a vertical exageration

Python function:

wbt.topo_render(
    dem, 
    output, 
    palette="soft", 
    rev_palette=False, 
    az=315.0, 
    alt=30.0, 
    background_hgt_offset=10.0, 
    polygon=None, 
    background_clr="[255, 255, 255]", 
    attenuation=0.6, 
    ambient_light=0.2, 
    z_factor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=TopoRender -i=dsm.tif -p='high_relief' ^
-o=shadow_animation.html --max_dist=500 --date='21/06/2021' ^
--time='14:30' --location='43.55/ -80.25/ -4' 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 08/06/2021

Last Modified: 13/06/2021

TopographicPositionAnimation

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

This tool creates an interactive animation that demonstrates the variation in deviation from mean elevation (DEV, DevFromMeanElev) as scale increases across a range for an input digital elevation model (--input). DEV is calculated as the difference between the elevation of each grid cell and the mean elevation of the centering local neighbourhood, normalized by standard deviation and is a measure of local topographic position. DEV is useful for highlighting locally prominent (either elevated or low-lying) locations within a landscape. Topographic position animations are extemely useful for interpreting landscape geomorphic structure across a range of scales.

The set of scales for which DEV is measured (using varying filter sizes) is determined by the three user-specified parameters, including --min_scale, --num_steps, and --step_nonlinearity. Experience with DEV scale signatures has shown that it is highly variable at shorter scales and changes more gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested scales, such that:

ri = rL + (i - rL)p

Where ri is the filter radius for step i, rL is the lower range of filter sizes (--min_scale), and p is the nonlinear scaling factor (--step_nonlinearity).

The tool can be run in one of two modes: using regular DEV calculations, or using DEVmax (MaxElevationDeviation), a multiscale version of DEV that outputs the maximum absolute value of DEV encountered across a range of tested scales. Use the --dev_max flag to run the tool in DEVmax mode.

The output (--output) of this tool is an HTML file, containing the interactive GIF animation. Users are able to zoom and pan around the displayed DEV animation. The DEV images may be rendered in one of several available palettes (--palette) suitable for visualization DEV. The output DEV/DEVmax animation will also be hillshaded to further enchance topographic interpretation. The user must also specify the image height (--height) in the output file, the time delay (--delay, in milliseconds) used in the GIF animation, and an optional label (--label), which will appear in the upper lefthand corner. Note that the output is simply HTML, CSS, javascript code, and a GIF file, which can be readily embedded in other documents.

Users should be aware that the outut GIF can be very large in size, depending on the size of the input DEM file. To reduce the file size of the output, it may be desirable to coarsen the input DEM resolution using image resampling (Resample).

The following is an example of what the output of this tool looks like. Click the image for an interactive example.

For more information about this tool and example outputs, see this blog on the WhiteboxTools homepage.

See Also: DevFromMeanElev, MaxElevationDeviation

Parameters:

FlagDescription
-i, --inputName of the input digital elevation model (DEM) raster file
-p, --paletteImage palette; options are 'bl_yl_rd', 'bl_w_rd', 'purple', 'gn_yl', 'pi_y_g', and 'viridis'
-o, --outputName of the output HTML file (*.html)
--min_scaleMinimum search neighbourhood radius in grid cells
--num_stepsNumber of steps
--step_nonlinearityStep nonlinearity factor (1.0-2.0 is typical)
--heightImage height, in pixels
--delayGIF time delay in milliseconds
-l, --labelLabel text (leave blank for none)
--dev_maxDo you want to use DEVmax instead of DEV for measuring local topographic position?

Python function:

wbt.topographic_position_animation(
    i, 
    output, 
    palette="bl_yl_rd", 
    min_scale=1, 
    num_steps=100, 
    step_nonlinearity=1.5, 
    height=600, 
    delay=250, 
    label="", 
    dev_max=False, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=TopographicPositionAnimation -i=dem.tif ^
-p='bl_w_rd' -o=DEV_animation.html --min_scale=3 ^
--num_steps=100 --step_nonlinearity=1.2 --height=620 ^
--delay=200 --label='DEVmax for Catfish Watershed' --dev_max 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 06/05/2021

Last Modified: 10/06/2021

TotalCurvature

This tool calculates the total curvature from a digital elevation model (DEM). Total curvature measures the curvature of the topographic surface rather than the curvature of a line across the surface in some direction (Wilson, 2018). Total curvature can be positive or negative, with zero curvature indicating that the surface is either flat or the convexity in one direction is balanced by the concavity in another direction, as would occur at a saddle point. Total curvature is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Shary P. A. , Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

Wilson, J. P. (2018). Environmental applications of digital terrain modeling. John Wiley & Sons.

MinimalCurvature, MaximalCurvature, TangentialCurvature, ProfileCurvature, PlanCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--logDisplay output values using a log-scale
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 15/01/2022

Unsphericity

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

This tool calculates the spatial pattern of unsphericity curvature, which describes the degree to which the shape of the topographic surface is nonspherical at a given point (Shary, 1995), from a digital elevation model (DEM). It is calculated as half the difference between the MaximalCurvature and the MinimalCurvature. Unsphericity has values equal to or greater than zero and is measured in units of m-1. Larger values indicate locations that are less spherical in form.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

See Also:

MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature, ProfileCurvature, TangentialCurvature

Parameters:

FlagDescription
-i, --demName of the input raster DEM file
-o, --outputName of the output raster image file
--logDisplay output values using a log-scale
--zfactorZ conversion factor

Python function:

wbt.unsphericity(
    dem, 
    output, 
    log=False, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=Unsphericity -i=DEM.tif -o=output.tif ^
--log 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 11/01/2022

Last Modified: 28/11/2022

VerticalExcessCurvature

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

This tool calculates the vertical excess curvature from a digital elevation model (DEM). Vertical excess curvature is the difference of profile (vertical) and minimal curvatures at a location (Shary, 1995). This variable has positive values, zero or greater. Florinsky (2017) states that vertical excess curvature measures the extent to which the bending of a normal section having a common tangent line with a slope line is larger than the minimal bending at a given point of the surface. Vertical excess curvature is measured in units of m-1.

The user must specify the name of the input DEM (--dem) and the output raster (--output). The The Z conversion factor (--zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (--log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References:

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

See Also:

TangentialCurvature, ProfileCurvature, MinimalCurvature, MaximalCurvature, MeanCurvature, GaussianCurvature

Parameters:

FlagDescription
-i, --demName of the input raster DEM file
-o, --outputName of the output raster image file
--logDisplay output values using a log-scale
--zfactorZ conversion factor

Python function:

wbt.vertical_excess_curvature(
    dem, 
    output, 
    log=False, 
    zfactor=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=VerticalExcessCurvature -i=DEM.tif ^
-o=output.tif --log 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 11/01/2022

Last Modified: 28/11/2022

Viewshed

This tool can be used to calculate the viewshed (i.e. the visible area) from a location (i.e. viewing station) or group of locations based on the topography defined by an input digital elevation model (DEM). The user must specify the name of the input DEM (--dem), a viewing station input vector file (--stations), the output file name (--output), and the viewing height (--height). Viewing station locations are specified as points within an input shapefile. The output image indicates the number of stations visible from each grid cell. The viewing height is in the same units as the elevations of the DEM and represent a height above the ground elevation from which the viewshed is calculated.

Viewshed should be used when there are a relatively small number of target sites for which visibility needs to be assessed. If you need to assess general landscape visibility as a land-surface parameter, the VisibilityIndex tool should be used instead.

Viewshed analysis is a very computationally intensive task. Depending on the size of the input DEM grid and the number of viewing stations, this operation may take considerable time to complete. Also, this implementation of the viewshed algorithm does not account for the curvature of the Earth. This should be accounted for if viewsheds are being calculated over very extensive areas.

See Also: VisibilityIndex

Parameters:

FlagDescription
--demInput raster DEM file
--stationsInput viewing station vector file
-o, --outputOutput raster file
--heightViewing station height, in z units

Python function:

wbt.viewshed(
    dem, 
    stations, 
    output, 
    height=2.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Viewshed -v --wd="/path/to/data/" ^
--dem='dem.tif' --stations='stations.shp' -o=output.tif ^
--height=10.0 

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 calculated for a subset of grid cells in the DEM based on the resolution factor. The visibility index value (0.0-1.0) indicates the proportion of tested stations (determined by the resolution factor) that each cell is visible from. The viewing height is in the same units as the elevations of the DEM and represent a height above the ground elevation. Each tested grid cell's viewshed will be calculated in parallel. However, visibility index is one of the most computationally intensive geomorphometric indices to calculate. Depending on the size of the input DEM grid and the resolution factor, this operation may take considerable time to complete. If the task is too long-running, it is advisable to raise the resolution factor. A resolution factor of 2 will skip every second row and every second column (effectively evaluating the viewsheds of a quarter of the DEM's grid cells). Increasing this value decreases the number of calculated viewshed but will result in a lower accuracy estimate of overall visibility. In addition to the high computational costs of this index, the tool also requires substantial memory resources to operate. Each of these limitations should be considered before running this tool on a particular data set. This tool is best to apply on computer systems with high core-counts and plenty of memory.

See Also: Viewshed

Parameters:

FlagDescription
--demInput raster DEM file
-o, --outputOutput raster file
--heightViewing station height, in z units
--res_factorThe resolution factor determines the density of measured viewsheds

Python function:

wbt.visibility_index(
    dem, 
    output, 
    height=2.0, 
    res_factor=2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=VisibilityIndex -v ^
--wd="/path/to/data/" --dem=dem.tif -o=output.tif ^
--height=10.0 --res_factor=4 

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:

FlagDescription
--scaInput raster specific contributing area (SCA) file
--slopeInput raster slope file (in degrees)
-o, --outputOutput raster file

Python function:

wbt.wetness_index(
    sca, 
    slope, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=WetnessIndex -v --wd="/path/to/data/" ^
--sca='flow_accum.tif' --slope='slope.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/07/2017

Last Modified: 21/01/2018

GIS Analysis

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:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--agg_factorAggregation factor, in pixels
--typeStatistic used to fill output pixels

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:

FlagDescription
-i, --inputInput vector Points file
--fieldInput field name in attribute table
--use_zUse z-coordinate instead of field?
-o, --outputOutput raster file
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified

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:

FlagDescription
-i, --inputInput vector Points file
--fieldInput field name in attribute table
--use_zUse z-coordinate instead of field?
-o, --outputOutput raster file
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified

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:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--text_outputOptional text output

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:

FlagDescription
-i, --inputInput vector file
-o, --outputOutput vector file

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:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--diagFlag indicating whether diagonal connections should be considered
--zero_backFlag indicating whether zero values should be treated as a background

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:

FlagDescription
-i, --inputInput vector points file
--fieldInput field name in attribute table
--use_zUse the 'z' dimension of the Shapefile's geometry instead of an attribute field?
-o, --outputOutput vector polygon file
--max_triangle_edge_lengthOptional maximum triangle edge length; triangles larger than this size will not be gridded

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:

FlagDescription
-i, --base, --inputInput base file
-o, --outputOutput vector polygon file
--widthThe grid cell width
--orientationGrid Orientation, 'horizontal' or 'vertical'

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: 27/08/2021

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:

FlagDescription
--baseInput base raster file
-o, --outputOutput raster file
--gradientSlope gradient in degrees (-85.0 to 85.0)
--aspectAspect (direction) in degrees clockwise from north (0.0-360.0)
--constantConstant value

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:

FlagDescription
-i, --base, --inputInput base file
-o, --outputOutput vector polygon file
--widthThe grid cell width
--heightThe grid cell height
--xorigThe grid origin x-coordinate
--yorigThe grid origin y-coordinate

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:

FlagDescription
-i, --inputInput vector file
--fieldDissolve field attribute (optional)
-o, --outputOutput vector file
--snapSnap tolerance

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:

FlagDescription
-i, --inputInput vector file
-o, --outputOutput vector points file
--toleranceThe distance tolerance for points

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:

FlagDescription
-i, --inputInput vector polyline file
-o, --outputOutput vector polyline file
--distThe distance to extend
--extendExtend direction, 'both ends' (default), 'line start', 'line end'

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:

FlagDescription
-i, --inputInput vector lines or polygon file
-o, --outputOutput vector points file

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:

FlagDescription
-i, --inputsInput raster files
--pointsInput vector points file
--out_textOutput point values as text? Otherwise, the only output is to to the points file's attribute table

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:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--thresholdRemove features with fewer grid cells than this threshold value
--backgroundBackground value

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:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput vector points file
--out_typeOutput type; one of 'area' (default) and 'volume'

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

HeatMap

This tool is used to generate a raster heat map, or kernel density estimation surface raster from a set of vector points (--input). Heat mapping is a visualization and modelling technique used to create the continuous density surface associated with the occurrences of a point phenomenon. Heat maps can therefore be used to identify point clusters by mapping the concentration of event occurrence. For example, heat maps have been used extensively to map the spatial distributions of crime events (i.e. crime mapping) or disease cases.

By default, the tool maps the density of raw occurrence events, however, the user may optionally specify an associated weights field (--weights) from the point file's attribute table. When a weights field is specified, these values are simply multiplied by each of the individual components of the density estimate. Weights must be numeric.

The bandwidth parameter (--bandwidth) determines the radius of the kernel used in calculation of the density surface. There are guidelines that statisticians use in determining an appropriate bandwidth for a particular population and data set, but often this parameter is determined through experimentation. The bandwidth of the kernel is a free parameter which exhibits a strong influence on the resulting estimate.

The user must specify the kernel function type (--kernel). Options include 'uniform', 'triangular', 'epanechnikov', 'quartic', 'triweight', 'tricube', 'gaussian', 'cosine', 'logistic', 'sigmoid', and 'silverman'; 'quartic' is the default kernel type. Descriptions of each function can be found at the link above.

The characteristics of the output raster (resolution and extent) are determined by one of two optional parameters, --cell_size and --base. If the user optionally specifies the output grid cell size parameter (--cell_size) then the coordinates of the output raster extent are determined by the input vector (i.e. the bounding box) and the specified cell size determines the number of rows and columns. 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, and therefore, resolution, will be the same as the base file.

Reference:

Geomatics (2017) QGIS Heatmap Using Kernel Density Estimation Explained, online resource: https://www.geodose.com/2017/11/qgis-heatmap-using-kernel-density.html visited 02/06/2022.

Parameters:

FlagDescription
-i, --inputName of the input points shapefile
--weights, --weight_fieldOptional name of the attribute containing point weight
-o, --outputName of the output raster image file
--bandwidthBandwidth (metres)
--kernelKernel type; one of 'uniform', 'triangular', 'epanechnikov', 'quartic', 'triweight', 'tricube', 'gaussian', 'cosine', 'logistic', 'sigmoid', 'silverman'
--cell_sizeOptionally specified cell size of output raster, in metres. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified

Python function:

wbt.heat_map(
    i, 
    output, 
    weight_field=None, 
    bandwidth="", 
    kernel="quartic", 
    cell_size="", 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=HeatMap -i=points.shp -o=density.tif ^
--bandwidth=1000.0 --kernel='quartic' --cell_size=10.0 

Source code is unavailable due to proprietary license.

Author: Dr. John Lindsay

Created: 01/06/2022

Last Modified: 01/06/2022

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:

FlagDescription
-i, --inputInput vector Points file
--fieldInput field name in attribute table
--use_zUse z-coordinate instead of field?
-o, --outputOutput raster file
--weightIDW weight value
--radiusSearch Radius in map units
--min_pointsMinimum number of points
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified

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:

FlagDescription
-i, --inputInput raster or vector file
-o, --outputOutput vector polygon file

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: 09/09/2021

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:

FlagDescription
-i, --inputInput vector file
-o, --outputOutput vector file

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:

FlagDescription
-i, --inputInput vector file
-o, --outputOutput vector polygon file
--criterionMinimization criterion; options include 'area' (default), 'length', 'width', and 'perimeter'
--featuresFind the minimum bounding rectangles around each individual vector feature

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:

FlagDescription
-i, --inputInput vector file
-o, --outputOutput vector polygon file
--featuresFind the minimum bounding circle around each individual vector feature

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:

FlagDescription
-i, --inputInput vector file
-o, --outputOutput vector polygon file
--featuresFind the minimum bounding envelop around each individual vector feature

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

FlagDescription
-i, --inputInput vector file
-o, --outputOutput vector polygon file
--featuresFind the hulls around each vector feature

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:

FlagDescription
-i, --inputInput vector points file
--fieldInput field name in attribute table
--use_zUse the 'z' dimension of the Shapefile's geometry instead of an attribute field?
-o, --outputOutput raster file
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified
--clipClip the data to the convex hull of the points?

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:

FlagDescription
-i, --inputInput vector Points file
--fieldInput field name in attribute table
--use_zUse z-coordinate instead of field?
-o, --outputOutput raster file
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified
--max_distMaximum search distance (optional)

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:

FlagDescription
-i, --inputInput vector polygon file

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:

FlagDescription
-i, --inputInput vector polygons file
-o, --outputOutput vector polyline file

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

PolygonPerimeter

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

Parameters:

FlagDescription
-i, --inputInput vector polygon file

Python function:

wbt.polygon_perimeter(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PolygonPerimeter -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

PolygonShortAxis

This tool can be used to map the short axis of polygon features. The short axis is the shorter of the two primary axes of the minimum bounding box (MBB), i.e. the smallest box to completely enclose a feature. The short 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:

FlagDescription
-i, --inputInput vector polygons file
-o, --outputOutput vector polyline file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/09/2018

Last Modified: 03/03/2020

RadialBasisFunctionInterpolation

This tool interpolates vector points into a raster surface using a radial basis function (RBF) scheme.

Parameters:

FlagDescription
-i, --inputInput vector points file
--fieldInput field name in attribute table
--use_zUse z-coordinate instead of field?
-o, --outputOutput raster file
--radiusSearch Radius (in map units)
--min_pointsMinimum number of points
--func_typeRadial basis function type; options are 'ThinPlateSpline' (default), 'PolyHarmonic', 'Gaussian', 'MultiQuadric', 'InverseMultiQuadric'
--poly_orderPolynomial order; options are 'none' (default), 'constant', 'affine'
--weightWeight parameter used in basis function
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified

Python function:

wbt.radial_basis_function_interpolation(
    i, 
    field, 
    output, 
    use_z=False, 
    radius=None, 
    min_points=None, 
    func_type="ThinPlateSpline", 
    poly_order="none", 
    weight=0.1, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RadialBasisFunctionInterpolation -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 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/12/2019

Last Modified: 10/12/2019

RasterArea

This tools estimates the area of each category, polygon, or patch in an input raster. The input raster must be categorical in data scale. Rasters with floating-point cell values are not good candidates for an area analysis. The user must specify whether the output is given in grid cells or map units (--units). Map Units are physical units, e.g. if the rasters's scale is in metres, areas will report in square-metres. Notice that square-metres can be converted into hectares by dividing by 10,000 and into square-kilometres by dividing by 1,000,000. If the input raster is in geographic coordinates (i.e. latitude and longitude) a warning will be issued and areas will be estimated based on per-row calculated degree lengths.

The tool can be run with a raster output (--output), a text output (--out_text), or both. If niether outputs are specified, the tool will automatically output a raster named area.tif.

Zero values in the input raster may be excluded from the area analysis if the --zero_back flag is used.

To calculate the area of vector polygons, use the PolygonArea tool instead.

See Also: PolygonArea, RasterHistogram

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--out_textWould you like to output polygon areas to text?
--unitsArea units; options include 'grid cells' and 'map units'
--zero_backFlag indicating whether zero values should be treated as a background

Python function:

wbt.raster_area(
    i, 
    output=None, 
    out_text=False, 
    units="grid cells", 
    zero_back=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterArea -v --wd="/path/to/data/" ^
-i=input.tif -o=output.tif --out_text --units='grid cells' ^
--zero_back 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/02/2019

Last Modified: 04/12/2019

RasterCellAssignment

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. Grid cells in the new raster will be assigned either the row or column number or the x- or y-coordinate, depending on the selected option (--assign flag). The user must also specify the name of the base image (--input).

See Also: NewRasterFromBase

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
-a, --assignWhich variable would you like to assign to grid cells? Options include 'column', 'row', 'x', and 'y'

Python function:

wbt.raster_cell_assignment(
    i, 
    output, 
    assign="column", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterCellAssignment -v ^
--wd="/path/to/data/" -i='input.tif' -o=output.tif ^
--assign='column' 

Source code on GitHub

Author: Daniel Newman

Created: August 10, 2017

Last Modified: 13/10/2018

RasterPerimeter

This tool can be used to measure the length of the perimeter of polygon features in a raster layer. The user must specify the name of the input raster file (--input) and optionally an output raster (--output), which is the raster layer containing the input features assigned the perimeter length. The user may also optionally choose to output text data (--out_text). Raster-based perimeter estimation uses the accurate, anti-aliasing algorithm of Prashker (2009).

The input file must be of a categorical data type, containing discrete polygon features that have been assigned unique identifiers. Such rasters are often created by region-grouping (Clump) a classified raster.

Reference:

Prashker, S. (2009) An anti-aliasing algorithm for calculating the perimeter of raster polygons. Geotec, Ottawa and Geomtics Atlantic, Wolfville, NS.

See Also: RasterArea, Clump

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--out_textWould you like to output polygon areas to text?
--unitsArea units; options include 'grid cells' and 'map units'
--zero_backFlag indicating whether zero values should be treated as a background

Python function:

wbt.raster_perimeter(
    i, 
    output=None, 
    out_text=False, 
    units="grid cells", 
    zero_back=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterPerimeter -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --out_text ^
--units='grid cells' --zero_back 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/12/2019

Last Modified: 18/12/2019

Reclass

This tool creates a new raster in which the value of each grid cell is determined by an input raster (--input) and a collection of user-defined classes. The user must specify the New value, the From value, and the To Just Less Than value of each class triplet of the reclass string. Classes must be mutually exclusive, i.e. non-overlapping. For example:

--reclass_vals='0.0;0.0;1.0;1.0;1.0;2.0'

The above reclass string assigns 0.0 to all grid cells in the input image with values from 0.0-1.0 and an output value of 1.0 from to inputs from 1.0-2.0. Alternatively, if the --assign_mode flag is specified, Reclass will operate in assign mode, using a reclass string composed of paired values:

--reclass_vals='0.0;1.0;1.0;2.0'

Here, 0.0 is assigned to input grid cell values of 1.0 and 1.0 is output for all input cells with a value of 2.0. Users may add the text strings min and max in the class definitions to stand in for the raster's minimum and maximum values. For example:

--reclass_vals='0.0;min;1.0;1.0;1.0;max'

Any values in the input raster that do not fall within one of the classes will be assigned its original value in the output raster. NoData values in the input raster will be assigned NoData values in the output raster, unless NoData is used in one of the user-defined reclass ranges (notice that it is valid to enter 'NoData' in these ranges).

See Also: ReclassEqualInterval, ReclassFromFile

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--reclass_valsReclassification triplet values (new value; from value; to less than), e.g. '0.0;0.0;1.0;1.0;1.0;2.0'
--assign_modeOptional Boolean flag indicating whether to operate in assign mode, reclass_vals values are interpreted as new value; old value pairs

Python function:

wbt.reclass(
    i, 
    output, 
    reclass_vals, 
    assign_mode=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Reclass -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif ^
--reclass_vals='0.0;0.0;1.0;1.0;1.0;2.0'
>>./whitebox_tools ^
-r=Reclass -v --wd="/path/to/data/" -i='input.tif' ^
-o=output.tif --reclass_vals='10;1;20;2;30;3;40;4' ^
--assign_mode 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/09/2017

Last Modified: 31/05/2021

ReclassEqualInterval

This tool reclassifies the values in an input raster (--input) file based on an equal-interval scheme, where the user must specify the reclass interval value (--interval), the starting value (--start_val), and optionally, the ending value (--end_val). Grid cells containing values that fall outside of the range defined by the starting and ending values, will be assigned their original values in the output grid. If the user does not specify an ending value, the tool will assign a very large positive value.

See Also: Reclass, ReclassFromFile

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--intervalClass interval size
--start_valOptional starting value (default is input minimum value)
--end_valOptional ending value (default is input maximum value)

Python function:

wbt.reclass_equal_interval(
    i, 
    output, 
    interval=10.0, 
    start_val=None, 
    end_val=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ReclassEqualInterval -v ^
--wd="/path/to/data/" -i='input.tif' -o=output.tif ^
--interval=10.0 --start_val=0.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 30/01/2020

ReclassFromFile

This tool creates a new raster image in which the value of each grid cell is determined by the values in an input raster image (--input) and a reclass file (--reclass_file). The reclass file is a text file containing two or three columns, delimited (i.e. separated) by either a space, tab, or comma. The columns describe respectively the New value, the From value, and the To Just Less Than value. Classes must be mutually exclusive, i.e. non-overlapping. Users may add the text strings min and max in the class definitions to stand in for the raster's minimum and maximum values.

If only two columns are present in the reclass file, i.e. the From column is left blank, the tool will operate in assign mode. That is, any cell in the input image that is equal to the From value (contained in the second column) will be assigned the New value (contained in the first column) in the output image.

Any values in the input raster that do not fall within one of the classes will be assigned its original value in the output raster. NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Reclass, ReclassEqualInterval

Parameters:

FlagDescription
-i, --inputInput raster file
--reclass_fileInput text file containing reclass ranges
-o, --outputOutput raster file

Python function:

wbt.reclass_from_file(
    i, 
    reclass_file, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ReclassFromFile -v ^
--wd="/path/to/data/" -i='input.tif' ^
--reclass_file='reclass.txt' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/09/2017

Last Modified: 13/02/2020

SmoothVectors

This tool smooths a vector coverage of either a POLYLINE or POLYGON base ShapeType. The algorithm uses a simple moving average method for smoothing, where the size of the averaging window is specified by the user. The default filter size is 3 and can be any odd integer larger than or equal to 3. The larger the averaging window, the greater the degree of line smoothing.

Parameters:

FlagDescription
-i, --inputInput vector POLYLINE or POLYGON file
-o, --outputOutput vector file
--filterThe filter size, any odd integer greater than or equal to 3; default is 3

Python function:

wbt.smooth_vectors(
    i, 
    output, 
    filter=3, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/10/2018

Last Modified: 13/10/2018

SplitVectorLines

This tool can be used to divide longer vector lines (--input) into segments of a maximum specified length (--length).

See Also: AssessRoute

Parameters:

FlagDescription
-i, --inputName of the input lines shapefile
-o, --outputName of the output lines shapefile
--lengthMaximum segment length (m)

Python function:

wbt.split_vector_lines(
    i, 
    output, 
    length=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=SplitVectorLines -i=input.shp ^
-o=line_segments.shp --length=100.0 

Source code on GitHub

Author: Prof. John Lindsay

Created: 23/04/2021

Last Modified: 23/04/2021

TinGridding

Creates a raster grid based on a triangular irregular network (TIN) fitted to vector points and linear interpolation within each triangular-shaped plane. The TIN creation algorithm is based on Delaunay triangulation.

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

See Also: LidarTINGridding, ConstructVectorTIN, NaturalNeighbourInterpolation

Parameters:

FlagDescription
-i, --inputInput vector points file
--fieldInput field name in attribute table
--use_zUse the 'z' dimension of the Shapefile's geometry instead of an attribute field?
-o, --outputOutput raster file
--resolutionOutput raster's grid resolution
--baseOptionally specified input base raster file. Not used when a cell size is specified
--max_triangle_edge_lengthOptional maximum triangle edge length; triangles larger than this size will not be gridded

Python function:

wbt.tin_gridding(
    i, 
    output, 
    field=None, 
    use_z=False, 
    resolution=None, 
    base=None, 
    max_triangle_edge_length=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 23/09/2018

Last Modified: 18/10/2019

TravellingSalesmanProblem

This tool finds approximate solutions to travelling salesman problems, the goal of which is to identify the shortest route connecting a set of locations. The tool uses an algorithm that applies a 2-opt heuristic and a 3-opt heuristic as a fall-back if the initial approach takes too long. The user must specify the names of the input points vector (--input) and output lines vector file (--output), as well as the duration, in seconds, over which the algorithm is allowed to search for improved solutions (--duration). The tool works in parallel to find more optimal solutions.

Parameters:

FlagDescription
-i, --inputName of the input points shapefile
-o, --outputName of the output lines shapefile
--durationMaximum duration, in seconds

Python function:

wbt.travelling_salesman_problem(
    i, 
    output, 
    duration=60, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=TravellingSalesmanProblem -i=input.shp ^
-o=route.shp --duration=120 

Source code on GitHub

Author: Prof. John Lindsay

Created: 23/02/2022

Last Modified: 06/05/2022

VectorHexBinning

The practice of binning point data to form a type of 2D histogram, density plot, or what is sometimes called a heatmap, is quite useful as an alternative for the cartographic display of of very dense points sets. This is particularly the case when the points experience significant overlap at the displayed scale. The PointDensity tool can be used to perform binning based on a regular grid (raster output). This tool, by comparison, bases the binning on a hexagonal grid.

The tool is similar to the CreateHexagonalVectorGrid tool, however instead will create an output hexagonal grid in which each hexagonal cell possesses a COUNT attribute which specifies the number of points from an input points file (Shapefile vector) that are contained within the hexagonal cell.

In addition to the names of the input points file and the output Shapefile, the user must also specify the desired hexagon width (w), which is the distance between opposing sides of each hexagon. The size (s) each side of the hexagon can then be calculated as, s = w / [2 x cos(PI / 6)]. The area of each hexagon (A) is, A = 3s(w / 2). The user must also specify the orientation of the grid with options of horizontal (pointy side up) and vertical (flat side up).

See Also: LidarHexBinning, PointDensity, CreateHexagonalVectorGrid

Parameters:

FlagDescription
-i, --inputInput base file
-o, --outputOutput vector polygon file
--widthThe grid cell width
--orientationGrid Orientation, 'horizontal' or 'vertical'

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=VectorHexBinning -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: 16/09/2018

Last Modified: 13/10/2018

VoronoiDiagram

This tool creates a vector Voronoi diagram for a set of vector points. The Voronoi diagram is the dual graph of the Delaunay triangulation. The tool operates by first constructing the Delaunay triangulation and then connecting the circumcenters of each triangle. Each Voronoi cell contains one point of the input vector points. All locations within the cell are nearer to the contained point than any other input point.

A dense frame of 'ghost' (hidden) points is inserted around the input point set to limit the spatial extent of the diagram. The frame is set back from the bounding box of the input points by 2 x the average point spacing. The polygons of these ghost points are not output, however, points that are situated along the edges of the data will have somewhat rounded (paraboloic) exterior boundaries as a result of this edge condition. If this property is unacceptable for application, clipping the Voronoi diagram to the convex hull may be a better alternative.

This tool works on vector input data only. If a Voronoi diagram is needed to tessellate regions associated with a set of raster points, use the EuclideanAllocation tool instead. To use Voronoi diagrams for gridding data (i.e. raster interpolation), use the NearestNeighbourGridding tool.

See Also: ConstructVectorTIN, EuclideanAllocation, NearestNeighbourGridding

Parameters:

FlagDescription
-i, --inputInput vector points file
-o, --outputOutput vector polygon file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=VoronoiDiagram -v --wd="/path/to/data/" ^
-i=points.shp -o=tin.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 03/10/2018

Last Modified: 16/06/2020

GIS Analysis → Distance Tools

BufferRaster

This tool can be used to identify an area of interest within a specified distance of features of interest in a raster data set.

The Euclidean distance (i.e. straight-line distance) is calculated between each grid cell and the nearest 'target cell' in the input image. Distance is calculated using the efficient method of Shih and Wu (2004). Target cells are all non-zero, non-NoData grid cells. Because NoData values in the input image are assigned the NoData value in the output image, the only valid background value in the input image is zero.

The user must specify the input and output image names, the desired buffer size (--size), and, optionally, whether the distance units are measured in grid cells (i.e. --gridcells flag). If the --gridcells flag is not specified, the linear units of the raster's coordinate reference system will be used.

Reference:

Shih FY and Wu Y-T (2004), Fast Euclidean distance transformation in two scans using a 3 x 3 neighborhood, Computer Vision and Image Understanding, 93: 195-205.

See Also: EuclideanDistance

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--sizeBuffer size
--gridcellsOptional flag to indicate that the 'size' threshold should be measured in grid cells instead of the default map units

Python function:

wbt.buffer_raster(
    i, 
    output, 
    size, 
    gridcells=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BufferRaster -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: 30/01/2020

CostAllocation

This tool can be used to identify the 'catchment area' of each source grid cell in a cost-distance analysis. The user must specify the names of the input source and back-link raster files. Source cells (i.e. starting points for the cost-distance or least-cost path analysis) are designated as all positive, non-zero valued grid cells in the source raster. A back-link raster file can be created using the CostDistance tool and is conceptually similar to the D8 flow-direction pointer raster grid in that it describes the connectivity between neighbouring cells on the accumulated cost surface.

NoData values in the input back-link image are assigned NoData values in the output image.

See Also: CostDistance, CostPathway, EuclideanAllocation

Parameters:

FlagDescription
--sourceInput source raster file
--backlinkInput backlink raster file generated by the cost-distance tool
-o, --outputOutput raster file

Python function:

wbt.cost_allocation(
    source, 
    backlink, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CostAllocation -v --wd="/path/to/data/" ^
--source='source.tif' --backlink='backlink.tif' ^
-o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/072017

Last Modified: 13/10/2018

CostDistance

This tool can be used to perform cost-distance or least-cost pathway analyses. Specifically, this tool can be used to calculate the accumulated cost of traveling from the 'source grid cell' to each other grid cell in a raster dataset. It is based on the costs associated with traveling through each cell along a pathway represented in a cost (or friction) surface. If there are multiple source grid cells, each cell in the resulting cost-accumulation surface will reflect the accumulated cost to the source cell that is connected by the minimum accumulated cost-path. The user must specify the names of the raster file containing the source cells (--source), the raster file containing the cost surface information (--cost), the output cost-accumulation surface raster (--out_accum), and the output back-link raster (--out_backlink). Source cells are designated as all positive, non-zero valued grid cells in the source raster. The cost (friction) raster can be created by combining the various cost factors associated with the specific problem (e.g. slope gradient, visibility, etc.) using a raster calculator or the WeightedOverlay tool.

While the cost-accumulation surface raster can be helpful for visualizing the three-dimensional characteristics of the 'cost landscape', it is actually the back-link raster that is used as inputs to the other two cost-distance tools, CostAllocation and CostPathway, to determine the least-cost linkages among neighbouring grid cells on the cost surface. If the accumulated cost surface is analogous to a digital elevation model (DEM) then the back-link raster is equivalent to the D8 flow-direction pointer. In fact, it is created in a similar way and uses the same convention for designating 'flow directions' between neighbouring grid cells. The algorithm for the cost distance accumulation operation uses a type of priority-flood method similar to what is used for depression filling and flow accumulation operations.

NoData values in the input cost surface image are ignored during processing and assigned NoData values in the outputs. The output cost accumulation raster is of the float data type and continuous data scale.

See Also: CostAllocation, CostPathway, WeightedOverlay

Parameters:

FlagDescription
--sourceInput source raster file
--costInput cost (friction) raster file
--out_accumOutput cost accumulation raster file
--out_backlinkOutput backlink raster file

Python function:

wbt.cost_distance(
    source, 
    cost, 
    out_accum, 
    out_backlink, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CostDistance -v --wd="/path/to/data/" ^
--source=src.tif --cost=cost.tif --out_accum=accum.tif ^
--out_backlink=backlink.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/07/2017

Last Modified: 15/11/2018

CostPathway

This tool can be used to map the least-cost pathway connecting each destination grid cell in a cost-distance analysis to a source cell. The user must specify the names of the input destination and back-link raster files. Destination cells (i.e. end points for the least-cost path analysis) are designated as all positive, non-zero valued grid cells in the destination raster. A back-link raster file can be created using the CostDistance tool and is conceptually similar to the D8 flow-direction pointer raster grid in that it describes the connectivity between neighbouring cells on the accumulated cost surface. All background grid cells in the output image are assigned the NoData value.

NoData values in the input back-link image are assigned NoData values in the output image.

See Also: CostDistance, CostAllocation

Parameters:

FlagDescription
--destinationInput destination raster file
--backlinkInput backlink raster file generated by the cost-distance tool
-o, --outputOutput cost pathway raster file
--zero_backgroundFlag indicating whether zero values should be treated as a background

Python function:

wbt.cost_pathway(
    destination, 
    backlink, 
    output, 
    zero_background=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CostPathway -v --wd="/path/to/data/" ^
--destination=dst.tif --backlink=backlink.tif ^
--output=cost_path.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/07/2017

Last Modified: 18/10/2019

EuclideanAllocation

This tool assigns grid cells in the output image the value of the nearest target cell in the input image, measured by the Euclidean distance (i.e. straight-line distance). Thus, EuclideanAllocation essentially creates the Voronoi diagram for a set of target cells. Target cells are all non-zero, non-NoData grid cells in the input image. Distances are calculated using the same efficient algorithm (Shih and Wu, 2003) as the EuclideanDistance tool.

Reference:

Shih FY and Wu Y-T (2004), Fast Euclidean distance transformation in two scans using a 3 x 3 neighborhood, Computer Vision and Image Understanding, 93: 195-205.

See Also: EuclideanDistance, VoronoiDiagram, CostAllocation

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: June 22 2017

Last Modified: 25/11/2018

EuclideanDistance

This tool will estimate the Euclidean distance (i.e. straight-line distance) between each grid cell and the nearest 'target cell' in the input image. Target cells are all non-zero, non-NoData grid cells. Distance in the output image is measured in the same units as the horizontal units of the input image.

Algorithm Description:

The algorithm is based on the highly efficient distance transform of Shih and Wu (2003). It makes four passes of the image; the first pass initializes the output image; the second and third passes calculate the minimum squared Euclidean distance by examining the 3 x 3 neighbourhood surrounding each cell; the last pass takes the square root of cell values, transforming them into true Euclidean distances, and deals with NoData values that may be present. All NoData value grid cells in the input image will contain NoData values in the output image. As such, NoData is not a suitable background value for non-target cells. Background areas should be designated with zero values.

Reference:

Shih FY and Wu Y-T (2004), Fast Euclidean distance transformation in two scans using a 3 x 3 neighborhood, Computer Vision and Image Understanding, 93: 195-205.

See Also: EuclideanAllocation, CostDistance

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=EuclideanDistance -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: 05/12/2019

GIS Analysis → Overlay Tools

AverageOverlay

This tool can be used to find the average value in each cell of a grid from a set of input images (--inputs). It is therefore similar to the WeightedSum tool except that each input image is given equal weighting. This tool operates on a cell-by-cell basis. Therefore, each of the input rasters must share the same number of rows and columns and spatial extent. An error will be issued if this is not the case. At least two input rasters are required to run this tool. Like each of the WhiteboxTools overlay tools, this tool has been optimized for parallel processing.

See Also: WeightedSum

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=AverageOverlay -v --wd='/path/to/data/' ^
-i='image1.dep;image2.dep;image3.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 13/10/2018

Clip

This tool will extract all the features, or parts of features, that overlap with the features of the clip vector file. The clipping operation is one of the most common vector overlay operations in GIS and effectively imposes the boundary of the clip layer on a set of input vector features, or target features. The operation is sometimes likened to a 'cookie-cutter'. The input vector file can be of any feature type (i.e. points, lines, polygons), however, the clip vector must consist of polygons.

See Also: Erase

Parameters:

FlagDescription
-i, --inputInput vector file
--clipInput clip polygon vector file
-o, --outputOutput vector file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=Clip -v --wd="/path/to/data/" ^
-i=lines1.shp --clip=clip_poly.shp -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/10/2018

Last Modified: 3/11/2018

ClipRasterToPolygon

This tool can be used to clip an input raster (--input) to the extent of a vector polygon (shapefile). The user must specify the name of the input clip file (--polygons), which must be a vector of a Polygon base shape type. The clip file may contain multiple polygon features. Polygon hole parts will be respected during clipping, i.e. polygon holes will be removed from the output raster by setting them to a NoData background value. Raster grid cells that fall outside of a polygons in the clip file will be assigned the NoData background value in the output file. By default, the output raster will be cropped to the spatial extent of the clip file, unless the --maintain_dimensions parameter is used, in which case the output grid extent will match that of the input raster. The grid resolution of output raster is the same as the input raster.

It is very important that the input raster and the input vector polygon file share the same projection. The result is unlikely to be satisfactory otherwise.

See Also: ErasePolygonFromRaster

Parameters:

FlagDescription
-i, --inputInput raster file
--polygonsInput vector polygons file
-o, --outputOutput raster file
--maintain_dimensionsMaintain input raster dimensions?

Python function:

wbt.clip_raster_to_polygon(
    i, 
    polygons, 
    output, 
    maintain_dimensions=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ClipRasterToPolygon -v ^
--wd="/path/to/data/" -i=raster.tif --polygons=poly.shp ^
-o=output.tif --maintain_dimensions 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/04/2018

Last Modified: 06/12/2022

CountIf

This tool counts the number of occurrences of a specified value (--value) in a stack of input rasters (--inputs). Each grid cell in the output raster (--output) will contain the number of occurrences of the specified value in the stack of corresponding cells in the input image. At least two input rasters are required to run this tool. Each of the input rasters must share the same number of rows and columns and spatial extent. An error will be issued if this is not the case.

See Also: PickFromList

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file
--valueSearch value (e.g. countif value = 5.0)

Python function:

wbt.count_if(
    inputs, 
    output, 
    value, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CountIf -v --wd='/path/to/data/' ^
-i='image1.dep;image2.dep;image3.tif' -o=output.tif ^
--value=5.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/04/2018

Last Modified: 13/10/2018

Difference

This tool will remove all the overlapping features, or parts of overlapping features, between input and overlay vector files, outputting only the features that occur in one of the two inputs but not both. The Symmetrical Difference is related to the Boolean exclusive-or (XOR) operation in set theory and is one of the common vector overlay operations in GIS. The user must specify the names of the input and overlay vector files as well as the output vector file name. The tool operates on vector points, lines, or polygon, but both the input and overlay files must contain the same ShapeType.

The Symmetrical Difference can also be derived using a combination of other vector overlay operations, as either (A union B) difference (A intersect B), or (A difference B) union (B difference A).

The attributes of the two input vectors will be merged in the output attribute table. Fields that are duplicated between the inputs will share a single attribute in the output. Fields that only exist in one of the two inputs will be populated by null in the output table. Multipoint ShapeTypes however will simply contain a single output feature identifier (FID) attribute. Also, note that depending on the ShapeType (polylines and polygons), Measure and Z ShapeDimension data will not be transferred to the output geometries. If the input attribute table contains fields that measure the geometric properties of their associated features (e.g. length or area), these fields will not be updated to reflect changes in geometry shape and size resulting from the overlay operation.

See Also: Intersect, Difference, Union, Clip, Erase

Parameters:

FlagDescription
-i, --inputInput vector file
--overlayInput overlay vector file
-o, --outputOutput vector file

Python function:

wbt.difference(
    i, 
    overlay, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Difference -v --wd="/path/to/data/" ^
-input=layer1.shp --overlay=layer2.shp -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 8/11/2018

Last Modified: 8/11/2018

Erase

This tool will remove all the features, or parts of features, that overlap with the features of the erase vector file. The erasing operation is one of the most common vector overlay operations in GIS and effectively imposes the boundary of the erase layer on a set of input vector features, or target features.

See Also: Clip

Parameters:

FlagDescription
-i, --inputInput vector file
--eraseInput erase polygon vector file
-o, --outputOutput vector file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=Erase -v --wd="/path/to/data/" ^
-i=lines1.shp --erase=erase_poly.shp -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 4/11/2018

Last Modified: 4/11/2018

ErasePolygonFromRaster

This tool can be used to set values an input raster (--input) to a NoData background value with a vector erasing polygon (--polygons). The input erase polygon file must be a vector of a Polygon base shape type. The erase file may contain multiple polygon features. Polygon hole parts will be respected during clipping, i.e. polygon holes will not be removed from the output raster. Raster grid cells that fall inside of a polygons in the erase file will be assigned the NoData background value in the output file.

See Also: ClipRasterToPolygon

Parameters:

FlagDescription
-i, --inputInput raster file
--polygonsInput vector polygons file
-o, --outputOutput raster file

Python function:

wbt.erase_polygon_from_raster(
    i, 
    polygons, 
    output, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/03/2018

Last Modified: 13/10/2018

HighestPosition

This tool identifies the stack position (index) of the maximum value within a raster stack on a cell-by-cell basis. For example, if five raster images (--inputs) are input to the tool, the output raster (--output) would show which of the five input rasters contained the highest value for each grid cell. The index value in the output raster is the zero-order number of the raster stack, i.e. if the highest value in the stack is contained in the first image, the output value would be 0; if the highest stack value were the second image, the output value would be 1, and so on. If any of the cell values within the stack is NoData, the output raster will contain the NoData value for the corresponding grid cell. The index value is related to the order of the input images.

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: LowestPosition, PickFromList

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=HighestPosition -v ^
--wd='/path/to/data/' -i='image1.tif;image2.tif;image3.tif' ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 13/10/2018

Intersect

The result of the Intersect vector overlay operation includes all the feature parts that occur in both input layers, excluding all other parts. It is analogous to the OR logical operator and multiplication in arithmetic. This tool is one of the common vector overlay operations in GIS. The user must specify the names of the input and overlay vector files as well as the output vector file name. The tool operates on vector points, lines, or polygon, but both the input and overlay files must contain the same ShapeType.

The Intersect tool is similar to the Clip tool. The difference is that the overlay vector layer in a Clip operation must always be polygons, regardless of whether the input layer consists of points or polylines.

The attributes of the two input vectors will be merged in the output attribute table. Note, duplicate fields should not exist between the inputs layers, as they will share a single attribute in the output (assigned from the first layer). Multipoint ShapeTypes will simply contain a single output feature identifier (FID) attribute. Also, note that depending on the ShapeType (polylines and polygons), Measure and Z ShapeDimension data will not be transferred to the output geometries. If the input attribute table contains fields that measure the geometric properties of their associated features (e.g. length or area), these fields will not be updated to reflect changes in geometry shape and size resulting from the overlay operation.

See Also: Difference, Union, SymmetricalDifference, Clip, Erase

Parameters:

FlagDescription
-i, --inputInput vector file
--overlayInput overlay vector file
-o, --outputOutput vector file
--snapSnap tolerance

Python function:

wbt.intersect(
    i, 
    overlay, 
    output, 
    snap=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Intersect -v --wd="/path/to/data/" ^
-input=layer1.shp --overlay=layer2.shp -o=out_file.shp ^
--snap=0.0000001 

Source code on GitHub

Author: Dr. John Lindsay

Created: 8/11/2018

Last Modified: 21/11/2018

LineIntersections

This tool identifies points where the features of two vector line/polygon layers intersect. The user must specify the names of two input vector line files and the output file. The output file will be a vector of POINT ShapeType. If the input vectors intersect at a line segment, the beginning and end vertices of the segment will be present in the output file. A warning is issued if intersection line segments are identified during analysis. If no intersections are found between the input line files, the output file will not be saved and a warning will be issued.

Each intersection point will contain PARENT1 and PARENT2 attribute fields, identifying the instersecting features in the first and second input line files respectively. Additionally, the output attribute table will contain all of the attributes (excluding FIDs) of the two parent line features.

Parameters:

FlagDescription
--i1, --input1Input vector polyline file
--i2, --input2Input vector polyline file
-o, --outputOutput vector point file

Python function:

wbt.line_intersections(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LineIntersections -v ^
--wd="/path/to/data/" --i1=lines1.shp --i2=lines2.shp ^
-o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/10/2018

Last Modified: 16/10/2018

LowestPosition

This tool identifies the stack position (index) of the minimum value within a raster stack on a cell-by-cell basis. For example, if five raster images (--inputs) are input to the tool, the output raster (--output) would show which of the five input rasters contained the lowest value for each grid cell. The index value in the output raster is the zero-order number of the raster stack, i.e. if the lowest value in the stack is contained in the first image, the output value would be 0; if the lowest stack value were the second image, the output value would be 1, and so on. If any of the cell values within the stack is NoData, the output raster will contain the NoData value for the corresponding grid cell. The index value is related to the order of the input images.

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: HighestPosition, PickFromList

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=LowestPosition -v --wd='/path/to/data/' ^
-i='image1.tif;image2.tif;image3.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/07/2017

Last Modified: 13/10/2018

MaxAbsoluteOverlay

This tool can be used to find the maximum absolute (non-negative) value in each cell of a grid from a set of input images (--inputs). NoData values in any of the input images will result in a NoData pixel in the output image.

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: MaxOverlay, MinAbsoluteOverlay, MinOverlay

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=MaxAbsoluteOverlay -v ^
--wd='/path/to/data/' -i='image1.tif;image2.tif;image3.tif' ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 13/10/2018

MaxOverlay

This tool can be used to find the maximum value in each cell of a grid from a set of input images (--inputs). NoData values in any of the input images will result in a NoData pixel in the output image (--output). It is similar to the Max mathematical tool, except that it will accept more than two input images.

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: MinOverlay, MaxAbsoluteOverlay, MinAbsoluteOverlay, Max

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=MaxOverlay -v --wd='/path/to/data/' ^
-i='image1.tif;image2.tif;image3.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 13/10/2018

MergeLineSegments

Vector lines can sometimes contain two features that are connected by a shared end vertex. This tool identifies connected line features in an input vector file (--input) and merges them in the output file (--output). Two line features are merged if their ends are coincident, and are not coincident with any other feature (i.e. a bifurcation junction). End vertices are considered to be coincident if they are within the specified snap distance (--snap).

See Also: SplitWithLines

Parameters:

FlagDescription
-i, --inputInput vector file
-o, --outputOutput vector file
--snapSnap tolerance

Python function:

wbt.merge_line_segments(
    i, 
    output, 
    snap=0.0, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/04/2019

Last Modified: 09/04/2019

MinAbsoluteOverlay

This tool can be used to find the minimum absolute (non-negative) value in each cell of a grid from a set of input images (--inputs). NoData values in any of the input images will result in a NoData pixel in the output image.

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: MinOverlay, MaxAbsoluteOverlay, MaxOverlay

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=MinAbsoluteOverlay -v ^
--wd='/path/to/data/' -i='image1.tif;image2.tif;image3.tif' ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 13/10/2018

MinOverlay

This tool can be used to find the minimum value in each cell of a grid from a set of input images (--inputs). NoData values in any of the input images will result in a NoData pixel in the output image (--output). It is similar to the Min mathematical tool, except that it will accept more than two input images.

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: MaxOverlay, MaxAbsoluteOverlay, MinAbsoluteOverlay, Min

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=MinOverlay -v --wd='/path/to/data/' ^
-i='image1.tif;image2.tif;image3.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 13/10/2018

MultiplyOverlay

This tool multiplies a stack of raster images (--inputs) on a pixel-by-pixel basis. This tool is particularly well suited when you need to create a masking layer from the combination of several Boolean rasters, i.e. for constraint mapping applications. NoData values in any of the input images will result in a NoData pixel in the output image (--output).

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: SumOverlay, WeightedSum

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=MultiplyOverlay -v ^
--wd='/path/to/data/' -i='image1.dep;image2.dep;image3.tif' ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/02/2022

Last Modified: 04/02/2022

PercentEqualTo

This tool calculates the percentage of a raster stack (--inputs) that have cell values equal to an input comparison raster. The user must specify the name of the value raster (--comparison), the names of the raster files contained in the stack, and an output raster file name (--output). The tool, working on a cell-by-cell basis, will count the number of rasters within the stack that have the same grid cell value as the corresponding grid cell in the comparison raster. This count is then expressed as a percentage of the number of rasters contained within the stack and output. If any of the rasters within the stack contain the NoData value, the corresponding grid cell in the output raster will be assigned NoData.

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: PercentGreaterThan, PercentLessThan

Parameters:

FlagDescription
-i, --inputsInput raster files
--comparisonInput comparison raster file
-o, --outputOutput raster file

Python function:

wbt.percent_equal_to(
    inputs, 
    comparison, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PercentEqualTo -v --wd='/path/to/data/' ^
-i='image1.tif;image2.tif;image3.tif' --comparison='comp.tif' ^
-o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 31/01/2019

PercentGreaterThan

This tool calculates the percentage of a raster stack (--inputs) that have cell values greater than an input comparison raster. The user must specify the name of the value raster (--comparison), the names of the raster files contained in the stack, and an output raster file name (--output). The tool, working on a cell-by-cell basis, will count the number of rasters within the stack with larger grid cell values greater than the corresponding grid cell in the comparison raster. This count is then expressed as a percentage of the number of rasters contained within the stack and output. If any of the rasters within the stack contain the NoData value, the corresponding grid cell in the output raster will be assigned NoData.

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: PercentLessThan, PercentEqualTo

Parameters:

FlagDescription
-i, --inputsInput raster files
--comparisonInput comparison raster file
-o, --outputOutput raster file

Python function:

wbt.percent_greater_than(
    inputs, 
    comparison, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PercentGreaterThan -v ^
--wd='/path/to/data/' -i='image1.tif;image2.tif;image3.tif' ^
--comparison='comp.tif' -o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 31/01/2019

PercentLessThan

This tool calculates the percentage of a raster stack (--inputs) that have cell values less than an input comparison raster. The user must specify the name of the value raster (--comparison), the names of the raster files contained in the stack, and an output raster file name (--output). The tool, working on a cell-by-cell basis, will count the number of rasters within the stack with larger grid cell values less than the corresponding grid cell in the comparison raster. This count is then expressed as a percentage of the number of rasters contained within the stack and output. If any of the rasters within the stack contain the NoData value, the corresponding grid cell in the output raster will be assigned NoData.

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: PercentGreaterThan, PercentEqualTo

Parameters:

FlagDescription
-i, --inputsInput raster files
--comparisonInput comparison raster file
-o, --outputOutput raster file

Python function:

wbt.percent_less_than(
    inputs, 
    comparison, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PercentLessThan -v ^
--wd='/path/to/data/' -i='image1.tif;image2.tif;image3.tif' ^
--comparison='comp.tif' -o='output.tif' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 31/01/2019

PickFromList

This tool outputs the cell value from a raster stack specified (--inputs) by a position raster (--pos_input). The user must specify the name of the position raster, the names of the raster files contained in the stack (i.e. group of rasters), and an output raster file name (--output). The tool, working on a cell-by-cell basis, will assign the value to the output grid cell contained in the corresponding cell in the stack image in the position specified by the cell value in the position raster. Importantly, the positions raster should be in zero-based order. That is, the first image in the stack should be assigned the value zero, the second raster is assigned 1, and so on.

At least two input rasters are required to run this tool. Each of the input rasters must share the same number of rows and columns and spatial extent. An error will be issued if this is not the case.

See Also: CountIf

Parameters:

FlagDescription
-i, --inputsInput raster files
--pos_inputInput position raster file
-o, --outputOutput raster file

Python function:

wbt.pick_from_list(
    inputs, 
    pos_input, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PickFromList -v --wd='/path/to/data/' ^
--pos_input=position.tif -i='image1.tif;image2.tif;image3.tif' ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 13/10/2018

Polygonize

This tool outputs a vector polygon layer from two or more intersecting line features contained in one or more input vector line files. Each space enclosed by the intersecting line set is converted to polygon added to the output layer. This tool should not be confused with the LinesToPolygons tool, which can be used to convert a vector file of polylines into a set of polygons, simply by closing each line feature. The LinesToPolygons tool does not deal with line intersection in the same way that the Polygonize tool does.

See Also: LinesToPolygons

Parameters:

FlagDescription
-i, --inputsInput vector polyline file
-o, --outputOutput vector polygon file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=Polygonize -v --wd="/path/to/data/" ^
-i='lines1.shp;lines2.shp;lines3.shp' -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/10/2018

Last Modified: 28/10/2018

SplitWithLines

This tool splits the lines or polygons in one layer using the lines in another layer to define the breaking points. Intersection points between geometries in both layers are considered as split points. The input layer (--input) can be of either POLYLINE or POLYGON ShapeType and the output file will share this geometry type. The user must also specify an split layer (--split), of POLYLINE ShapeType, used to bisect the input geometries.

Each split geometry's attribute record will contain FID and PARENT_FID values and all of the attributes (excluding FID's) of the input layer.

See Also: 'MergeLineSegments'

Parameters:

FlagDescription
-i, --inputInput vector line or polygon file
--splitInput vector polyline file
-o, --outputOutput vector file

Python function:

wbt.split_with_lines(
    i, 
    split, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SplitWithLines -v --wd="/path/to/data/" ^
--input=polygons.shp --split=lines.shp -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 17/10/2018

Last Modified: 08/04/2019

SumOverlay

This tool calculates the sum for each grid cell from a group of raster images (--inputs). NoData values in any of the input images will result in a NoData pixel in the output image (--output).

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: WeightedSum, MultiplyOverlay

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=SumOverlay -v --wd='/path/to/data/' ^
-i='image1.dep;image2.dep;image3.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/09/2018

Last Modified: 13/10/2018

SymmetricalDifference

This tool will remove all the overlapping features, or parts of overlapping features, between input and overlay vector files, outputting only the features that occur in one of the two inputs but not both. The Symmetrical Difference is related to the Boolean exclusive-or (XOR) operation in set theory and is one of the common vector overlay operations in GIS. The user must specify the names of the input and overlay vector files as well as the output vector file name. The tool operates on vector points, lines, or polygon, but both the input and overlay files must contain the same ShapeType.

The Symmetrical Difference can also be derived using a combination of other vector overlay operations, as either (A union B) difference (A intersect B), or (A difference B) union (B difference A).

The attributes of the two input vectors will be merged in the output attribute table. Fields that are duplicated between the inputs will share a single attribute in the output. Fields that only exist in one of the two inputs will be populated by null in the output table. Multipoint ShapeTypes however will simply contain a single output feature identifier (FID) attribute. Also, note that depending on the ShapeType (polylines and polygons), Measure and Z ShapeDimension data will not be transferred to the output geometries. If the input attribute table contains fields that measure the geometric properties of their associated features (e.g. length or area), these fields will not be updated to reflect changes in geometry shape and size resulting from the overlay operation.

See Also: Intersect, Difference, Union, Clip, Erase

Parameters:

FlagDescription
-i, --inputInput vector file
--overlayInput overlay vector file
-o, --outputOutput vector file
--snapSnap tolerance

Python function:

wbt.symmetrical_difference(
    i, 
    overlay, 
    output, 
    snap=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SymmetricalDifference -v ^
--wd="/path/to/data/" -input=layer1.shp --overlay=layer2.shp ^
-o=out_file.shp --snap=0.0000001 

Source code on GitHub

Author: Dr. John Lindsay

Created: 5/11/2018

Last Modified: 08/11/2018

Union

This tool splits vector layers at their overlaps, creating a layer containing all the portions from both input and overlay layers. The Union is related to the Boolean OR operation in set theory and is one of the common vector overlay operations in GIS. The user must specify the names of the input and overlay vector files as well as the output vector file name. The tool operates on vector points, lines, or polygon, but both the input and overlay files must contain the same ShapeType.

The attributes of the two input vectors will be merged in the output attribute table. Fields that are duplicated between the inputs will share a single attribute in the output. Fields that only exist in one of the two inputs will be populated by null in the output table. Multipoint ShapeTypes however will simply contain a single output feature identifier (FID) attribute. Also, note that depending on the ShapeType (polylines and polygons), Measure and Z ShapeDimension data will not be transferred to the output geometries. If the input attribute table contains fields that measure the geometric properties of their associated features (e.g. length or area), these fields will not be updated to reflect changes in geometry shape and size resulting from the overlay operation.

See Also: Intersect, Difference, SymmetricalDifference, Clip, Erase

Parameters:

FlagDescription
-i, --inputInput vector file
--overlayInput overlay vector file
-o, --outputOutput vector file
--snapSnap tolerance

Python function:

wbt.union(
    i, 
    overlay, 
    output, 
    snap=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Union -v --wd="/path/to/data/" ^
-input=layer1.shp --overlay=layer2.shp -o=out_file.shp ^
--snap=0.0000001 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/11/2018

Last Modified: 08/04/2019

UpdateNodataCells

This tool will assign the NoData valued cells in an input raster (--input1) the values contained in the corresponding grid cells in a second input raster (--input2). This operation is sometimes necessary because most other overlay operations exclude areas of NoData values from the analysis. This tool can be used when there is need to update the values of a raster within these missing data areas.

See Also: IsNodata

Parameters:

FlagDescription
--input1Input raster file 1
--input2Input raster file 2; update layer
-o, --outputOutput raster file

Python function:

wbt.update_nodata_cells(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=UpdateNodataCells -v ^
--wd="/path/to/data/" --input1=input1.tif ^
--input2=update_layer.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/05/2020

Last Modified: 26/05/2020

WeightedOverlay

This tool performs a weighted overlay on multiple input images. It can be used to combine multiple factors with varying levels of weight or relative importance. The WeightedOverlay tool is similar to the WeightedSum tool but is more powerful because it automatically converts the input factors to a common user-defined scale and allows the user to specify benefit factors and cost factors. A benefit factor is a factor for which higher values are more suitable. A cost factor is a factor for which higher values are less suitable. By default, WeightedOverlay assumes that input images are benefit factors, unless a cost value of 'true' is entered in the cost array. Constraints are absolute restriction with values of 0 (unsuitable) and 1 (suitable). This tool is particularly useful for performing multi-criteria evaluations (MCE).

Notice that the algorithm will convert the user-defined factor weights internally such that the sum of the weights is always equal to one. As such, the user can specify the relative weights as decimals, percentages, or relative weightings (e.g. slope is 2 times more important than elevation, in which case the weights may not sum to 1 or 100).

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

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

Parameters:

FlagDescription
--factorsInput factor raster files
-w, --weightsWeight values, contained in quotes and separated by commas or semicolons. Must have the same number as factors
--costBoolean array indicating which factors are cost factors, contained in quotes and separated by commas or semicolons. Must have the same number as factors
--constraintsInput constraints raster files
-o, --outputOutput raster file
--scale_maxSuitability scale maximum value (common values are 1.0, 100.0, and 255.0)

Python function:

wbt.weighted_overlay(
    factors, 
    weights, 
    output, 
    cost=None, 
    constraints=None, 
    scale_max=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=WeightedOverlay -v ^
--wd='/path/to/data/' ^
--factors='image1.tif;image2.tif;image3.tif' ^
--weights='0.3;0.2;0.5' --cost='false;false;true' -o=output.tif ^
--scale_max=100.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 07/05/2018

Last Modified: 13/10/2018

WeightedSum

This tool performs a weighted-sum overlay on multiple input raster images. If you have a stack of rasters that you would like to sum, each with an equal weighting (1.0), then use the SumOverlay tool instead.

Warning:

Each of the input rasters must have the same spatial extent and number of rows and columns.

See Also: SumOverlay

Parameters:

FlagDescription
-i, --inputsInput raster files
-w, --weightsWeight values, contained in quotes and separated by commas or semicolons
-o, --outputOutput raster file

Python function:

wbt.weighted_sum(
    inputs, 
    weights, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=WeightedSum -v --wd='/path/to/data/' ^
-i='image1.tif;image2.tif;image3.tif' --weights='0.3;0.2;0.5' ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 13/10/2018

GIS Analysis → Patch Shape Tools

BoundaryShapeComplexity

This tools calculates a type of shape complexity index for raster objects, focused on the complexity of the boundary of polygons. The index uses the LineThinning tool to estimate a skeletonized network for each input raster polygon. The Boundary Shape Complexity (BSC) index is then calculated as the percentage of the skeletonized network belonging to exterior links. Polygons with more complex boundaries will possess more branching skeletonized networks, with each spur in the boundary possessing a short exterior branch. The two longest exterior links in the network are considered to be part of the main network. Therefore, polygons of complex shaped boundaries will have a higher percentage of their skeleton networks consisting of exterior links. It is expected that simple convex hulls should have relatively low BSC index values.

Objects in the input raster (--input) are designated by their unique identifiers. Identifier values should be positive, non-zero whole numbers.

See Also: ShapeComplexityIndexRaster, LineThinning

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 17/02/2019

Last Modified: 17/02/2019

CompactnessRatio

The compactness ratio is an indicator of polygon shape complexity. The compactness ratio is defined as the polygon area divided by its perimeter. Unlike some other shape parameters (e.g. ShapeComplexityIndex), compactness ratio does not standardize to a simple Euclidean shape. Although widely used for landscape analysis, compactness ratio, like its inverse, the PerimeterAreaRatio, exhibits the undesirable property of polygon size dependence (Mcgarigal et al. 2002). That is, holding shape constant, an increase in polygon size will cause a change in the compactness ratio.

The output data will be contained in the input vector's attribute table as a new field (COMPACT).

See Also: PerimeterAreaRatio, ShapeComplexityIndex, RelatedCircumscribingCircle

Parameters:

FlagDescription
-i, --inputInput vector polygon file

Python function:

wbt.compactness_ratio(
    i, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/09/2018

Last Modified: 13/10/2018

EdgeProportion

This tool will measure the edge proportion, i.e. the proportion of grid cells in a patch that are located along the patch's boundary, for an input raster image (--input). Edge proportion is an indicator of polygon shape complexity and elongation. The user must specify the name of the output raster file (--output), which will be raster layer containing the input features assigned the edge proportion. The user may also optionally choose to output text data for easy input to a spreadsheet or database.

Objects in the input raster are designated by their unique identifiers. Identifier values must be positive, non-zero whole numbers.

See Also: ShapeComplexityIndexRaster, LinearityIndex, ElongationRatio

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--output_textflag indicating whether a text report should also be output

Python function:

wbt.edge_proportion(
    i, 
    output, 
    output_text=False, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/07/2017

Last Modified: 18/10/2019

ElongationRatio

This tool can be used to calculate the elongation ratio for vector polygons. The elongation ratio values calculated for each vector polygon feature will be placed in the accompanying database file (.dbf) as an elongation field (ELONGATION).

The elongation ratio (E) is:

E = 1 - S / L

Where S is the short-axis length, and L is the long-axis length. Axes lengths are determined by estimating the minimum bounding box.

The elongation ratio provides similar information as the Linearity Index. The ratio is not an adequate measure of overall polygon narrowness, because a highly sinuous but narrow polygon will have a low linearity (elongation) owing to the compact nature of these polygon.

Parameters:

FlagDescription
-i, --inputInput vector polygon file

Python function:

wbt.elongation_ratio(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ElongationRatio -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

FindPatchOrClassEdgeCells

This tool will identify all grid cells situated along the edges of patches or class features within an input raster (--input). Edge cells in the output raster (--output) will have the patch identifier value assigned in the corresponding grid cell. All non-edge cells will be assigned zero in the output raster. Patches (or classes) are designated by positive, non-zero values in the input image. Zero-valued and NoData-valued grid cells are interpreted as background cells by the tool.

See Also: EdgeProportion

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/07/2017

Last Modified: 13/10/2018

HoleProportion

This calculates the proportion of the total area of a polygon's holes (i.e. islands) relative to the area of the polygon's hull. It can be a useful measure of shape complexity, or how discontinuous a patch is. The user must specify the name of the input vector file and the output data will be contained within the input vector's database file as a new field (HOLE_PROP).

See Also: ShapeComplexityIndex, ElongationRatio, PerimeterAreaRatio

Parameters:

FlagDescription
-i, --inputInput vector polygon file

Python function:

wbt.hole_proportion(
    i, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/09/2018

Last Modified: 26/09/2018

LinearityIndex

This tool calculates the linearity index of polygon features based on a regression analysis. The index is simply the coefficient of determination (r-squared) calculated from a regression analysis of the x and y coordinates of the exterior hull nodes of a vector polygon. Linearity index is a measure of how well a polygon can be described by a straight line. It is a related index to the ElongationRatio, but is more efficient to calculate as it does not require finding the minimum bounding box. The Pearson correlation coefficient between linearity index and the elongation ratio for a large data set of lake polygons in northern Canada was found to be 0.656, suggesting a moderate level of association between the two measures of polygon linearity. Note that this index is not useful for identifying narrow yet sinuous polygons, such as meandering rivers.

The only required input is the name of the file. The linearity values calculated for each vector polygon feature will be placed in the accompanying attribute table as a new field (LINEARITY).

See Also: ElongationRatio, PatchOrientation

Parameters:

FlagDescription
-i, --inputInput vector polygon file

Python function:

wbt.linearity_index(
    i, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/10/2018

Last Modified: 13/10/2018

NarrownessIndex

This tools calculates a type of shape narrowness index (NI) for raster objects. The index is equal to:

NI = A / (πMD2)

where A is the patch area and MD is the maximum distance-to-edge of the patch. Circular-shaped patches will have a narrowness index near 1.0, while more narrow patch shapes will have higher index values. The index may be conceptualized as the ratio of the patch area to the area of the largest contained circle, although in practice the circle defined by the radius of the maximum distance-to-edge will often fall outside the patch boundaries.

Objects in the input raster (--input) are designated by their unique identifiers. Identifier values must be positive, non-zero whole numbers. It is quite common for identifiers to be set using the Clump tool applied to some kind of thresholded raster.

See Also: LinearityIndex, ElongationRatio, Clump

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 17/02/2019

Last Modified: 17/02/2019

PatchOrientation

This tool calculates the orientation of polygon features based on the slope of a reduced major axis (RMA) regression line. The regression analysis use the vertices of the exterior hull nodes of a vector polygon. The only required input is the name of the vector polygon file. The orientation values, measured in degrees from north, will be placed in the accompanying attribute table as a new field (ORIENT). The value of the orientation measure for any polygon will depend on how elongated the feature is.

Note that the output values are polygon orientations and not true directions. While directions may take values ranging from 0-360, orientation is expressed as an angle between 0 and 180 degrees clockwise from north. Lastly, the orientation measure may become unstable when polygons are oriented nearly vertical or horizontal.

See Also: LinearityIndex, ElongationRatio

Parameters:

FlagDescription
-i, --inputInput vector polygon file

Python function:

wbt.patch_orientation(
    i, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/10/2018

Last Modified: 16/10/2018

PerimeterAreaRatio

The perimeter-area ratio is an indicator of polygon shape complexity. Unlike some other shape parameters (e.g. shape complexity index), perimeter-area ratio does not standardize to a simple Euclidean shape. Although widely used for landscape analysis, perimeter-area ratio exhibits the undesirable property of polygon size dependence (Mcgarigal et al. 2002). That is, holding shape constant, an increase in polygon size will cause a decrease in the perimeter-area ratio. The perimeter-area ratio is the inverse of the compactness ratio.

The output data will be displayed as a new field (P_A_RATIO) in the input vector's database file.

Parameters:

FlagDescription
-i, --inputInput vector polygon file

Python function:

wbt.perimeter_area_ratio(
    i, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/09/2018

Last Modified: 03/03/2020

RadiusOfGyration

This can be used to calculate the radius of gyration (RoG) for the polygon features within a raster image. RoG measures how far across the landscape a polygon extends its reach on average, given by the mean distance between cells in a patch (Mcgarigal et al. 2002). The radius of gyration can be considered a measure of the average distance an organism can move within a patch before encountering the patch boundary from a random starting point (Mcgarigal et al. 2002). The input raster grid should contain polygons with unique identifiers greater than zero. The user must also specify the name of the output raster file (where the radius of gyration will be assigned to each feature in the input file) and the specified option of outputting text data.

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--text_outputOptional text output

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 31/12/2017

Last Modified: 18/10/2019

RelatedCircumscribingCircle

This tool can be used to calculate the related circumscribing circle (Mcgarigal et al. 2002) for vector polygon features. The related circumscribing circle values calculated for each vector polygon feature will be placed in the accompanying attribute table as a new field (RC_CIRCLE).

Related circumscribing circle (RCC) is defined as:

RCC = 1 - A / Ac

Where A is the polygon's area and Ac the area of the smallest circumscribing circle.

Theoretically, RelatedCircumscribingCircle ranges from 0 to 1, where a value of 0 indicates a circular polygon and a value of 1 indicates a highly elongated shape. The circumscribing circle provides a measure of polygon elongation. Unlike the ElongationRatio, however, it does not provide a measure of polygon direction in addition to overall elongation. Like the ElongationRatio and LinearityIndex, RelatedCircumscribingCircle is not an adequate measure of overall polygon narrowness, because a highly sinuous but narrow patch will have a low related circumscribing circle index owing to the compact nature of these polygon.

Note: Holes are excluded from the area calculation of polygons.

Parameters:

FlagDescription
-i, --inputInput vector polygon file

Python function:

wbt.related_circumscribing_circle(
    i, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/09/2018

Last Modified: 13/10/2018

ShapeComplexityIndex

This tool provides a measure of overall polygon shape complexity, or irregularity, for vector polygons. Several shape indices have been created to compare a polygon's shape to simple Euclidean shapes (e.g. circles, squares, etc.). One of the problems with this approach is that it inherently convolves the characteristics of polygon complexity and elongation. The Shape Complexity Index (SCI) was developed as a parameter for assessing the complexity of a polygon that is independent of its elongation.

SCI relates a polygon's shape to that of an encompassing convex hull. It is defined as:

SCI = 1 - A / Ah

Where A is the polygon's area and Ah is the area of the convex hull containing the polygon. Convex polygons, i.e. those that do not contain concavities or holes, have a value of 0. As the shape of the polygon becomes more complex, the SCI approaches 1. Note that polygon shape complexity also increases with the greater number of holes (i.e. islands), since holes have the effect of reducing the lake area.

The SCI values calculated for each vector polygon feature will be placed in the accompanying database file (.dbf) as a complexity field (COMPLEXITY).

See Also: ShapeComplexityIndexRaster

Parameters:

FlagDescription
-i, --inputInput vector polygon file

Python function:

wbt.shape_complexity_index(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ShapeComplexityIndex -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

ShapeComplexityIndexRaster

This tools calculates a type of shape complexity index for raster objects. The index is equal to the average number of intersections of the group of vertical and horizontal transects passing through an object. Simple objects will have a shape complexity index of 1.0 and more complex shapes, including those containing numerous holes or are winding in shape, will have higher index values. Objects in the input raster (--input) are designated by their unique identifiers. Identifier values should be positive, non-zero whole numbers.

See Also: ShapeComplexityIndex, BoundaryShapeComplexity

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/02/2019

Last Modified: 16/02/2019

Hydrological Analysis

AverageFlowpathSlope

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

See Also: AverageUpslopeFlowpathLength, BreachDepressions

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/07/2017

Last Modified: 17/01/2019

AverageUpslopeFlowpathLength

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

See Also: MaxUpslopeFlowpathLength, AverageFlowpathSlope, BreachDepressions

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/07/2017

Last Modified: 17/01/2019

Basins

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

...
641281
3202
1684

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

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

See Also: Watershed, D8Pointer, BreachDepressions

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 18/10/2019

BreachDepressions

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

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

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

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

Reference:

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

See Also: BreachDepressionsLeastCost, FillDepressions, FillSingleCellPits

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--max_depthOptional maximum breach depth (default is Inf)
--max_lengthOptional maximum breach channel length (in grid cells; default is Inf)
--flat_incrementOptional elevation increment applied to flat areas
--fill_pitsOptional flag indicating whether to fill single-cell pits

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 24/11/2019

BreachDepressionsLeastCost

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

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

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

cost1 = z1 - (zpit + l × s)

cost2 = z2 - [zpit + (l + 1)s]

accum2 = accum1 + g(cost1 + cost2) / 2.0

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

accum2 = accum1 + cost2

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

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

Reference:

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

See Also: BreachDepressions, FillDepressions, CostPathway

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--distMaximum search distance for breach paths in cells
--max_costOptional maximum breach cost (default is Inf)
--min_distOptional flag indicating whether to minimize breach distances
--flat_incrementOptional elevation increment applied to flat areas
--fillOptional flag indicating whether to fill any remaining unbreached depressions

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/11/2019

Last Modified: 24/11/2019

BreachSingleCellPits

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

See Also: FillDepressions, BreachDepressions, FillSingleCellPits

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 12/10/2018

BurnStreamsAtRoads

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

Reference:

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

See Also: RasterStreamsToVector, RasterizeStreams

Parameters:

FlagDescription
--demInput raster digital elevation model (DEM) file
--streamsInput vector streams file
--roadsInput vector roads file
-o, --outputOutput raster file
--widthMaximum road embankment width, in map units

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 30/10/2019

Last Modified: 29/12/2019

D8FlowAccumulation

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

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

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

Reference:

O'Callaghan, J. F., & Mark, D. M. 1984. The extraction of drainage networks from digital elevation data. Computer Vision, Graphics, and Image Processing, 28(3), 323-344.

See Also: FD8FlowAccumulation, QuinnFlowAccumulation, QinFlowAccumulation, DInfFlowAccumulation, MDInfFlowAccumulation, Rho8Pointer, D8Pointer, BreachDepressionsLeastCost, FillDepressions

Parameters:

FlagDescription
-i, --inputInput raster DEM or D8 pointer file
-o, --outputOutput raster file
--out_typeOutput type; one of 'cells' (default), 'catchment area', and 'specific contributing area'
--logOptional flag to request the output be log-transformed
--clipOptional flag to request clipping the display max by 1%
--pntrIs the input raster a D8 flow pointer rather than a DEM?
--esri_pntrInput D8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/016/2017

Last Modified: 29/08/2021

D8MassFlux

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

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

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

See Also: DInfMassFlux

Parameters:

FlagDescription
--demInput raster DEM file
--loadingInput loading raster file
--efficiencyInput efficiency raster file
--absorptionInput absorption raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: Dec. 29, 2017

Last Modified: 12/10/2018

D8Pointer

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

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

...
641281
3202
1684

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

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

Memory Usage

The peak memory usage of this tool is approximately 10 bytes per grid cell.

Reference:

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

See Also: DInfPointer, FD8Pointer, BreachDepressions, FillDepressions

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/06/2017

Last Modified: 18/10/2019

DInfFlowAccumulation

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

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

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

Reference:

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

See Also: DInfPointer, D8FlowAccumulation, QuinnFlowAccumulation, QinFlowAccumulation, FD8FlowAccumulation, MDInfFlowAccumulation, Rho8Pointer`, BreachDepressionsLeastCost, FillDepressions

Parameters:

FlagDescription
-i, --inputInput raster DEM or D-infinity pointer file
-o, --outputOutput raster file
--out_typeOutput type; one of 'cells', 'sca' (default), and 'ca'
--thresholdOptional convergence threshold parameter, in grid cells; default is infinity
--logOptional flag to request the output be log-transformed
--clipOptional flag to request clipping the display max by 1%
--pntrIs the input raster a D-infinity flow pointer rather than a DEM?

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/06/2017

Last Modified: 21/02/2020

DInfMassFlux

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

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

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

See Also: D8MassFlux

Parameters:

FlagDescription
--demInput raster DEM file
--loadingInput loading raster file
--efficiencyInput efficiency raster file
--absorptionInput absorption raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: Dec. 29, 2017

Last Modified: 12/10/2018

DInfPointer

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

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

Reference:

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

See Also: DInfFlowAccumulation, BreachDepressions, FillDepressions

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 13/02/2020

DepthInSink

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

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

Reference:

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

See Also: FillDepressions

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--zero_backgroundFlag indicating whether the background value of zero should be used

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 05/12/2019

DepthToWater

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

This tool calculates the cartographic depth-to-water (DTW) index described by Murphy et al. (2009). The DTW index has been shown to be related to soil moisture, and is useful for identifying low-lying positions that are likely to experience surface saturated conditions. In this regard, it is similar to each of WetnessIndex, ElevationAboveStream (HAND), and probability-of-depressions (i.e. StochasticDepressionAnalysis).

The index is the cumulative slope gradient along the least-slope path connecting each grid cell in an input DEM (--dem) to a surface water cell. Tangent slope (i.e. rise / run) is calculated for each grid cell based on the neighbouring elevation values in the input DEM. The algorithm operates much like a cost-accumulation analysis (CostDistance), where the cost of moving through a cell is determined by the cell's tangent slope value and the distance travelled. Therefore, lower DTW values are associated with wetter soils and higher values indicate drier conditions, over longer time periods. Areas of surface water have DTW values of zero. The user must input surface water features, including vector stream lines (--streams) and/or vector waterbody polygons (--lakes, i.e. lakes, ponds, wetlands, etc.). At least one of these two optional water feature inputs must be specified. The tool internally rasterizes these vector features, setting the DTW value in the output raster to zero. DTW tends to increase with greater distances from surface water features, and increases more slowly in flatter topography and more rapidly in steeper settings. Murphy et al. (2009) state that DTW is a probablistic model that assumes uniform soil properties, climate, and vegetation.

Note that DTW values are highly dependent upon the accuracy and extent of the input streams/lakes layer(s).

References:

Murphy, PNC, Gilvie, JO, and Arp, PA (2009) Topographic modelling of soil moisture conditiTons: a comparison and verification of two models. European Journal of Soil Science, 60, 94–109, DOI: 10.1111/j.1365-2389.2008.01094.x.

See Also: WetnessIndex, ElevationAboveStream, StochasticDepressionAnalysis

Parameters:

FlagDescription
--demName of the input raster DEM file
--streamsName of the input streams vector (optional)
--lakesName of the input lakes vector (optional)
-o, --outputName of the output raster image file

Python function:

wbt.depth_to_water(
    dem, 
    output, 
    streams=None, 
    lakes=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=DepthToWater --dem=DEM.tif ^
--streams=streams.shp --lakes=waterbodies.shp -o=output.tif 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 24/05/2022

Last Modified: 24/05/2022

DownslopeDistanceToStream

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

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

See Also: ElevationAboveStream, DistanceToOutlet

Parameters:

FlagDescription
-i, --demInput raster DEM file
--streamsInput raster streams file
-o, --outputOutput raster file
--dinfUse the D-infinity flow algorithm instead of D8?

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 9/07/2017

Last Modified: 04/10/2019

DownslopeFlowpathLength

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

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

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

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

Parameters:

FlagDescription
--d8_pntrInput D8 pointer raster file
--watershedsOptional input watershed raster file
--weightsOptional input weights raster file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/07/2017

Last Modified: 18/10/2019

EdgeContamination

This tool identifs grid cells in a DEM for which the upslope area extends beyond the raster data extent, so-called 'edge-contamined cells'. If a significant number of edge contaminated cells intersect with your area of interest, it is likely that any estimate of upslope area (i.e. flow accumulation) will be under-estimated.

The user must specify the name (--dem) of the input digital elevation model (DEM) and the output file (--output). The DEM must have been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achieved using either the BreachDepressions (also BreachDepressionsLeastCost) or FillDepressions tool.

Additionally, the user must specify the type of flow algorithm used for the analysis (-flow_type), which must be one of 'd8', 'mfd', or 'dinf', based on each of the D8FlowAccumulation, FD8FlowAccumulation, DInfFlowAccumulation methods respectively.

See Also: D8FlowAccumulation, FD8FlowAccumulation, DInfFlowAccumulation

Parameters:

FlagDescription
-d, --demName of the input DEM raster file; must be depressionless
-o, --outputName of the output raster file
--flow_typeFlow algorithm type, one of 'd8', 'mfd', or 'dinf'
--zfactorOptional multiplier for when the vertical and horizontal units are not the same

Python function:

wbt.edge_contamination(
    dem, 
    output, 
    flow_type="mfd", 
    zfactor="", 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=EdgeContamination --dem=DEM.tif ^
--output=edge_cont.tif --flow_type='dinf' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 23/07/2021

Last Modified: 23/07/2021

ElevationAboveStream

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

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

Reference:

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

See Also: ElevationAboveStreamEuclidean, DownslopeDistanceToStream, ElevAbovePit, BreachDepressions

Parameters:

FlagDescription
-i, --demInput raster DEM file
--streamsInput raster streams file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: July 9, 2017

Last Modified: 12/10/2018

ElevationAboveStreamEuclidean

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

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

Reference:

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

See Also: ElevationAboveStream, DownslopeDistanceToStream, ElevAbovePit

Parameters:

FlagDescription
-i, --demInput raster DEM file
--streamsInput raster streams file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/03/2018

Last Modified: 12/10/2018

Fd8FlowAccumulation

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

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

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

Reference:

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

See Also: D8FlowAccumulation, QuinnFlowAccumulation, QinFlowAccumulation, DInfFlowAccumulation, MDInfFlowAccumulation, Rho8Pointer

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--out_typeOutput type; one of 'cells', 'specific contributing area' (default), and 'catchment area'
--exponentOptional exponent parameter; default is 1.1
--thresholdOptional convergence threshold parameter, in grid cells; default is infinity
--logOptional flag to request the output be log-transformed
--clipOptional flag to request clipping the display max by 1%

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 15/07/2021

Fd8Pointer

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

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

...
641281
3202
1684

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

Reference:

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

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

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 12/10/2018

FillBurn

Burns streams into a digital elevation model (DEM) using the FillBurn (Saunders, 1999) method which produces a hydro-enforced DEM. This tool uses the algorithm described in:

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

And:

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

The TopologicalBreachBurn tool, contained within the Whitebox Toolset Extension (WTE), should be preferred to this FillBurn, because it accounts for the topological errors that frequently occur when burning vector streams into a DEM.

See Also: TopologicalBreachBurn, PruneVectorStreams

Parameters:

FlagDescription
--demInput raster DEM file
--streamsInput vector streams file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/04/2018

Last Modified: 22/10/2019

FillDepressions

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

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

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

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

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--fix_flatsOptional flag indicating whether flat areas should have a small gradient applied
--flat_incrementOptional elevation increment applied to flat areas
--max_depthOptional maximum depression depth to fill

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 12/12/2019

FillDepressionsPlanchonAndDarboux

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

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

Reference:

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

See Also: FillDepressions, BreachDepressionsLeastCost

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--fix_flatsOptional flag indicating whether flat areas should have a small gradient applied
--flat_incrementOptional elevation increment applied to flat areas

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/02/2020

Last Modified: 02/02/2020

FillDepressionsWangAndLiu

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

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

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

Reference:

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

See Also: FillDepressions, BreachDepressionsLeastCost, BreachDepressions, FillMissingData

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--fix_flatsOptional flag indicating whether flat areas should have a small gradient applied
--flat_incrementOptional elevation increment applied to flat areas

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 05/12/2019

FillSingleCellPits

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

See Also: BreachDepressions, FillDepressions, BreachSingleCellPits

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

FindNoFlowCells

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

See Also: D8Pointer, BreachDepressions

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

FindParallelFlow

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

See Also: D8Pointer

Parameters:

FlagDescription
--d8_pntrInput D8 pointer raster file
--streamsInput raster streams file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

FlattenLakes

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

See Also: FillDepressions

Parameters:

FlagDescription
-i, --demInput raster DEM file
--lakesInput lakes vector polygons file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 29/03/2018

Last Modified: 28/05/2020

FloodOrder

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

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

Reference:

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

See Also: FillDepressions

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/07/2017

Last Modified: 12/10/2018

FlowAccumulationFullWorkflow

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

Parameters:

FlagDescription
-i, --demInput raster DEM file
--out_demOutput raster DEM file
--out_pntrOutput raster flow pointer file
--out_accumOutput raster flow accumulation file
--out_typeOutput type; one of 'cells', 'sca' (default), and 'ca'
--logOptional flag to request the output be log-transformed
--clipOptional flag to request clipping the display max by 1%
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 18/10/2019

FlowLengthDiff

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

See Also: MaxBranchLength

Parameters:

FlagDescription
--d8_pntrInput D8 pointer raster file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/07/2017

Last Modified: 18/10/2019

Hillslopes

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

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

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

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

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

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/07/2017

Last Modified: 18/10/2019

HydrologicConnectivity

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

Theory

This tool calculates two indices related to hydrologic connectivity within catchments, the downslope unsaturated length (DUL) and the upslope disconnected saturated area (UDSA). Both of these hydrologic indices are based on the topographic wetness index (WetnessIndex), which measures the propensity for a site to be saturated to the surface, and therefore, to contribute to surface runoff. The wetness index (WI) is commonly used in hydrologic modelling, and famously in the TOPMODEL, to simulate variable source area (VSA) dynamics within catchments. The VSA is a dynamic region of surface-saturated soils within catchments that contributes fast overland flow to downslope streams during periods of precipitation. As a catchment's soil saturation deficit decreases ('wetting up'), areas with increasingly lower WI values become saturated to the surface. That is, areas of high WI are the first to become saturated and as the moisture deficit decreases, lower WI-valued cells become saturated, increasing the spatial extent of the source area. As a catchment dries out, the opposite effect occurs. The distribution of WI can therefore be used to map the spatial dyanamics of the VSA. However, the assumption in the TOPMODEL is that any rainfall over surface saturated areas will contribute to fast overland flow pathways and to stream discharge within the time step.

This method therefore implicitly assumes that all surface saturated grid cells are connected by continuously saturated areas along the downslope flow path connecting the cells to the stream. By comparison, Lane et al. (2004) proposed a modified WI, known as the network index (NI), which allowed for the modelling of disconnected, non-contributing saturated areas. The NI is essentially the downslope minimum WI. Grid cells for which WI > NI are likely to be disconnected during certain conditions from downslope streams, while similarly WI-valued cells are contributing. During these periods, any surface runoff from these cells is likely to contribute to downslope re-infilitration rather than directly to stream discharge via overland flow. This has implications for the timing and quality of stream discharge.

The DUL and UDSA indices extend the notion of the NI by mapping areas within catchments that are likely, at least during certain periods, to be sites of disconnected, non-contributing saturated areas and sites of re-infiltation respectively. These combined indices allow hydrologists to study the hydrologic connectivity and disconnectivity among areas within catchments.

The DUL (see image below) is defined for a grid cell as the number of downslope cells with a WI value lower than the current cell. Areas with non-zero DUL are likely to become fully saturated, and to contribute to overland flow, before they are directly connected to downslope areas and can contribute to stream flow. Under the appropriate catchment saturation deficit conditions, these are sites of disconnected, non-contributing saturated areas. When non-zero DUL cells are initially saturated, their precipitation excess will contribute to downslope re-infiltation, lessening the catchment's overall saturation deficit, rather than contributing to stormflow.

The UDSA (see image below) is defined for a grid cell as the number of upslope cells with a WI value higher than the current cell. Areas with non-zero UDSA are likely to have saturation deficits that are at least partly satisfied by local re-infiltation of overland flow from upslope areas. These non-zero UDSA cells are key sites causing the hydrologic disconnectivity of the catchment during certain conditions.

In the original Lane et al. (2004) NI paper, the authors state that the calculation of the index requires a unique, single downslope flow path for each grid cell. Therefore, the authors used the D8 single-direction flow algorithm to calculate NI. While the D8 method works well to model flow in convergent and channelized areas, it is generally recognized as a poor method for estimating WI on hillslopes, where divergent, non-chanellized flow dominates. Furthermore, the use of the D8 algorithm implied that the only way that WI can decrease downslope is for slope gradient to decrease, since specific contributing area only increases downslope with the D8 method. However, theoretically, WI may also decrease downslope due to flow dispersion, which allows for the upslope area (a surrogate for discharge) to be spread over a larger downslope dispersal area. The original NI formulation could not account for this effect.

Thus, in the implementation of the HydrologicConnectivity tool, WI is first calculated using the multiple flow-direction (MFD) algorithm described by Quinn et al. (1995), which is commonly used to estimate WI. While this implies that there are a multitude of potential flow pathways connecting each grid cell to a downstream location, in reality, if the flow path that follows the path of maximum WI issuing from a cell experiences a reduction in WI (to the point where it becomes less than the issuing cell's WI), then we can safely assume that re-infiltration occurs and the issuing cell is at times disconnected from downslope sites. Thus, after WI has been estimated using the QuinnFlowAccumulation algorithm, flow directions, which are used to calculate upslope and downslope flow paths for calculating the two indices, are approximated by identifying the downslope neighbour of highest WI value for each grid cell.

Operation

The user must specify the name of the input digital elevation model (DEM; --dem), and the output DUL and UDSA rasters (--output1 and --output2). The DEM must have been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achived using either the BreachDepressions (also BreachDepressionsLeastCost) or FillDepressions tool. The remaining two parameters are associated with the calculation of the Quinn et al. (1995) flow accumulation (QuinnFlowAccumulation), used to estimate WI. A value must be specified for the exponent parameter (--exponent), a number that controls the degree of dispersion in the flow-accumulation grid. A lower value yields greater apparent flow dispersion across divergent hillslopes. The exponent value (h) should probably be less than 10.0 and values between 1 and 2 are most common. The following equations are used to calculate the portion flow (Fi) given to each neighbour, i:

Fi = Li(tanβ)p / Σi=1n[Li(tanβ)p]

p = (A / threshold + 1)h

Where Li is the contour length, and is 0.5×grid size for cardinal directions and 0.354×grid size for diagonal directions, n = 8, and represents each of the eight neighbouring grid cells, and, A is the flow accumultation value assigned to the current grid cell, that is being apportioned downslope. The non-dispersive, channel initiation threshold (--threshold) is a flow-accumulation value (measured in upslope grid cells, which is directly proportional to area) above which flow dispersion is no longer permited. Grid cells with flow-accumulation values above this threshold will have their flow routed in a manner that is similar to the D8 single-flow-direction algorithm, directing all flow towards the steepest downslope neighbour. This is usually done under the assumption that flow dispersion, whilst appropriate on hillslope areas, is not realistic once flow becomes channelized. Importantly, the --threshold parameter sets the spatial extent of the stream network, with lower values resulting in more extensive networks.

References:

Beven K.J., Kirkby M.J., 1979. A physically-based, variable contributing area model of basin hydrology. Hydrological Sciences Bulletin 24: 43–69.

Lane, S.N., Brookes, C.J., Kirkby, M.J. and Holden, J., 2004. A network‐index‐based version of TOPMODEL for use with high‐resolution digital topographic data. Hydrological processes, 18(1), pp.191-201.

Quinn, P. F., K. J. Beven, Lamb, R. 1995. The in (a/tanβ) index: How to calculate it and how to use it within the topmodel framework. Hydrological processes 9(2): 161-182.

See Also: WetnessIndex, QuinnFlowAccumulation

Parameters:

FlagDescription
-d, --demName of the input DEM raster file; must be depressionless
--output1Name of the output downslope unsaturated length (DUL) file
--output2Name of the output upslope disconnected saturated area (UDSA) file
--exponentOptional exponent parameter; default is 1.0
--thresholdOptional convergence threshold parameter, in grid cells; default is infinity

Python function:

wbt.hydrologic_connectivity(
    dem, 
    output1, 
    output2, 
    exponent=1.0, 
    threshold=None, 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=HydrologicConnectivity --dem=DEM.tif ^
--output1=DUL.tif --output2=UDSA.tif --exponent=1.1 ^
--threshold=10000 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 08/07/2021

Last Modified: 08/07/2021

ImpoundmentSizeIndex

This tool can be used to calculate the impoundment size index (ISI) from a digital elevation model (DEM). The ISI is a land-surface parameter related to the size of the impoundment that would result from inserting a dam of a user-specified maximum length (--damlength) into each DEM grid cell. The tool requires the user to specify the name of one or more of the possible outputs, which include the mean flooded depth (--out_mean), the maximum flooded depth (--out_max), the flooded volume (--out_volume), the flooded area (--out_area), and the dam height (--out_dam_height).

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

Reference:

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

See Also: InsertDams, StochasticDepressionAnalysis

Parameters:

FlagDescription
-i, --demInput raster DEM file
--out_meanOutput mean flooded depth file
--out_maxOutput maximum flooded depth file
--out_volumeOutput flooded volume file
--out_areaOutput flooded area file
--out_dam_heightOutput dam height file
--damlengthMaximum length of the dam

Python function:

wbt.impoundment_size_index(
    dem, 
    damlength, 
    out_mean=None, 
    out_max=None, 
    out_volume=None, 
    out_area=None, 
    out_dam_height=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/05/2018

Last Modified: 12/10/2018

InsertDams

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

Reference:

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

See Also: ImpoundmentSizeIndex, StochasticDepressionAnalysis

Parameters:

FlagDescription
-i, --demInput raster DEM file
--dam_ptsInput vector dam points file
-o, --outputOutput file
--damlengthMaximum length of the dam

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/02/2020

Last Modified: 20/02/2020

Isobasins

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

The tool can optionally (--connections) output a CSV table that contains the upstream/downstream connections among isobasins. That is, this table will identify the downstream basin of each isobasin, or will list N/A in the event that there is no downstream basin, i.e. if it drains to an edge. Additionally, the CSV file will contain information about the number of grid cells in each isobasin and the isobasin outlet's row and column number and flow direction. The output CSV file will have the same name as the output raster, but with a *.csv file extension.

See Also: Watershed, Basins, BreachDepressions, FillDepressions

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--sizeTarget basin size, in grid cells
--connectionsOutput upstream-downstream flow connections among basins?

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 03/12/2017

Last Modified: 24/07/2020

JensonSnapPourPoints

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

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

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

Reference:

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

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

See Also: Watershed, SnapPourPoints, D8FlowAccumulation

Parameters:

FlagDescription
--pour_ptsInput vector pour points (outlet) file
--streamsInput raster streams file
-o, --outputOutput vector file
--snap_distMaximum snap distance in map units

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 12/10/2018

LongestFlowpath

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

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

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

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

Parameters:

FlagDescription
-i, --demInput raster DEM file
--basinsInput raster basins file
-o, --outputOutput vector file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 29/10/2018

Last Modified: 29/10/2018

LowPointsOnHeadwaterDivides

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

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

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

See Also: RemoveShortStreams

Parameters:

FlagDescription
-d, --demName of the input DEM raster file
--streamsName of the input stream channel raster file
-o, --outputName of the output vector file

Python function:

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

Command-line Interface:

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

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 12/04/2021

Last Modified: 12/04/2021

MaxUpslopeFlowpathLength

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

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

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 28/10/2019

MaxUpslopeValue

This tool is used to can be used calculate the maximum upslope value, based on the values within an input values raster (--values), along flow-paths, as calculated using the D8 flow method. The user must specify the names of the input digital elevation model (DEM) file (--dem), from which the D8 flow direction data will be calculated internally, and the output file (--output).

See Also: D8FlowAccumulation, D8Pointer

Parameters:

FlagDescription
-d, --demInput DEM; it must be depressionless
--valuesName of the input values raster file
--outputName of the output raster file

Python function:

wbt.max_upslope_value(
    dem, 
    values, 
    output, 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=MaxUpslopeValue --dem=DEM.tif ^
--values=values.tif --output=out.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/02/2022

Last Modified: 26/02/2022

MdInfFlowAccumulation

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

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

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

Reference:

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

See Also: D8FlowAccumulation, FD8FlowAccumulation, QuinnFlowAccumulation, QinFlowAccumulation, DInfFlowAccumulation, MDInfFlowAccumulation, Rho8Pointer, BreachDepressionsLeastCost

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--out_typeOutput type; one of 'cells', 'specific contributing area' (default), and 'catchment area'
--exponentOptional exponent parameter; default is 1.1
--thresholdOptional convergence threshold parameter, in grid cells; default is infinity
--logOptional flag to request the output be log-transformed
--clipOptional flag to request clipping the display max by 1%

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/02/2020

Last Modified: 12/02/2020

NumInflowingNeighbours

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

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

See Also: NumDownslopeNeighbours, NumUpslopeNeighbours

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 12/10/2018

QinFlowAccumulation

This tool is used to generate a flow accumulation grid (i.e. contributing area) using the Qin et al. (2007) flow algorithm, not to be confused with the similarly named QuinnFlowAccumulation tool. This algorithm is an examples of a multiple-flow-direction (MFD) method because the flow entering each grid cell is routed to more than one downslope neighbour, i.e. flow divergence is permitted. It is based on a modification of the Freeman (1991; FD8FlowAccumulation) and Quinn et al. (1995; QuinnFlowAccumulation) methods. The Qin method relates the degree of flow dispersion from a grid cell to the local maximum downslope gradient. Specifically, steeper terrain experiences more convergent flow while flatter slopes experience more flow divergence.

The following equations are used to calculate the portion flow (Fi) given to each neighbour, i:

Fi = Li(tanβ)f(e) / Σi=1n[Li(tanβ)f(e)]

f(e) = min(e, eU) / eU × (pU - 1.1) + 1.1

Where Li is the contour length, and is 0.5×cell size for cardinal directions and 0.354×cell size for diagonal directions, n = 8, and represents each of the eight neighbouring grid cells. The exponent f(e) controls the proportion of flow allocated to each downslope neighbour of a grid cell, based on the local maximum downslope gradient (e), and the user-specified upper boundary of e (eU; --max_slope), and the upper boundary of the exponent (pU; --exponent), f(e). Note that the original Qin (2007) implementation allowed for user-specified lower boundaries on the slope (eL) and exponent (pL) parameters as well. In this implementation, these parameters are assumed to be 0.0 and 1.1 respectively, and are not user adjustable. Also note, the --exponent parameter should be less than 50.0, as higher values may cause numerical instability.

The user must specify the name (--dem) of the input digital elevation model (DEM) and the output file (--output). The DEM must have been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achieved using either the BreachDepressions (also BreachDepressionsLeastCost) or FillDepressions tool.

The user-specified non-dispersive, channel initiation threshold (--threshold) is a flow-accumulation value (measured in upslope grid cells, which is directly proportional to area) above which flow dispersion is no longer permitted. Grid cells with flow-accumulation values above this area threshold will have their flow routed in a manner that is similar to the D8 single-flow-direction algorithm, directing all flow towards the steepest downslope neighbour. This is usually done under the assumption that flow dispersion, whilst appropriate on hillslope areas, is not realistic once flow becomes channelized. Importantly, the --threshold parameter sets the spatial extent of the stream network, with lower values resulting in more extensive networks.

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

Reference:

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

Qin, C., Zhu, A. X., Pei, T., Li, B., Zhou, C., & Yang, L. 2007. An adaptive approach to selecting a flow‐partition exponent for a multiple‐flow‐direction algorithm. International Journal of Geographical Information Science, 21(4), 443-458.

Quinn, P. F., K. J. Beven, Lamb, R. 1995. The in (a/tanβ) index: How to calculate it and how to use it within the topmodel framework. Hydrological Processes 9(2): 161-182.

See Also: D8FlowAccumulation, QuinnFlowAccumulation, FD8FlowAccumulation, DInfFlowAccumulation, MDInfFlowAccumulation, Rho8Pointer, WetnessIndex

Parameters:

FlagDescription
-d, --demName of the input DEM raster file; must be depressionless
--outputName of the output raster file
--out_typeOutput type; one of 'cells', 'specific contributing area' (default), and 'catchment area'
--exponentOptional upper-bound exponent parameter; default is 10.0
--max_slopeOptional upper-bound slope parameter, in degrees (0-90); default is 45.0
--thresholdOptional convergence threshold parameter, in grid cells; default is infinity
--logLog-transform the output values?
--clipOptional flag to request clipping the display max by 1%

Python function:

wbt.qin_flow_accumulation(
    dem, 
    output, 
    out_type="specific contributing area", 
    exponent=10.0, 
    max_slope=45.0, 
    threshold=None, 
    log=False, 
    clip=False, 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=QinFlowAccumulation --dem=DEM.tif ^
--output=QinMFD.tif --out_type='specific contributing area' ^
--exponent=15.0 --max_slope=30.0 --threshold=10000 

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/07/2021

Last Modified: 15/07/2021

QuinnFlowAccumulation

This tool is used to generate a flow accumulation grid (i.e. contributing area) using the Quinn et al. (1995) flow algorithm, sometimes called QMFD or QMFD2, and not to be confused with the similarly named QinFlowAccumulation tool. This algorithm is an examples of a multiple-flow-direction (MFD) method because the flow entering each grid cell is routed to more than one downslope neighbour, i.e. flow divergence is permitted. The user must specify the name (--dem) of the input digital elevation model (DEM). The DEM must have been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achieved using either the BreachDepressions (also BreachDepressionsLeastCost) or FillDepressions tool. A value must also be specified for the exponent parameter (--exponent), a number that controls the degree of dispersion in the resulting flow-accumulation grid. A lower value yields greater apparent flow dispersion across divergent hillslopes. The exponent value (h) should probably be less than 50.0, as higher values may cause numerical instability, and values between 1 and 2 are most common. The following equations are used to calculate the portion flow (Fi) given to each neighbour, i:

Fi = Li(tanβ)p / Σi=1n[Li(tanβ)p]

p = (A / threshold + 1)h

Where Li is the contour length, and is 0.5×cell size for cardinal directions and 0.354×cell size for diagonal directions, n = 8, and represents each of the eight neighbouring grid cells, and, A is the flow accumulation value assigned to the current grid cell, that is being apportioned downslope. The non-dispersive, channel initiation threshold (--threshold) is a flow-accumulation value (measured in upslope grid cells, which is directly proportional to area) above which flow dispersion is no longer permitted. Grid cells with flow-accumulation values above this threshold will have their flow routed in a manner that is similar to the D8 single-flow-direction algorithm, directing all flow towards the steepest downslope neighbour. This is usually done under the assumption that flow dispersion, whilst appropriate on hillslope areas, is not realistic once flow becomes channelized. Importantly, the --threshold parameter sets the spatial extent of the stream network, with lower values resulting in more extensive networks.

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

Reference:

Quinn, P. F., K. J. Beven, Lamb, R. 1995. The in (a/tanβ) index: How to calculate it and how to use it within the topmodel framework. Hydrological Processes 9(2): 161-182.

See Also: D8FlowAccumulation, QinFlowAccumulation, FD8FlowAccumulation, DInfFlowAccumulation, MDInfFlowAccumulation, Rho8Pointer, WetnessIndex

Parameters:

FlagDescription
-d, --demName of the input DEM raster file; must be depressionless
--outputName of the output raster file
--out_typeOutput type; one of 'cells', 'specific contributing area' (default), and 'catchment area'
--exponentOptional exponent parameter; default is 1.0
--thresholdOptional convergence threshold parameter, in grid cells; default is infinity
--logLog-transform the output values?
--clipOptional flag to request clipping the display max by 1%

Python function:

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

Command-line Interface:

-./whitebox_tools -r=QuinnFlowAccumulation --dem=DEM.tif ^
--output=QMFD.tif --out_type='specific contributing area' ^
--exponent=1.1 --threshold=10000 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/07/2021

Last Modified: 15/07/2021

RaiseWalls

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

Parameters:

FlagDescription
-i, walls, --inputInput vector lines or polygons file
--breachOptional input vector breach lines
--demInput raster DEM file
-o, --outputOutput raster file
--heightWall height

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/04/2018

Last Modified: 22/10/2019

Rho8FlowAccumulation

This tool is used to generate a flow accumulation grid (i.e. contributing area) using the Fairfield and Leymarie (1991) flow algorithm, often called Rho8. Like the D8 flow method, this algorithm is an examples of a single-flow-direction (SFD) method because the flow entering each grid cell is routed to only one downslope neighbour, i.e. flow divergence is not permitted. The user must specify the name of the input file (--input), which may be either a digital elevation model (DEM) or a Rho8 pointer file (see Rho8Pointer). If a DEM is input, it must have been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achieved using either the BreachDepressions (also BreachDepressionsLeastCost) or FillDepressions tool.

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

If a Rho8 pointer is used as the input raster, the user must specify this (--pntr). Similarly, if a pointer input is used and the pointer follows the Esri pointer convention, rather than the default WhiteboxTools convension for pointer files, then this must also be specified (--esri_pntr).

Reference:

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

See Also: Rho8Pointer, D8FlowAccumulation, QinFlowAccumulation, FD8FlowAccumulation, DInfFlowAccumulation, MDInfFlowAccumulation, WetnessIndex

Parameters:

FlagDescription
-i, --inputInput DEM or Rho8 pointer file; if a DEM is used, it must be depressionless
--outputName of the output raster file
--out_typeOutput type; one of 'cells', 'specific contributing area' (default), and 'catchment area'
--logLog-transform the output values?
--clipOptional flag to request clipping the display max by 1%
--pntrIs the input raster a Rho8 flow pointer rather than a DEM?
--esri_pntrDoes the input Rho8 pointer use the ESRI style scheme?

Python function:

wbt.rho8_flow_accumulation(
    i, 
    output, 
    out_type="specific contributing area", 
    log=False, 
    clip=False, 
    pntr=False, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=Rho8FlowAccumulation --dem=DEM.tif ^
--output=Rho8.tif --out_type='specific contributing area' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/08/2021

Last Modified: 29/08/2021

Rho8Pointer

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

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

...
641281
3202
1684

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

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

Memory Usage

The peak memory usage of this tool is approximately 10 bytes per grid cell.

References:

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

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

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/07/2017

Last Modified: 18/10/2019

RiverCenterlines

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

This tool can map river centerlines, or medial-lines, from input river rasters (--input). The input river (or water) raster is often derived from an image classification performed on multispectral satellite imagery. The river raster must be a Boolean (1 for water, 0/NoData for not-water) and can be derived either by reclassifying the classification output, or derived using a 1-class classification procedure. For example, using the ParallelepipedClassification tool, it is possible to train the classifier using water training polygons, and all other land classes will simply be left unclassified. It may be necessary to perform some pre-processing on the water Boolean raster before input to the centerlines tool. For example, you may need to remove smaller water polygons associated with small lakes and ponds, and you may want to remove small islands from the remaining water features. This tool will often create a bifurcating vector path around islands within rivers, even if those islands are a single-cell in size. The RemoveRasterPolygonHoles tool can be used to remove islands in the water raster that are smaller than a user-specified size. The user must also specify the minimum line length (--min_length), which determines the level of detail in the final rivers map. For example, in the first iamge below, a value of 30 grid cells was used for the --min_length parameter, while a value of 5 was used in the second image, which possesses far more (arguably too much) detail.

Lastly, the user must specify the --radius parameter value. At times, the tool will be able to connect distant water polygons that are part of the same feature and this parameter determines the size of the search radius used to identify separated line end-nodes that are candidates for connection. It is advisable that this value not be set too high, or else unexpected connections may be made between unrelated water features. However, a value of between 1 and 5 can produce satisfactory results. Experimentation may be needed to find an appropriate value for any one data set however. The image below provides an example of this characteristic of the tool, where the resulting vector stream centerline passes through disconnected raster water polygons in the underlying input image in four locations.

Here is a video that demonstrates how to apply this tool to map river center-lines taken from a water raster created by classifying a Sentinel-2 multi-spectral satellite imagery data set.

See Also: ParallelepipedClassification, RemoveRasterPolygonHoles

Parameters:

FlagDescription
-i, --inputName of the input raster image file
-o, --outputName of the output vector lines file
--min_lengthMinimum line length, in grid cells
--radiusSearch radius for joining distant endnodes, in grid cells

Python function:

wbt.river_centerlines(
    i, 
    output, 
    min_length=3, 
    radius=4, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RiverCenterlines -i=water.tif ^
-o=river_centerlines.shp --min_length=20 --radius=4 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 13/10/2022

Last Modified: 13/10/2022

Sink

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

See Also: FillDepressions, Clump

Parameters:

FlagDescription
-i, --dem, --inputInput raster DEM file
-o, --outputOutput raster file
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 05/12/2019

SnapPourPoints

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

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

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

Reference:

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

See Also: Watershed, JensonSnapPourPoints, D8FlowAccumulation

Parameters:

FlagDescription
--pour_ptsInput vector pour points (outlet) file
--flow_accumInput raster D8 flow accumulation file
-o, --outputOutput vector file
--snap_distMaximum snap distance in map units

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/072017

Last Modified: 12/10/2018

StochasticDepressionAnalysis

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

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

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

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

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

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

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

For a video demonstrating the application of the StochasticDepressionAnalysis tool, see this YouTube video.

Reference:

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

See Also: ImpoundmentSizeIndex, FastAlmostGaussianFilter

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput file
--rmseThe DEM's root-mean-square-error (RMSE), in z units. This determines error magnitude
--rangeThe error field's correlation length, in xy-units
--iterationsThe number of iterations

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/05/2018

Last Modified: 29/03/2019

StrahlerOrderBasins

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

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

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

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

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/07/2017

Last Modified: 18/10/2019

Subbasins

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

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

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

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

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

Parameters:

FlagDescription
--d8_pntrInput D8 pointer raster file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 13/02/2020

TopologicalBreachBurn

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

This tool performs a specialized form of stream burning, i.e. the practice of forcing the surface flow paths modelled from a digital elevation model (DEM) to match the pathway of a mapped vector stream network. Stream burning is a common flow enforcement technique used to correct surface drainage patterns derived from DEMs. The technique involves adjusting the elevations of grid cells that are coincident with the features of a vector hydrography layer, usually simply by lowering stream cell elevations by a constant offset value. This simple approach is used by the FillBurn tool, which suffers greatly from topological errors resulting from the mismatched scales of the hydrography and DEM data sets. These topological errors, which occur during the rasterization of the stream vector, result in inappropriate stream cell adjacencies (where two stream links appear to be beside one another in the stream raster with no space between) and collisions (where two stream links occupy the same cell in the stream raster). The TopologicalBreachBurn method uses total upstream channel length (TUCL) to prune the vector hydrography layer to a level of detail that matches the raster DEM grid resolution. Network pruning reduces the occurrence of erroneous stream piracy caused by the rasterization of multiple stream links to the same DEM grid cell. The algorithm also restricts flow, during the calculation of the D8 flow pointer raster output, within individual stream reaches, further reducing erroneous stream piracy. In situations where two vector stream features occupy the same grid cell, the new tool ensures that the larger stream, designated by higher TUCL, is given priority. TUCL-based priority minimizes the impact of the topological errors that occur during the stream rasterization process on modelled regional drainage patterns. Lindsay (2016) demonstrated that the TopologicalBreachBurn method produces highly accurate and scale-insensitive drainage patterns and watershed boundaries compared with FillBurn.

The tool requires two input layers, including the DEM (--dem) and mapped vector stream network (--streams). Note that these two inputs must share the same map projection. The tool also produces four output rasters, including:

  1. A rasterized version of the pruned stream network (--out_streams). Network pruning is based on a TUCL threshold that is calculated as the optimal value that satisfies the combined objectives of maximizing the length of maintained streams and minimizing the number of collisions/adjacencies in the rasterized network. This optimization process is carried out using TUCL and stream length data calculated for each tributary in the network. A tributary connects a channel head and a downstream confluence/outlet in the stream network. Tributaries are often composed of multiple stream links (lengths of streams between upstream-downstream heads/confluences) and can have tributaries of their own. At each confluence in the stream network, the tributary identifier that carries on downstream is associated with the upstream link with the larger TUCL value (a surrogate for stream/drainage area size). The output streams raster shows stream cells remaining after the pruning process along with their unique tributary identifier value. Lower tributary IDs are associated with larger streams, with the lowest valued tributary in a network associated with the main-stem, based on the TUCL criterion for modelling stream size. The main functions of this output are for the user to examine the extent of network pruning used by the tool and to evaluate the network structure described by the tributary IDs. Notice that pruning will be more extensive with a greater mismatch between the scales of the input mapped stream network and the DEM.

  2. The stream-burned DEM (--out_dem). This DEM will have constantly decreasing elevation values (i.e. breached) along stream tributaries from their channel heads all the way to their eventual outlet points. The tool does not use a constant elevation decrement value. Additionally, all topographic depressions that are located on the hillslopes will be filled; you may pre-process the input DEM with a length-restricted run of the BreachDepressionsLeastCost tool if you do not wish to fill depressions. This output DEM is probably the least useful of the four output rasters produced by this tool. It is created and output simply because other stream-burning tools produce a burned-in DEM. As indicated above, one of the mechanisms by which this tool improves the topological representation of flow through the rasterized stream network is to ensure that preferential flow path connections are made among stream cells of the same tributary ID and, where there are collisions, to ensure that larger tributaries (lower ID value) is preferred. However, this cannot be represented merely with the elevations contained within this stream-burned DEM. If, for example, you were to run a flow pointer/accumulation operation on the produced DEM, you will not get the exact same outputs as the D8 pointer and flow accumulation rasters produced by this tool, since the D8 tools will not be able to account for the within-tributary flow enforcement used by TopologicalBreachBurn using the elevation values contained within the DEM alone.

  3. The D8 flow pointer raster (--out_dir). This raster output contains the D8-style pointer values (see the D8Pointer tool for an explanation of pointer value interpretation) and can be used as an input to many of the other hydrological tools in Whitebox. It does capture the topological flow-enforcement within tributaries described above.

  4. The D8 flow accumulation raster (--out_fa). This raster can be optionally output from the tool if the user specifies a value for this parameter. When specified, the tool will run the standard D8 flow accumulation operation using the flow pointer raster above as input. Note that this raster will be exactly the same as what would be produced should you input the D8 flow pointer produced by this tool to the D8FlowAccumualation tool (thus this output is optional).

The user must lastly specify the --snap distance value, in meters. This parameter allows the tool to identify the linkage between stream segments when their end nodes are not perfectly aligned. One may also choose to run the RepairStreamVectorTopology tool prior to this tool to resolve any misalignment in the input streams vector.

Reference:

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

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

See Also: FillBurn, BreachDepressionsLeastCost, PruneVectorStreams, RepairStreamVectorTopology, VectorStreamNetworkAnalysis

Parameters:

FlagDescription
--streamsName of the input streams vector file
--demName of the input DEM raster file
--out_streamsName of the output pruned streams raster
--out_demName of the output lines shapefile
--out_dirName of the output flow direction raster
--out_accumName of the output lines shapefile
--snapSnap distance, in xy units (metres)

Python function:

wbt.topological_breach_burn(
    streams, 
    dem, 
    out_streams, 
    out_dem, 
    out_dir, 
    out_accum=None, 
    snap=1.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=TopologicalBreachBurn ^
--streams=rivers.shp --dem=DEM.tif ^
--out_streams=pruned_streams.tif --out_dem=burned_DEM.tif ^
--out_dir=flow_dir.tif --out_accum=flow_accum.tif --snap=1.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 04/05/2023

Last Modified: 04/05/2023

TraceDownslopeFlowpaths

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

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

Parameters:

FlagDescription
--seed_ptsInput vector seed points file
--d8_pntrInput D8 pointer raster file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/07/2017

Last Modified: 18/10/2019

UnnestBasins

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

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

Parameters:

FlagDescription
--d8_pntrInput D8 pointer raster file
--pour_ptsInput vector pour points (outlet) file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/04/2018

Last Modified: 18/10/2019

UpslopeDepressionStorage

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

See Also: FD8FlowAccumulation, FillDepressions, DepthInSink

Parameters:

FlagDescription
-i, --demInput raster DEM file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/11/2019

Last Modified: 21/11/2019

Watershed

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

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

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

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

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

Reference:

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

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

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

Parameters:

FlagDescription
--d8_pntrInput D8 pointer raster file
--pour_ptsInput pour points (outlet) file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 14/02/2020

Image Processing Tools

ChangeVectorAnalysis

Change Vector Analysis (CVA) is a change detection method that characterizes the magnitude and change direction in spectral space between two times. A change vector is the difference vector between two vectors in n-dimensional feature space defined for two observations of the same geographical location (i.e. corresponding pixels) during two dates. The CVA inputs include the set of raster images corresponding to the multispectral data for each date. Note that there must be the same number of image files (bands) for the two dates and they must be entered in the same order, i.e. if three bands, red, green, and blue are entered for date one, these same bands must be entered in the same order for date two.

CVA outputs two image files. The first image contains the change vector length, i.e. magnitude, for each pixel in the multi-spectral dataset. The second image contains information about the direction of the change event in spectral feature space, which is related to the type of change event, e.g. deforestation will likely have a different change direction than say crop growth. The vector magnitude is a continuous numerical variable. The change vector direction is presented in the form of a code, referring to the multi-dimensional sector in which the change vector occurs. A text output will be produced to provide a key describing sector codes, relating the change vector to positive or negative shifts in n-dimensional feature space.

It is common to apply a simple thresholding operation on the magnitude data to determine 'actual' change (i.e. change above some assumed level of error). The type of change (qualitatively) is then defined according to the corresponding sector code. Jensen (2015) provides a useful description of this approach to change detection.

Reference:

Jensen, J. R. (2015). Introductory Digital Image Processing: A Remote Sensing Perspective.

See Also: WriteFunctionMemoryInsertion

Parameters:

FlagDescription
--date1Input raster files for the earlier date
--date2Input raster files for the later date
--magnitudeOutput vector magnitude raster file
--directionOutput vector Direction raster file

Python function:

wbt.change_vector_analysis(
    date1, 
    date2, 
    magnitude, 
    direction, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ChangeVectorAnalysis -v ^
--wd="/path/to/data/" ^
--date1='d1_band1.tif;d1_band2.tif;d1_band3.tif' ^
--date2='d2_band1.tif;d2_band2.tif;d2_band3.tif' ^
--magnitude=mag_out.tif --direction=dir_out.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 29/04/2018

Last Modified: 29/04/2018

Closing

This tool performs a closing operation on an input greyscale image (--input). A closing is a mathematical morphology operation involving an erosion (minimum filter) of a dilation (maximum filter) set. Closing operations, together with the Opening operation, is frequently used in the fields of computer vision and digital image processing for image noise removal. The user must specify the size of the moving window in both the x and y directions (--filterx and --filtery).

See Also: Opening, TophatTransform

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.closing(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Closing -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 30/01/2020

CreateColourComposite

This tool can be used to create a colour-composite image from three bands of multi-spectral imagery. The user must specify the names of the input images to enter into the red, green, and blue channels of the resulting composite image. The output image uses the 32-bit aRGB colour model, and therefore, in addition to red, green and blue bands, the user may optionally specify a fourth image that will be used to determine pixel opacity (the 'a' channel). If no opacity image is specified, each pixel will be opaque. This can be useful for cropping an image to an irregular-shaped boundary. The opacity channel can also be used to create transparent gradients in the composite image.

A balance contrast enhancement (BCE) can optionally be performed on the bands prior to creation of the colour composite. While this operation will add to the runtime of CreateColourComposite, if the individual input bands have not already had contrast enhancements, then it is advisable that the BCE option be used to improve the quality of the resulting colour composite image.

NoData values in any of the input images are assigned NoData values in the output image and are not taken into account when performing the BCE operation. Please note, not all images have NoData values identified. When this is the case, and when the background value is 0 (often the case with multispectral imagery), then the CreateColourComposite tool can be told to ignore zero values using the --zeros flag.

See Also: BalanceContrastEnhancement, SplitColourComposite

Parameters:

FlagDescription
--redInput red band image file
--greenInput green band image file
--blueInput blue band image file
--opacityInput opacity band image file (optional)
-o, --outputOutput colour composite file
--enhanceOptional flag indicating whether a balance contrast enhancement is performed
--zerosOptional flag to indicate if zeros are nodata values

Python function:

wbt.create_colour_composite(
    red, 
    green, 
    blue, 
    output, 
    opacity=None, 
    enhance=True, 
    zeros=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CreateColourComposite -v ^
--wd="/path/to/data/" --red=band3.tif --green=band2.tif ^
--blue=band1.tif -o=output.tif
>>./whitebox_tools ^
-r=CreateColourComposite -v --wd="/path/to/data/" ^
--red=band3.tif --green=band2.tif --blue=band1.tif ^
--opacity=a.tif -o=output.tif --enhance --zeros 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/07/2017

Last Modified: 18/10/2019

FlipImage

This tool can be used to flip, or reflect, an image (--input) either vertically, horizontally, or both. The axis of reflection is specified using the --direction parameter. The input image is not reflected in place; rather, the reflected image is stored in a separate output (--output) file.

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--directionDirection of reflection; options include 'v' (vertical), 'h' (horizontal), and 'b' (both)

Python function:

wbt.flip_image(
    i, 
    output, 
    direction="vertical", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FlipImage -v --wd="/path/to/data/" ^
--input=in.tif -o=out.tif --direction=h 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 13/10/2018

IhsToRgb

This tool transforms three intensity, hue, and saturation (IHS; sometimes HSI or HIS) raster images into three equivalent multispectral images corresponding with the red, green, and blue channels of an RGB composite. Intensity refers to the brightness of a color, hue is related to the dominant wavelength of light and is perceived as color, and saturation is the purity of the color (Koutsias et al., 2000). There are numerous algorithms for performing a red-green-blue (RGB) to IHS transformation. This tool uses the transformation described by Haydn (1982). Note that, based on this transformation, the input IHS values must follow the ranges:

0 < I < 1

0 < H < 2PI

0 < S < 1

The output red, green, and blue images will have values ranging from 0 to 255. The user must specify the names of the intensity, hue, and saturation images (--intensity, --hue, --saturation). These images will generally be created using the RgbToIhs tool. The user must also specify the names of the output red, green, and blue images (--red, --green, --blue). Image enhancements, such as contrast stretching, are often performed on the individual IHS components, which are then inverse transformed back in RGB components using this tool. The output RGB components can then be used to create an improved color composite image.

References:

Haydn, R., Dalke, G.W. and Henkel, J. (1982) Application of the IHS color transform to the processing of multisensor data and image enhancement. Proc. of the Inter- national Symposium on Remote Sensing of Arid and Semiarid Lands, Cairo, 599-616.

Koutsias, N., Karteris, M., and Chuvico, E. (2000). The use of intensity-hue-saturation transformation of Landsat-5 Thematic Mapper data for burned land mapping. Photogrammetric Engineering and Remote Sensing, 66(7), 829-840.

See Also: RgbToIhs, BalanceContrastEnhancement, DirectDecorrelationStretch

Parameters:

FlagDescription
--intensityInput intensity file
--hueInput hue file
--saturationInput saturation file
--redOutput red band file. Optionally specified if colour-composite not specified
--greenOutput green band file. Optionally specified if colour-composite not specified
--blueOutput blue band file. Optionally specified if colour-composite not specified
-o, --outputOutput colour-composite file. Only used if individual bands are not specified

Python function:

wbt.ihs_to_rgb(
    intensity, 
    hue, 
    saturation, 
    red=None, 
    green=None, 
    blue=None, 
    output=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=IhsToRgb -v --wd="/path/to/data/" ^
--intensity=intensity.tif --hue=hue.tif ^
--saturation=saturation.tif --red=band3.tif --green=band2.tif ^
--blue=band1.tif
>>./whitebox_tools -r=IhsToRgb -v ^
--wd="/path/to/data/" --intensity=intensity.tif --hue=hue.tif ^
--saturation=saturation.tif --composite=image.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/07/2017

Last Modified: 22/10/2019

ImageSlider

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

This tool creates an interactive image slider from two input images (--input1 and --input2). An image slider is an interactive visualization of two overlapping images, in which the user moves the position of a slider bar to hide or reveal one of the overlapping images. The output (--output) is an HTML file. Each of the two input images may be rendered in one of several available palettes. If the input image is a colour composite image, no palette is required. Labels may also be optionally associated with each of the images, displayed in the upper left and right corners. The user must also specify the image height (--height) in the output file. Note that the output is simply HTML, CSS, and javascript code, which can be readily embedded in other documents.

The following is an example of what the output of this tool looks like. Click the image for an interactive example.

Parameters:

FlagDescription
--i1, --input1Name of the left input image file
--p1, --palette1Left image palette; options are 'grey', 'atlas', 'high_relief', 'arid', 'soft', 'muted', 'purple', 'viridi', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', and 'rgb'
--r1, --reverse1Reverse left image palette?
--l1, --label1Left image label (leave blank for none)
--i2, --input2Name of the right input image file
--p2, --palette2Right image palette; options are 'grey', 'atlas', 'high_relief', 'arid', 'soft', 'muted', 'purple', 'viridi', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', and 'rgb'
--r2, --reverse2Reverse right image palette?
--l2, --label2Right image label (leave blank for none)
-o, --outputName of the output HTML file (*.html)
-h, --heightImage height, in pixels

Python function:

wbt.image_slider(
    input1, 
    input2, 
    output, 
    palette1="grey", 
    reverse1=False, 
    label1="", 
    palette2="grey", 
    reverse2=False, 
    label2="", 
    height=600, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ImageSlider --i1=band1.tif --p1=soft ^
--r1=false --l1="Label 1" --i2=band2.tif --p1=soft --r2=false ^
--l2="Label 2" -o=class_properties.html 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 29/04/2021

Last Modified: 29/04/2021

ImageStackProfile

This tool can be used to plot an image stack profile (i.e. a signature) for a set of points (--points) and a multispectral image stack (--inputs). The tool outputs an interactive SVG line graph embedded in an HTML document (--output). If the input points vector contains multiple points, each input point will be associated with a single line in the output plot. The order of vertices in each signature line is determined by the order of images specified in the --inputs parameter. At least two input images are required to run this operation. Note that this tool does not require multispectral images as inputs; other types of data may also be used as the image stack. Also note that the input images should be single-band, continuous greytone rasters. RGB colour images are not good candidates for this tool.

If you require the raster values to be saved in the vector points file's attribute table, or if you need the raster values to be output as text, you may use the ExtractRasterValuesAtPoints tool instead.

See Also: ExtractRasterValuesAtPoints

Parameters:

FlagDescription
-i, --inputsInput multispectral image files
--pointsInput vector points file
-o, --outputOutput HTML file

Python function:

wbt.image_stack_profile(
    inputs, 
    points, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ImageStackProfile -v ^
--wd="/path/to/data/" -i='image1.tif;image2.tif;image3.tif' ^
--points=pts.shp -o=output.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/03/2018

Last Modified: 13/10/2018

IntegralImage

This tool transforms an input raster image into an integral image, or summed area table. Integral images are the two-dimensional equivalent to a cumulative distribution function. Each pixel contains the sum of all pixels contained within the enclosing rectangle above and to the left of a pixel. Images with a very large number of grid cells will likely experience numerical overflow errors when converted to an integral image. Integral images are used in a wide variety of computer vision and digital image processing applications, including texture mapping. They allow for the efficient calculation of very large filters and are the basis of several of WhiteboxTools's image filters.

Reference:

Crow, F. C. (1984, January). Summed-area tables for texture mapping. In ACM SIGGRAPH computer graphics (Vol. 18, No. 3, pp. 207-212). ACM.

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 13/10/2018

LineThinning

This image processing tool reduces all polygons in a Boolean raster image to their single-cell wide skeletons. This operation is sometimes called line thinning or skeletonization. In fact, the input image need not be truly Boolean (i.e. contain only 1's and 0's). All non-zero, positive values are considered to be foreground pixels while all zero valued cells are considered background pixels. The RemoveSpurs tool is useful for cleaning up an image before performing a line thinning operation.

Note: Unlike other filter-based operations in WhiteboxTools, this algorithm can't easily be parallelized because the output raster must be read and written to during the same loop.

See Also: RemoveSpurs, ThickenRasterLine

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 16/02/2019

Mosaic

This tool will create an image mosaic from one or more input image files using one of three resampling methods including, nearest neighbour, bilinear interpolation, and cubic convolution. The order of the input source image files is important. Grid cells in the output image will be assigned the corresponding value determined from the last image found in the list to possess an overlapping coordinate.

Note that when the --inputs parameter is left unspecified, the tool will use all of the .tif, .tiff, .rdc, .flt, .sdat, and .dep files located in the working directory. This can be a useful way of mosaicing large number of tiles, particularly when the text string that would be required to specify all of the input tiles is longer than the allowable limit.

This is the preferred mosaicing tool to use when appending multiple images with little to no overlapping areas, e.g. tiled data. When images have significant overlap areas, users are advised to use the MosaicWithFeathering tool instead.

Resample is very similar in operation to the Mosaic tool. The Resample tool should be used when there is an existing image into which you would like to dump information from one or more source images. If the source images are more extensive than the destination image, i.e. there are areas that extend beyond the destination image boundaries, these areas will not be represented in the updated image. Grid cells in the destination image that are not overlapping with any of the input source images will not be updated, i.e. they will possess the same value as before the resampling operation. The Mosaic tool is used when there is no existing destination image. In this case, a new image is created that represents the bounding rectangle of each of the two or more input images. Grid cells in the output image that do not overlap with any of the input images will be assigned the NoData value.

See Also: MosaicWithFeathering

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file
--methodResampling method; options include 'nn' (nearest neighbour), 'bilinear', and 'cc' (cubic convolution)

Python function:

wbt.mosaic(
    output, 
    inputs=None, 
    method="nn", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Mosaic -v --wd='/path/to/data/' ^
-i='image1.tif;image2.tif;image3.tif' -o=dest.tif ^
--method='cc' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/01/2018

Last Modified: 03/09/2020

MosaicWithFeathering

This tool will create a mosaic from two input images. It is similar in operation to the Mosaic tool, however, this tool is the preferred method of mosaicing images when there is significant overlap between the images. For areas of overlap, the feathering method will calculate the output value as a weighted combination of the two input values, where the weights are derived from the squared distance of the pixel to the edge of the data in each of the input raster files. Therefore, less weight is assigned to an image's pixel value where the pixel is very near the edge of the image. Note that the distance is actually calculated to the edge of the grid and not necessarily the edge of the data, which can differ if the image has been rotated during registration. The result of this feathering method is that the output mosaic image should have very little evidence of the original image edges within the overlapping area.

Unlike the Mosaic tool, which can take multiple input images, this tool only accepts two input images. Mosaic is therefore useful when there are many, adjacent or only slightly overlapping images, e.g. for tiled data sets.

Users may want to use the HistogramMatching tool prior to mosaicing if the two input images differ significantly in their radiometric properties. i.e. if image contrast differences exist.

See Also: Mosaic, HistogramMatching

Parameters:

FlagDescription
--i1, --input1Input raster file to modify
--i2, --input2Input reference raster file
-o, --outputOutput raster file
--methodResampling method; options include 'nn' (nearest neighbour), 'bilinear', and 'cc' (cubic convolution)
--weight

Python function:

wbt.mosaic_with_feathering(
    input1, 
    input2, 
    output, 
    method="cc", 
    weight=4.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MosaicWithFeathering -v ^
--wd='/path/to/data/' --input1='image1.tif' ^
--input2='image2.tif' -o='output.tif' --method='cc' ^
--weight=4.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 29/12/2018

Last Modified: 02/01/2019

NormalizedDifferenceIndex

This tool can be used to calculate a normalized difference index (NDI) from two bands of multispectral image data. A NDI of two band images (image1 and image2) takes the general form:

NDI = (image1 - image2) / (image1 + image2 + c)

Where c is a correction factor sometimes used to avoid division by zero. It is, however, often set to 0.0. In fact, the NormalizedDifferenceIndex tool will set all pixels where image1 + image2 = 0 to 0.0 in the output image. While this is not strictly mathematically correct (0 / 0 = infinity), it is often the intended output in these cases.

NDIs generally takes the value range -1.0 to 1.0, although in practice the range of values for a particular image scene may be more restricted than this.

NDIs have two important properties that make them particularly useful for remote sensing applications. First, they emphasize certain aspects of the shape of the spectral signatures of different land covers. Secondly, they can be used to de-emphasize the effects of variable illumination within a scene. NDIs are therefore frequently used in the field of remote sensing to create vegetation indices and other indices for emphasizing various land-covers and as inputs to analytical operations like image classification. For example, the normalized difference vegetation index (NDVI), one of the most common image-derived products in remote sensing, is calculated as:

NDVI = (NIR - RED) / (NIR + RED)

The optimal soil adjusted vegetation index (OSAVI) is:

OSAVI = (NIR - RED) / (NIR + RED + 0.16)

The normalized difference water index (NDWI), or normalized difference moisture index (NDMI), is:

NDWI = (NIR - SWIR) / (NIR + SWIR)

The normalized burn ratio 1 (NBR1) and normalized burn ration 2 (NBR2) are:

NBR1 = (NIR - SWIR2) / (NIR + SWIR2)

NBR2 = (SWIR1 - SWIR2) / (SWIR1 + SWIR2)

In addition to NDIs, Simple Ratios of image bands, are also commonly used as inputs to other remote sensing applications like image classification. Simple ratios can be calculated using the Divide tool. Division by zero, in this case, will result in an output NoData value.

See Also: Divide

Parameters:

FlagDescription
--input1Input image 1 (e.g. near-infrared band)
--input2Input image 2 (e.g. red band)
-o, --outputOutput raster file
--clipOptional amount to clip the distribution tails by, in percent
--correctionOptional adjustment value (e.g. 1, or 0.16 for the optimal soil adjusted vegetation index, OSAVI)

Python function:

wbt.normalized_difference_index(
    input1, 
    input2, 
    output, 
    clip=0.0, 
    correction=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NormalizedDifferenceIndex -v ^
--wd="/path/to/data/" --input1=band4.tif --input2=band3.tif ^
-o=output.tif
>>./whitebox_tools -r=NormalizedDifferenceIndex ^
-v --wd="/path/to/data/" --input1=band4.tif --input2=band3.tif ^
-o=output.tif --clip=1.0 --adjustment=0.16 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 24/02/2019

Opening

This tool performs an opening operation on an input greyscale image (--input). An opening is a mathematical morphology operation involving a dilation (maximum filter) on an erosion (minimum filter) set. Opening operations, together with the Closing operation, is frequently used in the fields of computer vision and digital image processing for image noise removal. The user must specify the size of the moving window in both the x and y directions (--filterx and --filtery).

See Also: Closing, TophatTransform

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.opening(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Opening -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 30/01/2020

RemoveSpurs

This image processing tool removes small irregularities (i.e. spurs) on the boundaries of objects in a Boolean input raster image (--input). This operation is sometimes called pruning. Remove Spurs is a useful tool for cleaning an image before performing a line thinning operation. In fact, the input image need not be truly Boolean (i.e. contain only 1's and 0's). All non-zero, positive values are considered to be foreground pixels while all zero valued cells are considered background pixels.

Note: Unlike other filter-based operations in WhiteboxTools, this algorithm can't easily be parallelized because the output raster must be read and written to during the same loop.

See Also: LineThinning

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--iterationsMaximum number of iterations

Python function:

wbt.remove_spurs(
    i, 
    output, 
    iterations=10, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 16/02/2019

Resample

This tool can be used to modify the grid resolution of one or more rasters. The user specifies the names of one or more input rasters (--inputs) and the output raster (--output). The resolution of the output raster is determined either using a specified --cell_size parameter, in which case the output extent is determined by the combined extent of the inputs, or by an optional base raster (--base), in which case the output raster spatial extent matches that of the base file. This operation is similar to the Mosaic tool, except that Resample modifies the output resolution. The Resample tool may also be used with a single input raster (when the user wants to modify its spatial resolution, whereas, Mosaic always includes multiple inputs.

If the input source images are more extensive than the base image (if optionally specified), these areas will not be represented in the output image. Grid cells in the output image that are not overlapping with any of the input source images will not be assigned the NoData value, which will be the same as the first input image. Grid cells in the output image that overlap with multiple input raster cells will be assigned the last input value in the stack. Thus, the order of input images is important.

See Also: Mosaic

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified
--baseOptionally specified input base raster file. Not used when a cell size is specified
--methodResampling method; options include 'nn' (nearest neighbour), 'bilinear', and 'cc' (cubic convolution)

Python function:

wbt.resample(
    inputs, 
    output, 
    cell_size=None, 
    base=None, 
    method="cc", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Resample -v --wd='/path/to/data/' ^
-i='image1.tif;image2.tif;image3.tif' --destination=dest.tif ^
--method='cc 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/01/2018

Last Modified: 25/08/2020

RgbToIhs

This tool transforms three raster images of multispectral data (red, green, and blue channels) into their equivalent intensity, hue, and saturation (IHS; sometimes HSI or HIS) images. Intensity refers to the brightness of a color, hue is related to the dominant wavelength of light and is perceived as color, and saturation is the purity of the color (Koutsias et al., 2000). There are numerous algorithms for performing a red-green-blue (RGB) to IHS transformation. This tool uses the transformation described by Haydn (1982). Note that, based on this transformation, the output IHS values follow the ranges:

0 < I < 1

0 < H < 2PI

0 < S < 1

The user must specify the names of the red, green, and blue images (--red, --green, --blue). Importantly, these images need not necessarily correspond with the specific regions of the electromagnetic spectrum that are red, green, and blue. Rather, the input images are three multispectral images that could be used to create a RGB color composite. The user must also specify the names of the output intensity, hue, and saturation images (--intensity, --hue, --saturation). Image enhancements, such as contrast stretching, are often performed on the IHS components, which are then inverse transformed back in RGB components to then create an improved color composite image.

References:

Haydn, R., Dalke, G.W. and Henkel, J. (1982) Application of the IHS color transform to the processing of multisensor data and image enhancement. Proc. of the Inter- national Symposium on Remote Sensing of Arid and Semiarid Lands, Cairo, 599-616.

Koutsias, N., Karteris, M., and Chuvico, E. (2000). The use of intensity-hue-saturation transformation of Landsat-5 Thematic Mapper data for burned land mapping. Photogrammetric Engineering and Remote Sensing, 66(7), 829-840.

See Also: IhsToRgb, BalanceContrastEnhancement, DirectDecorrelationStretch

Parameters:

FlagDescription
--redInput red band image file. Optionally specified if colour-composite not specified
--greenInput green band image file. Optionally specified if colour-composite not specified
--blueInput blue band image file. Optionally specified if colour-composite not specified
--compositeInput colour-composite image file. Only used if individual bands are not specified
--intensityOutput intensity raster file
--hueOutput hue raster file
--saturationOutput saturation raster file

Python function:

wbt.rgb_to_ihs(
    intensity, 
    hue, 
    saturation, 
    red=None, 
    green=None, 
    blue=None, 
    composite=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RgbToIhs -v --wd="/path/to/data/" ^
--red=band3.tif --green=band2.tif --blue=band1.tif ^
--intensity=intensity.tif --hue=hue.tif ^
--saturation=saturation.tif
>>./whitebox_tools -r=RgbToIhs -v ^
--wd="/path/to/data/" --composite=image.tif ^
--intensity=intensity.tif --hue=hue.tif ^
--saturation=saturation.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/07/2017

Last Modified: 22/10/2019

SplitColourComposite

This tool can be used to split a red-green-blue (RGB) colour-composite image into three separate bands of multi-spectral imagery. The user must specify the input image (--input) and output red, green, blue images (--red, --green, --blue).

See Also: CreateColourComposite

Parameters:

FlagDescription
-i, --inputInput colour composite image file
--redOutput red band file
--greenOutput green band file
--blueOutput blue band file

Python function:

wbt.split_colour_composite(
    i, 
    red=None, 
    green=None, 
    blue=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SplitColourComposite -v ^
--wd="/path/to/data/" -i=input.tif --red=red.tif ^
--green=green.tif --blue=blue.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/07/2017

Last Modified: 12/04/2019

ThickenRasterLine

This image processing tool can be used to thicken single-cell wide lines within a raster file along diagonal sections of the lines. Because of the limitation of the raster data format, single-cell wide raster lines can be traversed along diagonal sections without passing through a line grid cell. This causes problems for various raster analysis functions for which lines are intended to be barriers. This tool will thicken raster lines, such that it is impossible to cross a line without passing through a line grid cell. While this can also be achieved using a maximum filter, unlike the filter approach, this tool will result in the smallest possible thickening to achieve the desired result.

All non-zero, positive values are considered to be foreground pixels while all zero valued cells or NoData cells are considered background pixels.

Note: Unlike other filter-based operations in WhiteboxTools, this algorithm can't easily be parallelized because the output raster must be read and written to during the same loop.

See Also: LineThinning

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/07/2017

Last Modified: 13/10/2018

TophatTransform

This tool performs either a white or black top-hat transform on an input image. A top-hat transform is a common digital image processing operation used for various tasks, such as feature extraction, background equalization, and image enhancement. The size of the rectangular structuring element used in the filtering can be specified using the --filterx and --filtery flags.

There are two distinct types of top-hat transform including white and black top-hat transforms. The white top-hat transform is defined as the difference between the input image and its opening by some structuring element. An opening operation is the dilation (maximum filter) of an erosion (minimum filter) image. The black top-hat transform, by comparison, is defined as the difference between the closing and the input image. The user specifies which of the two flavours of top-hat transform the tool should perform by specifying either 'white' or 'black' with the --variant flag.

See Also: Closing, Opening, MaximumFilter, MinimumFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction
--variantOptional variant value. Options include 'white' and 'black'

Python function:

wbt.tophat_transform(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    variant="white", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=TophatTransform -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 30/01/2020

WriteFunctionMemoryInsertion

Jensen (2015) describes write function memory (WFM) insertion as a simple yet effective method of visualizing land-cover change between two or three dates. WFM insertion may be used to qualitatively inspect change in any type of registered, multi-date imagery. The technique operates by creating a red-green-blue (RGB) colour composite image based on co-registered imagery from two or three dates. If two dates are input, the first date image will be put into the red channel, while the second date image will be put into both the green and blue channels. The result is an image where the areas of change are displayed as red (date 1 is brighter than date 2) and cyan (date 1 is darker than date 2), and areas of little change are represented in grey-tones. The larger the change in pixel brightness between dates, the more intense the resulting colour will be.

If images from three dates are input, the resulting composite can contain many distinct colours. Again, more intense the colours are indicative of areas of greater land-cover change among the dates, while areas of little change are represented in grey-tones. Interpreting the direction of change is more difficult when three dates are used. Note that for multi-spectral imagery, only one band from each date can be used for creating a WFM insertion image.

Reference:

Jensen, J. R. (2015). Introductory Digital Image Processing: A Remote Sensing Perspective.

See Also: CreateColourComposite, ChangeVectorAnalysis

Parameters:

FlagDescription
--i1, --input1Input raster file associated with the first date
--i2, --input2Input raster file associated with the second date
--i3, --input3Optional input raster file associated with the third date
-o, --outputOutput raster file

Python function:

wbt.write_function_memory_insertion(
    input1, 
    input2, 
    output, 
    input3=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=WriteFunctionMemoryInsertion -v ^
--wd="/path/to/data/" -i1=input1.tif -i2=input2.tif ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/07/2017

Last Modified: 13/10/2018

Image Processing Tools → Classification

EvaluateTrainingSites

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

This tool performs an evaluation of the reflectance properties of multi-spectral image dataset for a group of digitized class polygons. This is often viewed as the first step in a supervised classification procedure, such as those performed using the MinDistClassification or ParallelepipedClassification tools. The analysis is based on a series of one or more input images (--inputs) and an input polygon vector file (--polys). The user must also specify the attribute name (--field), within the attribute table, containing the class ID associated with each feature in input the polygon vector. A single class may be designated by multiple polygon features in the test site polygon vector. Note that the input polygon file is generally created by digitizing training areas of exemplar reflectance properties for each class type. The input polygon vector should be in the same coordinate system as the input multi-spectral images. The input images must represent a multi-spectral data set made up of individual bands. Do not input colour composite images. Lastly, the user must specify the name of the output HTML file. This file will contain a series of box-and-whisker plots, one for each band in the multi-spectral data set, that visualize the distribution of each class in the associated bands. This can be helpful in determining the overlap between spectral properties for the classes, which may be useful if further class or test site refinement is necessary. For a subsequent supervised classification to be successful, each class should not overlap significantly with the other classes in at least one of the input bands. If this is not the case, the user may need to refine the class system.

See Also: MinDistClassification, ParallelepipedClassification

Parameters:

FlagDescription
-i, --inputsName of the input band images
-p, --polysName of the input training site polygons shapefile
-f, --fieldName of the attribute containing class name data
-o, --outputName of the output report file (*.html)

Python function:

wbt.evaluate_training_sites(
    inputs, 
    polys, 
    field, 
    output, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=EvaluateTrainingSites ^
--inputs="band1.tif;band2.tif;band3.tif;band4.tif" ^
--polys=training_sites.shp --field=CLASS ^
-o=class_properties.html 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 20/03/2021

Last Modified: 20/03/2021

GeneralizeClassifiedRaster

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

This tool can be used to generalize a raster containing class or object features. Such rasters are usually derived from some classification procedure (e.g. image classification and landform classification), or as the output of a segmentation procedure (ImageSegmentation). Rasters that are created in this way often contain many very small features that make their interpretation, or vectorization, challenging. Therefore, it is common for practitioners to remove the smaller features. Many different approaches have been used for this task in the past. For example, it is common to remove small features using a filtering based approach (MajorityFilter). While this can be an effective strategy, it does have the disadvantage of modifying all of the boundaries in the class raster, including those that define larger features. In many applications, this can be a serious issue of concern.

The GeneralizeClassifiedRaster tool offers an alternative method for simplifying class rasters. The process begins by identifying each contiguous group of cells in the input (i.e. a clumping operation) and then defines the subset of features that are smaller than the user-specified minimum feature size (--min_size), in grid cells. This set of small features is then dealt with using one of three methods (--method). In the first method (longest), a small feature may be reassigned the class value of the neighbouring feature with the longest shared border. The sum of the neighbouring feature size and the small feature size must be larger than the specified size threshold, and the tool will iterate through this process of reassigning feature values to neighbouring values until each small feature has been resolved.

The second method, largest, operates in much the same way as the first, except that objects are reassigned the value of the largest neighbour. Again, this process of reassigning small feature values iterates until every small feature has been reassigned to a large neighbouring feature.

The third and last method (nearest) takes a different approach to resolving the reassignment of small features. Using the nearest generalization approach, each grid cell contained within a small feature is reassigned the value of the nearest large neighbouring feature. When there are two or more neighbouring features that are equally distanced to a small feature cell, the cell will be reassigned to the largest neighbour. Perhaps the most significant disadvantage of this approach is that it creates a new artificial boundary in the output image that is not contained within the input class raster. That is, with the previous two methods, boundaries associated with smaller features in the input images are 'erased' in the output map, but every boundary in the output raster exactly matches boundaries within the input raster (i.e. the output boundaries are a subset of the input feature boundaries). However, with the nearest method, artificial boundaries, determined by the divide between nearest neighbours, are introduced to the output raster and these new feature boundaries do not have any basis in the original classification/segmentation process. Thus caution should be exercised when using this approach, especially when larger minimum size thresholds are used. The longest method is the recommended approach to class feature generalization.

For a video tutorial on how to use the GeneralizeClassifiedRaster tool, see this YouTube video.

See Also: GeneralizeWithSimilarity, MajorityFilter, ImageSegmentation

Parameters:

FlagDescription
-i, --inputName of the input raster image file
-o, --outputName of the output raster file
--min_sizeMinimum feature size, in grid cells
--methodGrouping method; one of 'longest' (default), 'largest', and 'nearest'

Python function:

wbt.generalize_classified_raster(
    i, 
    output, 
    min_size=4, 
    method="longest", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=GeneralizeClassifiedRaster ^
-i='classMap.tif' -o=newClassMap.tif --min_size=5 ^
--method='longest' 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 27/11/2021

Last Modified: 02/12/2021

GeneralizeWithSimilarity

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

This tool can be used to generalize a raster containing class features (--input) by reassigning the identifier values of small features (--min_size) to those of neighbouring features. Therefore, this tool performs a very similar operation to the GeneralizeClassifiedRaster tool. However, while the GeneralizeClassifiedRaster tool re-labels small features based on the geometric properties of neighbouring features (e.g. neighbour with the longest shared border, largest neighbour, or nearest neighbour), the GeneralizeWithSimilarity tool reassigns feature labels based on similarity with neighbouring features. Similarity is determined using a series of input similarity criteria rasters (--similarity), which may be factors used in the creation of the input class raster. For example, the similarlity rasters may be bands of multi-spectral imagery, if the input raster is a classified land-cover map, or DEM-derived land surface parameters, if the input raster is a landform class map.

The tool works by identifying each contiguous group of pixels (features) in the input class raster (--input), i.e. a clumping operation. The mean value is then calculated for each feature and each similarity input, which defines a multi-dimensional 'similarity centre point' associated with each feature. It should be noted that the similarity raster data are standardized prior to calculating these centre point values. Lastly, the tool then reassigns the input label values of all features smaller than the user-specified minimum feature size (--min_size) to that of the neighbouring feature with the shortest distance between similarity centre points.

For small features that are entirely enclosed by a single larger feature, this process will result in the same generalization solution presented by any of the geometric-based methods of the GeneralizeClassifiedRaster tool. However, for small features that have more than one neighbour, this tool may provide a superior generalization solution than those based solely on geometric information.

For a video tutorial on how to use the GeneralizeWithSimilarity tool, see this YouTube video.

See Also: GeneralizeClassifiedRaster, MajorityFilter, ImageSegmentation

Parameters:

FlagDescription
-i, --inputName of the input raster image file
--similarityNames of the input similarity images
-o, --outputName of the output raster file
--min_sizeMinimum feature size, in grid cells

Python function:

wbt.generalize_with_similarity(
    i, 
    similarity, 
    output, 
    min_size=4, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=GeneralizeWithSimilarity ^
-i='classMap.tif' --similarity='band1.tif;band2.tif;band3.tif' ^
-o=newClassMap.tif --min_size=5 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 03/12/2021

Last Modified: 05/12/2021

ImageSegmentation

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

This tool is used to segment a mult-spectral image data set, or multi-dimensional data stack. The algorithm is based on region-growing operations. Each of the input images are transformed into standard scores prior to analysis. The total multi-dimensional distance between each pixel and its eight neighbours is measured, which then serves as a priority value for selecting potential seed pixels for the region-growing operations, with pixels exhibited the least difference with their neighbours more likely to serve as seeds. The region-growing operations initiate at seed pixels and grows outwards, connecting neighbouring pixels that have a multi-dimensional distance from the seed cell that is less than a threshold value. Thus, the region-growing operations attempt to identify contiguous, relatively homogeneous objects. The algorithm stratifies potential seed pixels into bands, based on their total difference with their eight neighbours. The user may control the size and number of these bands using the --threshold and --steps parameters respectively. Increasing the magnitude of the threshold parameter will result in fewer mapped objects and vice versa. All pixels that are not assigned to an object after the seeding-based region-growing operations are then clumped simply based on contiguity.

It is commonly the case that there will be a large number of very small-sized objects identified using this approach. The user may optionally specify that objects that are less than a minimum area (expressed in pixels) be eliminated from the final output raster. The --min_area parameter must be an integer between 1 and 8. In cleaning small objects from the output, the pixels belonging to these smaller features are assigned to the most homogeneous neighbouring object.

The input rasters (--inputs) may be bands of satellite imagery, or any other attribute, such as measures of texture, elevation, or other topographic derivatives, such as slope. If satellite imagery is used as inputs, it can be beneficial to pre-process the data with an edge-preserving low-pass filter, such as the BilateralFilter and EdgePreservingMeanFilter tools.

See Also: BilateralFilter, EdgePreservingMeanFilter

Parameters:

FlagDescription
-i, --inputsNames of the input band images
-o, --outputName of the output raster file
--thresholdDistance threshold, in z-scores
--stepsNumber of steps
--min_areaMinimum object area, in grid cells (1-8)

Python function:

wbt.image_segmentation(
    inputs, 
    output, 
    threshold=0.5, 
    steps=10, 
    min_area=4, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ImageSegmentation ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' -o=segmented.tif ^
--threshold=4.0 --steps=10 --min_area=4 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 28/05/2021

Last Modified: 28/05/2021

MinDistClassification

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

This tool performs a supervised minimum-distance classification using training site polygons (--polys) and multi-spectral images (--inputs). This classification method uses the mean vectors for each class and calculates the Euclidean distance from each unknown pixel to the class mean vector. Unclassed pixels are then assigned to the nearest class mean. A threshold distance (--threshold), expressed in number of z-scores, may optionally be used and pixels whose multi-spectral distance is greater than this threshold will not be assigned a class in the output image (--output). When a threshold distance is unspecified, all pixels will be assigned to a class.

Like all supervised classification methods, this technique relies heavily on proper selection of training data. Training sites are exemplar areas of known and representative land cover type. The algorithm determines the spectral signature of the pixels within each training area, and uses this information to define the mean vector of each class. It is preferable that training sites are based on either field-collected data or fine-resolution reference imagery. In selecting training sites, care should be taken to ensure that they cover the full range of variability within each class. Otherwise the classification accuracy will be impacted. If possible, multiple training sites should be selected for each class. It is also advisable to avoid areas near the edges of land-cover patches, where mixed pixels may impact the purity of training site reflectance values.

After selecting training sites, the reflectance values of each land-cover type can be assessed using the EvaluateTrainingSites tool. In particular, the distribution of reflectance values should ideally be non-overlapping in at least one band of the multi-spectral data set.

See Also: EvaluateTrainingSites, ParallelepipedClassification

Parameters:

FlagDescription
-i, --inputsNames of the input band images
-p, --polysName of the input training site polygons shapefile
-f, --fieldName of the attribute containing class name data
-o, --outputName of the output raster file
--thresholdDistance threshold, in z-scores; blank for none

Python function:

wbt.min_dist_classification(
    inputs, 
    polys, 
    field, 
    output, 
    threshold=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=MinDistClassification ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' ^
-p=training_sites.shp -f='LAND_COVER' -o=classified.tif ^
--threshold=4.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 22/03/2021

Last Modified: 22/03/2021

ParallelepipedClassification

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

This tool performs a supervised parallelepiped classification using training site polygons (--polys) and multi-spectral images (--inputs). This classification method uses the minimum and maximum reflectance values for each class within the training data to characterize a set of parallelepipeds, i.e. multi-dimensional geometric shapes. The algorithm then assigns each unknown pixel in the image data set to the first class for which the pixel's spectral vector is contained within the corresponding class parallelepiped. Pixels with spectral vectors that are not contained within any class parallelepiped will not be assigned a class in the output image.

Like all supervised classification methods, this technique relies heavily on proper selection of training data. Training sites are exemplar areas of known and representative land cover type. The algorithm determines the spectral signature of the pixels within each training area, and uses this information to define the mean vector of each class. It is preferable that training sites are based on either field-collected data or fine-resolution reference imagery. In selecting training sites, care should be taken to ensure that they cover the full range of variability within each class. Otherwise the classification accuracy will be impacted. If possible, multiple training sites should be selected for each class. It is also advisable to avoid areas near the edges of land-cover patches, where mixed pixels may impact the purity of training site reflectance values.

After selecting training sites, the reflectance values of each land-cover type can be assessed using the EvaluateTrainingSites tool. In particular, the distribution of reflectance values should ideally be non-overlapping in at least one band of the multi-spectral data set.

See Also: EvaluateTrainingSites, MinDistClassification

Parameters:

FlagDescription
-i, --inputsName of the input band images
-p, --polysName of the input training site polygons shapefile
-f, --fieldName of the attribute containing class name data
-o, --outputName of the output raster file

Python function:

wbt.parallelepiped_classification(
    inputs, 
    polys, 
    field, 
    output, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ParallelepipedClassification ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' ^
-p=training_sites.shp -f='LAND_COVER' -o=classified.tif 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 21/03/2021

Last Modified: 21/03/2021

Image Processing Tools → Filters

AdaptiveFilter

This tool performs a type of adaptive filter on a raster image. An adaptive filter can be used to reduce the level of random noise (shot noise) in an image. The algorithm operates by calculating the average value in a moving window centred on each grid cell. If the absolute difference between the window mean value and the centre grid cell value is beyond a user-defined threshold (--threshold), the grid cell in the output image is assigned the mean value, otherwise it is equivalent to the original value. Therefore, the algorithm only modifies the image where grid cell values are substantially different than their neighbouring values.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

See Also: MeanFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction
--thresholdDifference from mean threshold, in standard deviations

Python function:

wbt.adaptive_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    threshold=2.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AdaptiveFilter -v --wd="/path/to/data/" ^
-i=DEM.tif -o=output.tif --filter=25 --threshold = 2.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

BilateralFilter

This tool can be used to perform an edge-preserving smoothing filter, or bilateral filter, on an image. A bilateral filter can be used to emphasize the longer-range variability in an image, effectively acting to smooth the image, while reducing the edge blurring effect common with other types of smoothing filters. As such, this filter is very useful for reducing the noise in an image. Bilateral filtering is a non-linear filtering technique introduced by Tomasi and Manduchi (1998). The algorithm operates by convolving a kernel of weights with each grid cell and its neighbours in an image. The bilateral filter is related to Gaussian smoothing, in that the weights of the convolution kernel are partly determined by the 2-dimensional Gaussian (i.e. normal) curve, which gives stronger weighting to cells nearer the kernel centre. Unlike the GaussianFilter, however, the bilateral kernel weightings are also affected by their similarity to the intensity value of the central pixel. Pixels that are very different in intensity from the central pixel are weighted less, also based on a Gaussian weight distribution. Therefore, this non-linear convolution filter is determined by the spatial and intensity domains of a localized pixel neighborhood.

The heavier weighting given to nearer and similar-valued pixels makes the bilateral filter an attractive alternative for image smoothing and noise reduction compared to the much-used Mean filter. The size of the filter is determined by setting the standard deviation distance parameter (--sigma_dist); the larger the standard deviation the larger the resulting filter kernel. The standard deviation can be any number in the range 0.5-20 and is specified in the unit of pixels. The standard deviation intensity parameter (--sigma_int), specified in the same units as the z-values, determines the intensity domain contribution to kernel weightings.

References:

Tomasi, C., & Manduchi, R. (1998, January). Bilateral filtering for gray and color images. In null (p. 839). IEEE.

See Also: EdgePreservingMeanFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--sigma_distStandard deviation in distance in pixels
--sigma_intStandard deviation in intensity in pixels

Python function:

wbt.bilateral_filter(
    i, 
    output, 
    sigma_dist=0.75, 
    sigma_int=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BilateralFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif ^
--sigma_dist=2.5 --sigma_int=4.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 30/01/2020

CannyEdgeDetection

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

This tool performs a Canny edge-detection filtering operation on an input image (--input). The Canny edge-detection filter is a multi-stage filter that combines a Gassian filtering (GaussianFilter) operation with various thresholding operations to generate a single-cell wide edges output raster (--output). The --sigma parameter, measured in grid cells determines the size of the Gaussian filter kernel. The --low and --high parameters determine the characteristics of the thresholding steps; both parameters range from 0.0 to 1.0.

By default, the output raster will be Boolean, with 1's designating edge-cells. It is possible, using the --add_back parameter to add the edge cells back into the original image, providing an edge-enchanced output, similar in concept to the UnsharpMasking operation.

References:

This implementation was inspired by the algorithm described here: https://towardsdatascience.com/canny-edge-detection-step-by-step-in-python-computer-vision-b49c3a2d8123

See Also: GaussianFilter, SobelFilter, UnsharpMasking, ScharrFilter

Parameters:

FlagDescription
-i, --inputName of the input raster image file
-o, --outputName of the output raster image file
-s, --sigmaSigma value used in Gaussian filtering, default = 0.5
-l, --lowLow threshold, default = 0.05
-h, --highHigh threshold, default = 0.15
-a, --add_backAdd the edge cells back to the input image

Python function:

wbt.canny_edge_detection(
    i, 
    output, 
    sigma=0.5, 
    low=0.05, 
    high=0.15, 
    add_back=False, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=CannyEdgeDetection -i=input.tif ^
-o=output.tif --sigma=2.0 --low=0.05 --high=0.2 --add_back 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 12/03/2021

Last Modified: 12/03/2021

ConservativeSmoothingFilter

This tool performs a conservative smoothing filter on a raster image. A conservative smoothing filter can be used to remove short-range variability in an image, effectively acting to smooth the image. It is particularly useful for eliminating local spikes and reducing the noise in an image. The algorithm operates by calculating the minimum and maximum neighbouring values surrounding a grid cell. If the cell at the centre of the kernel is greater than the calculated maximum value, it is replaced with the maximum value in the output image. Similarly, if the cell value at the kernel centre is less than the neighbouring minimum value, the corresponding grid cell in the output image is replaced with the minimum value. This filter tends to alter an image very little compared with other smoothing filters such as the MeanFilter, EdgePreservingMeanFilter, BilateralFilter, MedianFilter, GaussianFilter, or OlympicFilter.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

See Also: MeanFilter, EdgePreservingMeanFilter, BilateralFilter, MedianFilter, GaussianFilter, OlympicFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.conservative_smoothing_filter(
    i, 
    output, 
    filterx=3, 
    filtery=3, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ConservativeSmoothingFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

CornerDetection

This tool identifies corner patterns in boolean images using hit-and-miss pattern matching. Foreground pixels in the input image (--input) are designated by any positive, non-zero values. Zero-valued and NoData-valued grid cells are interpreted by the algorithm as background values.

Reference:

Fisher, R, Brown, N, Cammas, N, Fitzgibbon, A, Horne, S, Koryllos, K, Murdoch, A, Robertson, J, Sharman, T, Strachan, C, 2004. Hypertext Image Processing Resource. online: http://homepages.inf.ed.ac.uk/rbf/HIPR2/hitmiss.htm

Parameters:

FlagDescription
-i, --inputInput boolean image
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=CornerDetection -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --sigma=2.0 

Source code on GitHub

Author: Simon Gudim

Created: 04/05/2017

Last Modified: 25/02/2019

DiffOfGaussianFilter

This tool can be used to perform a difference-of-Gaussians (DoG) filter on a raster image. In digital image processing, DoG is a feature enhancement algorithm that involves the subtraction of one blurred version of an image from another, less blurred version of the original. The blurred images are obtained by applying filters with Gaussian-weighted kernels of differing standard deviations to the input image (--input). Blurring an image using a Gaussian-weighted kernel suppresses high-frequency spatial information and emphasizes lower-frequency variation. Subtracting one blurred image from the other preserves spatial information that lies between the range of frequencies that are preserved in the two blurred images. Thus, the difference-of-Gaussians is a band-pass filter that discards all but a specified range of spatial frequencies that are present in the original image.

The algorithm operates by differencing the results of convolving two kernels of weights with each grid cell and its neighbours in an image. The weights of the convolution kernels are determined by the 2-dimensional Gaussian (i.e. normal) curve, which gives stronger weighting to cells nearer the kernel centre. The size of the two convolution kernels are determined by setting the two standard deviation parameters (--sigma1 and --sigma2); the larger the standard deviation the larger the resulting filter kernel. The second standard deviation should be a larger value than the first, however if this is not the case, the tool will automatically swap the two parameters. Both standard deviations can range from 0.5-20.

The difference-of-Gaussians filter can be used to emphasize edges present in an image. Other edge-sharpening filters also operate by enhancing high-frequency detail, but because random noise also has a high spatial frequency, many of these sharpening filters tend to enhance noise, which can be an undesirable artifact. The difference-of-Gaussians filter can remove high-frequency noise while emphasizing edges. This filter can, however, reduce overall image contrast.

See Also: GaussianFilter, FastAlmostGaussianFilter, LaplacianFilter, LaplacianOfGaussianFilter`

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--sigma1Standard deviation distance in pixels
--sigma2Standard deviation distance in pixels

Python function:

wbt.diff_of_gaussian_filter(
    i, 
    output, 
    sigma1=2.0, 
    sigma2=4.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DiffOfGaussianFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --sigma1=2.0 ^
--sigma2=4.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

DiversityFilter

This tool assigns each cell in the output grid the number of different values in a moving window centred on each grid cell in the input raster. The input image should contain integer values but floating point data are allowable and will be handled by multiplying pixel values by 1000 and rounding. Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values, e.g. 3, 5, 7, 9... If the kernel filter size is the same in the x and y dimensions, the silent --filter flag may be used instead (command-line interface only).

See Also: MajorityFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.diversity_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DiversityFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 03/05/2019

EdgePreservingMeanFilter

This tool performs a type of edge-preserving mean filter operation on an input image (--input). The filter, a type of low-pass filter, can be used to emphasize the longer-range variability in an image, effectively acting to smooth the image and to reduce noise in the image. The algorithm calculates the average value in a moving window centred on each grid cell, including in the averaging only the set of neighbouring values for which the absolute value difference with the centre value is less than a specified threshold value (--threshold). It is, therefore, similar to the BilateralFilter, except all neighbours within the threshold difference are equally weighted and neighbour distance is not accounted for. Filter kernels are always square, and filter size, is specified using the --filter parameter. This dimensions should be odd, positive integer values, e.g. 3, 5, 7, 9...

This tool works with both greyscale and red-green-blue (RGB) input images. RGB images are decomposed into intensity-hue-saturation (IHS) and the filter is applied to the intensity channel. If an RGB image is input, the threshold value must be in the range 0.0-1.0 (more likely less than 0.15), where a value of 1.0 would result in an ordinary mean filter (MeanFilter). NoData values in the input image are ignored during filtering.

See Also: MeanFilter, BilateralFilter, EdgePreservingMeanFilter, GaussianFilter, MedianFilter, RgbToIhs

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterSize of the filter kernel
--thresholdMaximum difference in values

Python function:

wbt.edge_preserving_mean_filter(
    i, 
    output, 
    threshold, 
    filter=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=EdgePreservingMeanFilter -v ^
--wd="/path/to/data/" --input=image.tif -o=output.tif ^
--filter=5 --threshold=20 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/03/2018

Last Modified: 22/10/2019

EmbossFilter

This tool can be used to perform one of eight 3x3 emboss filters on a raster image. Like the SobelFilter and PrewittFilter, the EmbossFilter is often applied in edge-detection applications. While these other two common edge-detection filters approximate the slope magnitude of the local neighbourhood surrounding each grid cell, the EmbossFilter can be used to estimate the directional slope. The kernel weights for each of the eight available filters are as follows:

North (n)

...
0-10
000
010

Northeast (ne)

...
00-1
000
-100

East (e)

...
000
10-1
000

Southeast (se)

...
100
000
00-1

South (s)

...
010
000
0-10

Southwest (sw)

...
001
000
-100

West (w)

...
000
-101
000

Northwest (nw)

...
-100
000
001

The user must specify the --direction, options include 'n', 's', 'e', 'w', 'ne', 'se', 'nw', 'sw'. The user may also optionally clip the output image distribution tails by a specified amount (e.g. 1%).

See Also: SobelFilter, PrewittFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--directionDirection of reflection; options include 'n', 's', 'e', 'w', 'ne', 'se', 'nw', 'sw'
--clipOptional amount to clip the distribution tails by, in percent

Python function:

wbt.emboss_filter(
    i, 
    output, 
    direction="n", 
    clip=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=EmbossFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --direction='s' --clip=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 22/10/2019

FastAlmostGaussianFilter

The tool is somewhat modified from Dr. Kovesi's original Matlab code in that it works with both greyscale and RGB images (decomposes to HSI and uses the intensity data) and it handles the case of rasters that contain NoData values. This adds complexity to the original 20 additions and 5 multiplications assertion of the original paper.

Also note, for small values of sigma (< 1.8), you should probably just use the regular GaussianFilter tool.

Reference:

P. Kovesi 2010 Fast Almost-Gaussian Filtering, Digital Image Computing: Techniques and Applications (DICTA), 2010 International Conference on.

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--sigmaStandard deviation distance in pixels

Python function:

wbt.fast_almost_gaussian_filter(
    i, 
    output, 
    sigma=1.8, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FastAlmostGaussianFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --sigma=2.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/05/2018

Last Modified: 30/01/2020

GaussianFilter

This tool can be used to perform a Gaussian filter on a raster image. A Gaussian filter can be used to emphasize the longer-range variability in an image, effectively acting to smooth the image. This can be useful for reducing the noise in an image. The algorithm operates by convolving a kernel of weights with each grid cell and its neighbours in an image. The weights of the convolution kernel are determined by the 2-dimensional Gaussian (i.e. normal) curve, which gives stronger weighting to cells nearer the kernel centre. It is this characteristic that makes the Gaussian filter an attractive alternative for image smoothing and noise reduction than the MeanFilter. The size of the filter is determined by setting the standard deviation parameter (--sigma), which is in units of grid cells; the larger the standard deviation the larger the resulting filter kernel. The standard deviation can be any number in the range 0.5-20.

GaussianFilter works with both greyscale and red-green-blue (RGB) colour images. RGB images are decomposed into intensity-hue-saturation (IHS) and the filter is applied to the intensity channel. NoData values in the input image are ignored during processing.

Like many low-pass filters, Gaussian filtering can significantly blur well-defined edges in the input image. The EdgePreservingMeanFilter and BilateralFilter offer more robust feature preservation during image smoothing. GaussianFilter is relatively slow compared to the FastAlmostGaussianFilter tool, which offers a fast-running approximatation to a Gaussian filter for larger kernel sizes.

See Also: FastAlmostGaussianFilter, MeanFilter, MedianFilter, RgbToIhs

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--sigmaStandard deviation distance in pixels

Python function:

wbt.gaussian_filter(
    i, 
    output, 
    sigma=0.75, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=GaussianFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --sigma=2.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

HighPassBilateralFilter

This tool can be used to perform a high-pass bilateral filter. A high-pass filter is one which emphasizes short-scale variation within an image, usually by differencing the input image value from the result of a low-pass, smoothing filter. In this case, the low-pass filter is an edge-preserving bilateral filter (BilateralFilter). High-pass filters are often dominated by edges (transitions from high values to low values or vice versa) within an image. Because the bilateral filter is an edge-preserving filter, the high-pass bilateral filter output is not dominated by edges, instead emphasizing local-scale image texture patters. This filter is excellent for mapping image textures.

The size of the filter is determined by setting the standard deviation distance parameter (--sigma_dist); the larger the standard deviation the larger the resulting filter kernel. The standard deviation can be any number in the range 0.5-20 and is specified in the unit of pixels. The standard deviation intensity parameter (--sigma_int), specified in the same units as the image values, determines the intensity domain contribution to kernel weightings. If the input image is an RGB composite, the intensity value is filtered, and the intensity parameter should lie 0 > parameter < 1, with typical values ranging from 0.05 to 0.25. If the input image is not an RGB colour composite, appropriate values of this parameter will depend on the range of input values and will likely be considerably higher.

References:

Tomasi, C., & Manduchi, R. (1998, January). Bilateral filtering for gray and color images. In null (p. 839). IEEE.

See Also: BilateralFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--sigma_distStandard deviation in distance in pixels
--sigma_intStandard deviation in intensity in pixels

Python function:

wbt.high_pass_bilateral_filter(
    i, 
    output, 
    sigma_dist=0.75, 
    sigma_int=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HighPassBilateralFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif ^
--sigma_dist=2.5 --sigma_int=4.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 30/01/2020

HighPassFilter

This tool performs a high-pass filter on a raster image. High-pass filters can be used to emphasize the short-range variability in an image. The algorithm operates essentially by subtracting the value at the grid cell at the centre of the window from the average value in the surrounding neighbourhood (i.e. window.)

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

See Also: HighPassMedianFilter, MeanFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.high_pass_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HighPassFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

HighPassMedianFilter

This tool performs a high-pass median filter on a raster image. High-pass filters can be used to emphasize the short-range variability in an image. The algorithm operates essentially by subtracting the value at the grid cell at the centre of the window from the median value in the surrounding neighbourhood (i.e. window.)

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

See Also: HighPassFilter, MedianFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction
--sig_digitsNumber of significant digits

Python function:

wbt.high_pass_median_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    sig_digits=2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HighPassMedianFilter -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/09/2018

Last Modified: 22/10/2019

KNearestMeanFilter

This tool performs a k-nearest mean filter on a raster image. A mean filter can be used to emphasize the longer-range variability in an image, effectively acting to smooth or blur the image. This can be useful for reducing the noise in an image. The algorithm operates by calculating the average of a specified number (k) values in a moving window centred on each grid cell. The k values used in the average are those cells in the window with the nearest intensity values to that of the centre cell. As such, this is a type of edge-preserving smoothing filter. The BilateralFilter and EdgePreservingMeanFilter are examples of more sophisticated edge-preserving smoothing filters.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

NoData values in the input image are ignored during filtering.

See Also: MeanFilter, BilateralFilter, EdgePreservingMeanFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction
-kk-value in pixels; this is the number of nearest-valued neighbours to use

Python function:

wbt.k_nearest_mean_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    k=5, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=KNearestMeanFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --filter=9 ^
-k=5
>>./whitebox_tools -r=KNearestMeanFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --filtery=7 ^
--filtery=9 -k=5 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 30/01/2020

LaplacianFilter

This tool can be used to perform a Laplacian filter on a raster image. A Laplacian filter can be used to emphasize the edges in an image. As such, this filter type is commonly used in edge-detection applications. The algorithm operates by convolving a kernel of weights with each grid cell and its neighbours in an image. Four 3x3 sized filters and one 5x5 filter are available for selection. The weights of the kernels are as follows:

3x3(1)

...
0-10
-14-1
0-10

3x3(2)

...
0-10
-15-1
0-10

3x3(3)

...
-1-1-1
-18-1
-1-1-1

3x3(4)

...
1-21
-24-2
1-21

5x5(1)

.....
00-100
0-1-2-10
-1-217-2-1
0-1-2-10
00-100

5x5(2)

.....
00-100
0-1-2-10
-1-216-2-1
0-1-2-10
00-100

The user must specify the --variant, including '3x3(1)', '3x3(2)', '3x3(3)', '3x3(4)', '5x5(1)', and '5x5(2)'. The user may also optionally clip the output image distribution tails by a specified amount (e.g. 1%).

See Also: PrewittFilter, SobelFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--variantOptional variant value. Options include 3x3(1), 3x3(2), 3x3(3), 3x3(4), 5x5(1), and 5x5(2) (default is 3x3(1))
--clipOptional amount to clip the distribution tails by, in percent

Python function:

wbt.laplacian_filter(
    i, 
    output, 
    variant="3x3(1)", 
    clip=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LaplacianFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif ^
--variant='3x3(1)' --clip=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 30/01/2020

LaplacianOfGaussianFilter

The Laplacian-of-Gaussian (LoG) is a spatial filter used for edge enhancement and is closely related to the difference-of-Gaussians filter (DiffOfGaussianFilter). The formulation of the LoG filter algorithm is based on the equation provided in the Hypermedia Image Processing Reference (HIPR) 2. The LoG operator calculates the second spatial derivative of an image. In areas where image intensity is constant, the LoG response will be zero. Near areas of change in intensity the LoG will be positive on the darker side, and negative on the lighter side. This means that at a sharp edge, or boundary, between two regions of uniform but different intensities, the LoG response will be:

  • zero at a long distance from the edge,
  • positive just to one side of the edge,
  • negative just to the other side of the edge,
  • zero at some point in between, on the edge itself.

The user may optionally choose to reflecting the data along image edges. NoData values in the input image are similarly valued in the output. The output raster is of the float data type and continuous data scale.

Reference:

Fisher, R. 2004. Hypertext Image Processing Resources 2 (HIPR2). Available online: http://homepages.inf.ed.ac.uk/rbf/HIPR2/roberts.htm

See Also: DiffOfGaussianFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--sigmaStandard deviation in pixels

Python function:

wbt.laplacian_of_gaussian_filter(
    i, 
    output, 
    sigma=0.75, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LaplacianOfGaussianFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --sigma=2.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

LeeSigmaFilter

The Lee Sigma filter is a low-pass filter used to smooth the input image (--input). The user must specify the dimensions of the filter (--filterx and --filtery) as well as the sigma (--sigma) and M (-m) parameter.

Reference:

Lee, J. S. (1983). Digital image smoothing and the sigma filter. Computer vision, graphics, and image processing, 24(2), 255-269.

See Also: MeanFilter, GaussianFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction
--sigmaSigma value should be related to the standard deviation of the distribution of image speckle noise
-mM-threshold value the minimum allowable number of pixels within the intensity range

Python function:

wbt.lee_sigma_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    sigma=10.0, 
    m=5.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LeeSigmaFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filter=9 --sigma=10.0 ^
-m=5
>>./whitebox_tools -r=LeeSigmaFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --filtery=7 ^
--filtery=9 --sigma=10.0 -m=5 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 30/01/2020

LineDetectionFilter

This tool can be used to perform one of four 3x3 line-detection filters on a raster image. These filters can be used to find one-cell-thick vertical, horizontal, or angled (135-degrees or 45-degrees) lines in an image. Notice that line-finding is a similar application to edge-detection. Common edge-detection filters include the Sobel and Prewitt filters. The kernel weights for each of the four line-detection filters are as follows:

'v' (Vertical)

...
-12-1
-12-1
-12-1

'h' (Horizontal)

...
-1-1-1
222
-1-1-1

'45' (Northeast-Southwest)

...
-1-12
-12-1
2-1-1

'135' (Northwest-Southeast)

...
2-1-1
-12-1
-1-12

The user must specify the --variant, including 'v', 'h', '45', and '135', for vertical, horizontal, northeast-southwest, and northwest-southeast directions respectively. The user may also optionally clip the output image distribution tails by a specified amount (e.g. 1%).

See Also: PrewittFilter, SobelFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--variantOptional variant value. Options include 'v' (vertical), 'h' (horizontal), '45', and '135' (default is 'v')
--absvalsOptional flag indicating whether outputs should be absolute values
--clipOptional amount to clip the distribution tails by, in percent

Python function:

wbt.line_detection_filter(
    i, 
    output, 
    variant="vertical", 
    absvals=False, 
    clip=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LineDetectionFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --variant=h ^
--clip=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 30/01/2020

MajorityFilter

This tool performs a majority (or modal) filter on a raster image. A mode filter assigns each cell in the output grid the most commonly occurring value, i.e. mode, in a moving window centred on each grid cell. Mode filters should only be applied to input images of a categorical data scale. The input image should contain integer values but floating point data will be handled using a multiplier. Because it requires binning the values in the window, a relatively computationally intensive task, MajorityFilter is considerably less efficient than other smoothing filters. This may pose a problem for large images or large neighbourhoods. Like all WhiteboxTools' filters, however, this tool is parallelized, benefitting from multi-core processors, and the tool also takes advantage of the redundancy of the overlapping areas of filter windows along a row of data.

Neighbourhood size, or filter size, is determined by the user-defined x and y dimensions. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

NoData values in the input image are ignored during filtering. When the neighbourhood around a grid cell extends beyond the edge of the grid, NoData values are assigned to these sites. In the event of multiple modes, i.e. neighbourhoods for which there is more than one class with tied and maximal frequency within the neighbourhood, the tool will report the first-discovered class value in the output raster. This is unlikely to be an issue for larger filter windows, but may be more problematic at smaller window sizes.

See Also: MedianFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.majority_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MajorityFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 30/01/2020

MaximumFilter

This tool assigns each cell in the output grid (--output) the maximum value in a moving window centred on each grid cell in the input raster (--input). A maximum filter is the equivalent of the mathematical morphological dilation operator.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values, e.g. 3, 5, 7, 9... If the kernel filter size is the same in the x and y dimensions, the silent --filter flag may be used instead (command-line interface only).

This tool takes advantage of the redundancy between overlapping, neighbouring filters to enhance computationally efficiency. Like most of WhiteboxTools' filters, it is also parallelized for further efficiency.

See Also: MinimumFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.maximum_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MaximumFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

MeanFilter

This tool performs a mean filter operation on a raster image. A mean filter, a type of low-pass filter, can be used to emphasize the longer-range variability in an image, effectively acting to smooth the image. This can be useful for reducing the noise in an image. This tool utilizes an integral image approach (Crow, 1984) to ensure highly efficient filtering that is invariant to filter size. The algorithm operates by calculating the average value in a moving window centred on each grid cell. Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values, e.g. 3, 5, 7, 9... If the kernel filter size is the same in the x and y dimensions, the silent --filter flag may be used instead (command-line interface only).

Although commonly applied in digital image processing, mean filters are generally considered to be quite harsh, with respect to their impact on the image, compared to other smoothing filters such as the edge-preserving smoothing filters including the BilateralFilter, MedianFilter, OlympicFilter, EdgePreservingMeanFilter and even GaussianFilter.

This tool works with both greyscale and red-green-blue (RGB) images. RGB images are decomposed into intensity-hue-saturation (IHS) and the filter is applied to the intensity channel. NoData values in the input image are ignored during filtering. NoData values are assigned to all sites beyond the raster.

Reference:

Crow, F. C. (1984, January). Summed-area tables for texture mapping. In ACM SIGGRAPH computer graphics (Vol. 18, No. 3, pp. 207-212). ACM.

See Also: BilateralFilter, EdgePreservingMeanFilter, GaussianFilter, MedianFilter, RgbToIhs

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.mean_filter(
    i, 
    output, 
    filterx=3, 
    filtery=3, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MeanFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filterx=25 --filtery=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 22/10/2019

MedianFilter

This tool performs a median filter on a raster image. Median filters, a type of low-pass filter, can be used to emphasize the longer-range variability in an image, effectively acting to smooth the image. This can be useful for reducing the noise in an image. The algorithm operates by calculating the median value (middle value in a sorted list) in a moving window centred on each grid cell. Specifically, this tool uses the efficient running-median filtering algorithm of Huang et al. (1979). The median value is not influenced by anomolously high or low values in the distribution to the extent that the average is. As such, the median filter is far less sensitive to shot noise in an image than the mean filter.

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

Reference:

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: BilateralFilter, EdgePreservingMeanFilter, GaussianFilter, MeanFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction
--sig_digitsNumber of significant digits

Python function:

wbt.median_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    sig_digits=2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MedianFilter -v --wd="/path/to/data/" ^
-i=input.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/07/2017

Last Modified: 22/10/2019

MinimumFilter

This tool assigns each cell in the output grid (--output) the minimum value in a moving window centred on each grid cell in the input raster (--input). A maximum filter is the equivalent of the mathematical morphological erosion operator.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values, e.g. 3, 5, 7, 9... If the kernel filter size is the same in the x and y dimensions, the silent --filter flag may be used instead (command-line interface only).

This tool takes advantage of the redundancy between overlapping, neighbouring filters to enhance computationally efficiency. Like most of WhiteboxTools' filters, it is also parallelized for further efficiency.

See Also: MaximumFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.minimum_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MinimumFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

OlympicFilter

This filter is a modification of the MeanFilter, whereby the highest and lowest values in the kernel are dropped, and the remaining values are averaged to replace the central pixel. The result is a low-pass smoothing filter that is more robust than the MeanFilter, which is more strongly impacted by the presence of outlier values. It is named after a system of scoring Olympic events.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

See Also: MeanFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.olympic_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=OlympicFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

PercentileFilter

This tool calculates the percentile of the center cell in a moving filter window applied to an input image (`--input). This indicates the value below which a given percentage of the neighbouring values in within the filter fall. For example, the 35th percentile is the value below which 35% of the neighbouring values in the filter window may be found. As such, the percentile of a pixel value is indicative of the relative location of the site within the statistical distribution of values contained within a filter window. When applied to input digital elevation models, percentile is a measure of local topographic position, or elevation residual.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values, e.g. 3, 5, 7, 9... If the kernel filter size is the same in the x and y dimensions, the silent --filter flag may be used instead (command-line interface only).

This tool takes advantage of the redundancy between overlapping, neighbouring filters to enhance computationally efficiency, using a method similar to Huang et al. (1979). This efficient method of calculating percentiles requires rounding of floating-point inputs, and therefore the user must specify the number of significant digits (--sig_digits) to be used during the processing. Like most of WhiteboxTools' filters, this tool is also parallelized for further efficiency.

Reference:

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

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction
--sig_digitsNumber of significant digits

Python function:

wbt.percentile_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    sig_digits=2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PercentileFilter -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 03/05/2019

PrewittFilter

This tool performs a 3 × 3 Prewitt edge-detection filter on a raster image. The Prewitt filter is similar to the SobelFilter, in that it identifies areas of high slope in the input image through the calculation of slopes in the x and y directions. The Prewitt edge-detection filter, however, gives less weight to nearer cell values within the moving window, or kernel. For example, a Prewitt filter uses the following schemes to calculate x and y slopes:

X-direction slope

...
-101
-101
-101

Y-direction slope

...
111
000
-1-1-1

Each grid cell in the output image is assigned the square-root of the squared sum of the x and y slopes.

The user may optionally clip the output image distribution tails by a specified amount (e.g. 1%).

See Also: SobelFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--clipOptional amount to clip the distribution tails by, in percent

Python function:

wbt.prewitt_filter(
    i, 
    output, 
    clip=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PrewittFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --clip=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 30/01/2020

RangeFilter

This tool performs a range filter on an input image (--input). A range filter assigns to each cell in the output grid (--output) the range (maximum - minimum) of the values contained within a moving window centred on each grid cell.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

See Also: TotalFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.range_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RangeFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

RobertsCrossFilter

This tool performs Robert's Cross edge-detection filter on a raster image. The RobertsCrossFilter is similar to the SobelFilter and PrewittFilter, in that it identifies areas of high slope in the input image through the calculation of slopes in the x and y directions. A Robert's Cross filter uses the following 2 × 2 schemes to calculate slope magnitude, |G|:

..
P1P2
P3P4

|G| = |P1 - P4| + |P2- P3|

Note, the filter is centered on pixel P1 and P2, P3, and P4 are the neighbouring pixels towards the east, south, and south-east respectively.

The output image may be overwhelmed by a relatively small number of high-valued pixels, stretching the palette. The user may therefore optionally clip the output image distribution tails by a specified amount (--clip) for improved visualization.

Reference:

Fisher, R. 2004. Hypertext Image Processing Resources 2 (HIPR2). Available online: http://homepages.inf.ed.ac.uk/rbf/HIPR2/roberts.htm

See Also: SobelFilter, PrewittFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--clipOptional amount to clip the distribution tails by, in percent

Python function:

wbt.roberts_cross_filter(
    i, 
    output, 
    clip=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RobertsCrossFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --clip=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 30/01/2020

ScharrFilter

This tool performs a Scharr edge-detection filter on a raster image. The Scharr filter is similar to the SobelFilter and PrewittFilter, in that it identifies areas of high slope in the input image through the calculation of slopes in the x and y directions. A 3 × 3 Scharr filter uses the following schemes to calculate x and y slopes:

X-direction slope

...
30-3
100-10
30-3

Y-direction slope

...
3103
000
-3-10-3

Each grid cell in the output image is assigned the square-root of the squared sum of the x and y slopes.

The output image may be overwhelmed by a relatively small number of high-valued pixels, stretching the palette. The user may therefore optionally clip the output image distribution tails by a specified amount (--clip) for improved visualization.

See Also: SobelFilter, PrewittFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--clipOptional amount to clip the distribution tails by, in percent

Python function:

wbt.scharr_filter(
    i, 
    output, 
    clip=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ScharrFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --clip=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 30/01/2020

SobelFilter

This tool performs a 3 × 3 or 5 × 5 Sobel edge-detection filter on a raster image. The Sobel filter is similar to the PrewittFilter, in that it identifies areas of high slope in the input image through the calculation of slopes in the x and y directions. The Sobel edge-detection filter, however, gives more weight to nearer cell values within the moving window, or kernel. For example, a 3 × 3 Sobel filter uses the following schemes to calculate x and y slopes:

X-direction slope

...
-101
-202
-101

Y-direction slope

...
121
000
-1-2-1

Each grid cell in the output image is assigned the square-root of the squared sum of the x and y slopes.

The user must specify the --variant, including '3x3' and '5x5' variants. The user may also optionally clip the output image distribution tails by a specified amount (e.g. 1%).

See Also: PrewittFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--variantOptional variant value. Options include 3x3 and 5x5 (default is 3x3)
--clipOptional amount to clip the distribution tails by, in percent (default is 0.0)

Python function:

wbt.sobel_filter(
    i, 
    output, 
    variant="3x3", 
    clip=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SobelFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --variant=5x5 --clip=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 30/01/2020

StandardDeviationFilter

This tool performs a standard deviation filter on an input image (--input). A standard deviation filter assigns to each cell in the output grid (--output) the standard deviation, a measure of dispersion, of the values contained within a moving window centred on each grid cell.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

See Also: RangeFilter, TotalFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.standard_deviation_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=StandardDeviationFilter -v ^
--wd="/path/to/data/" -i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 30/01/2020

TotalFilter

This tool performs a total filter on an input image. A total filter assigns to each cell in the output grid the total (sum) of all values in a moving window centred on each grid cell.

Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx and --filtery flags. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

See Also: RangeFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--filterxSize of the filter kernel in the x-direction
--filterySize of the filter kernel in the y-direction

Python function:

wbt.total_filter(
    i, 
    output, 
    filterx=11, 
    filtery=11, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=TotalFilter -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --filter=25 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 30/01/2020

UnsharpMasking

Unsharp masking is an image edge-sharpening technique commonly applied in digital image processing. Admittedly, the name 'unsharp' seems somewhat counter-intuitive given the purpose of the filter, which is to enchance the definition of edge features within the input image (--input). This name comes from the use of a blurred, or unsharpened, intermediate image (mask) in the process. The blurred image is combined with the positive (original) image, creating an image that exhibits enhanced feature definition. A caution is needed in that the output image, although clearer, may be a less accurate representation of the image's subject. The output may also contain more speckle than the input image.

In addition to the input (--input) and output (--output) image files, the user must specify the values of three parameters: the standard deviation distance (--sigma), which is a measure of the filter size in pixels, the amount (--amount), a percentage value that controls the magnitude of each overshoot at edges, and lastly, the threshold (--threshold), which controls the minimal brightness change that will be sharpened. Pixels with values differ after the calculation of the filter by less than the threshold are unmodified in the output image.

UnsharpMasking works with both greyscale and red-green-blue (RGB) colour images. RGB images are decomposed into intensity-hue-saturation (IHS) and the filter is applied to the intensity channel. Importantly, the intensity values range from 0-1, which is important when setting the threshold value for colour images. NoData values in the input image are ignored during processing.

See Also: GaussianFilter, HighPassFilter

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--sigmaStandard deviation distance in pixels
--amountA percentage and controls the magnitude of each overshoot
--thresholdControls the minimal brightness change that will be sharpened

Python function:

wbt.unsharp_masking(
    i, 
    output, 
    sigma=0.75, 
    amount=100.0, 
    threshold=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=UnsharpMasking -v --wd="/path/to/data/" ^
-i=image.tif -o=output.tif --sigma=2.0 --amount=50.0 ^
--threshold=10.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/05/2018

Last Modified: 22/10/2019

UserDefinedWeightsFilter

NoData values in the input image are ignored during the convolution operation. This can lead to unexpected behavior at the edges of images (since the default behavior is to return NoData when addressing cells beyond the grid edge) and where the grid contains interior areas of NoData values. Normalization of kernel weights can be useful for handling the edge effects associated with interior areas of NoData values. When the normalization option is selected, the sum of the cell value-weight product is divided by the sum of the weights on a cell-by-cell basis. Therefore, if the kernel at a particular grid cell contains neighboring cells of NoData values, normalization effectively re-adjusts the weighting to account for the missing data values. Normalization also ensures that the output image will possess values within the range of the input image and allows the user to specify integer value weights in the kernel. However, note that this implies that the sum of weights should equal one. In some cases, alternative sums (e.g. zero) are more appropriate, and as such normalization should not be applied in these cases.

Parameters:

FlagDescription
-i, --inputInput raster file
--weightsInput weights file
-o, --outputOutput raster file
--centerKernel center cell; options include 'center', 'upper-left', 'upper-right', 'lower-left', 'lower-right'
--normalizeNormalize kernel weights? This can reduce edge effects and lessen the impact of data gaps (nodata) but is not suited when the kernel weights sum to zero

Python function:

wbt.user_defined_weights_filter(
    i, 
    weights, 
    output, 
    center="center", 
    normalize=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=UserDefinedWeightsFilter -v ^
--wd="/path/to/data/" -i=image.tif --weights=weights.txt ^
-o=output.tif --center=center --normalize 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/04/2018

Last Modified: 22/10/2019

Image Processing Tools → Image Enhancement

BalanceContrastEnhancement

This tool can be used to reduce colour bias in a colour composite image based on the technique described by Liu (1991). Colour bias is a common phenomena with colour images derived from multispectral imagery, whereby a higher average brightness value in one band results in over-representation of that band in the colour composite. The tool essentially applies a parabolic stretch to each of the three bands in a user specified RGB colour composite, forcing the histograms of each band to have the same minimum, maximum, and average values while maintaining their overall histogram shape. For greater detail on the operation of the tool, please see Liu (1991). Aside from the names of the input and output colour composite images, the user must also set the value of E, the desired output band mean, where 20 < E < 235.

Reference:

Liu, J.G. (1991) Balance contrast enhancement technique and its application in image colour composition. International Journal of Remote Sensing, 12:10.

See Also: DirectDecorrelationStretch, HistogramMatching, HistogramMatchingTwoImages, HistogramEqualization, GaussianContrastStretch

Parameters:

FlagDescription
-i, --inputInput colour composite image file
-o, --outputOutput raster file
--band_meanBand mean value

Python function:

wbt.balance_contrast_enhancement(
    i, 
    output, 
    band_mean=100.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BalanceContrastEnhancement -v ^
--wd="/path/to/data/" --input=image.tif -o=output.tif ^
--band_mean=120 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/07/2017

Last Modified: 30/01/2020

CorrectVignetting

This tool can be used to reduce vignetting within an image. Vignetting refers to the reduction of image brightness away from the image centre (i.e. the principal point). Vignetting is a radiometric distortion resulting from lens characteristics. The algorithm calculates the brightness value in the output image (BVout) as:

BVout = BVin / [cos^n(arctan(d / f))]

Where d is the photo-distance from the principal point in millimetres, f is the focal length of the camera, in millimeters, and n is a user-specified parameter. Pixel distances are converted to photo-distances (in millimetres) using the specified image width, i.e. distance between left and right edges (mm). For many cameras, 4.0 is an appropriate value of the n parameter. A second pass of the image is used to rescale the output image so that it possesses the same minimum and maximum values as the input image.

If an RGB image is input, the analysis will be performed on the intensity component of the HSI transform.

Parameters:

FlagDescription
-i, --inputInput raster file
--ppInput principal point file
-o, --outputOutput raster file
--focal_lengthCamera focal length, in millimeters
--image_widthDistance between photograph edges, in millimeters
-nThe 'n' parameter

Python function:

wbt.correct_vignetting(
    i, 
    pp, 
    output, 
    focal_length=304.8, 
    image_width=228.6, 
    n=4.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CorrectVignetting -v ^
--wd="/path/to/data/" -i=input.tif --pp=princ_pt.shp ^
-o=output.tif --focal_length=304.8 --image_width=228.6 ^
-n=4.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/04/2018

Last Modified: 22/10/2019

DirectDecorrelationStretch

The Direct Decorrelation Stretch (DDS) is a simple type of saturation stretch. The stretch is applied to a colour composite image and is used to improve the saturation, or colourfulness, of the image. The DDS operates by reducing the achromatic (grey) component of a pixel's colour by a scale factor (k), such that the red (r), green (g), and blue (b) components of the output colour are defined as:

rk = r - k min(r, g, b)

gk = g - k min(r, g, b)

bk = b - k min(r, g, b)

The achromatic factor (k) can range between 0 (no effect) and 1 (full saturation stretch), although typical values range from 0.3 to 0.7. A linear stretch is used afterwards to adjust overall image brightness. Liu and Moore (1996) recommend applying a colour balance stretch, such as BalanceContrastEnhancement before using the DDS.

Reference:

Liu, J.G., and Moore, J. (1996) Direct decorrelation stretch technique for RGB colour composition. International Journal of Remote Sensing, 17:5, 1005-1018.

See Also: CreateColourComposite, BalanceContrastEnhancement

Parameters:

FlagDescription
-i, --inputInput colour composite image file
-o, --outputOutput raster file
-kAchromatic factor (k) ranges between 0 (no effect) and 1 (full saturation stretch), although typical values range from 0.3 to 0.7
--clipOptional percent to clip the upper tail by during the stretch

Python function:

wbt.direct_decorrelation_stretch(
    i, 
    output, 
    k=0.5, 
    clip=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=DirectDecorrelationStretch -v ^
--wd="/path/to/data/" --input=image.tif -o=output.tif -k=0.4 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/07/2017

Last Modified: 30/01/2020

GammaCorrection

This tool performs a gamma colour correction transform on an input image (--input), such that each input pixel value (zin) is mapped to the corresponding output value (zout) as:

zout = zingamma

The user must specify the value of the gamma parameter. The input image may be of either a greyscale or RGB colour composite data type.

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--gammaGamma value

Python function:

wbt.gamma_correction(
    i, 
    output, 
    gamma=0.5, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=GammaCorrection -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --gamma=0.5 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/07/2017

Last Modified: 22/10/2019

GaussianContrastStretch

This tool performs a Gaussian stretch on a raster image. The observed histogram of the input image is fitted to a Gaussian histogram, i.e. normal distribution. A histogram matching technique is used to map the values from the input image onto the output Gaussian distribution. The user must the number of tones (--num_tones) used in the output image.

This tool is related to the more general HistogramMatching tool, which can be used to fit any frequency distribution to an input image, and other contrast enhancement tools such as HistogramEqualization, MinMaxContrastStretch, PercentageContrastStretch, SigmoidalContrastStretch, and StandardDeviationContrastStretch.

See Also: PiecewiseContrastStretch, HistogramEqualization, MinMaxContrastStretch, PercentageContrastStretch, SigmoidalContrastStretch, StandardDeviationContrastStretch, HistogramMatching

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--num_tonesNumber of tones in the output image

Python function:

wbt.gaussian_contrast_stretch(
    i, 
    output, 
    num_tones=256, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=GaussianContrastStretch -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif ^
--num_tones=1024 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/05/2018

Last Modified: 22/10/2019

HistogramEqualization

This tool alters the cumulative distribution function (CDF) of a raster image to match, as closely as possible, the CDF of a uniform distribution. Histogram equalization works by first calculating the histogram of the input image. This input histogram is then converted into a CDF. Each grid cell value in the input image is then mapped to the corresponding value in the uniform distribution's CDF that has an equivalent (or as close as possible) cumulative probability value. Histogram equalization provides a very effective means of performing image contrast adjustment in an efficient manner with little need for human input.

The user must specify the name of the input image to perform histogram equalization on. The user must also specify the number of tones, corresponding to the number of histogram bins used in the analysis.

HistogramEqualization is related to the HistogramMatchingTwoImages tool (used when an image's CDF is to be matched to a reference CDF derived from a reference image). Similarly, HistogramMatching, and GaussianContrastStretch are similarly related tools frequently used for image contrast adjustment, where the reference CDFs are uniform and Gaussian (normal) respectively.

Notes:

  • The algorithm can introduces gaps in the histograms (steps in the CDF). This is to be expected because the histogram is being distorted. This is more prevalent for integer-level images.
  • Histogram equalization is not appropriate for images containing categorical (class) data.

See Also: PiecewiseContrastStretch, HistogramMatching, HistogramMatchingTwoImages, GaussianContrastStretch

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--num_tonesNumber of tones in the output image

Python function:

wbt.histogram_equalization(
    i, 
    output, 
    num_tones=256, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HistogramEqualization -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif ^
--num_tones=1024 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/08/2017

Last Modified: 30/01/2020

HistogramMatching

This tool alters the cumulative distribution function (CDF) of a raster image to match, as closely as possible, the CDF of a reference histogram. Histogram matching works by first calculating the histogram of the input image. This input histogram and reference histograms are each then converted into CDFs. Each grid cell value in the input image is then mapped to the corresponding value in the reference CDF that has an equivalent (or as close as possible) cumulative probability value. Histogram matching provides the most flexible means of performing image contrast adjustment.

The reference histogram must be specified to the tool in the form of a text file (.txt), provided using the --histo_file flag. This file must contain two columns (delimited by a tab, space, comma, colon, or semicolon) where the first column contains the x value (i.e. the values that will be assigned to the grid cells in the output image) and the second column contains the frequency or probability. Note that 1) the file must not contain a header row, 2) each x value/frequency pair must be on a separate row, and 3) the frequency/probability must not be cumulative (i.e. the file must contain the histogram and not the CDF). The CDF will be computed for the reference histogram automatically by the tool. It is possible to create this type of histogram using the wide range of distribution tools available in most spreadsheet programs (e.g. Excel or LibreOffice's Calc program). You must save the file as a text-only (ASCII) file.

HistogramMatching is related to the HistogramMatchingTwoImages tool, which can be used when a reference CDF can be derived from a reference image. HistogramEqualization and GaussianContrastStretch are similarly related tools frequently used for image contrast adjustment, where the reference CDFs are uniform and Gaussian (normal) respectively.

Notes:

  • The algorithm can introduces gaps in the histograms (steps in the CDF). This is to be expected because the histogram is being distorted. This is more prevalent for integer-level images.
  • Histogram matching is not appropriate for images containing categorical (class) data.
  • This tool is not intended for images containing RGB data. If this is the case, the colour channels should be split using the SplitColourComposite tool.

See Also: HistogramMatchingTwoImages, HistogramEqualization, GaussianContrastStretch, SplitColourComposite

Parameters:

FlagDescription
-i, --inputInput raster file
--histo_fileInput reference probability distribution function (pdf) text file
-o, --outputOutput raster file

Python function:

wbt.histogram_matching(
    i, 
    histo_file, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HistogramMatching -v ^
--wd="/path/to/data/" -i=input1.tif --histo_file=histo.txt ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/09/2017

Last Modified: 13/10/2018

HistogramMatchingTwoImages

This tool alters the cumulative distribution function (CDF) of a raster image to match, as closely as possible, the CDF of a reference image. Histogram matching works by first calculating the histograms of the input image (i.e. the image to be adjusted) and the reference image. These histograms are then converted into CDFs. Each grid cell value in the input image is then mapped to the corresponding value in the reference CDF that has the an equivalent (or as close as possible) cumulative probability value. A common application of this is to match the images from two sensors with slightly different responses, or images from the same sensor, but the sensor's response is known to change over time.The size of the two images (rows and columns) do not need to be the same, nor do they need to be geographically overlapping.

HistogramMatchingTwoImages is related to the HistogramMatching tool, which can be used when a reference CDF is used directly rather than deriving it from a reference image. HistogramEqualization and GaussianContrastStretch are similarly related tools, where the reference CDFs are uniform and Gaussian (normal) respectively.

The algorithm may introduces gaps in the histograms (steps in the CDF). This is to be expected because the histograms are being distorted. This is more prevalent for integer-level images. Histogram matching is not appropriate for images containing categorical (class) data. It is also not intended for images containing RGB data, in which case, the colour channels should be split using the SplitColourComposite tool.

See Also: HistogramMatching, HistogramEqualization, GaussianContrastStretch, SplitColourComposite

Parameters:

FlagDescription
--i1, --input1Input raster file to modify
--i2, --input2Input reference raster file
-o, --outputOutput raster file

Python function:

wbt.histogram_matching_two_images(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HistogramMatchingTwoImages -v ^
--wd="/path/to/data/" --i1=input1.tif --i2=input2.tif ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 31/08/2017

Last Modified: 13/10/2018

MinMaxContrastStretch

This tool performs a minimum-maximum contrast stretch on a raster image. This operation maps each grid cell value in the input raster image (z) onto a new scale that ranges from the user-specified lower-tail clip value (min_val) to the upper-tail clip value (max_val), with the specified number of tonal values (num_tones), such that:

zout = ((zin – min_val)/(max_val – min_val)) x num_tones

where zout is the output value. Notice that any values in the input image that are less than min_val are assigned a value of min_val in the output image. Similarly, any input values greater than max_val are assigned a value of max_val in the output image.

This is a type of linear contrast stretch with saturation at the tails of the frequency distribution. This is the same kind of stretch that is used to display raster type data on the fly in many GIS software packages, such that the lower and upper tail values are set using the minimum and maximum display values and the number of tonal values is determined by the number of palette entries.

See Also: PiecewiseContrastStretch, GaussianContrastStretch, HistogramEqualization, PercentageContrastStretch, SigmoidalContrastStretch, StandardDeviationContrastStretch

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--min_valLower tail clip value
--max_valUpper tail clip value
--num_tonesNumber of tones in the output image

Python function:

wbt.min_max_contrast_stretch(
    i, 
    output, 
    min_val, 
    max_val, 
    num_tones=256, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MinMaxContrastStretch -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif ^
--min_val=45.0 --max_val=200.0 --num_tones=1024 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/07/2017

Last Modified: 30/01/2020

PanchromaticSharpening

Panchromatic sharpening, or simply pan-sharpening, refers to a range of techniques that can be used to merge finer spatial resolution panchromatic images with coarser spatial resolution multi-spectral images. The multi-spectral data provides colour information while the panchromatic image provides improved spatial information. This procedure is sometimes called image fusion. Jensen (2015) describes panchromatic sharpening in detail.

Whitebox provides two common methods for panchromatic sharpening including the Brovey transformation and the Intensity-Hue-Saturation (IHS) methods. Both of these techniques provide the best results when the range of wavelengths detected by the panchromatic image overlap significantly with the wavelength range covered by the three multi-spectral bands that are used. When this is not the case, the resulting colour composite will likely have colour properties that are dissimilar to the colour composite generated by the original multispectral images. For Landsat ETM+ data, the panchromatic band is sensitive to EMR in the range of 0.52-0.90 micrometres. This corresponds closely to the green (band 2), red (band 3), and near-infrared (band 4).

Reference:

Jensen, J. R. (2015). Introductory Digital Image Processing: A Remote Sensing Perspective.

See Also: CreateColourComposite

Parameters:

FlagDescription
--redInput red band image file. Optionally specified if colour-composite not specified
--greenInput green band image file. Optionally specified if colour-composite not specified
--blueInput blue band image file. Optionally specified if colour-composite not specified
--compositeInput colour-composite image file. Only used if individual bands are not specified
--panInput panchromatic band file
-o, --outputOutput colour composite file
--methodOptions include 'brovey' (default) and 'ihs'

Python function:

wbt.panchromatic_sharpening(
    pan, 
    output, 
    red=None, 
    green=None, 
    blue=None, 
    composite=None, 
    method="brovey", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PanchromaticSharpening -v ^
--wd="/path/to/data/" --red=red.tif --green=green.tif ^
--blue=blue.tif --pan=pan.tif --output=pan_sharp.tif ^
--method='brovey'
>>./whitebox_tools -r=PanchromaticSharpening ^
-v --wd="/path/to/data/" --composite=image.tif --pan=pan.tif ^
--output=pan_sharp.tif --method='ihs' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/07/2017

Last Modified: 11/02/2019

PercentageContrastStretch

This tool performs a percentage contrast stretch on a raster image. This operation maps each grid cell value in the input raster image (zin) onto a new scale that ranges from a lower-tail clip value (min_val) to the upper-tail clip value (max_val), with the user-specified number of tonal values (num_tones), such that:

zout = ((zin – min_val)/(max_val – min_val)) x num_tones

where zout is the output value. The values of min_val and max_val are determined from the frequency distribution and the user-specified tail clip value (--clip). For example, if a value of 1% is specified, the tool will determine the values in the input image for which 1% of the grid cells have a lower value min_val and 1% of the grid cells have a higher value max_val. The user must also specify which tails (upper, lower, or both) to clip (--tail).

This is a type of linear contrast stretch with saturation at the tails of the frequency distribution. This is the same kind of stretch that is used to display raster type data on the fly in many GIS software packages, such that the lower and upper tail values are set using the minimum and maximum display values and the number of tonal values is determined by the number of palette entries.

See Also: PiecewiseContrastStretch, GaussianContrastStretch, HistogramEqualization, MinMaxContrastStretch, SigmoidalContrastStretch, StandardDeviationContrastStretch

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--clipOptional amount to clip the distribution tails by, in percent
--tailSpecified which tails to clip; options include 'upper', 'lower', and 'both' (default is 'both')
--num_tonesNumber of tones in the output image

Python function:

wbt.percentage_contrast_stretch(
    i, 
    output, 
    clip=1.0, 
    tail="both", 
    num_tones=256, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PercentageContrastStretch -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --clip=2.0 ^
--tail='both' --num_tones=1024 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/07/2017

Last Modified: 30/01/2020

PiecewiseContrastStretch

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

This tool can be used to perform a piecewise contrast stretch on an input image (--input). The input image can be either a single-band image or a colour composite, in which case the contrast stretch will be performed on the intensity values of the hue-saturation-intensity (HSI) transform of the colour image. The user must also specify the name of the output image (--output) and the break-points that define the piecewise function used to transfer brightness values from the input to the output image. The break-point values are specified as a string parameter (--function), with each break-point taking the form of (input value, output proportion); (input value, output proportion); (input value, output proportion), etc. Piecewise functions can have as many break-points as desired, and each break-point should be separated by a semicolon (;). The input values are specifies as brightness values in the same units as the input image (unless it is an input colour composite, in which case the intensity values range from 0 to 1). The output function must be specified as a proportion (from 0 to 1) of the output value range, which is specified by the number of output greytones (--greytones). The greytones parameter is ignored if the input image is a colour composite. Note that there is no need to specify the initial break-point to the piecewise function, as (input min value; 0.0) will be inserted automatically. Similarly, an upper bound of the piecewise function of (input max value; 1.0) will also be inserted automatically.

Generally you want to set breakpoints by examining the image histogram. Typically it is desirable to map large unpopulated ranges of input brightness values in the input image onto relatively narrow ranges of the output brightness values (i.e. a shallow sloped segment of the piecewise function), and areas of the histogram that are well populated with pixels in the input image with a larger range of brightness values in the output image (i.e. a steeper slope segment). This will have the effect of reducing the number of tones used to display the under-populated tails of the distribution and spreading out the well-populated regions of the histogram, thereby improving the overall contrast and the visual interpretability of the output image. The flexibility of the piecewise contrast stretch can often provide a very suitable means of significantly improving image quality.

See Also: RasterHistogram, GaussianContrastStretch, MinMaxContrastStretch, StandardDeviationContrastStretch

Parameters:

FlagDescription
-i, --inputName of the input raster image file
-o, --outputName of the output raster image file
-f, --functionPiecewise function break-points e.g. '(50, 0.1); (150, 0.8); (255; 1.0)
-g, --greytonesNumber of greytones in the output image

Python function:

wbt.piecewise_contrast_stretch(
    i, 
    output, 
    function="", 
    greytones=1024, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=PiecewiseContrastStretch -i=input.tif ^
-o=output.tif --function="x += 5000.0" --greytones=255 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 17/02/2022

Last Modified: 17/02/2022

SigmoidalContrastStretch

This tool performs a sigmoidal stretch on a raster image. This is a transformation where the input image value for a grid cell (zin) is transformed to an output value zout such that:

zout = (1.0 / (1.0 + exp(gain(cutoff - z))) - a ) / b x num_tones

where,

z = (zin - MIN) / RANGE,

a = 1.0 / (1.0 + exp(gain x cutoff)),

b = 1.0 / (1.0 + exp(gain x (cutoff - 1.0))) - 1.0 / (1.0 + exp(gain x cutoff)),

MIN and RANGE are the minimum value and data range in the input image respectively and gain and cutoff are user specified parameters (--gain, --cutoff).

Like all of WhiteboxTools's contrast enhancement tools, this operation will work on either greyscale or RGB input images.

See Also: PiecewiseContrastStretch, GaussianContrastStretch, HistogramEqualization, MinMaxContrastStretch, PercentageContrastStretch, StandardDeviationContrastStretch

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--cutoffCutoff value between 0.0 and 0.95
--gainGain value
--num_tonesNumber of tones in the output image

Python function:

wbt.sigmoidal_contrast_stretch(
    i, 
    output, 
    cutoff=0.0, 
    gain=1.0, 
    num_tones=256, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SigmoidalContrastStretch -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --cutoff=0.1 ^
--gain=2.0 --num_tones=1024 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/07/2017

Last Modified: 30/01/2020

StandardDeviationContrastStretch

This tool performs a standard deviation contrast stretch on a raster image. This operation maps each grid cell value in the input raster image (zin) onto a new scale that ranges from a lower-tail clip value (min_val) to the upper-tail clip value (max_val), with the user-specified number of tonal values (num_tones), such that:

zout = ((zin – min_val)/(max_val – min_val)) x num_tones

where zout is the output value. The values of min_val and max_val are determined based on the image mean and standard deviation. Specifically, the user must specify the number of standard deviations (--clip or --stdev) to be used in determining the min and max clip values. The tool will then calculate the input image mean and standard deviation and estimate the clip values from these statistics.

This is the same kind of stretch that is used to display raster type data on the fly in many GIS software packages.

See Also: PiecewiseContrastStretch, GaussianContrastStretch, HistogramEqualization, MinMaxContrastStretch, PercentageContrastStretch, SigmoidalContrastStretch

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--clip, --stdevStandard deviation clip value
--num_tonesNumber of tones in the output image

Python function:

wbt.standard_deviation_contrast_stretch(
    i, 
    output, 
    stdev=2.0, 
    num_tones=256, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=StandardDeviationContrastStretch -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --stdev=2.0 ^
--num_tones=1024 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/07/2017

Last Modified: 30/01/2020

LiDAR Tools

AsciiToLas

This tool can be used to convert one or more ASCII files, containing LiDAR point data, into LAS files. The user must specify the name(s) of the input ASCII file(s) (--inputs). Each input file will have a correspondingly named output file with a .las file extension. The output point data, each on a separate line, will take the format:

x,y,z,intensity,class,return,num_returns"
ValueInterpretation
xx-coordinate
yy-coordinate
zelevation
iintensity value
cclassification
rnreturn number
nrnumber of returns
timeGPS time
sascan angle
rred
bblue
ggreen

The x, y, and z patterns must always be specified. If the rn pattern is used, the nr pattern must also be specified. Examples of valid pattern string include:

'x,y,z,i'
'x,y,z,i,rn,nr'
'x,y,z,i,c,rn,nr,sa'
'z,x,y,rn,nr'
'x,y,z,i,rn,nr,r,g,b'

Use the LasToAscii tool to convert a LAS file into a text file containing LiDAR point data.

See Also: LasToAscii

Parameters:

FlagDescription
-i, --inputsInput LiDAR ASCII files (.csv)
--patternInput field pattern
--projWell-known-text string or EPSG code describing projection

Python function:

wbt.ascii_to_las(
    inputs, 
    pattern, 
    proj=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AsciiToLas -v --wd="/path/to/data/" ^
-i="file1.las, file2.las, file3.las" -o=outfile.las" ^
--proj=2150 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/02/2019

Last Modified: 18/01/2020

ClassifyBuildingsInLidar

This tool can be used to assign the building class (classification value 6) to all points within an input LiDAR point cloud (--input) that are contained within the polygons of an input buildings footprint vector (--buildings). The tool performs a simple point-in-polygon operation to determine membership. The two inputs (i.e. the LAS file and vector) must share the same map projection. Furthermore, any error in the definition of the building footprints will result in misclassified points in the output LAS file (--output). In particular, if the footprints extend slightly beyond the actual building, ground points situated adjacent to the building will be incorrectly classified. Thus, care must be taken in digitizing building footprint polygons. Furthermore, where there are tall trees that overlap significantly with the building footprint, these vegetation points will also be incorrectly assigned the building class value.

See Also: FilterLidarClasses, LidarGroundPointFilter, ClipLidarToPolygon

Parameters:

FlagDescription
-i, --inputInput LiDAR file
--buildingsInput vector polygons file
-o, --outputOutput LiDAR file

Python function:

wbt.classify_buildings_in_lidar(
    i, 
    buildings, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ClassifyBuildingsInLidar -v ^
--wd="/path/to/data/" -i='data.las' --polygons='lakes.shp' ^
-o='output.las' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 17/11/2019

Last Modified: 17/11/2019

ClassifyLidar

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

This tool provides a basic classification of a LiDAR point cloud into ground, building, and vegetation classes. The algorithm performs the classification based on point neighbourhood geometric properties, including planarity, linearity, and height above the ground. There is also a point segmentation involved in the classification process.

The user may specify the names of the input and output LiDAR files (--input and --output). Note that if the user does not specify the optional input/output LiDAR files, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be useful for processing a large number of LiDAR files in batch mode. When this batch mode is applied, the output file names will be the same as the input file names but with a '_classified' suffix added to the end.

The search distance (--radius), defining the radius of the neighbourhood window surrounding each point, must also be specified. If this parameter is set to a value that is too large, areas of high surface curvature on the ground surface will be left unclassed and smaller buildings, e.g. sheds, will not be identified. If the parameter is set too small, areas of low point density may provide unsatisfactory classification values. The larger this search distance is, the longer the algorithm will take to processs a data set. For many airborne LiDAR data sets, a value between 1.0 - 3.0 meters is likely appropriate.

The ground threshold parameter (--grd_threshold) determines how far above the tophat-transformed surface a point must be to be excluded from the ground surface. This parameter also determines the maximum distance a point can be from a plane or line model fit to a neighbourhood of points to be considered part of the model geometry. Similarly the off-terrain object threshold parameter (--oto_threshold) is used to determine how high above the ground surface a point must be to be considered either a vegetation or building point. The ground threshold must be smaller than the off-terrain object threshold. If you find that breaks-in-slope in areas of more complex ground topography are left unclassed (class = 1), this can be addressed by raising the ground threshold parameter.

The planarity and linearity thresholds (--planarity_threshold and --linearity_threshold) describe the minimum proportion (0-1) of neighbouring points that must be part of a fitted model before the point is considered to be planar or linear. Both of these properties are used by the algorithm in a variety of ways to determine final class values. Planar and linear models are fit using a RANSAC-like algorithm, with the main user-specified parameter of the number of iterations (--iterations). The larger the number of iterations the greater the processing time will be.

The facade threshold (--facade_threshold) is the last user-specified parameter, and determines the maximum horizontal distance that a point beneath a rooftop edge point may be to be considered part of the building facade (i.e. walls). The default value is 0.5 m, although this value will depend on a number of factors, such as whether or not the building has balconies.

The algorithm generally does very well to identify deciduous (broad-leaf) trees but can at times struggle with incorrectly classifying dense coniferous (needle-leaf) trees as buildings. When this is the case, you may counter this tendency by lowering the planarity threshold parameter value. Similarly, the algorithm will generally leave overhead power lines as unclassified (class = 1), howevever, if you find that the algorithm misclassifies most such points as high vegetation (class = 5), this can be countered by lowering the linearity threshold value.

Note that if the input file already contains class data, these data will be overwritten in the output file.

See Also: ColourizeBasedOnClass, FilterLidar, ModifyLidar, SortLidar, SplitLidar

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output LiDAR points
--radiusSearch distance used in neighbourhood search (metres)
--grd_thresholdGround threshold (metres)
--oto_thresholdOff-terrain object threshold (metres)
--planarity_thresholdPlanarity threshold (0-1)
--linearity_thresholdLinearity threshold (0-1)
--iterationsNumber of iterations
--facade_thresholdFacade threshold (metres)

Python function:

wbt.classify_lidar(
    i=None, 
    output=None, 
    radius=1.5, 
    grd_threshold=0.1, 
    oto_threshold=2.0, 
    planarity_threshold=0.85, 
    linearity_threshold=0.70, 
    iterations=30, 
    facade_threshold=0.5, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ClassifyLidar -i=input.las ^
-o=output.las --radius=2.0 --grd_threshold=0.2 ^
--oto_threshold=1.0 --planarity_threshold=0.6 ^
--linearity_threshold=0.5 --iterations=50 ^
--facade_threshold=0.75 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 18/02/2022

Last Modified: 25/02/2022

ClassifyOverlapPoints

This tool can be used to flag points within an input LiDAR file (--input) that overlap with other nearby points from different flightlines, i.e. to identify overlap points. The flightline associated with a LiDAR point is assumed to be contained within the point's Point Source ID (PSID) property. If the PSID property is not set, or has been lost, users may with to apply the RecoverFlightlineInfo tool prior to running FlightlineOverlap.

Areas of multiple flightline overlap tend to have point densities that are far greater than areas of single flightlines. This can produce suboptimal results for applications that assume regular point distribution, e.g. in point classification operations.

The tool works by applying a square grid over the extent of the input LiDAR file. The grid cell size is determined by the user-defined --resolution parameter. Grid cells containing multiple PSIDs, i.e. with more than one flightline, are then identified. Overlap points within these grid cells can then be flagged on the basis of a user-defined --criterion. The flagging options include the following:

CriterionOverlap Point Definition
max scan angleAll points that share the PSID of the point with the maximum absolute scan angle
not min point source IDAll points with a different PSID to that of the point with the lowest PSID
not min timeAll points with a different PSID to that of the point with the minimum GPS time
multiple point source IDsAll points in grid cells with multiple PSIDs, i.e. all overlap points.

Note that the max scan angle criterion may not be appropriate when more than two flightlines overlap, since it will result in only flagging points from one of the multiple flightlines.

It is important to set the --resolution parameter appropriately, as setting this value too high will yield the filtering of points in non-overlap areas, and setting the resolution to low will result in fewer than expected points being flagged. An appropriate resolution size value may require experimentation, however a value that is 2-3 times the nominal point spacing has been previously recommended. The nominal point spacing can be determined using the LidarInfo tool.

By default, all flagged overlap points are reclassified in the output LiDAR file (--output) to class 12. Alternatively, if the user specifies the --filter parameter, then each overlap point will be excluded from the output file. Classified overlap points may also be filtered from LiDAR point clouds using the FilterLidar tool.

Note that this tool is intended to be applied to LiDAR tile data containing points that have been merged from multiple overlapping flightlines. It is commonly the case that airborne LiDAR data from each of the flightlines from a survey are merged and then tiled into 1 km2 tiles, which are the target dataset for this tool.

See Also: FlightlineOverlap, RecoverFlightlineInfo, FilterLidar, LidarInfo

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--resolutionThe size of the square area used to evaluate nearby points in the LiDAR data
-c, --criterionCriterion used to identify overlapping points; options are 'max scan angle', 'not min point source ID', 'not min time', 'multiple point source IDs'
--filterFilter out points from overlapping flightlines? If false, overlaps will simply be classified

Python function:

wbt.classify_overlap_points(
    i, 
    output, 
    resolution=2.0, 
    criterion="max scan angle", 
    filter=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ClassifyOverlapPoints -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.las ^
--resolution=2.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/04/2018

Last Modified: 24/03/2022

ClipLidarToPolygon

This tool can be used to isolate, or clip, all of the LiDAR points in a LAS file (--input) contained within one or more vector polygon features. The user must specify the name of the input clip file (--polygons), which must be a vector of a Polygon base shape type. The clip file may contain multiple polygon features and polygon hole parts will be respected during clipping, i.e. LiDAR points within polygon holes will be removed from the output LAS file.

Use the ErasePolygonFromLidar tool to perform the complementary operation of removing points from a LAS file that are contained within a set of polygons.

See Also: ErasePolygonFromLidar, FilterLidar, Clip, ClipRasterToPolygon

Parameters:

FlagDescription
-i, --inputInput LiDAR file
--polygonsInput vector polygons file
-o, --outputOutput LiDAR file

Python function:

wbt.clip_lidar_to_polygon(
    i, 
    polygons, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ClipLidarToPolygon -v ^
--wd="/path/to/data/" -i='data.las' --polygons='lakes.shp' ^
-o='output.las' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/04/2018

Last Modified: 26/07/2019

ColourizeBasedOnClass

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

This tools sets the RGB colour values of an input LiDAR point cloud (--input) based on the point classifications. Rendering a point cloud in this way can aid with the determination of point classification accuracy, by allowing you to determine if there are certain areas within a LiDAR tile, or certain classes, that are problematic during the point classification process.

By default, the tool renders buildings in red (see table below). However, the tool also provides the option to render each building in a unique colour (--use_unique_clrs_for_buildings), providing a visually stunning LiDAR-based map of built-up areas. When this option is selected, the user must also specify the --radius parameter, which determines the search distance used during the building segmentation operation. The --radius parameter is optional, and if unspecified (when the --use_unique_clrs_for_buildings flag is used), a value of 2.0 will be used.

The specific colours used to render each point class can optionally be set by the user with the --clr_str parameter. The value of this parameter may list specific class values (0-18) and corresponding colour values in either a red-green-blue (RGB) colour triplet form (i.e. (r, g, b)), or or a hex-colour, of either form #e6d6aa or 0xe6d6aa (note the # and 0x prefixes used to indicate hexadecimal numbers; also either lowercase or capital letter values are acceptable). The following is an example of the a valid --clr_str that sets the ground (class 2) and high vegetation (class 5) colours used for rendering:

2: (184, 167, 108); 5: #9ab86c

Notice that 1) each class is separated by a semicolon (';'), 2) class values and colour values are separated by colons (':'), and 3) either RGB and hex-colour forms are valid.

If a --clr_str parameter is not provided, the tool will use the default colours used for each class (see table below).

Class values are assumed to follow the class designations listed in the LAS specification:

Classification ValueMeaningDefault Colour
0Created never classified
1Unclassified
2Ground
3Low Vegetation
4Medium Vegetation
5High Vegetation
6Building
7Low Point (noise)
8Reserved
9Water
10Rail
11Road Surface
12Reserved
13Wire – Guard (Shield)
14Wire – Conductor (Phase)
15Transmission Tower
16Wire-structure Connector (e.g. Insulator)
17Bridge Deck
18High noise

The point RGB colour values can be blended with the intensity data to create a particularly effective visualization, further enhancing the visual interpretation of point return properties. The --intensity_blending parameter value, which must range from 0% (no intensity blending) to 100% (all intensity), is used to set the degree of intensity/RGB blending.

Because the output file contains RGB colour data, it is possible that it will be larger than the input file. If the input file does contain valid RGB data, the output will be similarly sized, but the input colour data will be replaced in the output file with the point-return colours.

The output file can be visualized using any point cloud renderer capable of displaying point RGB information. We recommend the plas.io LiDAR renderer but many similar open-source options exist.

See Also: ColourizeBasedOnPointReturns, LidarColourize

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output LiDAR points
--intensity_blendingIntensity blending amount (0-100%)
--clr_strColour values, e.g. 2: (184, 167, 108); 5: #9ab86c
--use_unique_clrs_for_buildingsUse unique colours for each building?
--radiusSearch distance used in neighbourhood search

Python function:

wbt.colourize_based_on_class(
    i=None, 
    output=None, 
    intensity_blending=50.0, 
    clr_str="", 
    use_unique_clrs_for_buildings=False, 
    radius="", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ColourizeBasedOnClass -i=input.las ^
-o=output.las --clr_str='2: (184, 167, 108); 5: (100, 255, 50)' ^
--use_unique_clrs_for_buildings --radius=2.5 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 09/04/2022

Last Modified: 10/04/2022

ColourizeBasedOnPointReturns

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

This tool sets the RGB colour values of a LiDAR point cloud (--input) based on the point returns. It specifically renders only-return, first-return, intermediate-return, and last-return points in different colours, storing these data in the RGB colour data of the output LiDAR file (--output). Colourizing the points in a LiDAR point cloud based on return properties can aid with the visual inspection of point distributions, and therefore, the quality assurance/quality control (QA/QC) of LiDAR data tiles. For example, this visualization process can help to determine if there are areas of vegetation where there is insufficient coverage of ground points, perhaps due to acquisition of the data during leaf-on conditions. There is often an assumption in LiDAR data processing that the ground surface can be modelled using a subset of the only-return and last-return points (beige and blue in the image below). However, under heavy forest cover, and in particular if the data were collected during leaf-on conditions or if there is significant coverage of conifer trees, the only-return and last-return points may be poor approximations of the ground surface. This tool can help to determine the extent to which this is the case for a particular data set.

The specific colours used to render each return type can be set by the user with the --only, --first, --intermediate, and --last parameters. Each parameter takes either a red-green-blue (RGB) colour triplet, of the form (r,g,b), or a hex-colour, of either form #e6d6aa or 0xe6d6aa (note the # and 0x prefixes used to indicate hexadecimal numbers; also either lowercase or capital letter values are acceptable).

The point RGB colour values can be blended with the intensity data to create a particularly effective visualization, further enhancing the visual interpretation of point return properties. The --intensity_blending parameter value, which must range from 0% (no intensity blending) to 100% (all intensity), is used to set the degree of intensity/RGB blending.

Because the output file contains RGB colour data, it is possible that it will be larger than the input file. If the input file does contain valid RGB data, the output will be similarly sized, but the input colour data will be replaced in the output file with the point-return colours.

The output file can be visualized using any point cloud renderer capable of displaying point RGB information. We recommend the plas.io LiDAR renderer but many similar open-source options exist.

This tool is a convenience function and can alternatively be achieved using the ModifyLidar tool with the statement:

rgb=if(is_only, (230,214,170), if(is_last, (0,0,255), if(is_first, (0,255,0), (255,0,255))))

The ColourizeBasedOnPointReturns tool is however significantly faster for this operation than the ModifyLidar tool because the expression above must be executed dynamically for each point.

See Also: ModifyLidar, LidarColourize

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output LiDAR points
--intensity_blendingIntensity blending amount (0-100%)
--onlyOnly return colour, e.g. (230,214,170), #e6d6aa, or 0xe6d6aa
--firstFirst return colour, e.g. (230,214,170), #e6d6aa, or 0xe6d6aa
--intermediateIntermediate return colour, e.g. (230,214,170), #e6d6aa, or 0xe6d6aa
--lastLast return colour, e.g. (230,214,170), #e6d6aa, or 0xe6d6aa

Python function:

wbt.colourize_based_on_point_returns(
    i=None, 
    output=None, 
    intensity_blending=50.0, 
    only="(230,214,170)", 
    first="(0,140,0)", 
    intermediate="(255,0,255)", 
    last="(0,0,255)", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ColourizeBasedOnPointReturns ^
-i=input.las -o=output.las 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 03/04/2022

Last Modified: 10/04/2022

ErasePolygonFromLidar

This tool can be used to remove, or erase, all of the LiDAR points in a LAS file (--input) contained within one or more vector polygon features. The user must specify the name of the input clip file (--polygons), which must be a vector of a Polygon base shape type. The clip file may contain multiple polygon features and polygon hole parts will be respected during clipping, i.e. LiDAR points within polygon holes will be remain in the output LAS file.

Use the ClipLidarToPolygon tool to perform the complementary operation of clipping (isolating) points from a LAS file that are contained within a set of polygons, while removing points that lie outside the input polygons.

See Also: ClipLidarToPolygon, FilterLidar, Clip, ClipRasterToPolygon

Parameters:

FlagDescription
-i, --inputInput LiDAR file
--polygonsInput vector polygons file
-o, --outputOutput LiDAR file

Python function:

wbt.erase_polygon_from_lidar(
    i, 
    polygons, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ErasePolygonFromLidar -v ^
--wd="/path/to/data/" -i='data.las' --polygons='lakes.shp' ^
-o='output.las' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/04/2018

Last Modified: 12/10/2018

FilterLidar

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

The FilterLidar tool is a very powerful tool for filtering points within a LiDAR point cloud based on point properties. Complex filter statements (--statement) can be used to include or exclude points in the output file (--output).

Note that if the user does not specify the optional input LiDAR file (--input), the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be useful for processing a large number of LiDAR files in batch mode. When this batch mode is applied, the output file names will be the same as the input file names but with a '_filtered' suffix added to the end.

Points are either included or excluded from the output file by creating conditional filter statements. Statements must be valid Rust syntax and evaluate to a Boolean. Any of the following variables are acceptable within the filter statement:

Variable NameDescription
xThe point x coordinate
yThe point y coordinate
zThe point z coordinate
intensityThe point intensity value
retThe point return number
nretThe point number of returns
is_onlyTrue if the point is an only return (i.e. ret == nret == 1), otherwise false
is_multipleTrue if the point is a multiple return (i.e. nret > 1), otherwise false
is_earlyTrue if the point is an early return (i.e. ret == 1), otherwise false
is_intermediateTrue if the point is an intermediate return (i.e. ret > 1 && ret < nret), otherwise false
is_lateTrue if the point is a late return (i.e. ret == nret), otherwise false
is_firstTrue if the point is a first return (i.e. ret == 1 && nret > 1), otherwise false
is_lastTrue if the point is a last return (i.e. ret == nret && nret > 1), otherwise false
classThe class value in numeric form, e.g. 0 = Never classified, 1 = Unclassified, 2 = Ground, etc.
is_noiseTrue if the point is classified noise (i.e. class == 7
is_syntheticTrue if the point is synthetic, otherwise false
is_keypointTrue if the point is a keypoint, otherwise false
is_withheldTrue if the point is withheld, otherwise false
is_overlapTrue if the point is an overlap point, otherwise false
scan_angleThe point scan angle
scan_directionTrue if the scanner is moving from the left towards the right, otherwise false
is_flightline_edgeTrue if the point is situated along the filightline edge, otherwise false
user_dataThe point user data
point_source_idThe point source ID
scanner_channelThe point scanner channel
timeThe point GPS time, if it exists, otherwise 0
redThe point red value, if it exists, otherwise 0
greenThe point green value, if it exists, otherwise 0
blueThe point blue value, if it exists, otherwise 0
nirThe point near infrared value, if it exists, otherwise 0
pt_numThe point number within the input file
n_ptsThe number of points within the file
min_xThe file minimum x value
mid_xThe file mid-point x value
max_xThe file maximum x value
min_yThe file minimum y value
mid_yThe file mid-point y value
max_yThe file maximum y value
min_zThe file minimum z value
mid_zThe file mid-point z value
max_zThe file maximum z value
dist_to_ptThe distance from the point to a specified xy or xyz point, e.g. dist_to_pt(562500, 4819500) or dist_to_pt(562500, 4819500, 320)
dist_to_lineThe distance from the point to the line passing through two xy points, e.g. dist_to_line(562600, 4819500, 562750, 4819750)
dist_to_line_segThe distance from the point to the line segment defined by two xy end-points, e.g. dist_to_line_seg(562600, 4819500, 562750, 4819750)
within_rect1 if the point falls within the bounds of a 2D or 3D rectangle, otherwise 0. Bounds are defined as within_rect(ULX, ULY, LRX, LRY) or within_rect(ULX, ULY, ULZ, LRX, LRY, LRZ)

In addition to the point properties defined above, if the user applies the LidarEigenvalueFeatures tool on the input LiDAR file, the FilterLidar tool will automatically read in the additional *.eigen file, which include the eigenvalue-based point neighbourhood measures, such as lambda1, lambda2, lambda3, linearity, planarity, sphericity, omnivariance, eigentropy, slope, and residual. See the LidarEigenvalueFeatures documentation for details on each of these metrics describing the structure and distribution of points within the neighbourhood surrounding each point in the LiDAR file.

Statements can be as simple or complex as desired. For example, to filter out all points that are classified noise (i.e. class numbers 7 or 18):

!is_noise

The following is a statement to retain only the late returns from the input file (i.e. both last and single returns):

ret == nret

Notice that equality uses the == symbol an inequality uses the != symbol. As an equivalent to the above statement, we could have used the is_late point property:

is_late

If we want to remove all points outside of a range of xy values:

x >= 562000 && x <= 562500 && y >= 4819000 && y <= 4819500

Notice how we can combine multiple constraints using the && (logical AND) and || (logical OR) operators. As an alternative to the above statement, we could have used the within_rect function:

within_rect(562000, 4819500, 562500, 4819000)

If we want instead to exclude all of the points within this defined region, rather than to retain them, we simply use the ! (logial NOT):

!(x >= 562000 && x <= 562500 && y >= 4819000 && y <= 4819500)

or, simply:

!within_rect(562000, 4819500, 562500, 4819000)

If we need to find all of the ground points within 150 m of (562000, 4819500), we could use:

class == 2 && dist_to_pt(562000, 4819500) <= 150.0

The following statement outputs all non-vegetation classed points in the upper-right quadrant:

!(class == 3 && class != 4 && class != 5) && x < min_x + (max_x - min_x) / 2.0 && y > max_y - (max_y - min_y) / 2.0

As demonstrated above, the FilterLidar tool provides an extremely flexible, powerful, and easy means for retaining and removing points from point clouds based on any of the common LiDAR point attributes.

See Also: FilterLidarClasses, FilterLidarScanAngles, ModifyLidar, ErasePolygonFromLidar, ClipLidarToPolygon, SortLidar, LidarEigenvalueFeatures

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output LiDAR points
-s, --statementFilter statement e.g. x < 5000.0 && y > 100.0 && is_late && !is_noise. This statement must be a valid Rust statement

Python function:

wbt.filter_lidar(
    i=None, 
    output=None, 
    statement="", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=FilterLidar -i=input.las -o=output.las ^
--statement="x<5000.0 && y>100.0" 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 05/02/2022

Last Modified: 05/02/2022

FilterLidarClasses

This tool can be used to remove points within a LAS LiDAR file that possess certain specified class values. The user must input the names of the input (--input) and output (--output) LAS files and the class values to be excluded (--exclude_cls). Class values are specified by their numerical values, such that:

Classification ValueMeaning
0Created never classified
1Unclassified
2Ground
3Low Vegetation
4Medium Vegetation
5High Vegetation
6Building
7Low Point (noise)
8Reserved
9Water
10Rail
11Road Surface
12Reserved
13Wire – Guard (Shield)
14Wire – Conductor (Phase)
15Transmission Tower
16Wire-structure Connector (e.g. Insulator)
17Bridge Deck
18High noise

Thus, to filter out low and high noise points from a point cloud, specify --exclude_cls='7,18'. Class ranges may also be specified, e.g. --exclude_cls='3-5,7,18'. Notice that usage of this tool assumes that the LAS file has underwent a comprehensive point classification, which not all point clouds have had. Use the LidarInfo tool determine the distribution of various class values in your file.

See Also: LidarInfo

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--exclude_clsOptional exclude classes from interpolation; Valid class values range from 0 to 18, based on LAS specifications. Example, --exclude_cls='3,4,5,6,7,18'

Python function:

wbt.filter_lidar_classes(
    i, 
    output, 
    exclude_cls=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FilterLidarClasses -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--exclude_cls='7,18' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/07/2019

Last Modified: 16/01/2020

FilterLidarScanAngles

Removes points in a LAS file with scan angles greater than a threshold.

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--thresholdScan angle threshold

Python function:

wbt.filter_lidar_scan_angles(
    i, 
    output, 
    threshold, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FilterLidarScanAngles -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--threshold=10.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: September 17, 2017

Last Modified: 12/10/2018

FindFlightlineEdgePoints

Identifies points along a flightline's edge in a LAS file.

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: June 14, 2017

Last Modified: 12/10/2018

FlightlineOverlap

This tool can be used to map areas of overlapping flightlines in an input LiDAR (LAS) file (--input). The output raster file (--output) will contain the number of different flightlines that are contained within each grid cell. The user must specify the desired cell size (--resolution). The flightline associated with a LiDAR point is assumed to be contained within the point's Point Source ID property. Thus, the tool essentially counts the number of different Point Source ID values among the points contained within each grid cell. If the Point Source ID property is not set, or has been lost, users may with to apply the RecoverFlightlineInfo tool prior to running FlightlineOverlap.

It is important to set the --resolution parameter appropriately, as setting this value too high will yield the mis-characterization of non-overlap areas, and setting the resolution to low will result in fewer than expected overlap areas. An appropriate resolution size value may require experimentation, however a value that is 2-3 times the nominal point spacing has been previously recommended. The nominal point spacing can be determined using the LidarInfo tool.

Note that this tool is intended to be applied to LiDAR tile data containing points that have been merged from multiple overlapping flightlines. It is commonly the case that airborne LiDAR data from each of the flightlines from a survey are merged and then tiled into 1 km2 tiles, which are the target dataset for this tool.

Like many of the LiDAR related tools, the input and output file parameters are optional. If left unspecified, the tool will locate all valid LiDAR files within the current Whitebox working directory and use these for calculation (specifying the output raster file name based on the associated input LiDAR file). This can be a helpful way to run the tool on a batch of user inputs within a specific directory.

See Also: ClassifyOverlapPoints, RecoverFlightlineInfo, LidarInfo

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput file
--resolutionOutput raster's grid resolution

Python function:

wbt.flightline_overlap(
    i=None, 
    output=None, 
    resolution=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FlightlineOverlap -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0"
./whitebox_tools -r=FlightlineOverlap -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=5.0 --palette=light_quant.plt 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/06/2017

Last Modified: 24/03/2022

HeightAboveGround

This tool normalizes an input LiDAR point cloud (--input) such that point z-values in the output LAS file (--output) are converted from elevations to heights above the ground, specifically the height above the nearest ground-classified point. The input LAS file must have ground-classified points, otherwise the tool will return an error. The LidarTophatTransform tool can be used to perform the normalization if a ground classification is lacking.

See Also: LidarTophatTransform

Parameters:

FlagDescription
-i, --inputInput LiDAR file (including extension)
-o, --outputOutput lidar file (including extension)

Python function:

wbt.height_above_ground(
    i=None, 
    output=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HeightAboveGround -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/11/2019

Last Modified: 15/12/2019

IndividualTreeDetection

This tool can be used to identify points in a LiDAR point cloud that are associated with the tops of individual trees. The tool takes a LiDAR point cloud as an input (input_lidar) and it is best if the input file has been normalized using the NormalizeLidar or LidarTophatTransform tools, such that points record height above the ground surface. Note that the input parameter is optional and if left unspecified the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This 'batch mode' operation is common among many of the LiDAR processing tools. Output vectors are saved to disc automatically for each processed LiDAR file when operating in batch mode.

The tool will evaluate the points within a local neighbourhood around each point in the input point cloud and determine if it is the highest point within the neighbourhood. If a point is the highest local point, it will be entered into the output vector file (output). The neighbourhood size can vary, with higher canopy positions generally associated with larger neighbourhoods. The user specifies the min_search_radius and min_height parameters, which default to 1 m and 0 m respectively. If the min_height parameter is greater than zero, all points that are less than this value above the ground (assuming the input point cloud measures this height parameter) are ignored, which can be a useful mechanism for removing shorter trees and other vegetation from the analysis. If the user specifies the max_search_radius and max_height parameters, the search radius will be determined by linearly interpolation based on point height and the min/max search radius and height parameter values. Points that are above the max_height parameter will be processed with search neighbourhoods sized max_search_radius. If the max radius and height parameters are unspecified, they are set to the same values as the minimum radius and height parameters, i.e., the neighbourhood size does not increase with canopy height.

If the point cloud contains point classifications, it may be useful to exclude all non-vegetation points. To do this simply set the only_use_veg parameter to True. This parameter should only be set to True when you know that the input file contains point classifications, otherwise the tool may generate an empty output vector file.

See Also: NormalizeLidar, LidarTophatTransform

Parameters:

FlagDescription
-i, --inputName of the input LiDAR file
-o, --outputName of the output vector points file
--min_search_radiusMinimum search radius (m)
--min_heightMinimum height (m)
--max_search_radiusMaximum search radius (m)
--max_heightMaximum height (m)
--only_use_vegOnly use veg. class points?

Python function:

wbt.individual_tree_detection(
    i=None, 
    output=None, 
    min_search_radius=1.0, 
    min_height=0.0, 
    max_search_radius="", 
    max_height="", 
    only_use_veg=False, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=IndividualTreeDetection -i=points.laz ^
-o=tree_tops.shp --min_search_radius=1.5 --min_height=2.0 ^
--max_search_radius=8.0 --max_height=30.0 --only_use_veg 

Source code is unavailable due to proprietary license.

Author: Dr. John Lindsay

Created: 05/03/2023

Last Modified: 05/03/2023

LasToAscii

This tool can be used to convert one or more LAS file, containing LiDAR data, into ASCII files. The user must specify the name(s) of the input LAS file(s) (--inputs). Each input file will have a correspondingly named output file with a .csv file extension. CSV files are comma separated value files and contain tabular data with each column corresponding to a field in the table and each row a point value. Fields are separated by commas in the ASCII formatted file. The output point data, each on a separate line, will take the format:

X,Y,Z,INTENSITY,CLASS,RETURN,NUM_RETURN,SCAN_ANGLE

If the LAS file has a point format that contains RGB data, the final three columns will contain the RED, GREEN, and BLUE values respectively. Use the AsciiToLas tool to convert a text file containing LiDAR point data into a LAS file.

See Also: AsciiToLas

Parameters:

FlagDescription
-i, --inputsInput LiDAR files

Python function:

wbt.las_to_ascii(
    inputs, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LasToAscii -v --wd="/path/to/data/" ^
-i="file1.las, file2.las, file3.las" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/07/2017

Last Modified: 29/02/2020

LasToLaz

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

This tool converts one or more LiDAR files in the uncompressed LAS format into a compressed LAZ file. Both the --input and --output parameters are optional. If these parameters are not specified by the user, the tool will search for all LAS files contained within the current WhiteboxTools working directory. This feature can be useful when you need to convert a large number of LAS files. This batch processing mode enables the tool to perform parallel data processing, which can significantly improve the efficiency of data conversion for datasets with many LiDAR tiles. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file with the same name as each input LiDAR file, but with the .laz extension.

The LAZ encoder/decoder that is used by the LasToLaz tool is not necessarily faster than other LAZ libraries, such as the common laszip LiDAR conversion utility program. While single-tile conversion performance is likely to be on par or slighly slower than laszip, the parallelization of the LazToLas tool when run in batch mode can result in significant performance gains in applications working on many individual LAS tiles. The following table shows a comparison of the performance of the LasToLaz tool with laszip (time laszip -i *.las) for a number of sample data sets. All tests were performed on a 2013 MacPro with an 8-core 3.0 GHz Intel Xeon processor with 64 GB memory. Files were written to an external hard drive, and times are inclusive of file I/O.

Dataset NameNum. TileslaszipLasToLaz
Guelph2011481.0s616.8s
Broughtons's Creek331139.3s48.6s
Big Otter Creek10895115.2s2689.7s
Ottawa 20156613308.3s1139.9s

See Also: LazToLas, LasToZlidar, ZlidarToLas, LasToAscii, LasToShapefile

Parameters:

FlagDescription
-i, --inputName of the input LAS files (leave blank to use all LAS files in WorkingDirectory
-o, --outputOutput LAZ file (including extension)

Python function:

wbt.las_to_laz(
    i=None, 
    output=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LazToLas -i=file.laz -o=outfile.las



Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 15/06/2021

Last Modified: 15/06/2021

LasToMultipointShapefile

Converts one or more LAS files into MultipointZ vector Shapefiles. When the input parameter is not specified, the tool grids all LAS files contained within the working directory.

This tool can be used in place of the LasToShapefile tool when the number of points are relatively high and when the desire is to represent the x,y,z position of points only. The z values of LAS points will be stored in the z-array of the output Shapefile. Notice that because the output file stores each point in a single multi-point record, this Shapefile representation, while unable to represent individual point classes, return numbers, etc, is an efficient means of converting LAS point positional information.

See Also: LasToShapefile

Parameters:

FlagDescription
-i, --inputInput LiDAR file

Python function:

wbt.las_to_multipoint_shapefile(
    i=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/09/2018

Last Modified: 19/05/2020

LasToShapefile

This tool converts one or more LAS files into a POINT vector. When the input parameter is not specified, the tool grids all LAS files contained within the working directory. The attribute table of the output Shapefile will contain fields for the z-value, intensity, point class, return number, and number of return.

This tool can be used in place of the LasToMultipointShapefile tool when the number of points are relatively low and when the desire is to represent more than simply the x,y,z position of points. Notice however that because each point in the input LAS file will be represented as a separate record in the output Shapefile, the output file will be many time larger than the equivalent output of the LasToMultipointShapefile tool. There is also a practical limit on the total number of records that can be held in a single Shapefile and large LAS files approach this limit. In these cases, the LasToMultipointShapefile tool should be preferred instead.

See Also: LasToMultipointShapefile

Parameters:

FlagDescription
-i, --inputInput LiDAR file

Python function:

wbt.las_to_shapefile(
    i=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/10/2018

Last Modified: 20/05/2020

LasToZlidar

This tool can be used to convert one or more LAS files into the zLidar compressed LiDAR data format. The tool takes a list of input LAS files (--inputs). If --inputs is unspecified, the tool will use all LAS files contained within the working directory as the tool inputs. The user may also specify an optional output directory --outdir. If this parameter is unspecified, each output zLidar file will be written to the same directory as the input files.

See Also: ZlidarToLas, LasToShapefile, LasToAscii

Parameters:

FlagDescription
-i, --inputsInput LAS files
--outdirOutput directory into which zlidar files are created. If unspecified, it is assumed to be the same as the inputs
--compressCompression method, including 'brotli' and 'deflate'
--levelCompression level (1-9)

Python function:

wbt.las_to_zlidar(
    inputs=None, 
    outdir=None, 
    compress="brotli", 
    level=5, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LasToZlidar -v --wd="/path/to/data/" ^
-i="file1.las, file2.las, file3.las" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/05/2020

Last Modified: 15/05/2020

LazToLas

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

This tool converts one or more LiDAR files in the compressed LAZ format into an uncompressed LAS file. Both the --input and --output parameters are optional. If these parameters are not specified by the user, the tool will search for all LAZ files contained within the current WhiteboxTools working directory. This feature can be useful when you need to convert a large number of LAZ files. This batch processing mode enables the tool to perform parallel data processing, which can significantly improve the efficiency of data conversion for datasets with many LiDAR tiles. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file with the same name as each input LiDAR file, but with the .las extension.

The LAZ encoder/decoder that is used by the LazToLas tool is not necessarily faster than other LAZ libraries, such as the common laszip LiDAR conversion utility program. While single-tile conversion performance is likely to be on par or slighly slower than laszip, the parallelization of the LazToLas tool when run in batch mode can result in significant performance gains in applications working on many individual LAZ tiles. The following table shows a comparison of the performance of the LazToLas tool with laszip (time laszip -i *.laz) for a number of sample data sets. All tests were performed on a 2013 MacPro with an 8-core 3.0 GHz Intel Xeon processor with 64 GB memory. Files were written to an external hard drive, and times are inclusive of file I/O.

Dataset NameNum. TileslaszipLazToLas
Guelph2013062.3s525.9s
Broughtons's Creek331261.4s53.2s
Big Otter Creek10897200.2s1923.9s
Ottawa 20156616950.6s1130.5s

See Also: LasToLaz, LasToZlidar, ZlidarToLas, LasToAscii, LasToShapefile

Parameters:

FlagDescription
-i, --inputName of the input LAZ files (leave blank to use all LAZ files in WorkingDirectory
-o, --outputOutput LAS file (including extension)

Python function:

wbt.laz_to_las(
    i=None, 
    output=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LazToLas -i=file.laz -o=outfile.las



Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 15/06/2021

Last Modified: 15/06/2021

LidarBlockMaximum

Creates a block-maximum raster from an input LAS file. When the input/output parameters are not specified, the tool grids all LAS files contained within the working directory.

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput file
--resolutionOutput raster's grid resolution

Python function:

wbt.lidar_block_maximum(
    i=None, 
    output=None, 
    resolution=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarBlockMaximum -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0"
./whitebox_tools -r=LidarBlockMaximum -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=5.0 --palette=light_quant.plt 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/07/2017

Last Modified: 19/05/2020

LidarBlockMinimum

Creates a block-minimum raster from an input LAS file. When the input/output parameters are not specified, the tool grids all LAS files contained within the working directory.

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput file
--resolutionOutput raster's grid resolution

Python function:

wbt.lidar_block_minimum(
    i=None, 
    output=None, 
    resolution=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarBlockMinimum -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0"
./whitebox_tools -r=LidarBlockMinimum -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=5.0 --palette=light_quant.plt 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/07/2017

Last Modified: 19/05/2020

LidarClassifySubset

This tool classifies points within a user-specified LiDAR point cloud (--base) that correspond with points in a subset cloud (--subset). The subset point cloud may have been derived by filtering the original point cloud. The user must specify the names of the two input LAS files (i.e. the full and subset clouds) and the class value (--subset_class) to assign the matching points. This class value will be assigned to points in the base cloud, overwriting their input class values in the output LAS file (--output). Class values should be numerical (integer valued) and should follow the LAS specifications below:

Classification ValueMeaning
0Created never classified
1Unclassified
2Ground
3Low Vegetation
4Medium Vegetation
5High Vegetation
6Building
7Low Point (noise)
8Reserved
9Water
10Rail
11Road Surface
12Reserved
13Wire – Guard (Shield)
14Wire – Conductor (Phase)
15Transmission Tower
16Wire-structure Connector (e.g. Insulator)
17Bridge Deck
18High noise

The user may optionally specify a class value to be assigned to non-subset (i.e. non-matching) points (--nonsubset_class) in the base file. If this parameter is not specified, output non-sutset points will have the same class value as the base file.

Parameters:

FlagDescription
--baseInput base LiDAR file
--subsetInput subset LiDAR file
-o, --outputOutput LiDAR file
--subset_classSubset point class value (must be 0-18; see LAS specifications)
--nonsubset_classNon-subset point class value (must be 0-18; see LAS specifications)

Python function:

wbt.lidar_classify_subset(
    base, 
    subset, 
    output, 
    subset_class, 
    nonsubset_class=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarClassifySubset -v ^
--wd="/path/to/data/" --base="full_cloud.las" ^
--subset="filtered_cloud.las" -o="output.las" ^
--subset_class=2 

Source code on GitHub

Author: Dr. John Lindsay and Kevin Roberts

Created: 24/10/2018

Last Modified: 24/10/2018

LidarColourize

This tool can be used to add red-green-blue (RGB) colour values to the points contained within an input LAS file (--in_lidar), based on the pixel values of an overlapping input colour image (--in_image). Ideally, the image has been acquired at the same time as the LiDAR point cloud. If this is not the case, one may expect that transient objects (e.g. cars) in both input data sets will be incorrectly coloured. The input image should overlap in extent with the LiDAR data set and the two data sets should share the same projection. You may use the LidarTileFootprint tool to determine the spatial extent of the LAS file.

See Also: ColourizeBasedOnClass, ColourizeBasedOnPointReturns, LidarTileFootprint

Parameters:

FlagDescription
--in_lidarInput LiDAR file
--in_imageInput colour image file
-o, --outputOutput LiDAR file

Python function:

wbt.lidar_colourize(
    in_lidar, 
    in_image, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarColourize -v --wd="/path/to/data/" ^
--in_lidar="input.las" --in_image="image.tif" ^
-o="output.las" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/02/2018

Last Modified: 12/10/2018

LidarContour

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

This tool can be used to create a contour (i.e. isolines of elevation values) vector coverage from an input LiDAR points data set (--input). The tool works by first creating a triangulation of the input LiDAR points. The user must specify the contour interval (--interval), or vertical spacing between contour lines. The --smooth parameter can be used to increase or decrease the degree to which contours are smoothed. This parameter should be an odd integer value (0, 1, 3, 5...), with 0 indicating no smoothing. The tool can interpolate contours based on the LiDAR point elevation values, intensity data, or the user data field (--parameter), with 'elevation' as the default parameter. LiDAR points may be excluded from the contouring process based on a number of criteria, including their return value (--returns, which may be 'all', 'last', 'first'), their class value (--exclude_cls), and whether they fall outside of a user-specified elevation range (--minz and --maxz). The optional --max_triangle_edge_length parameter can be used to exclude the output of contours within areas that are sparsely populated areas of the data set, where the triangles formed by the Delaunay triangulation are too large. This is often the case within bodies of water; long and narrow triangular facets can also occur within the concave portions of the hull, or polygon enclosing, the points, when the data have an irregular shaped extent. Setting this parameter can help alleviate the problem of contouring beyond the data footprint.

Like many of the LiDAR tools, both the --input and --output parameters are optional. If these parameters are not specified by the user, the tool will search for all LAS files contained within the current WhiteboxTools working directory. This feature can be useful when you need to contour a large number of LiDAR tiles. This batch processing mode enables the tool to enable parallel data processing, which can significantly improve the efficiency of data conversion for datasets with many LiDAR tiles. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file with the same name as each input LiDAR file, but with the .shp extension.

It is important to note that contouring is better suited to well-defined surfaces (e.g. the ground surface or building heights), rather than volume features, such as vegetation, which tend to produce extremely complex contour sets. It is advisable to use this tool with last-returns and/or ground-classified point returns. If the input data set does not contain ground classification, consider pre-processing with the LidarGroundPointFilter tool.

See Also: ContoursFromPoints, ContoursFromRaster, LidarGroundPointFilter

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output vector lines file
--intervalContour interval
--baseBase contour
--smoothSmoothing filter size (in num. points), e.g. 3, 5, 7, 9, 11
-p, --parameterInterpolation parameter; options are 'elevation' (default), 'intensity', 'user_data'
--returnsPoint return types to include; options are 'all' (default), 'last', 'first'
--exclude_clsOptional exclude classes from interpolation; Valid class values range from 0 to 18, based on LAS specifications. Example, --exclude_cls='3,4,5,6,7,18'
--minzOptional minimum elevation for inclusion in interpolation
--maxzOptional maximum elevation for inclusion in interpolation
--max_triangle_edge_lengthOptional maximum triangle edge length; triangles larger than this size will not be gridded

Python function:

wbt.lidar_contour(
    i=None, 
    output=None, 
    interval=10.0, 
    base=0.0, 
    smooth=5, 
    parameter="elevation", 
    returns="all", 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    max_triangle_edge_length=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LidarContour -i=input.las ^
-o=output.las --interval=5.0 --parameter=elevation ^
--returns=last --smooth=9 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 21/06/2021

Last Modified: 21/06/2021

LidarDigitalSurfaceModel

This tool creates a digital surface model (DSM) from a LiDAR point cloud. A DSM reflects the elevation of the tops of all off-terrain objects (i.e. non-ground features) contained within the data set. For example, a DSM will model the canopy top as well as building roofs. This is in stark contrast to a bare-earth digital elevation model (DEM), which models the ground surface without off-terrain objects present. Bare-earth DEMs can be derived from LiDAR data by interpolating last-return points using one of the other LiDAR interpolators (e.g. LidarTINGridding). The algorithm used for interpolation in this tool is based on gridding a triangulation (TIN) fit to top-level points in the input LiDAR point cloud. All points in the input LiDAR data set that are below other neighbouring points, within a specified search radius (--radius), and that have a large inter-point slope, are filtered out. Thus, this tool will remove the ground surface beneath as well as any intermediate points within a forest canopy, leaving only the canopy top surface to be interpolated. Similarly, building wall points and any ground points beneath roof overhangs will also be remove prior to interpolation. Note that because the ground points beneath overhead wires and utility lines are filtered out by this operation, these features tend to be appear as 'walls' in the output DSM. If these points are classified in the input LiDAR file, you may wish to filter them out before using this tool (FilterLidarClasses).

The following images show the differences between creating a DSM using the LidarDigitalSurfaceModel and by interpolating first-return points only using the LidarTINGridding tool respectively. Note, the images show TimeInDaylight, which is a more effective way of hillshading DSMs than the traditional Hillshade method. Compare how the DSM created LidarDigitalSurfaceModel tool (above) has far less variability in areas of tree-cover, more effectively capturing the canopy top. As well, notice how building rooftops are more extensive and straighter in the LidarDigitalSurfaceModel DSM image. This is because this method eliminates ground returns beneath roof overhangs before the triangulation operation.

The user must specify the grid resolution of the output raster (--resolution), and optionally, the name of the input LiDAR file (--input) and output raster (--output). Note that if an input LiDAR file (--input) is not specified by the user, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be very useful when you need to interpolate a DSM for a large number of LiDAR files. Not only does this batch processing mode enable the tool to run in a more optimized parallel manner, but it will also allow the tool to include a small buffer of points extending into adjacent tiles when interpolating an individual file. This can significantly reduce edge-effects when the output tiles are later mosaicked together. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file with the same name as each input LiDAR file, but with the .tif extension. This can provide a very efficient means for processing extremely large LiDAR data sets.

Users may also exclude points from the interpolation if they fall below or above the minimum (--minz) or maximum (--maxz) thresholds respectively. This can be a useful means of excluding anomalously high or low points. Note that points that are classified as low points (LAS class 7) or high noise (LAS class 18) are automatically excluded from the interpolation operation.

Triangulation will generally completely fill the convex hull containing the input point data. This can sometimes result in very long and narrow triangles at the edges of the data or connecting vertices on either side of void areas. In LiDAR data, these void areas are often associated with larger waterbodies, and triangulation can result in very unnatural interpolated patterns within these areas. To avoid this problem, the user may specify a the maximum allowable triangle edge length (max_triangle_edge_length) and all grid cells within triangular facets with edges larger than this threshold are simply assigned the NoData values in the output DSM. These NoData areas can later be better dealt with using the FillMissingData tool after interpolation.

See Also: LidarTINGridding, FilterLidarClasses, FillMissingData, TimeInDaylight

Parameters:

FlagDescription
-i, --inputInput LiDAR file (including extension)
-o, --outputOutput raster file (including extension)
--resolutionOutput raster's grid resolution
--radiusSearch Radius
--minzOptional minimum elevation for inclusion in interpolation
--maxzOptional maximum elevation for inclusion in interpolation
--max_triangle_edge_lengthOptional maximum triangle edge length; triangles larger than this size will not be gridded

Python function:

wbt.lidar_digital_surface_model(
    i=None, 
    output=None, 
    resolution=1.0, 
    radius=0.5, 
    minz=None, 
    maxz=None, 
    max_triangle_edge_length=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarDigitalSurfaceModel -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--returns=last --resolution=2.0 --exclude_cls='3,4,5,6,7,18' ^
--max_triangle_edge_length=5.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/08/2020

Last Modified: 16/08/2020

LidarEigenvalueFeatures

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

This tool can be used to measure eigenvalue-based features that describe the characteristics of the local neighbourhood surrounding each point in an input LiDAR file (--input). These features can then be used in point classification applications, or as the basis for point filtering (FilterLidar) or modifying point properties (ModifyLidar).

The algorithm begins by using the x, y, z coordinates of the points within a local spherical neighbourhood to calculate a covariance matrix. The three eigenvalues λ1, λ2, λ3 are then derived from the covariance matrix decomposition such that λ1 > λ2 > λ3. The eigenvalues are then used to describe the extent to which the neighbouring points can be characterized by a linear, planar, or volumetric distribution, by calculating the following three features:

linearity = (λ1 - λ2) / λ1

planarity = (λ2 - λ3) / λ1

sphericity = λ3 / λ1

In the case of a neighbourhood containing a 1-dimensional line, the first of the three components will possess most of data variance, with very little contained within λ2 and λ3, and linearity will be nearly equal to 1.0. If the local neighbourhood contains a 2-dimensional plane, the first two components will possess most of the variance, with little variance within λ3, and planarity will be nearly equal to 1.0. Lastly, in the case of a 3-dimensional, random volumetric point distribution, each of the three components will be nearly equal in magnitude and sphericity will be nearly equal to 1.0.

Researchers in the field of LiDAR point classification also frequently define two additional eigenvalue-based features, the omnivariance (low values correspond to planar and linear regions and higher values occur for areas with a volumetric point distribution, such as vegetation), and the eigentropy, which is related to the Shannon entropy and is a measure of the unpredictability of the distribution of points in the neighbourhood:

omnivariance = (λ1 ⋅ λ2 ⋅ λ3)1/3

eigentropy = -e1 ⋅ lne1 - e2 ⋅ lne2 - e3 ⋅ lne3

where e1, e2, and e3 are the normalized eigenvalues.

In addition to the eigenvalues, the eigendecomposition of the symmetric covariance matrix also yields the three eigenvectors, which describe the transformation coefficients of the principal components. The first two eigenvectors represent the basis of the plane resulting from the orthogonal regression analysis, while the third eigenvector represents the plane normal. From this normal, it is possible to calculate the slope of the plane, as well as the orthogonal distance between each point and the neighbourhood fitted plane, i.e. the point residual.

This tool outputs a binary file (*.eigen; --output) that contains a total of 10 features for each point in the input file, including the point_num (for reference), lambda1, lambda2, lambda3, linearity, planarity, sphericity, omnivariance, eigentropy, slope, and residual. Users should bear in mind that most of these features describe the properties of the distribution of points within a spherical neighbourhood surrounding each point in the input file, rather than a characteristic of the point itself. The only one of the ten features that is a point property is the residual. Points for which the planarity value is high and the residual value is low may be assumed to be part of the plane that dominate the structure of their neighbourhoods. In addition to the binary data *.eigen file, the tool will also output a sidecar file, with a *.eigen.json extension, which describes the structure of the raw binary data file.

Local neighbourhoods are spherical in shape and the size of each neighbourhood is characterized by the --num_neighbours and --radius parameters. If the optional --num_neighbours parameter is specified, the size of the neighbourhood will vary by point, increasing or decreasing to encompass the specified number of neighbours (notice that this value does not include the point itself). If the optional --radius parameter is specified in addition to a number of neighbours, the specified radius value will serve as a upper-bound and neighbouring points that are beyond this radial distance to the centre point will be excluded. If a radius search distance is specified but the --num_neighbours parameter is not, then a constant search distance will be used for each point in the input file, resulting in varying number of points within local neighbourhoods, depending on local point densities. If point density varies significantly in the input file, then use of the --num_neighbours parameter may be advisable. Notice that at least one of the two parameters must be specified. In cases where the number of neighbouring points is fewer than eight, each of the output feature values will be set to 0.0.

Note that if the user does not specify the optional input LiDAR file, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be useful for processing a large number of LiDAR files in batch mode.

The binary data file (*.eigen) can be used directly by the FilterLidar and ModifyLidar tools, and will be automatically read by the tools when the *.eigen and *.eigen.json files are present in the same folder as the accompanying source LiDAR file. This allows users to apply data filters, or to modify point properties, using these point neighbourhood features. For example, the statement, rgb=(int(linearity*255), int(planarity*255), int(sphericity*255)), used with the ModifyLidar tool, can render the point RGB colour values based on some of the eigenvalue features, allowing users to visually identify linear features (red), planar features (green), and volumetric regions (blue).

Additionally, these features data can also be readily incorporated into a Python-based point analysis or classification. As an example, the following script reads in a *.eigen binary data file for direct manipulation and analysis:

import numpy as np

dt = np.dtype([
('point_num', '<u8'),
('lambda1', '<f4'),
('lambda2', '<f4'),
('lambda3', '<f4'),
('linearity', '<f4'),
('planarity', '<f4'),
('sphericity', '<f4'),
('omnivariance', '<f4'),
('eigentropy', '<f4'),
('slope', '<f4'),
('resid', '<f4')
])

with open('/Users/johnlindsay/Documents/data/aaa2.eigen', 'rb') as f:
b = f.read()

pt_features = np.frombuffer(b, dt)

# Print the first 100 point features to demonstrate
for i in range(100):
print(f"{pt_features['point_num'][i]} {pt_features['linearity'][i]} {pt_features['planarity'][i]} {pt_features['sphericity'][i]}")


print("Done!")

References:

Chehata, N., Guo, L., & Mallet, C. (2009). Airborne lidar feature selection for urban classification using random forests. In Laser Scanning IAPRS, Vol. XXXVIII, Part 3/W8 – Paris, France, September 1-2, 2009.

Gross, H., Jutzi, B., & Thoennessen, U. (2007). Segmentation of tree regions using data of a full-waveform laser. International Archives of Photogrammetry, Remote Sensing and Spatial Information Sciences, 36(part 3), W49A.

Niemeyer, J., Mallet, C., Rottensteiner, F., & Sörgel, U. (2012). Conditional Random Fields for the Classification of LIDAR Point Clouds. In XXII ISPRS Congress at Melbourne, ISPRS Annals of the Photogrammetry, Remote Sensing and Spatial Information Sciences (Vol. 3).

West, K. F., Webb, B. N., Lersch, J. R., Pothier, S., Triscari, J. M., & Iverson, A. E. (2004). Context-driven automated target detection in 3D data. In Automatic Target Recognition XIV (Vol. 5426, pp. 133-143). SPIE.

See Also: FilterLidar, ModifyLidar, SortLidar, SplitLidar

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
--num_neighboursNumber of neighbours used in search
--radiusSearch distance used in neighbourhood search

Python function:

wbt.lidar_eigenvalue_features(
    i=None, 
    num_neighbours=None, 
    radius=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LidarEigenvalueFeatures -i=input.las ^
-o=output.las --radius=2.5 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 18/02/2022

Last Modified: 25/02/2022

LidarElevationSlice

This tool can be used to either extract or classify the elevation values (z) of LiDAR points within a specified elevation range (slice). In addition to the names of the input and output LiDAR files (--input and --output), the user must specify the lower (--minz) and upper (--maxz) bounds of the elevation range. By default, the tool will only output points within the elevation slice, filtering out all points lying outside of this range. If the --class parameter is used, the tool will operate by assigning a class value (--inclassval) to the classification bit of points within the slice and another class value (--outclassval) to those points falling outside the range.

See Also: LidarRemoveOutliers, LidarClassifySubset

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--minzMinimum elevation value (optional)
--maxzMaximum elevation value (optional)
--classOptional boolean flag indicating whether points outside the range should be retained in output but reclassified
--inclassvalOptional parameter specifying the class value assigned to points within the slice
--outclassvalOptional parameter specifying the class value assigned to points within the slice

Python function:

wbt.lidar_elevation_slice(
    i, 
    output, 
    minz=None, 
    maxz=None, 
    cls=False, 
    inclassval=2, 
    outclassval=1, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarElevationSlice -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--minz=100.0 --maxz=250.0
>>./whitebox_tools ^
-r=LidarElevationSlice -v -i="/path/to/data/input.las" ^
-o="/path/to/data/output.las" --minz=100.0 --maxz=250.0 ^
--class
>>./whitebox_tools -r=LidarElevationSlice -v ^
-i="/path/to/data/input.las" -o="/path/to/data/output.las" ^
--minz=100.0 --maxz=250.0 --inclassval=1 --outclassval=0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/06/2017

Last Modified: 18/10/2019

LidarGroundPointFilter

This tool can be used to perform a slope-based classification, or filtering (i.e. removal), of non-ground points within a LiDAR point-cloud. The user must specify the name of the input and output LiDAR files (--input and --output). Inter-point slopes are compared between pair of points contained within local neighbourhoods of size --radius. Neighbourhoods with fewer than the user-specified minimum number of points (--min_neighbours) are extended until the minimum point number is equaled or exceeded. Points that are above neighbouring points by the minimum (--height_threshold) and have an inter-point slope greater than the user-specifed threshold (--slope_threshold) are considered non-ground points and are either optionally (--classify) excluded from the output point-cloud or assigned the unclassified (value 1) class value.

Slope-based ground-point classification methods suffer from the challenge of uses a constant slope threshold under varying terrain slopes. Some researchers have developed schemes for varying the slope threshold based on underlying terrain slopes. LidarGroundPointFilter instead allow the user to optionally (--slope_norm) normalize the underlying terrain (i.e. flatten the terrain) using a white top-hat transform. A constant slope threshold may then be used without contributing to poorer performance under steep topography. Note, that this option, while useful in rugged terrain, is computationally intensive. If the point-cloud is of a relatively flat terrain, this option may be excluded.

While this tool is appropriately applied to LiDAR point-clouds, the RemoveOffTerrainObjects tool can be used to remove off-terrain objects from rasterized LiDAR digital elevation models (DEMs).

Reference:

Vosselman, G. (2000). Slope based filtering of laser altimetry data. International Archives of Photogrammetry and Remote Sensing, 33(B3/2; PART 3), 935-942.

See Also: RemoveOffTerrainObjects

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--radiusSearch Radius
--min_neighboursThe minimum number of neighbouring points within search areas. If fewer points than this threshold are identified during the fixed-radius search, a subsequent kNN search is performed to identify the k number of neighbours
--slope_thresholdMaximum inter-point slope to be considered an off-terrain point
--height_thresholdInter-point height difference to be considered an off-terrain point
--classifyClassify points as ground (2) or off-ground (1)
--slope_normPerform initial ground slope normalization?
--height_above_groundTransform output to height above average ground elevation?

Python function:

wbt.lidar_ground_point_filter(
    i, 
    output, 
    radius=2.0, 
    min_neighbours=0, 
    slope_threshold=45.0, 
    height_threshold=1.0, 
    classify=True, 
    slope_norm=True, 
    height_above_ground=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarGroundPointFilter -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 --min_neighbours=10 --slope_threshold=30.0 ^
--height_threshold=0.5 --classify --slope_norm 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/06/2017

Last Modified: 18/10/2019

LidarHexBinning

The practice of binning point data to form a type of 2D histogram, density plot, or what is sometimes called a heatmap, is quite useful as an alternative for the cartographic display of of very dense points sets. This is particularly the case when the points experience significant overlap at the displayed scale. The LidarPointDensity tool can be used to perform binning based on a regular grid (raster output). This tool, by comparison, bases the binning on a hexagonal grid.

The tool is similar to the CreateHexagonalVectorGrid tool, however instead will create an output hexagonal grid in which each hexagonal cell possesses a COUNT attribute which specifies the number of points from an input points file (LAS file) that are contained within the hexagonal cell. The tool will also calculate the minimum and maximum elevations and intensity values and outputs these data to the attribute table.

In addition to the names of the input points file and the output Shapefile, the user must also specify the desired hexagon width (w), which is the distance between opposing sides of each hexagon. The size (s) each side of the hexagon can then be calculated as, s = w / [2 x cos(PI / 6)]. The area of each hexagon (A) is, A = 3s(w / 2). The user must also specify the orientation of the grid with options of horizontal (pointy side up) and vertical (flat side up).

See Also: VectorHexBinning, LidarPointDensity, CreateHexagonalVectorGrid

Parameters:

FlagDescription
-i, --inputInput base file
-o, --outputOutput vector polygon file
--widthThe grid cell width
--orientationGrid Orientation, 'horizontal' or 'vertical'

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/09/2018

Last Modified: 12/10/2018

LidarHillshade

Calculates a hillshade value for points within a LAS file and stores these data in the RGB field.

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput file
--azimuthIllumination source azimuth in degrees
--altitudeIllumination source altitude in degrees
--radiusSearch Radius

Python function:

wbt.lidar_hillshade(
    i, 
    output, 
    azimuth=315.0, 
    altitude=30.0, 
    radius=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarHillshade -v --wd="/path/to/data/" ^
-i="input.las" -o="output.las" --radius=10.0
>>./whitebox_tools ^
-r=LidarHillshade -v --wd="/path/to/data/" -i="input.las" ^
-o="output.las" --azimuth=180.0 --altitude=20.0 --radius=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/06/2017

Last Modified: 22/10/2019

LidarHistogram

This tool can be used to plot a histogram of data derived from a LiDAR file. The user must specify the name of the input LAS file (--input), the name of the output HTML file (--output), the parameter (--parameter) to be plotted, and the amount (in percent) to clip the upper and lower tails of the f requency distribution (--clip). The LiDAR parameters that can be plotted using LidarHistogram include the point elevations, intensity values, scan angles, and class values.

Use the LidarPointStats tool instead to examine the spatial distribution of LiDAR points.

See Also: LidarPointStats

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput HTML file (default name will be based on input file if unspecified)
--parameterParameter; options are 'elevation' (default), 'intensity', 'scan angle', 'class', 'time'
--clipAmount to clip distribution tails (in percent)

Python function:

wbt.lidar_histogram(
    i, 
    output, 
    parameter="elevation", 
    clip=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarHistogram -v --wd="/path/to/data/" ^
-i="file1.tif, file2.tif, file3.tif" -o=outfile.htm ^
--contiguity=Bishopsl 

Source code on GitHub

Author: Dr. John Lindsay

Created: 23/12/2017

Last Modified: 12/10/2018

LidarIdwInterpolation

This tool interpolates LiDAR files using inverse-distance weighting (IDW) scheme. The user must specify the value of the IDW weight parameter (--weight). The output grid can be based on any of the stored LiDAR point parameters (--parameter), including elevation (in which case the output grid is a digital elevation model, DEM), intensity, class, return number, number of returns, scan angle, RGB (colour) values, and user data values. Similarly, the user may specify which point return values (--returns) to include in the interpolation, including all points, last returns (including single return points), and first returns (including single return points).

The user must specify the grid resolution of the output raster (--resolution), and optionally, the name of the input LiDAR file (--input) and output raster (--output). Note that if an input LiDAR file (--input) is not specified by the user, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be very useful when you need to interpolate a DEM for a large number of LiDAR files. Not only does this batch processing mode enable the tool to run in a more optimized parallel manner, but it will also allow the tool to include a small buffer of points extending into adjacent tiles when interpolating an individual file. This can significantly reduce edge-effects when the output tiles are later mosaicked together. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file with the same name as each input LiDAR file, but with the .tif extension. This can provide a very efficient means for processing extremely large LiDAR data sets.

Users may excluded points from the interpolation based on point classification values, which follow the LAS classification scheme. Excluded classes are specified using the --exclude_cls parameter. For example, to exclude all vegetation and building classified points from the interpolation, use --exclude_cls='3,4,5,6'. Users may also exclude points from the interpolation if they fall below or above the minimum (--minz) or maximum (--maxz) thresholds respectively. This can be a useful means of excluding anomalously high or low points. Note that points that are classified as low points (LAS class 7) or high noise (LAS class 18) are automatically excluded from the interpolation operation.

The tool will search for the nearest input LiDAR point to each grid cell centre, up to a maximum search distance (--radius). If a grid cell does not have a LiDAR point within this search distance, it will be assigned the NoData value in the output raster. In LiDAR data, these void areas are often associated with larger waterbodies. These NoData areas can later be better dealt with using the FillMissingData tool after interpolation.

See Also: LidarTINGridding, LidarNearestNeighbourGridding, LidarSibsonInterpolation

Parameters:

FlagDescription
-i, --inputInput LiDAR file (including extension)
-o, --outputOutput raster file (including extension)
--parameterInterpolation parameter; options are 'elevation' (default), 'intensity', 'class', 'return_number', 'number_of_returns', 'scan angle', 'rgb', 'user data'
--returnsPoint return types to include; options are 'all' (default), 'last', 'first'
--resolutionOutput raster's grid resolution
--weightIDW weight value
--radiusSearch Radius
--exclude_clsOptional exclude classes from interpolation; Valid class values range from 0 to 18, based on LAS specifications. Example, --exclude_cls='3,4,5,6,7,18'
--minzOptional minimum elevation for inclusion in interpolation
--maxzOptional maximum elevation for inclusion in interpolation

Python function:

wbt.lidar_idw_interpolation(
    i=None, 
    output=None, 
    parameter="elevation", 
    returns="all", 
    resolution=1.0, 
    weight=1.0, 
    radius=2.5, 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarIdwInterpolation -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0 --radius=5.0"
./whitebox_tools ^
-r=LidarIdwInterpolation --wd="/path/to/data/" -i=file.las ^
-o=outfile.tif --resolution=5.0 --weight=2.0 --radius=2.0 ^
--exclude_cls='3,4,5,6,7,18' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 03/07/2017

Last Modified: 19/05/2020

LidarInfo

This tool can be used to print basic information about the data contained within a LAS file, used to store LiDAR data. The reported information will include including data on the header, point return frequency, and classification data and information about the variable length records (VLRs) and geokeys.

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput HTML file for summary report
--densityFlag indicating whether or not to calculate the average point density and nominal point spacing
--vlrFlag indicating whether or not to print the variable length records (VLRs)
--geokeysFlag indicating whether or not to print the geokeys

Python function:

wbt.lidar_info(
    i, 
    output, 
    density=True, 
    vlr=True, 
    geokeys=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarInfo -v --wd="/path/to/data/" ^
-i=file.las --vlr --geokeys"
./whitebox_tools -r=LidarInfo ^
--wd="/path/to/data/" -i=file.las 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/06/2017

Last Modified: 30/01/2022

LidarJoin

This tool can be used to merge multiple LiDAR LAS files into a single output LAS file. Due to their large size, LiDAR data sets are often tiled into smaller, non-overlapping tiles. Sometimes it is more convenient to combine multiple tiles together for data processing and LidarJoin can be used for this purpose.

See Also: LidarTile

Parameters:

FlagDescription
-i, --inputsInput LiDAR files
-o, --outputOutput LiDAR file

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=LidarJoin -v --wd="/path/to/data/" ^
-i="file1.las, file2.las, file3.las" -o=outfile.las" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/06/2017

Last Modified: 29/08/2018

LidarKappaIndex

This tool performs a kappa index of agreement (KIA) analysis on the classification values of two LiDAR (LAS) files. The output report HTML file should be displayed automatically but can also be displayed afterwards in any web browser. As a measure of overall classification accuracy, the KIA is more robust than the percent agreement calculation because it takes into account the agreement occurring by random chance. In addition to the KIA, the tool will output the producer's and user's accuracy, the overall accuracy, and the error matrix. The KIA is often used as a means of assessing the accuracy of an image classification analysis; however the LidarKappaIndex tool performs the analysis on a point-to-point basis, comparing the class values of the points in one input LAS file with the corresponding nearest points in the second input LAS file.

The user must also specify the name and resolution of an output raster file, which is used to show the spatial distribution of class accuracy. Each grid cell contains the overall accuracy, i.e. the points correctly classified divided by the total number of points contained within the cell, expressed as a percentage.

Parameters:

FlagDescription
--i1, --input1Input LiDAR classification file
--i2, --input2Input LiDAR reference file
-o, --outputOutput HTML file
--class_accuracyOutput classification accuracy raster file
--resolutionOutput raster's grid resolution

Python function:

wbt.lidar_kappa_index(
    input1, 
    input2, 
    output, 
    class_accuracy, 
    resolution=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarKappaIndex -v ^
--wd="/path/to/data/" --i1=class.las --i2=reference.las ^
-o=kia.html --class_accuracy=new_file.tif --resolution=0.5 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/09/2017

Last Modified: 04/01/2019

LidarNearestNeighbourGridding

This tool grids LiDAR files using nearest-neighbour (NN) scheme, that is, each grid cell in the output image will be assigned the parameter value of the point nearest the grid cell centre. This method should not be confused for the similarly named natural-neighbour interpolation (a.k.a Sibson's method). Nearest neighbour gridding is generally regarded as a poor way of interpolating surfaces from low-density point sets and results in the creation of a Voronoi diagram. However, this method has several advantages when applied to LiDAR data. NN gridding is one of the fastest methods for generating raster surfaces from large LiDAR data sets. NN gridding is one of the few interpolation methods, along with triangulation, that will preserve vertical breaks-in-slope, such as occur at the edges of building. This characteristic can be important when using some post-processing methods, such as the RemoveOffTerrainObjects tool. Furthermore, because most LiDAR data sets have remarkably high point densities compared with other types of geographic data, this approach does often produce a satisfactory result; this is particularly true when the point density is high enough that there are multiple points in the majority of grid cells.

The output grid can be based on any of the stored LiDAR point parameters (--parameter), including elevation (in which case the output grid is a digital elevation model, DEM), intensity, class, return number, number of returns, scan angle, RGB (colour) values, time, and user data values. Similarly, the user may specify which point return values (--returns) to include in the interpolation, including all points, last returns (including single return points), and first returns (including single return points).

The user must specify the grid resolution of the output raster (--resolution), and optionally, the name of the input LiDAR file (--input) and output raster (--output). Note that if an input LiDAR file (--input) is not specified by the user, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be very useful when you need to interpolate a DEM for a large number of LiDAR files. Not only does this batch processing mode enable the tool to run in a more optimized parallel manner, but it will also allow the tool to include a small buffer of points extending into adjacent tiles when interpolating an individual file. This can significantly reduce edge-effects when the output tiles are later mosaicked together. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file with the same name as each input LiDAR file, but with the .tif extension. This can provide a very efficient means for processing extremely large LiDAR data sets.

Users may excluded points from the interpolation based on point classification values, which follow the LAS classification scheme. Excluded classes are specified using the --exclude_cls parameter. For example, to exclude all vegetation and building classified points from the interpolation, use --exclude_cls='3,4,5,6'. Users may also exclude points from the interpolation if they fall below or above the minimum (--minz) or maximum (--maxz) thresholds respectively. This can be a useful means of excluding anomalously high or low points. Note that points that are classified as low points (LAS class 7) or high noise (LAS class 18) are automatically excluded from the interpolation operation.

The tool will search for the nearest input LiDAR point to each grid cell centre, up to a maximum search distance (--radius). If a grid cell does not have a LiDAR point within this search distance, it will be assigned the NoData value in the output raster. In LiDAR data, these void areas are often associated with larger waterbodies. These NoData areas can later be better dealt with using the FillMissingData tool after interpolation.

See Also: LidarTINGridding, LidarIdwInterpolation, LidarTINGridding, RemoveOffTerrainObjects, FillMissingData

Parameters:

FlagDescription
-i, --inputInput LiDAR file (including extension)
-o, --outputOutput raster file (including extension)
--parameterInterpolation parameter; options are 'elevation' (default), 'intensity', 'class', 'return_number', 'number_of_returns', 'scan angle', 'rgb', 'user data', 'time'
--returnsPoint return types to include; options are 'all' (default), 'last', 'first'
--resolutionOutput raster's grid resolution
--radiusSearch Radius
--exclude_clsOptional exclude classes from interpolation; Valid class values range from 0 to 18, based on LAS specifications. Example, --exclude_cls='3,4,5,6,7,18'
--minzOptional minimum elevation for inclusion in interpolation
--maxzOptional maximum elevation for inclusion in interpolation

Python function:

wbt.lidar_nearest_neighbour_gridding(
    i=None, 
    output=None, 
    parameter="elevation", 
    returns="all", 
    resolution=1.0, 
    radius=2.5, 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarNearestNeighbourGridding -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--returns=last --resolution=2.0 --radius=5.0"
./whitebox_tools ^
-r=LidarNearestNeighbourGridding --wd="/path/to/data/" ^
-i=file.las -o=outfile.tif --resolution=5.0 --radius=2.0 ^
--exclude_cls='3,4,5,6,7,18' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 15/06/2021

LidarPointDensity

Calculates the spatial pattern of point density for a LiDAR data set. When the input/output parameters are not specified, the tool grids all LAS files contained within the working directory.

Parameters:

FlagDescription
-i, --inputInput LiDAR file (including extension)
-o, --outputOutput raster file (including extension)
--returnsPoint return types to include; options are 'all' (default), 'last', 'first'
--resolutionOutput raster's grid resolution
--radiusSearch radius
--exclude_clsOptional exclude classes from interpolation; Valid class values range from 0 to 18, based on LAS specifications. Example, --exclude_cls='3,4,5,6,7,18'
--minzOptional minimum elevation for inclusion in interpolation
--maxzOptional maximum elevation for inclusion in interpolation

Python function:

wbt.lidar_point_density(
    i=None, 
    output=None, 
    returns="all", 
    resolution=1.0, 
    radius=2.5, 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarPointDensity -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0 --radius=5.0"
./whitebox_tools ^
-r=LidarPointDensity -v --wd="/path/to/data/" -i=file.las ^
-o=outfile.tif --resolution=5.0 --radius=2.0 ^
--exclude_cls='3,4,5,6,7,18' --palette=light_quant.plt 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/07/2017

Last Modified: 19/05/2020

LidarPointReturnAnalysis

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

This performs a quality control check on the return values of points in a LiDAR file. In particular, the tool will search for missing point returns, duplicate point returns, and points for which the return number (r) is larger than the encoded number of returns (n), all of which may be indicative of processing or encoding errors in the input file.

The user must specify the name of the input LiDAR file (--input), and may optionally specify an output LiDAR file (--output). If no output file is specified, only the text report is generated by the tool. If an output is specified, the tool will create an output LiDAR file for which missing returns are assigned class 13, duplicate returns are assigned class 14, points that are both, part of a missing series and are duplicate returns, are classed 15, and all other non-problemmatic points are assigned class 1. Note, those points designated as missing in the output image are clearly not so much missing as they are part of a sequence of points that contain missing returns. Missing points are apparent when the first point in a series does not have r = 1, when the last point does not have r = n, or the series is non-sequential (e.g. 1/3, 3/3, but no 2/3). This condition may occur because returns are split between tiles. However, when sequences with missing points are not located near the edges of tiles, it is usually an indication that either point filtering has taken place during pre-processing or that there is been some kind of processing or encoding error.

Duplicate points are defined as points that share the same time, scanner channel, r, and n. Note that these points may have different x, y, z coordinates. Duplicate points are always an indication of a processing or encoding error. For example, it may indicate that the scanner channel information from a multi-channel LiDAR sensor has not been encoded when creating the file or has been lost.

No point should have r > n. This always indicates some kind of processing or encoding error when it occurs.

The following is a sample output report generated by this tool:

***************************************
* Welcome to LidarPointReturnAnalysis *
***************************************
The Global Encoding for this file indicates that
the point returns are not synthetic.

Missing Returns:
2441636 (16.336 percent) points are missing

| r | n | Missing Pts |
|---|---|-------------|
| 1 | 2 |     1127770 |
| 2 | 2 |         817 |
| 1 | 3 |      823240 |
| 2 | 3 |         569 |
| 3 | 3 |         718 |
| 1 | 4 |      285695 |
| 2 | 4 |      142890 |
| 3 | 4 |         142 |
| 4 | 4 |         213 |
| 1 | 5 |       29772 |
| 2 | 5 |       19848 |
| 3 | 5 |        9928 |
| 4 | 5 |          18 |
| 5 | 5 |          16 |


Duplicate Returns:
4311021 (28.844 percent) points are duplicates

| r | n | Duplicates |
|---|---|------------|
| 1 | 1 |    2707083 |
| 1 | 2 |     332028 |
| 2 | 2 |     663717 |
| 1 | 3 |      70619 |
| 2 | 3 |     211834 |
| 3 | 3 |     282348 |
| 1 | 4 |       2856 |
| 2 | 4 |       8568 |
| 3 | 4 |      14280 |
| 4 | 4 |      17136 |
| 1 | 5 |         23 |
| 2 | 5 |         69 |
| 3 | 5 |        115 |
| 4 | 5 |        161 |
| 5 | 5 |        184 |


Return Greater Than Num. Returns:
0 (0.000 percent) points have r > n

Writing output LAS file...
Complete!
Elapsed Time (including I/O): 1.959s

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output LiDAR points

Python function:

wbt.lidar_point_return_analysis(
    i, 
    output=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LidarPointReturnAnalysis -i=input.las ^
-o=output.las 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 13/06/2021

Last Modified: 13/06/2021

LidarPointStats

This tool creates several rasters summarizing the distribution of LiDAR points in a LAS data file. The user must specify the name of an input LAS file (--input) and the output raster grid resolution (--resolution). Additionally, the user must specify one or more of the possible output rasters to create using the various available flags, which include:

FlagMeaning
--num_pointsNumber of points (returns) in each grid cell
--num_pulsesNumber of pulses in each grid cell
--avg_points_per_pulseAverage number of points per pulse in each grid cells
--z_rangeElevation range within each grid cell
--intensity_rangeIntensity range within each grid cell
--predom_classPredominant class value within each grid cell

If no output raster flags are specified, all of the output rasters will be created. All output rasters will have the same base name as the input LAS file but will have a suffix that reflects the statistic type (e.g. _num_pnts, _num_pulses, _avg_points_per_pulse, etc.). Output files will be in the GeoTIFF (*.tif) file format.

When the input/output parameters are not specified, the tool works on all LAS files contained within the working directory.

Notes:

  1. The num_pulses output is actually the number of pulses with at least one return; specifically it is the sum of the early returns (first and only) in a grid cell. In areas of low reflectance, such as over water surfaces, the system may have emitted a significantly higher pulse rate but far fewer returns are observed.
  2. The memory requirement of this tool is high, particulalry if the grid resolution is fine and the spatial extent is large.

See Also: LidarBlockMinimum, LidarBlockMaximum

Parameters:

FlagDescription
-i, --inputInput LiDAR file
--resolutionOutput raster's grid resolution
--num_pointsFlag indicating whether or not to output the number of points (returns) raster
--num_pulsesFlag indicating whether or not to output the number of pulses raster
--avg_points_per_pulseFlag indicating whether or not to output the average number of points (returns) per pulse raster
--z_rangeFlag indicating whether or not to output the elevation range raster
--intensity_rangeFlag indicating whether or not to output the intensity range raster
--predom_classFlag indicating whether or not to output the predominant classification raster

Python function:

wbt.lidar_point_stats(
    i=None, 
    resolution=1.0, 
    num_points=True, 
    num_pulses=False, 
    avg_points_per_pulse=True, 
    z_range=False, 
    intensity_range=False, 
    predom_class=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarPointStats -v ^
--wd="/path/to/data/" -i=file.las --resolution=1.0 ^
--num_points 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/02/2018

Last Modified: 20/05/2020

LidarRansacPlanes

This tool uses the random sample consensus (RANSAC) method to identify points within a LiDAR point cloud that belong to planar surfaces. RANSAC is a common method used in the field of computer vision to identify a subset of inlier points in a noisy data set containing abundant outlier points. Because LiDAR point clouds often contain vegetation points that do not form planar surfaces, this tool can be used to largely strip vegetation points from the point cloud, leaving behind the ground returns, buildings, and other points belonging to planar surfaces. If the --classify flag is used, non-planar points will not be removed but rather will be assigned a different class (1) than the planar points (0).

The algorithm selects a random sample, of a specified size (--num_samples) of the points from within the neighbourhood (--radius) surrounding each LiDAR point. The sample is then used to parameterize a planar best-fit model. The distance between each neighbouring point and the plane is then evaluated; inliers are those neighbouring points within a user-specified distance threshold (--threshold). Models with at least a minimum number of inlier points (--model_size) are then accepted. This process of selecting models is iterated a number of user-specified times (--num_iter).

One of the challenges with identifying planar surfaces in LiDAR point clouds is that these data are usually collected along scan lines. Therefore, each scan line can potentially yield a vertical planar surface, which is one reason that some vegetation points remain after applying the RANSAC plane-fitting method. To cope with this problem, the tool allows the user to specify a maximum planar slope (--max_slope) parameter. Planes that have slopes greater than this threshold are rejected by the algorithm. This has the side-effect of removing building walls however.

References:

Fischler MA and Bolles RC. 1981. Random sample consensus: a paradigm for model fitting with applications to image analysis and automated cartography. Commun. ACM, 24(6):381–395.

See Also: LidarSegmentation, LidarGroundPointFilter

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--radiusSearch Radius
--num_iterNumber of iterations
--num_samplesNumber of sample points on which to build the model
--thresholdThreshold used to determine inlier points
--model_sizeAcceptable model size
--max_slopeMaximum planar slope
--classifyClassify points as ground (2) or off-ground (1)
--last_returnsOnly include last- and only-return points

Python function:

wbt.lidar_ransac_planes(
    i, 
    output, 
    radius=2.0, 
    num_iter=50, 
    num_samples=5, 
    threshold=0.35, 
    model_size=8, 
    max_slope=80.0, 
    classify=False, 
    last_returns=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarRansacPlanes -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 --num_iter=10 --num_samples=5 --threshold=0.25 ^
--max_slope=70.0 --last_returns 

Source code on GitHub

Author: Dr. John Lindsay

Created: 23/07/2019

Last Modified: 29/12/2019

LidarRbfInterpolation

Interpolates LAS files using a radial basis function (RBF) scheme. When the input/output parameters are not specified, the tool interpolates all LAS files contained within the working directory.

Parameters:

FlagDescription
-i, --inputInput LiDAR file (including extension)
-o, --outputOutput raster file (including extension)
--parameterInterpolation parameter; options are 'elevation' (default), 'intensity', 'class', 'return_number', 'number_of_returns', 'scan angle', 'rgb', 'user data'
--returnsPoint return types to include; options are 'all' (default), 'last', 'first'
--resolutionOutput raster's grid resolution
--num_pointsNumber of points
--exclude_clsOptional exclude classes from interpolation; Valid class values range from 0 to 18, based on LAS specifications. Example, --exclude_cls='3,4,5,6,7,18'
--minzOptional minimum elevation for inclusion in interpolation
--maxzOptional maximum elevation for inclusion in interpolation
--func_typeRadial basis function type; options are 'ThinPlateSpline' (default), 'PolyHarmonic', 'Gaussian', 'MultiQuadric', 'InverseMultiQuadric'
--poly_orderPolynomial order; options are 'none' (default), 'constant', 'affine'
--weightWeight parameter used in basis function

Python function:

wbt.lidar_rbf_interpolation(
    i=None, 
    output=None, 
    parameter="elevation", 
    returns="all", 
    resolution=1.0, 
    num_points=20, 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    func_type="ThinPlateSpline", 
    poly_order="none", 
    weight=5, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarRbfInterpolation -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0 --radius=5.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/11/2019

Last Modified: 19/05/2020

LidarRemoveDuplicates

This tool removes duplicate points from a LiDAR data set. Duplicates are determined by their x, y, and optionally (--include_z) z coordinates.

See Also: EliminateCoincidentPoints

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--include_zInclude z-values in point comparison?

Python function:

wbt.lidar_remove_duplicates(
    i, 
    output, 
    include_z=False, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/03/2018

Last Modified: 18/10/2019

LidarRemoveOutliers

This tool will filter out points from a LiDAR point cloud if the absolute elevation difference between a point and the averge elevation of its neighbourhood, calculated without the point, exceeds a threshold (elev_diff).

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--radiusSearch Radius
--elev_diffMax. elevation difference
--use_medianOptional flag indicating whether to use the difference from median elevation rather than mean
--classifyClassify points as ground (2) or off-ground (1)

Python function:

wbt.lidar_remove_outliers(
    i, 
    output, 
    radius=2.0, 
    elev_diff=50.0, 
    use_median=False, 
    classify=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarRemoveOutliers -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 --elev_diff=25.0 --use_median 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/02/2018

Last Modified: 18/10/2019

LidarRooftopAnalysis

This tool can be used to identify roof segments in a LiDAR point cloud.

See Also: ClassifyBuildingsInLidar, ClipLidarToPolygon

Parameters:

FlagDescription
-i, --inputInput LiDAR file
--buildingsInput vector build footprint polygons file
-o, --outputOutput vector polygon file
--radiusSearch Radius
--num_iterNumber of iterations
--num_samplesNumber of sample points on which to build the model
--thresholdThreshold used to determine inlier points (in elevation units)
--model_sizeAcceptable model size, in points
--max_slopeMaximum planar slope, in degrees
--norm_diffMaximum difference in normal vectors, in degrees
--azimuthIllumination source azimuth, in degrees
--altitudeIllumination source altitude in degrees

Python function:

wbt.lidar_rooftop_analysis(
    buildings, 
    output, 
    i=None, 
    radius=2.0, 
    num_iter=50, 
    num_samples=10, 
    threshold=0.15, 
    model_size=15, 
    max_slope=65.0, 
    norm_diff=10.0, 
    azimuth=180.0, 
    altitude=30.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarRooftopAnalysis -v ^
--wd="/path/to/data/" -i='data.las' --polygons='buildings.shp' ^
-o='rooftops.shp' --radius=10.0 --num_iter=10 --num_samples=5 ^
--threshold=0.25 --max_slope=70.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/06/2020

Last Modified: 10/06/2020

LidarSegmentation

This tool can be used to segment a LiDAR point cloud based on differences in the orientation of fitted planar surfaces and point proximity. The algorithm begins by attempting to fit planar surfaces to all of the points within a user-specified radius (--radius) of each point in the LiDAR data set. The planar equation is stored for each point for which a suitable planar model can be fit. A region-growing algorithm is then used to assign nearby points with similar planar models. Similarity is based on a maximum allowable angular difference (in degrees) between the two neighbouring points' plane normal vectors (--norm_diff). The --norm_diff parameter can therefore be thought of as a way of specifying the magnitude of edges mapped by the region-growing algorithm. By setting this value appropriately, it is possible to segment each facet of a building's roof. Segment edges for planar points may also be determined by a maximum allowable height difference (--maxzdiff) between neighbouring points on the same plane. Points for which no suitable planar model can be fit are assigned to 'volume' (non-planar) segments (e.g. vegetation points) using a region-growing method that connects neighbouring points based solely on proximity (i.e. all volume points within radius distance are considered to belong to the same segment).

The resulting point cloud will have both planar segments (largely ground surfaces and building roofs and walls) and volume segments (largely vegetation). Each segment is assigned a random red-green-blue (RGB) colour in the output LAS file. The largest segment in any airborne LiDAR dataset will usually belong to the ground surface. This largest segment will always be assigned a dark-green RGB of (25, 120, 0) by the tool.

This tool uses the random sample consensus (RANSAC) method to identify points within a LiDAR point cloud that belong to planar surfaces. RANSAC is a common method used in the field of computer vision to identify a subset of inlier points in a noisy data set containing abundant outlier points. Because LiDAR point clouds often contain vegetation points that do not form planar surfaces, this tool can be used to largely strip vegetation points from the point cloud, leaving behind the ground returns, buildings, and other points belonging to planar surfaces. If the --classify flag is used, non-planar points will not be removed but rather will be assigned a different class (1) than the planar points (0).

The algorithm selects a random sample, of a specified size (--num_samples) of the points from within the neighbourhood (--radius) surrounding each LiDAR point. The sample is then used to parameterize a planar best-fit model. The distance between each neighbouring point and the plane is then evaluated; inliers are those neighbouring points within a user-specified distance threshold (--threshold). Models with at least a minimum number of inlier points (--model_size) are then accepted. This process of selecting models is iterated a number of user-specified times (--num_iter).

One of the challenges with identifying planar surfaces in LiDAR point clouds is that these data are usually collected along scan lines. Therefore, each scan line can potentially yield a vertical planar surface, which is one reason that some vegetation points may be assigned to planes during the RANSAC plane-fitting method. To cope with this problem, the tool allows the user to specify a maximum planar slope (--max_slope) parameter. Planes that have slopes greater than this threshold are rejected by the algorithm. This has the side-effect of removing building walls however.

References:

Fischler MA and Bolles RC. 1981. Random sample consensus: a paradigm for model fitting with applications to image analysis and automated cartography. Commun. ACM, 24(6):381–395.

See Also: LidarRansacPlanes, LidarGroundPointFilter

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--radiusSearch Radius
--num_iterNumber of iterations
--num_samplesNumber of sample points on which to build the model
--thresholdThreshold used to determine inlier points
--model_sizeAcceptable model size
--max_slopeMaximum planar slope
--norm_diffMaximum difference in normal vectors, in degrees
--maxzdiffMaximum difference in elevation (z units) between neighbouring points of the same segment
--classesSegments don't cross class boundaries
--groundClassify the largest segment as ground points?

Python function:

wbt.lidar_segmentation(
    i, 
    output, 
    radius=2.0, 
    num_iter=50, 
    num_samples=10, 
    threshold=0.15, 
    model_size=15, 
    max_slope=80.0, 
    norm_diff=10.0, 
    maxzdiff=1.0, 
    classes=False, 
    ground=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarSegmentation -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 --num_iter=10 --num_samples=5 --threshold=0.25 ^
--max_slope=70.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/12/2017

Last Modified: 12/01/2020

LidarSegmentationBasedFilter

Identifies ground points within LiDAR point clouds using a segmentation based approach.

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput file
--dist, --radiusSearch Radius
--norm_diffMaximum difference in normal vectors, in degrees
--maxzdiffMaximum difference in elevation (z units) between neighbouring points of the same segment
--classifyClassify points as ground (2) or off-ground (1)

Python function:

wbt.lidar_segmentation_based_filter(
    i, 
    output, 
    radius=5.0, 
    norm_diff=2.0, 
    maxzdiff=1.0, 
    classify=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarSegmentationBasedFilter -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 --norm_diff=2.5 --maxzdiff=0.75 --classify 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/12/2017, 2017

Last Modified: 22/10/2019

LidarShift

This tool can be used to shift the x,y,z coordinates of points within a LiDAR file. The user must specify the name of the input file (--input) and the output file (--output). Additionally, the user must specify the x,y,z shift values (x_shift, y_shift, z_shift). At least one non-zero shift value is needed to run the tool. Notice that shifting the x,y,z coordinates of LiDAR points is also possible using the ModifyLidar tool, which can also be used for more sophisticated point property manipulation (e.g. rotations).

See Also: ModifyLidar, LidarElevationSlice, HeightAboveGround

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output LiDAR points
-x, --x_shiftx-shift value, blank for none
-y, --y_shifty-shift value, blank for none
-z, --z_shiftz-shift value, blank for none

Python function:

wbt.lidar_shift(
    i, 
    output, 
    x_shift="", 
    y_shift="", 
    z_shift="", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LidarShift -i=input.las -o=output.las



Source code is unavailable due to proprietary license.

Author: Dr. John Lindsay

Created: 19/01/2022

Last Modified: 19/01/2022

LidarSibsonInterpolation

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

This tool interpolates LiDAR files using Sibson's interpolation method, sometimes referred to as natural-neighbour interpolation (not to be confused with nearest-neighbour interpolation, LidarNearestNeighbourGridding). Sibon's method is based on assigning weight to points for which inserting a grid point would result in captured areas of the Voronoi tessellation of the input point set. The larger the captured area, the higher the weight assigned to the associated point. One of the main advantages of this natural neighbour approach to interpolation over similar techniques, such as inverse-distance weighting (IDW LidarIdwInterpolation), is that there is no need to specify a search distance or other interpolation weighting parameters. Sibson's approach frequently provides a very suitable interpolation for LiDAR data. The method requires the calculation of a Delaunay triangulation, from which the Voronoi tessellation is calculated.

The user must specify the value of the IDW weight parameter (--weight). The output grid can be based on any of the stored LiDAR point parameters (--parameter), including elevation (in which case the output grid is a digital elevation model, DEM), intensity, class, return number, number of returns, scan angle values, and user data values. Similarly, the user may specify which point return values (--returns) to include in the interpolation, including all points, last returns (including single return points), and first returns (including single return points).

The user must specify the grid resolution of the output raster (--resolution), and optionally, the name of the input LiDAR file (--input) and output raster (--output). Note that if an input LiDAR file (--input) is not specified by the user, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be useful when you need to interpolate a DEM for a large number of LiDAR files. This batch processing mode enables the tool to include a small buffer of points extending into adjacent tiles when interpolating an individual file. This can significantly reduce edge-effects when the output tiles are later mosaicked together. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file with the same name as each input LiDAR file, but with the .tif extension. This can provide a very efficient means for processing extremely large LiDAR data sets.

Users may excluded points from the interpolation based on point classification values, which follow the LAS classification scheme. Excluded classes are specified using the --exclude_cls parameter. For example, to exclude all vegetation and building classified points from the interpolation, use --exclude_cls='3,4,5,6'. Users may also exclude points from the interpolation if they fall below or above the minimum (--minz) or maximum (--maxz) thresholds respectively. This can be a useful means of excluding anomalously high or low points. Note that points that are classified as low points (LAS class 7) or high noise (LAS class 18) are automatically excluded from the interpolation operation.

See Also: LidarTINGridding, LidarNearestNeighbourGridding, LidarIdwInterpolation

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points (leave blank to use all files in WorkingDirectory
-o, --outputOutput raster file (including extension)
-p, --parameterInterpolation parameter; options are 'elevation' (default), 'intensity', 'class', 'return_number', 'number_of_returns', 'scan angle', 'user_data'
--returnsPoint return types to include; options are 'all' (default), 'last', 'first'
--resolutionOutput raster's grid resolution
--exclude_clsOptional exclude classes from interpolation; Valid class values range from 0 to 18, based on LAS specifications. Example, --exclude_cls='3,4,5,6,7,18'
--minzOptional minimum elevation for inclusion in interpolation
--maxzOptional maximum elevation for inclusion in interpolation

Python function:

wbt.lidar_sibson_interpolation(
    i=None, 
    output=None, 
    parameter="elevation", 
    returns="all", 
    resolution=1.0, 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LidarSibsonInterpolation -i=file.las ^
-o=outfile.tif -p='elevation' --returns='last' ^
--resolution=1.0 --exclude_cls='3,4,5,6,7,18' 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 12/04/2021

Last Modified: 12/04/2021

LidarSortByTime

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

This tool sorts the points in a LiDAR file by the GPS time. This can significantly improve LiDAR compression rates in the zLidar data format. Therefore, running LidarSortByTime can be a useful pre-cursor to running LasToZlidar when file size is the greatest concern.

See Also: LasToZlidar

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output LiDAR points

Python function:

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

Command-line Interface:

>> ./whitebox_tools -r=LidarSortByTime -i=input.las ^
-o=output.las 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 07/03/2021

Last Modified: 12/06/2021

LidarThin

Thins a LiDAR point cloud, reducing point density.

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--resolutionThe size of the square area used to evaluate nearby points in the LiDAR data
--methodPoint selection method; options are 'first', 'last', 'lowest' (default), 'highest', 'nearest'
--save_filteredSave filtered points to separate file?

Python function:

wbt.lidar_thin(
    i, 
    output, 
    resolution=2.0, 
    method="lowest", 
    save_filtered=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarThin -v --wd="/path/to/data/" ^
-i=file.las -o=outfile.las --resolution=2.0, --method=first ^
--save_filtered 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/05/2018

Last Modified: 18/10/2019

LidarThinHighDensity

Thins points from high density areas within a LiDAR point cloud.

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--resolutionOutput raster's grid resolution
--densityMax. point density (points / m^3)
--save_filteredSave filtered points to separate file?

Python function:

wbt.lidar_thin_high_density(
    i, 
    output, 
    density, 
    resolution=1.0, 
    save_filtered=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarThinHighDensity -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--resolution=1.0 --density=100.0 --save_filtered 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/02/2018

Last Modified: 18/10/2019

LidarTile

This tool can be used to break a LiDAR LAS file into multiple, non-overlapping tiles, each saved as a single LAS file. The user must specify the parameter of the tile grid, including its origin (--origin_x and --origin_y) and the tile width and height (--width and --height). Tiles containing fewer points than specified in the --min_points parameter will not be output. This can be useful when tiling terrestrial LiDAR datasets because the low point density at the edges of the point cloud (i.e. most distant from the scan station) can result in poorly populated tiles containing relatively few points.

See Also: LidarJoin, LidarTileFootprint

Parameters:

FlagDescription
-i, --inputInput LiDAR file
--widthWidth of tiles in the X dimension; default 1000.0
--heightHeight of tiles in the Y dimension
--origin_xOrigin point X coordinate for tile grid
--origin_yOrigin point Y coordinate for tile grid
--min_pointsMinimum number of points contained in a tile for it to be saved

Python function:

wbt.lidar_tile(
    i, 
    width=1000.0, 
    height=1000.0, 
    origin_x=0.0, 
    origin_y=0.0, 
    min_points=2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarTile -v -i=/path/to/data/input.las ^
--width=1000.0 --height=2500.0 -=min_points=100 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 05/02/2019

LidarTileFootprint

This tool can be used to create a vector polygon of the bounding box or convex hull of a LiDAR point cloud (i.e. LAS file). If the user specified an input file (--input) and output file (--output), the tool will calculate the footprint, containing all of the data points, and output this feature to a vector polygon file. If the input and output parameters are left unspecified, the tool will calculate the footprint of every LAS file contained within the working directory and output these features to a single vector polygon file. If this is the desired mode of operation, it is important to specify the working directory (--wd) containing the group of LAS files; do not specify the optional --input and --output parameters in this case. Each polygon in the output vector will contain a LAS_NM field, specifying the source LAS file name, a NUM_PNTS field, containing the number of points within the source file, and Z_MIN and Z_MAX fields, containing the minimum and maximum elevations. This output can therefore be useful to create an index map of a large tiled LiDAR dataset.

By default, this tool identifies the axis-aligned minimum rectangular hull, or bounding box, containing the points in each of the input tiles. If the user specifies the --hull flag, the tool will identify the minimum convex hull instead of the bounding box. This option is considerably more computationally intensive and will be a far longer running operation if many tiles are specified as inputs.

A note on LAZ file inputs: While WhiteboxTools does not currently support the reading and writing of the compressed LiDAR format LAZ, it is able to read LAZ file headers. This tool, when run in in the bounding box mode (rather than the convex hull mode), is able to take LAZ input files.

LidarTile, LayerFootprint, MinimumBoundingBox, MinimumConvexHull

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput vector polygon file
--hullIdentify the convex hull around points

Python function:

wbt.lidar_tile_footprint(
    output, 
    i=None, 
    hull=False, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 31/08/2018

Last Modified: 19/05/2020

LidarTinGridding

This tool creates a raster grid based on a Delaunay triangular irregular network (TIN) fitted to LiDAR points. The output grid can be based on any of the stored LiDAR point parameters (--parameter), including elevation (in which case the output grid is a digital elevation model, DEM), intensity, class, return number, number of returns, scan angle, RGB (colour) values, and user data values. Similarly, the user may specify which point return values (--returns) to include in the interpolation, including all points, last returns (including single return points), and first returns (including single return points).

The user must specify the grid resolution of the output raster (--resolution), and optionally, the name of the input LiDAR file (--input) and output raster (--output). Note that if an input LiDAR file (--input) is not specified by the user, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be very useful when you need to interpolate a DEM for a large number of LiDAR files. Not only does this batch processing mode enable the tool to run in a more optimized parallel manner, but it will also allow the tool to include a small buffer of points extending into adjacent tiles when interpolating an individual file. This can significantly reduce edge-effects when the output tiles are later mosaicked together. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file with the same name as each input LiDAR file, but with the .tif extension. This can provide a very efficient means for processing extremely large LiDAR data sets.

Users may excluded points from the interpolation based on point classification values, which follow the LAS classification scheme. Excluded classes are specified using the --exclude_cls parameter. For example, to exclude all vegetation and building classified points from the interpolation, use --exclude_cls='3,4,5,6'. Users may also exclude points from the interpolation if they fall below or above the minimum (--minz) or maximum (--maxz) thresholds respectively. This can be a useful means of excluding anomalously high or low points. Note that points that are classified as low points (LAS class 7) or high noise (LAS class 18) are automatically excluded from the interpolation operation.

Triangulation will generally completely fill the convex hull containing the input point data. This can sometimes result in very long and narrow triangles at the edges of the data or connecting vertices on either side of void areas. In LiDAR data, these void areas are often associated with larger waterbodies, and triangulation can result in very unnatural interpolated patterns within these areas. To avoid this problem, the user may specify a the maximum allowable triangle edge length (max_triangle_edge_length) and all grid cells within triangular facets with edges larger than this threshold are simply assigned the NoData values in the output DSM. These NoData areas can later be better dealt with using the FillMissingData tool after interpolation.

See Also: LidarIdwInterpolation, LidarNearestNeighbourGridding, LidarTINGridding, FilterLidarClasses, FillMissingData

Parameters:

FlagDescription
-i, --inputInput LiDAR file (including extension)
-o, --outputOutput raster file (including extension)
--parameterInterpolation parameter; options are 'elevation' (default), 'intensity', 'class', 'return_number', 'number_of_returns', 'scan angle', 'rgb', 'user data'
--returnsPoint return types to include; options are 'all' (default), 'last', 'first'
--resolutionOutput raster's grid resolution
--exclude_clsOptional exclude classes from interpolation; Valid class values range from 0 to 18, based on LAS specifications. Example, --exclude_cls='3,4,5,6,7,18'
--minzOptional minimum elevation for inclusion in interpolation
--maxzOptional maximum elevation for inclusion in interpolation
--max_triangle_edge_lengthOptional maximum triangle edge length; triangles larger than this size will not be gridded

Python function:

wbt.lidar_tin_gridding(
    i=None, 
    output=None, 
    parameter="elevation", 
    returns="all", 
    resolution=1.0, 
    exclude_cls="7,18", 
    minz=None, 
    maxz=None, 
    max_triangle_edge_length=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarTINGridding -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--returns=last --resolution=2.0 --exclude_cls='3,4,5,6,7,18' ^
--max_triangle_edge_length=5.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/09/2018

Last Modified: 25/05/2020

LidarTophatTransform

This tool performs a white top-hat transform on a LiDAR point cloud (--input). A top-hat transform is a common digital image processing operation used for various tasks, such as feature extraction, background equalization, and image enhancement. When applied to a LiDAR point cloud, the white top-hat transform provides an estimate of height above ground, which is useful for modelling the vegetation canopy.

As an example, notice that the input point cloud on the top of the image below has a substantial amount of topographic variability. After applying the top-hat transform (bottom point cloud), all of this topographic variability has been removed and point elevations values effectively become height above ground.

The white top-hat transform is defined as the difference between a point's original elevation and its opening. The opening operation can be thought of as the local neighbourhood maximum of a previous local minimum surface. The user must specify the size of the neighbourhood using the --radius parameter. Setting this parameter can require some experimentation. Generally, it is appropriate to use a radius of a few meters in non-urban landscapes. However, in urban areas, the radius may need to be set much larger, reflective of the size of the largest building.

If the input point cloud already has ground points classified, it may be better to use the HeightAboveGround, which simply measures the difference in height between each point and its nearest ground classified point within the search radius.

See Also: HeightAboveGround, TophatTransform, Closing, Opening

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--radiusSearch Radius

Python function:

wbt.lidar_tophat_transform(
    i, 
    output, 
    radius=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarTophatTransform -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/09/2017

Last Modified: 24/04/2019

ModifyLidar

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

The ModifyLidar tool can be used to alter the properties of points within a LiDAR point cloud. The user provides a statement (--statement) containing one or more expressions, separated by semicolons (;). The expressions are evaluated for each point within the input LiDAR file (--input). Expressions assign altered values to the properties of points in the output file (--output), based on any mathematically defined expression that may include the various properties of individual points (e.g. coordinates, intensity, return attributes, etc) or some file-level properties (e.g. min/max coordinates). As a basic example, the following statement:

x = x + 1000.0

could be used to translate the point cloud 1000 x-units (note, the increment operator could be used as a simpler equivalent, x += 1000.0).

Note that if the user does not specify the optional input LiDAR file, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be useful for processing a large number of LiDAR files in batch mode. When this batch mode is applied, the output file names will be the same as the input file names but with a '_modified' suffix added to the end.

Expressions may contain any of the following point-level or file-level variables:

Variable NameDescriptionType
Point-level properties
xThe point x coordinatefloat
yThe point y coordinatefloat
zThe point z coordinatefloat
xyAn x-y coordinate tuple, (x, y)(float, float)
xyzAn x-y-z coordinate tuple, (x, y, z)(float, float, float)
intensityThe point intensity valueint
retThe point return numberint
nretThe point number of returnsint
is_onlyTrue if the point is an only return (i.e. ret == nret == 1), otherwise falseBoolean
is_multipleTrue if the point is a multiple return (i.e. nret > 1), otherwise falseBoolean
is_earlyTrue if the point is an early return (i.e. ret == 1), otherwise falseBoolean
is_intermediateTrue if the point is an intermediate return (i.e. ret > 1 && ret < nret), otherwise falseBoolean
is_lateTrue if the point is a late return (i.e. ret == nret), otherwise falseBoolean
is_firstTrue if the point is a first return (i.e. ret == 1 && nret > 1), otherwise falseBoolean
is_lastTrue if the point is a last return (i.e. ret == nret && nret > 1), otherwise falseBoolean
classThe class value in numeric form, e.g. 0 = Never classified, 1 = Unclassified, 2 = Ground, etc.int
is_noiseTrue if the point is classified noise (i.e. class == 7
is_syntheticTrue if the point is synthetic, otherwise falseBoolean
is_keypointTrue if the point is a keypoint, otherwise falseBoolean
is_withheldTrue if the point is withheld, otherwise falseBoolean
is_overlapTrue if the point is an overlap point, otherwise falseBoolean
scan_angleThe point scan angleint
scan_directionTrue if the scanner is moving from the left towards the right, otherwise falseBoolean
is_flightline_edgeTrue if the point is situated along the filightline edge, otherwise falseBoolean
user_dataThe point user dataint
point_source_idThe point source IDint
scanner_channelThe point scanner channelint
timeThe point GPS time, if it exists, otherwise 0float
rgbA red-green-blue tuple (r, g, b) if it exists, otherwise (0,0,0)(int, int, int)
nirThe point near infrared value, if it exists, otherwise 0int
pt_numThe point number within the input fileint
File-level properties (invariant)
n_ptsThe number of points within the fileint
min_xThe file minimum x valuefloat
mid_xThe file mid-point x valuefloat
max_xThe file maximum x valuefloat
min_yThe file minimum y valuefloat
mid_yThe file mid-point y valuefloat
max_yThe file maximum y valuefloat
min_zThe file minimum z valuefloat
mid_zThe file mid-point z valuefloat
max_zThe file maximum z valuefloat
x_scale_factorThe file x scale factorfloat
y_scale_factorThe file y scale factorfloat
z_scale_factorThe file z scale factorfloat
x_offsetThe file x offsetfloat
y_offsetThe file y offsetfloat
z_offsetThe file z offsetfloat

Most of the point-level properties above are modifiable, however some are not. The complete list of modifiable point attributes include, x, y, z, xy, xyz, intensity, ret, nret, class, user_data, point_source_id, scanner_channel, scan_angle, time, rgb, nir, is_synthetic, is_keypoint, is_withheld, and is_overlap. The immutable properties include is_only, is_multiple, is_early, is_intermediate, is_late, is_first, is_last, is_noise, and pt_num. Of the file-level properties, the modifiable properties include the x_scale_factor, y_scale_factor, z_scale_factor, x_offset, y_offset, and z_offset.

In addition to the point properties defined above, if the user applies the LidarEigenvalueFeatures tool on the input LiDAR file, the ModifyLidar tool will automatically read in the additional *.eigen file, which include the eigenvalue-based point neighbourhood measures, such as lambda1, lambda2, lambda3, linearity, planarity, sphericity, omnivariance, eigentropy, slope, and residual. See the LidarEigenvalueFeatures documentation for details on each of these metrics describing the structure and distribution of points within the neighbourhood surrounding each point in the LiDAR file.

Expressions may use any of the standard mathematical operators, +, -, *, /, % (modulo), ^ (exponentiation), comparison operators, <, >, <=, >=, == (equality), != (inequality), and logical operators, && (Boolean AND), || (Boolean OR). Expressions must evaluate to an assignment operation, where the variable that is assigned to must be a modifiable point-level property (see table above). That is, expressions should take the form pt_variable = .... Other assignment operators are also possible (at least for numeric non-tuple properties), such as the increment (=+) operator (e.g. x += 1000.0) and the decrement (-=) operator (e.g. y -= 1000.0). Expressions may use a number of built-in mathematical functions, including:

Function NameDescriptionExample
ifPerforms an if(CONDITION, TRUE, FALSE) operation, return either the value of TRUE or FALSE depending on CONDITIONret = if(ret==0, 1, ret)
absReturns the absolute value of the argumentvalue = abs(x - mid_x)
minReturns the minimum of the argumentsvalue = min(x, y, z)
maxReturns the maximum of the argumentsvalue = max(x, y, z)
floorReturns the largest integer less than or equal to a numberx = floor(x)
roundReturns the nearest integer to a number. Rounds half-way cases away from 0.0x = round(x)
ceilReturns the smallest integer greater than or equal to a numberx = ceil(x)
clampForces a value to fall within a specified range, defined by a minimum and maximumz = clamp(min_z+10.0, z, max_z-20.0)
intReturns the integer equivalent of a numberintensity = int(z)
floatReturns the float equivalent of a numberz = float(intensity)
to_radiansConverts a number in degrees to radiansval = to_radians(scan_angle)
to_degreesConverts a number in radians to degreesscan_angle = int(to_degrees(val))
distReturns the distance between two points defined by two n-length tuplesd = dist(xy, (mid_x, mid_y)) or d = dist(xyz, (mid_x, mid_y, mid_z))
rotate_ptRotates an x-y point by a certain angle, in degreesxy = rotate_pt(xy, 45.0) or orig_pt = (1000.0, 1000.0); xy = rotate_pt(xy, 45.0, orig_pt)
math::lnReturns the natural logarithm of the numberz = math::ln(z)
math::logReturns the logarithm of the number with respect to an arbitrary basez = math::log(z, 10)
math::log2Returns the base 2 logarithm of the numberz = math::log2(z)
math::log10Returns the base 10 logarithm of the numberz = math::log10(z)
math::expReturns e^(number), (the exponential function)z = math::exp(z)
math::powRaises a number to the power of the other numberz = math::pow(z, 2.0)
math::sqrtReturns the square root of a number. Returns NaN for a negative numberz = math::sqrt(z, 2.0)
math::cosComputes the cosine of a number (in radians)z = math::cos(to_radians(z))
math::sinComputes the sine of a number (in radians)z = math::sin(to_radians(z))
math::tanComputes the tangent of a number (in radians)z = math::tan(to_radians(z))
math::acosComputes the arccosine of a number. The return value is in radians in the range [0, pi] or NaN if the number is outside the range [-1, 1]z = math::acos(z)
math::asinComputes the arcsine of a number. The return value is in radians in the range [0, pi] or NaN if the number is outside the range [-1, 1]z = math::asin(z)
math::atanComputes the arctangent of a number. The return value is in radians in the range [0, pi] or NaN if the number is outside the range [-1, 1]z = math::atan(z)
randReturns a random value between 0 and 1, with an optional seed valuergb = (int(255.0 * rand()), int(255.0 * rand()), int(255.0 * rand()))
helmert_transformationPerforms a Helmert transformation on a point using a 7-parameter transformxyz = helmert_transformation(xyz, −446.448, 125.157, −542.06, 20.4894, −0.1502, −0.247, −0.8421 )

The hyperbolic trigonometric functions are also available for use in expression building, as is math::atan2 and the mathematical constants pi and e.

You may use if operations within statements to implement a conditional modification of point properties. For example, the following expression demonstrates how you could modify a point's RGB colour based on its classification, assign ground points (class 2) in the output file a green colour:

rgb = if(class==2, (0,255,0), rgb)

To colour all points within 50 m of the tile mid-point red and all other points blue:

rgb = if(dist(xy, (mid_x, mid_y))<50.0, (255,0,0), (0,0,255))

if operations may also be nested to create more complex compound conditional point modification. For example, in the following statement, we assign first-return points red (255,0,0) and last-return points green (0,255,0) colours and white (255,255,255) to all other points (intermediate-returns and only-returns):

rgb = if(is_first, (255,0,0), if(is_last, (0,255,0), (255,255,255)))

Here we use an if expression to re-classify points above an elevation of 1000.0 as high noise (class 18):

class = if(z>1000.0, 18, class)

Expressions may be strung together within statements using semicolons (;), with each expression being evaluated individually. When this is the case, at least one of the expressions must assign a value to one of the variant point properties (see table above). The following statement demonstrates multi-expression statements, in this case to swap the x and y coordinates in a LiDAR file:

new_var = x; x = y; y = new_var

The rand function, used with the seeding option, can be useful when assigning colours to points based on common point properties. For example, to assign a point a random RGB colour based on its point_source_id (Note, for many point clouds, this operation will assign each flightline a unique colour; if flightline information is not stored in the file's point_source_id attribute, one could use the RecoverFlightlineInfo tool to calculate this data.):

rgb=(int(255 * rand(point_source_id)), int(255 * rand(point_source_id+1)), int(255 * rand(point_source_id+2)))

This expression-based approach to modifying point properties provides a great deal of flexibility and power to the processing of LiDAR point cloud data sets.

See Also: FilterLidar, SortLidar, LidarEigenvalueFeatures

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output LiDAR points
-s, --statementModify statement e.g. x += 5000.0

Python function:

wbt.modify_lidar(
    i=None, 
    output=None, 
    statement="", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ModifyLidar -i=input.las -o=output.las ^
--statement="x += 5000.0" 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 06/02/2022

Last Modified: 12/02/2022

NormalVectors

Calculates normal vectors for points within a LAS file and stores these data (XYZ vector components) in the RGB field.

Parameters:

FlagDescription
-i, --inputInput LiDAR file
-o, --outputOutput LiDAR file
--radiusSearch Radius

Python function:

wbt.normal_vectors(
    i, 
    output, 
    radius=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NormalVectors -v --wd="/path/to/data/" ^
-i="input.las" -o="output.las" --radius=10.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 22/10/2019

NormalizeLidar

This tool can be used to normalize a LiDAR point cloud. A normalized point cloud is one for which the point z-values represent height above the ground surface rather than raw elevation values. Thus, a point that falls on the ground surface will have a z-value of zero and vegetation points, and points associated with other off-terrain objects, have positive, non-zero z-values. Point cloud normalization is an essential pre-processing method for many forms of LiDAR data analysis, including the characterization of many forestry related metrics and individual tree mapping (IndividualTreeDetection).

This tool works by measuring the elevation difference of each point in an input LiDAR file (--input) and the elevation of an input raster digital terrain model (--dtm). A DTM is a bare-earth digital elevation model. Typically, the input DTM is creating using the same input LiDAR data by interpolating the ground surface using only ground-classified points. If the LiDAR point cloud does not contain ground-point classifications, you may wish to apply the LidarGroundPointFilter or ClassifyLidartools before interpolating the DTM. While ground-point classification works well to identify the ground surface beneath vegetation cover, building points are sometimes left It may also be necessary to remove other off-terrain objects like buildings. The RemoveOffTerrainObjects tool can be useful for this purpose, creating a final bare-earth DTM. This tool outputs a normalized LiDAR point cloud (--output). If the --no_negatives parameter is true, any points that fall beneath the surface elevation defined by the DTM, will have their z-value set to zero.

Note that the LidarTophatTransform tool similarly can be used to produce a type of normalized point cloud, although it does not require an input raster DTM. Rather, it attempts to model the ground surface within the point cloud by identifying the lowest points within local neighbourhoods surrounding each point in the cloud. While this approach can produce satisfactory results in some cases, the NormalizeLidar tool likely works better under more rugged topography and in areas with extensive building coverage, and provides greater control over the definition of the ground surface.

See Also: LidarTophatTransform, IndividualTreeDetection, LidarGroundPointFilter, ClassifyLidar

Parameters:

FlagDescription
-i, --inputName of the input LiDAR file
-o, --outputName of the output LiDAR file
--dtmName of the input digital terrain model (DTM) raster file

Python function:

wbt.normalize_lidar(
    i, 
    output, 
    dtm, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=NormalizeLidar -i=points.laz ^
-o=normalized.laz --dtm=dtm.tif 

Source code is unavailable due to proprietary license.

Author: Dr. John Lindsay

Created: 05/03/2023

Last Modified: 05/03/2023

RecoverFlightlineInfo

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

Raw airborne LiDAR data are collected along flightlines and multiple flightlines are typically merged into square tiles to simplify data handling and processing. Commonly the Point Source ID attribute is used to store information about the origin flightline of each point. However, sometimes this information is lost (e.g. during data format conversion) or is omitted from some data sets. This tool can be used to identify groups of points within a LiDAR file (--input) that belong to the same flightline.

The tool works by sorting points based on their timestamp and then identifying points for which the time difference from the previous point is greater than a user-specified maximum time difference (--max_time_diff), which are deemed to be the start of a different flightline. The operational assumption is that the time between consecutive points within a flightline is usually quite small (usually a fraction of a second), while the time between points in different flightlines is often relatively large (consider the aircraft turning time needed to take multiple passes of the study area). By default the maximum time difference is set to 5.0 seconds, although it may be necessary to increase this value depending on the characteristics of a particular data set.

The tool works on individual LiDAR tiles and the flightline identifiers will range from 0 to the number of flightlines detected within the tile, minus one. Therefore, the flightline identifier created by this tool will not extend beyond the boundaries of the tile and into adjacent tiles. That is, a flightline that extends across multiple adjacent LiDAR tiles may have different flightline identifiers used in each tile. The identifiers are intended to discriminate between flighlines within a single file. The flightline identifier value can be optionally assigned to the Point Source ID point attribute (--pt_src_id), the User Data point attribute (--user_data), and the red-green-blue point colour data (--rgb) within the output file (--output). At least one of these output options must be selected and it is possible to select multiple output options. Notice that if the input file contains any information within the selected output fields, the original information will be over-written, and therefore lost--of course, it will remain unaltered within the input file, which this tool does not modify. If the input file does not contain RGB colour data and the --rgb output option is selected, the output file point format will be altered from the input file to accommodate the addition of RGB colour data. Flightlines are assigned random colours. The LAS User Data point attribute is stored as a single byte and, therefore, if this output option is selected and the input file contains more than 256 flightlines, the tool will assign the same flightline identifier to more than one flightline. It is very rare for this condition to be the case in a typical 1 km-square tiles. The Point Source ID attribute is stored as a 16-bit integer and can therefore store 65,536 unique flightline identifiers.

Outputting flightline information within the colour data point attribute can be useful for visualizing areas of flightline overlap within a file. This can be an important quality assurance/quality control (QA/QC) step after acquiring a new LiDAR data set.

Please note that because this tool sorts points by their timestamps, the order of points in the output file may not match that of the input file.

See Also: FlightlineOverlap, FindFlightlineEdgePoints, LidarSortByTime

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output LiDAR points
--max_time_diffMaximum in-flightline time difference (seconds)
--pt_src_idAdd flightline information to the point source ID
--user_dataAdd flightline information to the user data
--rgbAdd flightline information to the RGB colour data

Python function:

wbt.recover_flightline_info(
    i, 
    output, 
    max_time_diff=5.0, 
    pt_src_id=False, 
    user_data=False, 
    rgb=False, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RecoverFlightlineInfo -i=input.las ^
-o=output.las --pt_src_id --rgb 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 12/02/2022

Last Modified: 13/02/2022

SelectTilesByPolygon

This tool copies LiDAR tiles overlapping with a polygon into an output directory. In actuality, the tool performs point-in-polygon operations, using the four corner points, the center point, and the four mid-edge points of each LiDAR tile bounding box and the polygons. This representation of overlapping geometry aids with performance. This approach generally works well when the polygon size is large relative to the LiDAR tiles. If, however, the input polygon is small relative to the tile size, this approach may miss some copying some tiles. It is advisable to buffer the polygon if this occurs.

See Also: LidarTileFootprint

Parameters:

FlagDescription
--indirInput LAS file source directory
--outdirOutput directory into which LAS files within the polygon are copied
--polygonsInput vector polygons file

Python function:

wbt.select_tiles_by_polygon(
    indir, 
    outdir, 
    polygons, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SelectTilesByPolygon -v ^
--indir='/path/to/lidar/' --outdir='/output/path/' ^
--polygons='watershed.shp' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/08/2018

Last Modified: 19/05/2020

SortLidar

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

This tool can be used to sort the points in an input LiDAR file (--input) based on their properties with respect to one or more sorting criteria (--criteria). The sorting criteria may include: the x, y or z coordinates (x, y, z), the intensity data (intensity), the point class value (class), the point user data field (user_data), the return number (ret_num), the point source ID (point_source_id), the point scan angle data (scan_angle), the scanner channel (scanner_channel; LAS 1.4 datasets only), and the acquisition time (time). The following is an example of a complex sorting criteria statement that includes multiple criteria:

x 100.0, y 100.0, z 10.0, scan_angle

Criteria should be separated by a comma, semicolon, or pipe (|). Each criteria may have an associated bin value. In the example above, point x values are sorted into bins of 100 m, which are then sorted by y values into bins of 100 m, and sorted by point z values into bins of 10 m, and finally sorted by their scan_angle.

Sorting point values can have a significant impact on the compression rate when using certain compressed LiDAR data formats (e.g. LAZ, zLidar). Sorting values can also improve the visualization speed in some rendering software.

Note that if the user does not specify the optional input LiDAR file, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be useful for processing a large number of LiDAR files in batch mode. When this batch mode is applied, the output file names will be the same as the input file names but with a '_sorted' suffix added to the end.

See Also: LasToLaz, SplitLidar, FilterLidar, ModifyLidar

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
-o, --outputName of the output LiDAR points
-c, --criteriaSort criteria e.g. 'x 50.0, y 50.0, z'; criteria may include x, y, z, intensity, class, user_data, point_source_id, and scan_angle

Python function:

wbt.sort_lidar(
    i=None, 
    output=None, 
    criteria="", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=SortLidar -i=input.las ^
--criteria='x 100, y 100, z 10, time' 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 18/02/2022

Last Modified: 27/02/2022

SplitLidar

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

This tool can be used to split an input LiDAR file (--input) into a series of output files, placing points into each output based on their properties with respect to a grouping criterion (--criterion). Points can be grouped based on a specified the number of points in the output file (num_pts; note the last file may contain fewer points), the x, y or z coordinates (x, y, z), the intensity data (intensity), the point class value (class), the point user data field (user_data), the point source ID (point_source_id), the point scan angle data (scan_angle), and the acquisition time (time). Points are binned into groupings based on a user-specified interval value (--interval). For example, if an interval of 50.0 is used with the z criterion, a series of files will be output that are elevation bands of 50 m. The user may also optionally specify the minimum number of points needed before a particular grouping file is saved (--min_pts). The interval value is not used for the class and point_source_id criteria.

With this tool, a single input file can generate many output files. The names of the output files will be reflective of the point attribute used for the grouping and the bin. For example, running the tool with the on an input file named my_file.las using intensity criterion and with an interval of 1000 may produce the following files:

  • my_file_intensity0.las
  • my_file_intensity1000.las
  • my_file_intensity2000.las
  • my_file_intensity3000.las
  • my_file_intensity4000.las

Where the number after the attribute (intensity, in this case) reflects the lower boundary of the bin. Thus, the first file contains all of the input points with intensity values from 0 to just less than 1000.

Note that if the user does not specify the optional input LiDAR file, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be useful for processing a large number of LiDAR files in batch mode. When this batch mode is applied, the output file names will be the same as the input file names but with a suffix added to the end reflective of the split criterion and value (see above).

See Also: SortLidar, FilterLidar, ModifyLidar, LidarElevationSlice

Parameters:

FlagDescription
-i, --inputName of the input LiDAR points
--criterionCriterion on which to base the split of the input file. Options include 'num_pts, 'x', 'y', 'z', intensity, 'class', 'user_data', 'point_source_id', 'scan_angle', 'time'
--intervalInterval
--min_ptsMinimum number of points in an output file

Python function:

wbt.split_lidar(
    i=None, 
    criterion="num_pts", 
    interval="", 
    min_pts=5, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=SplitLidar -i=input.las --criterion=z ^
--interval=10.0 --min_pts=10 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 12/02/2022

Last Modified: 14/02/2022

ZlidarToLas

This tool can be used to convert one or more zLidar files ('*.zlidar') files into the LAS LiDAR data format. zLidar files are a compressed form of the LAS data format. The tool takes a list of input LAS files (--inputs). If --inputs is unspecified, the tool will use all ZLidar files contained within the working directory as the tool inputs. The user may also specify an optional output directory --outdir. If this parameter is unspecified, each output LAS file will be written to the same directory as the input files.

See Also: LasToZlidar, AsciiToLas

Parameters:

FlagDescription
-i, --inputsInput ZLidar files
--outdirOutput directory into which zlidar files are created. If unspecified, it is assumed to be the same as the inputs

Python function:

wbt.zlidar_to_las(
    inputs=None, 
    outdir=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ZlidarToLas -v --wd="/path/to/data/" ^
-i="file1.zlidar, file2.zlidar, file3.zlidar" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/05/2020

Last Modified: 13/05/2020

Machine Learning

Dbscan

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

This tool performs an unsupervised DBSCAN clustering operation, based on a series of input rasters (--inputs). Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space. The DBSCAN algorithm identifies clusters in feature space by identifying regions of high density (core points) and the set of points connected to these high-density areas. Points in feature space that are not connected to high-density regions are labeled by the DBSCAN algorithm as 'noise' and the associated grid cell in the output raster (--output) is assigned the nodata value. Areas of high density (i.e. core points) are defined as those points for which the number of neighbouring points within a search distance (--search_dist) is greater than some user-defined minimum threshold (--min_points).

The main advantages of the DBSCAN algorithm over other clustering methods, such as k-means (KMeansClustering), is that 1) you do not need to specify the number of clusters a priori, and 2) that the method does not make assumptions about the shape of the cluster (spherical in the k-means method). However, DBSCAN does assume that the density of every cluster in the data is approximately equal, which may not be a valid assumption. DBSCAN may also produce unsatisfactory results if there is significant overlap among clusters, as it will aggregate the clusters. Finding search distance and minimum core-point density thresholds that apply globally to the entire data set may be very challenging or impossible for certain applications.

The DBSCAN algorithm is based on the calculation of distances in multi-dimensional space. Feature scaling is essential to the application of DBSCAN clustering, especially when the ranges of the features are different, for example, if they are measured in different units. Without scaling, features with larger ranges will have greater influence in computing the distances between points. The tool offers three options for feature-scaling (--scaling), including 'None', 'Normalize', and 'Standardize'. Normalization simply rescales each of the features onto a 0-1 range. This is a good option for most applications, but it is highly sensitive to outliers because it is determined by the range of the minimum and maximum values. Standardization rescales predictors using their means and standard deviations, transforming the data into z-scores. This is a better option than normalization when you know that the data contain outlier values; however, it does does assume that the feature data are somewhat normally distributed, or are at least symmetrical in distribution.

One should keep the impact of feature scaling in mind when setting the --search_dist parameter. For example, if applying normalization, the entire range of values for each dimension of feature space will be bound within the 0-1 range, meaning that the search distance should be smaller than 1.0, and likely significantly smaller. If standardization is used instead, features space is technically infinite, although the vast majority of the data are likely to be contained within the range -2.5 to 2.5.

Because the DBSCAN algorithm calculates distances in feature-space, like many other related algorithms, it suffers from the curse of dimensionality. Distances become less meaningful in high-dimensional space because the vastness of these spaces means that distances between points are less significant (more similar). As such, if the predictor list includes insignificant or highly correlated variables, it is advisable to exclude these features during the model-building phase, or to use a dimension reduction technique such as PrincipalComponentAnalysis to transform the features into a smaller set of uncorrelated predictors.

Memory Usage:

The peak memory usage of this tool is approximately 8 bytes per grid cell × # predictors.

See Also: KMeansClustering, ModifiedKMeansClustering, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input rasters
--scalingScaling method for predictors. Options include 'None', 'Normalize', and 'Standardize'
-o, --outputName of the output raster file
--search_distSearch-distance parameter
--min_pointsMinimum point density needed to define 'core' point in cluster

Python function:

wbt.dbscan(
    inputs, 
    output, 
    scaling="Normalize", 
    search_dist=0.01, 
    min_points=5, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=Dbscan ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' ^
--scaling='Normalize' -o=clustered.tif --search_dist=0.01 ^
--min_points=10 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 26/12/2021

Last Modified: 01/01/2022

KMeansClustering

This tool can be used to perform a k-means clustering operation on two or more input images (--inputs), typically several bands of multi-spectral satellite imagery. The tool creates two outputs, including the classified image (--output and a classification HTML report (--out_html). The user must specify the number of class (--classes), which should be known a priori, and the strategy for initializing class clusters (--initialize). The initialization strategies include "diagonal" (clusters are initially located randomly along the multi-dimensional diagonal of spectral space) and "random" (clusters are initially located randomly throughout spectral space). The algorithm will continue updating cluster center locations with each iteration of the process until either the user-specified maximum number of iterations (--max_iterations) is reached, or until a stability criteria (--class_change) is achieved. The stability criteria is the percent of the total number of pixels in the image that are changed among the class values between consecutive iterations. Lastly, the user must specify the minimum allowable number of pixels in a cluster (--min_class_size).

Note, each of the input images must have the same number of rows and columns and the same spatial extent because the analysis is performed on a pixel-by-pixel basis. NoData values in any of the input images will result in the removal of the corresponding pixel from the analysis.

See Also: ModifiedKMeansClustering

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file
--out_htmlOutput HTML report file
--classesNumber of classes
--max_iterationsMaximum number of iterations
--class_changeMinimum percent of cells changed between iterations before completion
--initializeHow to initialize cluster centres?
--min_class_sizeMinimum class size, in pixels

Python function:

wbt.k_means_clustering(
    inputs, 
    output, 
    classes, 
    out_html=None, 
    max_iterations=10, 
    class_change=2.0, 
    initialize="diagonal", 
    min_class_size=10, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=KMeansClustering -v ^
--wd='/path/to/data/' -i='image1.tif;image2.tif;image3.tif' ^
-o=output.tif --out_html=report.html --classes=15 ^
--max_iterations=25 --class_change=1.5 --initialize='random' ^
--min_class_size=500 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/12/2017

Last Modified: 24/02/2019

KnnClassification

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

This tool performs a supervised k-nearest neighbour (k-NN) classification using multiple predictor rasters (--inputs), or features, and training data (--training). It can be used to model the spatial distribution of class data, such as land-cover type, soil class, or vegetation type. The training data take the form of an input vector Shapefile containing a set of points or polygons, for which the known class information is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space. The algorithm works by identifying a user-defined number (k, -k) of feature-space neighbours from the training set for each grid cell. The class that is then assigned to the grid cell in the output raster (--output) is then determined as the most common class among the set of neighbours. Note that the KnnRegression tool can be used to apply the k-NN method to the modelling of continuous data.

The user has the option to clip the training set data (--clip). When this option is selected, each training pixel for which the estimated class value, based on the k-NN procedure, is not equal to the known class value, is removed from the training set before proceeding with labelling all grid cells. This has the effect of removing outlier points within the training set and often improves the overall classification accuracy.

The tool splits the training data into two sets, one for training the classifier and one for testing the classification. These test data are used to calculate the overall accuracy and Cohen's kappa index of agreement, as well as to estimate the variable importance. The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, the tool behaves stochastically, and will result in a different model each time it is run.

Note that the output image parameter (--output) is optional. When unspecified, the tool will simply report the model accuracy statistics and variable importance, allowing the user to experiment with different parameter settings and input predictor raster combinations to optimize the model before applying it to classify the whole image data set.

Like all supervised classification methods, this technique relies heavily on proper selection of training data. Training sites are exemplar areas/points of known and representative class value (e.g. land cover type). The algorithm determines the feature signatures of the pixels within each training area. In selecting training sites, care should be taken to ensure that they cover the full range of variability within each class. Otherwise the classification accuracy will be impacted. If possible, multiple training sites should be selected for each class. It is also advisable to avoid areas near the edges of class objects (e.g. land-cover patches), where mixed pixels may impact the purity of training site values.

After selecting training sites, the feature value distributions of each class type can be assessed using the EvaluateTrainingSites tool. In particular, the distribution of class values should ideally be non-overlapping in at least one feature dimension.

The k-NN algorithm is based on the calculation of distances in multi-dimensional space. Feature scaling is essential to the application of k-NN modelling, especially when the ranges of the features are different, for example, if they are measured in different units. Without scaling, features with larger ranges will have greater influence in computing the distances between points. The tool offers three options for feature-scaling (--scaling), including 'None', 'Normalize', and 'Standardize'. Normalization simply rescales each of the features onto a 0-1 range. This is a good option for most applications, but it is highly sensitive to outliers because it is determined by the range of the minimum and maximum values. Standardization rescales predictors using their means and standard deviations, transforming the data into z-scores. This is a better option than normalization when you know that the data contain outlier values; however, it does does assume that the feature data are somewhat normally distributed, or are at least symmetrical in distribution.

Because the k-NN algorithm calculates distances in feature-space, like many other related algorithms, it suffers from the curse of dimensionality. Distances become less meaningful in high-dimensional space because the vastness of these spaces means that distances between points are less significant (more similar). As such, if the predictor list includes insignificant or highly correlated variables, it is advisable to exclude these features during the model-building phase, or to use a dimension reduction technique such as PrincipalComponentAnalysis to transform the features into a smaller set of uncorrelated predictors.

For a video tutorial on how to use the KnnClassification tool, see this YouTube video.

Memory Usage:

The peak memory usage of this tool is approximately 8 bytes per grid cell × # predictors.

See Also: KnnRegression, RandomForestClassification, SvmClassification, ParallelepipedClassification, EvaluateTrainingSites

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters
--scalingScaling method for predictors. Options include 'None', 'Normalize', and 'Standardize'
-t, --trainingName of the input training site polygons/points shapefile
-f, --fieldName of the attribute containing class name data
-o, --outputName of the output raster file
-kk-parameter, which determines the number of nearest neighbours used
--clipPerform training data clipping to remove outlier pixels?
--test_proportionThe proportion of the dataset to include in the test split; default is 0.2

Python function:

wbt.knn_classification(
    inputs, 
    training, 
    field, 
    scaling="Normalize", 
    output=None, 
    k=5, 
    clip=True, 
    test_proportion=0.2, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=KnnClassification ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' ^
-p=training_sites.shp -f='LAND_COVER' -o=classified.tif -k=8 ^
--clip --test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 14/12/2021

Last Modified: 30/12/2021

KnnRegression

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

This tool performs a supervised k-nearest neighbour (k-NN) regression analysis using multiple predictor rasters (--inputs), or features, and training data (--training). It can be used to model the spatial distribution of continuous data, such as soil properties (e.g. percent sand/silt/clay). The training data take the form of an input vector Shapefile containing a set of points, for which the known outcome information is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space. The algorithm works by identifying a user-defined number (k, -k) of feature-space neighbours from the training set for each grid cell. The value that is then assigned to the grid cell in the output raster (--output) is then determined as the mean of the outcome variable among the set of neighbours. The user may optionally choose to weight neighbour outcome values in the averaging calculation, with weights determined by the inverse distance function (--weight). Note that the KnnClassification tool can be used to apply the k-NN method to the modelling of categorical data.

The tool splits the training data into two sets, one for training the model and one for testing the prediction. These test data are used to calculate the regression accuracy statistics, as well as to estimate the variable importance. The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, the tool behaves stochastically, and will result in a different model each time it is run.

Note that the output image parameter (--output) is optional. When unspecified, the tool will simply report the model accuracy statistics and variable importance, allowing the user to experiment with different parameter settings and input predictor raster combinations to optimize the model before applying it to model the outcome variable across the whole region defined by image data set.

The k-NN algorithm is based on the calculation of distances in multi-dimensional space. Feature scaling is essential to the application of k-NN modelling, especially when the ranges of the features are different, for example, if they are measured in different units. Without scaling, features with larger ranges will have greater influence in computing the distances between points. The tool offers three options for feature-scaling (--scaling), including 'None', 'Normalize', and 'Standardize'. Normalization simply rescales each of the features onto a 0-1 range. This is a good option for most applications, but it is highly sensitive to outliers because it is determined by the range of the minimum and maximum values. Standardization rescales predictors using their means and standard deviations, transforming the data into z-scores. This is a better option than normalization when you know that the data contain outlier values; however, it does does assume that the feature data are somewhat normally distributed, or are at least symmetrical in distribution.

Because the k-NN algorithm calculates distances in feature-space, like many other related algorithms, it suffers from the curse of dimensionality. Distances become less meaningful in high-dimensional space because the vastness of these spaces means that distances between points are less significant (more similar). As such, if the predictor list includes insignificant or highly correlated variables, it is advisable to exclude these features during the model-building phase, or to use a dimension reduction technique such as PrincipalComponentAnalysis to transform the features into a smaller set of uncorrelated predictors.

Memory Usage:

The peak memory usage of this tool is approximately 8 bytes per grid cell × # predictors.

See Also: KnnClassification, RandomForestRegression, SvmRegression, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters
--scalingScaling method for predictors. Options include 'None', 'Normalize', and 'Standardize'
-t, --trainingName of the input training site points Shapefile
-f, --fieldName of the attribute containing response variable name data
-o, --outputName of the output raster file
-kk-parameter, which determines the number of nearest neighbours used
--weightUse distance weighting?
--test_proportionThe proportion of the dataset to include in the test split; default is 0.2

Python function:

wbt.knn_regression(
    inputs, 
    training, 
    field, 
    scaling="Normalize", 
    output=None, 
    k=5, 
    weight=True, 
    test_proportion=0.2, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=KnnRegression ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' ^
-p=training_sites.shp -f='PCT_SAND' -o=PercentSand.tif -k=8 ^
--weight --test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 14/12/2021

Last Modified: 21/01/2022

LogisticRegression

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

This tool performs a logistic regression analysis using multiple predictor rasters (--inputs), or features, and training data (--training). Logistic regression is a type of linear statistical classifier that in its basic form uses a logistic function to model a binary outcome variable, although the implementation used by this tool can handle multi-class dependent variables. This tool can be used to model the spatial distribution of class data, such as land-cover type, soil class, or vegetation type.

The training data take the form of an input vector Shapefile containing a set of points or polygons, for which the known class information is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space.

The tool splits the training data into two sets, one for training the model and one for testing the prediction. These test data are used to calculate the classification accuracy stats, as well as to estimate the variable importance. The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, the tool behaves stochastically, and will result in a different model each time it is run.

Note that the output image parameter (--output) is optional. When unspecified, the tool will simply report the model accuracy statistics and variable importance, allowing the user to experiment with different parameter settings and input predictor raster combinations to optimize the model before applying it to model the outcome variable across the whole region defined by image data set.

The user may opt for feature scaling, which can be important when the ranges of the features are different, for example, if they are measured in different units. Without scaling, features with larger ranges will have greater influence in computing the distances between points. The tool offers three options for feature-scaling (--scaling), including 'None', 'Normalize', and 'Standardize'. Normalization simply rescales each of the features onto a 0-1 range. This is a good option for most applications, but it is highly sensitive to outliers because it is determined by the range of the minimum and maximum values. Standardization rescales predictors using their means and standard deviations, transforming the data into z-scores. This is a better option than normalization when you know that the data contain outlier values; however, it does does assume that the feature data are somewhat normally distributed, or are at least symmetrical in distribution.

Because the logistic regression calculates distances in feature-space, like many other related algorithms, it suffers from the curse of dimensionality. Distances become less meaningful in high-dimensional space because the vastness of these spaces means that distances between points are less significant (more similar). As such, if the predictor list includes insignificant or highly correlated variables, it is advisable to exclude these features during the model-building phase, or to use a dimension reduction technique such as PrincipalComponentAnalysis to transform the features into a smaller set of uncorrelated predictors.

Memory Usage:

The peak memory usage of this tool is approximately 8 bytes per grid cell × # predictors.

See Also: SvmClassification, RandomForestClassification, KnnClassification, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters
--scalingScaling method for predictors. Options include 'None', 'Normalize', and 'Standardize'
-t, --trainingName of the input training site polygons/points shapefile
-f, --fieldName of the attribute containing class data
-o, --outputName of the output raster file
--test_proportionThe proportion of the dataset to include in the test split; default is 0.2

Python function:

wbt.logistic_regression(
    inputs, 
    training, 
    field, 
    scaling="Normalize", 
    output=None, 
    test_proportion=0.2, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LogisticRegression ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' ^
-p=training_sites.shp -f='SANDY' -o=classified.tif ^
--test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 02/01/2022

Last Modified: 02/01/2022

ModifiedKMeansClustering

This modified k-means algorithm is similar to that described by Mather and Koch (2011). The main difference between the traditional k-means and this technique is that the user does not need to specify the desired number of classes/clusters prior to running the tool. Instead, the algorithm initializes with a very liberal overestimate of the number of classes and then merges classes that have cluster centres that are separated by less than a user-defined threshold. The main difference between this algorithm and the ISODATA technique is that clusters can not be broken apart into two smaller clusters.

Reference:

Mather, P. M., & Koch, M. (2011). Computer processing of remotely-sensed images: an introduction. John Wiley & Sons.

See Also: KMeansClustering

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput raster file
--out_htmlOutput HTML report file
--start_clustersInitial number of clusters
--merge_distCluster merger distance
--max_iterationsMaximum number of iterations
--class_changeMinimum percent of cells changed between iterations before completion

Python function:

wbt.modified_k_means_clustering(
    inputs, 
    output, 
    out_html=None, 
    start_clusters=1000, 
    merge_dist=None, 
    max_iterations=10, 
    class_change=2.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ModifiedKMeansClustering -v ^
--wd='/path/to/data/' -i='image1.tif;image2.tif;image3.tif' ^
-o=output.tif --out_html=report.html --start_clusters=100 ^
--merge_dist=30.0 --max_iterations=25 --class_change=1.5 

Source code on GitHub

Author: Dr. John Lindsay

Created: 30/12/2017

Last Modified: 24/02/2019

RandomForestClassification

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

This tool performs a supervised random forest (RF) classification using multiple predictor rasters (--inputs), or features, and training data (--training). It can be used to model the spatial distribution of class data, such as land-cover type, soil class, or vegetation type. The training data take the form of an input vector Shapefile containing a set of points or polygons, for which the known class information is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space. Random forest is an ensemble learning method that works by creating a large number (--n_trees) of decision trees and using a majority vote to determine estimated class values. Individual trees are created using a random sub-set of predictors. This ensemble approach overcomes the tendency of individual decision trees to overfit the training data. As such, the RF method is a widely and successfully applied machine-learning method in many domains. Note that the RandomForestRegression tool can be used to apply the RF method to the modelling of continuous data.

The user must specify the splitting criteria (--split_criterion) used in training the decision trees. Options for this parameter include 'Gini', 'Entropy', and 'ClassificationError'. The model can also be adjusted based on each of the number of trees (--n_trees), the minimum number of samples required to be at a leaf node (--min_samples_leaf), and the minimum number of samples required to split an internal node (--min_samples_split) parameters.

The tool splits the training data into two sets, one for training the classifier and one for testing the model. These test data are used to calculate the overall accuracy and Cohen's kappa index of agreement, as well as to estimate the variable importance. The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, and the random selection of features used in decision tree creation, the tool is inherently stochastic, and will result in a different model each time it is run.

Note that the output image parameter (--output) is optional. When unspecified, the tool will simply report the model accuracy statistics and variable importance, allowing the user to experiment with different parameter settings and input predictor raster combinations to optimize the model before applying it to classify the whole image data set.

Like all supervised classification methods, this technique relies heavily on proper selection of training data. Training sites are exemplar areas/points of known and representative class value (e.g. land cover type). The algorithm determines the feature signatures of the pixels within each training area. In selecting training sites, care should be taken to ensure that they cover the full range of variability within each class. Otherwise the classification accuracy will be impacted. If possible, multiple training sites should be selected for each class. It is also advisable to avoid areas near the edges of class objects (e.g. land-cover patches), where mixed pixels may impact the purity of training site values.

After selecting training sites, the feature value distributions of each class type can be assessed using the EvaluateTrainingSites tool. In particular, the distribution of class values should ideally be non-overlapping in at least one feature dimension.

RF, like decision trees, does not require feature scaling. That is, unlike the k-NN algorithm and other methods that are based on the calculation of distances in multi-dimensional space, there is no need to rescale the predictors onto a common scale prior to RF analysis. Because individual trees do not use the full set of predictors, RF is also more robust against the curse of dimensionality than many other machine learning methods. Nonetheless, there is still debate about whether or not it is advisable to use a large number of predictors with RF analysis and it may be better to exclude predictors that are highly correlated with others, or that do not contribute significantly to the model during the model-building phase. A dimension reduction technique such as PrincipalComponentAnalysis can be used to transform the features into a smaller set of uncorrelated predictors.

Memory Usage:

The peak memory usage of this tool is approximately 8 bytes per grid cell × # predictors.

See Also: RandomForestRegression, KnnClassification, SvmClassification, ParallelepipedClassification, EvaluateTrainingSites, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters
-t, --trainingName of the input training site polygons/points shapefile
-f, --fieldName of the attribute containing class data
-o, --outputName of the output raster file
--split_criterionSplit criterion to use when building a tree. Options include 'Gini', 'Entropy', and 'ClassificationError'
--n_treesThe number of trees in the forest
--min_samples_leafThe minimum number of samples required to be at a leaf node
--min_samples_splitThe minimum number of samples required to split an internal node
--test_proportionThe proportion of the dataset to include in the test split; default is 0.2

Python function:

wbt.random_forest_classification(
    inputs, 
    training, 
    field, 
    output=None, 
    split_criterion="Gini", 
    n_trees=500, 
    min_samples_leaf=1, 
    min_samples_split=2, 
    test_proportion=0.2, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RandomForestClassification ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' ^
-p=training_sites.shp -f='LAND_COVER' -o=classified.tif ^
--n_trees=100 --test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 17/12/2021

Last Modified: 31/12/2021

RandomForestClassificationFit

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

This tool builds a supervised random forest (RF) classification model using multiple predictor rasters (--inputs), or features, and training data (--training). This tool is intended to be paired with the RandomForestClassificationPrediction tool, where users first build the model by fitting and random forest to training data (RandomForestClassificationFit) and subsequently use the output model (--model) to predict a spatial distribution (RandomForestClassificationPredict). The model created by the RandomForestClassificationFit tool is saved to a generic binary formatted file with a *.dat extension, which then serves as the input to the RandomForestClassificationPredict tool. These two tools are used to model the spatial distribution of class data, such as land-cover type, soil class, or vegetation type. The training data take the form of an input vector Shapefile containing a set of points or polygons, for which the known class information is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space.

Note: it is very important that the order of feature rasters is the same for both fitting the model and using the model for prediction. It is possible to use a model fitted to one data set to make preditions for another data set, however, the set of feature reasters specified to the prediction tool must be input in the same sequence used for building the model. For example, one may train a RF classifer on one set of multi-spectral satellite imagery and then apply that model to classify a different imagery scene, but the image band sequence must be the same for the Fit/Predict tools otherwise inaccurate predictions will result.

Random forest is an ensemble learning method that works by creating a large number (--n_trees) of decision trees and using a majority vote to determine estimated class values. Individual trees are created using a random sub-set of predictors. This ensemble approach overcomes the tendency of individual decision trees to overfit the training data. As such, the RF method is a widely and successfully applied machine-learning method in many domains. Note that the RandomForestRegressionFit tool (paired with RandomForestRegressionPredict) can be used to apply the RF method to the modelling of continuous data.

The user must specify the splitting criteria (--split_criterion) used in training the decision trees. Options for this parameter include 'Gini', 'Entropy', and 'ClassificationError'. The model can also be adjusted based on each of the number of trees (--n_trees), the minimum number of samples required to be at a leaf node (--min_samples_leaf), and the minimum number of samples required to split an internal node (--min_samples_split) parameters.

The tool splits the training data into two sets, one for training the classifier and one for testing the model. These test data are used to calculate the overall accuracy and Cohen's kappa index of agreement, as well as to estimate the variable importance. The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, and the random selection of features used in decision tree creation, the tool is inherently stochastic, and will result in a different model each time it is run.

Like all supervised classification methods, this technique relies heavily on proper selection of training data. Training sites are exemplar areas/points of known and representative class value (e.g. land cover type). The training data input file (--training) can consist of either vector points or polygons, for whcih the attribute table contains one field with the known class value. The algorithm determines the feature signatures of the pixels within each training area/point. In selecting training sites, care should be taken to ensure that they cover the full range of variability within each class. Otherwise the classification accuracy will be impacted. If possible, multiple training sites should be selected for each class. It is also advisable to avoid areas near the edges of class objects (e.g. land-cover patches), where mixed pixels may impact the purity of training site values.

After selecting training sites, the feature value distributions of each class type can be assessed using the EvaluateTrainingSites tool. In particular, the distribution of class values should ideally be non-overlapping in at least one feature dimension.

RF, like decision trees, does not require feature scaling. That is, unlike the k-NN algorithm and other methods that are based on the calculation of distances in multi-dimensional space, there is no need to rescale the predictors onto a common scale prior to RF analysis. Because individual trees do not use the full set of predictors, RF is also more robust against the curse of dimensionality than many other machine learning methods. Nonetheless, there is still debate about whether or not it is advisable to use a large number of predictors with RF analysis and it may be better to exclude predictors that are highly correlated with others, or that do not contribute significantly to the model during the model-building phase. A dimension reduction technique such as PrincipalComponentAnalysis can be used to transform the features into a smaller set of uncorrelated predictors.

Memory Usage: Depending on the size and number of input feature rasters, this tool may require substantial memory to run. Peak memory usage will be at least 8 × # grid cells × # of features.

See Also: RandomForestClassificationPredict, RandomForestRegressionFit, RandomForestRegressionPredict, KnnClassification, SvmClassification, ParallelepipedClassification, EvaluateTrainingSites, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters
-t, --trainingName of the input training site polygons/points shapefile
-f, --fieldName of the attribute containing class data
-m, --modelName of the output model file (*.dat)
--split_criterionSplit criterion to use when building a tree. Options include 'Gini', 'Entropy', and 'ClassificationError'
--n_treesThe number of trees in the forest
--min_samples_leafThe minimum number of samples required to be at a leaf node
--min_samples_splitThe minimum number of samples required to split an internal node
--test_proportionThe proportion of the dataset to include in the test split; default is 0.2

Python function:

wbt.random_forest_classification_fit(
    inputs, 
    training, 
    field, 
    model, 
    split_criterion="Gini", 
    n_trees=500, 
    min_samples_leaf=1, 
    min_samples_split=2, 
    test_proportion=0.2, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RandomForestClassificationFit ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' ^
-p=training_sites.shp -f='LAND_COVER' -o=classified.tif ^
--n_trees=100 --test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 15/05/2023

Last Modified: 15/05/2023

RandomForestClassificationPredict

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

This tool applies a pre-built random forest (RF) classification model trained using multiple predictor rasters (--inputs), or features, and training data (--training) to predict a spatial distribution. This tool is intended to be paired with the RandomForestClassificationFit tool, where users first build the model by fitting and random forest to training data (RandomForestClassificationFit) and subsequently use the output model (--model) to predict a spatial distribution (RandomForestClassificationPredict). The model created by the RandomForestClassificationFit tool is saved to a generic binary formatted file with a *.dat extension, which then serves as the input to the RandomForestClassificationPredict tool. These two tools are used to model the spatial distribution of class data, such as land-cover type, soil class, or vegetation type. The training data take the form of an input vector Shapefile containing a set of points or polygons, for which the known class information is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space.

Note: it is very important that the order of feature rasters is the same for both fitting the model and using the model for prediction. It is possible to use a model fitted to one data set to make preditions for another data set, however, the set of feature reasters specified to the prediction tool must be input in the same sequence used for building the model. For example, one may train a RF classifer on one set of multi-spectral satellite imagery and then apply that model to classify a different imagery scene, but the image band sequence must be the same for the Fit/Predict tools otherwise inaccurate predictions will result.

Random forest is an ensemble learning method that works by creating a large number (--n_trees) of decision trees and using a majority vote to determine estimated class values. Individual trees are created using a random sub-set of predictors. This ensemble approach overcomes the tendency of individual decision trees to overfit the training data. As such, the RF method is a widely and successfully applied machine-learning method in many domains. Note that the RandomForestRegressionFit tool (paired with RandomForestRegressionPredict) can be used to apply the RF method to the modelling of continuous data.

The user must specify the splitting criteria (--split_criterion) used in training the decision trees. Options for this parameter include 'Gini', 'Entropy', and 'ClassificationError'. The model can also be adjusted based on each of the number of trees (--n_trees), the minimum number of samples required to be at a leaf node (--min_samples_leaf), and the minimum number of samples required to split an internal node (--min_samples_split) parameters.

The tool splits the training data into two sets, one for training the classifier and one for testing the model. These test data are used to calculate the overall accuracy and Cohen's kappa index of agreement, as well as to estimate the variable importance. The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, and the random selection of features used in decision tree creation, the tool is inherently stochastic, and will result in a different model each time it is run.

Like all supervised classification methods, this technique relies heavily on proper selection of training data. Training sites are exemplar areas/points of known and representative class value (e.g. land cover type). The training data input file (--training) can consist of either vector points or polygons, for whcih the attribute table contains one field with the known class value. The algorithm determines the feature signatures of the pixels within each training area/point. In selecting training sites, care should be taken to ensure that they cover the full range of variability within each class. Otherwise the classification accuracy will be impacted. If possible, multiple training sites should be selected for each class. It is also advisable to avoid areas near the edges of class objects (e.g. land-cover patches), where mixed pixels may impact the purity of training site values.

After selecting training sites, the feature value distributions of each class type can be assessed using the EvaluateTrainingSites tool. In particular, the distribution of class values should ideally be non-overlapping in at least one feature dimension.

RF, like decision trees, does not require feature scaling. That is, unlike the k-NN algorithm and other methods that are based on the calculation of distances in multi-dimensional space, there is no need to rescale the predictors onto a common scale prior to RF analysis. Because individual trees do not use the full set of predictors, RF is also more robust against the curse of dimensionality than many other machine learning methods. Nonetheless, there is still debate about whether or not it is advisable to use a large number of predictors with RF analysis and it may be better to exclude predictors that are highly correlated with others, or that do not contribute significantly to the model during the model-building phase. A dimension reduction technique such as PrincipalComponentAnalysis can be used to transform the features into a smaller set of uncorrelated predictors.

Memory Usage: Depending on the size and number of input feature rasters, this tool may require substantial memory to run. Peak memory usage will be at least 8 × # grid cells × # of features.

See Also: RandomForestClassificationFit, RandomForestRegressionFit, RandomForestRegressionPredict, KnnClassification, SvmClassification, ParallelepipedClassification, EvaluateTrainingSites, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters. Raster order is important and must follow that used to fit the model
-m, --modelName of the previously trained random forest model (*.dat)
-o, --outputName of the output raster file

Python function:

wbt.random_forest_classification_predict(
    inputs, 
    model, 
    output, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RandomForestClassificationFit ^
-i='dem.tif; slope.tif; DEVmax.tif; tan_curv.tif' ^
-t=field_sites.shp -f='PCT_SAND' -o=PercentSand.dat ^
--n_trees=100 --test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 15/05/2023

Last Modified: 15/05/2023

RandomForestRegression

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

This tool performs a supervised random forest (RF) regression analysis using multiple predictor rasters (--inputs), or features, and training data (--training). It can be used to model the spatial distribution of continuous data, such as soil properties (e.g. percent sand/silt/clay). The training data take the form of an input vector Shapefile containing a set of points, for which the known outcome information is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space. Random forest is an ensemble learning method that works by creating a large number (--n_trees) of decision trees and using an averaging of each tree to determine estimated outcome values. Individual trees are created using a random sub-set of predictors. This ensemble approach overcomes the tendency of individual decision trees to overfit the training data. As such, the RF method is a widely and successfully applied machine-learning method in many domains. Note that the RandomForestClassification tool can be used to apply the RF method to the modelling of categorical (class) data.

Users must specify the number of trees (--n_trees), the minimum number of samples required to be at a leaf node (--min_samples_leaf), and the minimum number of samples required to split an internal node (--min_samples_split) parameters, which determine the characteristics of the resulting model.

The tool splits the training data into two sets, one for training the model and one for testing the prediction. These test data are used to calculate the regression accuracy statistics, as well as to estimate the variable importance. The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, as well as the randomness involved in establishing the individual decision trees, the tool in inherently stochastic, and will result in a different model each time it is run.

Note that the output image parameter (--output) is optional. When unspecified, the tool will simply report the model accuracy statistics and variable importance, allowing the user to experiment with different parameter settings and input predictor raster combinations to optimize the model before applying it to model the outcome variable across the whole region defined by image data set.

RF, like decision trees, does not require feature scaling. That is, unlike the k-NN algorithm and other methods that are based on the calculation of distances in multi-dimensional space, there is no need to rescale the predictors onto a common scale prior to RF analysis. Because individual trees do not use the full set of predictors, RF is also more robust against the curse of dimensionality than many other machine learning methods. Nonetheless, there is still debate about whether or not it is advisable to use a large number of predictors with RF analysis and it may be better to exclude predictors that are highly correlated with others, or that do not contribute significantly to the model during the model-building phase. A dimension reduction technique such as PrincipalComponentAnalysis can be used to transform the features into a smaller set of uncorrelated predictors.

For a video tutorial on how to use the RandomForestRegression tool, see this YouTube video.

Memory Usage:

The peak memory usage of this tool is approximately 8 bytes per grid cell × # predictors.

See Also: RandomForestClassification, KnnRegression, SvmRegression, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters
-t, --trainingName of the input training site points shapefile
-f, --fieldName of the attribute containing response variable name data
-o, --outputName of the output raster file. This parameter is optional. When unspecified, the tool will only build the model. When specified, the tool will use the built model and predictor rasters to perform a spatial prediction
--n_treesThe number of trees in the forest
--min_samples_leafThe minimum number of samples required to be at a leaf node
--min_samples_splitThe minimum number of samples required to split an internal node
--test_proportionThe proportion of the dataset to include in the test split; default is 0.2

Python function:

wbt.random_forest_regression(
    inputs, 
    training, 
    field, 
    output=None, 
    n_trees=100, 
    min_samples_leaf=1, 
    min_samples_split=2, 
    test_proportion=0.2, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RandomForestRegression ^
-i='dem.tif; slope.tif; DEVmax.tif; tan_curv.tif' ^
-t=field_sites.shp -f='PCT_SAND' -o=PercentSand.tif ^
--n_trees=100 --test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 16/12/2021

Last Modified: 21/01/2022

RandomForestRegressionFit

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

This tool performs a supervised random forest (RF) regression analysis using multiple predictor rasters (--inputs), or features, and training data (--training). This tool is intended to be paired with the RandomForestRegressionPredict tool, where users first build the model by fitting and random forest to training data (RandomForestRegressionFit) and subsequently use the output model (--model) to predict a spatial distribution (RandomForestRegressionPredict). The model created by the RandomForestRegressionFit tool is saved to a generic binary formatted file with a *.dat extension, which then serves as the input to the RandomForestRegressionPredict tool. These two tools can be used to model the spatial distribution of continuous data, such as soil properties (e.g. percent sand/silt/clay). The training data take the form of an input vector Shapefile containing a set of points, for which the known outcome information is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space.

Note: it is very important that the order of feature rasters is the same for both fitting the model and using the model for prediction. It is possible to use a model fitted to one data set to make preditions for another data set, however, the set of feature reasters specified to the prediction tool must be input in the same sequence used for building the model. For example, one may train a RF regressor on one set of land-surface parameters and then apply that model to predict the spatial distribution of a soil property on a land-surface parameter stack derived for a different landscape, but the image band sequence must be the same for the Fit/Predict tools otherwise inaccurate predictions will result.

Random forest is an ensemble learning method that works by creating a large number (--n_trees) of decision trees and using an averaging of each tree to determine estimated outcome values. Individual trees are created using a random sub-set of predictors. This ensemble approach overcomes the tendency of individual decision trees to overfit the training data. As such, the RF method is a widely and successfully applied machine-learning method in many domains. Note that the RandomForestClassification tool can be used to apply the RF method to the modelling of categorical (class) data.

Users must specify the number of trees (--n_trees), the minimum number of samples required to be at a leaf node (--min_samples_leaf), and the minimum number of samples required to split an internal node (--min_samples_split) parameters, which determine the characteristics of the resulting model.

The tool splits the training data into two sets, one for training the model and one for testing the prediction. These test data are used to calculate the regression accuracy statistics, as well as to estimate the variable importance. The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, as well as the randomness involved in establishing the individual decision trees, the tool in inherently stochastic, and will result in a different model each time it is run.

RF, like decision trees, does not require feature scaling. That is, unlike the k-NN algorithm and other methods that are based on the calculation of distances in multi-dimensional space, there is no need to rescale the predictors onto a common scale prior to RF analysis. Because individual trees do not use the full set of predictors, RF is also more robust against the curse of dimensionality than many other machine learning methods. Nonetheless, there is still debate about whether or not it is advisable to use a large number of predictors with RF analysis and it may be better to exclude predictors that are highly correlated with others, or that do not contribute significantly to the model during the model-building phase. A dimension reduction technique such as PrincipalComponentAnalysis can be used to transform the features into a smaller set of uncorrelated predictors.

For a video tutorial on how to use the RandomForestRegression tool, see this YouTube video.

Memory Usage: Depending on the size and number of input feature rasters, this tool may require substantial memory to run. Peak memory usage will be at least 8 × # grid cells × # of features.

See Also: RandomForestRegressionPredict, RandomForestClassificationFit, RandomForestClassificationPredict, KnnRegression, SvmRegression, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters
-t, --trainingName of the input training site points Shapefile
-f, --fieldName of the attribute containing response variable name data
-o, --outputName of the output model file
--n_treesThe number of trees in the forest
--min_samples_leafThe minimum number of samples required to be at a leaf node
--min_samples_splitThe minimum number of samples required to split an internal node
--test_proportionThe proportion of the dataset to include in the test split; default is 0.2

Python function:

wbt.random_forest_regression_fit(
    inputs, 
    training, 
    field, 
    output, 
    n_trees=100, 
    min_samples_leaf=1, 
    min_samples_split=2, 
    test_proportion=0.2, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RandomForestRegressionFit ^
-i='dem.tif; slope.tif; DEVmax.tif; tan_curv.tif' ^
-t=field_sites.shp -f='PCT_SAND' -o=PercentSand.dat ^
--n_trees=100 --test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 15/05/2023

Last Modified: 15/05/2023

RandomForestRegressionPredict

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

This tool performs a pre-built random forest (RF) regression analysis using multiple predictor rasters (--inputs), or features, and training data (--training), to predict a continuous spatial distribution. This tool is intended to be paired with the RandomForestRegressionFit tool, where users first build the model by fitting and random forest to training data (RandomForestRegressionFit) and subsequently use the output model (--model) to predict a spatial distribution (RandomForestRegressionPredict). The model created by the RandomForestRegressionFit tool is saved to a generic binary formatted file with a *.dat extension, which then serves as the input to the RandomForestRegressionPredict tool. These two tools can be used to model the spatial distribution of continuous data, such as soil properties (e.g. percent sand/silt/clay). The training data take the form of an input vector Shapefile containing a set of points, for which the known outcome information is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space.

Note: it is very important that the order of feature rasters is the same for both fitting the model and using the model for prediction. It is possible to use a model fitted to one data set to make preditions for another data set, however, the set of feature reasters specified to the prediction tool must be input in the same sequence used for building the model. For example, one may train a RF regressor on one set of land-surface parameters and then apply that model to predict the spatial distribution of a soil property on a land-surface parameter stack derived for a different landscape, but the image band sequence must be the same for the Fit/Predict tools otherwise inaccurate predictions will result.

Random forest is an ensemble learning method that works by creating a large number (--n_trees) of decision trees and using an averaging of each tree to determine estimated outcome values. Individual trees are created using a random sub-set of predictors. This ensemble approach overcomes the tendency of individual decision trees to overfit the training data. As such, the RF method is a widely and successfully applied machine-learning method in many domains. Note that the RandomForestClassification tool can be used to apply the RF method to the modelling of categorical (class) data.

Users must specify the number of trees (--n_trees), the minimum number of samples required to be at a leaf node (--min_samples_leaf), and the minimum number of samples required to split an internal node (--min_samples_split) parameters, which determine the characteristics of the resulting model.

The tool splits the training data into two sets, one for training the model and one for testing the prediction. These test data are used to calculate the regression accuracy statistics, as well as to estimate the variable importance. The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, as well as the randomness involved in establishing the individual decision trees, the tool in inherently stochastic, and will result in a different model each time it is run.

RF, like decision trees, does not require feature scaling. That is, unlike the k-NN algorithm and other methods that are based on the calculation of distances in multi-dimensional space, there is no need to rescale the predictors onto a common scale prior to RF analysis. Because individual trees do not use the full set of predictors, RF is also more robust against the curse of dimensionality than many other machine learning methods. Nonetheless, there is still debate about whether or not it is advisable to use a large number of predictors with RF analysis and it may be better to exclude predictors that are highly correlated with others, or that do not contribute significantly to the model during the model-building phase. A dimension reduction technique such as PrincipalComponentAnalysis can be used to transform the features into a smaller set of uncorrelated predictors.

For a video tutorial on how to use the RandomForestRegression tool, see this YouTube video.

Memory Usage: Depending on the size and number of input feature rasters, this tool may require substantial memory to run. Peak memory usage will be at least 8 × # grid cells × # of features.

See Also: RandomForestRegressionFit, RandomForestClassificationFit, RandomForestClassificationPredict, KnnRegression, SvmRegression, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters. Raster order is important and must follow that used to fit the model
-m, --modelName of the previously trained random forest model (*.dat)
-o, --outputName of the output raster file

Python function:

wbt.random_forest_regression_predict(
    inputs, 
    model, 
    output, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RandomForestRegressionFit ^
-i='dem.tif; slope.tif; DEVmax.tif; tan_curv.tif' ^
-t=field_sites.shp -f='PCT_SAND' -o=PercentSand.dat ^
--n_trees=100 --test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 15/05/2023

Last Modified: 15/05/2023

SvmClassification

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

This tool performs a support vector machine (SVM) binary classification using multiple predictor rasters (--inputs), or features, and training data (--training). SVMs are a common class of supervised learning algorithms widely applied in many problem domains. This tool can be used to model the spatial distribution of class data, such as land-cover type, soil class, or vegetation type. The training data take the form of an input vector Shapefile containing a set of points or polygons, for which the known class information is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space. Note that the SvmRegression tool can be used to apply the SVM method to the modelling of continuous data.

The user must specify the values of three parameters used in the development of the model, the c parameters (-c), gamma (--gamma), and the tolerance (--tolerance). The c-value is the regularization parameter used in model optimization. The gamma parameter defines the radial basis function (Gaussian) kernel parameter. The tolerance parameter controls the stopping condition used during model optimization.

The tool splits the training data into two sets, one for training the classifier and one for testing the classification. These test data are used to calculate the overall accuracy and Matthew correlation coefficient (MCC). The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, the tool behaves stochastically, and will result in a different model each time it is run.

Note that the output image parameter (--output) is optional. When unspecified, the tool will simply report the model accuracy statistics, allowing the user to experiment with different parameter settings and input predictor raster combinations to optimize the model before applying it to classify the whole image data set.

Like all supervised classification methods, this technique relies heavily on proper selection of training data. Training sites are exemplar areas/points of known and representative class value (e.g. land cover type). The algorithm determines the feature signatures of the pixels within each training area. In selecting training sites, care should be taken to ensure that they cover the full range of variability within each class. Otherwise the classification accuracy will be impacted. If possible, multiple training sites should be selected for each class. It is also advisable to avoid areas near the edges of class objects (e.g. land-cover patches), where mixed pixels may impact the purity of training site values.

After selecting training sites, the feature value distributions of each class type can be assessed using the EvaluateTrainingSites tool. In particular, the distribution of class values should ideally be non-overlapping in at least one feature dimension.

The SVM algorithm is based on the calculation of distances in multi-dimensional space. Feature scaling is essential to the application of SVM-based modelling, especially when the ranges of the features are different, for example, if they are measured in different units. Without scaling, features with larger ranges will have greater influence in computing the distances between points. The tool offers three options for feature-scaling (--scaling), including 'None', 'Normalize', and 'Standardize'. Normalization simply rescales each of the features onto a 0-1 range. This is a good option for most applications, but it is highly sensitive to outliers because it is determined by the range of the minimum and maximum values. Standardization rescales predictors using their means and standard deviations, transforming the data into z-scores. This is a better option than normalization when you know that the data contain outlier values; however, it does does assume that the feature data are somewhat normally distributed, or are at least symmetrical in distribution.

Because the SVM algorithm calculates distances in feature-space, like many other related algorithms, it suffers from the curse of dimensionality. Distances become less meaningful in high-dimensional space because the vastness of these spaces means that distances between points are less significant (more similar). As such, if the predictor list includes insignificant or highly correlated variables, it is advisable to exclude these features during the model-building phase, or to use a dimension reduction technique such as PrincipalComponentAnalysis to transform the features into a smaller set of uncorrelated predictors.

Memory Usage:

The peak memory usage of this tool is approximately 8 bytes per grid cell × # predictors.

See Also: RandomForestClassification, KnnClassification, ParallelepipedClassification, EvaluateTrainingSites, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters
--scalingScaling method for predictors. Options include 'None', 'Normalize', and 'Standardize'
-t, --trainingName of the input training site polygons/points Shapefile
-f, --fieldName of the attribute containing class data
-o, --outputName of the output raster file
-cc-value, the regularization parameter
--gammaGamma parameter used in setting the RBF (Gaussian) kernel function
--toleranceThe tolerance parameter used in determining the stopping condition
--test_proportionThe proportion of the dataset to include in the test split; default is 0.2

Python function:

wbt.svm_classification(
    inputs, 
    training, 
    field, 
    scaling="Normalize", 
    output=None, 
    c=200.0, 
    gamma=50.0, 
    tolerance=0.1, 
    test_proportion=0.2, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=SvmClassification ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' ^
--scaling='Normalize' -p=training_sites.shp -f='LAND_COVER' ^
-o=classified.tif --gamma=20.0 --tolerance=0.01 --c_pos=5000.0 ^
--c_neg=500.0 --test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 02/01/2022

Last Modified: 02/01/2022

SvmRegression

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

This tool performs a supervised support vector machine (SVM) regression analysis using multiple predictor rasters (--inputs), or features, and training data (--training). SVMs are a common class of supervised learning algorithms widely applied in many problem domains. This tool can be used to model the spatial distribution of continuous data, such as soil properties (e.g. percent sand/silt/clay). The training data take the form of an input vector Shapefile containing a set of points for which the known outcome data is contained within a field (--field) of the attribute table. Each grid cell defines a stack of feature values (one value for each input raster), which serves as a point within the multi-dimensional feature space. Note that the SvmClassification tool can be used to apply the SVM method to the modelling of categorical data.

The user must specify the c-value (-c), the regularization parameter used in model optimization, the epsilon-value (--eps), used in the development of the epsilon-SVM regression model, and the gamma-value (--gamma), which is used in defining the radial basis function (Gaussian) kernel parameter.

The tool splits the training data into two sets, one for training the model and one for testing the prediction. These test data are used to calculate the regression accuracy statistics, as well as to estimate the variable importance. The --test_proportion parameter is used to set the proportion of the input training data used in model testing. For example, if --test_proportion = 0.2, 20% of the training data will be set aside for testing, and this subset will be selected randomly. As a result of this random selection of test data, the tool behaves stochastically, and will result in a different model each time it is run.

Note that the output image parameter (--output) is optional. When unspecified, the tool will simply report the model accuracy statistics and variable importance, allowing the user to experiment with different parameter settings and input predictor raster combinations to optimize the model before applying it to model the outcome variable across the whole region defined by image data set.

The SVM algorithm is based on the calculation of distances in multi-dimensional space. Feature scaling is essential to the application of SVM modelling, especially when the ranges of the features are different, for example, if they are measured in different units. Without scaling, features with larger ranges will have greater influence in computing the distances between points. The tool offers three options for feature-scaling (--scaling), including 'None', 'Normalize', and 'Standardize'. Normalization simply rescales each of the features onto a 0-1 range. This is a good option for most applications, but it is highly sensitive to outliers because it is determined by the range of the minimum and maximum values. Standardization rescales predictors using their means and standard deviations, transforming the data into z-scores. This is a better option than normalization when you know that the data contain outlier values; however, it does does assume that the feature data are somewhat normally distributed, or are at least symmetrical in distribution.

Because the SVM algorithm calculates distances in feature-space, like many other related algorithms, it suffers from the curse of dimensionality. Distances become less meaningful in high-dimensional space because the vastness of these spaces means that distances between points are less significant (more similar). As such, if the predictor list includes insignificant or highly correlated variables, it is advisable to exclude these features during the model-building phase, or to use a dimension reduction technique such as PrincipalComponentAnalysis to transform the features into a smaller set of uncorrelated predictors.

Memory Usage:

The peak memory usage of this tool is approximately 8 bytes per grid cell × # predictors.

See Also: SvmClassification, RandomForestRegression, KnnRegression, PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsNames of the input predictor rasters
--scalingScaling method for predictors. Options include 'None', 'Normalize', and 'Standardize'
-t, --trainingName of the input training site points Shapefile
-f, --fieldName of the attribute containing class data
-o, --outputName of the output raster file
-cc-value, the regularization parameter
--epsEpsilon in the epsilon-SVR model
--gammaGamma parameter used in setting the RBF (Gaussian) kernel function
--test_proportionThe proportion of the dataset to include in the test split; default is 0.2

Python function:

wbt.svm_regression(
    inputs, 
    training, 
    field, 
    scaling="Normalize", 
    output=None, 
    c=50.0, 
    eps=10.0, 
    gamma=0.5, 
    test_proportion=0.2, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=SvmRegression ^
-i='band1.tif; band2.tif; band3.tif; band4.tif' ^
--scaling='Normalize' -p=training_sites.shp -f='SAND_PCT' ^
-o=PercentSand.tif -c=50.0 --eps=2.0 --gamma=20.0 ^
--test_proportion=0.1 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 31/12/2021

Last Modified: 21/01/2022

Math and Stats Tools

AbsoluteValue

This tool creates a new raster (--output) in which each grid cell is equal to the absolute value of the corresponding grid cell in an input raster (--input). The absolute value is a number that is equal in magnitude but is always positive.

See Also: Negate

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: July 5, 2017

Last Modified: 12/10/2018

Add

This tool creates a new raster in which each grid cell is equal to the addition of the corresponding grid cells in two input rasters or one input raster and a constant value. If two images are input, both images must possess the same number of rows and columns and spatial extent, as the analysis will be carried out on a cell-by-cell basis. If a grid cell contains a NoData value in either of the input images, the cell will be excluded from the analysis.

See Also: Subtract, Multiply, Divide, InPlaceAdd

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.add(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Add -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 24/01/2019

And

This tool is a Boolean AND operator, i.e. it works on True or False (1 and 0) values. Grid cells for which the first and second input rasters (--input1; --input2) have True values are assigned 1 in the output raster, otherwise grid cells are assigned a value of 0. All non-zero values in the input rasters are considered to be True, while all zero-valued grid cells are considered to be False. Grid cells containing NoData values in either of the input rasters will be assigned a NoData value in the output raster (--output).

See Also: Not, Or, Xor

Parameters:

FlagDescription
--input1Input raster file
--input2Input raster file
-o, --outputOutput raster file

Python function:

wbt.And(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=And -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 12/10/2018

Anova

This tool performs an Analysis of variance (ANOVA) test on the distribution of values in a raster (--input) among a group of features (--features). The ANOVA report is written to an output HTML report (--output).

Parameters:

FlagDescription
-i, --inputInput raster file
--featuresFeature definition (or class) raster
-o, --outputOutput HTML file

Python function:

wbt.anova(
    i, 
    features, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Anova -v --wd="/path/to/data/" ^
-i=data.tif --features=classes.tif -o=anova.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 23/09/2017

Last Modified: 12/10/2018

ArcCos

This tool creates a new raster (--output) in which each grid cell is equal to the inverse cosine of the corresponding grid cell in an input raster (--input). The output raster will contain angular data measured in radian, in the range [0, π] or NoData if the number is outside the range [-1, 1]. If desired, you can convert radians to degrees using the ToDegrees tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: ArcSin, ArcTan, ToDegrees

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 12/10/2018

ArcSin

This tool creates a new raster (--output) in which each grid cell is equal to the inverse sine of the corresponding grid cell in an input raster (--input). The output raster will contain angular data measured in radian, in the range [-π/2, π/2] or NoData if the number is outside the range [-1, 1]. If desired, you can convert radians to degrees using the ToDegrees tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: ArcCos, ArcTan, ToDegrees

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 12/10/2018

ArcTan

This tool creates a new raster (--output) in which each grid cell is equal to the inverse tangent of the corresponding grid cell in an input raster (--input). The output raster will contain angular data measured in radian, in the range [-π/2, π/2] or NoData if the number is outside the range [-1, 1]. If desired, you can convert radians to degrees using the ToDegrees tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: ArcCos, ArcTan, Atan2, ToDegrees

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 12/10/2018

Arcosh

This tool creates a new raster (--output) in which each grid cell is equal to the inverse hyperbolic cosine (arcosh) of the corresponding grid cell in an input raster (--input). The output raster will contain angular data measured in radian, in the range [0, π] or NoData if the number is outside the range [-1, 1]. If desired, you can convert radians to degrees using the ToDegrees tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Arsinh, Artanh, ToDegrees

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/10/2019

Last Modified: 26/10/2019

Arsinh

This tool creates a new raster (--output) in which each grid cell is equal to the inverse hyperbolic sine (arsinh) of the corresponding grid cell in an input raster (--input). The output raster will contain angular data measured in radian, in the range [-π/2, π/2] or NoData if the number is outside the range [-1, 1]. If desired, you can convert radians to degrees using the ToDegrees tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Arcosh, Artanh, ToDegrees

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/10/2019

Last Modified: 26/10/2019

Artanh

This tool creates a new raster (--output) in which each grid cell is equal to the inverse hyperbolic tangent (artanh) of the corresponding grid cell in an input raster (--input). The output raster will contain angular data measured in radian, in the range [-π/2, π/2] or NoData if the number is outside the range [-1, 1]. If desired, you can convert radians to degrees using the ToDegrees tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Arcosh, Arsinh, ToDegrees

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/10/2019

Last Modified: 26/10/2019

Atan2

This tool creates a new raster (--output) in which each grid cell is equal to the four quadrant arctangent of an y (--input_y) and x (--input_x) inputs, measured in radians. Inputs may be either rasters or constant values. The output raster will contain angular data measured in radian, in the range:

x = 0, y = 0: 0
x >= 0: arctan(y/x) -> [-π/2, π/2]
y >= 0: arctan(y/x) + π -> (π/2, π]
y < 0: arctan(y/x) - π -> (-π, -π/2)

If desired, you can convert radians to degrees using the ToDegrees tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: ArcCos, ArcTan, Atan2, ToDegrees

Parameters:

FlagDescription
--input_yInput y raster file or constant value (rise)
--input_xInput x raster file or constant value (run)
-o, --outputOutput raster file

Python function:

wbt.atan2(
    input_y, 
    input_x, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Atan2 -v --wd="/path/to/data/" ^
--input_y='in1.tif' --input_x='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 12/10/2018

AttributeCorrelation

This tool can be used to estimate the Pearson product-moment correlation coefficient (r) for each pair among a group of attributes associated with the database file of a shapefile. The r-value is a measure of the linear association in the variation of the attributes. The coefficient ranges from -1, indicated a perfect negative linear association, to 1, indicated a perfect positive linear association. An r-value of 0 indicates no correlation between the test variables.

Notice that this index is a measure of the linear association; two variables may be strongly related by a non-linear association (e.g. a power function curve) which will lead to an apparent weak association based on the Pearson coefficient. In fact, non-linear associations are very common among spatial variables, e.g. terrain indices such as slope and contributing area. In such cases, it is advisable that the input images are transformed prior to the estimation of the Pearson coefficient, or that an alternative, non-parametric statistic be used, e.g. the Spearman rank correlation coefficient.

The user must specify the name of the input vector Shapefile (--input). Correlations will be calculated for each pair of numerical attributes contained within the input file's attribute table and presented in a correlation matrix HMTL output (--output).

See Also: ImageCorrelation, AttributeScattergram, AttributeHistogram

Parameters:

FlagDescription
-i, --inputInput vector file
-o, --outputOutput HTML file (default name will be based on input file if unspecified)

Python function:

wbt.attribute_correlation(
    i, 
    output=None, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 29/04/2018

Last Modified: 12/10/2018

AttributeCorrelationNeighbourhoodAnalysis

This tool can be used to perform nieghbourhood-based (i.e. using roving search windows applied to each grid cell) correlation analysis on two continuous attributes (--field1 and --field2) of an input vector (--input). The tool outputs correlation value and a significance (p-value) fields (CORREL and PVALUE) to the input vector's attribute table. Additionally,the user must specify the size of the search window (--filter) and the correlation statistic (--stat). Options for the correlation statistic include pearson, kendall, and spearman. Notice that Pearson's r is the most computationally efficient of the three correlation metrics but is unsuitable when the input distributions are non-linearly associated, in which case, either Spearman's Rho or Kendall's tau-b correlations are more suited. Both Spearman and Kendall correlations evaluate monotonic associations without assuming linearity in the relation. Kendall's tau-b is by far the most computationally expensive of the three statistics and may not be suitable to larger sized search windows.

See Also: AttributeCorrelation, ImageCorrelationNeighbourhoodAnalysis

Parameters:

FlagDescription
-i, --inputInput vector file
--field1First input field name (dependent variable) in attribute table
--field2Second input field name (independent variable) in attribute table
--radiusSearch Radius (in map units)
--min_pointsMinimum number of points
--statCorrelation type; one of 'pearson' (default) and 'spearman'

Python function:

wbt.attribute_correlation_neighbourhood_analysis(
    i, 
    field1, 
    field2, 
    radius=None, 
    min_points=None, 
    stat="pearson", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AttributeCorrelationNeighbourhoodAnalysis ^
-v --wd="/path/to/data/" -i=input.shp --field1=DEPEND ^
--field2=INDEPEND --radius=4.0 --min_points=3 ^
--stat="spearman" 

Source code on GitHub

Author: Simon Gudim and Dr. John Lindsay

Created: 19/12/2019

Last Modified: 10/01/2020

AttributeHistogram

This tool can be used to create a histogram, which is a graph displaying the frequency distribution of data, for the values contained in a field of an input vector's attribute table. The user must specify the name of an input vector (--input) and the name of one of the fields (--field) contained in the associated attribute table. The tool output (--output) is an HTML formatted histogram analysis report. If the specified field is non-numerical, the tool will produce a bar-chart of class frequency, similar to the tabular output of the ListUniqueValues tool.

See Also: ListUniqueValues, RasterHistogram

Parameters:

FlagDescription
-i, --inputInput vector file
--fieldInput field name in attribute table
-o, --outputOutput HTML file (default name will be based on input file if unspecified)

Python function:

wbt.attribute_histogram(
    i, 
    field, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AttributeHistogram -v ^
--wd="/path/to/data/" -i=lakes.shp --field=HEIGHT ^
-o=outfile.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/04/2018

Last Modified: 12/10/2018

AttributeScattergram

This tool can be used to create a scattergram for two numerical fields (--fieldx and --fieldy) contained within an input vector's attribute table (--input). The user must specify the name of an input shapefile and the name of two of the fields contained it the associated attribute table. The tool output (--output) is an HTML formatted report containing a graphical scattergram plot.

See Also: AttributeHistogram, AttributeCorrelation

Parameters:

FlagDescription
-i, --inputInput raster file
--fieldxInput field name in attribute table for the x-axis
--fieldyInput field name in attribute table for the y-axis
-o, --outputOutput HTML file (default name will be based on input file if unspecified)
--trendlineDraw the trendline

Python function:

wbt.attribute_scattergram(
    i, 
    fieldx, 
    fieldy, 
    output, 
    trendline=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AttributeScattergram -v ^
--wd="/path/to/data/" -i=lakes.shp --fieldx=HEIGHT ^
--fieldy=area -o=outfile.html --trendline 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/04/2018

Last Modified: 18/10/2019

Ceil

This tool performs a ceiling (ceil) operation on the values in an input raster (--input) to the nearest integer value. The ceil function calculates the smallest integer greater than or equal to the input value (e.g. ceil(0.5) = 1, ceil(-4.5) = -5). The output raster (--output) will be of an I32 data type.

See Also: Round, Floor, Truncate

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 26/10/2019

ConditionalEvaluation

The ConditionalEvaluation tool can be used to perform an if-then-else style conditional evaluation on a raster image on a cell-to-cell basis. The user specifies the names of an input raster image (--input) and an output raster (--output), along with a conditional statement (--statement). The grid cell values in the output image will be determined by the TRUE and FALSE values and conditional statement. The conditional statement is a logical expression that must evaluate to either a Boolean, i.e. TRUE or FALSE. Then depending on how this statement evaluates for each grid cell, the TRUE or FALSE values will be assigned to the corresponding grid cells of the output raster. The TRUE or FALSE values may take the form of either a constant numerical value or a raster image (which may be the same image as the input). These are specified by the --true and --false parameters, which can be either a file name pointing to existing rasters, or numerical values.

The conditional statement is a single-line logical condition. In addition to the common comparison and logical operators, i.e. < > <= >= == (EQUAL TO) != (NOT EQUAL TO) || (OR) && (AND), conditional statements may contain a number of valid mathematical functions. For example:

* log(base=10, val) -- Logarithm with optional 'base' as first argument.
If not provided, 'base' defaults to '10'.
Example: log(100) + log(e(), 100)

* e()  -- Euler's number (2.718281828459045)
* pi() -- π (3.141592653589793)

* int(val)
* ceil(val)
* floor(val)
* round(modulus=1, val) -- Round with optional 'modulus' as first argument.
Example: round(1.23456) == 1 && round(0.001, 1.23456) == 1.235

* abs(val)
* sign(val)

* min(val, ...) -- Example: min(1, -2, 3, -4) == -4
* max(val, ...) -- Example: max(1, -2, 3, -4) == 3

* sin(radians)    * asin(val)
* cos(radians)    * acos(val)
* tan(radians)    * atan(val)
* sinh(val)       * asinh(val)
* cosh(val)       * acosh(val)
* tanh(val)       * atanh(val)

Notice that the constants Pi and e must be specified as functions, pi() and e(). A number of global variables are also available to build conditional statements. These include the following:

Special Variable Names For Use In Conditional Statements:

NameDescription
valueThe grid cell value.
nodataThe input raster's NoData value.
nullSame as nodata.
minvalueThe input raster's minimum value.
maxvalueThe input raster's maximum value.
rowsThe input raster's number of rows.
columnsThe input raster's number of columns.
rowThe grid cell's row number.
columnThe grid cell's column number.
rowyThe row's y-coordinate.
columnxThe column's x-coordinate.
northThe input raster's northern coordinate.
southThe input raster's southern coordinate.
eastThe input raster's eastern coordinate.
westThe input raster's western coordinate.
cellsizexThe input raster's grid resolution in the x-direction.
cellsizeyThe input raster's grid resolution in the y-direction.
cellsizeThe input raster's average grid resolution.

The special variable names are case-sensitive. Each of the special variable names can also be used as valid TRUE or FALSE constant values.

The following are examples of valid conditional statements:

value != 300.0

row > (rows / 2)

value >= (minvalue + 35.0)

(value >= 25.0) && (value <= 75.0)

tan(value * pi() / 180.0) > 1.0

value == nodata

Any grid cell in the input raster containing the NoData value will be assigned NoData in the output raster, unless a NoData grid cell value allows the conditional statement to evaluate to True (i.e. the conditional statement includes the NoData value), in which case the True value will be assigned to the output.

Parameters:

FlagDescription
-i, --inputName of the input raster file
--statementConditional statement e.g. value > 35.0. This statement must be a valid Rust statement
--trueValue where condition evaluates TRUE (input raster or constant value)
--falseValue where condition evaluates FALSE (input raster or constant value)
--outputName of the output raster file

Python function:

wbt.conditional_evaluation(
    i, 
    output, 
    statement="", 
    true=None, 
    false=None, 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=ConditionalEvaluation -i=DEM.tif ^
--statement='value > 2500.0' --true=2500.0 --false=DEM.tif ^
--output=onlyLowPlaces.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/07/2021

Last Modified: 21/07/2021

ConditionedLatinHypercube

This tool creates a new shapefile output (--output) sample sites that sastisfy a latin hypercube based on a set of input rasters wth the same projections (--inputs), and is therefore a multidimensional stratified random sampling scheme. A random subset of samples (--samples, n << N) is chosen from the population and iteratively resampled (--max_iter) to minimize an objective function. An annealing schedule and a random resample probability (--rs_prob) are used to control how likely a interation is to randomly resample, or resample the worst strata, where higher values favour a more random sample, and lower values favour a more stratified sample.

The annealing process controls the probability that samples will be discarded each iteration. The temperature is decreased over several iterations, decreasing the probability of discarding the new sample. The properties of the annealing process can be manipulated through the parameters --temp for initial temperature --temp_decay for the tempature decay rate, and -cycle to determine the number of iterations before re-applying the decay rate.

This implementation is loosely based on Minasny and McBratney (2006). An additional optional parameter --average has been added to normalize the continuous objective function and bring it closer to the range of values for the catagorical and correlation objective functions. This prevents continuous inputs from dominating the objective function and makes the objective function cutoff threshold (--threshold) more predictable. However, as a result, the algorithm will emphasize the catagorical and correlation objective relative to the standard weighting.

data objective function has been used to average the number of strata so that it does not dominate the objective function, and makes a objective function cutoff value more predictable (--o_thresh). Another departure from the orignal is that a lower objective function forces the sample to be retained instead of rejected. This was originally based on a random number and the annealed changed in objective function.

Reference:

Minsasny, B., and McBratney, A. B. (2006). A conditioned Latin hypercube method for sampling in the presence of ancillary information. Computers and Geosciences, 32, 1378-1388.

See Also: random_sample

Parameters:

FlagDescription
-i, --inputsName of the input raster file
-o, --outputOutput shapefile
--samplesNumber of sample sites returned
--iterationsMaximum iterations (if stopping criteria not reached)
--seedSeed for RNG consistency
--probProbability of random resample or resampling worst strata between [0,1]
--thresholdObjective function values below the theshold stop the resampling iterations
--tempInitial annealing temperature between [0,1]
--temp_decayAnnealing temperature decay proportion between [0,1]. Reduce temperature by this proportion each annealing cycle
--cycleNumber of iterations before decaying annealing temperature
--averageWeight the continuous objective funtion by the 1/N contributing strata

Python function:

wbt.conditioned_latin_hypercube(
    inputs, 
    output, 
    samples=500, 
    iterations=25000, 
    seed=None, 
    prob=0.5, 
    threshold=None, 
    temp=1.0, 
    temp_decay=0.05, 
    cycle=10, 
    average=False, 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools run -i=Raster1.tif;Raster2.tif ^
--output=sites.shp --samples=500 

Source code on GitHub

Author: Daniel Newman

Created: 17/08/2021

Last Modified: 31/05/2022

Cos

This tool creates a new raster (--output) in which each grid cell is equal to the cosine (cos) of the corresponding grid cell in an input raster (--input). The input raster image should contain angular data measured in radians. You may convert a raster containing degrees to radians using the ToRadians tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Sin, Tan, ArcCos, ToRadians

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 12/10/2018

Cosh

This tool creates a new raster (--output) in which each grid cell is equal to the hyperbolic cosine (cosh) of the corresponding grid cell in an input raster (--input). The input raster image should contain angular data measured in radians. You may convert a raster containing degrees to radians using the ToRadians tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Sinh, Tanh, ToRadians

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 12/10/2018

CrispnessIndex

The Crispness Index (C) provides a means of quantifying the crispness, or fuzziness, of a membership probability (MP) image. MP images describe the probability of each grid cell belonging to some feature or class. MP images contain values ranging from 0 to 1.

The index, as described by Lindsay (2006), is the ratio between the sum of the squared differences (from the image mean) in the MP image divided by the sum of the squared differences for the Boolean case in which the total probability, summed for the image, is arranged crisply.

C is closely related to a family of relative variation coefficients that measure variation in an MP image relative to the maximum possible variation (i.e. when the total probability is arranged such that grid cells contain only 1s or 0s). Notice that 0 < C < 1 and a low C-value indicates a nearly uniform spatial distribution of any probability value, and C = 1 indicates a crisp spatial probability distribution, containing only 1's and 0's.

C is calculated as follows:

C = SS_mp ∕ SS_B = [∑(pij − p-bar)^2] ∕ [ ∑pij(1 − p-bar)^2 + p2(RC − ∑pij)]

Note that there is an error in the original published equation. Specifically, the denominator read:

∑pij(1 - p_bar)^2 + p_bar^2 (RC - ∑pij)

instead of the original:

∑pij(1 - p_bar^2) - p_bar^2 (RC - ∑pij)

References:

Lindsay, J. B. (2006). Sensitivity of channel mapping techniques to uncertainty in digital elevation data. International Journal of Geographical Information Science, 20(6), 669-692.

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOptional output html file (default name will be based on input file if unspecified)

Python function:

wbt.crispness_index(
    i, 
    output=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CrispnessIndex -v --wd="/path/to/data/" ^
-i=input.tif
>>./whitebox_tools -r=CrispnessIndex -v ^
--wd="/path/to/data/" -o=crispness.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/08/2017

Last Modified: 12/10/2018

CrossTabulation

This tool can be used to perform a cross-tabulation on two input raster images (--i1 and --i2) containing categorical data, i.e. classes. It will output a contingency table in HTML format (--output). A contingency table, also known as a cross tabulation or crosstab, is a type of table that displays the multivariate frequency distribution of the variables. These tables provide a basic picture of the interrelation between two categorical variables and can help find interactions between them. CrossTabulation can provide useful information about the nature of land-use/land-cover (LULC) changes between two dates of classified multi-spectral satellite imagery. For example, the extent of urban expansion could be described using the information about the extent of pixels in an 'urban' class in Date 2 that were previously assigned to other classes (e.g. agricultural LULC categories) in the Date 1 imagery.

Both input images must share the same grid, as the analysis requires a comparison of a pair of images on a cell-by-cell basis. If a grid cell contains a NoData value in either of the input images, the cell will be excluded from the analysis.

Parameters:

FlagDescription
--i1, --input1Input raster file 1
--i2, --input2Input raster file 1
-o, --outputOutput HTML file (default name will be based on input file if unspecified)

Python function:

wbt.cross_tabulation(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CrossTabulation -v ^
--wd="/path/to/data/" --i1="file1.tif" --i2="file2.tif" ^
-o=outfile.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/12/2017

Last Modified: 12/10/2018

CumulativeDistribution

This tool converts the values in an input image (--input) into a cumulative distribution function. Therefore, the output raster (--output) will contain the cumulative probability value (0-1) of of values equal to or less than the value in the corresponding grid cell in the input image. NoData values in the input image are not considered during the transformation and remain NoData values in the output image.

See Also: ZScores

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/07/2017

Last Modified: 12/10/2018

Decrement

This tool can be used to decrease the values of each grid cell in an input raster (--input) by 1.0. Note that this tool will modify the input raster. If you would rather create a new raster file, leaving the input unmodified, use the Subtract tool instead.

See Also: InPlaceSubtract, Subtract, Increment

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

Divide

This tool creates a new raster in which each grid cell is equal to the division of the corresponding grid cells in two input rasters or one input raster and a constant value. If two images are input, both images must possess the same number of rows and columns and spatial extent, as the analysis will be carried out on a cell-by-cell basis. If a grid cell contains a NoData value in either of the input images, the cell will be excluded from the analysis.

See Also: Multiply, Add, Subtract, InPlaceDivide

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.divide(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Divide -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 24/01/2019

EqualTo

This tool assigns grid cells for which both (--input1 and --input2) input rasters (or one raster and a constant value) have equal values a new value of 1 (True) in the output raster (--output). All non-equivalent grid cells are assigned a value of zero (False). Grid cells containing NoData values in either of the inputs will be assigned a NoData value in the output raster.

See Also: NotEqualTo, GreaterThan, LessThan

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.equal_to(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=EqualTo -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 12/10/2018

Exp

This tool creates a new raster (--output) in which each grid cell is calculated as e to the power of the value of the corresponding grid cell in the input raster (--input). Moderate to large values in the input raster will result in very large values in the output raster and this may cause errors when you try to display the data. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Exp2, Power, Ln

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 12/10/2018

Exp2

This tool creates a new raster (--output) in which each grid cell is calculated as 2 to the power of the value of the corresponding grid cell in the input raster (--input). Moderate to large values in the input raster will result in very large values in the output raster and this may cause errors when you try to display the data. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Exp, Power, Log2

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 12/10/2018

Floor

This tool performs a floor operation on the values in an input raster (--input) to the nearest integer value. The floor function calculates the largest integer less than or equal to the input value (e.g. floor(0.5) = 0, floor(-4.5) = -4). The output raster (--output) will be of an I32 data type.

See Also: Ceil, Round, Truncate

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 26/10/2019

GreaterThan

This tool assigns grid cells for which the first input raster or constant value (--input1) is greater than the second input raster or constant value (--input2) a new value of 1 (True) in the output raster (--output). All grid cells with lesser values are assigned a value of zero (False) in the output. Grid cells containing NoData values in either of the inputs will be assigned a NoData value in the output raster.

Use the --incl_equals flag to perform a greater-than-equal-to (>=) operation instead of the default greater-than (>) operator.

See Also: LessThan, EqualTo, NotEqualTo

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file
--incl_equalsPerform a greater-than-or-equal-to operation

Python function:

wbt.greater_than(
    input1, 
    input2, 
    output, 
    incl_equals=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=GreaterThan -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif ^
--incl_equals 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 18/10/2019

ImageAutocorrelation

Spatial autocorrelation describes the extent to which a variable is either dispersed or clustered through space. In the case of a raster image, spatial autocorrelation refers to the similarity in the values of nearby grid cells. This tool measures the spatial autocorrelation of a raster image using the global Moran's I statistic. Moran's I varies from -1 to 1, where I = -1 indicates a dispersed, checkerboard type pattern and I = 1 indicates a clustered (smooth) surface. I = 0 occurs for a random distribution of values. ImageAutocorrelation computes Moran's I for the first lag only, meaning that it only takes into account the variability among the immediate neighbors of each grid cell.

The user must specify the names of one or more input raster images. In addition, the user must specify the contiguity type (--contiguity; Rook's, King's, or Bishop's), which describes which neighboring grid cells are examined for the analysis. The following figure describes the available cases:

Rook's contiguity

...
010
1X1
010

Kings's contiguity

...
111
1X1
111

Bishops's contiguity

...
101
0X0
101

The tool outputs an HTML report (--output) which, for each input image (--input), reports the Moran's I value and the variance, z-score, and p-value (significance) under normal and randomization sampling assumptions.

Use the ImageCorrelation tool instead when there is need to determine the correlation among multiple raster inputs.

**NoData **values in the input image are ignored during the analysis.

See Also: ImageCorrelation, ImageCorrelationNeighbourhoodAnalysis

Parameters:

FlagDescription
-i, --inputsInput raster files
--contiguityContiguity type
-o, --outputOutput HTML file (default name will be based on input file if unspecified)

Python function:

wbt.image_autocorrelation(
    inputs, 
    output, 
    contiguity="Rook", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ImageAutocorrelation -v ^
--wd="/path/to/data/" -i="file1.tif, file2.tif, file3.tif" ^
-o=outfile.html --contiguity=Bishops 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/12/2017

Last Modified: 12/10/2018

ImageCorrelation

This tool can be used to estimate the Pearson product-moment correlation coefficient (r) between two or more input images (--inputs). The r-value is a measure of the linear association in the variation of the input variables (images, in this case). The coefficient ranges from -1.0, indicated a perfect negative linear association, to 1.0, indicated a perfect positive linear association. An r-value of 0.0 indicates no correlation between the test variables.

Note that this index is a measure of the linear association; two variables may be strongly related by a non-linear association (e.g. a power function curve) which will lead to an apparent weak association based on the Pearson coefficient. In fact, non-linear associations are very common among spatial variables, e.g. terrain indices such as slope and contributing area. In such cases, it is advisable that the input images are transformed prior to the estimation of the Pearson coefficient, or that an alternative, non-parametric statistic be used, e.g. the Spearman rank correlation coefficient.

The user must specify the names of two or more input images (--inputs). All input images must share the same grid, as the coefficient requires a comparison of a pair of images on a grid-cell-by-grid-cell basis. If more than two image names are selected, the correlation coefficient will be calculated for each pair of images and reported in the HTML output report (--output) as a correlation matrix. Caution must be exercised when attempted to estimate the significance of a correlation coefficient derived from image data. The very high N-value (essentially the number of pixels in the image pair) means that even small correlation coefficients can be found to be statistically significant, despite being practically insignificant.

NoData values in either of the two input images are ignored during the calculation of the correlation between images.

See Also: ImageCorrelationNeighbourhoodAnalysis, ImageRegression, ImageAutocorrelation

Parameters:

FlagDescription
-i, --inputsInput raster files
-o, --outputOutput HTML file (default name will be based on input file if unspecified)

Python function:

wbt.image_correlation(
    inputs, 
    output=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ImageCorrelation -v ^
--wd="/path/to/data/" -i="file1.tif, file2.tif, file3.tif" ^
-o=outfile.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 03/09/2017

Last Modified: 12/10/2018

ImageCorrelationNeighbourhoodAnalysis

This tool can be used to perform nieghbourhood-based (i.e. using roving search windows applied to each grid cell) correlation analysis on two input rasters (--input1 and --input2). The tool outputs a correlation value raster (--output1) and a significance (p-value) raster (--output2). Additionally, the user must specify the size of the search window (--filter) and the correlation statistic (--stat). Options for the correlation statistic include pearson, kendall, and spearman. Notice that Pearson's r is the most computationally efficient of the three correlation metrics but is unsuitable when the input distributions are non-linearly associated, in which case, either Spearman's Rho or Kendall's tau-b correlations are more suited. Both Spearman and Kendall correlations evaluate monotonic associations without assuming linearity in the relation. Kendall's tau-b is by far the most computationally expensive of the three statistics and may not be suitable to larger sized search windows.

See Also: ImageCorrelation, ImageRegression

Parameters:

FlagDescription
--i1, --input1Input raster file
--i2, --input2Input raster file
--o1, --output1Output correlation (r-value or rho) raster file
--o2, --output2Output significance (p-value) raster file
--filterSize of the filter kernel
--statCorrelation type; one of 'pearson' (default) and 'spearman'

Python function:

wbt.image_correlation_neighbourhood_analysis(
    input1, 
    input2, 
    output1, 
    output2, 
    filter=11, 
    stat="pearson", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ImageCorrelationNeighbourhoodAnalysis -v ^
--wd="/path/to/data/" --i1=file1.tif --i2=file2.tif ^
--o1=corr.tif --o2=sig.tif --stat="spearman" 

Source code on GitHub

Author: Simon Gudim and Dr. John Lindsay

Created: 06/12/2019

Last Modified: 06/12/2019

ImageRegression

This tool performs a bivariate linear regression analysis on two input raster images. The first image (--i1) is considered to be the independent variable while the second image (--i2) is considered to be the dependent variable in the analysis. Both input images must share the same grid, as the coefficient requires a comparison of a pair of images on a grid-cell-by-grid-cell basis. The tool will output an HTML report (--output) summarizing the regression model, an Analysis of Variance (ANOVA), and the significance of the regression coefficients. The regression residuals can optionally be output as a new raster image (--out_residuals) and the user can also optionally specify to standardize the residuals (--standardize).

Note that the analysis performs a linear regression; two variables may be strongly related by a non-linear association (e.g. a power function curve) which will lead to an apparently weak fitting regression model. In fact, non-linear relations are very common among spatial variables, e.g. terrain indices such as slope and contributing area. In such cases, it is advisable that the input images are transformed prior to the analysis.

NoData values in either of the two input images are ignored during the calculation of the correlation between images.

See Also: ImageCorrelation, ImageCorrelationNeighbourhoodAnalysis

Parameters:

FlagDescription
--i1, --input1Input raster file (independent variable, X)
--i2, --input2Input raster file (dependent variable, Y)
-o, --outputOutput HTML file for regression summary report
--out_residualsOutput raster regression residual file
--standardizeOptional flag indicating whether to standardize the residuals map
--scattergramOptional flag indicating whether to output a scattergram
--num_samplesNumber of samples used to create scattergram

Python function:

wbt.image_regression(
    input1, 
    input2, 
    output, 
    out_residuals=None, 
    standardize=False, 
    scattergram=False, 
    num_samples=1000, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ImageRegression -v ^
--wd="/path/to/data/" --i1='file1.tif' --i2='file2.tif' ^
-o='outfile.html' --out_residuals='residuals.tif' ^
--standardize 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/09/2017

Last Modified: 18/10/2019

InPlaceAdd

This tool performs an in-place addition, or increment operation (i.e. input1 += input2). The user must specify the names of two input images (--input1 and --input2) and the tool will add the values of input2 to the input1 raster on a pixel-by-pixel basis. Therefore, the input1 raster is modified by this tool. Note that input2 may either be an existing raster file or a constant value. If input2 is a raster, it must have the same dimensions (rows and columns) as input1.

The difference between this tool and the Add tool is that Add does not modify either of its two operands, and instead creates a new output raster to save the resultant value into.

If input2 = 1, use the Increment tool instead.

See Also: Add, InPlaceSubtract, InPlaceDivide, InPlaceMultiply, Increment

Parameters:

FlagDescription
--input1Input raster file
--input2Input raster file or constant value

Python function:

wbt.in_place_add(
    input1, 
    input2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=InPlaceAdd -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif'"
>>./whitebox_tools ^
-r=InPlaceAdd -v --wd="/path/to/data/" --input1='in1.tif' ^
--input2=10.5' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/03/2018

Last Modified: 12/10/2018

InPlaceDivide

This tool performs an in-place division operation (i.e. input1 /= input2). The user must specify the names of two input images (--input1 and --input2) and the tool will divide the input1 raster by the input2 values on a pixel-by-pixel basis. Therefore, the input1 raster is modified by this tool. Note that input2 may either be an existing raster file or a non-zero constant value. If input2 is a raster, it must have the same dimensions (rows and columns) as input1. Zero-valued pixels in input2 will be assigned the NoData value in input1 after this operation.

The difference between this tool and the Divide tool is that Divide does not modify either of its two operands, and instead creates a new output raster to save the resultant value into.

See Also: Divide, InPlaceAdd, InPlaceMultiply, InPlaceSubtract

Parameters:

FlagDescription
--input1Input raster file
--input2Input raster file or constant value

Python function:

wbt.in_place_divide(
    input1, 
    input2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=InPlaceDivide -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif'"
>>./whitebox_tools ^
-r=InPlaceDivide -v --wd="/path/to/data/" --input1='in1.tif' ^
--input2=10.5' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/03/2018

Last Modified: 12/10/2018

InPlaceMultiply

This tool performs an in-place multiplication operation (i.e. input1 *= input2). The user must specify the names of two input images (--input1 and --input2) and the tool will multiply the input1 raster by the input2 values on a pixel-by-pixel basis. Therefore, the input1 raster is modified by this tool. Note that input2 may either be an existing raster file or a constant value. If input2 is a raster, it must have the same dimensions (rows and columns) as input1.

The difference between this tool and the Multiply tool is that Multiply does not modify either of its two operands, and instead creates a new output raster to save the resultant value into.

See Also: Multiply, InPlaceAdd, InPlaceDivide, InPlaceSubtract

Parameters:

FlagDescription
--input1Input raster file
--input2Input raster file or constant value

Python function:

wbt.in_place_multiply(
    input1, 
    input2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=InPlaceMultiply -v ^
--wd="/path/to/data/" --input1='in1.tif' ^
--input2='in2.tif'"
>>./whitebox_tools -r=InPlaceMultiply -v ^
--wd="/path/to/data/" --input1='in1.tif' --input2=10.5' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/03/2018

Last Modified: 12/10/2018

InPlaceSubtract

This tool performs an in-place subtraction, or decrement operation (i.e. input1 -= input2). The user must specify the names of two input images (--input1 and --input2) and the tool will subtact the values of input2 from the input1 raster on a pixel-by-pixel basis. Therefore, the input1 raster is modified by this tool. Note that input2 may either be an existing raster file or a constant value. If input2 is a raster, it must have the same dimensions (rows and columns) as input1.

The difference between this tool and the Subtract tool is that Subtract does not modify either of its two operands, and instead creates a new output raster to save the resultant value into.

If input2 = 1, use the Decrement tool instead.

See Also: Subtract, InPlaceAdd, InPlaceDivide, InPlaceMultiply, Decrement

Parameters:

FlagDescription
--input1Input raster file
--input2Input raster file or constant value

Python function:

wbt.in_place_subtract(
    input1, 
    input2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=InPlaceSubtract -v ^
--wd="/path/to/data/" --input1='in1.tif' ^
--input2='in2.tif'"
>>./whitebox_tools -r=InPlaceSubtract -v ^
--wd="/path/to/data/" --input1='in1.tif' --input2=10.5' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/03/2018

Last Modified: 12/10/2018

Increment

This tool can be used to increase the values of each grid cell in an input raster (--input) by 1.0. Note that this tool will modify the input raster. If you would rather create a new raster file, leaving the input unmodified, use the Add tool instead.

See Also: InPlaceAdd, Add, Decrement

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

IntegerDivision

This tool creates a new raster (--output) in which each grid cell is equal to the integer division of the corresponding grid cells in two input rasters or constant values (--input1 and --input2). The calculation differs from regular division in that the result is always an integer value (rounded by truncation). If the second raster / constant is zero the corresponding grid cell in the output raster will be assigned the NoData value. Grid cells containing NoData values in either of the inputs will be assigned a NoData value in the output raster.

See Also: Divide

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.integer_division(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=IntegerDivision -v ^
--wd="/path/to/data/" --input1='in1.tif' --input2='in2.tif' ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 12/10/2018

InversePrincipalComponentAnalysis

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

This tool takes a two or more component images (--inputs), and the principal component analysis (PCA) report derived using the PrincipalComponentAnalysis tool, and performs the inverse PCA transform to derive the original series of input images. This inverse transform is frequently performed to reduce noise within a multi-spectral image data set. With a typical PCA transform, high-frequency noise will commonly map onto the higher component images. By excluding one or more higher-valued component images from the input component list, the inverse transform can produce a set of images in the original coordinate system that exclude the information contained within component images excluded from the input list. Note that the number of output images will also equal the number of original images input to the PrincipalComponentAnalysis tool. The output images will be named automatically with a "inv_PCA_image" suffix.

See Also: PrincipalComponentAnalysis

Parameters:

FlagDescription
-i, --inputsName of the input PCA component images
-r, --reportName of the PCA report file (*.html)

Python function:

wbt.inverse_principal_component_analysis(
    inputs, 
    report, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=InversePrincipalComponentAnalysis ^
--inputs="PCA_comp1.tif; PCA_comp2.tif; PCA_comp3.tif" ^
--report=PCA_report.html 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 14/03/2021

Last Modified: 14/03/2021

IsNoData

This tool can be used to identify areas of NoData values within an input image.The user must specify the name of the input and output (--input and --output) raster images. Grid cells containing the NoData value in the input image will be assigned a value of 1.0 in the output image. All non-NoData valued grid cells will be assigned 0.0 in the output image.

See Also: SetNodataValue, ConvertNodataToZero

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 01/06/2020

KappaIndex

This tool calculates the Kappa index of agreement (KIA), or Cohen's Kappa, for two categorical input raster images (--input1 and --input2). The KIA is a measure of inter-rater reliability (i.e. classification accuracy) and is widely applied in many fields, notably remote sensing. For example, The KIA is often used as a means of assessing the accuracy of an image classification analysis. The KIA can be interpreted as the percentage improvement that the underlying classification has over and above a random classifier (i.e. random assignment to categories). The user must specify the output HTML file (--output). The input images must be of a categorical data type, i.e. contain classes. As a measure of classification accuracy, the KIA is more robust than the overall percent agreement because it takes into account the agreement occurring by chance. A KIA of 0 would indicate that the classifier is no better than random class assignment. In addition to the KIA, this tool will also output the producer's and user's accuracy, the overall accuracy, and the error matrix.

See Also: CrossTabulation

Parameters:

FlagDescription
--i1, --input1Input classification raster file
--i2, --input2Input reference raster file
-o, --outputOutput HTML file

Python function:

wbt.kappa_index(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=KappaIndex -v --wd="/path/to/data/" ^
--i1=class.tif --i2=reference.tif -o=kia.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/09/2017

Last Modified: 12/10/2018

KsTestForNormality

This tool will perform a Kolmogorov-Smirnov (K-S) test for normality to evaluate whether the frequency distribution of values within a raster image are drawn from a Gaussian (normal) distribution. The user must specify the name of the raster image. The test can be performed optionally on the entire image or on a random sub-sample of pixel values of a user-specified size. In evaluating the significance of the test, it is important to keep in mind that given a sufficiently large sample, extremely small and non-notable differences can be found to be statistically significant. Furthermore statistical significance says nothing about the practical significance of a difference.

See Also: TwoSampleKsTest

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput HTML file
--num_samplesNumber of samples. Leave blank to use whole image

Python function:

wbt.ks_test_for_normality(
    i, 
    output, 
    num_samples=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=KsTestForNormality -v ^
--wd="/path/to/data/" -i=input.tif -o=output.html ^
--num_samples=1000
>>./whitebox_tools -r=KsTestForNormality -v ^
--wd="/path/to/data/" -i=input.tif -o=output.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/01/2018

Last Modified: 12/10/2018

LessThan

This tool assigns grid cells for which the first input raster or constant value (--input1) is less than the second input raster or constant value (--input2) a new value of 1 (True) in the output raster (--output). All grid cells with greater values are assigned a value of zero (False) in the output. Grid cells containing NoData values in either of the inputs will be assigned a NoData value in the output raster.

Use the --incl_equals flag to perform a less-than-equal-to (<=) operation instead of the default less-than (<) operator.

See Also: LessThan, EqualTo, NotEqualTo

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file
--incl_equalsPerform a less-than-or-equal-to operation

Python function:

wbt.less_than(
    input1, 
    input2, 
    output, 
    incl_equals=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LessThan -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif ^
--incl_equals 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 18/10/2019

ListUniqueValues

This tool can be used to list each of the unique values contained within a categorical field of an input vector file's attribute table. The tool outputs an HTML formatted report (--output) containing a table of the unique values and their frequency of occurrence within the data. The user must specify the name of an input shapefile (--input) and the name of one of the fields (--field) contained in the associated attribute table. The specified field should not contained floating-point numerical data, since the number of categories will likely equal the number of records, which may be quite large. The tool effectively provides tabular output that is similar to the graphical output provided by the AttributeHistogram tool, which, however, can be applied to continuous data.

See Also: AttributeHistogram

Parameters:

FlagDescription
-i, --inputInput vector file
--fieldInput field name in attribute table
-o, --outputOutput HTML file (default name will be based on input file if unspecified)

Python function:

wbt.list_unique_values(
    i, 
    field, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ListUniqueValues -v ^
--wd="/path/to/data/" -i=lakes.shp --field=HEIGHT ^
-o=outfile.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/04/2018

Last Modified: 13/10/2018

ListUniqueValuesRaster

This tool can be used to list each of the unique values contained within a categorical raster (input). The tool outputs an HTML formatted report (--output) containing a table of the unique values and their frequency of occurrence within the data. The user must specify the name of an input shapefile (--input) and the name of one of the fields (--field) contained in the associated attribute table. The specified field should not contained floating-point numerical data, since the number of categories will likely equal the number of records, which may be quite large. The tool effectively provides tabular output that is similar to the graphical output provided by the AttributeHistogram tool, which, however, can be applied to continuous data.

See Also: ListUniqueValues

Parameters:

FlagDescription
-i, --inputInput vector file

Python function:

wbt.list_unique_values_raster(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ListUniqueValuesRaster -v ^
--wd="/path/to/data/" -i=lakes.shp --field=HEIGHT ^
-o=outfile.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/04/2018

Last Modified: 09/02/2023

Ln

This tool creates a new raster (--output) in which each grid cell is calculated as the base-e logarithm of the value of the corresponding grid cell in the input raster (--input), i.e. the natural logarithm. Eurler's number e is a constant approximately equal to 2.718282. Negative values in the input raster will be assigned the NoData value in the output raster. NoData values in the input image will be assigned the NoData value in the output image.

See Also: Log2, Log10, Exp

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

Log10

This tool creates a new raster (--output) in which each grid cell is calculated as the base-10 logarithm of the value of the corresponding grid cell in the input raster (--input). Negative values in the input raster will be assigned the NoData value in the output raster. NoData values in the input image will be assigned the NoData value in the output image.

See Also: Ln, Log2

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

Log2

This tool creates a new raster (--output) in which each grid cell is calculated as the base-2 logarithm of the value of the corresponding grid cell in the input raster (--input). Negative values in the input raster will be assigned the NoData value in the output raster. NoData values in the input image will be assigned the NoData value in the output image.

See Also: Ln, Log10, Exp2

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

Max

This tool performs a Max operation on either two input rasters or a raster and a constant value (--input1 and --input2). The operation is performed on a cell-by-cell basis, where by the output raster (--output) will be assigned the maximum value of each of the input values. NoData values in the input image will be assigned NoData values in the output raster.

See Also: Min

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.max(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Max -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

Min

This tool performs a Min operation on either two input rasters or a raster and a constant value (--input1 and --input2). The operation is performed on a cell-by-cell basis, where by the output raster (--output) will be assigned the minimum value of each of the input values. NoData values in the input image will be assigned NoData values in the output raster.

See Also: Max

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.min(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Min -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

Modulo

This tool creates a new raster (--output) in which each grid cell is equal to the remainder of the division of the corresponding grid cells in two input rasters or one input raster and a constant value (--input1 and --input2), i.e. it performs a modulo operation on two numbers. For example, the expression 14 Mod 4 equals 2. If either of the two input numbers is a floating-point value, the floating-point remainder of the division is returned. Because of the imprecision of floating-point storage, the Modulo tool can return an unexpected result when at least one of the operands is floating-point. If the second raster / constant is zero the corresponding grid cell in the output raster will be assigned the NoData value. NoData values in either of the input images will be assigned a NoData value in the output image. Notice that the IntegerDivision tool returns the integer quotient of a division. For example, the expression 14 intdiv 4 evaluates to 3.

See Also: IntegerDivision

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.modulo(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Modulo -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

Multiply

This tool creates a new raster in which each grid cell is equal to the multiplication (product) of the corresponding grid cells in two input rasters or one input raster and a constant value. If two images are input, both images must possess the same number of rows and columns and spatial extent, as the analysis will be carried out on a cell-by-cell basis. If a grid cell contains a NoData value in either of the input images, the cell will be excluded from the analysis.

See Also: Divide, Add, Subtract, InPlaceMulitply

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.multiply(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Multiply -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 24/01/2019

Negate

This tool creates a new raster in which each grid cell is equal to negative one times the corresponding grid cell in the input raster. This effectively changes the sign of values. This tool also handles Boolean data (0, 1) by reversing values (i.e. 0->1 and 1->0).

See Also: AbsoluteValue

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

Not

This tool is a Boolean NOT operator, i.e. it works on True or False (1 and 0) values. Grid cells for which the first input raster (--input1) has a True value and the second raster (--input2) has a False value are assigned 0 in the output raster, otherwise grid cells are assigned a value of 0. All non-zero values in the input rasters are considered to be True, while all zero-valued grid cells are considered to be False. Grid cells containing NoData values in either of the input rasters will be assigned a NoData value in the output raster (--output). Notice that the Not operator is asymmetrical, and the order of inputs matters.

See Also: And, Or, Xor

Parameters:

FlagDescription
--input1Input raster file
--input2Input raster file
-o, --outputOutput raster file

Python function:

wbt.Not(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Not -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/07/2017

Last Modified: 13/10/2018

NotEqualTo

This tool assigns grid cells for which both (--input1 and --input2) input rasters (or one raster and a constant value) have unequal values a new value of 1 (True) in the output raster (--output). All equivalent grid cells are assigned a value of zero (False). Grid cells containing NoData values in either of the inputs will be assigned a NoData value in the output raster.

See Also: EqualTo, GreaterThan, LessThan

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.not_equal_to(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NotEqualTo -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 13/10/2018

Or

This tool is a Boolean OR operator, i.e. it works on True or False (1 and 0) values. Grid cells for which the either the first or second input rasters (--input1; --input2) have a True value are assigned 1 in the output raster, otherwise grid cells are assigned a value of 0. All non-zero values in the input rasters are considered to be True, while all zero-valued grid cells are considered to be False. Grid cells containing NoData values in either of the input rasters will be assigned a NoData value in the output raster (--output).

See Also: And, Not, Xor

Parameters:

FlagDescription
--input1Input raster file
--input2Input raster file
-o, --outputOutput raster file

Python function:

wbt.Or(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Or -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/07/2017

Last Modified: 13/10/2018

PairedSampleTTest

This tool will perform a paired-sample t-test to evaluate whether a significant statistical difference exists between the two rasters. The null hypothesis is that the difference between the paired population means is equal to zero. The paired-samples t-test makes an assumption that the differences between related samples follows a Gaussian distribution. The tool will output a cumulative probability distribution, with a fitted Gaussian, to help users evaluate whether this assumption is violated by the data. If this is the case, the WilcoxonSignedRankTest should be used instead.

The user must specify the name of the two input raster images (--input1 and --input2) and the output report HTML file (--output). The test can be performed optionally on the entire image or on a random sub-sample of pixel values of a user-specified size (--num_samples). In evaluating the significance of the test, it is important to keep in mind that given a sufficiently large sample, extremely small and non-notable differences can be found to be statistically significant. Furthermore statistical significance says nothing about the practical significance of a difference.

See Also: TwoSampleKsTest, WilcoxonSignedRankTest

Parameters:

FlagDescription
--input1First input raster file
--input2Second input raster file
-o, --outputOutput HTML file
--num_samplesNumber of samples. Leave blank to use whole image

Python function:

wbt.paired_sample_t_test(
    input1, 
    input2, 
    output, 
    num_samples=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PairedSampleTTest -v ^
--wd="/path/to/data/" --input1=input1.tif -input2=input2.tif ^
-o=output.html --num_samples=1000 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/10/2019

Last Modified: 25/10/2019

PhiCoefficient

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

This tool performs a binary classification accuracy assessment, using the Phi coefficient. The Phi coefficient is a measure of association for two binary variables. Introduced by Karl Pearson, this measure is similar to the Pearson correlation coefficient in its interpretation and is related to the chi-squared statistic for a 2×2 contingency table. The user must specify the names of two input images (--input1 and --input2), containing categorical data.

Parameters:

FlagDescription
--input1Name of the first input raster image file
--input2Name of the second input raster image file
-o, --outputName of the output HTML file

Python function:

wbt.phi_coefficient(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=PhiCoefficient --input1=image1.tif ^
--input2=image2.tif' -o=PhiReport.html 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 21/04/2021

Last Modified: 21/04/2021

Power

This tool creates a new raster (--output) in which each grid cell is calculated as a value (--input1) raised to the power of another value (--input2). Both inputs can either be rasters or constant values. Moderate to exponent large values will result in very large output values and this may cause errors when you display the data. Grid cells with NoData values in either of the input rasters will be assigned NoData values in the output raster.

See Also: Exp, Exp2

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.power(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Power -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

PrincipalComponentAnalysis

Principal component analysis (PCA) is a common data reduction technique that is used to reduce the dimensionality of multi-dimensional space. In the field of remote sensing, PCA is often used to reduce the number of bands of multi-spectral, or hyper-spectral, imagery. Image correlation analysis often reveals a substantial level of correlation among bands of multi-spectral imagery. This correlation represents data redundancy, i.e. fewer images than the number of bands are required to represent the same information, where the information is related to variation within the imagery. PCA transforms the original data set of n bands into n 'component' images, where each component image is uncorrelated with all other components. The technique works by transforming the axes of the multi-spectral space such that it coincides with the directions of greatest correlation. Each of these new axes are orthogonal to one another, i.e. they are at right angles. PCA is therefore a type of coordinate system transformation. The PCA component images are arranged such that the greatest amount of variance (or information) within the original data set, is contained within the first component and the amount of variance decreases with each component. It is often the case that the majority of the information contained in a multi-spectral data set can be represented by the first three or four PCA components. The higher-order components are often associated with noise in the original data set.

The user must specify the names of the multiple input images (--inputs). Additionally, the user must specify whether to perform a standardized PCA (--standardized) and the number of output components (--num_comp) to generate (all components will be output unless otherwise specified). A standardized PCA is performed using the correlation matrix rather than the variance-covariance matrix. This is appropriate when the variances in the input images differ substantially, such as would be the case if they contained values that were recorded in different units (e.g. feet and meters) or on different scales (e.g. 8-bit vs. 16 bit).

Several outputs will be generated when the tool has completed. The PCA report will be embedded within an output (--output) HTML file, which should be automatically displayed after the tool has completed. This report contains useful data summarizing the results of the PCA, including the explained variances of each factor, the Eigenvalues and Eigenvectors associated with factors, the factor loadings, and a scree plot. The first table that is in the PCA report lists the amount of explained variance (in non-cumulative and cumulative form), the Eigenvalue, and the Eigenvector for each component. Each of the PCA components refer to the newly created, transformed images that are created by running the tool. The amount of explained variance associated with each component can be thought of as a measure of how much information content within the original multi-spectral data set that a component has. The higher this value is, the more important the component is. This same information is presented in graphical form in the scree plot, found at the bottom of the PCA report. The Eigenvalue is another measure of the information content of a component and the eigenvector describes the mathematical transformation (rotation coordinates) that correspond to a particular component image.

Factor loadings are also output in a table within the PCA text report (second table). These loading values describe the correlation (i.e. r values) between each of the PCA components (columns) and the original images (rows). These values show you how the information contained in an image is spread among the components. An analysis of factor loadings can be reveal useful information about the data set. For example, it can help to identify groups of similar images.

PCA is used to reduce the number of band images necessary for classification (i.e. as a data reduction technique), for noise reduction, and for change detection applications. When used as a change detection technique, the major PCA components tend to be associated with stable elements of the data set while variance due to land-cover change tend to manifest in the high-order, 'change components'. When used as a noise reduction technique, an inverse PCA is generally performed, leaving out one or more of the high-order PCA components, which account for noise variance.

Note: the current implementation reads every raster into memory at one time. This is because of the calculation of the co-variances. As such, if the entire image stack cannot fit in memory, the tool will likely experience an out-of-memory error. This tool should be run using the --wd flag to specify the working directory into which the component images will be written.

Parameters:

FlagDescription
-i, --inputsInput raster files
--out_html, --outputOutput HTML report file
--num_compNumber of component images to output; <= to num. input images
--standardizedPerform standardized PCA?

Python function:

wbt.principal_component_analysis(
    inputs, 
    output, 
    num_comp=None, 
    standardized=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PrincipalComponentAnalysis -v ^
--wd='/path/to/data/' -i='image1.tif;image2.tif;image3.tif' ^
--output=report.html --num_comp=3 --standardized 

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/03/2018

Last Modified: 18/10/2019

Quantiles

This tool transforms values in an input raster (--input) into quantiles. In statistics, quantiles are cut points dividing the range of a probability distribution into continuous intervals with equal probabilities, or dividing the observations in a sample in a same way. There is one fewer quantile than the number of groups created. Thus quartiles are the three cut points that will divide a dataset into four equal-sized groups. Common quantiles have special names: for instance quartile (4-quantile), quintiles (5-quantiles), decile (10-quantile), percentile (100-quantile).

The user must specify the desired number of quantiles, q (--num_quantiles), in the output raster (--output). The output raster will contain q equal-sized groups with values 1 to q, indicating which quantile group each grid cell belongs to.

See Also: HistogramEqualization

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--num_quantilesNumber of quantiles

Python function:

wbt.quantiles(
    i, 
    output, 
    num_quantiles=5, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 13/10/2018

RandomField

This tool can be used to a raster image filled with random values drawn from a standard normal distribution. The values range from approximately -4.0 to 4.0, with a mean of 0 and a standard deviation of 1.0. The dimensions and georeferencing of the output random field (--output) are based on an existing, user-specified raster grid (--base). Note that the output field will not possess any spatial autocorrelation. If spatially autocorrelated random fields are desired, the TurningBandsSimulation tool is more appropriate, or alternatively, the FastAlmostGaussianFilter tool may be used to force spatial autocorrelation onto the distribution of the RandomField tool.

See Also: TurningBandsSimulation, FastAlmostGaussianFilter

Parameters:

FlagDescription
-i, --baseInput raster file
-o, --outputOutput raster file

Python function:

wbt.random_field(
    base, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RandomField -v --wd="/path/to/data/" ^
--base=in.tif -o=out.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 13/10/2018

RandomSample

This tool can be used to create a random sample of grid cells. The user specifies the base raster file, which is used to determine the grid dimensions and georeference information for the output raster, and the number of sample random samples (n). The output grid will contain n non-zero grid cells, randomly distributed throughout the raster grid, and a background value of zero. This tool is useful when performing statistical analyses on raster images when you wish to obtain a random sample of data.

Only valid, non-nodata, cells in the base raster will be sampled.

Parameters:

FlagDescription
-i, --baseInput raster file
-o, --outputOutput raster file
--num_samplesNumber of samples

Python function:

wbt.random_sample(
    base, 
    output, 
    num_samples=1000, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RandomSample -v --wd="/path/to/data/" ^
--base=in.tif -o=out.tif --num_samples=1000 

Source code on GitHub

Author: Dr. John Lindsay

Created: January 2, 2018

Last Modified: 13/10/2018

RasterCalculator

The RasterCalculator tool can be used to perform a complex mathematical operations on one or more input raster images on a cell-to-cell basis. The user specifies the name of the output raster (--output) and a mathematical expression, or statement (--statement). Rasters are treated like variables (that change value with each grid cell) and are specified within the statement with the file name contained within either double or single quotation marks (e.g. "DEM.tif" > 500.0). Raster variables may or may not include the file directory. If unspecified, a raster is assumed to exist within the working directory. Similarly, if the file extension is unspecified, it is assumed to be '.tif'. **Note, all input rasters must share the same number of rows and columns and spatial extent. Use the Resample tool if this is not the case to convert the one raster's grid resolution to the others.

The mathematical expression supports all of the standard algebraic unary and binary operators (+ - * / ^ %), as well as comparisons (< <= == != >= >) and logical operators (&& ||) with short-circuit support. The order of operations, from highest to lowest is as follows.

Listed in order of precedence:

OrderSymbolDescription
(Highest Precedence)^Exponentiation
%Modulo
/Division
*Multiplication
-Subtraction
+Addition
== != < <= >= >Comparisons (all have equal precedence)
&& andLogical AND with short-circuit
(Lowest Precedence)|| orLogical OR with short-circuit

Several common mathematical functions are also available for use in the input statement. For example:

* log(base=10, val) -- Logarithm with optional 'base' as first argument.
If not provided, 'base' defaults to '10'.
Example: log(100) + log(e(), 100)

* e()  -- Euler's number (2.718281828459045)
* pi() -- π (3.141592653589793)

* int(val)
* ceil(val)
* floor(val)
* round(modulus=1, val) -- Round with optional 'modulus' as first argument.
Example: round(1.23456) == 1 && round(0.001, 1.23456) == 1.235

* abs(val)
* sign(val)

* min(val, ...) -- Example: min(1, -2, 3, -4) == -4
* max(val, ...) -- Example: max(1, -2, 3, -4) == 3

* sin(radians)    * asin(val)
* cos(radians)    * acos(val)
* tan(radians)    * atan(val)
* sinh(val)       * asinh(val)
* cosh(val)       * acosh(val)
* tanh(val)       * atanh(val)

Notice that the constants pi and e must be specified as functions, pi() and e(). A number of global variables are also available to build conditional statements. These include the following:

Special Variable Names For Use In Conditional Statements:

NameDescription
nodataAn input raster's NoData value.
nullSame as nodata.
minvalueAn input raster's minimum value.
maxvalueAn input raster's maximum value.
rowsThe input raster's number of rows.
columnsThe input raster's number of columns.
rowThe grid cell's row number.
columnThe grid cell's column number.
rowyThe row's y-coordinate.
columnxThe column's x-coordinate.
northThe input raster's northern coordinate.
southThe input raster's southern coordinate.
eastThe input raster's eastern coordinate.
westThe input raster's western coordinate.
cellsizexThe input raster's grid resolution in the x-direction.
cellsizeyThe input raster's grid resolution in the y-direction.
cellsizeThe input raster's average grid resolution.

The special variable names are case-sensitive. If there are more than one raster inputs used in the statement, the functional forms of the nodata, null, minvalue, and maxvalue variables should be used, e.g. nodata("InputRaster"), otherwise the value is assumed to specify the attribute of the first raster in the statement. The following are examples of valid statements:

"raster" != 300.0

"raster" >= (minvalue + 35.0)

("raster1" >= 25.0) && ("raster2" <= 75.0) -- Evaluates to 1 where both conditions are true.

tan("raster" * pi() / 180.0) > 1.0

"raster" == nodata

Any grid cell in the input rasters containing the NoData value will be assigned NoData in the output raster, unless a NoData grid cell value allows the statement to evaluate to True (i.e. the mathematical expression includes the nodata value).

See Also: ConditionalEvaluation

Parameters:

FlagDescription
--statementStatement e.g. cos("raster1") * 35.0 + "raster2". This statement must be a valid Rust statement
--outputName of the output raster file

Python function:

wbt.raster_calculator(
    output, 
    statement="", 
    callback=default_callback
)

Command-line Interface:

-./whitebox_tools -r=ConditionalEvaluation -i=DEM.tif ^
--statement='value > 2500.0' --true=2500.0 --false=DEM.tif ^
--output=onlyLowPlaces.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/07/2021

Last Modified: 21/07/2021

RasterHistogram

This tool produces a histogram (i.e. a frequency distribution graph) for the values contained within an input raster file (--input). The histogram will be embedded within an output (--output) HTML file, which should be automatically displayed after the tool has completed.

See Also: AttributeHistogram

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput HTML file (default name will be based on input file if unspecified)

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=RasterHistogram -v ^
--wd="/path/to/data/" -i="file1.tif" -o=outfile.html 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/12/2017

Last Modified: 24/01/2019

RasterSummaryStats

This tool outputs distribution summary statistics for input raster images (--input). The distribution statistics include the raster minimum, maximum, range, total, mean, variance, and standard deviation. These summary statistics are output to the system stdout.

The following is an example of the summary report:

*********************************
* Welcome to RasterSummaryStats *
*********************************
Reading data...

Number of non-nodata grid cells: 32083559
Number of nodata grid cells: 3916441
Image minimum: 390.266357421875
Image maximum: 426.0322570800781
Image range: 35.765899658203125
Image total: 13030334843.332886
Image average: 406.13745012929786
Image variance: 31.370027239143383
Image standard deviation: 5.600895217654351

See Also: RasterHistogram, ZonalStatistics

Parameters:

FlagDescription
-i, --inputInput raster file

Python function:

wbt.raster_summary_stats(
    i, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 13/10/2018

Reciprocal

This tool creates a new raster (--output) in which each grid cell is equal to one divided by the grid cell values in the input raster image (--input). NoData values in the input image will be assigned NoData values in the output image.

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

RescaleValueRange

Performs a min-max contrast stretch on an input greytone image.

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--out_min_valNew minimum value in output image
--out_max_valNew maximum value in output image
--clip_minOptional lower tail clip value
--clip_maxOptional upper tail clip value

Python function:

wbt.rescale_value_range(
    i, 
    output, 
    out_min_val, 
    out_max_val, 
    clip_min=None, 
    clip_max=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RescaleValueRange -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif ^
--out_min_val=0.0 --out_max_val=1.0
>>./whitebox_tools ^
-r=RescaleValueRange -v --wd="/path/to/data/" -i=input.tif ^
-o=output.tif --out_min_val=0.0 --out_max_val=1.0 ^
--clip_min=45.0 --clip_max=200.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: September 10, 2017

Last Modified: 30/01/2020

RootMeanSquareError

This tool calculates the root-mean-square-error (RMSE) or root-mean-square-difference (RMSD) from two input rasters. If the two input rasters possess the same number of rows and columns, the RMSE is calucated on a cell-by-cell basis, otherwise bilinear resampling is used. In addition to RMSE, the tool also reports other common accuracy statistics including the mean verical error, the 95% confidence limit (RMSE x 1.96), and the 90% linear error (LE90), which is the 90% percentile of the residuals between two raster surfaces. The LE90 is the most robust of the reported accuracy statistics when the residuals are non-Gaussian. The LE90 requires sorting the residual values, which can be a relatively slow operation for larger rasters.

See Also: PairedSampleTTest, WilcoxonSignedRankTest

Parameters:

FlagDescription
-i, --inputInput raster file
--baseInput base raster file used for comparison

Python function:

wbt.root_mean_square_error(
    i, 
    base, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: September 18, 2017

Last Modified: 13/10/2018

Round

This tool rounds the values in an input raster (--input) to the nearest integer value. Half-way cases are rounded away from zero (e.g. round(0.5) = 1, round(-4.5) = -5). The output raster (--output) will be of an I32 data type.

See Also: Ceil, Floor, Truncate

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 26/10/2019

Sin

This tool creates a new raster (--output) in which each grid cell is equal to the sine (sin) of the corresponding grid cell in an input raster (--input). The input raster image should contain angular data measured in radians. You may convert a raster containing degrees to radians using the ToRadians tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Cos, Tan, ArcSin, ToRadians

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 13/10/2018

Sinh

This tool creates a new raster (--output) in which each grid cell is equal to the hyperbolic sine (sinh) of the corresponding grid cell in an input raster (--input). The input raster image should contain angular data measured in radians. You may convert a raster containing degrees to radians using the ToRadians tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Cosh, Tanh, ToRadians

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

Square

This tool creates a new raster (--output) in which each grid cell is equal to the square of the value of the corresponding grid cell in the input raster (--input), i.e. the input raster is raised to the power of two. NoData values in the input image will be assigned NoData values in the output image.

See Also: SquareRoot

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

SquareRoot

This tool creates a new raster (--output) in which each grid cell is equal to the square root of the value of the corresponding grid cell in the input raster (--input). NoData values in the input image will be assigned NoData values in the output image.

See Also: Square

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 26/10/2019

Subtract

This tool creates a new raster in which each grid cell is equal to the subtraction (difference) of the corresponding grid cells in two input rasters or one input raster and a constant value. If two images are input, both images must possess the same number of rows and columns and spatial extent, as the analysis will be carried out on a cell-by-cell basis. If a grid cell contains a NoData value in either of the input images, the cell will be excluded from the analysis.

See Also: Add, Divide, Multiply, InPlaceSubtract

Parameters:

FlagDescription
--input1Input raster file or constant value
--input2Input raster file or constant value
-o, --outputOutput raster file

Python function:

wbt.subtract(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Subtract -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 24/01/2019

Tan

This tool creates a new raster (--output) in which each grid cell is equal to the tangent (tan) of the corresponding grid cell in an input raster (--input). The input raster image should contain angular data measured in radians. You may convert a raster containing degrees to radians using the ToRadians tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Cos, Sin, ArcTan, ToRadians

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 13/10/2018

Tanh

This tool creates a new raster (--output) in which each grid cell is equal to the hyperbolic tangent (tanh) of the corresponding grid cell in an input raster (--input). The input raster image should contain angular data measured in radians. You may convert a raster containing degrees to radians using the ToRadians tool. Grid cells with NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Cosh, Sinh, ToRadians

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

ToDegrees

This tool converts the radians values contained within an input raster (--input) to degrees in the output raster (--output). One degree is approximately 0.017453293 (π / 180) radians. Conversion between degrees and radians is common when working with trigonometric functions.

See Also: ToRadians

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

ToRadians

This tool converts the degree values contained within an input raster (--input) to radians in the output raster (--output). One radian is just under 57.3 (180 / π) degrees. Conversion between degrees and radians is common when working with trigonometric functions.

See Also: ToDegrees

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 13/10/2018

TrendSurface

This tool can be used to interpolate a trend surface from a raster image. The technique uses a polynomial, least-squares regression analysis. The user must specify the name of the input raster file. In addition, the user must specify the polynomial order (1 to 10) for the analysis. A first-order polynomial is a planar surface with no curvature. As the polynomial order is increased, greater flexibility is allowed in the fitted surface. Although polynomial orders as high as 10 are accepted, numerical instability in the analysis often creates artifacts in trend surfaces of orders greater than 5. The operation will display a text report on completion, in addition to the output raster image. The report will list each of the coefficient values and the r-square value. Note that the entire raster image must be able to fit into computer memory, limiting the use of this tool to relatively small rasters. The Trend Surface (Vector Points) tool can be used instead if the input data is vector points contained in a shapefile.

Numerical stability is enhanced by transforming the x, y, z data by their minimum values before performing the regression analysis. These transform parameters are also reported in the output report.

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--orderPolynomial order (1 to 10)

Python function:

wbt.trend_surface(
    i, 
    output, 
    order=1, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=TrendSurface -v --wd="/path/to/data/" ^
-i='input.tif' -o='output.tif' --order=2 

Source code on GitHub

Author: Dr. John Lindsay

Created: 30/04/2018

Last Modified: 13/10/2018

TrendSurfaceVectorPoints

This tool can be used to interpolate a trend surface from a vector points file. The technique uses a polynomial, least-squares regression analysis. The user must specify the name of the input shapefile, which must be of a 'Points' base ShapeType and select the attribute in the shapefile's associated attribute table for which to base the trend surface analysis. The attribute must be numerical. In addition, the user must specify the polynomial order (1 to 10) for the analysis. A first-order polynomial is a planar surface with no curvature. As the polynomial order is increased, greater flexibility is allowed in the fitted surface. Although polynomial orders as high as 10 are accepted, numerical instability in the analysis often creates artifacts in trend surfaces of orders greater than 5. The operation will display a text report on completion, in addition to the output raster image. The report will list each of the coefficient values and the r-square value. The Trend Surface tool can be used instead if the input data is a raster image.

Numerical stability is enhanced by transforming the x, y, z data by their minimum values before performing the regression analysis. These transform parameters are also reported in the output report.

Parameters:

FlagDescription
-i, --inputInput vector Points file
--fieldInput field name in attribute table
-o, --outputOutput raster file
--orderPolynomial order (1 to 10)
--cell_sizeOptionally specified cell size of output raster. Not used when base raster is specified

Python function:

wbt.trend_surface_vector_points(
    i, 
    field, 
    output, 
    cell_size, 
    order=1, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=TrendSurfaceVectorPoints -v ^
--wd="/path/to/data/" -i='input.shp' --field=ELEV ^
-o='output.tif' --order=2 --cell_size=10.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/05/2018

Last Modified: 13/10/2018

Truncate

This tool truncates the values in an input raster (--input); truncation limits the number of digits right of the decimal point. For example, trunc(3.2) = 3 and trunc(5.8) = 5 The output raster (--output) will be of an I32 data type.

See Also: Round, Ceil, Floor

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file
--num_decimalsNumber of decimals left after truncation (default is zero)

Python function:

wbt.truncate(
    i, 
    output, 
    num_decimals=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Truncate -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif --num_decimals=2 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 30/01/2020

TurningBandsSimulation

This tool can be used to create a random field using the turning bands algorithm. The user must specify the name of a base raster image (--base) from which the output raster will derive its geographical information, dimensions (rows and columns), and other information. In addition, the range (--range), in x-y units, must be specified. The range determines the correlation length of the resulting field. For a good description of how the algorithm works, see Carr (2002). The turning bands method creates a number of 1-D simulations (called bands) and fuses these together to create a 2-D error field. There is no natural stopping condition in this process, so the user must specify the number of bands to create (--iterations). The default value of 1000 iterations is reasonable. The fewer iterations used, the more prevalent the 1-D simulations will be in the output error image, effectively creating artifacts. Run time increases with the number of iterations.

Turning bands simulation is a commonly applied technique in Monte Carlo style simulations of uncertainty. As such, it is frequently run many times during a simulation (often 1000s of times). When this is the case, algorithm performance and efficiency are key considerations. One alternative method to efficiently generate spatially autocorrelated random fields is to apply the FastAlmostGaussianFilter tool to the output of the RandomField tool. This can be used to generate a random field with the desired spatial characteristics and frequency distribution. This is the alternative approach used by the StochasticDepressionAnalysis tool.

Reference:

Carr, J. R. (2002). Data visualization in the geosciences. Upper Saddle River, NJ: Prentice Hall. pp. 267.

See Also: RandomField, FastAlmostGaussianFilter, StochasticDepressionAnalysis

Parameters:

FlagDescription
-i, --baseInput base raster file
-o, --outputOutput file
--rangeThe field's range, in xy-units, related to the extent of spatial autocorrelation
--iterationsThe number of iterations

Python function:

wbt.turning_bands_simulation(
    base, 
    output, 
    range, 
    iterations=1000, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=TurningBandsSimulation -v ^
--wd="/path/to/data/" --base=in.tif -o=out.tif --range=850.0 ^
--iterations=2500 

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/07/2017

Last Modified: 30/01/2020

TwoSampleKsTest

This tool will perform a two-sample Kolmogorov-Smirnov (K-S) test to evaluate whether a significant statistical difference exists between the frequency distributions of two rasters. The null hypothesis is that both samples come from a population with the same distribution. Note that this test evaluates the two input rasters for differences in their overall distribution shape, with no assumption of normality. If there is need to compare the per-pixel differences between two input rasters, a paired-samples test such as the PairedSampleTTest or the non-parametric WilcoxonSignedRankTest should be used instead.

The user must specify the name of the two input raster images (--input1 and --input2) and the output report HTML file (--output). The test can be performed optionally on the entire image or on a random sub-sample of pixel values of a user-specified size (--num_samples). In evaluating the significance of the test, it is important to keep in mind that given a sufficiently large sample, extremely small and non-notable differences can be found to be statistically significant. Furthermore statistical significance says nothing about the practical significance of a difference.

See Also: KSTestForNormality, PairedSampleTTest, WilcoxonSignedRankTest

Parameters:

FlagDescription
--input1First input raster file
--input2Second input raster file
-o, --outputOutput HTML file
--num_samplesNumber of samples. Leave blank to use whole image

Python function:

wbt.two_sample_ks_test(
    input1, 
    input2, 
    output, 
    num_samples=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=TwoSampleKsTest -v ^
--wd="/path/to/data/" --input1=input1.tif -input2=input2.tif ^
-o=output.html --num_samples=1000 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/10/2019

Last Modified: 24/10/2019

WilcoxonSignedRankTest

This tool will perform a Wilcoxon signed-rank test to evaluate whether a significant statistical difference exists between the two rasters. The Wilcoxon signed-rank test is often used as a non-parametric equivalent to the paired-samples Student's t-test, and is used when the distribution of sample difference values between the paired inputs is non-Gaussian. The null hypothesis of this test is that difference between the sample pairs follow a symmetric distribution around zero. i.e. that the median difference between pairs of observations is zero.

The user must specify the name of the two input raster images (--input1 and --input2) and the output report HTML file (--output). The test can be performed optionally on the entire image or on a random sub-sample of pixel values of a user-specified size (--num_samples). In evaluating the significance of the test, it is important to keep in mind that given a sufficiently large sample, extremely small and non-notable differences can be found to be statistically significant. Furthermore statistical significance says nothing about the practical significance of a difference. Note that cells with a difference of zero are excluded from the ranking and tied difference values are assigned their average rank values.

See Also: PairedSampleTTest, TwoSampleKsTest

Parameters:

FlagDescription
--input1First input raster file
--input2Second input raster file
-o, --outputOutput HTML file
--num_samplesNumber of samples. Leave blank to use whole image

Python function:

wbt.wilcoxon_signed_rank_test(
    input1, 
    input2, 
    output, 
    num_samples=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=WilcoxonSignedRankTest -v ^
--wd="/path/to/data/" --input1=input1.tif -input2=input2.tif ^
-o=output.html --num_samples=1000 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/10/2019

Last Modified: 25/10/2019

Xor

This tool is a Boolean XOR operator, i.e. it works on True or False (1 and 0) values. Grid cells for which either the first or second input rasters (--input1; --input2) have a True value but not both are assigned 1 in the output raster, otherwise grid cells are assigned a value of 0. All non-zero values in the input rasters are considered to be True, while all zero-valued grid cells are considered to be False. Grid cells containing NoData values in either of the input rasters will be assigned a NoData value in the output raster (--output). Notice that the Not operator is asymmetrical, and the order of inputs matters.

See Also: Or, And, Not

Parameters:

FlagDescription
--input1Input raster file
--input2Input raster file
-o, --outputOutput raster file

Python function:

wbt.xor(
    input1, 
    input2, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Xor -v --wd="/path/to/data/" ^
--input1='in1.tif' --input2='in2.tif' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/07/2017

Last Modified: 13/10/2018

ZScores

This tool will transform the values in an input raster image (--input) into z-scores. Z-scores are also called standard scores, normal scores, or z-values. A z-score is a dimensionless quantity that is calculated by subtracting the mean from an individual raw value and then dividing the difference by the standard deviation. This conversion process is called standardizing or normalizing and the result is sometimes referred to as a standardized variable. The mean and standard deviation are estimated using all values in the input image except for NoData values. The input image should not have a Boolean or categorical data scale, i.e. it should be on a continuous scale.

See Also: CumulativeDistribution

Parameters:

FlagDescription
-i, --inputInput raster file
-o, --outputOutput raster file

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/07/2017

Last Modified: 13/10/2018

ZonalStatistics

This tool can be used to extract common descriptive statistics associated with the distribution of some underlying data raster based on feature units defined by a feature definition raster. For example, this tool can be used to measure the maximum or average slope gradient (data image) for each of a group of watersheds (feature definitions). Although the data raster can contain any type of data, the feature definition raster must be categorical, i.e. it must define area entities using integer values.

The --stat parameter can take the values, 'mean', 'median', 'minimum', 'maximum', 'range', 'standard deviation', or 'total'.

If an output image name is specified, the tool will assign the descriptive statistic value to each of the spatial entities defined in the feature definition raster. If text output is selected, an HTML table will be output, which can then be readily copied into a spreadsheet program for further analysis. This is a very powerful and useful tool for creating numerical summary data from spatial data which can then be interrogated using statistical analyses. At least one output type (image or text) must be specified for the tool to operate.

NoData values in either of the two input images are ignored during the calculation of the descriptive statistic.

See Also: RasterSummaryStats

Parameters:

FlagDescription
-i, --inputInput data raster file
--featuresInput feature definition raster file
-o, --outputOutput raster file
--statStatistic to extract, including 'mean', 'median', 'minimum', 'maximum', 'range', 'standard deviation', and 'total'
--out_tableOutput HTML Table file

Python function:

wbt.zonal_statistics(
    i, 
    features, 
    output=None, 
    stat="mean", 
    out_table=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ZonalStatistics -v ^
--wd="/path/to/data/" -i='input.tif' --features='groups.tif' ^
-o='output.tif' --stat='minimum'
>>./whitebox_tools ^
-r=ZonalStatistics -v --wd="/path/to/data/" -i='input.tif' ^
--features='groups.tif' --out_table='output.html' 

Source code on GitHub

Author: Dr. John Lindsay

Created: Dec. 15, 2017

Last Modified: 17/07/2019

Precision Agriculture

ReconcileMultipleHeaders

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

This tool can be used to adjust the crop yield values for data sets collected with multiple headers or combines. When this situation occurs, the spatial pattern of in-field yield can be dominated by the impact of any miscalibration of the equipment among the individual headers. For example, notice how the areas collected by certain equipment (specified by the various random colours) in the leftmost panel (A) of the image below correspond with anomlously low or high yield values in the original yield map (middle panel, B). The goal of this tool is to calculate adjustment values to offset all of the yield data associated with each region in order to minimize the relative disparity among the various regions (rightmost panel, C).

The data collected by a single header defines a region, which is specified by the --region field in the attribute table of the input vector file (--input). The algorithm works by first locking the data associated the most extensive region. All non-locked points are visited and neighbouring points within a specified radius (--radius) are retrieved. The difference between the average of yield values (--yield_field) within the same region as the non-locked point and the average of locked-point yield values is calculated. After visiting all non-locked points, the overall average difference value is calculated for each non-locked region that shares an edge with the locked region. This overall average difference value is then used to offset all of the yield values contained within each neighbouring region. Each adjusted region is then locked and this whole process is iterated until eventually every region has had adjusted and locked. The adjusted yield values are then saved in the output file's (--output) attribute table as a new field named ADJ_YIELD. The tool will also output a report that shows the offsets applied to each region to calculate the adjusted yield values.

The user may optionally specify minimum and maximum allowable yield values (--min_yield and --max_yield). Any points with yield values outside these bounds will not be included in the point neighbourhood analysis for calculating region adjustments and will also not be included in the output. The default values for this minimum and maximum yield values are the smallest non-zero value and positive infinity respectively. Additionally, the user may optionally specify a mean overall yield tonnage (--mean_tonnage) value. If specified, the output yield values will have one final adjustment to ensure that the overall mean yield value equals this parameter, which should also be between the minimum and maximum values, if specified. This parameter can be set by dividing the actual measured tonnage taken off the field by the field area.

This tool can be used as a pre-processing step prior to applying the YieldFilter tool for fields collected with multiple headers. Note that some experimentation with the radius size may be necessary to achieve optimal results and that this parameter should not be less than the spacing between passes, but may be substantially larger. Also, difficulties may be encountered when regions are composed of multiple separated areas that are joined by a path along the edge of the field. This is particularly problemmatic when there exists a strong spatial trend, in the form of a yield graidient, within the field. In such cases, it may be necessary to remove edge points from the data set using the RemoveFieldEdgePoints tool.

See Also: YieldFilter, RemoveFieldEdgePoints, YieldMap, RecreatePassLines

Parameters:

FlagDescription
-i, --inputName of the input points shapefile
--region_fieldName of the attribute containing region data
-y, --yield_fieldName of the attribute containing yield data
-o, --outputName of the output points shapefile
--radiusOptional search radius, in metres. Only specify this value if you want to calculate locally normalized yield
--min_yieldMinimum yield value in output
--max_yieldMaximum yield value in output
--mean_tonnageUse this optional parameter to force the output to have a certain overall average tonnage

Python function:

wbt.reconcile_multiple_headers(
    i, 
    region_field, 
    yield_field, 
    output, 
    radius=None, 
    min_yield=None, 
    max_yield=None, 
    mean_tonnage=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=ReconcileMultipleHeaders ^
-i=yield_points.shp --region_field='REGION' ^
--yield_field='YIELD' -o=filtered_points.shp --radius=12.0 ^
--min_yield=24.0 --max_yield=55.0 --mean_tonnage=35.5 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 17/08/2021

Last Modified: 22/08/2021

RecreatePassLines

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

This tool can be used to approximate the combine harvester swath pass lines from yield points. It is sometimes the case that either pass-line information is not stored in the point data created during harvesting, or that this information is lost. The YieldFilter and YieldMap tools however require information about the associated swath path for each point in the dataset. This tool can therefore serve as a pre-processing operation before running either of those more advanced mapping tools. It works by examining the geometry of nearby points and associating points with line features that observe a maximum angular change in direction (--max_change_in_heading). The tool creates two output vectors, including a pass line vector (--output) and a points vector (--output_points). The points output contains a PASS_NUM field within its attribute tables that indicate the unique identifier associated with features. The line vector output contains an AVGYIELD attribute field, which provides the pass-line average of the input yield values (--yield_field_name).

For a video tutorial on how to use the RecreatePassLines, YieldFilter and YieldMap tools, see this YouTube video. There is also a blog that describes the usage of this tool on the WhiteboxTools homepage.

See Also: YieldFilter, YieldMap, ReconcileMultipleHeaders, RemoveFieldEdgePoints, YieldNormalization

Parameters:

FlagDescription
-i, --inputName of the input points shapefile
-y, --yield_field_nameName of the attribute containing yield data
--output_linesName of the output pass lines shapefile
--output_pointsName of the output points shapefile
-m, --max_change_in_headingMax change in heading
--ignore_zerosIgnore zero-valued yield points?

Python function:

wbt.recreate_pass_lines(
    i, 
    yield_field_name, 
    output_lines, 
    output_points, 
    max_change_in_heading=25.0, 
    ignore_zeros=False, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RecreatePassLines -i=yield_points.shp ^
--yield_field_name='YIELD' -o=filtered_points.shp ^
--max_change_in_heading=25.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 24/05/2021

Last Modified: 18/06/2021

RemoveFieldEdgePoints

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

This tool can be used to remove, or flag, most of the points along the edges from a crop yield data set. It is frequently the case that yield data collected along the edges of fields are anomalous in value compared with interior values. There are many reasons for this phenomenon, but one of the most common is that the header may be only partially full.

The user must specify the name of the input vector yield points data set (--input), the output points vector (--output), the average distance between passes (--dist), in meters, and the maximum angular change in direction (--max_change_in_heading), which is used to map pass lines (see also RecreatePassLines).

For a video tutorial on how to use the RemoveFieldEdgePoints tool, see this YouTube video.

See Also: YieldFilter, ReconcileMultipleHeaders, YieldMap, RecreatePassLines, YieldNormalization

Parameters:

FlagDescription
-i, --inputName of the input points shapefile
-o, --outputName of the output points shapefile
-d, --distAverage distance between passes, in meters
-m, --max_change_in_headingMax change in heading
--flag_edgesDon't remove edge points, just flag them in the attribute table?

Python function:

wbt.remove_field_edge_points(
    i, 
    output, 
    dist=None, 
    max_change_in_heading=25.0, 
    flag_edges=False, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RemoveFieldEdgePoints ^
-i=yield_points.shp -o=filtered_points.shp --dist=12.0 ^
--max_change_in_heading=25.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 19/08/2021

Last Modified: 19/08/2021

YieldFilter

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

This tool can be used to filter the crop yield values associated with point data derived from commerical combine harvester yield monitors. Crop yield data often suffer from high levels of noise do to the nature of how these data are collected. Commercial crop yield monitors on combine haresters are prone to erroneous data for several reasons. Where harvested rows overlap, lower than expected crop yields may be associated with the second overlapping swath because the head of the harvesting equipment is only partially filled. The edges of fields are particularly susceptible to being harvested without a full swath of crop, resulting in anomalous crop yields. The starts of new swaths are also prone to errors, because of the misalignment between the time when the monitor begins recording and the time when grain begins flowing. Sudden changes in harvester speed, either speeing up or slowing down, can also result in anomalous yield measurements.

The YieldFilter tool can smooth yield point patterns, particularly accounting for differences among adjacent swath lines. The user must specify the name of the input points shapefile (--input), the name of the yield attribute (--yield_field), the pass number attribute (--pass_field_name), the output file (--output), the swatch width (combine head length, --width), the threshold value (--z_score_threshold), and optionally, minimum and maximum yield values (--min_yield and --max_yield). If the input vector does not contain a field indicating a unique identifier associated with each swath pass for points, users may use the RecreatePassLines to estimate swath line structures within the yield points. The threshold value, measured in standardized z-scores is used by the tool to determine when a point is replaced by the mean value of nearby points in adjacent swaths. The output vector will contain the smoothed yield data in the attribute table in a field named AVGYIELD.

The following images show before and after examples of applying YieldFilter:

For a video tutorial on how to use the RecreatePassLines, YieldFilter and YieldMap tools, see this YouTube video. There is also a blog that describes the usage of this tool on the WhiteboxTools homepage.

See Also: RecreatePassLines, YieldMap, ReconcileMultipleHeaders, RemoveFieldEdgePoints, YieldNormalization

Parameters:

FlagDescription
-i, --inputName of the input points shapefile
-y, --yield_fieldName of the attribute containing yield data
-p, --pass_fieldName of the attribute containing pass line ID
-o, --outputName of the output points shapefile
-w, --widthPass swath width (m)
-z, --z_score_thresholdZ-score threshold value (default=2.5)
--min_yieldMinimum yield value in output
--max_yieldMaximum yield value in output

Python function:

wbt.yield_filter(
    i, 
    yield_field, 
    pass_field, 
    output, 
    width=6.096, 
    z_score_threshold=2.5, 
    min_yield=0.0, 
    max_yield=99999.9, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=YieldFilter -i=yield_points.shp ^
--yield_field_name='YIELD' --pass_field_name='PASS_NUM' ^
-o=filtered_points.shp --width=7.0 --z_score_threshold=3.0 ^
--max_yield=55.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 25/05/2021

Last Modified: 25/05/2021

YieldMap

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

This tool can be used to create a segmented-vector polygon yield map from a set of harvester points. The user must specify the name of the input points shapefile (--input), the pass number attribute (--passFieldName), the output file (--output), the swatch width (combine head length, --width), and maximum angular change in direction (--maxChangeInHeading). If the input vector does not contain a field indicating a unique identifier associated with each swath pass for points, users may use the RecreatePassLines to estimate swath line structures within the yield points.

For a video tutorial on how to use the RecreatePassLines, YieldFilter and YieldMap tools, see this YouTube video. There is also a blog that describes the usage of this tool on the WhiteboxTools homepage.

See Also: RecreatePassLines, YieldFilter, ReconcileMultipleHeaders, RemoveFieldEdgePoints, YieldNormalization

Parameters:

FlagDescription
-i, --inputName of the input points shapefile
-p, --pass_field_nameName of the attribute containing pass line ID
-o, --outputName of the output polygon shapefile
-w, --widthPass swath width (m)
-m, --max_change_in_headingMax change in heading

Python function:

wbt.yield_map(
    i, 
    pass_field_name, 
    output, 
    width=6.096, 
    max_change_in_heading=25.0, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=YieldMap -i=points.shp -p='PASS_NUM' ^
-o=yield_map.shp --width=7.0 --max_change_in_heading=25.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 25/05/2021

Last Modified: 25/05/2021

YieldNormalization

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

This tool can be used to normalize the crop yield values (--yield_field) in a coverage of vector points (--input) derived from a combine harvester for a single agricultural field. Normalization is the process of modifying the numerical range of a set of values. Normalizing crop yield values is a common pre-processing procedure prior to analyzing crop data in either a statistical model or machine learning based analysis. The tool re-scales the crop yield values to a 0.0-1.0 range based on the minimum and maximum values, storing the rescaled yield data in an attribute field (named NORM_YIELD)) in the output vector file (--output). The user may also specify custom minimum and maximum yield values (--min_yield and --max_yield); any crop yield values less than this minimum or larger than the specified maximum will be assigned the boundary values, and will subsequently define the 0.0-1.0 range.

The user may also optionally choose to standardize (--standardize), rather than normalize the data. See here for a detailed description of the difference between these two data re-scaling methods. With this option, the output yield values (stored in the STD_YIELD field of the output vector attribute table) will be z-scores, based on differences from the mean and scaled by the standard deviation.

Lastly, the user may optionally specify a search radius (--radius), in meters. Without this optional parameter, the normalization of the data will be based on field-scale values (min/max, or mean/std. dev.). However, when a radius value larger than zero is specified, the tool will perform a regional analysis based on the points contained within a local neighbourhood. The radius value should be large enough to ensure that at least three point measurements are contain within the neighbourhood surrounding each point. Warnings will be issued for points for which this condition is not met, and their output values will be set to -99.0. When this warning occurs frequently, you should consider choosing a larger search radius. The following images demonstrate the difference between field-scale and localized normalization of a sample yield data set.

Like many other tools in the Precision Agriculture toolbox, this tool will work with input vector points files in geographic coordinates (i.e. lat/long), although it is preferable to use a projected coordinate system.

See Also: YieldMap, YieldFilter, RecreatePassLines, ReconcileMultipleHeaders, RemoveFieldEdgePoints

Parameters:

FlagDescription
-i, --inputName of the input points shapefile
-y, --yield_fieldName of the attribute containing yield data
-o, --outputName of the output points shapefile
--standardizeShould the yield values be standardized (converted to z-scores) rather than normalized?
--radiusOptional search radius, in metres. Only specify this value if you want to calculate locally normalized yield
--min_yieldMinimum yield value in output
--max_yieldMaximum yield value in output

Python function:

wbt.yield_normalization(
    i, 
    yield_field, 
    output, 
    standardize=False, 
    radius=None, 
    min_yield=0.0, 
    max_yield=99999.9, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=YieldNormalization -i=yield_points.shp ^
--yield_field='YIELD' -o=filtered_points.shp --standardize ^
--radius=12.0 --min_yield=24.0 --max_yield=55.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 20/06/2021

Last Modified: 21/06/2021

Stream Network Analysis

DistanceToOutlet

This tool calculates the distance of stream grid cells to the channel network outlet cell for each grid cell belonging to a raster stream network. The user must specify the name of a raster containing streams data (--streams), where stream grid cells are denoted by all positive non-zero values, and a D8 flow pointer (i.e. flow direction) raster (--d8_pntr). The pointer image is used to traverse the stream network and must only be created using the D8 algorithm. Stream cells are designated in the streams image as all values greater than zero. Thus, all non-stream or background grid cells are commonly assigned either zeros or NoData values. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

See Also: DownslopeDistanceToStream, LengthOfUpstreamChannels

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=DistanceToOutlet -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=DistanceToOutlet -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/07/2017

Last Modified: 18/10/2019

ExtractStreams

This tool can be used to extract, or map, the likely stream cells from an input flow-accumulation image (--flow_accum). The algorithm applies a threshold to the input flow accumulation image such that streams are considered to be all grid cells with accumulation values greater than the specified threshold (--threshold). As such, this threshold represents the minimum area (area is used here as a surrogate for discharge) required to initiate and maintain a channel. Smaller threshold values result in more extensive stream networks and vice versa. Unfortunately there is very little guidance regarding an appropriate method for determining the channel initiation area threshold. As such, it is frequently determined either by examining map or imagery data or by experimentation until a suitable or desirable channel network is identified. Notice that the threshold value will be unique for each landscape and dataset (including source and grid resolution), further complicating its a priori determination. There is also evidence that in some landscape the threshold is a combined upslope area-slope function. Generally, a lower threshold is appropriate in humid climates and a higher threshold is appropriate in areas underlain by more resistant bedrock. Climate and bedrock resistance are two factors related to drainage density, i.e. the extent to which a landscape is dissected by drainage channels.

The background value of the output raster (--output) will be the NoData value unless the --zero_background flag is specified.

See Also: GreaterThan

Parameters:

FlagDescription
--flow_accumInput raster D8 flow accumulation file
-o, --outputOutput raster file
--thresholdThreshold in flow accumulation values for channelization
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

wbt.extract_streams(
    flow_accum, 
    output, 
    threshold, 
    zero_background=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ExtractStreams -v --wd="/path/to/data/" ^
--flow_accum='d8accum.tif' -o='output.tif' --threshold=100.0 ^
--zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 30/01/2020

ExtractValleys

This tool can be used to extract channel networks from an input digital elevation models (--dem) using one of three techniques that are based on local topography alone.

The Lindsay (2006) 'lower-quartile' method (--variant='LQ') algorithm is a type of 'valley recognition' method. Other channel mapping methods, such as the Johnston and Rosenfeld (1975) algorithm, experience problems because channel profiles are not always 'v'-shaped, nor are they always apparent in small 3 x 3 windows. The lower-quartile method was developed as an alternative and more flexible valley recognition channel mapping technique. The lower-quartile method operates by running a filter over the DEM that calculates the percentile value of the centre cell with respect to the distribution of elevations within the filter window. The roving window is circular, the diameter of which should reflect the topographic variation of the area (e.g. the channel width or average hillslope length). If this variant is selected, the user must specify the filter size (--filter), in pixels, and this value should be an odd number (e.g. 3, 5, 7, etc.). The appropriateness of the selected window diameter will depend on the grid resolution relative to the scale of topographic features. Cells that are within the lower quartile of the distribution of elevations of their neighbourhood are flagged. Thus, the algorithm identifies grid cells that are in relatively low topographic positions at a local scale. This approach to channel mapping is only appropriate in fluvial landscapes. In regions containing numerous lakes and wetlands, the algorithm will pick out the edges of features.

The Johnston and Rosenfeld (1975) algorithm (--variant='JandR') is a type of 'valley recognition' method and operates as follows: channel cells are flagged in a 3 x 3 window if the north and south neighbours are higher than the centre grid cell or if the east and west neighbours meet this same criterion. The group of cells that are flagged after one pass of the roving window constituted the drainage network. This method is best applied to DEMs that are relatively smooth and do not exhibit high levels of short-range roughness. As such, it may be desirable to use a smoothing filter before applying this tool. The FeaturePreservingSmoothing is a good option for removing DEM roughness while preserving the topographic information contain in breaks-in-slope (i.e. edges).

The Peucker and Douglas (1975) algorithm (--variant='PandD') is one of the simplest and earliest algorithms for topography-based network extraction. Their 'valley recognition' method operates by passing a 2 x 2 roving window over a DEM and flagging the highest grid cell in each group of four. Once the window has passed over the entire DEM, channel grid cells are left unflagged. This method is also best applied to DEMs that are relatively smooth and do not exhibit high levels of short-range roughness. Pre-processing the DEM with the FeaturePreservingSmoothing tool may also be useful when applying this method.

Each of these methods of extracting valley networks result in line networks that can be wider than a single grid cell. As such, it is often desirable to thin the resulting network using a line-thinning algorithm. The option to perform line-thinning is provided by the tool as a post-processing step (--line_thin).

References:

Johnston, E. G., & Rosenfeld, A. (1975). Digital detection of pits, peaks, ridges, and ravines. IEEE Transactions on Systems, Man, and Cybernetics, (4), 472-480.

Lindsay, J. B. (2006). Sensitivity of channel mapping techniques to uncertainty in digital elevation data. International Journal of Geographical Information Science, 20(6), 669-692.

Peucker, T. K., & Douglas, D. H. (1975). Detection of surface-specific points by local parallel processing of discrete terrain elevation data. Computer Graphics and image processing, 4(4), 375-387.

See Also: FeaturePreservingSmoothing

Parameters:

FlagDescription
--demInput raster DEM file
-o, --outputOutput raster file
--variantOptions include 'LQ' (lower quartile), 'JandR' (Johnston and Rosenfeld), and 'PandD' (Peucker and Douglas); default is 'LQ'
--line_thinOptional flag indicating whether post-processing line-thinning should be performed
--filterOptional argument (only used when variant='lq') providing the filter size, in grid cells, used for lq-filtering (default is 5)

Python function:

wbt.extract_valleys(
    dem, 
    output, 
    variant="LQ", 
    line_thin=True, 
    filter=5, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ExtractValleys -v --wd="/path/to/data/" ^
--dem=pointer.tif -o=out.tif --variant='JandR' ^
--line_thin
>>./whitebox_tools -r=ExtractValleys -v ^
--wd="/path/to/data/" --dem=pointer.tif -o=out.tif ^
--variant='lq' --filter=7 --line_thin 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/07/2017

Last Modified: 30/01/2020

FarthestChannelHead

This tool calculates the upstream distance to the farthest stream head for each grid cell belonging to a raster stream network. The user must specify the name of a raster containing streams data (--streams), where stream grid cells are denoted by all positive non-zero values, and a D8 flow pointer (i.e. flow direction) raster (--d8_pntr). The pointer image is used to traverse the stream network and must only be created using the D8 algorithm. Stream cells are designated in the streams image as all values greater than zero. Thus, all non-stream or background grid cells are commonly assigned either zeros or NoData values. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

See Also: LengthOfUpstreamChannels, FindMainStem

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=FarthestChannelHead -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=FarthestChannelHead -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/07/2017

Last Modified: 18/10/2019

FindMainStem

This tool can be used to identify the main channel in a stream network. The user must specify the names of a D8 pointer (flow direction) raster (--d8_pntr), and a streams raster (--streams). The pointer raster is used to traverse the stream network and should only be created using the D8Pointer. By default, the pointer raster is assumed to use the clockwise indexing method used by WhiteboxTools:

...
641281
3202
1684

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

The streams raster should have been created using one of the DEM-based stream mapping methods, i.e. contributing area thresholding. Stream grid cells are designated in the streams image as all positive, non-zero values. All non-stream cells will be assigned the NoData value in the output image, unless the --zero_background parameter is specified.

The algorithm operates by traversing each stream and identifying the longest stream-path draining to each outlet. When a confluence is encountered, the traverse follows the branch with the larger distance-to-head.

See Also: D8Pointer

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=FindMainStem -v --wd="/path/to/data/" ^
--d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=FindMainStem -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 18/10/2019

HackStreamOrder

This tool can be used to assign the Hack stream order to each link in a stream network. According to this common stream numbering system, the main stream is assigned an order of one. All tributaries to the main stream (i.e. the trunk) are assigned an order of two; tributaries to second-order links are assigned an order of three, and so on. The trunk or main stream of the stream network can be defined either based on the furthest upstream distance, at each bifurcation (i.e. network junction).

Stream order is often used in hydro-geomorphic and ecological studies to quantify the relative size and importance of a stream segment to the overall river system. Unlike some other stream ordering systems, e.g. Horton-Strahler stream order (StrahlerStreamOrder) and Shreve's stream magnitude (ShreveStreamMagnitude), Hack's stream ordering method increases from the catchment outlet towards the channel heads. This has the main advantage that the catchment outlet is likely to be accurately located while the channel network extent may be less accurately mapped.

The user must specify the names of a streams raster image (--streams) and D8 pointer image (--d8_pntr). Stream cells are designated in the streams image as all positive, nonzero values. Thus all non-stream or background grid cells are commonly assigned either zeros or NoData values. The pointer image is used to traverse the stream network and should only be created using the D8 algorithm. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

Reference:

Hack, J. T. (1957). Studies of longitudinal stream profiles in Virginia and Maryland (Vol. 294). US Government Printing Office.

See Also: HortonStreamOrder, StrahlerStreamOrder, ShreveStreamMagnitude, TopologicalStreamOrder

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=HackStreamOrder -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=HackStreamOrder -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 18/10/2019

HortonStreamOrder

This tool can be used to assign the Horton stream order to each link in a stream network. Stream ordering is often used in hydro-geomorphic and ecological studies to quantify the relative size and importance of a stream segment to the overall river system. There are several competing stream ordering schemes. Based on to this common stream numbering system, headwater stream links are assigned an order of one. Stream order only increases downstream when two links of equal order join, otherwise the downstream link is assigned the larger of the two link orders.

Strahler order and Horton order are similar approaches to assigning stream network hierarchy. Horton stream order essentially starts with the Strahler order scheme, but subsequently replaces each of the assigned stream order value along the main trunk of the network with the order value of the outlet. The main channel is not treated differently compared with other tributaries in the Strahler ordering scheme.

The user must specify the names of a streams raster image (--streams) and D8 pointer image (--d8_pntr). Stream cells are designated in the streams image as all positive, nonzero values. Thus all non-stream or background grid cells are commonly assigned either zeros or NoData values. The pointer image is used to traverse the stream network and should only be created using the D8 algorithm (D8Pointer). Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

Reference:

Horton, R. E. (1945). Erosional development of streams and their drainage basins; hydrophysical approach to quantitative morphology. Geological society of America bulletin, 56(3), 275-370.

See Also: HackStreamOrder, ShreveStreamMagnitude, StrahlerStreamOrder, TopologicalStreamOrder

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=HortonStreamOrder -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=HortonStreamOrder -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 18/10/2019

LengthOfUpstreamChannels

This tool calculates, for each stream grid cell in an input streams raster (--streams) the total length of channels upstream. The user must specify the name of a raster containing streams data (--streams), where stream grid cells are denoted by all positive non-zero values, and a D8 flow pointer (i.e. flow direction) raster (--d8_pntr). The pointer image is used to traverse the stream network and must only be created using the D8 algorithm. Stream cells are designated in the streams image as all values greater than zero. Thus, all non-stream or background grid cells are commonly assigned either zeros or NoData values. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

See Also: FarthestChannelHead, FindMainStem

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=LengthOfUpstreamChannels -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=LengthOfUpstreamChannels -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 18/10/2019

LongProfile

This tool can be used to create a longitudinal profile plot. A longitudinal stream profile is a plot of elevation against downstream distance. Most long profiles use distance from channel head as the distance measure. This tool, however, uses the distance to the stream network outlet cell, or mouth, as the distance measure. The reason for this difference is that while for any one location within a stream network there is only ever one downstream outlet, there is usually many upstream channel heads. Thus plotted using the traditional downstream-distance method, the same point within a network will plot in many different long profile locations, whereas it will always plot on one unique location in the distance-to-mouth method. One consequence of this difference is that the long profile will be oriented from right-to-left rather than left-to-right, as would traditionally be the case.

The tool outputs an interactive SVG line graph embedded in an HTML document (--output). The user must specify the names of a D8 pointer (--d8_pntr) image (flow direction), a streams raster image (--streams), and a digital elevation model (--dem). Stream cells are designated in the streams image as all positive, nonzero values. Thus all non-stream or background grid cells are commonly assigned either zeros or NoData values. The pointer image is used to traverse the stream network and should only be created using the D8 algorithm (D8Pointer). The streams image should be derived using a flow accumulation based stream network extraction algorithm, also based on the D8 flow algorithm.

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

See Also: LongProfileFromPoints, Profile, D8Pointer

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
--demInput raster DEM file
-o, --outputOutput HTML file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=LongProfile -v --wd="/path/to/data/" ^
--d8_pntr=D8.tif --streams=streams.tif --dem=dem.tif ^
-o=output.html --esri_pntr 

Source code on GitHub

Author: Dr. John Lindsay

Created: 20/02/2018

Last Modified: 18/10/2019

LongProfileFromPoints

This tool can be used to create a longitudinal profile plot for a set of vector points (--points). A longitudinal stream profile is a plot of elevation against downstream distance. Most long profiles use distance from channel head as the distance measure. This tool, however, uses the distance to the outlet cell, or mouth, as the distance measure.

The tool outputs an interactive SVG line graph embedded in an HTML document (--output). The user must specify the names of a D8 pointer (--d8_pntr) image (flow direction), a vector points file (--points), and a digital elevation model (--dem). The pointer image is used to traverse the flow path issuing from each initiation point in the vector file; this pointer file should only be created using the D8 algorithm (D8Pointer).

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

See Also: LongProfile, Profile, D8Pointer

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--pointsInput vector points file
--demInput raster DEM file
-o, --outputOutput HTML file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

wbt.long_profile_from_points(
    d8_pntr, 
    points, 
    dem, 
    output, 
    esri_pntr=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LongProfileFromPoints -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --points=stream_head.shp ^
--dem=dem.tif -o=output.html --esri_pntr 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/02/2018

Last Modified: 18/10/2019

PruneVectorStreams

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

This tool can be used to prune an input vector stream network (--streams), such that smaller headwater streams are removed from the output vector streams file (--output). Streams are pruned based on their modelled size, which is estimated using the tributary total upstream channel length (TUCL). TUCL is a measure of the upstream channel extent and therefore the catchment area. A tributary always connects a channel head and a downstream confluence/outlet in the stream network. This is in contrast to a stream link, which connects either a channel head and downstream confluence, in the case of headwater streams, or two confluences, in the case of interior links. Tributaries are often composed of multiple stream links and can have tributaries of their own. At each confluence in the stream network, the tributary identifier that carries on downstream is associated with the upstream link with the larger TUCL value (a surrogate for stream/drainage area size). The tool will determine TUCL and tributary structure by first performing a network analysis operation on the input vector stream network. This requires knowledge of the elevation distribution among stream links, which is provided by an input digital elevation model (DEM; --dem). The main purpose of the DEM is to distinguish between the the outlet stream link and exterior (i.e. headwater) stream links in initiating the tree-traversal algorithm used in the stream network analysis operation. Thus, the DEM need not be particularly fine-resolution.

The user must specify the --threshold tributary TUCL value, with larger values providing more extensive pruning. Because the tool uses tributary TUCL, rather than stream-link TUCL, the resulting pruned stream network will contain fewer streams but will preserve the spatially extent of the original network. That is, stream tributaries with TUCL values larger than the specified threshold will maintain their full length all the way to their channel heads. The main channel stem of networks will be preserved. User experimentation is likely required to determine an appropriate value for the threshold parameter, which will also depend of the application. However, this value should not be larger than the TUCL of the main stem, or else the output network will not contain any features. Tributary TUCL generally follows an exponential progression in a stream network from headwater tributaries towards the main branch. To review the range of TUCL values within a network, one may wish to apply the related VectorStreamNetworkAnalysis tool first, reviewing the TUCL values in the output attribute table. Be mindful however that this is a stream-link TUCL value and not a tributary TUCL (which is why the output of PruneVectorStreams cannot simply be replicated by thresholding the TUCL attribute output by VectorStreamNetworkAnalysis) although the range of values will be the same.

The user must lastly specify the --snap distance value, in meters. This parameter allows the tool to identify the linkage between stream segments when their end nodes are not perfectly aligned. One may also choose to run the RepairStreamVectorTopology tool prior to this tool to resolve any misalignment in the input streams vector.

See Also: TopologicalBreachBurn, RepairStreamVectorTopology, VectorStreamNetworkAnalysis

Parameters:

FlagDescription
--streamsName of the input streams vector file
--demName of the input DEM raster file
-o, --outputName of the output lines shapefile
--thresholdTributary upslope channel length threshold, in xy units (metres)
--snapSnap distance, in xy units (metres)

Python function:

wbt.prune_vector_streams(
    streams, 
    dem, 
    output, 
    threshold="", 
    snap=0.1, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=PruneVectorStreams --streams=rivers.shp ^
--dem=DEM.tif -o=network_analysis.shp --snap=1.0 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 04/05/2023

Last Modified: 04/05/2023

RasterStreamsToVector

This tool converts a raster stream file into a vector file. The user must specify: 1) the name of the raster streams file, 2) the name of the D8 flow pointer file, and 3) the name of the output vector file. Streams in the input raster streams file are denoted by cells containing any positive, non-zero integer. A field in the vector database file, called STRM_VAL, will correspond to this positive integer value. The database file will also have a field for the length of each link in the stream network. The flow pointer file must be calculated from a DEM with all topographic depressions and flat areas removed and must be calculated using the D8 flow pointer algorithm. The output vector will contain PolyLine features.

See Also: RasterizeStreams, RasterToVectorLines

Parameters:

FlagDescription
--streamsInput raster streams file
--d8_pntrInput raster D8 pointer file
-o, --outputOutput vector file
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=RasterStreamsToVector -v ^
--wd="/path/to/data/" --streams=streams.tif --d8_pntr=D8.tif ^
-o=output.shp
>>./whitebox_tools -r=RasterStreamsToVector -v ^
--wd="/path/to/data/" --streams=streams.tif --d8_pntr=D8.tif ^
-o=output.shp --esri_pntr 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/09/2018

Last Modified: 18/10/2019

RasterizeStreams

This tool can be used rasterize an input vector stream network (--streams) using on Lindsay (2016) method. The user must specify the name of an existing raster (--base), from which the output raster's grid resolution is determined.

Reference:

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

See Also: RasterStreamsToVector

Parameters:

FlagDescription
--streamsInput vector streams file
--baseInput base raster file
-o, --outputOutput raster file
--nodataUse NoData value for background?
--feature_idUse feature number as output value?

Python function:

wbt.rasterize_streams(
    streams, 
    base, 
    output, 
    nodata=True, 
    feature_id=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterizeStreams -v ^
--wd="/path/to/data/" --streams=streams.shp --base=raster.tif ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/03/2018

Last Modified: 22/10/2019

RemoveShortStreams

This tool can be used to remove stream links in a stream network that are shorter than a user-specified length (--min_length). The user must specify the names of a streams raster image (--streams) and D8 pointer image (--d8_pntr). Stream cells are designated in the streams raster as all positive, nonzero values. Thus all non-stream or background grid cells are commonly assigned either zeros or NoData values. The pointer raster is used to traverse the stream network and should only be created using the D8 algorithm. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

See Also: ExtractStreams

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--min_lengthMinimum tributary length (in map units) used for network pruning
--esri_pntrD8 pointer uses the ESRI style scheme

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=RemoveShortStreams -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 30/01/2020

RepairStreamVectorTopology

This tool can be used to resolve many of the topological errors and inconsistencies associated with manually digitized vector stream networks, i.e. hydrography data. A properly structured stream network should consist of a series of stream segments that connect a channel head to a downstream confluence, or an upstream confluence to a downstream confluence/outlet. This tool will join vector arcs that connect at arbitrary, non-confluence points along stream segments. It also splits an arc where a tributary stream connects at a mid-point, thereby creating a proper confluence where two upstream triburaries converge into a downstream segment. The tool also handles non-connecting tributaries caused by dangling arcs, i.e. overshoots and undershoots.

The user must specify the name of the input vector stream network (--input) and the output file (--output). Additionally, a distance threshold for snapping dangling arcs (--snap) must be specified. This distance is in the input layer's x-y units. The tool works best on projected input data, however, if the input are in geographic coordinates (latitude and longitude), then specifying a small valued snap distance is advisable. Notice that the attributes of the input layer will not be carried over to the output file because there is not a one-for-one feature correspondence between the two files due to the joins and splits of stream segments. Instead the output attribute table will only contain a feature ID (FID) entry.

Note: this tool should be used to pre-process vector streams that are input to the VectorStreamNetworkAnalysis tool.

See Also: VectorStreamNetworkAnalysis, FixDanglingArcs

Parameters:

FlagDescription
-i, --inputName of the input lines vector file
-o, --outputName of the output lines vector file
--snap, --distSnap distance, in xy units (metres)

Python function:

wbt.repair_stream_vector_topology(
    i, 
    output, 
    dist="", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=RepairStreamVectorTopology ^
--input=streams.shp --output=streams_fixed.shp --snap=2.0 

Source code on GitHub

Author: Prof. John Lindsay

Created: 03/08/2021 (oringinally in Whitebox Toolset Extension)

Last Modified: 23/03/2023

ShreveStreamMagnitude

This tool can be used to assign the Shreve stream magnitude to each link in a stream network. Stream ordering is often used in hydro-geomorphic and ecological studies to quantify the relative size and importance of a stream segment to the overall river system. There are several competing stream ordering schemes. Shreve stream magnitude is equal to the number of headwater links upstream of each link. Headwater stream links are assigned a magnitude of one.

The user must specify the names of a streams raster image (--streams) and D8 pointer image (--d8_pntr). Stream cells are designated in the streams raster as all positive, nonzero values. Thus all non-stream or background grid cells are commonly assigned either zeros or NoData values. The pointer image is used to traverse the stream network and should only be created using the D8 algorithm. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

Reference:

Shreve, R. L. (1966). Statistical law of stream numbers. The Journal of Geology, 74(1), 17-37.

See Also: HortonStreamOrder, HackStreamOrder, StrahlerStreamOrder, TopologicalStreamOrder

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=ShreveStreamMagnitude -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=ShreveStreamMagnitude -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 18/10/2019

StrahlerStreamOrder

This tool can be used to assign the Strahler stream order to each link in a stream network. Stream ordering is often used in hydro-geomorphic and ecological studies to quantify the relative size and importance of a stream segment to the overall river system. There are several competing stream ordering schemes. Based on to this common stream numbering system, headwater stream links are assigned an order of one. Stream order only increases downstream when two links of equal order join, otherwise the downstream link is assigned the larger of the two link orders.

Strahler order and Horton order are similar approaches to assigning stream network hierarchy. Horton stream order essentially starts with the Strahler order scheme, but subsequently replaces each of the assigned stream order value along the main trunk of the network with the order value of the outlet. The main channel is not treated differently compared with other tributaries in the Strahler ordering scheme.

The user must specify the names of a streams raster image (--streams) and D8 pointer image (--d8_pntr). Stream cells are designated in the streams image as all positive, nonzero values. Thus all non-stream or background grid cells are commonly assigned either zeros or NoData values. The pointer image is used to traverse the stream network and should only be created using the D8 algorithm. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

Reference:

Strahler, A. N. (1957). Quantitative analysis of watershed geomorphology. Eos, Transactions American Geophysical Union, 38(6), 913-920.

See Also: HortonStreamOrder, HackStreamOrder, ShreveStreamMagnitude, TopologicalStreamOrder

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=StrahlerStreamOrder -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=StrahlerStreamOrder -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 18/10/2019

StreamLinkClass

This tool identifies all interior and exterior links, and source, link, and sink nodes in an input stream network (--streams). The input streams file is used to designate which grid cells contain a stream and the pointer image is used to traverse the stream network. Stream cells are designated in the streams image as all values greater than zero. Thus, all non-stream or background grid cells are commonly assigned either zeros or NoData values. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

Each feature is assigned the following identifier in the output image:

ValueStream Type
1Exterior Link
2Interior Link
3Source Node (head water)
4Link Node
5Sink Node

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

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

See Also: StreamLinkIdentifier

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=StreamLinkClass -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=StreamLinkClass -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/07/2017

Last Modified: 10/10/2019

StreamLinkIdentifier

This tool can be used to assign each link in a stream network a unique numeric identifier. This grid is used by a number of other stream network analysis tools.

The input streams file (--streams) is used to designate which grid cells contain a stream and the pointer image is used to traverse the stream network. Stream cells are designated in the streams image as all values greater than zero. Thus, all non-stream or background grid cells are commonly assigned either zeros or NoData values. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

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

See Also: D8Pointer, TributaryIdentifier, BreachDepressions, FillDepressions

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=StreamLinkIdentifier -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=StreamLinkIdentifier -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 03/09/2020

StreamLinkLength

This tool can be used to measure the length of each link in a stream network. The user must specify the names of a stream link ID raster (--linkid), created using the StreamLinkIdentifier and D8 pointer raster (--d8_pntr). The flow pointer raster is used to traverse the stream network and should only be created using the D8Pointer algorithm. Stream cells are designated in the stream link ID raster as all non-zero, positive values. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

See Also: D8Pointer, StreamLinkSlope

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--linkidInput raster streams link ID (or tributary ID) file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

wbt.stream_link_length(
    d8_pntr, 
    linkid, 
    output, 
    esri_pntr=False, 
    zero_background=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=StreamLinkLength -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --linkid=streamsID.tif ^
--dem=dem.tif -o=output.tif
>>./whitebox_tools ^
-r=StreamLinkLength -v --wd="/path/to/data/" --d8_pntr=D8.tif ^
--linkid=streamsID.tif --dem=dem.tif -o=output.tif --esri_pntr ^
--zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 18/10/2019

StreamLinkSlope

This tool can be used to measure the average slope gradient, in degrees, of each link in a raster stream network. To estimate the slope of individual grid cells in a raster stream network, use the StreamSlopeContinuous tool instead. The user must specify the names of a stream link identifier raster image (--linkid), a D8 pointer image (--d8_pntr), and a digital elevation model (--dem). The pointer image is used to traverse the stream network and must only be created using the D8 algorithm (D8Pointer). Stream cells are designated in the streams image as all values greater than zero. Thus, all non-stream or background grid cells are commonly assigned either zeros or NoData values. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

See Also: StreamSlopeContinuous, D8Pointer

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--linkidInput raster streams link ID (or tributary ID) file
-i, --demInput raster DEM file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

wbt.stream_link_slope(
    d8_pntr, 
    linkid, 
    dem, 
    output, 
    esri_pntr=False, 
    zero_background=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=StreamLinkSlope -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --linkid=streamsID.tif ^
--dem=dem.tif -o=output.tif
>>./whitebox_tools ^
-r=StreamLinkSlope -v --wd="/path/to/data/" --d8_pntr=D8.tif ^
--linkid=streamsID.tif --dem=dem.tif -o=output.tif --esri_pntr ^
--zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/06/2017

Last Modified: 18/10/2019

StreamSlopeContinuous

This tool can be used to measure the slope gradient, in degrees, each grid cell in a raster stream network. To estimate the average slope for each link in a stream network, use the StreamLinkSlope tool instead. The user must specify the names of a stream raster image (--streams), a D8 pointer image (--d8_pntr), and a digital elevation model (--dem). The pointer image is used to traverse the stream network and must only be created using the D8 algorithm (D8Pointer). Stream cells are designated in the streams image as all values greater than zero. Thus, all non-stream or background grid cells are commonly assigned either zeros or NoData values. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

See Also: StreamLinkSlope, D8Pointer

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-i, --demInput raster DEM file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

wbt.stream_slope_continuous(
    d8_pntr, 
    streams, 
    dem, 
    output, 
    esri_pntr=False, 
    zero_background=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=StreamSlopeContinuous -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --linkid=streamsID.tif ^
--dem=dem.tif -o=output.tif
>>./whitebox_tools ^
-r=StreamSlopeContinuous -v --wd="/path/to/data/" ^
--d8_pntr=D8.tif --streams=streamsID.tif --dem=dem.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 18/10/2019

TopologicalStreamOrder

This tool can be used to assign the topological stream order to each link in a stream network. According to this stream numbering system, the link directly draining to the outlet is assigned an order of one. Each of the two tributaries draining to the order-one link are assigned an order of two, and so on until the most distant link from the catchment outlet has been assigned an order. The topological order can therefore be thought of as a measure of the topological distance of each link in the network to the catchment outlet and is likely to be related to travel time.

The user must specify the names of a streams raster image (--streams) and D8 pointer image (--d8_pntr). Stream cells are designated in the streams image as all positive, nonzero values. Thus all non-stream or background grid cells are commonly assigned either zeros or NoData values. The pointer image is used to traverse the stream network and should only be created using the D8 algorithm. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

See Also: HackStreamOrder, HortonStreamOrder, StrahlerStreamOrder, ShreveStreamMagnitude

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=TopologicalStreamOrder -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=TopologicalStreamOrder -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 28/06/2017

Last Modified: 18/10/2019

TributaryIdentifier

This tool can be used to assigns a unique identifier to each tributary in a stream network. A tributary is a section of a stream network extending from a channel head downstream to a confluence with a larger stream. Relative stream size is estimated using stream length as a surrogate. Tributaries therefore extend from channel heads downstream until a confluence is encountered in which the intersecting stream is longer, or an outlet cell is detected.

The input streams file (--streams) is used to designate which grid cells contain a stream and the pointer image is used to traverse the stream network. Stream cells are designated in the streams image as all values greater than zero. Thus, all non-stream or background grid cells are commonly assigned either zeros or NoData values. Background cells will be assigned the NoData value in the output image, unless the --zero_background parameter is used, in which case non-stream cells will be assigned zero values in the output.

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

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

See Also: D8Pointer, StreamLinkIdentifier, BreachDepressions, FillDepressions

Parameters:

FlagDescription
--d8_pntrInput raster D8 pointer file
--streamsInput raster streams file
-o, --outputOutput raster file
--esri_pntrD8 pointer uses the ESRI style scheme
--zero_backgroundFlag indicating whether a background value of zero should be used

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=TributaryIdentifier -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif
>>./whitebox_tools -r=TributaryIdentifier -v ^
--wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif ^
-o=output.tif --esri_pntr --zero_background 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/06/2017

Last Modified: 10/10/2019

VectorStreamNetworkAnalysis

This tool performs common stream network analysis operations on an input vector stream file (--streams). The network indices produced by this analysis are contained within the output vector's (--output) attribute table. The following table shows each of the network indices that are calculated.

Index NameDescription
OUTLETUnique outlet identifying value, used as basin identifier
TRIB_IDUnique tributary identifying value
DIST2MOUTHDistance to outlet (i.e., mouth node)
DS_NODESNumber of downstream nodes
TUCLTotal upstream channel length; the channel equivalent to catchment area
MAXUPSDISTMaximum upstream distance
HORTONHorton stream order
STRAHLERStrahler stream order
SHREVEShreve stream magnitude
HACKHack stream order
MAINSTREAMBoolean value indicating whether link is the main stream trunk of its basin
MIN_ELEVMinimum link elevation (from DEM)
MAX_ELEVMaximum link elevation (from DEM)
IS_OUTLETBoolean value indicating whether link is an outlet link

In addition to the input and output files, the user must also specify the name of an input DEM file (--dem), the maximum ridge-cutting height, in DEM z units (--cutting_height), and the snap distance used for identifying any topological errors in the stream file (--snap). The main function of the input DEM is to distinguish between outlet and headwater links in the network, which can be differentiated by their elevations during the priority-flood operation used in the algorithm (see Lindsay et al. 2019). The maximum ridge-cutting height parameter is useful for preventing erroneous stream capture in the headwaters when channel heads are very near (within the sanp distance), which is usually very rare. The snap distance parameter is used to deal with certain common topological errors. However, it is advisable that the input streams file be pre-processed prior to analysis.

Note: The input streams file for this tool should be pre-processed using the RepairStreamVectorTopology tool. This is an important step.

OUTLET:

HORTON:

SHREVE:

TRIB_ID:

Many of the network indices output by this tool for vector streams have raster equivalents in WhiteboxTools. For example, see the StrahlerStreamOrder, ShreveStreamMagnitude tools.

Reference:

Lindsay, JB, Yang, W, Hornby, DD. 2019. Drainage network analysis and structuring of topologically noisy vector stream data. ISPRS International Journal of Geo-Information. 8(9), 422; DOI: 10.3390/ijgi8090422

See Also: RepairStreamVectorTopology, StrahlerStreamOrder, ShreveStreamMagnitude

Parameters:

FlagDescription
--streamsName of the input streams vector file
--demName of the input DEM raster file
-o, --outputName of the output lines shapefile
--cutting_heightMaximum ridge-cutting height (z units)
--snapSnap distance, in xy units (metres)

Python function:

wbt.vector_stream_network_analysis(
    streams, 
    dem, 
    output, 
    cutting_height=10.0, 
    snap=0.1, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=VectorStreamNetworkAnalysis ^
--streams=rivers.shp --dem=DEM.tif -o=network_analysis.shp ^
--cutting_height=10.0 --snap=1.0 

Source code on GitHub

Author: Prof. John Lindsay

Created: 28/07/2021 (oringinally in Whitebox Toolset Extension)

Last Modified: 23/03/2023

Whitebox Utilities

InstallWbExtension

This tool can be used to install the Whitebox Toolset Extension (WTE). The WTE is a commercial add-on for the WhiteboxTools Open Core and contains more than 60 advanced tools for geospatial data processing. The WTE easily integrates into your current WhiteboxTools environment. This tool will launch the Whitebox Runner, allowing users a convenient way to install the extension. While this tool will install the extension running the extension tools does require a valid license, which can be purchased from Whitebox Geospatial Inc..

Parameters:

FlagDescription
--install_extensionName of the extension product to install. Options include: 'General Toolset Extension', 'DEM & Spatial Hydrology Extension', 'Lidar & Remote Sensing Extension', and 'Agriculture Extension'

Python function:

wbt.install_wb_extension(
    install_extension="General Toolset Extension", 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LaunchWbRunner



Source code is unavailable due to proprietary license.

Author: Dr. John Lindsay

Created: 14/11/2022

Last Modified: 14/11/2022

LaunchWbRunner

This tool can be used to launch the Whitebox Runner application from within other Whitebox front-ends. The purpose of this tool is to make the Whitebox Runner more accessible from other Whitebox front-ends. However, note that you can also launch the Whitebox Runner simply by double-clicking on the executable file (whitebox_runner.exe on Windows, whitebox_tools on other systems) located within your WBT directory, containing your Whitebox installation.

Parameters:

FlagDescription
--clear_app_stateClear the application state memory?

Python function:

wbt.launch_wb_runner(
    clear_app_state=False, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LaunchWbRunner



Source code is unavailable due to proprietary license.

Author: Dr. John Lindsay

Created: 14/11/2022

Last Modified: 14/11/2022

Tutorials

How can I mosaic hundreds of rasters?

Sometimes you find that you need to mosaic many individual raster tiles into a single larger raster image. You can use WhiteboxTools' Mosaic tool to join multiple rasters together; however, this operation can become extremely challenging if you have many hundreds of large raster tiles. The following script shows how you can use WhiteboxTools' Python interface to mosaic many rasters using intermediate mosaicing steps, which are then merged in a final step. Each intermediate mosaic raster is cleaned up at the end. The script assumes that the initial raster tiles are contained in a single directory (source_data_dir) and that the output mosaics will be contained in a seperate directory (raster_data_dir). Please modify these as needed.

# This script is affiliated with the WhiteboxTools Geospatial analysis library 
# Authors: Anthony Francioni, Carys Owens, and John Lindsay
# Created: 01/07/2020
# Last Modified: 17/08/2020
# License: MIT


######################################################################################
# This script creates an image mosaic from one or more input image files using the   #
# Mosaic tool from Whitebox tools. This tool uses one of three user-defined          #
# resampling methods (--method) including, nearest neighbour ("nn"), bilinear        #
# interpolation ("bilinear"), and cubic convolution ("cc").                          #
#                                                                                    #
# The order of the input source image files is important. Grid cells in the output   #
# image will be assigned the corresponding value determined from the last image      #
# found in the list to possess an overlapping coordinate.                            #
#                                                                                    #
# Note that when the --inputs parameter is left unspecified, the tool will use all   #
# of the raster files of supported data formats located in the working directory.    #
#                                                                                    #
# This is the preferred mosaicing tool to use when appending multiple images with    #
# little to no overlapping areas, e.g. tiled data. When images have significant      #
# overlap areas, users are advised to use the MosaicWithFeathering tool instead.     #
######################################################################################

# Library import statements
import os
from WBT.whitebox_tools import WhiteboxTools # Module call to WhiteboxTools. For more information see https://jblindsay.github.io/wbt_book/python_scripting/using_whitebox_tools.html)


def main():
    #########################
    # Set up Whitebox tools #
    #########################
    wbt = WhiteboxTools()
    wbt.set_verbose_mode(True) # Sets verbose mode. If verbose mode is False, tools will not print output messages as they run
    wbt.set_compress_rasters(True) # Compressed TIF file format based on the DEFALTE algorithm
    
    ##########################
    # Set up tool parameters #
    ##########################
    input_directory = "C:\\Path\\to\\input\\files\\" # Input directory; change to match user environment
    output_directory = "C:\\Path\\to\\output\\directory\\" # Output directory; change to match yours
    
    if os.path.isdir(output_directory) != True: # Creates output dir if it does not already exist 
        os.mkdir(output_directory)      
    
    ################
    # Run the tool #
    ################
    wbt.set_working_dir(input_directory) # Set the working dir: This should be teh location of the input files #
    outfile = os.path.join(output_directory,"NAME_OF_FILE.tif") # Create the output file by joining the output directory path with the name of file
    # Calls mosaic tool with nearest neighbour as the resampling method ("nn")
    if wbt.mosaic(
        output=outfile, 
        method = "nn"
    ) != 0:
        # Non-zero returns indicate an error.
        print('ERROR running mosaic')
    
    print("Complete!")

main()

Processing LiDAR data

How do I convert a LiDAR point cloud into a raster?

Converting your LiDAR data into a raster requires an interpolation operation. There are many such interpolation methods. The following is an example of how to interpolate the last-return points of a LAS/zLidar file using an inverse distance weighted (IDW) interpolation scheme, with a search window radius of 2.5 m, an exponent of 2.0, and an output grid resolution of 1.5 m. You may prefer to derive your raster DEM using Delaunay triangulation (TINing) instead.

from WBT.whitebox_tools import WhiteboxTools

wbt = WhiteboxTools()
wbt.wbt.set_working_dir("/path/to/data/")

wbt.lidar_idw_interpolation(
i="myFile.las",
output="myRaster.tif",
parameter="elevation",
returns="last",
resolution=1.5,
weight=2.0,
radius=2.5
)

Other methods for gridding a LAS/zLidar file include nearest neighbour, Delaunay triangulation (TINing), block minimum, and block maximum gridding schemes.

How do I extract a subset of LiDAR files that overlap with an area of interest?

Sometimes, you need to extract all of the LAS/zLidar tiles from a large dataset that overlap with a particular area of interest. For example, you may need to interpolate all the files overlapping with a watershed or a particular city. For this task, you can use select_tiles_by_polygon. # Uncomment the four lines below if you want to do this. # outdir = "/Users/johnlindsay/Documents/data/LAS_files_in_watershed/" # polygons = "/Users/johnlindsay/Documents/data/LAS_files_in_watershed/watershed.shp" # wbt.select_tiles_by_polygon(las_files_dir, outdir, polygons) # las_files_dir = outdir # this way the analysis below works only on the selected tiles.

import os
from WBT.whitebox_tools import WhiteboxTools # module call to WhiteboxTools. For more information see https://jblindsay.github.io/wbt_book/python_scripting/using_whitebox_tools.html)

def main():
    ########################
    # Set up WhiteboxTools #
    ########################
    wbt = WhiteboxTools()
    wbt.set_verbose_mode(False) # Sets verbose mode. If verbose mode is False, tools will not print output messages
    input_directory = "C:\\Insert\\Path\\to\\infile\\directory\\" # Input file directory; change to match your environment
    output_directory = "C:\\Insert\\path\\to\\output\\directory\\" # Output file directory; change to match your environment
    aoi_polygon = "C:\\path\\area_of_interest.shp" # Name of the shapefile containing the AOI; change to match your file
    # Note: the AOI shapefile must be in the same CRS as the LiDAR data.
    
    if os.path.isdir(output_directory) != True: # Creates the output directory if it does not already exist
        os.mkdir(output_directory)

    wbt.select_tiles_by_polygon(
        indir=input_directory, 
        outdir=output_directory, 
        polygons=aoi_polygon
    )

if __name__ == "__main__" :
    main()
    print("Complete")

How do I exclude points with certain classifications?

It is commonly the case that points with certain class values should be excluded from the gridding of LiDAR data. For example, you may wish to exclude points associated with vegetation, buildings, bridges, utility lines, etc. The LidarIdwInterpolation and LidarNearestNeighbourGridding tools allow for excluded point classes using the exclude_cls parameter. The parameter takes a numeric list as input, e.g. exclude_cls='3,4,5,6,7,18'. Class values follow those of the LAS v.1.4 specifications:

LAS point classification values

Classification ValueMeaning
0Created never classified
1Unclassified3
2Ground
3Low Vegetation
4Medium Vegetation
5High Vegetation
6Building
7Low Point (noise)
8Reserved
9Water
10Rail
11Road Surface
12Reserved
13Wire – Guard (Shield)
14Wire – Conductor (Phase)
15Transmission Tower
16Wire-structure Connector (e.g. Insulator)
17Bridge Deck
18High Noise

Of course, not all LAS/zLidar files have had point classifications applied and stored. To determine whether your data contains point class data, you can run the LidarInfo tool before interpolation.

How do I remove non-ground points from my LiDAR file?


# This script is affiliated with the WhiteboxTools Geospatial analysis library 
# Authors: Anthony Francioni, Carys Owens, and John Lindsay
# Created: 01/07/2020
# Last Modified: 17/08/2020
# License: MIT

##########################################################################
# The workflow was designed to preform the WBT LidarGroundPointFilter on #
# .las or .zlidar files to remove non-ground points. This script first   #
# calls a function on the input directory to gather all files ending in  #
# the .las or .zlidar extension. It then sets up WhiteboxTools according #
# to the user's settings and runs the LidarGroundPointFilter tool on all #
# the collected .las or .zlidar files. This tool performs a slope-based  #
# classification, or filtering (i.e. removal), of non-ground points      #
# within a LiDAR point-cloud. Inter-point slopes are compared between    #
# pairs of points contained within local neighbourhoods of size --radius.#
# Neighbourhoods with fewer than the user-specified minimum number of    #
# points (--min_neighbours) are extended until the minimum point number  #
# is equaled or exceeded. Points that are above neighbouring points by   #
# the --height_threshold and have an inter-point slope greater than the  #
# --slope_threshold are considered non-ground points and are either      #
# optionally excluded from the output point-cloud or assigned the        #
# unclassified (value 1) class value (--classify). Slope-based           #
# ground-point classification methods suffer from the challenge of using #
# a constant slope threshold under varying terrain slopes. Some          #
# researchers have developed schemes for varying the slope threshold     #
# based on underlying terrain slopes. LidarGroundPointFilter instead     #
# allows the user to optionally (--slope_norm) normalize the underlying  #
# terrain (i.e. flatten the terrain) using a white top-hat transform. A  #
# constant slope threshold may then be used without contributing to      #
# poorer performance under steep topography. Note, that this option,     #
# while useful in rugged terrain, is computationally intensive. If the   #
# point-cloud is of a relatively flat terrain, this option may be        #
# excluded.                                                              #
##########################################################################

# library import statements #
import os
from WBT.whitebox_tools import WhiteboxTools # module call to WhiteboxTools. For more information see https://jblindsay.github.io/wbt_book/python_scripting/using_whitebox_tools.html)


# Function to find all the .las or z.lidar files in the input directory
def find_files (input_directory, processed_files):
    files = os.listdir(input_directory)
    file_names = []
    for f in files:
        if f.endswith(".las") or f.endswith(".zlidar") and f not in processed_files: #if filename is a .las or .zlidar file and not already processed, append the file to the list
            file_names.append(f)
    return(file_names)


def main():
    ########################
    # Set up WhiteboxTools #
    ########################
    wbt = WhiteboxTools()
    wbt.set_verbose_mode(False) # Sets verbose mode. If verbose mode is False, tools will not print output messages
    input_directory = "C:\\Insert\\Path\\to\\infile\\directory\\" # Input file directory; change to match your environment
    output_directory = "C:\\Insert\\path\\to\\output\\directory\\" # Output file directory; change to match your environment
    

    if os.path.isdir(output_directory) != True: # Creates the output directory if it does not already exist
        os.mkdir(output_directory)

    #################################################################################################
    # Script Settings: modify these as is appropriate to your use-case and desired filter settings. #
    #################################################################################################
    processed_files = [] # list of files that have been processed
    num_filtered = 1 #keeps track of how many files have been filtered 
    flag = True # flag argument.. this block of code will execute as long as true
    while flag:
        file_names = find_files(input_directory, processed_files) # calls the function to get all the las or zlidar files in the input directory
        if len(file_names) > 0: # if there is still files in the in directory 
            for i in range (len(file_names)):
                in_file = os.path.join(input_directory, file_names[i]) # creates the input file name by joining the path with the file name
                out_file = os.path.join(output_directory, file_names[i].replace(".zlidar", "_filtered.zlidar"))  # creates the out file name by joining the path with the file name... change the file type to either .las or .zlidar depending on the analysis 
                print("Processing GroundPointFilter LAS {} OF {} (total filtered = {})".format(i+1, len(file_names), num_filtered))
                # Calls the LidarGroundPointFilter on the input file; change the user parameters accordingly

                # This one is a SLOW operation, particularly when using slope_norm=True. If you are
                # confident that you have good point classification data, i.e. that the vegetation 
                # and building classes have been properly populated, this operation can likely be
                # avoided and interpolation should use the appropriate exclude_cls values.
                wbt.lidar_ground_point_filter(i=in_file, # name of input file
                output=out_file, # name of output file
                radius=2.0,
                min_neighbours=5,
                slope_threshold=45.0,
                height_threshold=0.35,
                classify=True,
                slope_norm=True,
                height_above_ground=False) 

                processed_files.append(file_names[i]) # append the processed file to the list
                num_filtered += 1 # counter to update completed files
            else:
                flag = False

    print("Complete")

main()

I have many LAS/zLidar files and want to interpolate all of them at once

When you have hundreds, or even thousands, of LAS/zLidar files you might be inclined to write a Python script that calls the above function for each input file contained within a folder. But that isn't the best way to handle this common situation. Instead, if the input (i) and output parameters are left unspecified, each of WhiteboxTool's LiDAR gridding methods will interpolate all of the LAS and zLidar files in the working directory, e.g.

# This script is affiliated with the WhiteboxTools Geospatial analysis library 
# Authors: Anthony Francioni, Carys Owens, and John Lindsay
# Created: 01/07/2020
# Last Modified : 17/08/2020
# License: MIT

##########################################################################
# This script calls the WhiteboxTools LidarTinGridding Tool on an entire #
# input directory containing either .las or .zlidar (LiDAR) files. This  #
# tool creates a raster grid based on a Delaunay triangular irregular    #
# network (TIN) fitted to LiDAR points. The current settings include     #
# using the last return elevation points, although this can be modified  #
# by the user in the script settings section. The exclude_cls parameter  #
# allows you to optionally exclude listed point classes from the         #
# interpolation; Valid class values range from 0 to 18, based on the LAS #
# specifications.                                                       #
#                                                                        #
# This script makes use of batch processing in which the input include   #
# and entire directory of .las or .zlidar files. This is more beneficial #
# than interpolating individual LiDAR files, which would not be as       #
# computationally efficient and can result in an edge effect in the      #
# interpolated raster. When calling the entire directory as input, the   #
# tool will use points in a small buffer area extending into             #
# neighbouring tiles to reduce edge effects. These edge effects are      #
# noticable in mosaicked DEMs derived from multiple tiles that have been #
# interpolated individually. They are apparent as vertical/horizontal    #
# stripping that are particularly obvious in a hillshade raster. Note    #
# most of WhiteboxTools LiDAR tools can be run in this batch mode on     #
# entire directories of LAS/zLidar files. This can make working with     #
# many hundreds or even thousands of tiles an efficient task.            #
##########################################################################

# library import statements
import os
from WBT.whitebox_tools import WhiteboxTools # module call to WhiteboxTools... for more information see https://jblindsay.github.io/wbt_book/python_scripting/using_whitebox_tools.html)


# Function to gather the file names of TIF files and puts them in a list
def find_tif_files(input_directory): # finds TIF files in an input directory
    files = os.listdir(input_directory)
    file_names = []
    for f in files:
        if f.endswith(".tif"): #change accordingly for appropriate raster type 
            file_names.append(f)
    return file_names


def main():
    ########################
    # Set up WhiteboxTools #
    ########################
    wbt = WhiteboxTools()
    wbt.set_verbose_mode(False) # Sets verbose mode. If verbose mode is False, tools will not print output messages
    wbt.set_compress_rasters(True) # Compressed TIF file format based on the DEFALTE algorithm
    in_directory = "C:\\Insert\\Path\\to\\infile\\directory\\" # Input file directory; change to match your environment
    output_dir = "C:\\Path\\to\\output\\directory\\" # Output file directory; change to match your environment
   

    ###################################################################################################
    # Script Settings: modify these as is appropriate to your use-case and desired gridding settings. #
    ###################################################################################################

    # Set the working dir: This should be teh location of the input files
    # Note: This location will also be the location of the output files
    wbt.set_working_dir(in_directory)


    # The line below executes the LidarTinGridding tool with the example parameters.
    # Please change the parameters to suit the needs of your analysis.
    # Notice how the 'i' or 'input' parameter isn't set, which you would do if you wanted
    # to interpolate a single file. By leaving it un-specified, the tool will discover all
    # .las and/or .zlidar files contained within the working directory, and each will be 
    # interpolated. This method has the added benefit that the tool will grab points within 
    # a buffer area extending into adjacent tiles, thereby reducing edge effects.
    wbt.lidar_tin_gridding(parameter="elevation", 
    returns="last", # A DEM or DTM is usually obtained from the "last" returns, a DSM uses "first" returns (or better, use the lidar_digital_surface_model tool)
    resolution=0.5, # This is the spatial resolution of the output raster in meters and should depend on application needs and point density.
    exclude_cls= "9,10,18", # Example of classified points to be excluded from analysis i.e. class 9 is water.
    minz=None,
    maxz=None,
    max_triangle_edge_length=15.0
    )
    print("Completed TIN interpolation \n")

    # Mosaic the individual tiles.
    outfile = os.path.join(output_dir,"NAME_OFF_FILE.tif") # Creates the output file by joining the output directory with the output file name.
    wbt.mosaic(output=outfile,
    method = "nn" # Uses the nearest-neighbour resampling method (i.e. nn). Cubic convolution (i.e. cc) and bilinear interpolation (i.e. bilinear) are other options.
    ) 
    print("Completed mosaic \n")

    # Delete intermediate TIFF files
    print("Deleting intermediate TIF files")
    delete_single_tif_files = find_tif_files(in_directory) # Gets the intermediate TIFF files and deletes them
    for i in range(len(delete_single_tif_files)):
        os.remove(os.path.join(in_directory, delete_single_tif_files[i]))
        print("Deleting TIF files {} of {}".format(i+1, len(delete_single_tif_files)))

    print("Complete!")
    
main()

Using this approach to folder-based interpolation has some advantages other than a greatly simplified script. WhiteboxTools will be able to parallelize the operation better, greatly improving the overall time required to interpolate the batch of files. Also, the gridding operations will be carried out with a strip of buffered data surrounding each LiDAR tile, i.e. there will be reduced edge-effects. This will reduce the potential for artifacts in the final mosaiced DEM.

What if my data contains anomalously high/low points?

This is a fairly common problem with LiDAR data. If you're fortunate, these points, which often fall hundreds of meters above or below the terrain surface, will be classified appropriately. When this is the case, you may simply exclude the points with class values of 7 (low point) and 18 (high point). Alternatively, you may use the optional minz and maxz interpolation parameters to exclude unclassified outlier points. Lastly, you may remove these points from the original point cloud data set using the LidarRemoveOutliers tool.

My data are in LAZ format. How do I interpolate them?

WhiteboxTools does not currently support the compressed LiDAR format LAZ. To use these data, you will first need to decompress the files to a LAS format. You may wish to use LasTools for this purpose. You may also want to convert the LAS files into the zLidar compressed LiDAR format which is supported.

How do I convert LAS or LAZ to zLidar?

The LasToZlidar tool can be used to convert one ore more LAS files to the zLidar compressed LiDAR format. Converting LAZ files into the zLidar format requires a more complex workflow because the LASTools library is needed.

# This script is affiliated with the WhiteboxTools Geospatial analysis library 
# Authors: Anthony Francioni, Carys Owens, John Lindsay
# Created: 01/07/2020
# Last Modified : 17/08/2020
# License: MIT

################################################################################
# This workflow converts .laz files into a .zlidar files. This script uses the #
# LAS file format only as an intermediary file. This script first utilizes the #
# laszip tool from LAStools to convert a .laz files in the user defined input  #
# directory to .las files. Futhermore this conversion is parallelized to       #
# decrease processing time by taking advantage of multiple CPU cores. A        #
# user-defined parameter called Num_Batch_Files in the "Set up parameters"     #
# section should be set to the number of .laz files to be included in bacth    #
# processing at a time. This is helpful for computers with limited storage as  #
# las files can be quite large and since they are only an intermediate file    #
# type, they should not take up excess computer storage.                       #                                            #                                                                              #
#   Once the .laz files are gathered, they are then converted to .las files    #
# using laszip command from LAStools. The path to the laszip executable should #
# be set prior to executing this script. Next, the LAStozlidar tool from       #
# WhiteboxTools is applied to all .las files, converting them to .zlidar       #
# files. The .las files are then deleted to reduce redundancy as they are now  #
# held in the output directories as .zlidar file types, and the original .laz  #
# files are still held in their original directory. LAStools software is       #
# required for these tasks to be completed.                                    #
#                                                                              #
# How to install LAStools:                                                     #
# LAStools is available for free download at https://rapidlasso.com/lastools/. #
# Once downloaded, ensure the executable laszip.exe is present in the defined  #
# laszip_exe path in the "Set up LAStools" section of the script.              #
################################################################################

# library import statements #
import os, sys, subprocess
from subprocess import CalledProcessError, Popen, PIPE, STDOUT
import multiprocessing as mp 
from WBT.whitebox_tools import WhiteboxTools # Module call to WhiteboxTools. For more information see https://jblindsay.github.io/wbt_book/python_scripting/using_whitebox_tools.html)

########################################
# List of Defined Functions for main() #
########################################
def total_num_files(input_dir): # Gets the number of laz files in an input directory
    files = os.listdir(input_dir)
    file_names = []
    for f in files:
        if f.endswith(".laz"): # Only count file names that end with .laz
            file_names.append(f)
    return file_names


def find_las_files(input_dir): # Finds all las files in an input directory and returns them in a list
    files = os.listdir(input_dir)
    file_names = []
    for f in files:
        if f.endswith(".las"): # Only select file names that end with .las
            file_names.append(f)
    return file_names


def find_laz_files(input_dir, processed_files, max_num = 1): # Finds a specific number of laz files in an input directory
    files = os.listdir(input_dir)
    file_names = []
    for f in files:
        if f.endswith(".laz") and f not in processed_files: # Only select file names that end with .laz and have not already been selected
            if len(file_names) < max_num:
                file_names.append(f)
            else:
                break
    return file_names

###################
# Set up LAStools #
###################
def parallelize_zip(in_files_list): # Converts laz to las using the laszip tool in LAStools 
    laszip_exe = "C:\\Path\\to\\laszip.exe" # Where lazsip executable exists 
    input_dir = "C:\\Path\\to\\input\\directory\\" # Input laz file directory; change this based on your computer environment
    out_dir = "C:\\Path\\to\\output\\directory\\" # Output LAS file directory; change this based on your computer environment

    Tile_name = os.path.join(input_dir, in_files_list) # Creates the full path name  of the .laz tile of interest
    LAZ_tile_name = in_files_list
    output_las_file = out_dir + LAZ_tile_name.replace(".laz", ".las") # Creates the output file ending with .las
    print("Processing LAZ to LAS for {}".format(LAZ_tile_name))
    args = [laszip_exe, Tile_name, "-o", output_las_file] # Execute laszip tool
    proc = subprocess.Popen(args, shell=False)
    proc.communicate() # Wait for las zip to finish executing
    return output_las_file


def main():
    #########################
    # Set up Whitebox Tools #
    #########################
    wbt = WhiteboxTools()
    wbt.set_verbose_mode(True) # Sets verbose mode. If verbose mode is False, tools will not print output messages
    input_LAZ_dir = "C:\\Path\\to\\input\\LAZ\\directory\\" # Input LAZ file directory; change this based on your computer environment
    out_las_file_dir = "C:\\Path\\to\\las\\output\\directory\\" # Output LAS directory; change this based on your computer environment
    out_zlidar_file_dir = "C:\\Path\\to\\zlidar\\output\\directory\\" # Output zlidar directory; change this based on your computer environment

    if os.path.isdir(out_las_file_dir) != True: # Creates the las output directory if it does not already exist
        os.mkdir(out_las_file_dir)
    
    if os.path.isdir(out_zlidar_file_dir) != True: # Creates the zlidar output directory if it does not already exist
        os.mkdir(out_zlidar_file_dir)
    
    #####################
    # Set up parameters #
    #####################
    num_batch_file = 8 # Number of laz files to be used at a time: change this to how many files you want per batch (make sure it is less than or equal to the total number of .las files to be converted) 
    pool = mp.Pool(mp.cpu_count()) # Multi-threaded command, counts number of cores user's CPU has

    # Start of processing
    processed_files = [] 
    total_files = total_num_files(input_LAZ_dir) # Gets the total number of files 
    flag = True # flag argument, this block of code will execute as long as true
    while flag:
        laz_file_names = find_laz_files(input_LAZ_dir, processed_files, num_batch_file) # Call function to get laz files
        if len(laz_file_names) >= 1: # Has to be zero or less than/equal to 1 in order to account for when only 1 file left 
            in_list = ""
            for i in range(len(laz_file_names)): # Go through files in directory to be used as the input files
                if i < len(laz_file_names)-1:
                    in_list += f"{laz_file_names[i]};"
                else:
                    in_list += f"{laz_file_names[i]}"
                processed_files.append(laz_file_names[i])

            pool.map(parallelize_zip, laz_file_names) # Calls the parallelizing function on .LAZ to convert to .LAS
            print("Number of completed files {} of {}\n".format(len(processed_files), len(total_files)))

            # Convert LAS to zlidar
            wbt.set_working_dir(out_las_file_dir) # Set working dir to location of .LAS files needed to be converted
            print("Converting LAS to zLidar")
            wbt.las_to_zlidar(outdir=out_zlidar_file_dir) # Calls the WBT tool las_to_zlidar to convert .LAS files to .zlidar files

            # Delete LAS
            delete_files = find_las_files(out_las_file_dir) # Gets names of .LAS files in the .LAS directory and deletes them to decrease redundancy
            for a in range(len(delete_files)):
                os.remove(os.path.join(out_las_file_dir, delete_files[a]))
                print("Deleting LAS files {} of {}".format(a+1, len(delete_files)))
        
        else:
            flag = False


if __name__ == "__main__" :
    main()
    print("script complete")

How do I interpolate an image from the intensity data?

The parameter argument of the IDW and nearest neighbour interpolator tools allows you to interpolate intensity data (options include 'elevation', 'intensity', 'class', 'scan angle', and 'user data'). Here is an example:

from WBT.whitebox_tools import WhiteboxTools

wbt = WhiteboxTools()
wbt.wbt.set_working_dir("/path/to/data/")

wbt.lidar_nearest_neighbour_gridding(
"in.las", "out.tif", parameter="intensity")

How do I decide on an appropriate grid resolution?

You want to choose a grid resolution where the vast majority of grid cells in the area covered by data have at least one return point. If you are interpolating with last-return points only, then this will necessarily reduce the potential resolution. Ultimately, there is not single appropriate value and the range of suitable resolutions will depend on the distribution of point density with the area of coverage. If the specified resolution is too high given the point density of the LiDAR data set, many of the grid cells will either be NoData holes, or represent interpolated values from relatively distant (up to the search radius) points. A higher than necessary grid resolution will also make working with the final mosaiced DEM raster more challenging, due to the computational effort needed to work with massive rasters and increase the storage and memory requirements. It is advisable to experiment with the LidarPointDensity and LidarPointStats tools before deciding upon a grid resolution for interpolation.

My raster contains NoData gaps. How do I remove these?

First, we need to distinguish between two common areas of NoData values in the interpolated rasters of LiDAR data sets. Because LiDAR data are often collected for irregularly shaped sites, it is frequently the case that LiDAR DEMs have large NoData areas beyond the area of LiDAR point coverage. These are generally acceptable void areas and should not be altered. The more problemmatic void areas are interior data gaps (so called doughnut holes). These generally arise because the point density in an area of LiDAR coverage is lower than the grid resolution (and search radius) dictate in an area. Sometimes these NoData areas are associated with specific non-reflective surfaces, such as water, or areas of dense vegetation (and therefore the last return point density is far lower than in other areas). If the NoData gaps are extensive and spread throughout he area of coverage, that is a sign that you likely need to interpolate either with a coarser grid resolution or a larger search radius, or quite probably both. If your LiDAR DEM has a small number these void areas, and they are not extensive, then you may interpolate to remove the gaps using the FillMissingData tool:

from WBT.whitebox_tools import WhiteboxTools

wbt = WhiteboxTools()
wbt.wbt.set_working_dir("/path/to/data/")

wbt.fill_missing_data("dem.tif", "new_dem.tif", filter=11)

The choice of a filter size will depend on the extent of the largest interior void area.

How do I combine many LiDAR tiles into a single raster?

Often you have many hundred LAS/zLidar files, which you've interpolated into an equally large number of raster files. To combine these rasters into a single large DEM, use the Mosaic tool.

# This script is affiliated with the WhiteboxTools Geospatial analysis library 
# Authors: Anthony Francioni, Carys Owens, and John Lindsay
# Created: 01/07/2020
# Last Modified: 17/08/2020
# License: MIT


######################################################################################
# This script creates an image mosaic from one or more input image files using the   #
# Mosaic tool from Whitebox tools. This tool uses one of three user-defined          #
# resampling methods (--method) including, nearest neighbour ("nn"), bilinear        #
# interpolation ("bilinear"), and cubic convolution ("cc").                          #
#                                                                                    #
# The order of the input source image files is important. Grid cells in the output   #
# image will be assigned the corresponding value determined from the last image      #
# found in the list to possess an overlapping coordinate.                            #
#                                                                                    #
# Note that when the --inputs parameter is left unspecified, the tool will use all   #
# of the raster files of supported data formats located in the working directory.    #
#                                                                                    #
# This is the preferred mosaicing tool to use when appending multiple images with    #
# little to no overlapping areas, e.g. tiled data. When images have significant      #
# overlap areas, users are advised to use the MosaicWithFeathering tool instead.     #
######################################################################################

# Library import statements
import os
from WBT.whitebox_tools import WhiteboxTools # Module call to WhiteboxTools. For more information see https://jblindsay.github.io/wbt_book/python_scripting/using_whitebox_tools.html)


def main():
    #########################
    # Set up Whitebox tools #
    #########################
    wbt = WhiteboxTools()
    wbt.set_verbose_mode(True) # Sets verbose mode. If verbose mode is False, tools will not print output messages as they run
    wbt.set_compress_rasters(True) # Compressed TIF file format based on the DEFALTE algorithm
    
    ##########################
    # Set up tool parameters #
    ##########################
    input_directory = "C:\\Path\\to\\input\\files\\" # Input directory; change to match user environment
    output_directory = "C:\\Path\\to\\output\\directory\\" # Output directory; change to match yours
    
    if os.path.isdir(output_directory) != True: # Creates output dir if it does not already exist 
        os.mkdir(output_directory)      
    
    ################
    # Run the tool #
    ################
    wbt.set_working_dir(input_directory) # Set the working dir: This should be teh location of the input files #
    outfile = os.path.join(output_directory,"NAME_OF_FILE.tif") # Create the output file by joining the output directory path with the name of file
    # Calls mosaic tool with nearest neighbour as the resampling method ("nn")
    if wbt.mosaic(
        output=outfile, 
        method = "nn"
    ) != 0:
        # Non-zero returns indicate an error.
        print('ERROR running mosaic')
    
    print("Complete!")

main()

What is the workflow after mosaicking my DEM?

The following code is an example of some of the common tasks required in processing large LiDAR datasets.

import os
from os import path
from WBT.whitebox_tools import WhiteboxTools

def main():

    input_directory = "C:\\Path\\to\\input\\files\\" # Input directory; change to match user environment

    wbt = WhiteboxTools()
    wbt.set_working_dir(input_directory) # Set working directory
    wbt.verbose = False
    if not os.path.exists(filtered_las_dir):
        os.makedirs(filtered_las_dir)

    ##############################################
    # Would you like to fill in the NoData gaps? #
    ##############################################
    dem_nodata_filled = input_directory + "DEM_gaps_filled.tif"
    wbt.fill_missing_data(
        mosaic_file, 
        dem_nodata_filled, 
        filter=11
    )


    ######################################################################
    # I usually remove off-terrain objects, like any remaining buildings #
    ######################################################################
    dem_no_otos = input_directory + "DEM_no_OTOs.tif"
    wbt.remove_off_terrain_objects(
        dem_nodata_filled, 
        dem_no_otos, 
        filter=11, 
        slope=15.0
    )


    #####################################
    # Would you like to smooth the DEM? #
    #####################################
    dem_smoothed = input_directory + "DEM_smoothed.tif"
    wbt.feature_preserving_denoise(
        dem_no_otos, 
        dem_smoothed, 
        filter=11, 
        norm_diff=8.0
    )


    ################################
    # Want to fix the depressions? #
    ################################
    dem_breached = input_directory + "DEM_breached.tif"
    # Set the maximum breach depth appropriate for the terrain. You can
    # also restrict breaching based on a maximum breach channel length (dist).
    wbt.breach_depressions_least_cost(
        dem=dem_smoothed, 
        output=dem_breached, 
        dist=100.0, 
        max_cost=10.0, 
        min_dist=True, 
        flat_increment=None, 
        fill=True
    )


    ####################################################################
    # Okay, now we have a good base DEM from which we can extract      #
    # various land-surface parameters. There are really a large        #
    # number of these parameters available, but I'll just showcase     #
    # a few common ones here. See the User Manual for a complete list. #
    ####################################################################

    # slope
    slope_file = input_directory + "slope.tif"
    wbt.slope(dem_filled, slope_file)

    # plan curvature
    plan_curv_file = input_directory + "plan_curv.tif"
    wbt.plan_curvature(dem_filled, plan_curv_file)

    # profile curvature; other curvatures are available too.
    profile_curv_file = input_directory + "profile_curv.tif"
    wbt.profile_curvature(dem_filled, profile_curv_file)

    # hillshade (shaded relief raster)
    hillshade_file = input_directory + "hillshade.tif"
    wbt.hillshade(dem_filled, hillshade_file)

    # relative topographic position (RTP) index
    rtp_file = input_directory + "relative_topographic_position.tif"
    wbt.relative_topographic_position(dem_filled, rtp_file, filterx=11, filtery=11)

    # or even better, multiscale topographic position
    dev_max_mag = input_directory + "multiscale_topo_position_mag.tif"
    dev_max_scale = input_directory + "multiscale_topo_position_scale.tif"
    wbt.max_elevation_deviation(dem_filled, dev_max_mag, dev_max_scale, min_scale=1, max_scale=100, step=2)

    # ruggedness index
    ruggedness_index_file = input_directory + "ruggedness_index.tif"
    wbt.ruggedness_index(dem_filled, ruggedness_index_file)

    # or even better, multiscale roughness
    roughness_mag = input_directory + "multiscale_roughness_mag.tif"
    roughness_scale = input_directory + "multiscale_roughness_scale.tif"
    wbt.multiscale_roughness(dem_filled, roughness_mag, roughness_scale, min_scale=1, max_scale=100, step=2)

    # D-infinity flow accumulation
    flow_accum_file = input_directory + "dinf_flow_accum.tif"
    wbt.d_inf_flow_accumulation(dem_filled, flow_accum_file, log=True)

    # There literally hundreds of other useful parameters that could be
    # extracted from our DEM using WhiteboxTools. Take a look at the User Manual.


    print("Done!")


main()

Is there a video tutorial on working with LiDAR data?

Yes there is, and you can watch it on YouTube here

Supported Data Formats

Raster formats

The WhiteboxTools library can currently support reading/writing raster data in several common formats.

FormatExtensionReadWrite
GeoTIFF*.tif, *.tiffXX
Big GeoTIFF*.tif, *.tiffXX
Esri ASCII*.txt, *.ascXX
Esri BIL*.bil, *.hdrXX
Esri Binary*.flt and *.hdrXX
GRASS ASCII*.txt, *.ascXX
Idrisi*.rdc and *.rstXX
SAGA Binary*.sdat and *.sgrdXX
Surfer ASCII*.grdXX
Surfer Binary*.grdXX
Whitebox*.tas and *.depXX

Throughout this manual code examples that manipulate raster files all use the GeoTIFF format (.tif) but any of the supported file extensions can be used in its place.

The library is primarily tested using Whitebox raster and GeoTIFF data sets and if you encounter issues when reading/writing data in other formats, you should report the issue.

WhiteboxTools is able to read GeoTIFFs compressed using the PackBits, DEFLATE, and LZW methods. Compressed GeoTIFFs, created using the DEFLATE algorithm, can also be output from any tool that generates raster output files by using the --compress_rasters command line flag. If using the Python WhiteboxTools API, you can set the flag by using the set_compress_rasters method (e.g. wbt.set_compress_rasters(True)). The default is False. GeoTIFF output file compression can be set in the WhiteboxTools Runner Multi-band GeoTIFFs are not currently supported.

Please note that there are no plans to incorporate third-party libraries, like GDAL, in the project given the design goal of keeping a pure (or as close as possible) Rust codebase without third-party dependencies. This design greatly simplifies installation of the library but significantly complicates the development by necessitating hand-rolled encoders/decoders for various raster data formats. For more complicated file formats, particularly the ubiquitous GeoTIFF format, it will take time to develop a mature and bug-free encoder/decoder and it is likely that we will only ever be able to support a sub-set of the possible GeoTIFF raster types. It is helpful if users who encounter raster-format related issues report their problems complete with descriptions of the error (What tool was being used? What type of data were input? How far along was the execution before the error was thrown? What was the error message?) and if possible submit a copy of the problematic file.

Vector Formats

At present, there is limited support in WhiteboxTools for working with vector geospatial data formats. The only supported vector format is the ESRI Shapefile. Shapefiles geometries (.shp) and attributes (.dbf) can be read and written. There are plans to support a wider variety of vector file formats in the future.

While the Shapefile format is extremely common, it does have certain limitations for vector representation. For example, owing to their 32-bit indexing, Shapefiles are limited in the number of geometries that can be stored in these files. Furthermore, Shapefiles are incapable of storing geometries of more than one type (point, lines, polygons) within the same file. As such, the vector-related tools in WhiteboxTools also carry these same limitations imposed by the Shapefile format.

Point Cloud (LiDAR) Formats

LiDAR data can be read/written in the common LAS and compressed LAZ (as of v1.6.0) data formats. WhiteboxTools also supports the losslessly compressed open-source zLidar data format. WhiteboxTools can also read and write LAS files that have been compressed (zipped with a .zip extension) using the common DEFLATE algorithm. Note that only LAS file should be contained within a zipped archive file. The following is an example of running a LiDAR tool using zipped input/output files:

>>./whitebox_tools -r=LidarTophatTransform -v --wd="/path/to/data/"
-i="input.las.zip" -o="output.las.zip" --radius=10.0

Note that the double extensions (.las.zip) in the above command are not necessary and are only used for convenience of keeping track of LiDAR data sets (i.e. .zip extensions work too). The extra work of decoding/encoding compressed files does add additional processing time, although the Rust compression library that is used is highly efficient and usually only adds a few seconds to tool run times. Zipping LAS files frequently results 40-60% smaller binary files, making the additional processing time worthwhile for larger LAS file data sets with massive storage requirements.

Note: The Esri LiDAR format is not currently supported in WhiteboxTools. The ESRI format is proprietary and closed-source, making it impossible to write an encoder/decoder for this file format.

Contributing and Reporting Bugs

If you would like to contribute financial support to the project, the best way to proceed is to purchase a license for one of the WhiteboxTools Extension products or by purchasing a WhiteboxTools Open-Core binary. The proceeds from the sales go towards paying developers who work on the open-core portion of the WhiteboxTools platform. Each license sale goes a long way towards making the ongoing development of WhiteboxTools more sustainable.

If you would like to contribute to the project as a developer, follow these instructions to get started:

  1. Fork the WhiteboxTools project ( https://github.com/jblindsay/whitebox-tools )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion in the work shall be licensed under the MIT License without any additional terms or conditions.

We also welcome contributions in the form of media exposure. If you have written an article or blog about WhiteboxTools please let us know about it (support@whiteboxgeo.com).

WhiteboxTools is distributed as is and without warranty of suitability for application. If you encounter flaws with the software (i.e. bugs) please report the issue. Providing a detailed description of the conditions under which the bug occurred will help to identify the bug. Use the Issues tracker on GitHub to report issues with the software and to request feature enchancements. Please do not email Dr. Lindsay directly with bugs.

Known Issues and Limitations

  • The zLAS (Esri) compressed LiDAR data format is currently unsupported although LAZ, zLidar, and zipped LAS files (.zip) compressed LiDAR data formats are.
  • There is no support for reading waveform data contained within or associated with LiDAR files.
  • File directories cannot contain apostrophes (', e.g. /John's data/) as they will be interpreted in the arguments array as single quoted strings. File directories also should not contain periods ('.'). In fact, it is best to avoid any special characters in directories containing data, or the directory in which WBT is installed.
  • The Python scripts included with WhiteboxTools require Python 3. They will not work with Python 2, which is frequently the default Python version installed on many systems.
  • Not all types of GeoTIFF files are supported. The GeoTIFF format is very flexible and certain less common varieties may not be read properly by WhiteboxTools. The WhiteboxTools GeoTIFF reader/writer is a custom implementation and does not rely on other library (e.g. GDAL) and therefore there may be difficulties when exchanging GeoTIFF data between WhiteboxTools and GDAL supported software.

Memory Requirements

People sometimes ask me what the memory requirements of WhiteboxTools is. There is no simple answer to this question because each tool has different memory requirements. The memory requirements of a tool will depend on a number of factors. Clearly the tools that read and write raster data have among the largest memory requirements, although the LiDAR tools will also have substantial memory footprints compared with others as well. When you are working with raster data, say a digital elevation model (DEM) data set, a good convention is that the minimum memory that your system will need is at least 4X greater than the size of your data set. Likely you will want to ensure that you have more than this minimum, i.e. 5-10X is an appropriate range.

However, there are some important factors to consider when trying to calculate the memory that you'll need to process a data set. First, whatever size your raster file is on disc does not relate to how large it will be when read into memory. Raster files are commonly compressed, e.g. GeoTIFFs are usually compressed) and the actual uncompressed size of the file may be considerably larger. The number of grid cells (rows x columns) and the data type (bit depth) are better indicators of memory size than is the file size. Secondly, when WhiteboxTools reads your file, it will convert the grid cell values into 64-bit floating point values, while it is quite likely that the data set contains data in a smaller data type. For example, it is common for DEM data to be stored as 32-bit floats, meaning that the in-memory footprint of your DEM will be doubled. Why does WhiteboxTools do this? When WhiteboxTools reads your raster file, it converts it into a generic raster format that is then fed to the tool that you are running. The tool likely needs to read individual grid cell values. For example, it may scan an input raster DEM cell-by-cell and place the cell values into a variable (z = dem.get_value(row, col)) to then work with. The variable z needs to have a data type assigned to it at compile time and it cannot know in advance what type of data will be contained within your file. And so it will be assigned a data type that is large enough to hold (after conversion) any data type that the user may throw at it--a 64-bit float in most cases. This approach greatly simplifies the code for tools compared with the alternative by which each possible input data type is handled in separate code paths. The main implication of this approach is that whatever the uncompressed data size of your input raster file is, it will likely be doubled (if it is 32-bit data on disc), or even quadrupled (if it is 16-bit data on disc), when it is read into memory.

Furthermore, in addition to the memory requirements of the input raster, most tools need to create an output file, which exists in memory before being written into a file at the end of operation. This is why it was stated above that the minimum memory requirement is 4X the size of the data set (8X if it is in 16-bit form on disc), i.e. a doubling for the data type issue and another doubling for the input/output raster of the tool. Many tool, particularly those that perform complex tasks beyond simply scanning the data in a filter-type operation, will also have intermediate data that are often in the form of in-memory rasters or data structures used for spatial searches. This further increases the memory requirements of individual tools. I always try to develop tools so that they have as modest memory requirements as possible. However, in developing WhiteboxTools, I have made certain design decisions that favour speed over memory footprint. This is why I frequently get feedback from users that WhiteboxTools is impressively fast. The relation between performance speed and memory requirements is a balance and Whitebox has certainly favoured speed. This was an intentional design decision in recognition that 1) system memory has increased significantly since 2017 when the project began and continues to do so (systems with between 64 GB and 256 GB are now widely available), and RAM is becoming cheaper, and 2) users that are working with extremely massive data set often have access to systems with large enough memory resources to handle the processing needs of WhiteboxTools when working with these types of data.

WhiteboxTools' predecessor, Whitebox GAT, was developed using the Java programming language. Java is known to use memory very inefficiently, and I would regularly have users contact me with out-of-memory issues. This was one of the main motivations that I had in developing WhiteboxTools, and for choosing the Rust programming language to do so. Using Rust for this project has afforded me significant performance gains over Java, but it has also significantly lowered the memory requirements of equivalent tools. Rust uses memory more conservatively than Java. And this is the main reason why I rarely receive feedback from users who have encountered out-of-memory issues using WhiteboxTools. It certainly can happen however, particularly if you are trying to process a large data set on a system with insufficient memory resources and without an understanding of the relationship between file size and system memory.

License

The WhiteboxTools open-core platform is distributed under the MIT license, a permissive open-source (free software) license.

The MIT License (MIT)

Copyright (c) 2017-2020 John Lindsay

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Each of the WhiteboxTools Extension products are distributed by Whitebox Geospatial Inc. under a proprietary license.

Frequently Asked Questions

Do I need Whitebox GAT to use WhiteboxTools?

No you do not. You can call the tools contained within WhiteboxTools completely independent from the Whitebox GAT user interface using a Remote Procedure Call (RPC) approach. In fact, you can interact with the tools using Python scripting or directly, using a terminal application (command prompt). See Interacting With WhiteboxTools From the Command Prompt for further details.

How do I request a tool be added?

Eventually most of the tools in Whitebox GAT will be ported over to WhiteboxTools and all new tools will be added to this library as well. Naturally, this will take time. The order by which tools are ported is partly a function of ease of porting, existing infrastructure (i.e. raster and LiDAR tools will be ported first since their is currently no support in the library for vector I/O), and interest. If you are interested in making a tool a higher priority for porting or if you have an request for a tool to be added that is not part of Whitebox GAT, i.e. a new feature, then please submit an issue to the GitHub repository. The request will be marked with the enhancement label.

Can WhiteboxTools be incorporated into other software and open-source GIS projects?

WhiteboxTools was developed with the open-source GIS Whitebox GAT in mind. That said, the tools can be accessed independently and so long as you abide by the terms of the MIT license, there is no reason why other software and GIS projects cannot use WhiteboxTools as well. In fact, this was one of the motivating factors for creating the library in the first place. Feel free to use WhiteboxTools as the geospatial analysis engine in your open-source software project.

What platforms does WhiteboxTools support?

WhiteboxTools is developed using the Rust programming language, which supports a wide variety of platforms including MS Windows, MacOS, and Linux operating systems and common chip architectures. Interestingly, Rust also supports mobile platforms, and WhiteboxTools should therefore be capable of targeting (although no testing has been completed in this regard to date). Nearly all development and testing of the software is currently carried out on MacOS and we cannot guarantee a bug-free performance on other platforms. In particularly, MS Windows is the most different from the other platforms and is therefore the most likely to encounter platform-specific bugs. If you encounter bugs in the software, please consider reporting an issue using the GitHub support for issue-tracking.

What are the system requirements?

The answer to this question depends strongly on the type of analysis and data that you intend to process. However, generally we find performance to be optimal with a recommended minimum of 8-16GB of memory (RAM), a modern multi-core processor (e.g. 64-bit i5 or i7), and an solid-state-drive (SSD). It is likely that WhiteboxTools will have satisfactory performance on lower-spec systems if smaller datasets are being processed. Because WhiteboxTools reads entire raster datasets into system memory (for optimal performance, and in recognition that modern systems have increasingly larger amounts of fast RAM), this tends to be the limiting factor for the upper-end of data size successfully processed by the library. 64-bit operating systems are recommended and extensive testing has not been carried out on 32-bit OSs. See "What platforms does WhiteboxTools support?" for further details on supported platforms.

Are pre-compiled executables of WhiteboxTools available?

Pre-compiled binaries for WhiteboxTools can be downloaded from the Whitebox Geospatial Inc. homepage software web site for various supported operating systems. The website also contains the binaries for each of the WhiteboxTools Extension products. If you need binaries for other operating systems/system architectures, you will need to compile the executable from source files. See Installation for details.

Why is WhiteboxTools programmed in Rust?

I spent a long time evaluating potential programming language for future development efforts for the Whitebox GAT project. My most important criterion for a language was that it compile to native code, rather than target the Java virtual machine (JVM). I have been keen to move Whitebox GAT away from Java because of some of the challenges that supporting the JVM has included for many Whitebox users. The language should be fast and productive--Java is already quite fast, but if I am going to change development languages, I would like a performance boost. Furthermore, given that many, though not all, of the algorithms used for geospatial analysis scale well with concurrent (parallel) implementations, I favoured languages that offered easy and safe concurrent programming. Although many would consider C/C++ for this work, I was looking for a modern and safe language. Fortunately, we are living through a renaissance period in programming language development and there are many newer languages that fit the bill nicely. Over the past two years, I considered each of Go, Rust, D, Nim, and Crystal for Whitebox development and ultimately decided on Rust. [See GoSpatial and lidario.]

Each of the languages I examined has its own advantages of disadvantages, so why Rust? It's a combination of factors that made it a compelling option for this project. Compared with many on the list, Rust is a mature language with a vibrant user community. Like C/C++, it's a high-performance and low-level language that allows for complete control of the system. However, Rust is also one of the safest languages, meaning that I can be confident that WhiteboxTools will not contain common bugs, such as memory use-after-release, memory leaks and race conditions within concurrent code. Importantly, and quite uniquely, this safety is achieved in the Rust language without the use of a garbage collector (automatic memory management). Garbage collectors can be great, but they do generally come with a certain efficiency trade-off that Rust does not have. The other main advantage of Rust's approach to memory management is that it allows for a level of interaction with scripting languages (e.g. Python) that is quite difficult to do in garbage collected languages. Although WhiteboxTools is currently set up to use an automation approach to interacting with Python code that calls it, I like the fact that I have the option to create a WhiteboxTools shared library.

Not everything with Rust is perfect however. It is still a very young language and there are many pieces still missing from its ecosystem. Furthermore, it is not the easiest language to learn, particularly for people who are inexperienced with programming. This may limit my ability to attract other programers to the Whitebox project, which would be unfortunate. However, overall, Rust was the best option for this particular application.

Do I need Rust installed on my computer to run WhiteboxTools?

No, you would only need Rust installed if you were compiling the WhiteboxTools codebase from source files.

How does WhiteboxTools' design philosophy differ?

Whitebox GAT is frequently praised for its consistent design and ease of use. Like Whitebox GAT, WhiteboxTools follows the convention of one tool for one function. For example, in WhiteboxTools assigning the links in a stream channel network their Horton, Strahler, Shreve, or Hack stream ordering numbers requires running separate tools (i.e. HortonStreamOrder, StrahlerStreamOrder, ShreveStreamMagnitude, and HackStreamOrder). By contrast, in GRASS GIS1 and ArcGIS single tools (i.e. the r.stream.order and Stream Order tools respectively) can be configured to output different channel ordering schemes. The WhiteboxTools design is intended to simplify the user experience and to make it easier to find the right tool for a task. With more specific tool names that are reflective of their specific purposes, users are not as reliant on reading help documentation to identify the tool for the task at hand. Similarly, it is not uncommon for tools in other GIS to have multiple outputs. For example, in GRASS GIS the r.slope.aspect tool can be configured to output slope, aspect, profile curvature, plan curvature, and several other common terrain surface derivatives. Based on the one tool for one function design approach of WhiteboxTools, multiple outputs are indicative that a tool should be split into different, more specific tools. Are you more likely to go to a tool named r.slope.aspect or TangentialCurvature when you want to create a tangential curvature raster from a DEM? If you're new to the software and are unfamiliar with it, probably the later is more obvious. The WhiteboxTools design approach also has the added benefit of simplifying the documentation for tools. The one downside to this design approach, however, is that it results (or will result) in a large number of tools, often with signifcant overlap in function.

1 NOTE: It is not my intent to criticize GRASS GIS, as I deeply respect the work that the GRASS developers have contributed. Rather, I am contrasting the consequences of WhiteboxTools' design philosophy to that of other GIS.

Index of Tools

  1. AbsoluteValue: Calculates the absolute value of every cell in a raster. Found in Math and Stats Tools.

  2. AccumulationCurvature: This tool calculates accumulation curvature from an input DEM. Found in Geomorphometric Analysis.

  3. AdaptiveFilter: Performs an adaptive filter on an image. Found in Image Processing Tools → Filters.

  4. AddPointCoordinatesToTable: Modifies the attribute table of a point vector by adding fields containing each point's X and Y coordinates. Found in Data Tools.

  5. Add: Performs an addition operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  6. AggregateRaster: Aggregates a raster to a lower resolution. Found in GIS Analysis.

  7. And: Performs a logical AND operator on two Boolean raster images. Found in Math and Stats Tools.

  8. Anova: Performs an analysis of variance (ANOVA) test on a raster dataset. Found in Math and Stats Tools.

  9. ArcCos: Returns the inverse cosine (arccos) of each values in a raster. Found in Math and Stats Tools.

  10. ArcSin: Returns the inverse sine (arcsin) of each values in a raster. Found in Math and Stats Tools.

  11. ArcTan: Returns the inverse tangent (arctan) of each values in a raster. Found in Math and Stats Tools.

  12. Arcosh: Returns the inverse hyperbolic cosine (arcosh) of each values in a raster. Found in Math and Stats Tools.

  13. Arsinh: Returns the inverse hyperbolic sine (arsinh) of each values in a raster. Found in Math and Stats Tools.

  14. Artanh: Returns the inverse hyperbolic tangent (arctanh) of each values in a raster. Found in Math and Stats Tools.

  15. AsciiToLas: Converts one or more ASCII files containing LiDAR points into LAS files. Found in LiDAR Tools.

  16. Aspect: Calculates an aspect raster from an input DEM. Found in Geomorphometric Analysis.

  17. AssessRoute: This tool assesses a route for slope, elevation, and visibility variation. Found in Geomorphometric Analysis.

  18. Atan2: Returns the 2-argument inverse tangent (atan2). Found in Math and Stats Tools.

  19. AttributeCorrelationNeighbourhoodAnalysis: Performs a correlation on two input vector attributes within a neighbourhood search windows. Found in Math and Stats Tools.

  20. AttributeCorrelation: Performs a correlation analysis on attribute fields from a vector database. Found in Math and Stats Tools.

  21. AttributeHistogram: Creates a histogram for the field values of a vector's attribute table. Found in Math and Stats Tools.

  22. AttributeScattergram: Creates a scattergram for two field values of a vector's attribute table. Found in Math and Stats Tools.

  23. AverageFlowpathSlope: Measures the average slope gradient from each grid cell to all upslope divide cells. Found in Hydrological Analysis.

  24. AverageNormalVectorAngularDeviation: Calculates the circular variance of aspect at a scale for a DEM. Found in Geomorphometric Analysis.

  25. AverageOverlay: Calculates the average for each grid cell from a group of raster images. Found in GIS Analysis → Overlay Tools.

  26. AverageUpslopeFlowpathLength: Measures the average length of all upslope flowpaths draining each grid cell. Found in Hydrological Analysis.

  27. BalanceContrastEnhancement: Performs a balance contrast enhancement on a colour-composite image of multispectral data. Found in Image Processing Tools → Image Enhancement.

  28. Basins: Identifies drainage basins that drain to the DEM edge. Found in Hydrological Analysis.

  29. BilateralFilter: A bilateral filter is an edge-preserving smoothing filter introduced by Tomasi and Manduchi (1998). Found in Image Processing Tools → Filters.

  30. BlockMaximumGridding: Creates a raster grid based on a set of vector points and assigns grid values using a block maximum scheme. Found in GIS Analysis.

  31. BlockMinimumGridding: Creates a raster grid based on a set of vector points and assigns grid values using a block minimum scheme. Found in GIS Analysis.

  32. BoundaryShapeComplexity: Calculates the complexity of the boundaries of raster polygons. Found in GIS Analysis → Patch Shape Tools.

  33. BreachDepressionsLeastCost: Breaches the depressions in a DEM using a least-cost pathway method. Found in Hydrological Analysis.

  34. BreachDepressions: Breaches all of the depressions in a DEM using Lindsay's (2016) algorithm. This should be preferred over depression filling in most cases. Found in Hydrological Analysis.

  35. BreachSingleCellPits: Removes single-cell pits from an input DEM by breaching. Found in Hydrological Analysis.

  36. BreaklineMapping: This tool maps breaklines from an input DEM. Found in Geomorphometric Analysis.

  37. BufferRaster: Maps a distance-based buffer around each non-background (non-zero/non-nodata) grid cell in an input image. Found in GIS Analysis → Distance Tools.

  38. BurnStreamsAtRoads: Burns-in streams at the sites of road embankments. Found in Hydrological Analysis.

  39. CannyEdgeDetection: This tool performs a Canny edge-detection filter on an input image. Found in Image Processing Tools → Filters.

  40. Ceil: Returns the smallest (closest to negative infinity) value that is greater than or equal to the values in a raster. Found in Math and Stats Tools.

  41. CentroidVector: Identifies the centroid point of a vector polyline or polygon feature or a group of vector points. Found in GIS Analysis.

  42. Centroid: Calculates the centroid, or average location, of raster polygon objects. Found in GIS Analysis.

  43. ChangeVectorAnalysis: Performs a change vector analysis on a two-date multi-spectral dataset. Found in Image Processing Tools.

  44. CircularVarianceOfAspect: Calculates the circular variance of aspect at a scale for a DEM. Found in Geomorphometric Analysis.

  45. ClassifyBuildingsInLidar: Reclassifies a LiDAR points that lie within vector building footprints. Found in LiDAR Tools.

  46. ClassifyLidar: Classify points within a LiDAR point cloud based on point properties. Found in LiDAR Tools.

  47. ClassifyOverlapPoints: Classifies or filters LAS points in regions of overlapping flight lines. Found in LiDAR Tools.

  48. CleanVector: Removes null features and lines/polygons with fewer than the required number of vertices. Found in Data Tools.

  49. ClipLidarToPolygon: Clips a LiDAR point cloud to a vector polygon or polygons. Found in LiDAR Tools.

  50. ClipRasterToPolygon: Clips a raster to a vector polygon. Found in GIS Analysis → Overlay Tools.

  51. Clip: Extract all the features, or parts of features, that overlap with the features of the clip vector. Found in GIS Analysis → Overlay Tools.

  52. Closing: A closing is a mathematical morphology operation involving an erosion (min filter) of a dilation (max filter) set. Found in Image Processing Tools.

  53. Clump: Groups cells that form discrete areas, assigning them unique identifiers. Found in GIS Analysis.

  54. ColourizeBasedOnClass: Sets the RGB values of a LiDAR point cloud based on the point classification values. Found in LiDAR Tools.

  55. ColourizeBasedOnPointReturns: Sets the RGB values of a LiDAR point cloud based on the point returns. Found in LiDAR Tools.

  56. CompactnessRatio: Calculates the compactness ratio (A/P), a measure of shape complexity, for vector polygons. Found in GIS Analysis → Patch Shape Tools.

  57. ConditionalEvaluation: Performs a conditional evaluation (if-then-else) operation on a raster. Found in Math and Stats Tools.

  58. ConditionedLatinHypercube: Implements conditioned Latin Hypercube sampling. Found in Math and Stats Tools.

  59. ConservativeSmoothingFilter: Performs a conservative-smoothing filter on an image. Found in Image Processing Tools → Filters.

  60. ConstructVectorTin: Creates a vector triangular irregular network (TIN) for a set of vector points. Found in GIS Analysis.

  61. ContoursFromPoints: Creates a contour coverage from a set of input points. Found in Geomorphometric Analysis.

  62. ContoursFromRaster: Derives a vector contour coverage from a raster surface. Found in Geomorphometric Analysis.

  63. ConvertNodataToZero: Converts nodata values in a raster to zero. Found in Data Tools.

  64. ConvertRasterFormat: Converts raster data from one format to another. Found in Data Tools.

  65. CornerDetection: Identifies corner patterns in boolean images using hit-and-miss pattern matching. Found in Image Processing Tools → Filters.

  66. CorrectVignetting: Corrects the darkening of images towards corners. Found in Image Processing Tools → Image Enhancement.

  67. Cos: Returns the cosine (cos) of each values in a raster. Found in Math and Stats Tools.

  68. Cosh: Returns the hyperbolic cosine (cosh) of each values in a raster. Found in Math and Stats Tools.

  69. CostAllocation: Identifies the source cell to which each grid cell is connected by a least-cost pathway in a cost-distance analysis. Found in GIS Analysis → Distance Tools.

  70. CostDistance: Performs cost-distance accumulation on a cost surface and a group of source cells. Found in GIS Analysis → Distance Tools.

  71. CostPathway: Performs cost-distance pathway analysis using a series of destination grid cells. Found in GIS Analysis → Distance Tools.

  72. CountIf: Counts the number of occurrences of a specified value in a cell-stack of rasters. Found in GIS Analysis → Overlay Tools.

  73. CreateColourComposite: Creates a colour-composite image from three bands of multispectral imagery. Found in Image Processing Tools.

  74. CreateHexagonalVectorGrid: Creates a hexagonal vector grid. Found in GIS Analysis.

  75. CreatePlane: Creates a raster image based on the equation for a simple plane. Found in GIS Analysis.

  76. CreateRectangularVectorGrid: Creates a rectangular vector grid. Found in GIS Analysis.

  77. CrispnessIndex: Calculates the Crispness Index, which is used to quantify how crisp (or conversely how fuzzy) a probability image is. Found in Math and Stats Tools.

  78. CrossTabulation: Performs a cross-tabulation on two categorical images. Found in Math and Stats Tools.

  79. CsvPointsToVector: Converts a CSV text file to vector points. Found in Data Tools.

  80. CumulativeDistribution: Converts a raster image to its cumulative distribution function. Found in Math and Stats Tools.

  81. Curvedness: This tool calculates curvedness from an input DEM. Found in Geomorphometric Analysis.

  82. D8FlowAccumulation: Calculates a D8 flow accumulation raster from an input DEM or flow pointer. Found in Hydrological Analysis.

  83. D8MassFlux: Performs a D8 mass flux calculation. Found in Hydrological Analysis.

  84. D8Pointer: Calculates a D8 flow pointer raster from an input DEM. Found in Hydrological Analysis.

  85. DInfFlowAccumulation: Calculates a D-infinity flow accumulation raster from an input DEM. Found in Hydrological Analysis.

  86. DInfMassFlux: Performs a D-infinity mass flux calculation. Found in Hydrological Analysis.

  87. DInfPointer: Calculates a D-infinity flow pointer (flow direction) raster from an input DEM. Found in Hydrological Analysis.

  88. Dbscan: Performs a DBSCAN-based unsupervised clustering operation. Found in Machine Learning.

  89. Decrement: Decreases the values of each grid cell in an input raster by 1.0 (see also InPlaceSubtract). Found in Math and Stats Tools.

  90. DemVoidFilling: This tool can be used to fill the void areas of a DEM using another fill DEM data set. Found in Geomorphometric Analysis.

  91. DepthInSink: Measures the depth of sinks (depressions) in a DEM. Found in Hydrological Analysis.

  92. DepthToWater: This tool calculates cartographic depth-to-water (DTW) index. Found in Hydrological Analysis.

  93. DevFromMeanElev: Calculates deviation from mean elevation. Found in Geomorphometric Analysis.

  94. DiffFromMeanElev: Calculates difference from mean elevation (equivalent to a high-pass filter). Found in Geomorphometric Analysis.

  95. DiffOfGaussianFilter: Performs a Difference of Gaussian (DoG) filter on an image. Found in Image Processing Tools → Filters.

  96. DifferenceCurvature: This tool calculates difference curvature from an input DEM. Found in Geomorphometric Analysis.

  97. Difference: Outputs the features that occur in one of the two vector inputs but not both, i.e. no overlapping features. Found in GIS Analysis → Overlay Tools.

  98. DirectDecorrelationStretch: Performs a direct decorrelation stretch enhancement on a colour-composite image of multispectral data. Found in Image Processing Tools → Image Enhancement.

  99. DirectionalRelief: Calculates relief for cells in an input DEM for a specified direction. Found in Geomorphometric Analysis.

  100. Dissolve: Removes the interior, or shared, boundaries within a vector polygon coverage. Found in GIS Analysis.

  101. DistanceToOutlet: Calculates the distance of stream grid cells to the channel network outlet cell. Found in Stream Network Analysis.

  102. DiversityFilter: Assigns each cell in the output grid the number of different values in a moving window centred on each grid cell in the input raster. Found in Image Processing Tools → Filters.

  103. Divide: Performs a division operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  104. DownslopeDistanceToStream: Measures distance to the nearest downslope stream cell. Found in Hydrological Analysis.

  105. DownslopeFlowpathLength: Calculates the downslope flowpath length from each cell to basin outlet. Found in Hydrological Analysis.

  106. DownslopeIndex: Calculates the Hjerdt et al. (2004) downslope index. Found in Geomorphometric Analysis.

  107. EdgeContamination: Identifies grid cells within an input DEM that may be impacted by edge contamination for hydrological applications. Found in Hydrological Analysis.

  108. EdgeDensity: Calculates the density of edges, or breaks-in-slope within DEMs. Found in Geomorphometric Analysis.

  109. EdgePreservingMeanFilter: Performs a simple edge-preserving mean filter on an input image. Found in Image Processing Tools → Filters.

  110. EdgeProportion: Calculate the proportion of cells in a raster polygon that are edge cells. Found in GIS Analysis → Patch Shape Tools.

  111. ElevAbovePit: Calculate the elevation of each grid cell above the nearest downstream pit cell or grid edge cell. Found in Geomorphometric Analysis.

  112. ElevPercentile: Calculates the elevation percentile raster from a DEM. Found in Geomorphometric Analysis.

  113. ElevRelativeToMinMax: Calculates the elevation of a location relative to the minimum and maximum elevations in a DEM. Found in Geomorphometric Analysis.

  114. ElevRelativeToWatershedMinMax: Calculates the elevation of a location relative to the minimum and maximum elevations in a watershed. Found in Geomorphometric Analysis.

  115. ElevationAboveStreamEuclidean: Calculates the elevation of cells above the nearest (Euclidean distance) stream cell. Found in Hydrological Analysis.

  116. ElevationAboveStream: Calculates the elevation of cells above the nearest downslope stream cell. Found in Hydrological Analysis.

  117. EliminateCoincidentPoints: Removes any coincident, or nearly coincident, points from a vector points file. Found in GIS Analysis.

  118. ElongationRatio: Calculates the elongation ratio for vector polygons. Found in GIS Analysis → Patch Shape Tools.

  119. EmbankmentMapping: Maps and/or removes road embankments from an input fine-resolution DEM. Found in Geomorphometric Analysis.

  120. EmbossFilter: Performs an emboss filter on an image, similar to a hillshade operation. Found in Image Processing Tools → Filters.

  121. EqualTo: Performs a equal-to comparison operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  122. ErasePolygonFromLidar: Erases (cuts out) a vector polygon or polygons from a LiDAR point cloud. Found in LiDAR Tools.

  123. ErasePolygonFromRaster: Erases (cuts out) a vector polygon from a raster. Found in GIS Analysis → Overlay Tools.

  124. Erase: Removes all the features, or parts of features, that overlap with the features of the erase vector polygon. Found in GIS Analysis → Overlay Tools.

  125. EuclideanAllocation: Assigns grid cells in the output raster the value of the nearest target cell in the input image, measured by the Shih and Wu (2004) Euclidean distance transform. Found in GIS Analysis → Distance Tools.

  126. EuclideanDistance: Calculates the Shih and Wu (2004) Euclidean distance transform. Found in GIS Analysis → Distance Tools.

  127. EvaluateTrainingSites: This tool can be used to inspect the overlap in spectral signatures of training sites for various classes. Found in Image Processing Tools → Classification.

  128. Exp2: Returns the exponential (base 2) of values in a raster. Found in Math and Stats Tools.

  129. Exp: Returns the exponential (base e) of values in a raster. Found in Math and Stats Tools.

  130. ExportTableToCsv: Exports an attribute table to a CSV text file. Found in Data Tools.

  131. ExposureTowardsWindFlux: Evaluates hydrologic connectivity within a DEM Found in Geomorphometric Analysis.

  132. ExtendVectorLines: Extends vector lines by a specified distance. Found in GIS Analysis.

  133. ExtractNodes: Converts vector lines or polygons into vertex points. Found in GIS Analysis.

  134. ExtractRasterValuesAtPoints: Extracts the values of raster(s) at vector point locations. Found in GIS Analysis.

  135. ExtractStreams: Extracts stream grid cells from a flow accumulation raster. Found in Stream Network Analysis.

  136. ExtractValleys: Identifies potential valley bottom grid cells based on local topolography alone. Found in Stream Network Analysis.

  137. FarthestChannelHead: Calculates the distance to the furthest upstream channel head for each stream cell. Found in Stream Network Analysis.

  138. FastAlmostGaussianFilter: Performs a fast approximate Gaussian filter on an image. Found in Image Processing Tools → Filters.

  139. Fd8FlowAccumulation: Calculates an FD8 flow accumulation raster from an input DEM. Found in Hydrological Analysis.

  140. Fd8Pointer: Calculates an FD8 flow pointer raster from an input DEM. Found in Hydrological Analysis.

  141. FeaturePreservingSmoothing: Reduces short-scale variation in an input DEM using a modified Sun et al. (2007) algorithm. Found in Geomorphometric Analysis.

  142. FetchAnalysis: Performs an analysis of fetch or upwind distance to an obstacle. Found in Geomorphometric Analysis.

  143. FillBurn: Burns streams into a DEM using the FillBurn (Saunders, 1999) method. Found in Hydrological Analysis.

  144. FillDepressionsPlanchonAndDarboux: Fills all of the depressions in a DEM using the Planchon and Darboux (2002) method. Found in Hydrological Analysis.

  145. FillDepressionsWangAndLiu: Fills all of the depressions in a DEM using the Wang and Liu (2006) method. Depression breaching should be preferred in most cases. Found in Hydrological Analysis.

  146. FillDepressions: Fills all of the depressions in a DEM. Depression breaching should be preferred in most cases. Found in Hydrological Analysis.

  147. FillMissingData: Fills NoData holes in a DEM. Found in Geomorphometric Analysis.

  148. FillSingleCellPits: Raises pit cells to the elevation of their lowest neighbour. Found in Hydrological Analysis.

  149. FilterLidarClasses: Removes points in a LAS file with certain specified class values. Found in LiDAR Tools.

  150. FilterLidarScanAngles: Removes points in a LAS file with scan angles greater than a threshold. Found in LiDAR Tools.

  151. FilterLidar: Filters points within a LiDAR point cloud based on point properties. Found in LiDAR Tools.

  152. FilterRasterFeaturesByArea: Removes small-area features from a raster. Found in GIS Analysis.

  153. FindFlightlineEdgePoints: Identifies points along a flightline's edge in a LAS file. Found in LiDAR Tools.

  154. FindLowestOrHighestPoints: Locates the lowest and/or highest valued cells in a raster. Found in GIS Analysis.

  155. FindMainStem: Finds the main stem, based on stream lengths, of each stream network. Found in Stream Network Analysis.

  156. FindNoFlowCells: Finds grid cells with no downslope neighbours. Found in Hydrological Analysis.

  157. FindParallelFlow: Finds areas of parallel flow in D8 flow direction rasters. Found in Hydrological Analysis.

  158. FindPatchOrClassEdgeCells: Finds all cells located on the edge of patch or class features. Found in GIS Analysis → Patch Shape Tools.

  159. FindRidges: Identifies potential ridge and peak grid cells. Found in Geomorphometric Analysis.

  160. FixDanglingArcs: This tool fixes undershot and overshot arcs, two common topological errors, in an input vector lines file. Found in Data Tools.

  161. FlattenLakes: Flattens lake polygons in a raster DEM. Found in Hydrological Analysis.

  162. FlightlineOverlap: Reads a LiDAR (LAS) point file and outputs a raster containing the number of overlapping flight-lines in each grid cell. Found in LiDAR Tools.

  163. FlipImage: Reflects an image in the vertical or horizontal axis. Found in Image Processing Tools.

  164. FloodOrder: Assigns each DEM grid cell its order in the sequence of inundations that are encountered during a search starting from the edges, moving inward at increasing elevations. Found in Hydrological Analysis.

  165. Floor: Returns the largest (closest to positive infinity) value that is less than or equal to the values in a raster. Found in Math and Stats Tools.

  166. FlowAccumulationFullWorkflow: Resolves all of the depressions in a DEM, outputting a breached DEM, an aspect-aligned non-divergent flow pointer, and a flow accumulation raster. Found in Hydrological Analysis.

  167. FlowLengthDiff: Calculates the local maximum absolute difference in downslope flowpath length, useful in mapping drainage divides and ridges. Found in Hydrological Analysis.

  168. GammaCorrection: Performs a gamma correction on an input images. Found in Image Processing Tools → Image Enhancement.

  169. GaussianContrastStretch: Performs a Gaussian contrast stretch on input images. Found in Image Processing Tools → Image Enhancement.

  170. GaussianCurvature: Calculates a mean curvature raster from an input DEM. Found in Geomorphometric Analysis.

  171. GaussianFilter: Performs a Gaussian filter on an image. Found in Image Processing Tools → Filters.

  172. GaussianScaleSpace: Uses the fast Gaussian approximation algorithm to produce scaled land-surface parameter measurements from an input DEM. Found in Geomorphometric Analysis.

  173. GeneralizeClassifiedRaster: Generalizes a raster containing class or object features by removing small features. Found in Image Processing Tools → Classification.

  174. GeneralizeWithSimilarity: Generalizes a raster containing class or object features by removing small features using similarity criteria of neighbouring features. Found in Image Processing Tools → Classification.

  175. GeneratingFunction: This tool calculates generating function from an input DEM. Found in Geomorphometric Analysis.

  176. Geomorphons: Computes geomorphon patterns. Found in Geomorphometric Analysis.

  177. GreaterThan: Performs a greater-than comparison operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  178. HackStreamOrder: Assigns the Hack stream order to each tributary in a stream network. Found in Stream Network Analysis.

  179. HeatMap: Calculates a heat map, or kernel density estimation (KDE), for an input point set. Found in GIS Analysis.

  180. HeightAboveGround: Normalizes a LiDAR point cloud, providing the height above the nearest ground-classified point. Found in LiDAR Tools.

  181. HighPassBilateralFilter: Performs a high-pass bilateral filter, by differencing an input image by the bilateral filter by Tomasi and Manduchi (1998). Found in Image Processing Tools → Filters.

  182. HighPassFilter: Performs a high-pass filter on an input image. Found in Image Processing Tools → Filters.

  183. HighPassMedianFilter: Performs a high pass median filter on an input image. Found in Image Processing Tools → Filters.

  184. HighestPosition: Identifies the stack position of the maximum value within a raster stack on a cell-by-cell basis. Found in GIS Analysis → Overlay Tools.

  185. Hillshade: Calculates a hillshade raster from an input DEM. Found in Geomorphometric Analysis.

  186. Hillslopes: Identifies the individual hillslopes draining to each link in a stream network. Found in Hydrological Analysis.

  187. HistogramEqualization: Performs a histogram equalization contrast enhancement on an image. Found in Image Processing Tools → Image Enhancement.

  188. HistogramMatchingTwoImages: Alters the cumulative distribution function of a raster image to that of another image. Found in Image Processing Tools → Image Enhancement.

  189. HistogramMatching: Alters the statistical distribution of a raster image matching it to a specified PDF. Found in Image Processing Tools → Image Enhancement.

  190. HoleProportion: Calculates the proportion of the total area of a polygon's holes relative to the area of the polygon's hull. Found in GIS Analysis → Patch Shape Tools.

  191. HorizonAngle: Calculates horizon angle (maximum upwind slope) for each grid cell in an input DEM. Found in Geomorphometric Analysis.

  192. HorizontalExcessCurvature: This tool calculates horizontal excess curvature from an input DEM. Found in Geomorphometric Analysis.

  193. HortonStreamOrder: Assigns the Horton stream order to each tributary in a stream network. Found in Stream Network Analysis.

  194. HydrologicConnectivity: This tool evaluates hydrologic connectivity within a DEM Found in Hydrological Analysis.

  195. HypsometricAnalysis: Calculates a hypsometric curve for one or more DEMs. Found in Geomorphometric Analysis.

  196. HypsometricallyTintedHillshade: Creates an colour shaded relief image from an input DEM. Found in Geomorphometric Analysis.

  197. IdwInterpolation: Interpolates vector points into a raster surface using an inverse-distance weighted scheme. Found in GIS Analysis.

  198. IhsToRgb: Converts intensity, hue, and saturation (IHS) images into red, green, and blue (RGB) images. Found in Image Processing Tools.

  199. ImageAutocorrelation: Performs Moran's I analysis on two or more input images. Found in Math and Stats Tools.

  200. ImageCorrelationNeighbourhoodAnalysis: Performs image correlation on two input images neighbourhood search windows. Found in Math and Stats Tools.

  201. ImageCorrelation: Performs image correlation on two or more input images. Found in Math and Stats Tools.

  202. ImageRegression: Performs image regression analysis on two input images. Found in Math and Stats Tools.

  203. ImageSegmentation: Performs a region-growing based segmentation on a set of multi-spectral images. Found in Image Processing Tools → Classification.

  204. ImageSlider: This tool creates an image slider from two input images. Found in Image Processing Tools.

  205. ImageStackProfile: Plots an image stack profile (i.e. signature) for a set of points and multispectral images. Found in Image Processing Tools.

  206. ImpoundmentSizeIndex: Calculates the impoundment size resulting from damming a DEM. Found in Hydrological Analysis.

  207. InPlaceAdd: Performs an in-place addition operation (input1 += input2). Found in Math and Stats Tools.

  208. InPlaceDivide: Performs an in-place division operation (input1 /= input2). Found in Math and Stats Tools.

  209. InPlaceMultiply: Performs an in-place multiplication operation (input1 *= input2). Found in Math and Stats Tools.

  210. InPlaceSubtract: Performs an in-place subtraction operation (input1 -= input2). Found in Math and Stats Tools.

  211. Increment: Increases the values of each grid cell in an input raster by 1.0. (see also InPlaceAdd) Found in Math and Stats Tools.

  212. IndividualTreeDetection: Identifies points in a LiDAR point cloud that are associated with the tops of individual trees. Found in LiDAR Tools.

  213. InsertDams: Calculates the impoundment size resulting from damming a DEM. Found in Hydrological Analysis.

  214. InstallWbExtension: Use to install a Whitebox extension product. Found in Whitebox Utilities.

  215. IntegerDivision: Performs an integer division operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  216. IntegralImage: Transforms an input image (summed area table) into its integral image equivalent. Found in Image Processing Tools.

  217. Intersect: Identifies the parts of features in common between two input vector layers. Found in GIS Analysis → Overlay Tools.

  218. InversePrincipalComponentAnalysis: This tool performs an inverse principal component analysis on a series of input component images. Found in Math and Stats Tools.

  219. IsNoData: Identifies NoData valued pixels in an image. Found in Math and Stats Tools.

  220. Isobasins: Divides a landscape into nearly equal sized drainage basins (i.e. watersheds). Found in Hydrological Analysis.

  221. JensonSnapPourPoints: Moves outlet points used to specify points of interest in a watershedding operation to the nearest stream cell. Found in Hydrological Analysis.

  222. JoinTables: Merge a vector's attribute table with another table based on a common field. Found in Data Tools.

  223. KMeansClustering: Performs a k-means clustering operation on a multi-spectral dataset. Found in Machine Learning.

  224. KNearestMeanFilter: A k-nearest mean filter is a type of edge-preserving smoothing filter. Found in Image Processing Tools → Filters.

  225. KappaIndex: Performs a kappa index of agreement (KIA) analysis on two categorical raster files. Found in Math and Stats Tools.

  226. KnnClassification: Performs a supervised k-nearest neighbour classification using training site polygons/points and predictor rasters. Found in Machine Learning.

  227. KnnRegression: Performs a supervised k-nearest neighbour regression using training site points and predictor rasters. Found in Machine Learning.

  228. KsTestForNormality: Evaluates whether the values in a raster are normally distributed. Found in Math and Stats Tools.

  229. LaplacianFilter: Performs a Laplacian filter on an image. Found in Image Processing Tools → Filters.

  230. LaplacianOfGaussianFilter: Performs a Laplacian-of-Gaussian (LoG) filter on an image. Found in Image Processing Tools → Filters.

  231. LasToAscii: Converts one or more LAS files into ASCII text files. Found in LiDAR Tools.

  232. LasToLaz: This tool converts one or more LAS files into the LAZ format Found in LiDAR Tools.

  233. LasToMultipointShapefile: Converts one or more LAS files into MultipointZ vector Shapefiles. When the input parameter is not specified, the tool grids all LAS files contained within the working directory. Found in LiDAR Tools.

  234. LasToShapefile: Converts one or more LAS files into a vector Shapefile of POINT ShapeType. Found in LiDAR Tools.

  235. LasToZlidar: Converts one or more LAS files into the zlidar compressed LiDAR data format. Found in LiDAR Tools.

  236. LaunchWbRunner: Opens the Whitebox Runner application. Found in Whitebox Utilities.

  237. LayerFootprint: Creates a vector polygon footprint of the area covered by a raster grid or vector layer. Found in GIS Analysis.

  238. LazToLas: This tool converts one or more LAZ files into the LAS format Found in LiDAR Tools.

  239. LeeSigmaFilter: Performs a Lee (Sigma) smoothing filter on an image. Found in Image Processing Tools → Filters.

  240. LengthOfUpstreamChannels: Calculates the total length of channels upstream. Found in Stream Network Analysis.

  241. LessThan: Performs a less-than comparison operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  242. LidarBlockMaximum: Creates a block-maximum raster from an input LAS file. When the input/output parameters are not specified, the tool grids all LAS files contained within the working directory. Found in LiDAR Tools.

  243. LidarBlockMinimum: Creates a block-minimum raster from an input LAS file. When the input/output parameters are not specified, the tool grids all LAS files contained within the working directory. Found in LiDAR Tools.

  244. LidarClassifySubset: Classifies the values in one LiDAR point cloud that correspond with points in a subset cloud. Found in LiDAR Tools.

  245. LidarColourize: Adds the red-green-blue colour fields of a LiDAR (LAS) file based on an input image. Found in LiDAR Tools.

  246. LidarContour: This tool creates a vector contour coverage from an input LiDAR point file. Found in LiDAR Tools.

  247. LidarDigitalSurfaceModel: Creates a top-surface digital surface model (DSM) from a LiDAR point cloud. Found in LiDAR Tools.

  248. LidarEigenvalueFeatures: Calculate eigenvalue-based metrics from a LiDAR point cloud. Found in LiDAR Tools.

  249. LidarElevationSlice: Outputs all of the points within a LiDAR (LAS) point file that lie between a specified elevation range. Found in LiDAR Tools.

  250. LidarGroundPointFilter: Identifies ground points within LiDAR dataset using a slope-based method. Found in LiDAR Tools.

  251. LidarHexBinning: Hex-bins a set of LiDAR points. Found in LiDAR Tools.

  252. LidarHillshade: Calculates a hillshade value for points within a LAS file and stores these data in the RGB field. Found in LiDAR Tools.

  253. LidarHistogram: Creates a histogram of LiDAR data. Found in LiDAR Tools.

  254. LidarIdwInterpolation: Interpolates LAS files using an inverse-distance weighted (IDW) scheme. When the input/output parameters are not specified, the tool interpolates all LAS files contained within the working directory. Found in LiDAR Tools.

  255. LidarInfo: Prints information about a LiDAR (LAS) dataset, including header, point return frequency, and classification data and information about the variable length records (VLRs) and geokeys. Found in LiDAR Tools.

  256. LidarJoin: Joins multiple LiDAR (LAS) files into a single LAS file. Found in LiDAR Tools.

  257. LidarKappaIndex: Performs a kappa index of agreement (KIA) analysis on the classifications of two LAS files. Found in LiDAR Tools.

  258. LidarNearestNeighbourGridding: Grids LiDAR files using nearest-neighbour scheme. When the input/output parameters are not specified, the tool grids all LAS files contained within the working directory. Found in LiDAR Tools.

  259. LidarPointDensity: Calculates the spatial pattern of point density for a LiDAR data set. When the input/output parameters are not specified, the tool grids all LAS files contained within the working directory. Found in LiDAR Tools.

  260. LidarPointReturnAnalysis: This tool performs a quality control check on the return values of points in a LiDAR file. Found in LiDAR Tools.

  261. LidarPointStats: Creates several rasters summarizing the distribution of LAS point data. When the input/output parameters are not specified, the tool works on all LAS files contained within the working directory. Found in LiDAR Tools.

  262. LidarRansacPlanes: Performs a RANSAC analysis to identify points within a LiDAR point cloud that belong to linear planes. Found in LiDAR Tools.

  263. LidarRbfInterpolation: Interpolates LAS files using a radial basis function (RBF) scheme. When the input/output parameters are not specified, the tool interpolates all LAS files contained within the working directory. Found in LiDAR Tools.

  264. LidarRemoveDuplicates: Removes duplicate points from a LiDAR data set. Found in LiDAR Tools.

  265. LidarRemoveOutliers: Removes outliers (high and low points) in a LiDAR point cloud. Found in LiDAR Tools.

  266. LidarRooftopAnalysis: Identifies roof segments in a LiDAR point cloud. Found in LiDAR Tools.

  267. LidarSegmentationBasedFilter: Identifies ground points within LiDAR point clouds using a segmentation based approach. Found in LiDAR Tools.

  268. LidarSegmentation: Segments a LiDAR point cloud based on differences in the orientation of fitted planar surfaces and point proximity. Found in LiDAR Tools.

  269. LidarShift: Shifts the x,y,z coordinates of a LiDAR file. Found in LiDAR Tools.

  270. LidarSibsonInterpolation: This tool interpolates one or more LiDAR tiles using Sibson's natural neighbour method. Found in LiDAR Tools.

  271. LidarSortByTime: This tool sorts the points in a LiDAR file by the GPS time. Found in LiDAR Tools.

  272. LidarThinHighDensity: Thins points from high density areas within a LiDAR point cloud. Found in LiDAR Tools.

  273. LidarThin: Thins a LiDAR point cloud, reducing point density. Found in LiDAR Tools.

  274. LidarTileFootprint: Creates a vector polygon of the convex hull of a LiDAR point cloud. When the input/output parameters are not specified, the tool works with all LAS files contained within the working directory. Found in LiDAR Tools.

  275. LidarTile: Tiles a LiDAR LAS file into multiple LAS files. Found in LiDAR Tools.

  276. LidarTinGridding: Creates a raster grid based on a Delaunay triangular irregular network (TIN) fitted to LiDAR points. Found in LiDAR Tools.

  277. LidarTophatTransform: Performs a white top-hat transform on a Lidar dataset; as an estimate of height above ground, this is useful for modelling the vegetation canopy. Found in LiDAR Tools.

  278. LineDetectionFilter: Performs a line-detection filter on an image. Found in Image Processing Tools → Filters.

  279. LineIntersections: Identifies points where the features of two vector line layers intersect. Found in GIS Analysis → Overlay Tools.

  280. LineThinning: Performs line thinning a on Boolean raster image; intended to be used with the RemoveSpurs tool. Found in Image Processing Tools.

  281. LinearityIndex: Calculates the linearity index for vector polygons. Found in GIS Analysis → Patch Shape Tools.

  282. LinesToPolygons: Converts vector polylines to polygons. Found in Data Tools.

  283. ListUniqueValuesRaster: Lists the unique values contained in a field within a vector's attribute table. Found in Math and Stats Tools.

  284. ListUniqueValues: Lists the unique values contained in a field within a vector's attribute table. Found in Math and Stats Tools.

  285. Ln: Returns the natural logarithm of values in a raster. Found in Math and Stats Tools.

  286. LocalHypsometricAnalysis: This tool calculates a local, neighbourhood-based hypsometric integral raster. Found in Geomorphometric Analysis.

  287. LocalQuadraticRegression: An implementation of the constrained quadratic regression algorithm using a flexible window size described in Wood (1996). Found in Geomorphometric Analysis.

  288. Log10: Returns the base-10 logarithm of values in a raster. Found in Math and Stats Tools.

  289. Log2: Returns the base-2 logarithm of values in a raster. Found in Math and Stats Tools.

  290. LogisticRegression: Performs a logistic regression analysis using training site polygons/points and predictor rasters. Found in Machine Learning.

  291. LongProfileFromPoints: Plots the longitudinal profiles from flow-paths initiating from a set of vector points. Found in Stream Network Analysis.

  292. LongProfile: Plots the stream longitudinal profiles for one or more rivers. Found in Stream Network Analysis.

  293. LongestFlowpath: Delineates the longest flowpaths for a group of subbasins or watersheds. Found in Hydrological Analysis.

  294. LowPointsOnHeadwaterDivides: This tool locates saddle points along ridges within a digital elevation model (DEM) Found in Hydrological Analysis.

  295. LowestPosition: Identifies the stack position of the minimum value within a raster stack on a cell-by-cell basis. Found in GIS Analysis → Overlay Tools.

  296. MajorityFilter: Assigns each cell in the output grid the most frequently occurring value (mode) in a moving window centred on each grid cell in the input raster. Found in Image Processing Tools → Filters.

  297. MapOffTerrainObjects: Maps off-terrain objects in a digital elevation model (DEM). Found in Geomorphometric Analysis.

  298. MaxAbsoluteOverlay: Evaluates the maximum absolute value for each grid cell from a stack of input rasters. Found in GIS Analysis → Overlay Tools.

  299. MaxAnisotropyDevSignature: Calculates the anisotropy in deviation from mean for points over a range of spatial scales. Found in Geomorphometric Analysis.

  300. MaxAnisotropyDev: Calculates the maximum anisotropy (directionality) in elevation deviation over a range of spatial scales. Found in Geomorphometric Analysis.

  301. MaxBranchLength: Lindsay and Seibert's (2013) branch length index is used to map drainage divides or ridge lines. Found in Geomorphometric Analysis.

  302. MaxDifferenceFromMean: Calculates the maximum difference from mean elevation over a range of spatial scales. Found in Geomorphometric Analysis.

  303. MaxDownslopeElevChange: Calculates the maximum downslope change in elevation between a grid cell and its eight downslope neighbors. Found in Geomorphometric Analysis.

  304. MaxElevDevSignature: Calculates the maximum elevation deviation over a range of spatial scales and for a set of points. Found in Geomorphometric Analysis.

  305. MaxElevationDeviation: Calculates the maximum elevation deviation over a range of spatial scales. Found in Geomorphometric Analysis.

  306. MaxOverlay: Evaluates the maximum value for each grid cell from a stack of input rasters. Found in GIS Analysis → Overlay Tools.

  307. MaxUpslopeElevChange: Calculates the maximum upslope change in elevation between a grid cell and its eight downslope neighbors. Found in Geomorphometric Analysis.

  308. MaxUpslopeFlowpathLength: Measures the maximum length of all upslope flowpaths draining each grid cell. Found in Hydrological Analysis.

  309. MaxUpslopeValue: Calculates the maximum upslope value from an input values raster along flowpaths. Found in Hydrological Analysis.

  310. Max: Performs a MAX operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  311. MaximalCurvature: Calculates a mean curvature raster from an input DEM. Found in Geomorphometric Analysis.

  312. MaximumFilter: Assigns each cell in the output grid the maximum value in a moving window centred on each grid cell in the input raster. Found in Image Processing Tools → Filters.

  313. MdInfFlowAccumulation: Calculates an FD8 flow accumulation raster from an input DEM. Found in Hydrological Analysis.

  314. MeanCurvature: Calculates a mean curvature raster from an input DEM. Found in Geomorphometric Analysis.

  315. MeanFilter: Performs a mean filter (low-pass filter) on an input image. Found in Image Processing Tools → Filters.

  316. MedianFilter: Performs a median filter on an input image. Found in Image Processing Tools → Filters.

  317. Medoid: Calculates the medoid for a series of vector features contained in a shapefile. Found in GIS Analysis.

  318. MergeLineSegments: Merges vector line segments into larger features. Found in GIS Analysis → Overlay Tools.

  319. MergeTableWithCsv: Merge a vector's attribute table with a table contained within a CSV text file. Found in Data Tools.

  320. MergeVectors: Combines two or more input vectors of the same ShapeType creating a single, new output vector. Found in Data Tools.

  321. MinAbsoluteOverlay: Evaluates the minimum absolute value for each grid cell from a stack of input rasters. Found in GIS Analysis → Overlay Tools.

  322. MinDistClassification: Performs a supervised minimum-distance classification using training site polygons and multi-spectral images. Found in Image Processing Tools → Classification.

  323. MinDownslopeElevChange: Calculates the minimum downslope change in elevation between a grid cell and its eight downslope neighbors. Found in Geomorphometric Analysis.

  324. MinMaxContrastStretch: Performs a min-max contrast stretch on an input greytone image. Found in Image Processing Tools → Image Enhancement.

  325. MinOverlay: Evaluates the minimum value for each grid cell from a stack of input rasters. Found in GIS Analysis → Overlay Tools.

  326. Min: Performs a MIN operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  327. MinimalCurvature: Calculates a mean curvature raster from an input DEM. Found in Geomorphometric Analysis.

  328. MinimumBoundingBox: Creates a vector minimum bounding rectangle around vector features. Found in GIS Analysis.

  329. MinimumBoundingCircle: Delineates the minimum bounding circle (i.e. smallest enclosing circle) for a group of vectors. Found in GIS Analysis.

  330. MinimumBoundingEnvelope: Creates a vector axis-aligned minimum bounding rectangle (envelope) around vector features. Found in GIS Analysis.

  331. MinimumConvexHull: Creates a vector convex polygon around vector features. Found in GIS Analysis.

  332. MinimumFilter: Assigns each cell in the output grid the minimum value in a moving window centred on each grid cell in the input raster. Found in Image Processing Tools → Filters.

  333. ModifiedKMeansClustering: Performs a modified k-means clustering operation on a multi-spectral dataset. Found in Machine Learning.

  334. ModifyLidar: Modify points within a LiDAR point cloud based on point properties. Found in LiDAR Tools.

  335. ModifyNoDataValue: Modifies nodata values in a raster. Found in Data Tools.

  336. Modulo: Performs a modulo operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  337. MosaicWithFeathering: Mosaics two images together using a feathering technique in overlapping areas to reduce edge-effects. Found in Image Processing Tools.

  338. Mosaic: Mosaics two or more images together. Found in Image Processing Tools.

  339. MultiPartToSinglePart: Converts a vector file containing multi-part features into a vector containing only single-part features. Found in Data Tools.

  340. MultidirectionalHillshade: Calculates a multi-direction hillshade raster from an input DEM. Found in Geomorphometric Analysis.

  341. MultiplyOverlay: Calculates the sum for each grid cell from a group of raster images. Found in GIS Analysis → Overlay Tools.

  342. Multiply: Performs a multiplication operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  343. MultiscaleCurvatures: This tool calculates several multiscale curvatures and curvature-based indices from an input DEM. Found in Geomorphometric Analysis.

  344. MultiscaleElevationPercentile: Calculates surface roughness over a range of spatial scales. Found in Geomorphometric Analysis.

  345. MultiscaleRoughnessSignature: Calculates the surface roughness for points over a range of spatial scales. Found in Geomorphometric Analysis.

  346. MultiscaleRoughness: Calculates surface roughness over a range of spatial scales. Found in Geomorphometric Analysis.

  347. MultiscaleStdDevNormalsSignature: Calculates the surface roughness for points over a range of spatial scales. Found in Geomorphometric Analysis.

  348. MultiscaleStdDevNormals: Calculates surface roughness over a range of spatial scales. Found in Geomorphometric Analysis.

  349. MultiscaleTopographicPositionImage: Creates a multiscale topographic position image from three DEVmax rasters of differing spatial scale ranges. Found in Geomorphometric Analysis.

  350. NarrownessIndex: Calculates the narrowness of raster polygons. Found in GIS Analysis → Patch Shape Tools.

  351. NaturalNeighbourInterpolation: Creates a raster grid based on Sibson's natural neighbour method. Found in GIS Analysis.

  352. NearestNeighbourGridding: Creates a raster grid based on a set of vector points and assigns grid values using the nearest neighbour. Found in GIS Analysis.

  353. Negate: Changes the sign of values in a raster or the 0-1 values of a Boolean raster. Found in Math and Stats Tools.

  354. NewRasterFromBase: Creates a new raster using a base image. Found in Data Tools.

  355. NormalVectors: Calculates normal vectors for points within a LAS file and stores these data (XYZ vector components) in the RGB field. Found in LiDAR Tools.

  356. NormalizeLidar: Normalizes a LiDAR point cloud. Found in LiDAR Tools.

  357. NormalizedDifferenceIndex: Calculate a normalized-difference index (NDI) from two bands of multispectral image data. Found in Image Processing Tools.

  358. NotEqualTo: Performs a not-equal-to comparison operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  359. Not: Performs a logical NOT operator on two Boolean raster images. Found in Math and Stats Tools.

  360. NumDownslopeNeighbours: Calculates the number of downslope neighbours to each grid cell in a DEM. Found in Geomorphometric Analysis.

  361. NumInflowingNeighbours: Computes the number of inflowing neighbours to each cell in an input DEM based on the D8 algorithm. Found in Hydrological Analysis.

  362. NumUpslopeNeighbours: Calculates the number of upslope neighbours to each grid cell in a DEM. Found in Geomorphometric Analysis.

  363. OlympicFilter: Performs an olympic smoothing filter on an image. Found in Image Processing Tools → Filters.

  364. Opening: An opening is a mathematical morphology operation involving a dilation (max filter) of an erosion (min filter) set. Found in Image Processing Tools.

  365. Openness: This tool calculates the topographic openness index from an input DEM. Found in Geomorphometric Analysis.

  366. Or: Performs a logical OR operator on two Boolean raster images. Found in Math and Stats Tools.

  367. PairedSampleTTest: Performs a 2-sample K-S test for significant differences on two input rasters. Found in Math and Stats Tools.

  368. PanchromaticSharpening: Increases the spatial resolution of image data by combining multispectral bands with panchromatic data. Found in Image Processing Tools → Image Enhancement.

  369. ParallelepipedClassification: Performs a supervised parallelepiped classification using training site polygons and multi-spectral images. Found in Image Processing Tools → Classification.

  370. PatchOrientation: Calculates the orientation of vector polygons. Found in GIS Analysis → Patch Shape Tools.

  371. PennockLandformClass: Classifies hillslope zones based on slope, profile curvature, and plan curvature. Found in Geomorphometric Analysis.

  372. PercentElevRange: Calculates percent of elevation range from a DEM. Found in Geomorphometric Analysis.

  373. PercentEqualTo: Calculates the percentage of a raster stack that have cell values equal to an input on a cell-by-cell basis. Found in GIS Analysis → Overlay Tools.

  374. PercentGreaterThan: Calculates the percentage of a raster stack that have cell values greater than an input on a cell-by-cell basis. Found in GIS Analysis → Overlay Tools.

  375. PercentLessThan: Calculates the percentage of a raster stack that have cell values less than an input on a cell-by-cell basis. Found in GIS Analysis → Overlay Tools.

  376. PercentageContrastStretch: Performs a percentage linear contrast stretch on input images. Found in Image Processing Tools → Image Enhancement.

  377. PercentileFilter: Performs a percentile filter on an input image. Found in Image Processing Tools → Filters.

  378. PerimeterAreaRatio: Calculates the perimeter-area ratio of vector polygons. Found in GIS Analysis → Patch Shape Tools.

  379. PhiCoefficient: This tool performs a binary classification accuracy assessment. Found in Math and Stats Tools.

  380. PickFromList: Outputs the value from a raster stack specified by a position raster. Found in GIS Analysis → Overlay Tools.

  381. PiecewiseContrastStretch: Performs a piecewise contrast stretch on an input image. Found in Image Processing Tools → Image Enhancement.

  382. PlanCurvature: Calculates a plan (contour) curvature raster from an input DEM. Found in Geomorphometric Analysis.

  383. PolygonArea: Calculates the area of vector polygons. Found in GIS Analysis.

  384. PolygonLongAxis: Used to map the long axis of polygon features. Found in GIS Analysis.

  385. PolygonPerimeter: Calculates the perimeter of vector polygons. Found in GIS Analysis.

  386. PolygonShortAxis: Used to map the short axis of polygon features. Found in GIS Analysis.

  387. Polygonize: Creates a polygon layer from two or more intersecting line features contained in one or more input vector line files. Found in GIS Analysis → Overlay Tools.

  388. PolygonsToLines: Converts vector polygons to polylines. Found in Data Tools.

  389. Power: Raises the values in grid cells of one rasters, or a constant value, by values in another raster or constant value. Found in Math and Stats Tools.

  390. PrewittFilter: Performs a Prewitt edge-detection filter on an image. Found in Image Processing Tools → Filters.

  391. PrincipalComponentAnalysis: Performs a principal component analysis (PCA) on a multi-spectral dataset. Found in Math and Stats Tools.

  392. PrintGeoTiffTags: Prints the tags within a GeoTIFF. Found in Data Tools.

  393. ProfileCurvature: Calculates a profile curvature raster from an input DEM. Found in Geomorphometric Analysis.

  394. Profile: Plots profiles from digital surface models. Found in Geomorphometric Analysis.

  395. PruneVectorStreams: This tool performs common stream network analysis operations on an input vector stream file. Found in Stream Network Analysis.

  396. QinFlowAccumulation: Calculates Qin et al. (2007) flow accumulation. Found in Hydrological Analysis.

  397. Quantiles: Transforms raster values into quantiles. Found in Math and Stats Tools.

  398. QuinnFlowAccumulation: Calculates Quinn et al. (1995) flow accumulation. Found in Hydrological Analysis.

  399. RadialBasisFunctionInterpolation: Interpolates vector points into a raster surface using a radial basis function scheme. Found in GIS Analysis.

  400. RadiusOfGyration: Calculates the distance of cells from their polygon's centroid. Found in GIS Analysis → Patch Shape Tools.

  401. RaiseWalls: Raises walls in a DEM along a line or around a polygon, e.g. a watershed. Found in Hydrological Analysis.

  402. RandomField: Creates an image containing random values. Found in Math and Stats Tools.

  403. RandomForestClassificationFit: Performs a supervised random forest classification using training site polygons/points and predictor rasters. Found in Machine Learning.

  404. RandomForestClassificationPredict: Uses a pre-trained random forest classification model and predictor rasters to create an output raster. Found in Machine Learning.

  405. RandomForestClassification: Performs a supervised random forest classification using training site polygons/points and predictor rasters. Found in Machine Learning.

  406. RandomForestRegressionFit: Trains a random forest regression model using training site data and predictor rasters. Found in Machine Learning.

  407. RandomForestRegressionPredict: Uses a pre-trained random forest regression model and predictor rasters to create an output raster. Found in Machine Learning.

  408. RandomForestRegression: Performs a random forest regression analysis using training site data and predictor rasters. Found in Machine Learning.

  409. RandomSample: Creates an image containing randomly located sample grid cells with unique IDs. Found in Math and Stats Tools.

  410. RangeFilter: Assigns each cell in the output grid the range of values in a moving window centred on each grid cell in the input raster. Found in Image Processing Tools → Filters.

  411. RasterArea: Calculates the area of polygons or classes within a raster image. Found in GIS Analysis.

  412. RasterCalculator: Performs a complex mathematical operations on one or more input raster images on a cell-to-cell basis. Found in Math and Stats Tools.

  413. RasterCellAssignment: Assign row or column number to cells. Found in GIS Analysis.

  414. RasterHistogram: Creates a histogram from raster values. Found in Math and Stats Tools.

  415. RasterPerimeter: Calculates the perimeters of polygons or classes within a raster image. Found in GIS Analysis.

  416. RasterStreamsToVector: Converts a raster stream file into a vector file. Found in Stream Network Analysis.

  417. RasterSummaryStats: Measures a rasters min, max, average, standard deviation, num. non-nodata cells, and total. Found in Math and Stats Tools.

  418. RasterToVectorLines: Converts a raster lines features into a vector of the POLYLINE shapetype Found in Data Tools.

  419. RasterToVectorPoints: Converts a raster dataset to a vector of the POINT shapetype. Found in Data Tools.

  420. RasterToVectorPolygons: Converts a raster dataset to a vector of the POLYGON shapetype. Found in Data Tools.

  421. RasterizeStreams: Rasterizes vector streams based on Lindsay (2016) method. Found in Stream Network Analysis.

  422. Reciprocal: Returns the reciprocal (i.e. 1 / z) of values in a raster. Found in Math and Stats Tools.

  423. ReclassEqualInterval: Reclassifies the values in a raster image based on equal-ranges. Found in GIS Analysis.

  424. ReclassFromFile: Reclassifies the values in a raster image using reclass ranges in a text file. Found in GIS Analysis.

  425. Reclass: Reclassifies the values in a raster image. Found in GIS Analysis.

  426. ReconcileMultipleHeaders: This tool adjusts the crop yield values for data sets collected with multiple headers or combines. Found in Precision Agriculture.

  427. RecoverFlightlineInfo: Associates LiDAR points by their flightlines. Found in LiDAR Tools.

  428. RecreatePassLines: This tool can be used to approximate the harvester pass lines from yield points. Found in Precision Agriculture.

  429. ReinitializeAttributeTable: Reinitializes a vector's attribute table deleting all fields but the feature ID (FID). Found in Data Tools.

  430. RelatedCircumscribingCircle: Calculates the related circumscribing circle of vector polygons. Found in GIS Analysis → Patch Shape Tools.

  431. RelativeAspect: Calculates relative aspect (relative to a user-specified direction) from an input DEM. Found in Geomorphometric Analysis.

  432. RelativeTopographicPosition: Calculates the relative topographic position index from a DEM. Found in Geomorphometric Analysis.

  433. RemoveFieldEdgePoints: This tool can be used to remove, or flag, most of the points along the edges from a crop yield data set. Found in Precision Agriculture.

  434. RemoveOffTerrainObjects: Removes off-terrain objects from a raster digital elevation model (DEM). Found in Geomorphometric Analysis.

  435. RemovePolygonHoles: Removes holes within the features of a vector polygon file. Found in Data Tools.

  436. RemoveRasterPolygonHoles: Removes polygon holes, or 'donut-holes', from raster polygons. Found in Data Tools.

  437. RemoveShortStreams: Removes short first-order streams from a stream network. Found in Stream Network Analysis.

  438. RemoveSpurs: Removes the spurs (pruning operation) from a Boolean line image; intended to be used on the output of the LineThinning tool. Found in Image Processing Tools.

  439. RepairStreamVectorTopology: This tool resolves topological errors and inconsistencies associated with digitized vector streams. Found in Stream Network Analysis.

  440. Resample: Resamples one or more input images into a destination image. Found in Image Processing Tools.

  441. RescaleValueRange: Performs a min-max contrast stretch on an input greytone image. Found in Math and Stats Tools.

  442. RgbToIhs: Converts red, green, and blue (RGB) images into intensity, hue, and saturation (IHS) images. Found in Image Processing Tools.

  443. Rho8FlowAccumulation: Calculates Fairfield and Leymarie (1991) flow accumulation. Found in Hydrological Analysis.

  444. Rho8Pointer: Calculates a stochastic Rho8 flow pointer raster from an input DEM. Found in Hydrological Analysis.

  445. RingCurvature: This tool calculates ring curvature from an input DEM. Found in Geomorphometric Analysis.

  446. RiverCenterlines: Maps river centerlines from an input water raster. Found in Hydrological Analysis.

  447. RobertsCrossFilter: Performs a Robert's cross edge-detection filter on an image. Found in Image Processing Tools → Filters.

  448. RootMeanSquareError: Calculates the RMSE and other accuracy statistics. Found in Math and Stats Tools.

  449. Rotor: This tool calculates rotor from an input DEM. Found in Geomorphometric Analysis.

  450. Round: Rounds the values in an input raster to the nearest integer value. Found in Math and Stats Tools.

  451. RuggednessIndex: Calculates the Riley et al.'s (1999) terrain ruggedness index from an input DEM. Found in Geomorphometric Analysis.

  452. ScharrFilter: Performs a Scharr edge-detection filter on an image. Found in Image Processing Tools → Filters.

  453. SedimentTransportIndex: Calculates the sediment transport index. Found in Geomorphometric Analysis.

  454. SelectTilesByPolygon: Copies LiDAR tiles overlapping with a polygon into an output directory. Found in LiDAR Tools.

  455. SetNodataValue: Assign the NoData value for an input image. Found in Data Tools.

  456. ShadowAnimation: This tool creates an animated GIF of shadows based on an input DEM. Found in Geomorphometric Analysis.

  457. ShadowImage: This tool creates a raster of shadow areas based on an input DEM. Found in Geomorphometric Analysis.

  458. ShapeComplexityIndexRaster: Calculates the complexity of raster polygons or classes. Found in GIS Analysis → Patch Shape Tools.

  459. ShapeComplexityIndex: Calculates overall polygon shape complexity or irregularity. Found in GIS Analysis → Patch Shape Tools.

  460. ShapeIndex: This tool calculates the shape index from an input DEM. Found in Geomorphometric Analysis.

  461. ShreveStreamMagnitude: Assigns the Shreve stream magnitude to each link in a stream network. Found in Stream Network Analysis.

  462. SigmoidalContrastStretch: Performs a sigmoidal contrast stretch on input images. Found in Image Processing Tools → Image Enhancement.

  463. Sin: Returns the sine (sin) of each values in a raster. Found in Math and Stats Tools.

  464. SinglePartToMultiPart: Converts a vector file containing multi-part features into a vector containing only single-part features. Found in Data Tools.

  465. Sinh: Returns the hyperbolic sine (sinh) of each values in a raster. Found in Math and Stats Tools.

  466. Sink: Identifies the depressions in a DEM, giving each feature a unique identifier. Found in Hydrological Analysis.

  467. SlopeVsAspectPlot: This tool creates a slope-aspect relation plot from an input DEM. Found in Geomorphometric Analysis.

  468. SlopeVsElevationPlot: Creates a slope vs. elevation plot for one or more DEMs. Found in Geomorphometric Analysis.

  469. Slope: Calculates a slope raster from an input DEM. Found in Geomorphometric Analysis.

  470. SmoothVectors: Smooths a vector coverage of either a POLYLINE or POLYGON base ShapeType. Found in GIS Analysis.

  471. SmoothVegetationResidual: This tool can smooth the residual roughness due to vegetation cover in LiDAR DEMs. Found in Geomorphometric Analysis.

  472. SnapPourPoints: Moves outlet points used to specify points of interest in a watershedding operation to the cell with the highest flow accumulation in its neighbourhood. Found in Hydrological Analysis.

  473. SobelFilter: Performs a Sobel edge-detection filter on an image. Found in Image Processing Tools → Filters.

  474. SortLidar: Sorts LiDAR points based on their properties. Found in LiDAR Tools.

  475. SphericalStdDevOfNormals: Calculates the spherical standard deviation of surface normals for a DEM. Found in Geomorphometric Analysis.

  476. SplitColourComposite: Splits an RGB colour composite image into separate multispectral images. Found in Image Processing Tools.

  477. SplitLidar: Splits LiDAR points up into a series of new files based on their properties. Found in LiDAR Tools.

  478. SplitVectorLines: Used to split a vector line coverage into even-lengthed segments. Found in GIS Analysis.

  479. SplitWithLines: Splits the lines or polygons in one layer using the lines in another layer. Found in GIS Analysis → Overlay Tools.

  480. SquareRoot: Returns the square root of the values in a raster. Found in Math and Stats Tools.

  481. Square: Squares the values in a raster. Found in Math and Stats Tools.

  482. StandardDeviationContrastStretch: Performs a standard-deviation contrast stretch on input images. Found in Image Processing Tools → Image Enhancement.

  483. StandardDeviationFilter: Assigns each cell in the output grid the standard deviation of values in a moving window centred on each grid cell in the input raster. Found in Image Processing Tools → Filters.

  484. StandardDeviationOfSlope: Calculates the standard deviation of slope from an input DEM. Found in Geomorphometric Analysis.

  485. StochasticDepressionAnalysis: Performs a stochastic analysis of depressions within a DEM. Found in Hydrological Analysis.

  486. StrahlerOrderBasins: Identifies Strahler-order basins from an input stream network. Found in Hydrological Analysis.

  487. StrahlerStreamOrder: Assigns the Strahler stream order to each link in a stream network. Found in Stream Network Analysis.

  488. StreamLinkClass: Identifies the exterior/interior links and nodes in a stream network. Found in Stream Network Analysis.

  489. StreamLinkIdentifier: Assigns a unique identifier to each link in a stream network. Found in Stream Network Analysis.

  490. StreamLinkLength: Estimates the length of each link (or tributary) in a stream network. Found in Stream Network Analysis.

  491. StreamLinkSlope: Estimates the average slope of each link (or tributary) in a stream network. Found in Stream Network Analysis.

  492. StreamPowerIndex: Calculates the relative stream power index. Found in Geomorphometric Analysis.

  493. StreamSlopeContinuous: Estimates the slope of each grid cell in a stream network. Found in Stream Network Analysis.

  494. Subbasins: Identifies the catchments, or sub-basin, draining to each link in a stream network. Found in Hydrological Analysis.

  495. Subtract: Performs a differencing operation on two rasters or a raster and a constant value. Found in Math and Stats Tools.

  496. SumOverlay: Calculates the sum for each grid cell from a group of raster images. Found in GIS Analysis → Overlay Tools.

  497. SurfaceAreaRatio: Calculates a the surface area ratio of each grid cell in an input DEM. Found in Geomorphometric Analysis.

  498. SvmClassification: Performs an SVM binary classification using training site polygons/points and multiple input images. Found in Machine Learning.

  499. SvmRegression: Performs a supervised SVM regression analysis using training site points and predictor rasters. Found in Machine Learning.

  500. SymmetricalDifference: Outputs the features that occur in one of the two vector inputs but not both, i.e. no overlapping features. Found in GIS Analysis → Overlay Tools.

  501. Tan: Returns the tangent (tan) of each values in a raster. Found in Math and Stats Tools.

  502. TangentialCurvature: Calculates a tangential curvature raster from an input DEM. Found in Geomorphometric Analysis.

  503. Tanh: Returns the hyperbolic tangent (tanh) of each values in a raster. Found in Math and Stats Tools.

  504. ThickenRasterLine: Thickens single-cell wide lines within a raster image. Found in Image Processing Tools.

  505. TimeInDaylight: Calculates the proportion of time a location is not within an area of shadow. Found in Geomorphometric Analysis.

  506. TinGridding: Creates a raster grid based on a triangular irregular network (TIN) fitted to vector points. Found in GIS Analysis.

  507. ToDegrees: Converts a raster from radians to degrees. Found in Math and Stats Tools.

  508. ToRadians: Converts a raster from degrees to radians. Found in Math and Stats Tools.

  509. TophatTransform: Performs either a white or black top-hat transform on an input image. Found in Image Processing Tools.

  510. TopoRender: This tool creates a pseudo-3D rendering from an input DEM, for the purpose of effective topographic visualization. Found in Geomorphometric Analysis.

  511. TopographicPositionAnimation: This tool creates an animated GIF of multi-scale local topographic position (elevation deviation). Found in Geomorphometric Analysis.

  512. TopologicalBreachBurn: This tool burns streams into a DEM using the topological breach-burn method of Lindsay (2016). Found in Hydrological Analysis.

  513. TopologicalStreamOrder: Assigns each link in a stream network its topological order. Found in Stream Network Analysis.

  514. TotalCurvature: Calculates a total curvature raster from an input DEM. Found in Geomorphometric Analysis.

  515. TotalFilter: Performs a total filter on an input image. Found in Image Processing Tools → Filters.

  516. TraceDownslopeFlowpaths: Traces downslope flowpaths from one or more target sites (i.e. seed points). Found in Hydrological Analysis.

  517. TravellingSalesmanProblem: Finds approximate solutions to travelling salesman problems, the goal of which is to identify the shortest route connecting a set of locations. Found in GIS Analysis.

  518. TrendSurfaceVectorPoints: Estimates a trend surface from vector points. Found in Math and Stats Tools.

  519. TrendSurface: Estimates the trend surface of an input raster file. Found in Math and Stats Tools.

  520. TributaryIdentifier: Assigns a unique identifier to each tributary in a stream network. Found in Stream Network Analysis.

  521. Truncate: Truncates the values in a raster to the desired number of decimal places. Found in Math and Stats Tools.

  522. TurningBandsSimulation: Creates an image containing random values based on a turning-bands simulation. Found in Math and Stats Tools.

  523. TwoSampleKsTest: Performs a 2-sample K-S test for significant differences on two input rasters. Found in Math and Stats Tools.

  524. Union: Splits vector layers at their overlaps, creating a layer containing all the portions from both input and overlay layers. Found in GIS Analysis → Overlay Tools.

  525. UnnestBasins: Extract whole watersheds for a set of outlet points. Found in Hydrological Analysis.

  526. UnsharpMasking: An image sharpening technique that enhances edges. Found in Image Processing Tools → Filters.

  527. Unsphericity: This tool calculates the unsphericity curvature from an input DEM. Found in Geomorphometric Analysis.

  528. UpdateNodataCells: Replaces the NoData values in an input raster with the corresponding values contained in a second update layer. Found in GIS Analysis → Overlay Tools.

  529. UpslopeDepressionStorage: Estimates the average upslope depression storage depth. Found in Hydrological Analysis.

  530. UserDefinedWeightsFilter: Performs a user-defined weights filter on an image. Found in Image Processing Tools → Filters.

  531. VectorHexBinning: Hex-bins a set of vector points. Found in GIS Analysis.

  532. VectorLinesToRaster: Converts a vector containing polylines into a raster. Found in Data Tools.

  533. VectorPointsToRaster: Converts a vector containing points into a raster. Found in Data Tools.

  534. VectorPolygonsToRaster: Converts a vector containing polygons into a raster. Found in Data Tools.

  535. VectorStreamNetworkAnalysis: This tool performs common stream network analysis operations on an input vector stream file. Found in Stream Network Analysis.

  536. VerticalExcessCurvature: This tool calculates vertical excess curvature from an input DEM. Found in Geomorphometric Analysis.

  537. Viewshed: Identifies the viewshed for a point or set of points. Found in Geomorphometric Analysis.

  538. VisibilityIndex: Estimates the relative visibility of sites in a DEM. Found in Geomorphometric Analysis.

  539. VoronoiDiagram: Creates a vector Voronoi diagram for a set of vector points. Found in GIS Analysis.

  540. Watershed: Identifies the watershed, or drainage basin, draining to a set of target cells. Found in Hydrological Analysis.

  541. WeightedOverlay: Performs a weighted sum on multiple input rasters after converting each image to a common scale. The tool performs a multi-criteria evaluation (MCE). Found in GIS Analysis → Overlay Tools.

  542. WeightedSum: Performs a weighted-sum overlay on multiple input raster images. Found in GIS Analysis → Overlay Tools.

  543. WetnessIndex: Calculates the topographic wetness index, Ln(A / tan(slope)). Found in Geomorphometric Analysis.

  544. WilcoxonSignedRankTest: Performs a 2-sample K-S test for significant differences on two input rasters. Found in Math and Stats Tools.

  545. WriteFunctionMemoryInsertion: Performs a write function memory insertion for single-band multi-date change detection. Found in Image Processing Tools.

  546. Xor: Performs a logical XOR operator on two Boolean raster images. Found in Math and Stats Tools.

  547. YieldFilter: Filters crop yield values of point data derived from combine harvester yield monitors. Found in Precision Agriculture.

  548. YieldMap: This tool can be used to create a segmented-vector polygon yield map from a set of harvester points. Found in Precision Agriculture.

  549. YieldNormalization: This tool can be used to normalize the yield points for a field. Found in Precision Agriculture.

  550. ZScores: Standardizes the values in an input raster by converting to z-scores. Found in Math and Stats Tools.

  551. ZlidarToLas: Converts one or more zlidar files into the LAS data format. Found in LiDAR Tools.

  552. ZonalStatistics: Extracts descriptive statistics for a group of patches in a raster. Found in Math and Stats Tools.