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


Introduction
WhiteboxTools is an advanced geospatial data analysis platform created by Prof. John Lindsay at the University of Guelph's Geomorphometry and Hydrogeomatics Research Group (GHRG). The project began in January 2017 and quickly evolved in terms of its analytical capabilities. The WhiteboxTools homepage contains more project information and the software download site.
Project Highlights
- Contains more than 440 tools for processing various types of geospatial data.
- Many tools operate in parallel, taking full advantage of your multi-core processor.
- Written in the safe and cross-platform systems programming language Rust and compiled to highly efficient native code.
- Small stand-alone application with no external dependencies, making installation as easy as downloading the 8Mb zip file and decompressing it.
- Simple yet powerful Python scripting interface that allows users to develop custom scripted workflows.
- Embed WhiteboxTools functions into hetergenous scripting environments along with ArcPy, GDAL, and other geoprocessing libraries.
- Serves as an analytical back-end for other GIS and remote sensing software (e.g. the QGIS Whitebox for Processing plugin).
- Permissive MIT open-source license allows for ready integration with other software.
- Transparent software philosopy allows for easy source code inspection and rapid innovation and development.
What can WhiteboxTools do?
WhiteboxTools can be used to perform common geographical information systems (GIS) analysis operations, such as cost-distance analysis, distance buffering, and raster reclassification. Remote sensing and image processing tasks include image enhancement (e.g. panchromatic sharpening, contrast adjustments), image mosaicking, numerous filtering operations, simple classification (k-means clustering), and common image transformations. WhiteboxTools also contains advanced tooling for spatial hydrological analysis (e.g. flow-accumulation, watershed delineation, stream network analysis, sink removal), geomorphometric analysis (e.g. common terrain indices such as slope, curvatures, wetness index, hillshading; hypsometric analysis; multi-scale topographic position analysis), and LiDAR data processing. LiDAR point clouds can be interrogated (LidarInfo, LidarHistogram), segmented, tiled and joined, analyzed for outliers, interpolated to rasters (DEMs, intensity images), and ground-points can be classified or filtered.
WhiteboxTools is not a cartographic or spatial data visualization package; instead it is meant to serve as an analytical backend for other data visualization software, mainly GIS (e.g. Whitebox GAT and QGIS).
WhiteboxTools vs. Whitebox Geospatial Analysis Tools (GAT)
Although WhiteboxTools was first developed with to serve as a source of plugin tools for the Whitebox Geospatial Analysis Tools (GAT) open-source GIS project, the tools contained in the library are stand-alone and can run outside of the larger Whitebox GAT project. See Interacting With WhiteboxTools From the Command Prompt for further details. There have been a large number of requests to call Whitebox GAT tools and functionality from outside of the Whitebox GAT user-interface (e.g. from Python automation scripts). WhiteboxTools is intended to meet these usage requirements. For example, a WhiteboxTools plug-in for QGIS is available.
In this manual, WhiteboxTools refers to the standalone geospatial analysis library, a collection of tools contained within a compiled binary executable command-line program and the associated Python scripts that are distributed alongside the binary file (e.g. whitebox_tools.py and wb_runner.py). Whitebox Geospatial Analysis Tools and Whitebox GAT refer to the GIS software, which includes a user-interface (front-end), point-and-click tool interfaces, and cartographic data visualization capabilities. Importantly, WhiteboxTools and Whitebox GAT are related but separate projects.
Why is it named WhiteboxTools?
The project name WhiteboxTools clearly takes it inspiration from the related project Whitebox GAT. However, the name Whitebox is intended to convey opposition to a 'black box' system, one for which only the inputs and outputs may be observed and the internal workings may not be scrutinized. WhiteboxTools is inspired by the concept of open-access software, the tenants of which were described by Lindsay (2014)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 GitHub site or from the Geomorphometry and Hydrogeomatics Research Group homepage and decompress the folder. Pre-compiled binaries can be downloaded for MS Windows, MacOS, and Linux operating systems. Depending on your operating system, you may need to grant the WhiteboxTools executable file execution privileges before running it.
If you intend to use WhiteboxTools from the command prompt (i.e. a terminal application), you may wish to add the directory containing the WhiteboxTools executable file to your system PATH variable. Doing so will greatly simplify usage of the library from your terminal. Instructions for doing this depend on your operating system and can be found on the Internet.
If you intend to use the Python programming interface for WhiteboxTools you will need to have Python 3 installed. Please note that the Python interface will not work correctly with Python 2. If your system has Python 2 as the default Python version, it is possible to install Python 3 alongside your current version. You may need to use the python3
command in place of the usual python
if this is the case.
Building WhiteboxTools From Source Code
Most users rely on the pre-compiled versions of WhiteboxTools and will never need to compile the software from its source code. There are two circumstances under which you may find that you need to build your own binary executable: 1) if you need a binary compiled for a platform other than the project-supported operating systems, and 2) if you require a bleeding-edge feature or bug-fix only available in the development branch. It is likely that WhiteboxTools will work on a wider variety of operating systems and architectures than those of the distributed pre-compiled binaries. If you do not find your operating system/architecture in the list of available WhiteboxTool binaries, then compilation from source code will be necessary. WhiteboxTools can be compiled from the source code with the following steps:
- 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).
-
Download the WhiteboxTools source code. To download the code, click the green Clone or download button on the GitHub repository site.
-
Decompress the zipped download file.
-
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/
- 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 withconda install -c conda-forge whitebox_tools
, although it is unclear if this package is regularly updated to reflect the latest versions of WhiteboxTools.
Using the whitebox_tools.py script
Interacting with WhiteboxTools from Python scripts is easy. To begin, each script must start by importing the WhiteboxTools class, contained with the whitebox_tools.py script; a new WhiteboxTools
object can then be created:
from WBT.whitebox_tools import WhiteboxTools
wbt = WhiteboxTools()
Depending on the relative location of the WhiteboxTools directory and the script file that you are importing to, the import statement may need to be altered slightly. In the above script, it is assumed that the folder containing the WhiteboxTools files (including the whitebox_tools Python script) is named WBT
(Line 1) and that the calling script that is importing WhiteboxTools is located in the parent directory of WBT
. See An Example WhiteboxTools Python Project for more details on project set-up. The use of wbt
to designate the WhiteboxTools object variable in the above script (Line 3) is just the convention used in this manual and other project resources. In fact, any variable name can be used for this purpose.
The WhiteboxTools
class expects to find the WhiteboxTools executable file (whitebox_tools.exe on Windows and whitebox_tools on other platforms) within the same directory (WBT
) as the whitebox_tools.py script. If the binary file is located in a separate directory, you will need to set the executable directory as follows:
wbt.set_whitebox_dir('/local/path/to/whitebox/binary/')
Individual tools can be called using the convenience methods provided in the WhiteboxTools
class:
# This line performs a 5 x 5 mean filter on 'inFile.tif':
wbt.mean_filter('/file/path/inFile.tif', '/file/path/outFile.tif', 5, 5)
Each tool has a cooresponding convenience method. The listing of tools in this manual includes information about each tool's Python convienience method, including default parameter values. Parameters with default values may be optionally left off of function calls. In addition to the convenience methods, tools can be called using the run_tool()
method, specifying the tool name and a list of tool arguments.
source = "source.tif"
cost = "cost.tif"
out_accum = "accum.tif"
out_backlink = "backlink.tif"
args = []
args.append("--source='{}'".format(source))
args.append("--cost='{}'".format(cost))
args.append("--out_accum='{}'".format(out_accum))
args.append("--out_backlink='{}'".format(out_backlink))
self.run_tool('cost_distance', args)
Each of the tool-specific convenience methods collect their parameters into a properly formated list and then ultimately call the run_tools()
method. Notice that while internally whitebox_tools.exe uses CamelCase (e.g. MeanFilter) to denote tool names, the Python interface of whitebox_tools.py uses snake_case (e.g. mean_filter), according to Python style conventions. The only exceptions are tools with names that clash with Python keywords (e.g. And()
, Not()
, and Or()
).
The return value can be used to check for errors during operation:
if wbt.ruggedness_index('/path/DEM.tif', '/path/ruggedness.tif') != 0:
# Non-zero returns indicate an error.
print('ERROR running ruggedness_index')
If your data files tend to be burried deeply in layers of sub-directories, specifying complete file names as input parameters can be tedius. In this case, the best option is setting the working directory before calling tools:
from whitebox_tools import WhiteboxTools
wbt = WhiteboxTools()
wbt.set_whitebox_dir("/path/to/data/") # Sets the Whitebox working directory
# Setting the following to True enables tools to output DEFLATE compressed GeoTIFFs.
# You only need to do this once, if you wish all tools to compress their raster
# outputs.
wbt.set_compress_rasters(True)
# Because the working directory has been set, file arguments can be
# specified simply using file names, without paths.
wbt.d_inf_flow_accumulation("DEM.tif", "output.tif", log=True)
An advanced text editor, such as VS Code or Atom, can provide hints and autocompletion for available tool convenience methods and their parameters, including default values (Figure 1).
Sometimes it can be useful to print a complete list of available tools:
print(wbt.list_tools()) # List all tools in WhiteboxTools
The list_tools()
method also takes an optional keywords list to search for tools:
# Lists tools with 'lidar' or 'LAS' in tool name or description.
print(wbt.list_tools(['lidar', 'LAS']))
To retrieve more detailed information for a specific tool, use the tool_help()
method:
print(wbt.tool_help("elev_percentile"))
tool_help()
prints tool details including a description, tool parameters (and their flags), and example usage at the command line prompt. The above statement prints this report:
ElevPercentile
Description:
Calculates the elevation percentile raster from a DEM.
Toolbox: Geomorphometric Analysis
Parameters:
Flag Description
----------------- -----------
-i, --input, --dem Input raster DEM file.
-o, --output Output raster file.
--filterx Size of the filter kernel in the x-direction.
--filtery Size of the filter kernel in the y-direction.
--sig_digits Number of significant digits.
Example usage:
>>./whitebox_tools -r=ElevPercentile -v --wd="/path/to/data/" --dem=DEM.tif
>>-o=output.tif --filterx=25
A note on default parameter values
Each tool contains one or more parameters with default values. These will always be listed after any input parameters that do not have default values. You do not need to specify a parameter with a default value if you accept the default. That is, unless you intend to specify an input value different from the default, you may leave these parameters off of the function call. However, be mindful of the fact that Python assigns values to parameters based on order, unless parameter names are specified.
Consider the Hillshade tool as an example. The User Manual gives the following function definition for the tool:
hillshade( dem, output, azimuth=315.0, altitude=30.0, zfactor=1.0, callback=default_callback)
The
dem
andoutput
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 thehillshade
function. As an example, say I want to accept the default values for all the parameters exceptaltitude
. I would then need to use the named-parameter form of the function call:wbt.hillshade( "DEM.tif", "hillshade.tif", altitude=20.0)
If I hadn't specified the parameter name for
altitude
, Python would have assumed that the value 20.0 should be assigned to the third parameter,azimuth
.
Handling tool output
Tools will frequently print text to the standard output during their execution, including warnings, progress updates and other notifications. Sometimes, when users run many tools in complex workflows and in batch mode, these output messages can be undesirable. Most tools will have their outputs suppressed by setting the verbose mode to False as follows:
wbt.set_verbose_mode(False)
Alternatively, it may be helpful to capture the text output of a tool for custom processing. This is achieved by specifying a custom callback function to the tool's convenience function:
# This callback function suppresses printing progress updates,
# which always use the '%' character. The callback function
# approach is flexible and allows for any level of complex
# interaction with tool outputs.
def my_callback(value):
if not "%" in value:
print(value)
wbt.slope('DEM.tif', 'slope_raster.tif', callback=my_callback)
Every convienience function takes an optional callback as the last parameter. The default callback simply prints tool outputs to the standard output without any additional processing. The default callback itself can be overridden, instead of having to set callbacks in convienience functions individually:
wbt.set_default_callback(my_callback)
Callback functions can serve as a means of cancelling operations:
def my_callback(value):
if user_selected_cancel_btn: # Assumes a 'Cancel' button on a GUI
print('Cancelling operation...')
wbt.cancel_op = True
else:
print(value)
wbt.breach_depressions('DEM.tif', 'DEM_breached.tif', callback=my_callback)
Additional functions in whitebox_tools.py
The whitebox_tools.py script provides several other functions for interacting with the WhiteboxTools library, including:
# Print the WhiteboxTools help...a listing of available commands
print(wbt.help())
# Print the WhiteboxTools license
print(wbt.license())
# Print the WhiteboxTools version
print("Version information: {}".format(wbt.version()))
# Get the toolbox associated with a tool
tb = wbt.toolbox('lidar_info')
# Retrieve a JSON object of a tool's parameters.
tp = wbt.tool_parameters('raster_histogram')
# Opens a browser and navigates to a tool's source code in the
# WhiteboxTools GitHub repository
wbt.view_code('watershed')
# Use this function to specify whether output GeoTIFF rasters should be
# compressed using the DEFLATE compression method.
wbt.set_compress_rasters(True)
For a working example of how to call functions and run tools from Python, see the whitebox_example.py Python script, which is distributed with the WhiteboxTools library.
Additional resources for using WhiteboxTools' Python interface can be found on the Tutorials site of the WhiteboxTools home page. This site contains in-depth tutorials on topics such as, 'Interpolating LiDAR data'.
An Example Python Project
In this section, we will create a Python project that utilizes the WhiteboxTools library to interpolate a LiDAR point-cloud, to process the resulting digital elevation model (DEM) to make it suitable for hydrological applications, and to perform a simple flow-accumulation operation. I suggest using an advanced coding text editor, such as Visual Studio Code or Atom, for this tutorial, but Python code can be written using any basic text editor.
Begin by creating a dedicated project directory called FlowAccumExample and copy WhiteboxTools binary file (i.e. the compressed file downloaded from the Geomorphometry & Hydrogeomatics Research Group website) into this folder. Using the decompression software on your computer, decompress (i.e. an operation sometimes called unzipping) the file into the newly created FlowAccumExample directory. You will find the compressed file contains a folder with contents similar to the following:

The folder contains a number of files, including the WhiteboxTools executable file, the whitebox_tools.py python script, the WhiteboxTools Runner (wb_runner.py; see below), and this user manual. It is likely that the folder has a name that reflects the operating system and architecture that the binary file was compiled for (e.g. WhiteboxTools_darwin_amd64). Rename this directory to WBT. Also note, depending on your decompression software, it may be the case that the contents of the WBT folder itself contains a sub-directory that actually holds these files. If this is the case, be sure to move the contents of the sub-directory into the WBT parent directory.
Using your text editor, create a new Python script file, called FlowAccumulation.py within the FlowAccumExample directory. We will begin by importing the WhiteboxTools class from the whitebox_tools.py script contained within the WBT sub-directory. Unfortunately, Python's module system is only able to import classes and function definitions declared in external Python scripts if these external files are contained somewhere on the Python path or in the directory containing the script file into which you are importing. This is important because based on the project structure that we have established, the whitebox_tools.py script is actually contained within a sub-directory of the FlowAccumExample directory and is therefore not directly accessible, unless you have previously installed the script on the Python path. Another, perhaps easier solution to this problem is to create a file named __init__.py (those are two leading and trailing underscore characters) within the FlowAccumExample directory. The presence of this empty file will make Python treat the WBT directory as containing packages, in this case, the whitebox_tools package. For more information, see the Python documentation on modules and packages.
At this stage, you should have a project directory structure like the following:

Many operating systems will disallow the execution of files that are downloaded directly from the Internet. As such, it is possible that you will need to explicitly give the whitebox_tools.exe permission to execute on your computer (Note: here we are referring to the compiled WhiteboxTools binary file and not the similarly named Python script whitebox_tools.py also contained in the folder). The procedure for doing this depends on your specific operating system. On MacOS, for example, this is usually achieved using the 'Security & Privacy' tab under 'System Preferences'. To test whether whitebox_tools.exe has permission to run on your system, double-click the file. If the file is configured to execute, a command terminal will automatically open and the WhiteboxTools help documentation and a listing of the available tools will be printed. If this does not occur, you likely need to give the file permission to execute.
Using your text editor, you may now add the following lines to the FlowAccumulation.py file.
from WBT.whitebox_tools import WhiteboxTools
wbt = WhiteboxTools()
In the import statement, WBT
is a reference to the package folder containing the WhiteboxTools files; whitebox_tools
is a reference to the whitebox_tools.py script contained with this package folder; and WhiteboxTools
is a reference to the WhiteboxTools class contained within this script file. Please note that if you named your directory containing the WhiteboxTools files something other than WBT, you would need to alter the import statement accordingly.
Visit the Geomorphometry and Hydrogeomatics Research Group website and download the St. Elis Mountains and Gulf of Alaska sample data set (StElisAk.las) from the WhiteboxTools section of the site. This file contains a LiDAR point cloud that has been previously filtered to remove points associated with non-ground returns, mainly trees (Figure 4). Create a sub-directory within the project folder called 'data' and copy StElisAk.las into the folder.
Now we can complete our flow accumulation analysis with the following code:
import os
from WBT.whitebox_tools import WhiteboxTools
wbt = WhiteboxTools()
# Set the working directory, i.e. the folder containing the data,
# to the 'data' sub-directory.
wbt.set_working_dir(os.path.dirname(os.path.abspath(__file__)) + "/data/")
# When you're running mulitple tools, the outputs can be a tad
# chatty. In this case, you may want to suppress the output by
# setting the verbose mode to False.
# wbt.set_verbose_mode(False)
# Interpolate the LiDAR data using an inverse-distance weighting
# (IDW) scheme.
print("Interpolating DEM...")
wbt.lidar_idw_interpolation(
i="StElisAk.las",
output="raw_dem.tif",
parameter="elevation",
returns="last",
resolution=1.0,
weight=1.0,
radius=2.5
)
# The resulting DEM will contain NoData gaps. We need to fill
# these in by interpolating across the gap.
print("Filling missing data...")
wbt.fill_missing_data(
i="raw_dem.tif",
output="dem_nodata_filled.tif",
filter=11
)
# This DEM will contain grid cells that have no lower neighbours.
# This condition is unsuited for flow-path modelling applications
# because these operations assume that each interior cell in the
# DEM has at least one downslope neighour. We'll use an operation
# called depression breaching to 'fix' the elevations within the
# DEM to enforce continuous flow.
print("Performing flow enforcement...")
wbt.breach_depressions(
dem="dem_nodata_filled.tif",
output="dem_hydro_enforced.tif"
)
# Lastly, perform the flow accumulation operation using the
# D-infinity flow algorithm.
print("Performing flow accumulation...")
wbt.d_inf_flow_accumulation(
dem="dem_hydro_enforced.tif",
output="flow_accum.tif",
log=True
)
print("Complete!")
To run the above script, open a terminal (command prompt), cd to the script containing folder, and run the following command:
>>python FlowAccumulation.py
If Python 3 is not your default Python version, substitute python3
for python
in the above command line. The final D-infinity flow accumulation raster can be displayed in any GIS software of choice and should look similar to Figure 5.
Interfacing With R
In addition to the Python interface, the WhiteboxTools library is also accessible from an R language package. R is a common programming language used within the statistical and scientific computing communities and the R WhiteboxTools package targets these groups. Prof. Qiusheng Wu, at Binghamton University (SUNY) maintains the R package.
Installation
WhiteboxTools is available on R-Forge and can be installed with the command:
install.packages("whitebox", repos="http://R-Forge.R-project.org")
You can alternatively install the development version of the R package whitebox from the GitHub repository as follows:
if (!require(devtools)) install.packages('devtools')
devtools::install_github("giswqs/whiteboxR")
You will also need to make sure your machine is able to build packages from source. See Package Development Prerequisites for the tools needed for your operating system.
Usage
A complete list of functions available in the whitebox R package can be found within the GitHub repository. A comprehensive demonstration, complete with detailed examples, is also available from this site.
About WhiteboxTools
library(whitebox)
# Prints the whitebox-tools help...a listing of available commands
print(wbt_help())
# Prints the whitebox-tools license
print(wbt_license())
# Prints the whitebox-tools version
print(wbt_version())
# Prints the toolbox for a specific tool.
print(wbt_toolbox())
# List all available tools in whitebox-tools
print(wbt_list_tools())
# Lists tools with 'lidar' in tool name or description.
print(wbt_list_tools("lidar"))
# Prints the help for a specific tool.
print(wbt_tool_help("lidar_info"))
# Retrieves the tool parameter descriptions for a specific tool.
print(wbt_tool_parameters("slope"))
# View the source code for a specific tool on the source code repository.
print(wbt_view_code("breach_depressions"))
How to run tools?
Tool names in the whitebox R package can be called using the snake_case (e.g. lidar_info). A comprehensive list of all available function tools can be found on the package repository site. For example:
library(whitebox)
# Set input raster DEM file
dem <- system.file("extdata", "DEM.tif", package="whitebox")
# Run tools
feature_preserving_denoise(dem, "./smoothed.tif", filter=9)
breach_depressions("./smoothed.tif", "./breached.tif")
d_inf_flow_accumulation(dem, "./flow_accum.tif", verbose_mode=FALSE)
Interfacing With Nim
Nim is a statically compiled programming language that has Python-like syntax (e.g. significant whitespace) and c-level efficiency. It has been used by Python programmers who are looking for a faster, more efficient language but don't want to give up the elegant and terse syntax of Python.
wbt_nim is a Nim-based application programming interface (API) used to call WhiteboxTools functionality from Nim programs. The documentation for wbt_nim can be found on GitHub. To use this API, simply copy the source file into your Nim project and import wbt_nim. You will need to ensure that the WhiteboxTools binary, pre-compiled for your operating system, is also within the same directory. Otherwise, use the setExecutableDirectory function to tell wbt_nim where the WhiteboxTools binary is located on your system.
The Nim interface is very similar to the Python API:
import wbt_nim
import options, strformat, strutils
proc main() =
# Create a new WhiteboxTools object
var wbt = newWhiteboxTools()
# Tell the wbt object where to find the WhiteboxTools executable.
# If you don't do this, it assumes that it is in the same directory as
# your Nim code.
wbt.setExecutableDirectory("/Users/johnlindsay/Documents/programming/whitebox-tools/")
# Set the working directory
let wd = "/Users/johnlindsay/Documents/data/LakeErieLidar/"
wbt.setWorkingDirectory(wd)
# Set the verbose mode. By default it is 'true', which prints all output
# from WBT. If you need to make it less chatty, set it to false.
wbt.setVerboseMode(false)
# By default, all GeoTiff outputs of tools will be compressed. You can
# modify this with the following:
wbt.setCompressRasters(false)
# Print out the version of WBT:
echo(wbt.getVersionInfo())
# WhiteboxTools is open-access software. If you'd like to see the source
# code for any tool, simply use the following:
discard wbt.viewCode("balanceContrastEnhancement")
# To get a brief description of a tool and it's parameters:
echo(wbt.getToolHelp("breachDepressionsLeastCost"))
# If you'd like to see more detailed help documentation:
discard wbt.viewHelpPage("breachDepressionsLeastCost")
# This will open the default browser and navigate to the relevant tool help.
# Here's an example of how to run a tool:
if wbt.hillshade(
dem="90m_DEM.tif",
output="tmp1.tif",
azimuth=180.0,
altitude=45.0,
zFactor=1.0
) != 0:
echo("Error while running hillshade.")
# If you haven't previously set the working directory, you need to include
# full file path names.
# You can capture tool output by creating a custom callback function
proc myCallback(value: string) =
if not value.contains("%"):
echo(value)
else:
let s = value.replace("%", "").strip()
echo(fmt"{s} percent")
wbt.setCallback(myCallback)
# And to reset the default callback, which just prints to stdout
wbt.setDefaultCallback()
main()
WhiteboxTools Runner
There is a Python script contained within the WhiteboxTools directory called 'wb_runner.py'. This script is intended to provide a very basic user-interface, WhiteboxTools Runner, for running the tools contained within the WhiteboxTools library. The user-interface uses Python's TkInter GUI library and is cross-platform. The user interface is currently experimental and is under heavy testing. Please report any issues that you experience in using it.
The script must be run from a directory that also contains the 'whitebox_tools.py' Python script and the 'whitebox_tools' executable file.
To launch the runner application, open a terminal and issue issue the following commands:
cd /path/to/whitebox_runner/script/
python3 wb_runner.py
If you recieve No module named '_tkinter'
error when running the WhiteboxTools Runner on Linux, you likely need to install the python3-tk package:
- For Ubuntu, Linux Mint, try sudo apt-get install python3-tk
- For Manjaro, Arch Linux, try sudo pacman -S tk
QGIS Plugin
WhiteboxTools functionality can also be accessed conveniently through the popular open-source geospatial software QGIS. QGIS developer Alexander Bruy maintains a plugin for the toolbox called Whitebox For Processing.
The Whitebox for QGIS plugin works QGIS v3 but cannot be installed on the earlier v2 series.
Installation of the Plugin
- From the Plugins menu, select Manage and Install Plugins....
- Select the Settings tab and press the Add button.
- In the Repository details dialog box, enter something logical, such as Alex Bruy Plugins in the Name textbox.
- In the URL textbox, enter
https://plugins.bruy.me/plugins/plugins.xml
and press OK.
- Select the All tab and enter the word 'whitebox' in the search box.
Whitebox for Processing
should appear the search listing. Select and check this toolbox and press the Install buttton.
Note that the QGIS plugin does not come with a copy of the WhiteboxTools executable and so you will still need to download WhiteboxTools from either the Geomorphometry and Hydrogeomatics Research Group website or the WhiteboxTools Github repository prior to running the plugin.
-
Once you've downloaded WhiteboxTools and decompressed (unzipped) the folder, select Options from under the Settings menu in QGIS.
-
Select the Processing tab and the Providers list item. You should find the WhiteboxTools entry there. Select the down arrow, and check the Activate and Log commands output checkboxes. Lastly, enter full file name of the WhiteboxTools executable file contained within the decompressed WhiteboxTools folder that you downloaded previously (see note above). If you are using a Mac or Linux computer, note that this may require you to 1) select a file contained in the folder that is not the executable (QGIS seems to exclude files without extensions, which the WhiteboxTools executable is on MacOS and Linux) then delete the file extension (see below). You will also need to leave the textbox by selecting any other feature on the dialog box before pressing the OK button.
You should now see the Whitebox toolbox within the Processing Toolbox at the right-hand side of the QGIS interface, as in the screenshots above.
ArcGIS Plugin
WhiteboxTools functionality can also be accessed conveniently through the ArcGIS. This WhiteboxTools front-end has been developed and is maintained by Prof. Qiusheng Wu, of Binghamton University (SUNY). This front-end is available from the Gihub repository. The plugin works for ArcGIS 10.6 and ArcGIS Pro; other version of ArcGIS have not been tested for support. Detailed instructions on installing and setting-up the ArcGIS toolbox can be found on the GitHub site.
Command-Line Interface
WhiteboxTools is a command-line program and can be run either by calling it from a terminal application with appropriate commands and arguments, or, more conveniently, by calling it from a script. The following commands are recognized by the WhiteboxTools library:
Command | Description |
---|---|
--cd, --wd | Changes the working directory; used in conjunction with --run flag. |
-h, --help | Prints help information. |
-l, --license | Prints the whitebox-tools license. |
--listtools | Lists all available tools, with tool descriptions. Keywords may also be used, --listtools slope. |
-r, --run | Runs a tool; used in conjunction with --cd flag; -r="LidarInfo". |
--toolbox | Prints the toolbox associated with a tool; --toolbox=Slope. |
--toolhelp | Prints the help associated with a tool; --toolhelp="LidarInfo". |
--toolparameters | Prints the parameters (in json form) for a specific tool; e.g. --toolparameters="FeaturePreservingDenoise". |
-v | Verbose mode. Without this flag, tool outputs will not be printed. |
--viewcode | Opens the source code of a tool in a web browser; --viewcode="LidarInfo". |
--version | Prints 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.
Tools Reference
The WhiteboxTools library currently contains approximately 400 tools, which are organized into themed toolboxes, including:
- Data Tools
- Geomorphometric Analysis
- GIS Analysis
- Hydrological Analysis
- Image Analysis
- LiDAR Analysis
- Mathematical and Statistical Analysis
- Precision Agriculture
- Stream Network Analysis
To retrieve detailed information about a tool's input arguments and example usage, either use the toolhelp
command from the terminal, or the wbt.tool_help('tool_name')
function from the whitebox_tools.py script. The following is a complete listing of available tools, with brief descriptions, tool parameter, and example usage.
The Tool Index located at the end of the user manual contains a complete alphabetical listing of the available tools.
Data Tools
- AddPointCoordinatesToTable
- CleanVector
- ConvertNodataToZero
- ConvertRasterFormat
- CsvPointsToVector
- ExportTableToCsv
- JoinTables
- LinesToPolygons
- MergeTableWithCsv
- MergeVectors
- ModifyNoDataValue
- MultiPartToSinglePart
- NewRasterFromBase
- PolygonsToLines
- PrintGeoTiffTags
- RasterToVectorLines
- RasterToVectorPoints
- RasterToVectorPolygons
- ReinitializeAttributeTable
- RemovePolygonHoles
- SetNodataValue
- SinglePartToMultiPart
- VectorLinesToRaster
- VectorPointsToRaster
- VectorPolygonsToRaster
AddPointCoordinatesToTable
This tool modifies the attribute table of a vector of POINT ShapeType by adding two fields, XCOORD and YCOORD, containing each point's X and Y coordinates respectively.
Parameters:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input vector file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: July 6, 2017
Last Modified: 12/10/2018
CsvPointsToVector
This tool can be used to import a series of points contained within a comma-separated values
(*.csv) file (--input
) into a vector shapefile of a POINT ShapeType. The input file must be an ASCII text
file with a .csv extensions. The tool will automatically detect the field data type; for numeric
fields, it will also determine the appropriate length and precision. The user must specify the
x-coordinate (--xfield
) and y-coordiante (--yfield
) fields. All fields are imported as
attributes in the output (--output
) vector file. The tool assumes that the first line of the file is a header line from which field
names are retreived.
See Also: MergeTableWithCsv, ExportTableToCsv
Parameters:
Flag | Description |
---|---|
-i, --input | Input CSV file (i.e. source of data to be imported) |
-o, --output | Output vector file |
--xfield | X field number (e.g. 0 for first field) |
--yfield | Y field number (e.g. 1 for second field) |
--epsg | EPSG 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
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:
Flag | Description |
---|---|
-i, --input | Input vector file |
-o, --output | Output raster file |
--headers | Export 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
Author: Dr. John Lindsay
Created: 24/04/2018
Last Modified: 18/10/2019
JoinTables
This tool can be used to join (i.e. merge) a vector's attribute table with a second table. The
user must specify the name of the vector file (and associated attribute file) as well as the
primary key within the table. The primary key (--pkey
flag) is the field
within the table that is being appended to that serves as the identifier. Additionally, the user
must specify the name of a second vector from which the data appended into the first table will be
derived. The foreign key (--fkey
flag), the identifying field within the
second table that corresponds with the data contained within the primary key in the table, must be
specified. Both the primary and foreign keys should either be strings (text) or integer values.
Fields containing decimal values are not good candidates for keys. Lastly, the names of the field
within the second file to include in the merge operation can also be input (--import_field
). If the
--import_field
field is not input, all fields in the attribute table of the second file, that are not
the foreign key nor FID, will be imported to the first table.
Merging works for one-to-one and many-to-one database relations. A one-to-one relations exists when each record in the attribute table corresponds to one record in the second table and each primary key is unique. Since each record in the attribute table is associated with a geospatial feature in the vector, an example of a one-to-one relation may be where the second file contains AREA and PERIMETER fields for each polygon feature in the vector. This is the most basic type of relation. A many-to-one relation would exist when each record in the first attribute table corresponds to one record in the second file and the primary key is NOT unique. Consider as an example a vector and attribute table associated with a world map of countries. Each country has one or more more polygon features in the shapefile, e.g. Canada has its mainland and many hundred large islands. You may want to append a table containing data about the population and area of each country. In this case, the COUNTRY columns in the attribute table and the second file serve as the primary and foreign keys respectively. While there may be many duplicate primary keys (all of those Canadian polygons) each will correspond to only one foreign key containing the population and area data. This is a many-to-one relation. The JoinTables tool does not support one-to-many nor many-to-many relations.
See Also: MergeTableWithCsv, ReinitializeAttributeTable, ExportTableToCsv
Parameters:
Flag | Description |
---|---|
--i1, --input1 | Input primary vector file (i.e. the table to be modified) |
--pkey | Primary key field |
--i2, --input2 | Input foreign vector file (i.e. source of data to be imported) |
--fkey | Foreign key field |
--import_field | Imported field (all fields will be imported if not specified) |
Python function:
wbt.join_tables(
input1,
pkey,
input2,
fkey,
import_field,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=JoinTables -v --wd="/path/to/data/" ^
--i1=properties.shp --pkey=TYPE --i2=land_class.shp ^
--fkey=VALUE --import_field=NEW_VALUE
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:
Flag | Description |
---|---|
-i, --input | Input vector line file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input primary vector file (i.e. the table to be modified) |
--pkey | Primary key field |
--csv | Input CSV file (i.e. source of data to be imported) |
--fkey | Foreign key field |
--import_field | Imported 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
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:
Flag | Description |
---|---|
-i, --inputs | Input vector files |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 01/10/2018
Last Modified: 12/10/2018
ModifyNoDataValue
This tool can be used to modify the value of pixels containing the NoData value for an input raster image. This operation differs from the SetNodataValue tool, which sets the NoData value for an image in the image header without actually modifying pixel values. Also, SetNodataValue does not overwrite the input file, while the ModifyNoDataValue tool does.
See Also: SetNodataValue, ConvertNodataToZero
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
--new_value | New 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
Author: Dr. John Lindsay
Created: 08/09/2019
Last Modified: 08/09/2019
MultiPartToSinglePart
This tool can be used to convert a vector file containing multi-part features into a vector
containing only single-part features. Any multi-part polygons or lines within the input
vector file will be split into seperate features in the output file, each possessing their
own entry in the associated attribute file. For polygon-type vectors, the user may optionally
choose to exclude hole-parts from being separated from their containing polygons. That is,
with the --exclude_holes
flag, hole parts in the input vector will continue to belong to
their enclosing polygon in the output vector. The tool will also convert MultiPoint Shapefiles
into single Point vectors.
See Also: SinglePartToMultiPart
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector line or polygon file |
-o, --output | Output vector line or polygon file |
--exclude_holes | Exclude 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
Author: Dr. John Lindsay
Created: 27/09/2018
Last Modified: 16/06/2020
NewRasterFromBase
This tool can be used to create a new raster with the same coordinates and dimensions
(i.e. rows and columns) as an existing base image. The user must specify the name of the
base image (--base
), the value that the new grid will be filled with (--value
flag;
default of NoData), and the data type (--data_type
flag; options include 'double',
'float', and 'integer'). Notice that the functionality of this tool is the same as
multiplying the base image by zero and adding the constant value.
See Also: RasterCellAssignment
Parameters:
Flag | Description |
---|---|
-i, --base | Input base raster file |
-o, --output | Output raster file |
--value | Constant value to fill raster with; either 'nodata' or numeric value |
--data_type | Output raster data type; options include 'double' (64-bit), 'float' (32-bit), and 'integer' (signed 16-bit) (default is 'float') |
Python function:
wbt.new_raster_from_base(
base,
output,
value="nodata",
data_type="float",
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=NewRasterFromBase -v ^
--wd="/path/to/data/" --base=base.tif -o=NewRaster.tif ^
--value=0.0 --data_type=integer
>>./whitebox_tools ^
-r=NewRasterFromBase -v --wd="/path/to/data/" --base=base.tif ^
-o=NewRaster.tif --value=nodata
Author: Dr. John Lindsay
Created: July 11, 2017
Last Modified: 12/10/2018
PolygonsToLines
This tool converts vector polygons into polylines, simply by modifying the Shapefile geometry type.
See Also: LinesToPolygons
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input raster lines file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 26/09/2018
Last Modified: 12/10/2018
SetNodataValue
This tool will re-assign a user-defined background value in an input raster image the NoData value. More precisely, the NoData value will be changed to the specified background value and any existing grid cells containing the previous NoData value, if it had been defined, will be changed to this new value. Most WhiteboxTools tools recognize NoData grid cells and treat them specially. NoData grid cells are also often displayed transparently by GIS software. The user must specify the names of the input and output rasters and the background value. The default background value is zero, although any numeric value is possible.
This tool differs from the ModifyNoDataValue tool in that it simply updates the NoData value in the raster header, without modifying pixel values. The ModifyNoDataValue tool will update the value in the header, and then modify each existing NoData pixel to contain this new value. Also, SetNodataValue does not overwrite the input file, while the ModifyNoDataValue tool does.
See Also: ModifyNoDataValue, ConvertNodataToZero, IsNoData
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--back_value | Background 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
Author: Dr. John Lindsay
Created: 10/09/2017
Last Modified: 24/01/2019
SinglePartToMultiPart
This tool can be used to convert a vector file containing single-part features into a vector
containing multi-part features. The user has the option to either group features based on an
ID Field (--field
flag), which is a categorical field within the vector's attribute table.
The ID Field should either be of String (text) or Integer type. Fields containing decimal values
are not good candidates for the ID Field. If no --field
flag is specified, all features will
be grouped together into one large multi-part vector.
This tool works for vectors containing either point, line, or polygon features. Since vectors of a POINT ShapeType cannot represent multi-part features, the ShapeType of the output file will be modified to a MULTIPOINT ShapeType if the input file is of a POINT ShapeType. If the input vector is of a POLYGON ShapeType, the user can optionally set the algorithm to search for polygons that should be represented as hole parts. In the case of grouping based on an ID Field, hole parts are polygon features contained within larger polygons of the same ID Field value. Please note that searching for polygon holes may significantly increase processing time for larger polygon coverages.
See Also: MultiPartToSinglePart
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector line or polygon file |
--field | Grouping ID field name in attribute table |
-o, --output | Output 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'
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:
Flag | Description |
---|---|
-i, --input | Input vector lines file |
--field | Input field name in attribute table |
-o, --output | Output raster file |
--nodata | Background value to set to NoData. Without this flag, it will be set to 0.0 |
--cell_size | Optionally specified cell size of output raster. Not used when base raster is specified |
--base | Optionally 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
Author: Dr. John Lindsay
Created: 18/04/2018
Last Modified: 22/10/2019
VectorPointsToRaster
This tool can be used to convert a vector points file into a raster grid. The user must
specify the name of the input vector and the output raster file. The field name (--field
)
is the field from the attributes table from which the tool will retrieve the information to
assign to grid cells in the output raster. The field must contain numerical data. If the user does not
supply a field name parameter, each feature in the raster will be assigned the record number
of the feature. The assignment operation determines how the situation of multiple points
contained within the same grid cell is handled. The background value is zero by default
but can be set to NoData
optionally using the --nodata
value.
If the user optionally specifies the grid cell size parameter (--cell_size
) then the coordinates
will be determined by the input vector (i.e. the bounding box) and the specified cell size. This
will also determine the number of rows and columns in the output raster. If the user instead
specifies the optional base raster file parameter (--base
), the output raster's coordinates (i.e.
north, south, east, west) and row and column count will be the same as the base file.
In the case that multiple points are contained within a single grid cell, the output can be
assigned (--assign
) the first, last (default), min, max, or sum of the contained points.
See Also: VectorPolygonsToRaster, VectorLinesToRaster
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector Points file |
--field | Input field name in attribute table |
-o, --output | Output raster file |
--assign | Assignment operation, where multiple points are in the same grid cell; options include 'first', 'last' (default), 'min', 'max', 'sum' |
--nodata | Background value to set to NoData. Without this flag, it will be set to 0.0 |
--cell_size | Optionally specified cell size of output raster. Not used when base raster is specified |
--base | Optionally 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
Author: Dr. John Lindsay
Created: 19/04/2018
Last Modified: 18/10/2019
VectorPolygonsToRaster
Converts a vector containing polygons into a raster.
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygons file |
--field | Input field name in attribute table |
-o, --output | Output raster file |
--nodata | Background value to set to NoData. Without this flag, it will be set to 0.0 |
--cell_size | Optionally specified cell size of output raster. Not used when base raster is specified |
--base | Optionally 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
Author: Dr. John Lindsay
Created: 17/04/2018
Last Modified: 18/10/2019
Geomorphometric Analysis
- Aspect
- AssessRoute
- AverageNormalVectorAngularDeviation
- CircularVarianceOfAspect
- ContoursFromPoints
- ContoursFromRaster
- DevFromMeanElev
- DiffFromMeanElev
- DirectionalRelief
- DownslopeIndex
- EdgeDensity
- ElevAbovePit
- ElevPercentile
- ElevRelativeToMinMax
- ElevRelativeToWatershedMinMax
- EmbankmentMapping
- FeaturePreservingSmoothing
- FetchAnalysis
- FillMissingData
- FindRidges
- Hillshade
- HorizonAngle
- HypsometricAnalysis
- HypsometricallyTintedHillshade
- MapOffTerrainObjects
- MaxAnisotropyDev
- MaxAnisotropyDevSignature
- MaxBranchLength
- MaxDifferenceFromMean
- MaxDownslopeElevChange
- MaxElevDevSignature
- MaxElevationDeviation
- MinDownslopeElevChange
- MultidirectionalHillshade
- MultiscaleElevationPercentile
- MultiscaleRoughness
- MultiscaleRoughnessSignature
- MultiscaleStdDevNormals
- MultiscaleStdDevNormalsSignature
- MultiscaleTopographicPositionImage
- NumDownslopeNeighbours
- NumUpslopeNeighbours
- Openness
- PennockLandformClass
- PercentElevRange
- PlanCurvature
- Profile
- ProfileCurvature
- RelativeAspect
- RelativeTopographicPosition
- RemoveOffTerrainObjects
- RuggednessIndex
- SedimentTransportIndex
- ShadowAnimation
- Slope
- SlopeVsElevationPlot
- SmoothVegetationResidual
- SphericalStdDevOfNormals
- StandardDeviationOfSlope
- StreamPowerIndex
- SurfaceAreaRatio
- TangentialCurvature
- TimeInDaylight
- TopographicPositionAnimation
- TotalCurvature
- Viewshed
- VisibilityIndex
- WetnessIndex
Aspect
This tool calculates slope aspect (i.e. slope orientation in degrees clockwise from north) for each grid cell
in an input digital elevation model (DEM). The user must specify the name of the input
DEM (--dem
) and the output raster image. The Z conversion factor is only important
when the vertical and horizontal units are not the same in the DEM. When this is the case,
the algorithm will multiply each elevation in the DEM by the Z conversion factor. If the
DEM is in the geographic coordinate system (latitude and longitude), the following equation
is used:
zfactor = 1.0 / (111320.0 x cos(mid_lat))
where mid_lat
is the latitude of the centre of the raster, in radians.
The tool uses Horn's (1981) 3rd-order finite difference method to estimate slope. Given the following clock-type grid cell numbering scheme (Gallant and Wilson, 2000),
| 7 | 8 | 1 |
| 6 | 9 | 2 |
| 5 | 4 | 3 |
aspect = 180 - arctan(fy / fx) + 90(fx / |fx|)
where,
fx = (z3 - z5 + 2(z2 - z6) + z1 - z7) / 8 * Δx
and,
fy = (z7 - z5 + 2(z8 - z4) + z1 - z3) / 8 * Δy
Δx and Δy are the grid resolutions in the x and y direction respectively
Reference:
Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, in Terrain Analysis: Principles and Applications, edited by J. P. Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.
See Also: Slope, PlanCurvature, ProfileCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.aspect(
dem,
output,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Aspect -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 01/03/2021
AssessRoute
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool assesses the variability in slope, elevation, and visibility along a line vector, which may
be a footpath, road, river or any other route. The user must specify the name of the input line vector
(--routes
), the input raster digital elevation model file (--dem
), and the output line vector
(--output
). The algorithm initially splits the input line vector in equal-length segments (--length
).
For each line segment, the tool then calculates the average slope (AVG_SLOPE), minimum and maximum
elevations (MIN_ELEV, MAX_ELEV), the elevation range or relief (RELIEF), the path sinuosity
(SINUOSITY), the number of changes in slope direction or breaks-in-slope (CHG_IN_SLP), and the
maximum visibility (VISIBILITY). Each of these metrics are output to the attribute table of the output
vector, along with the feature identifier (FID); any attributes associated with the input parent
feature will also be copied into the output table. Slope and elevation metrics are measured along the
2D path based on the elevations of each of the row and column intersection points of the raster with
the path, estimated from linear-interpolation using the two neighbouring elevations on either side of
the path. Sinuosity is calculated as the ratio of the along-surface (i.e. 3D) path length, divided by
the 3D distance between the start and end points of the segment. CHG_IN_SLP can be thought of as a crude
measure of path roughness, although this will be very sensitive to the quality of the DEM. The visibility
metric is based on the Yokoyama et al. (2002) Openness index, which calculates the average horizon
angle in the eight cardal directions to a maximum search distance (--dist
), measured in grid cells.
Note that the input DEM must be in a projected coordinate system. The DEM and the input routes vector must be also share the same coordinate system. This tool also works best when the input DEM is of high quality and fine spatial resolution, such as those derived from LiDAR data sets.
Maximum segment visibility:
Average segment slope:
See Also: SplitVectorLines, Openness
Parameters:
Flag | Description |
---|---|
--routes | Name of the input routes vector file |
--dem | Name of the input DEM raster file |
-o, --output | Name of the output lines shapefile |
--length | Maximum segment length (m) |
--dist | Search distance, in grid cells, used in visibility analysis |
Python function:
wbt.assess_route(
routes,
dem,
output,
length="",
dist=20,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=AssessRoute --routes=footpath.shp ^
--dem=DEM.tif -o=assessedRoutes.shp --length=50.0 --dist=200
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 16/05/2021
Last Modified: 16/05/2021
AverageNormalVectorAngularDeviation
This tool characterizes the spatial distribution of the average normal vector angular deviation, a measure of
surface roughness. Working in the field of 3D printing, Ko et al. (2016) defined a measure of surface roughness
based on quantifying the angular deviations in the direction of the normal vector of a real surface from its ideal
(i.e. smoothed) form. This measure of surface complexity is therefore in units of degrees. Specifically, roughness
is defined in this study as the neighborhood-averaged difference in the normal vectors of the original DEM and a
smoothed DEM surface. Smoothed surfaces are derived by applying a Gaussian blur of the same size as the
neighborhood (--filter
).
The MultiscaleRoughness tool calculates the same measure of surface roughness, except that it is designed to work with multiple spatial scales.
Reference:
Ko, M., Kang, H., ulrim Kim, J., Lee, Y., & Hwang, J. E. (2016, July). How to measure quality of affordable 3D printing: Cultivating quantitative index in the user community. In International Conference on Human-Computer Interaction (pp. 116-121). Springer, Cham.
Lindsay, J. B., & Newman, D. R. (2018). Hyper-scale analysis of surface roughness. PeerJ Preprints, 6, e27110v1.
See Also: MultiscaleRoughness, SphericalStdDevOfNormals, CircularVarianceOfAspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--output | Output raster file |
--filter | Size of the filter kernel |
Python function:
wbt.average_normal_vector_angular_deviation(
dem,
output,
filter=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=AverageNormalVectorAngularDeviation -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: 26/01/2019
Last Modified: 03/09/2020
CircularVarianceOfAspect
This tool can be used to calculate the circular variance (i.e. one minus the mean resultant length) of aspect
for an input digital elevation model (DEM). This is a measure of how variable slope aspect is within a local
neighbourhood of a specified size (--filter
). CircularVarianceOfAspect is therefore a measure of surface
shape complexity, or texture. It will take a value of 0.0 for smooth sites and near 1.0 in areas of high surface
roughness or complex topography.
The local neighbourhood size (--filter
) must be any odd integer equal to or greater than three. Grohmann et al. (2010) found that
vector dispersion, a related measure of angular variance, increases monotonically with scale. This is the result
of the angular dispersion measure integrating (accumulating) all of the surface variance of smaller scales up to the
test scale. A more interesting scale relation can therefore be estimated by isolating the amount of surface complexity
associated with specific scale ranges. That is, at large spatial scales, the metric should reflect
the texture of large-scale landforms rather than the accumulated complexity at all smaller scales, including
microtopographic roughness. As such, this tool normalizes the surface complexity of scales that are smaller than
the filter size by applying Gaussian blur (with a standard deviation of one-third the filter size) to the DEM prior
to calculating CircularVarianceOfAspect. In this way, the resulting distribution is able to isolate and highlight
the surface shape complexity associated with landscape features of a similar scale to that of the filter size.
This tool makes extensive use of integral images (i.e. summed-area tables) and parallel processing to ensure computational efficiency. It may, however, require substantial memory resources when applied to larger DEMs.
References:
Grohmann, C. H., Smith, M. J., & Riccomini, C. (2010). Multiscale analysis of topographic surface roughness in the Midland Valley, Scotland. IEEE Transactions on Geoscience and Remote Sensing, 49(4), 1200-1213.
See Also: Aspect, SphericalStdDevOfNormals, MultiscaleRoughness, EdgeDensity, SurfaceAreaRatio, RuggednessIndex
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--output | Output raster file |
--filter | Size of the filter kernel |
Python function:
wbt.circular_variance_of_aspect(
dem,
output,
filter=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=CircularVarianceOfAspect -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: 26/01/2019
Last Modified: 03/09/2020
ContoursFromPoints
This tool creates a contour coverage from a set of input points (--input
). The user must specify the contour
interval (--interval
) and optionally, the base contour value (--base
). The degree to which contours are
smoothed is controlled by the Smoothing Filter Size parameter (--smooth
). This value, which determines
the size of a mean filter applied to the x-y position of vertices in each contour, should be an odd integer value, e.g.
3, 5, 7, 9, 11, etc. Larger values will result in smoother contour lines.
See Also: ContoursFromRaster
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector points file |
--field | Input field name in attribute table |
--use_z | Use the 'z' dimension of the Shapefile's geometry instead of an attribute field? |
-o, --output | Output vector lines file |
--max_triangle_edge_length | Optional maximum triangle edge length; triangles larger than this size will not be gridded |
--interval | Contour interval |
--base | Base contour height |
--smooth | Smoothing filter size (in num. points), e.g. 3, 5, 7, 9, 11 |
Python function:
wbt.contours_from_points(
i,
output,
field=None,
use_z=False,
max_triangle_edge_length=None,
interval=10.0,
base=0.0,
smooth=5,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ContoursFromPoints -v ^
--wd="/path/to/data/" -i=points.shp --field=HEIGHT ^
-o=contours.shp --max_triangle_edge_length=100.0 ^
--interval=100.0 --base=0.0 --smooth=11
Author: Dr. John Lindsay
Created: 26/04/2020
Last Modified: 26/04/2020
ContoursFromRaster
This tool can be used to create a vector contour coverage from an input raster surface model (--input
), such as a digital
elevation model (DEM). The user must specify the contour interval (--interval
) and optionally, the base contour value (--base
).
The degree to which contours are smoothed is controlled by the Smoothing Filter Size parameter (--smooth
). This value, which
determines the size of a mean filter applied to the x-y position of vertices in each contour, should be an odd integer value, e.g.
3, 5, 7, 9, 11, etc. Larger values will result in smoother contour lines. The tolerance parameter (--tolerance
) controls the
amount of line generalization. That is, vertices in a contour line will be selectively removed from the line if they do not result in
an angular deflection in the line's path of at least this threshold value. Increasing this value can significantly decrease the size
of the output contour vector file, at the cost of generating straighter contour line segments.
See Also: RasterToVectorPolygons
Parameters:
Flag | Description |
---|---|
-i, --input | Input surface raster file |
-o, --output | Output vector contour file |
--interval | Contour interval |
--base | Base contour height |
--smooth | Smoothing filter size (in num. points), e.g. 3, 5, 7, 9, 11 |
--tolerance | Tolerance factor, in degrees (0-45); determines generalization level |
Python function:
wbt.contours_from_raster(
i,
output,
interval=10.0,
base=0.0,
smooth=9,
tolerance=10.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ContoursFromRaster -v ^
--wd="/path/to/data/" --input=DEM.tif -o=contours.shp ^
--interval=100.0 --base=0.0 --smooth=11 --tolerance=20.0
Author: Dr. John Lindsay
Created: 22/02/2020
Last Modified: 04/03/2020
DevFromMeanElev
This tool can be used to calculate the difference between the elevation of each grid cell and the mean elevation of the centering local neighbourhood, normalized by standard deviation. Therefore, this index of topographic residual is essentially equivalent to a local z-score. This attribute measures the relative topographic position as a fraction of local relief, and so is normalized to the local surface roughness. DevFromMeanElev utilizes an integral image approach (Crow, 1984) to ensure highly efficient filtering that is invariant with filter size.
The user must specify the name (--dem
) of the input digital elevation model (DEM), the
name of the output file (--output
), and the size of the neighbourhood in the x and y
directions (--filterx
and --filtery
), measured in grid size.
While DevFromMeanElev calculates the deviation from mean elevation (DEV) at a single, user-defined scale, the MaxElevationDeviation tool can be used to output the per-pixel maximum DEV value across a range of input scales.
See Also: DiffFromMeanElev, MaxElevationDeviation
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.dev_from_mean_elev(
dem,
output,
filterx=11,
filtery=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=DevFromMeanElev -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--filter=25
Author: Dr. John Lindsay
Created: 21/06/2017
Last Modified: 30/01/2020
DiffFromMeanElev
This tool can be used to calculate the difference between the elevation of each grid cell and the mean elevation of the centering local neighbourhood. This is similar to what a high-pass filter calculates for imagery data, but is intended to work with DEM data instead. This attribute measures the relative topographic position. DiffFromMeanElev utilizes an integral image approach (Crow, 1984) to ensure highly efficient filtering that is invariant with filter size.
The user must specify the name (--dem
) of the input digital elevation model (DEM), the
name of the output file (--output
), and the size of the neighbourhood in the x and y
directions (--filterx
and --filtery
), measured in grid size.
While DevFromMeanElev calculates the DIFF at a single, user-defined scale, the MaxDifferenceFromMean tool can be used to output the per-pixel maximum DIFF value across a range of input scales.
See Also: DevFromMeanElev, MaxDifferenceFromMean
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.diff_from_mean_elev(
dem,
output,
filterx=11,
filtery=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=DiffFromMeanElev -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--filter=25
Author: Dr. John Lindsay
Created: 25/06/2017
Last Modified: 30/01/2020
DirectionalRelief
This tool calculates the relief for each grid cell in a digital elevation model (DEM) in a specified direction.
Directional relief is an index of the degree to which a DEM grid cell is higher or lower than its surroundings.
It is calculated by subtracting the elevation of a DEM grid cell from the average elevation of those cells which
lie between it and the edge of the DEM in a specified compass direction. Thus, positive values indicate that a
grid cell is lower than the average elevation of the grid cells in a specific direction (i.e. relatively sheltered),
whereas a negative directional relief indicates that the grid cell is higher (i.e. relatively exposed). The
algorithm is based on a modification of the procedure described by Lapen and Martz (1993). The modifications
include: (1) the ability to specify any direction between 0-degrees and 360-degrees (--azimuth
), and (2) the ability to use
a distance-limited search (--max_dist
), such that the ray-tracing procedure terminates before the DEM edge is
reached for longer search paths. The algorithm works by tracing a ray from each grid cell in the direction of
interest and evaluating the average elevation along the ray. Linear interpolation is used to estimate the elevation
of the surface where a ray does not intersect the DEM grid precisely at one of its nodes. The user must specify the
name of an input DEM raster file, the output raster name, and a hypothetical wind direction. Furthermore, the user
is able to constrain the maximum search distance for the ray tracing. If no maximum search distance is specified,
each ray will be traced to the edge of the DEM. The units of the output image are the same as the input DEM.
Ray-tracing is a highly computationally intensive task and therefore this tool may take considerable time to operate for larger sized DEMs. This tool is parallelized to aid with computational efficiency. NoData valued grid cells in the input image will be assigned NoData values in the output image. The output raster is of the float data type and continuous data scale. Directional relief is best displayed using the blue-white-red bipolar palette to distinguish between the positive and negative values that are present in the output.
Reference:
Lapen, D. R., & Martz, L. W. (1993). The measurement of two simple topographic indices of wind sheltering-exposure from raster digital elevation models. Computers & Geosciences, 19(6), 769-779.
See Also: FetchAnalysis, HorizonAngle, RelativeAspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--azimuth | Wind azimuth in degrees |
--max_dist | Optional maximum search distance (unspecified if none; in xy units) |
Python function:
wbt.directional_relief(
dem,
output,
azimuth=0.0,
max_dist=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=DirectionalRelief -v ^
--wd="/path/to/data/" -i='input.tif' -o=output.tif ^
--azimuth=315.0
Author: Dr. John Lindsay
Created: 07/07/2017
Last Modified: 03/09/2020
DownslopeIndex
This tool can be used to calculate the downslope index described by Hjerdt et al. (2004). The downslope index is a measure of the slope gradient between a grid cell and some downslope location (along the flowpath passing through the upslope grid cell) that represents a specified vertical drop (i.e. a potential head drop). The index has been shown to be useful for hydrological, geomorphological, and biogeochemical applications.
The user must specify the name of a digital elevaton model (DEM) raster. This DEM
should be have been pre-processed to remove artifact topographic depressions and flat
areas. The user must also specify the head potential drop (d), and the output type. The
output type can be either 'tangent
', 'degrees
', 'radians
', or 'distance
'. If
'distance
' is selected as the output type, the output grid actually represents the
downslope flowpath length required to drop d meters from each grid cell. Linear
interpolation is used when the specified drop value is encountered between two adjacent
grid cells along a flowpath traverse.
Notice that this algorithm is affected by edge contamination. That is, for some grid cells, the edge of the grid will be encountered along a flowpath traverse before the specified vertical drop occurs. In these cases, the value of the downslope index is approximated by replacing d with the actual elevation drop observed along the flowpath. To avoid this problem, the entire watershed containing an area of interest should be contained in the DEM.
Grid cells containing NoData values in any of the input images are assigned the NoData value in the output raster. The output raster is of the float data type and continuous data scale.
Reference:
Hjerdt, K.N., McDonnell, J.J., Seibert, J. Rodhe, A. (2004) A new topographic index to quantify downslope controls on local drainage, Water Resources Research, 40, W05602, doi:10.1029/2004WR003130.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--drop | Vertical drop value (default is 2.0) |
--out_type | Output type, options include 'tangent', 'degrees', 'radians', 'distance' (default is 'tangent') |
Python function:
wbt.downslope_index(
dem,
output,
drop=2.0,
out_type="tangent",
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=DownslopeIndex -v --wd="/path/to/data/" ^
--dem=pointer.tif -o=dsi.tif --drop=5.0 --out_type=distance
Author: Dr. John Lindsay
Created: July 17, 2017
Last Modified: 12/10/2018
EdgeDensity
This tool calculates the density of edges, or breaks-in-slope within an input digital elevation model (DEM).
A break-in-slope occurs between two neighbouring grid cells if the angular difference between their normal
vectors is greater than a user-specified threshold value (--norm_diff
). EdgeDensity calculates the proportion
of edge cells within the neighbouring window, of square filter dimension --filter
, surrounding each grid cell.
Therefore, EdgeDensity
is a measure of how complex the topographic surface is within a local neighbourhood.
It is therefore a measure of topographic texture. It will take a value near 0.0 for smooth sites and 1.0 in areas
of high surface roughness or complex topography.
The distribution of EdgeDensity is highly dependent upon the value of the norm_diff
used in the calculation. This
threshold may require experimentation to find an appropriate value and is likely dependent upon the topography and
source data. Nonetheless, experience has shown that EdgeDensity provides one of the best measures of surface
texture of any of the available roughness tools.
See Also: CircularVarianceOfAspect, MultiscaleRoughness, SurfaceAreaRatio, RuggednessIndex
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filter | Size of the filter kernel |
--norm_diff | Maximum difference in normal vectors, in degrees |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.edge_density(
dem,
output,
filter=11,
norm_diff=5.0,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=EdgeDensity -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --filter=15 --norm_diff=20.0 ^
--num_iter=4
Author: Dr. John Lindsay
Created: 27/01/2019
Last Modified: 03/09/2020
ElevAbovePit
This tool will calculate the elevation of each grid cell in a digital elevation model (DEM) above the nearest downslope pit cell or grid edge cell, depending on which is encountered first during the flow-path traverse. The resulting image is therefore a measure of relative landscape position. The user must specify the names of a D8 flow pointer grid, a DEM file, and the output file. The flow pointer grid must be derived using the D8 flow algorithm.
See Also: ElevationAboveStream
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.elev_above_pit(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ElevAbovePit -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 13/07/2017
Last Modified: 12/10/2018
ElevPercentile
Elevation percentile (EP) is a measure of local topographic position (LTP). It expresses the vertical position for a digital elevation model (DEM) grid cell (z0) as the percentile of the elevation distribution within the filter window, such that:
EP = counti∈C(zi > z0) x (100 / nC)
where z0 is the elevation of the window's center grid cell, zi is the elevation of cell i contained within the neighboring set C, and nC is the number of grid cells contained within the window.
EP is unsigned and expressed as a percentage, bound between 0% and 100%. Quantile-based estimates (e.g., the median and interquartile range) are often used in nonparametric statistics to provide data variability estimates without assuming the distribution is normal. Thus, EP is largely unaffected by irregularly shaped elevation frequency distributions or by outliers in the DEM, resulting in a highly robust metric of LTP. In fact, elevation distributions within small to medium sized neighborhoods often exhibit skewed, multimodal, and non-Gaussian distributions, where the occurrence of elevation errors can often result in distribution outliers. Thus, based on these statistical characteristics, EP is considered one of the most robust representation of LTP.
The algorithm implemented by this tool uses the relatively efficient running-histogram filtering algorithm of Huang
et al. (1979). Because most DEMs contain floating point data, elevation values must be rounded to be binned. The
--sig_digits
parameter is used to determine the level of precision preserved during this binning process. The
algorithm is parallelized to further aid with computational efficiency.
Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx
and --filtery
flags.
These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).
References:
Newman, D. R., Lindsay, J. B., and Cockburn, J. M. H. (2018). Evaluating metrics of local topographic position for multiscale geomorphometric analysis. Geomorphology, 312, 40-50.
Huang, T., Yang, G.J.T.G.Y. and Tang, G., 1979. A fast two-dimensional median filtering algorithm. IEEE Transactions on Acoustics, Speech, and Signal Processing, 27(1), pp.13-18.
See Also: DevFromMeanElev, DiffFromMeanElev
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
--sig_digits | Number of significant digits |
Python function:
wbt.elev_percentile(
dem,
output,
filterx=11,
filtery=11,
sig_digits=2,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ElevPercentile -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --filter=25
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 02/04/2019
ElevRelativeToMinMax
This tool can be used to express the elevation of a grid cell in a digital elevation model (DEM) as a percentage of the relief between the DEM minimum and maximum values. As such, it provides a basic measure of relative topographic position.
See Also: ElevRelativeToWatershedMinMax, ElevationAboveStream, ElevAbovePit
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.elev_relative_to_min_max(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ElevRelativeToMinMax -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 12/07/2017
Last Modified: 12/10/2018
ElevRelativeToWatershedMinMax
This tool can be used to express the elevation of a grid cell in a digital elevation model (DEM) as a percentage
of the relief between the watershed minimum and maximum values. As such, it provides a basic
measure of relative topographic position. The user must specify the names of DEM (--dem
) and watersheds (--watersheds
)
raster files.
See Also: ElevRelativeToMinMax, ElevationAboveStream, ElevAbovePit
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--watersheds | Input raster watersheds file |
-o, --output | Output raster file |
Python function:
wbt.elev_relative_to_watershed_min_max(
dem,
watersheds,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ElevRelativeToWatershedMinMax -v ^
--wd="/path/to/data/" --dem=DEM.tif --watersheds=watershed.tif ^
-o=output.tif
Author: Dr. John Lindsay
Created: 12/07/2017
Last Modified: 12/10/2018
EmbankmentMapping
This tool can be used to map and/or remove road embankments from an input fine-resolution digital elevation
model (--dem
). Fine-resolution LiDAR DEMs can represent surface features such as road and railway
embankments with high fidelity. However, transportation embankments are problematic for several
environmental modelling applications, including soil an vegetation distribution mapping, where the pre-embankment
topography is the contolling factor. The algorithm utilizes repositioned (--search_dist
) transportation
network cells, derived from rasterizing a transportation vector (--road_vec
), as seed points in a
region-growing operation. The embankment region grows based on derived morphometric parameters, including
road surface width (--min_road_width
), embankment width (--typical_width
and --max_width
), embankment
height (--max_height
), and absolute slope (--spillout_slope
). The tool can be run in two modes. By default
the tool will simply map embankment cells, with a Boolean output raster. If, however, the --remove_embankments
flag is specified, the tool will instead output a DEM for which the mapped embankment grid cells have been
excluded and new surfaces have been interpolated based on the surrounding elevation values (see below).
Hillshade from original DEM:
Hillshade from embankment-removed DEM:
References:
Van Nieuwenhuizen, N, Lindsay, JB, DeVries, B. 2021. Automated mapping of transportation embankments in fine-resolution LiDAR DEMs. Remote Sensing. 13(7), 1308; https://doi.org/10.3390/rs13071308
See Also: RemoveOffTerrainObjects, SmoothVegetationResidual
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--road_vec | Input vector polygons file |
-o, --output | Output raster file |
--search_dist | Search distance used to reposition transportation vectors onto road embankments (in map units) |
--min_road_width | Minimum road width; this is the width of the paved road surface (in map units) |
--typical_width | Typical embankment width; this is the maximum width of an embankment with roadside ditches (in map units) |
--max_height | Typical embankment maximum height; this is the height a typical embankment with roadside ditches (in map units) |
--max_width | Maximum embankment width, typically where embankments traverse steep-sided valleys (in map units) |
--max_increment | Maximum upwards increment between neighbouring cells on an embankment (in elevation units) |
--spillout_slope | Spillout slope (in degrees) |
--remove_embankments | Optional flag indicating whether to output a DEM with embankments removed (true) or an embankment raster map (false) |
Python function:
wbt.embankment_mapping(
dem,
road_vec,
output,
search_dist=2.5,
min_road_width=6.0,
typical_width=30.0,
max_height=2.0,
max_width=60.0,
max_increment=0.05,
spillout_slope=4.0,
remove_embankments=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=EmbankmentMapping -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif ^
--search_dist=1.0 --min_road_width=6.0 --typical_width=30.0 ^
--max_height=2.0 --max_width=60.0 --max_increment=0.05 ^
--spillout_slope=4.0 --remove_embankments=true
Author: Dr. John Lindsay and Nigel Van Nieuwenhuizen
Created: 21/09/2020
Last Modified: 05/10/2020
FeaturePreservingSmoothing
This tool implements a highly modified form of the DEM de-noising algorithm described by Sun et al. (2007). It is very effective at removing surface roughness from digital elevation models (DEMs), without significantly altering breaks-in-slope. As such, this tool should be used for smoothing DEMs rather than either smoothing with low-pass filters (e.g. mean, median, Gaussian filters) or grid size coarsening by resampling. The algorithm works by 1) calculating the surface normal 3D vector of each grid cell in the DEM, 2) smoothing the normal vector field using a filtering scheme that applies more weight to neighbours with lower angular difference in surface normal vectors, and 3) uses the smoothed normal vector field to update the elevations in the input DEM.
Sun et al.'s (2007) original method was intended to work on input point clouds and fitted triangular irregular networks (TINs). The algorithm has been modified to work with input raster DEMs instead. In so doing, this algorithm calculates surface normal vectors from the planes fitted to 3 x 3 neighbourhoods surrounding each grid cell, rather than the triangular facet. The normal vector field smoothing and elevation updating procedures are also based on raster filtering operations. These modifications make this tool more efficient than Sun's original method, but will also result in a slightly different output than what would be achieved with Sun's method.
The user must specify the values of three key parameters, including the filter size
(--filter
), the normal difference threshold (--norm_diff
), and the number of
iterations (--num_iter
). Lindsay et al. (2019) found that the degree of smoothing
was less impacted by the filter size than it was either the normal difference threshold
and the number of iterations. A filter size of 11, the default value, tends to work
well in many cases. To increase the level of smoothing applied to the DEM, consider
increasing the normal difference threshold, i.e. the angular difference in normal vectors
between the center cell of a filter window and a neighbouring cell. This parameter determines
which neighbouring values are included in a filtering operation and higher values will
result in a greater number of neighbouring cells included, and therefore smooother surfaces.
Similarly, increasing the number of iterations from the default value of 3 to upwards of
5-10 will result in significantly greater smoothing.
Before smoothing treatment:
After smoothing treatment with FPS:
Reference:
Lindsay JB, Francioni A, Cockburn JMH. 2019. LiDAR DEM smoothing and the preservation of drainage features. Remote Sensing, 11(16), 1926; DOI: 10.3390/rs11161926.
Sun, X., Rosin, P., Martin, R., & Langbein, F. (2007). Fast and effective feature-preserving mesh denoising. IEEE Transactions on Visualization & Computer Graphics, (5), 925-938.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filter | Size of the filter kernel |
--norm_diff | Maximum difference in normal vectors, in degrees |
--num_iter | Number of iterations |
--max_diff | Maximum allowable absolute elevation change (optional) |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.feature_preserving_smoothing(
dem,
output,
filter=11,
norm_diff=15.0,
num_iter=3,
max_diff=0.5,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=FeaturePreservingSmoothing -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif --filter=15 ^
--norm_diff=20.0 --num_iter=4
Author: Dr. John Lindsay
Created: 23/11/2017
Last Modified: 03/09/2020
FetchAnalysis
This tool creates a new raster in which each grid cell is assigned the distance, in meters, to the nearest topographic obstacle in a specified direction. It is a modification of the algorithm described by Lapen and Martz (1993). Unlike the original algorithm, Fetch Analysis is capable of analyzing fetch in any direction from 0-360 degrees. The user must specify the name of an input digital elevation model (DEM) raster file, the output raster name, a hypothetical wind direction, and a value for the height increment parameter. The algorithm searches each grid cell in a path following the specified wind direction until the following condition is met:
Ztest >= Zcore + DI
where Zcore is the elevation of the grid cell at which fetch is being determined, Ztest is the elevation of the grid cell being tested as a topographic obstacle, D is the distance between the two grid cells in meters, and I is the height increment in m/m. Lapen and Martz (1993) suggest values for I in the range of 0.025 m/m to 0.1 m/m based on their study of snow re-distribution in low-relief agricultural landscapes of the Canadian Prairies. If the directional search does not identify an obstacle grid cell before the edge of the DEM is reached, the distance between the DEM edge and Zcore is entered. Edge distances are assigned negative values to differentiate between these artificially truncated fetch values and those for which a valid topographic obstacle was identified. Notice that linear interpolation is used to estimate the elevation of the surface where a ray (i.e. the search path) does not intersect the DEM grid precisely at one of its nodes.
Ray-tracing is a highly computationally intensive task and therefore this tool may take considerable time to operate for larger sized DEMs. This tool is parallelized to aid with computational efficiency. NoData valued grid cells in the input image will be assigned NoData values in the output image. Fetch Analysis images are best displayed using the blue-white-red bipolar palette to distinguish between the positive and negative values that are present in the output.
Reference:
Lapen, D. R., & Martz, L. W. (1993). The measurement of two simple topographic indices of wind sheltering-exposure from raster digital elevation models. Computers & Geosciences, 19(6), 769-779.
See Also: DirectionalRelief, HorizonAngle, RelativeAspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--azimuth | Wind azimuth in degrees in degrees |
--hgt_inc | Height increment value |
Python function:
wbt.fetch_analysis(
dem,
output,
azimuth=0.0,
hgt_inc=0.05,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=FetchAnalysis -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif --azimuth=315.0
Author: Dr. John Lindsay
Created: 07/07/2017
Last Modified: 03/09/2020
FillMissingData
This tool can be used to fill in small gaps in a raster or digital elevation model (DEM). The gaps, or holes, must have recognized NoData values. If gaps do not currently have this characteristic, use the SetNodataValue tool and ensure that the data are stored using a raster format that supports NoData values. All valid, non-NoData values in the input raster will be assigned the same value in the output image.
The algorithm uses an inverse-distance weighted (IDW) scheme based on the valid values on the edge of
NoData gaps to estimate gap values. The user must specify the filter size (--filter
), which determines
the size of gap that is filled, and the IDW weight (--weight
).
The filter size, specified in grid cells, is used to determine how far the algorithm will search for valid, non-NoData values. Therefore, setting a larger filter size allows for the filling of larger gaps in the input raster.
The --no_edges
flag can be used to exclude NoData values that are connected to the edges of the raster. It is
usually the case that irregularly shaped DEMs have large regions of NoData values along the containing raster
edges. This flag can be used to exclude these regions from the gap-filling operation, leaving only interior gaps
for filling.
See Also: SetNodataValue
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filter | Filter size (cells) |
--weight | IDW weight value |
--no_edges | Optional flag indicating whether to exclude NoData cells in edge regions |
Python function:
wbt.fill_missing_data(
i,
output,
filter=11,
weight=2.0,
no_edges=True,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=FillMissingData -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif --filter=25 ^
--weight=1.0 --no_edges
Author: Dr. John Lindsay
Created: 14/06/2017
Last Modified: 12/10/2018
FindRidges
This tool can be used to identify ridge cells in a digital elevation model (DEM). Ridge cells are those that
have lower neighbours either to the north and south or the east and west. Line thinning can optionally be used
to create single-cell wide ridge networks by specifying the --line_thin
parameter.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--line_thin | Optional flag indicating whether post-processing line-thinning should be performed |
Python function:
wbt.find_ridges(
dem,
output,
line_thin=True,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=FindRidges -v --wd="/path/to/data/" ^
--dem=pointer.tif -o=out.tif --line_thin
Author: Dr. John Lindsay
Created: 04/12/2017
Last Modified: 18/10/2019
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--azimuth | Illumination source azimuth in degrees |
--altitude | Illumination source altitude in degrees |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.hillshade(
dem,
output,
azimuth=315.0,
altitude=30.0,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Hillshade -v --wd="/path/to/data/" ^
-i=DEM.tif -o=output.tif --azimuth=315.0 --altitude=30.0
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 03/09/2020
HorizonAngle
This tool calculates the horizon angle (Sx), i.e. the maximum slope along a specified azimuth (0-360 degrees) for each grid cell in an input digital elevation model (DEM). Horizon angle is sometime referred to as the maximum upwind slope in wind exposure/sheltering studies. Positive values can be considered sheltered with respect to the azimuth and negative values are exposed. Thus, Sx is a measure of exposure to a wind from a specific direction. The algorithm works by tracing a ray from each grid cell in the direction of interest and evaluating the slope for each location in which the DEM grid is intersected by the ray. Linear interpolation is used to estimate the elevation of the surface where a ray does not intersect the DEM grid precisely at one of its nodes.
The user is able to constrain the maximum search distance (--max_dist
) for the ray tracing by entering a valid maximum
search distance value (in the same units as the X-Y coordinates of the input raster DEM). If the maximum search distance
is left blank, each ray will be traced to the edge of the DEM, which will add to the computational time.
Maximum upwind slope should not be calculated for very extensive areas over which the Earth's curvature must be taken into account. Also, this index does not take into account the deflection of wind by topography. However, averaging the horizon angle over a window of directions can yield a more robust measure of exposure, compensating for the deflection of wind from its regional average by the topography. For example, if you are interested in measuring the exposure of a landscape to a northerly wind, you could perform the following calculation:
Sx(N) = [Sx(345)+Sx(350)+Sx(355)+Sx(0)+Sx(5)+Sx(10)+Sx(15)] / 7.0
Ray-tracing is a highly computationally intensive task and therefore this tool may take considerable time to operate for larger sized DEMs. Maximum upwind slope is best displayed using a Grey scale palette that is inverted.
Horizon angle is best visualized using a white-to-black palette and rescaled from approximately -10 to 70 (see below for an example of horizon angle calculated at a 150-degree azimuth).
See Also: TimeInDaylight
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--azimuth | Azimuth, in degrees |
--max_dist | Optional maximum search distance (unspecified if none; in xy units). Minimum value is 5 x cell size |
Python function:
wbt.horizon_angle(
dem,
output,
azimuth=0.0,
max_dist=100.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=HorizonAngle -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif --azimuth=315.0
Author: Dr. John Lindsay
Created: 07/07/2017
Last Modified: 03/09/2020
HypsometricAnalysis
This tool can be used to derive the hypsometric curve, or area-altitude curve, of one or more
input digital elevation models (DEMs) (--inputs
). A hypsometric curve is a histogram or cumulative
distribution function of elevations in a geographical area.
See Also: SlopeVsElevationPlot
Parameters:
Flag | Description |
---|---|
-i, --inputs | Input DEM files |
--watershed | Input watershed files (optional) |
-o, --output | Output HTML file (default name will be based on input file if unspecified) |
Python function:
wbt.hypsometric_analysis(
inputs,
output,
watershed=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=HypsometricAnalysis -v ^
--wd="/path/to/data/" -i="DEM1.tif;DEM2.tif" ^
--watershed="ws1.tif;ws2.tif" -o=outfile.html
Author: Dr. John Lindsay
Created: 30/01/2018
Last Modified: 12/10/2018
HypsometricallyTintedHillshade
This tool creates a hypsometrically tinted shaded relief (Swiss hillshading) image from an input digital elevation model (DEM).
The tool combines a colourized version of the DEM with varying illumination provided by a hillshade image, to
produce a composite relief model that can be used to visual topography for more effective interpretation of
landscapes. The output (--output
) of the tool is a 24-bit red-green-blue (RGB) colour image.
The user must specify the name of the input DEM and the output image name. Other parameters that must
be specified include the illumination source azimuth (--azimuth
), or sun direction (0-360 degrees), the
illumination source altitude (--altitude
; i.e. the elevation of the sun above the horizon, measured as an angle
from 0 to 90 degrees), the hillshade weight (--hs_weight
; 0-1), image brightness (--brightness
; 0-1), and atmospheric
effects (--atmospheric
; 0-1). The hillshade weight can be used to increase or subdue the relative prevalence of the
hillshading effect in the output image. The image brightness parameter is used to create an overall brighter or
darker version of the terrain rendering; note however, that very high values may over-saturate the well-illuminated
portions of the terrain. The atmospheric effects parameter can be used to introduce a haze or atmosphere effect to
the output image. It is intended to reproduce the effect of viewing mountain valley bottoms through a thicker and
more dense atmosphere. Values greater than zero will introduce a slightly blue tint, particularly at lower altitudes,
blur the hillshade edges slightly, and create a random haze-like speckle in lower areas. The user must also specify
the Z conversion factor (--zfactor
). The Z conversion factor is only important when the vertical and horizontal
units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z conversion factor. If the DEM is in the geographic coordinate system (latitude and longitude), the following equation
is used:
zfactor = 1.0 / (111320.0 x cos(mid_lat))
where mid_lat
is the latitude of the centre of the raster, in radians.
See Also: Hillshade, MultidirectionalHillshade, Aspect, Slope
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--altitude | Illumination source altitude in degrees |
--hs_weight | Weight given to hillshade relative to relief (0.0-1.0) |
--brightness | Brightness factor (0.0-1.0) |
--atmospheric | Atmospheric effects weight (0.0-1.0) |
--palette | Options include 'atlas', 'high_relief', 'arid', 'soft', 'muted', 'purple', 'viridi', 'gn_yl', 'pi_y_g', 'bl_yl_rd', and 'deep' |
--reverse | Optional flag indicating whether to use reverse the palette |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
--full_mode | Optional flag indicating whether to use full 360-degrees of illumination sources |
Python function:
wbt.hypsometrically_tinted_hillshade(
dem,
output,
altitude=45.0,
hs_weight=0.5,
brightness=0.5,
atmospheric=0.0,
palette="atlas",
reverse=False,
zfactor=None,
full_mode=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=HypsometricallyTintedHillshade -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif --altitude=45.0 ^
--hs_weight=0.3 --brightness=0.6 --atmospheric=0.2 ^
--palette=arid --full_mode
Author: Dr. John Lindsay
Created: 09/07/2020
Last Modified: 03/09/2020
MapOffTerrainObjects
This tool can be used to map off-terrain objects in a digital surface model (DSM) based on cell-to-cell differences
in elevations and local slopes. The algorithm works by using a region-growing operation to connect neighbouring grid
cells outwards from seed cells. Two neighbouring cells are considered connected if the slope between the two cells
is less than the user-specified maximum slope value (--max_slope
). Mapped segments that are less than the minimum
feature size (--min_size
), in grid cells, are assigned a common background value. Note that this method of mapping
off-terrain objects, and thereby separating ground cells from non-ground objects in DSMs, works best with fine-resolution
DSMs that have been interpolated using a non-smoothing method, such as triangulation (TINing) or nearest-neighbour
interpolation.
See Also: RemoveOffTerrainObjects
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--max_slope | Maximum inter-cell absolute slope |
--min_size | Minimum feature size, in grid cells |
Python function:
wbt.map_off_terrain_objects(
dem,
output,
max_slope=40.0,
min_size=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MapOffTerrainObjects -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--max_diff=1.0
Author: Dr. John Lindsay
Created: 27/07/2020
Last Modified: 27/07/2020
MaxAnisotropyDev
Calculates the maximum anisotropy (directionality) in elevation deviation over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster DEVmax magnitude file |
--out_scale | Output raster DEVmax scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.max_anisotropy_dev(
dem,
out_mag,
out_scale,
max_scale,
min_scale=3,
step=2,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxAnisotropyDev -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=DEVmax_mag.tif ^
--out_scale=DEVmax_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dan Newman and John Lindsay
Created: January 26, 2018
Last Modified: 12/10/2018
MaxAnisotropyDevSignature
Calculates the anisotropy in deviation from mean for points over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--points | Input vector points file |
-o, --output | Output HTML file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.max_anisotropy_dev_signature(
dem,
points,
output,
max_scale,
min_scale=1,
step=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxAnisotropyDevSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.shp ^
--output=roughness.html --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dan Newman and John Lindsay
Created: 27/03/2018
Last Modified: 12/10/2018
MaxBranchLength
Maximum branch length (Bmax
) is the longest branch length between a grid cell's flowpath
and the flowpaths initiated at each of its neighbours. It can be conceptualized as the
downslope distance that a volume of water that is split into two portions by a drainage
divide would travel before reuniting.
If the two flowpaths of neighbouring grid cells do not intersect, Bmax
is simply the
flowpath length from the starting cell to its terminus at the edge of the grid or a cell
with undefined flow direction (i.e. a pit cell either in a topographic depression or at
the edge of a major body of water).
The pattern of Bmax
derived from a DEM should be familiar to anyone who has interpreted
upslope contributing area images. In fact, Bmax
can be thought of as the complement of
upslope contributing area. Whereas contributing area is greatest along valley bottoms and lowest at
drainage divides, Bmax
is greatest at divides and lowest along channels. The two topographic
attributes are also distinguished by their units of measurements; Bmax
is a length rather
than an area. The presence of a major drainage divide between neighbouring grid cells is apparent in
a Bmax
image as a linear feature, often two grid cells wide, of relatively high values. This
property makes Bmax
a useful land surface parameter for mapping ridges and divides.
Bmax
is useful in the study of landscape structure, particularly with respect to drainage patterns.
The index gives the relative significance of a specific location along a divide, with respect to the
dispersion of materials across the landscape, in much the same way that stream ordering can be used
to assess stream size.
See Also: FlowLengthDiff
Reference:
Lindsay JB, Seibert J. 2013. Measuring the significance of a divide to local drainage patterns. International Journal of Geographical Information Science, 27: 1453-1468. DOI: 10.1080/13658816.2012.705289
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--log | Optional flag to request the output be log-transformed |
Python function:
wbt.max_branch_length(
dem,
output,
log=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxBranchLength -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 09/07/2017
Last Modified: 18/10/2019
MaxDifferenceFromMean
Calculates the maximum difference from mean elevation over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster DIFFmax magnitude file |
--out_scale | Output raster DIFFmax scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.max_difference_from_mean(
dem,
out_mag,
out_scale,
min_scale,
max_scale,
step=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxDifferenceFromMean -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=DEVmax_mag.tif ^
--out_scale=DEVmax_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: 28/08/2018
Last Modified: 12/10/2018
MaxDownslopeElevChange
This tool calculates the maximum elevation drop between each grid cell and its neighbouring cells within
a digital elevation model (DEM). The user must specify the name of the input DEM (--dem
) and the output
(--output
) raster name.
See Also: MinDownslopeElevChange, NumDownslopeNeighbours
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.max_downslope_elev_change(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxDownslopeElevChange -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=out.tif
Author: Dr. John Lindsay
Created: 11/07/2017
Last Modified: 12/10/2018
MaxElevDevSignature
Calculates the maximum elevation deviation over a range of spatial scales and for a set of points.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--points | Input vector points file |
-o, --output | Output HTML file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.max_elev_dev_signature(
dem,
points,
output,
min_scale,
max_scale,
step=10,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxElevDevSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.tif ^
--output=topo_position.html --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: March 1, 2018
Last Modified: 12/10/2018
MaxElevationDeviation
This tool can be used to calculate the maximum deviation from mean elevation, DEVmax (Lindsay et al. 2015) for each grid cell in a digital elevation model (DEM) across a range specified spatial scales. DEV is an elevation residual index and is essentially equivalent to a local elevation z-score. This attribute measures the relative topographic position as a fraction of local relief, and so is normalized to the local surface roughness. The multi-scaled calculation of DEVmax utilizes an integral image approach (Crow, 1984) to ensure highly efficient filtering that is invariant with filter size, which is the algorithm characteristic that allows for this densely sampled multi-scale analysis. In this way, MaxElevationDeviation allows users to estimate the locally optimal scale with which to estimate DEV on a pixel-by-pixel basis. This multi-scaled version of local topographic position can reveal significant terrain characteristics and can aid with soil, vegetation, landform, and other mapping applications that depend on geomorphometric characterization.
The user must specify the name (--dem
) of the input digital elevation model (DEM). The range of scales that are
evaluated in calculating DEVmax are determined by the user-specified --min_scale
, --max_scale
, and --step
parameters. All filter radii between the minimum and maximum scales, increasing by step
, will be evaluated.
The scale parameters are in units of grid cells and specify kernel size "radii" (r), such that:
d = 2r + 1
That is, a radii of 1, 2, 3... yields a square filters of dimension (d) 3 x 3, 5 x 5, 7 x 7...
DEV is estimated at each tested filter size and every grid cell is assigned the maximum DEV value across the evaluated scales.
The user must specify the file names of two output rasters, including the magnitude (DEVmax) and a second raster the assigns each pixel the scale at which DEVmax is encountered (DEVscale). The DEVscale raster can be very useful for revealing multi-scale landscape structure.
Reference:
Lindsay J, Cockburn J, Russell H. 2015. An integral image approach to performing multi-scale topographic position analysis. Geomorphology, 245: 51-61.
See Also: DevFromMeanElev, MaxDifferenceFromMean, MultiscaleElevationPercentile
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster DEVmax magnitude file |
--out_scale | Output raster DEVmax scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.max_elevation_deviation(
dem,
out_mag,
out_scale,
min_scale,
max_scale,
step=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MaxElevationDeviation -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=DEVmax_mag.tif ^
--out_scale=DEVmax_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: July 20, 2017
Last Modified: 12/10/2018
MinDownslopeElevChange
This tool calculates the minimum elevation drop between each grid cell and its neighbouring cells within
a digital elevation model (DEM). The user must specify the name of the input DEM (--dem
) and the output
(--output
) raster name.
See Also: MaxDownslopeElevChange, NumDownslopeNeighbours
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.min_downslope_elev_change(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MinDownslopeElevChange -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=out.tif
Author: Dr. John Lindsay
Created: 11/07/2017
Last Modified: 12/10/2018
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--altitude | Illumination source altitude in degrees |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
--full_mode | Optional flag indicating whether to use full 360-degrees of illumination sources |
Python function:
wbt.multidirectional_hillshade(
dem,
output,
altitude=45.0,
zfactor=None,
full_mode=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultidirectionalHillshade -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif ^
--altitude=30.0
Author: Dr. John Lindsay
Created: 19/07/2020
Last Modified: 03/09/2020
MultiscaleElevationPercentile
This tool calculates the most elevation percentile (EP) across a range of spatial scales. EP is a measure of local topographic position (LTP) and expresses the vertical position for a digital elevation model (DEM) grid cell (z0) as the percentile of the elevation distribution within the filter window, such that:
EP = counti∈C(zi > z0) x (100 / nC)
where z0 is the elevation of the window's center grid cell, zi is the elevation of cell i contained within the neighboring set C, and nC is the number of grid cells contained within the window.
EP is unsigned and expressed as a percentage, bound between 0%
and 100%. This tool outputs two rasters, the multiscale EP magnitude (--out_mag
) and
the scale at which the most extreme EP value occurs (--out_scale
). The magnitude raster is
the most extreme EP value (i.e. the furthest from 50%) for each grid cell encountered within
the tested scales of EP.
Quantile-based estimates (e.g., the median and interquartile range) are often used in nonparametric statistics to provide data variability estimates without assuming the distribution is normal. Thus, EP is largely unaffected by irregularly shaped elevation frequency distributions or by outliers in the DEM, resulting in a highly robust metric of LTP. In fact, elevation distributions within small to medium sized neighborhoods often exhibit skewed, multimodal, and non-Gaussian distributions, where the occurrence of elevation errors can often result in distribution outliers. Thus, based on these statistical characteristics, EP is considered one of the most robust representation of LTP.
The algorithm implemented by this tool uses the relatively efficient running-histogram filtering algorithm of Huang
et al. (1979). Because most DEMs contain floating point data, elevation values must be rounded to be binned. The
--sig_digits
parameter is used to determine the level of precision preserved during this binning process. The
algorithm is parallelized to further aid with computational efficiency.
Experience with multiscale EP has shown that it is highly variable at shorter scales and changes more gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested scales, such that:
ri = rL + [step × (i - rL)]p
Where ri is the filter radius for step i and p is the nonlinear scaling factor (--step_nonlinearity
)
and a step size (--step
) of step.
References:
Newman, D. R., Lindsay, J. B., and Cockburn, J. M. H. (2018). Evaluating metrics of local topographic position for multiscale geomorphometric analysis. Geomorphology, 312, 40-50.
Huang, T., Yang, G.J.T.G.Y. and Tang, G., 1979. A fast two-dimensional median filtering algorithm. IEEE Transactions on Acoustics, Speech, and Signal Processing, 27(1), pp.13-18.
See Also:
ElevationPercentile
, MaxElevationDeviation, MaxDifferenceFromMean
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster roughness magnitude file |
--out_scale | Output raster roughness scale file |
--sig_digits | Number of significant digits |
--min_scale | Minimum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
--num_steps | Number of steps |
--step_nonlinearity | Step nonlinearity factor (1.0-2.0 is typical) |
Python function:
wbt.multiscale_elevation_percentile(
dem,
out_mag,
out_scale,
sig_digits=3,
min_scale=4,
step=1,
num_steps=10,
step_nonlinearity=1.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleElevationPercentile -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --step=5 ^
--num_steps=100 --step_nonlinearity=1.5
Author: Dr. John Lindsay
Created: 22/12/2019
Last Modified: 22/12/2019
MultiscaleRoughness
Calculates surface roughness over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster roughness magnitude file |
--out_scale | Output raster roughness scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.multiscale_roughness(
dem,
out_mag,
out_scale,
max_scale,
min_scale=1,
step=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleRoughness -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: 26/02/2018
Last Modified: 03/09/2020
MultiscaleRoughnessSignature
Calculates the surface roughness for points over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--points | Input vector points file |
-o, --output | Output HTML file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--max_scale | Maximum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
Python function:
wbt.multiscale_roughness_signature(
dem,
points,
output,
max_scale,
min_scale=1,
step=1,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleRoughnessSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.shp ^
--output=roughness.html --min_scale=1 --max_scale=1000 ^
--step=5
Author: Dr. John Lindsay
Created: 27/02/2018
Last Modified: 03/09/2020
MultiscaleStdDevNormals
This tool can be used to map the spatial pattern of maximum spherical standard deviation
(σs max; --out_mag
), as well as the scale at which maximum spherical standard deviation occurs
(rmax; --out_scale
), for each grid cell in an input DEM (--dem
). This serves as a multi-scale measure
of surface roughness, or topographic complexity. The spherical standard deviation (σs) is
a measure of the angular spread among n unit vectors and is defined as:
σs = √[-2ln(R / N)] × 180 / π
Where R is the resultant vector length and is derived from the sum of the x, y, and z components of each of the n normals contained within a filter kernel, which designates a tested spatial scale. Each unit vector is a 3-dimensional measure of the surface orientation and slope at each grid cell center. The maximum spherical standard deviation is:
σs max=max{σs(r):r=rL...rU},
Experience with roughness scale signatures has shown that σs max is highly variable at shorter scales and changes more gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested scales, such that:
ri = rL + [step × (i - rL)]p
Where ri is the filter radius for step i and p is the nonlinear scaling factor (--step_nonlinearity
)
and a step size (--step
) of step.
Use the SphericalStdDevOfNormals tool if you need to calculate σs for a single scale.
Reference:
JB Lindsay, DR Newman, and A Francioni. 2019 Scale-Optimized Surface Roughness for Topographic Analysis. Geosciences, 9(322) doi: 10.3390/geosciences9070322.
See Also: SphericalStdDevOfNormals, MultiscaleStdDevNormalsSignature, MultiscaleRoughness
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_mag | Output raster roughness magnitude file |
--out_scale | Output raster roughness scale file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
--num_steps | Number of steps |
--step_nonlinearity | Step nonlinearity factor (1.0-2.0 is typical) |
Python function:
wbt.multiscale_std_dev_normals(
dem,
out_mag,
out_scale,
min_scale=1,
step=1,
num_steps=10,
step_nonlinearity=1.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleStdDevNormals -v ^
--wd="/path/to/data/" --dem=DEM.tif --out_mag=roughness_mag.tif ^
--out_scale=roughness_scale.tif --min_scale=1 --step=5 ^
--num_steps=100 --step_nonlinearity=1.5
Author: Dr. John Lindsay
Created: 05/06/2019
Last Modified: 03/09/2020
MultiscaleStdDevNormalsSignature
Calculates the surface roughness for points over a range of spatial scales.
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--points | Input vector points file |
-o, --output | Output HTML file |
--min_scale | Minimum search neighbourhood radius in grid cells |
--step | Step size as any positive non-zero integer |
--num_steps | Number of steps |
--step_nonlinearity | Step nonlinearity factor (1.0-2.0 is typical) |
Python function:
wbt.multiscale_std_dev_normals_signature(
dem,
points,
output,
min_scale=1,
step=1,
num_steps=10,
step_nonlinearity=1.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleStdDevNormalsSignature -v ^
--wd="/path/to/data/" --dem=DEM.tif --points=sites.shp ^
--output=roughness.html --min_scale=1 --step=5 --num_steps=100 ^
--step_nonlinearity=1.5
Author: Dr. John Lindsay
Created: 20/06/2019
Last Modified: 03/09/2020
MultiscaleTopographicPositionImage
This tool creates a multiscale topographic position (MTP) image (see here for an
example) from three DEVmax rasters of differing
spatial scale ranges. Specifically, MultiscaleTopographicPositionImage takes three DEVmax magnitude
rasters, created using the MaxElevationDeviation tool, as inputs. The three inputs should correspond to the elevation
deviations in the local (--local
), meso (--meso
), and broad (--broad
) scale ranges and will be forced into the
blue, green, and red colour components of the colour composite output (--output
) raster. The image lightness value
(--lightness
) controls the overall brightness of the output image, as depending on the topography and scale ranges,
these images can appear relatively dark. Higher values result in brighter, more colourful output images.
The output images can take some training to interpret correctly and a detailed explanation can be found in Lindsay et al. (2015). Sites within the landscape that occupy prominent topographic positions, either low-lying or elevated, will be apparent by their bright colouring in the MTP image. Those that are coloured more strongly in the blue are promient at the local scale range; locations that are more strongly green coloured are promient at the meso scale; and bright reds in the MTP image are associated with broad-scale landscape prominence. Of course, combination colours are also possible when topography is elevated or low-lying across multiple scale ranges. For example, a yellow area would indicated a site of prominent topographic position across the meso and broadest scale ranges.
Reference:
Lindsay J, Cockburn J, Russell H. 2015. An integral image approach to performing multi-scale topographic position analysis. Geomorphology, 245: 51-61.
See Also: MaxElevationDeviation
Parameters:
Flag | Description |
---|---|
--local | Input local-scale topographic position (DEVmax) raster file |
--meso | Input meso-scale topographic position (DEVmax) raster file |
--broad | Input broad-scale topographic position (DEVmax) raster file |
-o, --output | Output raster file |
--lightness | Image lightness value (default is 1.2) |
Python function:
wbt.multiscale_topographic_position_image(
local,
meso,
broad,
output,
lightness=1.2,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=MultiscaleTopographicPositionImage -v ^
--wd="/path/to/data/" --local=DEV_local.tif --meso=DEV_meso.tif ^
--broad=DEV_broad.tif -o=output.tif --lightness=1.5
Author: Dr. John Lindsay
Created: 19/07/2017
Last Modified: 30/01/2020
NumDownslopeNeighbours
This tool calculates the number of downslope neighbours of each grid cell in a raster digital elevation model (DEM).
The user must specify the name of the input DEM (--dem
) and the output (--output
) raster name. The tool examines
the eight neighbouring cells for each grid cell in a the DEM and counts the number of neighbours with an elevation
less than the centre cell of the 3 x 3 window. The output image can therefore have values raning from 0 to 8. A
raster grid cell with eight downslope neighbours is a peak and a cell with zero downslope neighbours is a pit. This
tool can be used with the NumUpslopeNeighbours tool to assess the degree of local flow divergence/convergence.
See Also: NumUpslopeNeighbours
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.num_downslope_neighbours(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=NumDownslopeNeighbours -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 12/10/2018
NumUpslopeNeighbours
This tool calculates the number of upslope neighbours of each grid cell in a raster digital elevation model (DEM).
The user must specify the name of the input DEM (--dem
) and the output (--output
) raster name. The tool examines
the eight neighbouring cells for each grid cell in a the DEM and counts the number of neighbours with an elevation
less than the centre cell of the 3 x 3 window. The output raster can therefore have values ranging from 0 to 8, although
in a DEM that has been hydrologically conditioned (i.e. depressions and flats removed), the values of the output will
not exceed seven. This tool can be used with the NumDownslopeNeighbours tool to assess the degree of local flow
divergence/convergence.
See Also: NumDownslopeNeighbours
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.num_upslope_neighbours(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=NumUpslopeNeighbours -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 12/10/2018
Openness
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool calculates the Yokoyama et al. (2002) topographic openness index from an input DEM (--input
).
Openness has two viewer perspectives, which correspond with positive and negative openness outputs (--pos_output
and --neg_output
). Positive values, expressing openness above the surface, are high for convex forms,
whereas negative values describe this attribute below the surface and are high for concave forms. Openness
is an angular value that is an average of the horizon angle in the eight cardinal directions to a maximum
search distance (--dist
), measured in grid cells. Openness rasters are best visualized using a greyscale palette.
Positive Openness:
Negative Openness:
References:
Yokoyama, R., Shirasawa, M., & Pike, R. J. (2002). Visualizing topography by openness: a new application of image processing to digital elevation models. Photogrammetric engineering and remote sensing, 68(3), 257-266.
See Also: Viewshed, HorizonAngle, TimeInDaylight, Hillshade
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input raster image file |
--pos_output | Name of the positive openness output raster file |
--neg_output | Name of the negative openness output raster file |
--dist | Search distance, in grid cells |
Python function:
wbt.openness(
i,
pos_output,
neg_output,
dist=20,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=Openness --input=DEM.tif ^
--pos_output=positive_openness.tif ^
--neg_output=negative_openness.tif --dist=500
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 30/03/2021
Last Modified: 30/03/2021
PennockLandformClass
Tool can be used to perform a simple landform classification based on measures of slope gradient and curvature derived from a user-specified digital elevation model (DEM). The classification scheme is based on the method proposed by Pennock, Zebarth, and DeJong (1987). The scheme divides a landscape into seven element types, including: convergent footslopes (CFS), divergent footslopes (DFS), convergent shoulders (CSH), divergent shoulders (DSH), convergent backslopes (CBS), divergent backslopes (DBS), and level terrain (L). The output raster image will record each of these base element types as:
Element Type | Code |
---|---|
CFS | 1 |
DFS | 2 |
CSH | 3 |
DSH | 4 |
CBS | 5 |
DBS | 6 |
L | 7 |
The definition of each of the elements, based on the original Pennock et al. (1987) paper, is as follows:
PROFILE | GRADIENT | PLAN | Element |
---|---|---|---|
Concave ( -0.10) | High >3.0 | Concave 0.0 | CFS |
Concave ( -0.10) | High >3.0 | Convex >0.0 | DFS |
Convex (>0.10) | High >3.0 | Concave 0.0 | CSH |
Convex (>0.10) | High >3.0 | Convex >0.0 | DSH |
Linear (-0.10...0.10) | High >3.0 | Concave 0.0 | CBS |
Linear (-0.10...0.10) | High >3.0 | Convex >0.0 | DBS |
-- | Low 3.0 | -- | L |
Where PROFILE is profile curvature, GRADIENT is the slope gradient, and PLAN is the plan curvature. Note that these values are likely landscape and data specific and can be adjusted by the user. Landscape classification schemes that are based on terrain attributes are highly sensitive to short-range topographic variability (i.e. roughness) and can benefit from pre-processing the DEM with a smoothing filter to reduce the effect of surface roughness and emphasize the longer-range topographic signal. The FeaturePreservingSmoothing tool offers excellent performance in smoothing DEMs without removing the sharpness of breaks-in-slope.
Reference:
Pennock, D.J., Zebarth, B.J., and DeJong, E. (1987) Landform classification and soil distribution in hummocky terrain, Saskatchewan, Canada. Geoderma, 40: 297-315.
See Also: FeaturePreservingSmoothing
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--slope | Slope threshold value, in degrees (default is 3.0) |
--prof | Profile curvature threshold value (default is 0.1) |
--plan | Plan curvature threshold value (default is 0.0) |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.pennock_landform_class(
dem,
output,
slope=3.0,
prof=0.1,
plan=0.0,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=PennockLandformClass -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif --slope=3.0 ^
--prof=0.1 --plan=0.0
Author: Dr. John Lindsay
Created: 12/07/2017
Last Modified: 03/09/2020
PercentElevRange
Percent elevation range (PER) is a measure of local topographic position (LTP). It expresses the vertical position for a digital elevation model (DEM) grid cell (z0) as the percentage of the elevation range within the neighbourhood filter window, such that:
PER = z0 / (zmax - zmin) x 100
where z0 is the elevation of the window's center grid cell, zmax is the maximum neighbouring elevation, and zmin is the minimum neighbouring elevation.
Neighbourhood size, or filter size, is specified in the x and y dimensions using the --filterx
and --filtery
flags.
These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).
Compared with ElevPercentile and DevFromMeanElev, PER is a less robust measure of LTP that is susceptible to outliers in neighbouring elevations (e.g. the presence of off-terrain objects in the DEM).
References:
Newman, D. R., Lindsay, J. B., and Cockburn, J. M. H. (2018). Evaluating metrics of local topographic position for multiscale geomorphometric analysis. Geomorphology, 312, 40-50.
See Also: ElevPercentile, DevFromMeanElev, DiffFromMeanElev, RelativeTopographicPosition
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.percent_elev_range(
dem,
output,
filterx=3,
filtery=3,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=PercentElevRange -v ^
--wd="/path/to/data/" -i=DEM.tif -o=output.tif --filter=25
Author: Dr. John Lindsay
Created: 25/06/2017
Last Modified: 30/01/2020
PlanCurvature
This tool calculates the plan curvature (i.e. contour curvature), or the rate of change in
aspect along a contour line, from a digital elevation model (DEM). Curvature is the second
derivative of the topographic surface defined by a DEM. Plan curvature characterizes the
degree of flow convergence or divergence within the landscape (Gallant and Wilson, 2000).
The user must specify the name of the input DEM (--dem
) and the output raster image.
WhiteboxTools reports curvature in degrees multiplied by 100 for easier interpretation. The
Z conversion factor (--zfactor
) is only important when the vertical and horizontal units
are not the same in the DEM. When this is the case, the algorithm will multiply each
elevation in the DEM by the Z Conversion Factor. If the DEM is in the geographic coordinate
system (latitude and longitude), the following equation is used:
zfactor = 1.0 / (111320.0 x cos(mid_lat))
where mid_lat
is the latitude of the centre of the raster, in radians.
The algorithm uses the same formula for the calculation of plan curvature as Gallant and Wilson (2000). Plan curvature is negative for diverging flow along ridges and positive for convergent areas, e.g. along valley bottoms.
Reference:
Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, in Terrain Analysis: Principles and Applications, edited by J. P. Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.
See Also: ProfileCurvature, TangentialCurvature, TotalCurvature, Slope, Aspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.plan_curvature(
dem,
output,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=PlanCurvature -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 01/06/2017
Last Modified: 01/03/2021
Profile
This tool can be used to plot the data profile, along a set of one or more vector lines (--lines
), in
an input (--surface
) digital elevation model (DEM), or other surface model. The data profile plots
surface height (y-axis) against distance along profile (x-axis). The tool outputs an interactive SVG line
graph embedded in an HTML document (--output
). If the vector lines file contains multiple line features,
the output plot will contain each of the input profiles.
If you want to extract the longitudinal profile of a river, use the LongProfile tool instead.
See Also: LongProfile, HypsometricAnalysis
Parameters:
Flag | Description |
---|---|
--lines | Input vector line file |
--surface | Input raster surface file |
-o, --output | Output HTML file |
Python function:
wbt.profile(
lines,
surface,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Profile -v --wd="/path/to/data/" ^
--lines=profile.shp --surface=dem.tif -o=profile.html
Author: Dr. John Lindsay
Created: 21/02/2018
Last Modified: 12/10/2018
ProfileCurvature
This tool calculates the profile curvature, or the rate of change in slope along a flow line,
from a digital elevation model (DEM). Curvature is the second
derivative of the topographic surface defined by a DEM. Profile curvature characterizes the
degree of downslope acceleration or deceleration within the landscape (Gallant and Wilson, 2000).
The user must specify the name of the input DEM (--dem
) and the output raster image.
WhiteboxTools reports curvature in degrees multiplied by 100 for easier interpretation because
curvature values are typically very small. The
Z conversion factor (--zfactor
) is only important when the vertical and horizontal units
are not the same in the DEM. When this is the case, the algorithm will multiply each
elevation in the DEM by the Z Conversion Factor. If the DEM is in the geographic coordinate
system (latitude and longitude), the following equation is used:
zfactor = 1.0 / (111320.0 x cos(mid_lat))
where mid_lat
is the latitude of the centre of the raster, in radians.
The algorithm uses the same formula for the calculation of plan curvature as Gallant and Wilson (2000). Profile curvature is negative for slope increasing downhill (convex flow profile, typical of upper slopes) and positive for slope decreasing downhill (concave, typical of lower slopes).
Reference:
Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, in Terrain Analysis: Principles and Applications, edited by J. P. Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.
See Also: ProfileCurvature, TangentialCurvature, TotalCurvature, Slope, Aspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.profile_curvature(
dem,
output,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ProfileCurvature -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/062017
Last Modified: 01/03/2021
RelativeAspect
This tool creates a new raster in which each grid cell is assigned the terrain aspect relative to a user-specified
direction (--azimuth
). Relative terrain aspect is the angular distance (measured in degrees) between the land-surface
aspect and the assumed regional wind azimuth (Bohner and Antonic, 2007). It is bound between 0-degrees (windward direction)
and 180-degrees (leeward direction). Relative terrain aspect is the simplest of the measures of topographic exposure to
wind, taking into account terrain orientation only and neglecting the influences of topographic shadowing by distant
landforms and the deflection of wind by topography.
The user must specify the name of a digital elevation model (DEM) (--dem
) and an azimuth (i.e. a wind direction). The
Z Conversion Factor (--zfactor
) is only important when the vertical and horizontal units are not the same in the DEM.
When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor.
Reference:
Böhner, J., and Antonić, O. (2009). Land-surface parameters specific to topo-climatology. Developments in Soil Science, 33, 195-226.
See Also: Aspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--azimuth | Illumination source azimuth |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.relative_aspect(
dem,
output,
azimuth=0.0,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=RelativeAspect -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --azimuth=180.0
Author: Dr. John Lindsay
Created: 17/06/2017
Last Modified: 03/09/2020
RelativeTopographicPosition
Relative topographic position (RTP) is an index of local topographic position (i.e. how
elevated or low-lying a site is relative to its surroundings) and is a modification of percent
elevation range (PER; PercentElevRange) and accounts for the elevation distribution. Rather than
positioning the central cell's elevation solely between the filter extrema, RTP is a piece-wise
function that positions the central elevation relative to the minimum (zmin), mean (μ),
and maximum values (zmax), within a local neighbourhood of a user-specified size (--filterx
,
--filtery
), such that:
RTP = (z0 − μ) / (μ − zmin), if z0 < μ
OR
RTP = (z0 − μ) / (zmax - μ), if z0 >= μ
The resulting index is bound by the interval [−1, 1], where the sign indicates if the cell is above or below than the filter mean. Although RTP uses the mean to define two linear functions, the reliance on the filter extrema is expected to result in sensitivity to outliers. Furthermore, the use of the mean implies assumptions of unimodal and symmetrical elevation distribution.
In many cases, Elevation Percentile (ElevPercentile) and deviation from mean elevation (DevFromMeanElev) provide more suitable and robust measures of relative topographic position.
Reference:
Newman, D. R., Lindsay, J. B., and Cockburn, J. M. H. (2018). Evaluating metrics of local topographic position for multiscale geomorphometric analysis. Geomorphology, 312, 40-50.
See Also: DevFromMeanElev, DiffFromMeanElev, ElevPercentile, PercentElevRange
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.relative_topographic_position(
dem,
output,
filterx=11,
filtery=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=RelativeTopographicPosition -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--filter=25
Author: Dr. John Lindsay
Created: 06/06/2017
Last Modified: 30/01/2020
RemoveOffTerrainObjects
This tool can be used to create a bare-earth DEM from a fine-resolution digital surface model. The
tool is typically applied to LiDAR DEMs which frequently contain numerous off-terrain objects (OTOs) such
as buildings, trees and other vegetation, cars, fences and other anthropogenic objects. The algorithm
works by finding and removing steep-sided peaks within the DEM. All peaks within a sub-grid, with a
dimension of the user-specified maximum OTO size (--filter
), in pixels, are identified and removed.
Each of the edge cells of the peaks are then examined to see if they have a slope that is less than the
user-specified minimum OTO edge slope (--slope
) and a back-filling procedure is used. This ensures that
OTOs are distinguished from natural topographic features such as hills. The DEM is preprocessed using a
white top-hat transform, such that elevations are normalized for the underlying ground surface.
Note that this tool is appropriate to apply to rasterized LiDAR DEMs. Use the LidarGroundPointFilter tool to remove or classify OTOs within a LiDAR point-cloud.
Reference:
J.B. Lindsay (2018) A new method for the removal of off-terrain objects from LiDAR-derived raster surface models. Available online, DOI: 10.13140/RG.2.2.21226.62401
See Also: MapOffTerrainObjects, TophatTransform, LidarGroundPointFilter
Parameters:
Flag | Description |
---|---|
-i, --input, --dem | Input raster DEM file |
-o, --output | Output raster file |
--filter | Filter size (cells) |
--slope | Slope threshold value |
Python function:
wbt.remove_off_terrain_objects(
dem,
output,
filter=11,
slope=15.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=RemoveOffTerrainObjects -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=bare_earth_DEM.tif ^
--filter=25 --slope=10.0
Author: Dr. John Lindsay
Created: 06/06/2017
Last Modified: 07/08/2020
RuggednessIndex
The terrain ruggedness index (TRI) is a measure of local topographic relief. The TRI calculates the root-mean-square-deviation (RMSD) for each grid cell in a digital elevation model (DEM), calculating the residuals (i.e. elevation differences) between a grid cell and its eight neighbours. Notice that, unlike the output of this tool, the original Riley et al. (1999) TRI did not normalize for the number of cells in the local window (i.e. it is a root-square-deviation only). However, using the mean has the advantage of allowing for the varying number of neighbouring cells along the grid edges and in areas bordering NoData cells. This modification does however imply that the ouput of this tool cannot be directly compared with the index ranges of level to extremely rugged terrain provided in Riley et al. (1999)
Reference:
Riley, S. J., DeGloria, S. D., and Elliot, R. (1999). Index that quantifies topographic heterogeneity. Intermountain Journal of Sciences, 5(1-4), 23-27.
See Also: RelativeTopographicPosition, DevFromMeanElev
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.ruggedness_index(
dem,
output,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=RuggednessIndex -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 03/09/2020
SedimentTransportIndex
This tool calculates the sediment transport index, or sometimes, length-slope (LS)
factor, based on input specific contributing area (As, i.e. the upslope
contributing area per unit contour length; --sca
) and slope gradient
(β, measured in degrees; --slope
) rasters. Moore et al. (1991) state that the physical potential for
sheet and rill erosion in upland catchments can be evaluated by the product R K LS,
a component of the Universal Soil Loss Equation (USLE), where R is a rainfall and
runoff erosivity factor, K is a soil erodibility factor, and LS is the length-slope
factor that accounts for the effects of topography on erosion. To predict erosion at a
point in the landscape the LS factor can be written as:
LS = (n + 1)(As / 22.13)n(sin(β) / 0.0896)m
where n = 0.4 (--sca_exponent
) and m = 1.3 (--slope_exponent
) in its original formulation.
This index is derived from unit stream-power theory and is sometimes used in place of the length-slope factor in the revised universal soil loss equation (RUSLE) for slope lengths less than 100 m and slope less than 14 degrees. Like many hydrological land-surface parameters SedimentTransportIndex assumes that contributing area is directly related to discharge. Notice that As must not be log-transformed prior to being used; As is commonly log-transformed to enhance visualization of the data. Also, As can be derived using any of the available flow accumulation tools, alghough better results usually result from application of multiple-flow direction algorithms such as DInfFlowAccumulation and FD8FlowAccumulation. The slope raster can be created from the base digital elevation model (DEM) using the Slope tool. The input images must have the same grid dimensions.
Reference:
Moore, I. D., Grayson, R. B., and Ladson, A. R. (1991). Digital terrain modelling: a review of hydrological, geomorphological, and biological applications. Hydrological processes, 5(1), 3-30.
See Also: StreamPowerIndex, DInfFlowAccumulation, FD8FlowAccumulation
Parameters:
Flag | Description |
---|---|
--sca | Input raster specific contributing area (SCA) file |
--slope | Input raster slope file |
-o, --output | Output raster file |
--sca_exponent | SCA exponent value |
--slope_exponent | Slope exponent value |
Python function:
wbt.sediment_transport_index(
sca,
slope,
output,
sca_exponent=0.4,
slope_exponent=1.3,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=SedimentTransportIndex -v ^
--wd="/path/to/data/" --sca='flow_accum.tif' ^
--slope='slope.tif' -o=output.tif --sca_exponent=0.5 ^
--slope_exponent=1.0
Author: Dr. John Lindsay
Created: 02/07/2017
Last Modified: 30/01/2020
ShadowAnimation
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool creates an interactive animated GIF of shadows based on an input digital surface model (DSM).
The shadow model is based on the modelled positions of the sun throughout a user-specified date (--date
)
sampling at a regular interval (--interval
), in minutes. Similar to the TimeInDaylight tool, this
tool uses calculated horizon angle (HorizonAngle) values and a solar position model to determine which
grid cells are located in shadow areas due to distant obsticles. The calculation of horizon angle, requires
the user input a maximum search distance parameter (--max_dist
).
The output (--output
) of this tool is an HTML file, containing the interactive GIF animation. Users
are able to zoom and pan around the displayed DEV animation. The DSM may be rendered in one of several
available palettes (--palette
) suitable for visualization topography. The user must also
specify the image height (--height
) in the output file, the time delay (--delay
, in milliseconds) used
in the GIF animation, and an optional label (--label
), which will appear in the upper lefthand corner.
Note that the output is simply HTML, CSS, javascript code, and a GIF file, which can be readily embedded
in other documents.
Users should be aware that the outut GIF can be very large in size, depending on the size of the input DEM file. To reduce the file size of the output, it may be desirable to coarsen the input DEM resolution using image resampling (Resample).
The following is an example of what the output of this tool looks like. Click the image for an interactive example.
See Also: TimeInDaylight, HorizonAngle
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input digital surface model (DSM) raster file |
-p, --palette | DSM image palette; options are 'atlas', 'high_relief', 'arid', 'soft', 'muted', 'light_quant', 'purple', 'viridi', 'gn_yl', 'pi_y_g', 'bl_yl_rd', 'deep', and 'none' |
-o, --output | Name of the output HTML file (*.html) |
--max_dist | Optional maximum search distance. Minimum value is 5 x cell size |
-d, --date | Date in format DD/MM/YYYY |
--interval | Time interval, in minutes (1-60) |
--location | Location, defined as Lat/Long/UTC-offset (e.g. 43.5448/-80.2482/-4) |
-h, --height | Image height, in pixels |
--delay | GIF time delay in milliseconds |
-l, --label | Label text (leave blank for none) |
Python function:
wbt.shadow_animation(
i,
output,
palette="atlas",
max_dist="",
date="21/06/2021",
interval=15,
location="43.5448/-80.2482/-4",
height=600,
delay=250,
label="",
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=ShadowAnimation -i=dsm.tif ^
-p='high_relief' -o=shadow_animation.html --max_dist=500 ^
--date='21/06/2021' --interval=20 --location='43.55/ -80.25/ ^
-4' --height=620 --delay=200 --label='Shadow Animation'
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 01/05/2021
Last Modified: 01/05/2021
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. If the
DEM is in the geographic coordinate system (latitude and longitude), the following equation
is used:
zfactor = 1.0 / (111320.0 x cos(mid_lat))
where mid_lat
is the latitude of the centre of the raster, in radians.
The tool uses Horn's (1981) 3rd-order finite difference method to estimate slope. Given the following clock-type grid cell numbering scheme (Gallant and Wilson, 2000),
| 7 | 8 | 1 |
| 6 | 9 | 2 |
| 5 | 4 | 3 |
slope = arctan(fx2 + fy2)0.5
where,
fx = (z3 - z5 + 2(z2 - z6) + z1 - z7) / 8 * Δx
and,
fy = (z7 - z5 + 2(z8 - z4) + z1 - z3) / * Δy
Δx and Δy are the grid resolutions in the x and y direction respectively
Reference:
Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, in Terrain Analysis: Principles and Applications, edited by J. P. Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.
See Also: Aspect, PlanCurvature, ProfileCurvature
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
--units | Units of output raster; options include 'degrees', 'radians', 'percent' |
Python function:
wbt.slope(
dem,
output,
zfactor=None,
units="degrees",
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Slope -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif --units="radians"
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 01/03/2021
SlopeVsElevationPlot
This tool can be used to create a slope versus average elevation plot for one or more digital elevation models (DEMs).
Similar to a hypsometric analysis (HypsometricAnalysis), the slope-elevation relation can reveal the basic
topographic character of a site. The output of this analysis is an HTML document (--output
) that contains the
slope-elevation chart. The tool can plot multiple slope-elevation analyses on the same chart by specifying multiple
input DEM files (--inputs
). Each input DEM can have an optional watershed in which the slope-elevation analysis is
confined by specifying the optional --watershed
flag. If multiple input DEMs are used, and a watershed is used to
confine the analysis to a sub-area, there must be the same number of input raster watershed files as input DEM files.
The order of the DEM and watershed files must the be same (i.e. the first DEM file must correspond to the first
watershed file, the second DEM file to the second watershed file, etc.). Each watershed file may contain one or more
watersheds, designated by unique identifiers.
See Also: HypsometricAnalysis
Parameters:
Flag | Description |
---|---|
-i, --inputs | Input DEM files |
--watershed | Input watershed files (optional) |
-o, --output | Output HTML file (default name will be based on input file if unspecified) |
Python function:
wbt.slope_vs_elevation_plot(
inputs,
output,
watershed=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=SlopeVsElevationPlot -v ^
--wd="/path/to/data/" -i="DEM1.tif;DEM2.tif" ^
--watershed="ws1.tif;ws2.tif" -o=outfile.html
Author: Dr. John Lindsay
Created: 01/02/2018
Last Modified: 03/09/2020
SmoothVegetationResidual
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool can smooth the roughness due to residual vegetation cover in LiDAR digital elevation models (DEMs).
Sometimes when LiDAR data are collected under heavy forest cover, particularly conifer species, the DEM
will contain substantial roughness, even if it is interpolated using last-return points only. This tool can
be used to reduce the roughness of the ground surface under these conditions. It works by identifying grid cells
that possess deviation in mean elevation (DEV, DevFromMeanElev) values that are higher than a specified
threshold value (--dev_threshold
) for tested scales less than a specified threshold (--scale_threshold
).
DEV is measured for the input DEM (--input
) using filter radii from 1 to a user-specified maximum (--max_scale
).
The identified grid cells are then masked out and their elevations are re-interpolated using the surrounding,
non-masked values.
This method can work well under some conditions, and will further benefit from multiple passes of the tool, i.e.
run the tool using one set of parameters and then use the output (--output
) as the input for the second pass.
Alternative approaches include use of the RemoveOffTerrainObjects tool, using low-pass filters such as the
FeaturePreservingSmoothing tool, or, if the point-cloud source data are available, classifying the ground
points using LidarGroundPointFilter and excluding non-ground points from the interpolation.
The following image shows an image of a DEM that is badly impacted by heavy forest cover, with obvious vegetation residual roughness.
This image shows the impact of two-passes of the SmoothVegetationResidual tool.
See Also:
RemoveOffTerrainObjects, FeaturePreservingSmoothing, LidarGroundPointFilter, DevFromMeanElev
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input digital elevation model (DEM) raster file |
-o, --output | Name of the output raster file |
--max_scale | Maximum search neighbourhood radius in grid cells |
--dev_threshold | DEVmax Threshold |
--scale_threshold | DEVmax scale threshold |
Python function:
wbt.smooth_vegetation_residual(
i,
output,
max_scale=30,
dev_threshold=1.0,
scale_threshold=5,
callback=default_callback
)
Command-line Interface:
-./whitebox_tools -r=SmoothVegetationResidual -i=DEM.tif ^
-o=smoothed_DEM.tif --max_scale=50 --dev_threshold=0.5 ^
--scale_threshold=8
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 09/05/2021
Last Modified: 09/05/2021
SphericalStdDevOfNormals
This tool can be used to calculate the spherical standard deviation of the distribution of surface normals
for an input digital elevation model (DEM; --dem
). This is a measure of the angular dispersion of the surface
normal vectors within a local neighbourhood of a specified size (--filter
). SphericalStdDevOfNormals
is therefore a measure of surface shape complexity, texture, and roughness. The
spherical standard deviation (s) is defined as:
s = √[-2ln(R / N)] × 180 / π
where R is the resultant vector length and N is the number of unit normal vectors within the local neighbourhood. s is measured in degrees and is zero for simple planes and increases infinitely with increasing surface complexity or roughness. Note that this formulation of the spherical standard deviation assumes an underlying wrapped normal distribution.
The local neighbourhood size (--filter
) must be any odd integer equal to or greater than three. Grohmann et al. (2010) found that
vector dispersion, a related measure of angular dispersion, increases monotonically with scale. This is the result
of the angular dispersion measure integrating (accumulating) all of the surface variance of smaller scales up to the
test scale. A more interesting scale relation can therefore be estimated by isolating the amount of surface complexity
associated with specific scale ranges. That is, at large spatial scales, s should reflect
the texture of large-scale landforms rather than the accumulated complexity at all smaller scales, including
microtopographic roughness. As such, this tool normalizes the surface complexity of scales that are smaller than
the filter size by applying Gaussian blur (with a standard deviation of one-third the filter size) to the DEM prior
to calculating R. In this way, the resulting distribution is able to isolate and highlight
the surface shape complexity associated with landscape features of a similar scale to that of the filter size.
This tool makes extensive use of integral images (i.e. summed-area tables) and parallel processing to ensure computational efficiency. It may, however, require substantial memory resources when applied to larger DEMs.
References:
Grohmann, C. H., Smith, M. J., & Riccomini, C. (2010). Multiscale analysis of topographic surface roughness in the Midland Valley, Scotland. IEEE Transactions on Geoscience and Remote Sensing, 49(4), 1200-1213.
Hodgson, M. E., and Gaile, G. L. (1999). A cartographic modeling approach for surface orientation-related applications. Photogrammetric Engineering and Remote Sensing, 65(1), 85-95.
Lindsay J. B., Newman* D. R., Francioni, A. 2019. Scale-optimized surface roughness for topographic analysis. Geosciences, 9(7) 322. DOI: 10.3390/geosciences9070322.
See Also: CircularVarianceOfAspect, MultiscaleRoughness, EdgeDensity, SurfaceAreaRatio, RuggednessIndex
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--output | Output raster file |
--filter | Size of the filter kernel |
Python function:
wbt.spherical_std_dev_of_normals(
dem,
output,
filter=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=SphericalStdDevOfNormals -v ^
--wd="/path/to/data/" --dem=DEM.tif --output=roughness.tif ^
--filter=15
Author: Dr. John Lindsay
Created: 22/05/2019
Last Modified: 03/09/2020
StandardDeviationOfSlope
Calculates the standard deviation of slope from an input DEM, a metric of roughness described by Grohmann et al., (2011).
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster DEM file |
-o, --output | Output raster DEM file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.standard_deviation_of_slope(
i,
output,
zfactor=None,
filterx=11,
filtery=11,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=StandardDeviationOfSlope -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif ^
--zfactor=1.0 --filterx=15 --filtery=15
Author: Anthony Francioni
Created: 26/05/2018
Last Modified: 03/09/2020
StreamPowerIndex
This tool can be used to calculate the relative stream power (RSP) index. This index is directly related
to the stream power if the assumption can be made that discharge is directly proportional to upslope
contributing area (As; --sca
). The index is calculated as:
RSP = Asp × tan(β)
where As is the specific catchment area (i.e. the upslope contributing area per unit
contour length) estimated using one of the available flow accumulation algorithms; β is the local
slope gradient in degrees (--slope
); and, p (--exponent
) is a user-defined exponent term that
controls the location-specific relation between contributing area and discharge. Notice that
As must not be log-transformed prior to being used; As is commonly
log-transformed to enhance visualization of the data. The slope raster can be created from the base
digital elevation model (DEM) using the Slope tool. The input images must have the same grid dimensions.
Reference:
Moore, I. D., Grayson, R. B., and Ladson, A. R. (1991). Digital terrain modelling: a review of hydrological, geomorphological, and biological applications. Hydrological processes, 5(1), 3-30.
See Also: SedimentTransportIndex, Slope, D8FlowAccumulation DInfFlowAccumulation, FD8FlowAccumulation
Parameters:
Flag | Description |
---|---|
--sca | Input raster specific contributing area (SCA) file |
--slope | Input raster slope file |
-o, --output | Output raster file |
--exponent | SCA exponent value |
Python function:
wbt.stream_power_index(
sca,
slope,
output,
exponent=1.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=StreamPowerIndex -v ^
--wd="/path/to/data/" --sca='flow_accum.tif' ^
--slope='slope.tif' -o=output.tif --exponent=1.1
Author: Dr. John Lindsay
Created: 02/07/2017
Last Modified: 30/01/2020
SurfaceAreaRatio
This tool calculates the ratio between the surface area and planar area of grid cells within digital elevation models (DEMs). The tool uses the method of Jenness (2004) to estimate the surface area of a DEM grid cell based on the elevations contained within the 3 x 3 neighbourhood surrounding each cell. The surface area ratio has a lower bound of 1.0 for perfectly flat grid cells and is greater than 1.0 for other conditions. In particular, surface area ratio is a measure of neighbourhood surface shape complexity (texture) and elevation variability (local slope).
Reference:
Jenness, J. S. (2004). Calculating landscape surface area from digital elevation models. Wildlife Society Bulletin, 32(3), 829-839.
See Also: RuggednessIndex, MultiscaleRoughness, CircularVarianceOfAspect, EdgeDensity
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
Python function:
wbt.surface_area_ratio(
dem,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=SurfaceAreaRatio -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 23/01/2019
Last Modified: 23/01/2019
TangentialCurvature
This tool calculates the tangential curvature, which is the curvature of an inclined plan perpendicular
to both the direction of flow and the surface (Gallant and Wilson, 2000). Curvature is a second
derivative of the topographic surface defined by a digital elevation model (DEM). The user must specify
the name of the input DEM (--dem
) and the output raster image (--output
). The output reports curvature
in degrees multiplied by 100 for easier interpretation, as curvature values are often very small. The Z
Conversion Factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. If the DEM is in the geographic coordinate system (latitude and longitude), with
XY units measured in degrees, an appropriate Z Conversion Factor is calculated internally based on
site latitude.
Reference:
Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, in Terrain Analysis: Principles and Applications, edited by J. P. Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.
PlanCurvature, ProfileCurvature, TotalCurvature, Slope, Aspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.tangential_curvature(
dem,
output,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=TangentialCurvature -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 01/03/2021
TimeInDaylight
This tool calculates the proportion of time a location is within daylight. That is, it calculates the
proportion of time, during a user-defined time frame, that a grid cell in an input digital elevation
model (--dem
) is outside of an area of shadow cast by a local object. The input DEM should truly be
a digital surface model (DSM) that contains significant off-terrain objects. Such a model, for example,
could be created using the first-return points of a LiDAR data set, or using the LidarDigitalSurfaceModel
tool.
The tool operates by calculating a solar almanac, which estimates the sun's position for the location, in
latitude and longitude coordinate (--lat
, --long
), of the input DSM. The algorithm then calculates
horizon angle (see HorizonAngle) rasters from the DSM based on the user-specified azimuth fraction (--az_fraction
).
For example, if an azimuth fraction of 15-degrees is specified, horizon angle rasters could be calculated for
the solar azimuths 0, 15, 30, 45... In reality, horizon angle rasters are only calculated for azimuths for which
the sun is above the horizon for some time during the tested time period. A horizon angle raster evaluates
the vertical angle between each grid cell in a DSM and a distant obstacle (e.g. a mountain ridge, building, tree, etc.) that
blocks the view along a specified direction. In calculating horizon angle, the user must specify the maximum search
distance (--max_dist
) beyond which the query for higher, more distant objects will cease. This parameter strongly
impacts the performance of the tool, with larger values resulting in significantly longer run-times. Users are advised
to set the --max_dist
based on the maximum shadow length expected in an area. For example, in a relatively flat
urban landscape, the tallest building will likely determine the longest shadow lengths. All grid cells for which the
calculated solar positions throughout the time frame are higher than the cell's horizon angle are deemed to be
illuminated during the time the sun is in the corresponding azimuth fraction.
By default, the tool calculates time-in-daylight for a time-frame spanning an entire year. That is, the solar almanac
is calculated for each hour, at 10-second intervals, and for each day of the year. Users may alternatively restrict the
time of year over which time-in-daylight is calculated by specifying a starting day (1-365; --start_day
) and ending day
(1-365; --end_day
). Similarly, by specifying start time (--start_time
) and end time (--end_time
) parameters,
the user is able to measure time-in-daylight for specific ranges of the day (e.g. for the morning or afternoon hours).
These time parameters must be specified in 24-hour time (HH:MM:SS), e.g. 15:30:00. sunrise
and sunset
are also
acceptable inputs for the start time and end time respectively. The timing of sunrise and sunset on each day in the
tested time-frame will be determined using the solar almanac.
See Also: LidarDigitalSurfaceModel, HorizonAngle
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--az_fraction | Azimuth fraction in degrees |
--max_dist | Optional maximum search distance. Minimum value is 5 x cell size |
--lat | Centre point latitude |
--long | Centre point longitude |
--utc_offset | UTC time offset, in hours (e.g. -04:00, +06:00) |
--start_day | Start day of the year (1-365) |
--end_day | End day of the year (1-365) |
--start_time | Starting hour to track shadows (e.g. 5, 5:00, 05:00:00). Assumes 24-hour time: HH:MM:SS. 'sunrise' is also a valid time |
--end_time | Starting hour to track shadows (e.g. 21, 21:00, 21:00:00). Assumes 24-hour time: HH:MM:SS. 'sunset' is also a valid time |
Python function:
wbt.time_in_daylight(
dem,
output,
lat,
long,
az_fraction=10.0,
max_dist=100.0,
utc_offset="00:00",
start_day=1,
end_day=365,
start_time="00:00:00",
end_time="23:59:59",
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=TimeInDaylight -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif --az_fraction=15.0 ^
--max_dist=100.0 --lat=43.545 --long= -80.248
Author: Dr. John Lindsay
Created: 29/07/2020
Last Modified: 03/09/2020
TopographicPositionAnimation
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool creates an interactive animation that demonstrates the variation in deviation from mean
elevation (DEV, DevFromMeanElev) as scale increases across a range for an input digital elevation
model (--input
). DEV is calculated as the difference between the elevation of each grid cell and the
mean elevation of the centering local neighbourhood, normalized by standard deviation and is a measure
of local topographic position. DEV is useful for highlighting locally prominent (either elevated or
low-lying) locations within a landscape. Topographic position animations are extemely useful for
interpreting landscape geomorphic structure across a range of scales.
The set of scales for which DEV is measured (using varying filter sizes) is determined by the three
user-specified parameters, including --min_scale
, --num_steps
, and --step_nonlinearity
. Experience
with DEV scale signatures has shown that it is highly variable at shorter scales and changes more
gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to
ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested
scales, such that:
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.
See Also: DevFromMeanElev, MaxElevationDeviation
Parameters:
Flag | Description |
---|---|
-i, --input | Name of the input digital elevation model (DEM) raster file |
-p, --palette | Image palette; options are 'bl_yl_rd', 'bl_w_rd', 'purple', 'gn_yl', 'pi_y_g', and 'viridi' |
-o, --output | Name of the output HTML file (*.html) |
--min_scale | Minimum search neighbourhood radius in grid cells |
--num_steps | Number of steps |
--step_nonlinearity | Step nonlinearity factor (1.0-2.0 is typical) |
--height | Image height, in pixels |
--delay | GIF time delay in milliseconds |
-l, --label | Label text (leave blank for none) |
--dev_max | Do you want to use DEVmax instead of DEV for measuring local topographic position? |
Python function:
wbt.topographic_position_animation(
i,
output,
palette="bl_yl_rd",
min_scale=1,
num_steps=100,
step_nonlinearity=1.5,
height=600,
delay=250,
label="",
dev_max=False,
callback=default_callback
)
Command-line Interface:
>> ./whitebox_tools -r=TopographicPositionAnimation -i=dem.tif ^
-p='bl_w_rd' -o=DEV_animation.html --min_scale=3 ^
--num_steps=100 --step_nonlinearity=1.2 --height=620 ^
--delay=200 --label='DEVmax for Catfish Watershed' --dev_max
Source code is unavailable due to proprietary license.
Author: Whitebox Geospatial Inc. (c)
Created: 06/05/2021
Last Modified: 06/05/2021
TotalCurvature
This tool calculates the total curvature, which measures the curvature of the topographic surface rather
than the curvature of a line across the surface in some direction (Gallant and Wilson, 2000). Total
curvature can be positive or negative, with zero curvature indicating that the surface is either flat
or the convexity in one direction is balanced by the concavity in another direction, as would occur at
a saddle point. Curvature is a second derivative of the topographic surface defined by a digital elevation
model (DEM). The user must specify the name of the input DEM (--dem
) and the output raster image (--output
). The output reports curvature
in degrees multiplied by 100 for easier interpretation, as curvature values are often very small. The Z
Conversion Factor (--zfactor
) is only important when the vertical and horizontal units are not the
same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the
Z Conversion Factor. If the DEM is in the geographic coordinate system (latitude and longitude), with
XY units measured in degrees, an appropriate Z Conversion Factor is calculated internally based on
site latitude.
Reference:
Gallant, J. C., and J. P. Wilson, 2000, Primary topographic attributes, in Terrain Analysis: Principles and Applications, edited by J. P. Wilson and J. C. Gallant pp. 51-86, John Wiley, Hoboken, N.J.
PlanCurvature, ProfileCurvature, TangentialCurvature, Slope, Aspect
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--zfactor | Optional multiplier for when the vertical and horizontal units are not the same |
Python function:
wbt.total_curvature(
dem,
output,
zfactor=None,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=TotalCurvature -v --wd="/path/to/data/" ^
--dem=DEM.tif -o=output.tif
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 03/09/2020
Viewshed
This tool can be used to calculate the viewshed (i.e. the visible area) from a
location (i.e. viewing station) or group of locations based on the topography defined
by an input digital elevation model (DEM). The user must specify the name of the input
DEM (--dem
), a viewing station input vector file (--stations
), the output file name
(--output
), and the viewing height (--height
).
Viewing station locations are specified as points within an input shapefile. The output
image indicates the number of stations visible from each grid cell. The viewing height
is in the same units as the elevations of the DEM and represent a height above the ground
elevation from which the viewshed is calculated.
Viewshed should be used when there are a relatively small number of target sites for which visibility needs to be assessed. If you need to assess general landscape visibility as a land-surface parameter, the VisibilityIndex tool should be used instead.
Viewshed analysis is a very computationally intensive task. Depending on the size of the input DEM grid and the number of viewing stations, this operation may take considerable time to complete. Also, this implementation of the viewshed algorithm does not account for the curvature of the Earth. This should be accounted for if viewsheds are being calculated over very extensive areas.
See Also: VisibilityIndex
Parameters:
Flag | Description |
---|---|
--dem | Input raster DEM file |
--stations | Input viewing station vector file |
-o, --output | Output raster file |
--height | Viewing station height, in z units |
Python function:
wbt.viewshed(
dem,
stations,
output,
height=2.0,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=Viewshed -v --wd="/path/to/data/" ^
--dem='dem.tif' --stations='stations.shp' -o=output.tif ^
--height=10.0
Author: Dr. John Lindsay
Created: 10/01/2018
Last Modified: 12/10/2018
VisibilityIndex
This tool can be used to calculate a measure of landscape visibility based on the
topography of an input digital elevation model (DEM). The user must specify the name of
the input DEM (--dem
), the output file name (--output
), the viewing height (--height
),
and a resolution factor (--res_factor
).
Viewsheds are calcuated for a subset of grid cells in the DEM based on the resolution
factor. The visibility index value (0.0-1.0) indicates the proportion of tested stations
(determined by the resolution factor) that each cell is visible from. The viewing height
is in the same units as the elevations of the DEM and represent a height above the ground
elevation. Each tested grid cell's viewshed will be calculated in parallel. However, visibility
index is one of the most computationally intensive geomorphometric indices to calculate.
Depending on the size of the input DEM grid and the resolution factor, this operation may take
considerable time to complete. If the task is too long-running, it is advisable to raise the
resolution factor. A resolution factor of 2 will skip every second row and every second column
(effectively evaluating the viewsheds of a quarter of the DEM's grid cells). Increasing this
value decreases the number of calculated viewshed but will result in a lower accuracy estimate
of overall visibility. In addition to the high computational costs of this index, the tool
also requires substantial memory resources to operate. Each of these limitations should be
considered before running this tool on a particular data set. This tool is best to apply
on computer systems with high core-counts and plenty of memory.
See Also: Viewshed
Parameters:
Flag | Description |
---|---|
--dem | Input raster DEM file |
-o, --output | Output raster file |
--height | Viewing station height, in z units |
--res_factor | The resolution factor determines the density of measured viewsheds |
Python function:
wbt.visibility_index(
dem,
output,
height=2.0,
res_factor=2,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=VisibilityIndex -v ^
--wd="/path/to/data/" --dem=dem.tif -o=output.tif ^
--height=10.0 --res_factor=4
Author: Dr. John Lindsay
Created: 07/04/2018
Last Modified: 12/10/2018
WetnessIndex
This tool can be used to calculate the topographic wetness index, commonly used in the TOPMODEL rainfall-runoff framework. The index describes the propensity for a site to be saturated to the surface given its contributing area and local slope characteristics. It is calculated as:
WI = Ln(As / tan(Slope))
Where As
is the specific catchment area (i.e. the upslope contributing area per unit contour length) estimated using one of
the available flow accumulation algorithms in the Hydrological Analysis toolbox. Notice that As
must not be log-transformed
prior to being used; log-transformation of As
is a common practice when visualizing the data. The slope image should be
measured in degrees and can be created from the base digital elevation model (DEM) using the Slope tool. Grid cells with a
slope of zero will be assigned NoData in the output image to compensate for the fact that division by zero is infinity.
These very flat sites likely coincide with the wettest parts of the landscape. The input images must have the same grid dimensions.
Grid cells possessing the NoData value in either of the input images are assigned NoData value in the output image. The output raster is of the float data type and continuous data scale.
See Also Slope, D8FlowAccumulation, DInfFlowAccumulation, FD8FlowAccumulation, BreachDepressionsLeastCost
Parameters:
Flag | Description |
---|---|
--sca | Input raster specific contributing area (SCA) file |
--slope | Input raster slope file (in degrees) |
-o, --output | Output raster file |
Python function:
wbt.wetness_index(
sca,
slope,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=WetnessIndex -v --wd="/path/to/data/" ^
--sca='flow_accum.tif' --slope='slope.tif' -o=output.tif
Author: Dr. John Lindsay
Created: 02/07/2017
Last Modified: 21/01/2018
GIS Analysis
- AggregateRaster
- BlockMaximumGridding
- BlockMinimumGridding
- Centroid
- CentroidVector
- Clump
- ConstructVectorTin
- CreateHexagonalVectorGrid
- CreatePlane
- CreateRectangularVectorGrid
- Dissolve
- EliminateCoincidentPoints
- ExtendVectorLines
- ExtractNodes
- ExtractRasterValuesAtPoints
- FilterRasterFeaturesByArea
- FindLowestOrHighestPoints
- IdwInterpolation
- LayerFootprint
- Medoid
- MinimumBoundingBox
- MinimumBoundingCircle
- MinimumBoundingEnvelope
- MinimumConvexHull
- NaturalNeighbourInterpolation
- NearestNeighbourGridding
- PolygonArea
- PolygonLongAxis
- PolygonPerimeter
- PolygonShortAxis
- RadialBasisFunctionInterpolation
- RasterArea
- RasterCellAssignment
- RasterPerimeter
- Reclass
- ReclassEqualInterval
- ReclassFromFile
- SmoothVectors
- SplitVectorLines
- TinGridding
- VectorHexBinning
- VoronoiDiagram
AggregateRaster
This tool can be used to reduce the grid resolution of a raster by a user specified amount. For example, using
an aggregation factor (--agg_factor
) of 2 would result in a raster with half the number of rows and columns.
The grid cell values (--type
) in the output image will consist of the mean, sum, maximum, minimum, or range
of the overlapping grid cells in the input raster (four cells in the case of an aggregation factor of 2).
See Also: Resample
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--agg_factor | Aggregation factor, in pixels |
--type | Statistic 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
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:
Flag | Description |
---|---|
-i, --input | Input vector Points file |
--field | Input field name in attribute table |
--use_z | Use z-coordinate instead of field? |
-o, --output | Output raster file |
--cell_size | Optionally specified cell size of output raster. Not used when base raster is specified |
--base | Optionally 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
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:
Flag | Description |
---|---|
-i, --input | Input vector Points file |
--field | Input field name in attribute table |
--use_z | Use z-coordinate instead of field? |
-o, --output | Output raster file |
--cell_size | Optionally specified cell size of output raster. Not used when base raster is specified |
--base | Optionally 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--text_output | Optional 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
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.
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--diag | Flag indicating whether diagonal connections should be considered |
--zero_back | Flag 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
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:
Flag | Description |
---|---|
-i, --input | Input vector points file |
--field | Input field name in attribute table |
--use_z | Use the 'z' dimension of the Shapefile's geometry instead of an attribute field? |
-o, --output | Output vector polygon file |
--max_triangle_edge_length | Optional 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
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:
Flag | Description |
---|---|
-i, --base, --input | Input base file |
-o, --output | Output vector polygon file |
--width | The grid cell width |
--orientation | Grid 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
Author: Dr. John Lindsay
Created: 15/09/2018
Last Modified: 19/05/2020
CreatePlane
This tool can be used to create a new raster with values that are determined by the equation of a simple plane. The user
must specify the name of a base raster (--base
) from which the output raster coordinate and dimensional information
will be taken. In addition the user must specify the values of the planar slope gradient (S; --gradient
; --aspect
)
in degrees, the planar slope direction or aspect (A; 0 to 360 degrees), and an constant value (k; --constant
). The
equation of the plane is as follows:
Z = tan(S) × sin(A - 180) × X + tan(S) × cos(A - 180) × Y + k
where X and Y are the X and Y coordinates of each grid cell in the grid. Notice that A is the direction, or azimuth, that the plane is facing
Parameters:
Flag | Description |
---|---|
--base | Input base raster file |
-o, --output | Output raster file |
--gradient | Slope gradient in degrees (-85.0 to 85.0) |
--aspect | Aspect (direction) in degrees clockwise from north (0.0-360.0) |
--constant | Constant 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
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:
Flag | Description |
---|---|
-i, --base, --input | Input base file |
-o, --output | Output vector polygon file |
--width | The grid cell width |
--height | The grid cell height |
--xorig | The grid origin x-coordinate |
--yorig | The 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
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:
Flag | Description |
---|---|
-i, --input | Input vector file |
--field | Dissolve field attribute (optional) |
-o, --output | Output vector file |
--snap | Snap 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
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:
Flag | Description |
---|---|
-i, --input | Input vector file |
-o, --output | Output vector polygon file |
--tolerance | The 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
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:
Flag | Description |
---|---|
-i, --input | Input vector polyline file |
-o, --output | Output vector polyline file |
--dist | The distance to extend |
--extend | Extend 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'
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:
Flag | Description |
---|---|
-i, --input | Input vector lines or polygon file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
--points | Input vector points file |
--out_text | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--threshold | Remove features with fewer grid cells than this threshold value |
--background | Background 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output vector points file |
--out_type | Output 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
Author: Dr. John Lindsay
Created: 12/06/2018
Last Modified: 13/10/2018
IdwInterpolation
points or a fixed neighbourhood size. This tool is currently configured to perform the later only, using a FixedRadiusSearch structure. Using a fixed number of neighbours will require use of a KD-tree structure. I've been testing one Rust KD-tree library but its performance does not appear to be satisfactory compared to the FixedRadiusSearch. I will need to explore other options here.
Another change that will need to be implemented is the use of a nodal function. The original Whitebox GAT tool allows for use of a constant or a quadratic. This tool only allows the former. This tool interpolates vector points into a raster surface using an inverse-distance weighted scheme.
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector Points file |
--field | Input field name in attribute table |
--use_z | Use z-coordinate instead of field? |
-o, --output | Output raster file |
--weight | IDW weight value |
--radius | Search Radius in map units |
--min_points | Minimum number of points |
--cell_size | Optionally specified cell size of output raster. Not used when base raster is specified |
--base | Optionally 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
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:
Flag | Description |
---|---|
-i, --input | Input raster or vector file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 31/09/2018
Last Modified: 13/10/2018
Medoid
This tool calculates the medoid for a series of vector features contained in a shapefile. The medoid of a two-dimensional feature is conceptually similar its centroid, or mean position, but the medoid is always a members of the input feature data set. Thus, the medoid is a measure of central tendency that is robust in the presence of outliers. If the input vector is of a POLYLINE or POLYGON ShapeType, the nodes of each feature will be used to estimate the feature medoid. If the input vector is of a POINT base ShapeType, the medoid will be calculated for the collection of points. While there are more than one competing method of calculating the medoid, this tool uses an algorithm that works as follows:
- The x-coordinate and y-coordinate of each point/node are placed into two arrays.
- The x- and y-coordinate arrays are then sorted and the median x-coordinate (Med X) and median y-coordinate (Med Y) are calculated.
- The point/node in the dataset that is nearest the point (Med X, Med Y) is identified as the medoid.
See Also: CentroidVector
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input vector file |
-o, --output | Output vector polygon file |
--criterion | Minimization criterion; options include 'area' (default), 'length', 'width', and 'perimeter' |
--features | Find 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
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:
Flag | Description |
---|---|
-i, --input | Input vector file |
-o, --output | Output vector polygon file |
--features | Find 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
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:
Flag | Description |
---|---|
-i, --input | Input vector file |
-o, --output | Output vector polygon file |
--features | Find 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
Author: Dr. John Lindsay
Created: 31/09/2018
Last Modified: 18/10/2019
MinimumConvexHull
This tool creates a vector convex polygon around vector features. The convex hull is a convex closure of a set of points or polygon verticies and can be may be conceptualized as the shape enclosed by a rubber band stretched around the point set. The convex hull has many applications and is most notably used in various shape indices. The Delaunay triangulation of a point set and its dual, the Voronoi diagram, are mathematically related to convex hulls.
See Also: MinimumBoundingBox, MinimumBoundingCircle, MinimumBoundingEnvelope
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector file |
-o, --output | Output vector polygon file |
--features | Find 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
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:
Flag | Description |
---|---|
-i, --input | Input vector points file |
--field | Input field name in attribute table |
--use_z | Use the 'z' dimension of the Shapefile's geometry instead of an attribute field? |
-o, --output | Output raster file |
--cell_size | Optionally specified cell size of output raster. Not used when base raster is specified |
--base | Optionally specified input base raster file. Not used when a cell size is specified |
--clip | Clip 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
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:
Flag | Description |
---|---|
-i, --input | Input vector Points file |
--field | Input field name in attribute table |
--use_z | Use z-coordinate instead of field? |
-o, --output | Output raster file |
--cell_size | Optionally specified cell size of output raster. Not used when base raster is specified |
--base | Optionally specified input base raster file. Not used when a cell size is specified |
--max_dist | Maximum 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input vector polygons file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input vector polygons file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input vector points file |
--field | Input field name in attribute table |
--use_z | Use z-coordinate instead of field? |
-o, --output | Output raster file |
--radius | Search Radius (in map units) |
--min_points | Minimum number of points |
--func_type | Radial basis function type; options are 'ThinPlateSpline' (default), 'PolyHarmonic', 'Gaussian', 'MultiQuadric', 'InverseMultiQuadric' |
--poly_order | Polynomial order; options are 'none' (default), 'constant', 'affine' |
--weight | Weight parameter used in basis function |
--cell_size | Optionally specified cell size of output raster. Not used when base raster is specified |
--base | Optionally 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--out_text | Would you like to output polygon areas to text? |
--units | Area units; options include 'grid cells' and 'map units' |
--zero_back | Flag 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
-a, --assign | Which 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'
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--out_text | Would you like to output polygon areas to text? |
--units | Area units; options include 'grid cells' and 'map units' |
--zero_back | Flag 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--reclass_vals | Reclassification triplet values (new value; from value; to less than), e.g. '0.0;0.0;1.0;1.0;1.0;2.0' |
--assign_mode | Optional 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
Author: Dr. John Lindsay
Created: 09/09/2017
Last Modified: 13/02/2020
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--interval | Class interval size |
--start_val | Optional starting value (default is input minimum value) |
--end_val | Optional 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
--reclass_file | Input text file containing reclass ranges |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input vector POLYLINE or POLYGON file |
-o, --output | Output vector file |
--filter | The 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
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:
Flag | Description |
---|---|
-i, --input | Name of the input lines shapefile |
-o, --output | Name of the output lines shapefile |
--length | Maximum 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](https://github.com/jblindsay/whitebox-tools/blob/master/Splitvectorlines
thread 'main' panicked at 'Unrecognized tool name Splitvectorlines.', whitebox-tools-app/src/main.rs:72:21
note: run with RUST_BACKTRACE=1
environment variable to display a backtrace
)
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:
Flag | Description |
---|---|
-i, --input | Input vector points file |
--field | Input field name in attribute table |
--use_z | Use the 'z' dimension of the Shapefile's geometry instead of an attribute field? |
-o, --output | Output raster file |
--resolution | Output raster's grid resolution |
--base | Optionally specified input base raster file. Not used when a cell size is specified |
--max_triangle_edge_length | Optional 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
Author: Dr. John Lindsay
Created: 23/09/2018
Last Modified: 18/10/2019
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:
Flag | Description |
---|---|
-i, --input | Input base file |
-o, --output | Output vector polygon file |
--width | The grid cell width |
--orientation | Grid 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
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 tesselate 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:
Flag | Description |
---|---|
-i, --input | Input vector points file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--size | Buffer size |
--gridcells | Optional 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
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:
Flag | Description |
---|---|
--source | Input source raster file |
--backlink | Input backlink raster file generated by the cost-distance tool |
-o, --output | Output 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'
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:
Flag | Description |
---|---|
--source | Input source raster file |
--cost | Input cost (friction) raster file |
--out_accum | Output cost accumulation raster file |
--out_backlink | Output 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
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:
Flag | Description |
---|---|
--destination | Input destination raster file |
--backlink | Input backlink raster file generated by the cost-distance tool |
-o, --output | Output cost pathway raster file |
--zero_background | Flag 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 05/12/2019
GIS Analysis → Overlay Tools
- AverageOverlay
- Clip
- ClipRasterToPolygon
- CountIf
- Difference
- Erase
- ErasePolygonFromRaster
- HighestPosition
- Intersect
- LineIntersections
- LowestPosition
- MaxAbsoluteOverlay
- MaxOverlay
- MergeLineSegments
- MinAbsoluteOverlay
- MinOverlay
- PercentEqualTo
- PercentGreaterThan
- PercentLessThan
- PickFromList
- Polygonize
- SplitWithLines
- SumOverlay
- SymmetricalDifference
- Union
- UpdateNodataCells
- WeightedOverlay
- WeightedSum
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input vector file |
--clip | Input clip polygon vector file |
-o, --output | Output 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
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
), wich 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:
Flag | Description |
---|---|
-i, --input | Input raster file |
--polygons | Input vector polygons file |
-o, --output | Output raster file |
--maintain_dimensions | Maintain 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
Author: Dr. John Lindsay
Created: 25/04/2018
Last Modified: 18/10/2019
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 cooresponding 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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output raster file |
--value | Search 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
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
ouptut feature indentifier (FID
) attribute. Also, note that depending on the
ShapeType (polylines and polygons), Measure
and Z
ShapeDimension data will not
be transfered 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:
Flag | Description |
---|---|
-i, --input | Input vector file |
--overlay | Input overlay vector file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input vector file |
--erase | Input erase polygon vector file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
--polygons | Input vector polygons file |
-o, --output | Output 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'
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output 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
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 ouptut feature indentifier (FID
) attribute. Also, note that depending
on the ShapeType (polylines and polygons), Measure
and Z
ShapeDimension data will not
be transfered 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:
Flag | Description |
---|---|
-i, --input | Input vector file |
--overlay | Input overlay vector file |
-o, --output | Output vector file |
--snap | Snap 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
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 FID
s) of the two parent line features.
Parameters:
Flag | Description |
---|---|
--i1, --input1 | Input vector polyline file |
--i2, --input2 | Input vector polyline file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input vector file |
-o, --output | Output vector file |
--snap | Snap 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
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 13/10/2018
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
--comparison | Input comparison raster file |
-o, --output | Output 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'
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
--comparison | Input comparison raster file |
-o, --output | Output 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'
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
--comparison | Input comparison raster file |
-o, --output | Output 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'
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
--pos_input | Input position raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --inputs | Input vector polyline file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input vector line or polygon file |
--split | Input vector polyline file |
-o, --output | Output 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
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
Parameters:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output 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
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
ouptut feature indentifier (FID
) attribute. Also, note that depending on the
ShapeType (polylines and polygons), Measure
and Z
ShapeDimension data will not
be transfered 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:
Flag | Description |
---|---|
-i, --input | Input vector file |
--overlay | Input overlay vector file |
-o, --output | Output vector file |
--snap | Snap 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
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
ouptut feature indentifier (FID
) attribute. Also, note that depending on the
ShapeType (polylines and polygons), Measure
and Z
ShapeDimension data will not
be transfered 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:
Flag | Description |
---|---|
-i, --input | Input vector file |
--overlay | Input overlay vector file |
-o, --output | Output vector file |
--snap | Snap 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
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:
Flag | Description |
---|---|
--input1 | Input raster file 1 |
--input2 | Input raster file 2; update layer |
-o, --output | Output 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
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:
Flag | Description |
---|---|
--factors | Input factor raster files |
-w, --weights | Weight values, contained in quotes and separated by commas or semicolons. Must have the same number as factors |
--cost | Weight values, contained in quotes and separated by commas or semicolons. Must have the same number as factors |
--constraints | Input constraints raster files |
-o, --output | Output raster file |
--scale_max | Suitability 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
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-w, --weights | Weight values, contained in quotes and separated by commas or semicolons |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 13/10/2018
GIS Analysis → Patch Shape Tools
- BoundaryShapeComplexity
- CompactnessRatio
- EdgeProportion
- ElongationRatio
- FindPatchOrClassEdgeCells
- HoleProportion
- LinearityIndex
- NarrownessIndex
- PatchOrientation
- PerimeterAreaRatio
- RadiusOfGyration
- RelatedCircumscribingCircle
- ShapeComplexityIndex
- ShapeComplexityIndexRaster
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 identifers. Identifer values should be
positive, non-zero whole numbers.
See Also: ShapeComplexityIndexRaster, LineThinning
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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 identifers. Identifer values must be positive, non-zero whole numbers.
See Also: ShapeComplexityIndexRaster, LinearityIndex, ElongationRatio
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--output_text | flag 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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 patche 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 identifers. Identifer values must
be positive, non-zero whole numbers.
See Also: LinearityIndex, ElongationRatio
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--text_output | Optional 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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 numberous
holes or are winding in shape, will have higher index values. Objects in the input raster (--input
) are
designated by their unique identifers. Identifer values should be positive, non-zero whole numbers.
See Also: ShapeComplexityIndex, BoundaryShapeComplexity
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 16/02/2019
Last Modified: 16/02/2019
Hydrological Analysis
- AverageFlowpathSlope
- AverageUpslopeFlowpathLength
- Basins
- BreachDepressions
- BreachDepressionsLeastCost
- BreachSingleCellPits
- BurnStreamsAtRoads
- D8FlowAccumulation
- D8MassFlux
- D8Pointer
- DInfFlowAccumulation
- DInfMassFlux
- DInfPointer
- DepthInSink
- DownslopeDistanceToStream
- DownslopeFlowpathLength
- ElevationAboveStream
- ElevationAboveStreamEuclidean
- Fd8FlowAccumulation
- Fd8Pointer
- FillBurn
- FillDepressions
- FillDepressionsPlanchonAndDarboux
- FillDepressionsWangAndLiu
- FillSingleCellPits
- FindNoFlowCells
- FindParallelFlow
- FlattenLakes
- FloodOrder
- FlowAccumulationFullWorkflow
- FlowLengthDiff
- Hillslopes
- ImpoundmentSizeIndex
- InsertDams
- Isobasins
- JensonSnapPourPoints
- LongestFlowpath
- LowPointsOnHeadwaterDivides
- MaxUpslopeFlowpathLength
- MdInfFlowAccumulation
- NumInflowingNeighbours
- RaiseWalls
- Rho8Pointer
- Sink
- SnapPourPoints
- StochasticDepressionAnalysis
- StrahlerOrderBasins
- Subbasins
- TraceDownslopeFlowpaths
- UnnestBasins
- UpslopeDepressionStorage
- Watershed
AverageFlowpathSlope
This tool calculates the average slope gradient (i.e. slope steepness in degrees) of the flowpaths that
pass through each grid cell in an input digital elevation model (DEM). The user must specify the name of
a DEM raster (--dem
). It is important that this DEM is pre-processed to remove all topographic depressions and
flat areas using a tool such as BreachDepressions. Several intermediate rasters are created and stored in
memory during the operation of this tool, which may limit the size of DEM that can be processed, depending
on available system resources.
See Also: AverageUpslopeFlowpathLength, BreachDepressions
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
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:
. | . | . |
---|---|---|
64 | 128 | 1 |
32 | 0 | 2 |
16 | 8 | 4 |
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:
Flag | Description |
---|---|
--d8_pntr | Input raster D8 pointer file |
-o, --output | Output raster file |
--esri_pntr | D8 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'
Author: Dr. John Lindsay
Created: 01/07/2017
Last Modified: 18/10/2019
BreachDepressions
This tool can be used to remove the depressions in a digital elevation model (DEM), a common requirement of spatial hydrological operations such as flow accumulation and watershed modelling. The tool based on on the efficient hybrid depression breaching algorithm described by Lindsay (2016). It uses a breach-first, fill-second approach to resolving continous flowpaths through depressions.
Notice that when the input DEM (--dem
) contains deep, single-cell pits, it can be useful
to raise the pits elevation to that of the lowest neighbour (--fill_pits
), to avoid the
creation of deep breach trenches. Deep pits can be common in DEMs containing speckle-type noise.
This option, however, does add slightly to the computation time of the tool.
The user may optionally (--flat_increment
) override the default value applied to increment elevations on
flat areas (often formed by the subsequent depression filling operation). The default value is
dependent upon the elevation range in the input DEM and is generally a very small elevation value (e.g.
0.001). It may be necessary to override the default elevation increment value in landscapes where there
are extensive flat areas resulting from depression filling (and along breach channels). Values in the range
0.00001 to 0.01 are generally appropriate. increment values that are too large can result in obvious artifacts
along flattened sites, which may extend beyond the flats, and values that are too small (i.e. smaller than the
numerical precision) may result in the presence of grid cells with no downslope neighbour in the
output DEM. The output DEM will always use 64-bit floating point values for storing elevations because of
the need to precisely represent small elevation differences along flats. Therefore, if the input DEM is stored
at a lower level of precision (e.g. 32-bit floating point elevations), this may result in a doubling of
the size of the DEM.
In comparison with the BreachDepressionsLeastCost tool, this breaching method often provides a less satisfactory, higher impact, breaching solution and is often less efficient. It has been provided to users for legacy reasons and it is advisable that users try the BreachDepressionsLeastCost tool to remove depressions from their DEMs first. The BreachDepressionsLeastCost tool is particularly well suited to breaching through road embankments. Nonetheless, there are applications for which full depression filling using the FillDepressions tool may be preferred.
Reference:
Lindsay JB. 2016. Efficient hybrid breaching-filling sink removal methods for flow path enforcement in digital elevation models. Hydrological Processes, 30(6): 846–857. DOI: 10.1002/hyp.10648
See Also: BreachDepressionsLeastCost, FillDepressions, FillSingleCellPits
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--max_depth | Optional maximum breach depth (default is Inf) |
--max_length | Optional maximum breach channel length (in grid cells; default is Inf) |
--flat_increment | Optional elevation increment applied to flat areas |
--fill_pits | Optional 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
Author: Dr. John Lindsay
Created: 28/06/2017
Last Modified: 24/11/2019
BreachDepressionsLeastCost
This tool can be used to perform a type of optimal depression breaching to prepare a digital elevation model (DEM) for hydrological analysis. Depression breaching is a common alternative to depression filling (FillDepressions) and often offers a lower-impact solution to the removal of topographic depressions. This tool implements a method that is loosely based on the algorithm described by Lindsay and Dhun (2015), furthering the earlier algorithm with efficiency optimizations and other significant enhancements. The approach uses a least-cost path analysis to identify the breach channel that connects pit cells (i.e. grid cells for which there is no lower neighbour) to some distant lower cell. Here, the cost of a breach path is determined by the amount of elevation lowering needed to cut the breach channel through the surrounding topography.
The user must specify the name of the input DEM file (--dem
), the output breached DEM
file (--output
), the maximum search window radius (--radius
), the optional maximum breach
cost (--max_cost
), and an optional flat height increment value (--flat_increment
). Notice that if the
--flat_increment
parameter is not specified, the small number used to ensure flow across flats will be
calculated automatically, which should be preferred in most applications of the tool.
The tool operates by performing a least-cost path analysis for each pit cell, radiating outward
until the operation identifies a potential breach destination cell or reaches the maximum breach length parameter.
If a value is specified for the optional --max_cost
parameter, then least-cost breach paths that would require
digging a channel that is more costly than this value will be left unbreached. The flat increment value is used
to ensure that there is a monotonically descending path along breach channels to satisfy the necessary
condition of a downslope gradient for flowpath modelling. It is best for this value to be a small
value. If left unspecified, the tool with determine an appropriate value based on the range of
elevation values in the input DEM, which should be the case in most applications. Notice that the need to specify these very small elevation
increment values is one of the reasons why the output DEM will always be of a 64-bit floating-point
data type, which will often double the storage requirements of a DEM (DEMs are often store with 32-bit
precision). Lastly, the user may optionally choose to apply depression filling (--fill
) on any depressions
that remain unresolved by the earlier depression breaching operation. This filling step uses an efficient
filling method based on flooding depressions from their pit cells until outlets are identified and then
raising the elevations of flooded cells back and away from the outlets.
The tool can be run in two modes, based on whether the --min_dist
is specified. If the --min_dist
flag
is specified, the accumulated cost (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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--dist | Maximum search distance for breach paths in cells |
--max_cost | Optional maximum breach cost (default is Inf) |
--min_dist | Optional flag indicating whether to minimize breach distances |
--flat_increment | Optional elevation increment applied to flat areas |
--fill | Optional 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
--dem | Input raster digital elevation model (DEM) file |
--streams | Input vector streams file |
--roads | Input vector roads file |
-o, --output | Output raster file |
--width | Maximum 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
Author: Dr. John Lindsay
Created: 30/10/2019
Last Modified: 29/12/2019
D8FlowAccumulation
This tool is used to generate a flow accumulation grid (i.e. catchment area) using the
D8 (O'Callaghan and Mark, 1984) algorithm. This algorithm is an example of single-flow-direction
(SFD) method because the flow entering each grid cell is routed to only one downslope neighbour,
i.e. flow divergence is not permitted. The user must specify the name of the input digital
elevation model (DEM) or flow pointer raster (--input
) derived using the D8 or Rho8 method
(D8Pointer, Rho8Pointer). If an input DEM is used, it must have
been hydrologically corrected to remove all spurious depressions and flat areas. DEM pre-processing
is usually achieved using the BreachDepressionsLeastCost or FillDepressions tools. If a D8 pointer
raster is input, the user must also specify the optional --pntr
flag. If the D8 pointer follows
the Esri pointer scheme, rather than the default WhiteboxTools scheme, the user must also specify the
optional --esri_pntr
flag.
In addition to the input DEM/pointer, the user must specify the output type. The output flow-accumulation
can be 1) cells
(i.e. the number of inflowing grid cells), catchment area
(i.e. the upslope area),
or specific contributing area
(i.e. the catchment area divided by the flow width. The default value
is cells
. The user must also specify whether the output flow-accumulation grid should be
log-tranformed (--log
), i.e. the output, if this option is selected, will be the natural-logarithm of the
accumulated flow value. This is a transformation that is often performed to better visualize the
contributing area distribution. Because contributing areas tend to be very high along valley bottoms
and relatively low on hillslopes, when a flow-accumulation image is displayed, the distribution of
values on hillslopes tends to be 'washed out' because the palette is stretched out to represent the
highest values. Log-transformation provides a means of compensating for this phenomenon. Importantly,
however, log-transformed flow-accumulation grids must not be used to estimate other secondary terrain
indices, such as the wetness index, or relative stream power index.
Grid cells possessing the NoData value in the input DEM/pointer raster are assigned the NoData value in the output flow-accumulation image.
See Also: Rho8Pointer, D8Pointer, DInfPointer, DInfFlowAccumulation, BreachDepressionsLeastCost, FillDepressions
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster DEM or D8 pointer file |
-o, --output | Output raster file |
--out_type | Output type; one of 'cells' (default), 'catchment area', and 'specific contributing area' |
--log | Optional flag to request the output be log-transformed |
--clip | Optional flag to request clipping the display max by 1% |
--pntr | Is the input raster a D8 flow pointer rather than a DEM? |
--esri_pntr | Input 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
Author: Dr. John Lindsay
Created: 26/016/2017
Last Modified: 21/02/2020
D8MassFlux
This tool can be used to perform a mass flux calculation using DEM-based surface flow-routing techniques.
For example, it could be used to model the distribution of sediment or phosphorous within a catchment.
Flow-routing is based on a D8 flow pointer (i.e. flow direction) derived from an input depresionless DEM
(--dem
). The user must also specify the names of loading (--loading
), efficiency (--efficiency
), and
absorption (--absorption
) rasters, as well as the output raster. Mass Flux operates very much like a
flow-accumulation operation except that rather than accumulating catchment areas the algorithm routes a
quantity of mass, the spatial distribution of which is specified within the loading image. The efficiency and
absorption rasters represent spatial distributions of losses to the accumulation process, the difference
being that the efficiency raster is a proportional loss (e.g. only 50% of material within a particular grid
cell will be directed downslope) and the absorption raster is an loss specified as a quantity in the same
units as the loading image. The efficiency image can range from 0 to 1, or alternatively, can be expressed as
a percentage. The equation for determining the mass sent from one grid cell to a neighbouring grid cell is:
Outflowing Mass = (Loading - Absorption + Inflowing Mass) × Efficiency
This tool assumes that each of the three input rasters have the same number of rows and columns and that any NoData cells present are the same among each of the inputs.
See Also: DInfMassFlux
Parameters:
Flag | Description |
---|---|
--dem | Input raster DEM file |
--loading | Input loading raster file |
--efficiency | Input efficiency raster file |
--absorption | Input absorption raster file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: Dec. 29, 2017
Last Modified: 12/10/2018
D8Pointer
This tool is used to generate a flow pointer grid using the simple D8 (O'Callaghan and Mark, 1984) algorithm. The
user must specify the name (--dem
) of a digital elevation model (DEM) that has been hydrologically
corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achived using
either the BreachDepressions or FillDepressions tool. The local drainage direction raster output (--output
)
by this tool serves as a necessary input for several other spatial hydrology and stream network analysis tools
in the toolset. Some tools will calculate this flow pointer raster directly from the input DEM.
By default, D8 flow pointers use the following clockwise, base-2 numeric index convention:
. | . | . |
---|---|---|
64 | 128 | 1 |
32 | 0 | 2 |
16 | 8 | 4 |
Notice that grid cells that have no lower neighbours are assigned a flow direction of zero. In a DEM that has been
pre-processed to remove all depressions and flat areas, this condition will only occur along the edges of the grid.
If the pointer file contains ESRI flow direction values instead, the --esri_pntr
parameter must be specified.
Grid cells possessing the NoData value in the input DEM are assigned the NoData value in the output image.
Reference:
O'Callaghan, J. F., & Mark, D. M. (1984). The extraction of drainage networks from digital elevation data. Computer vision, graphics, and image processing, 28(3), 323-344.
See Also: DInfPointer, FD8Pointer, BreachDepressions, FillDepressions
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--esri_pntr | D8 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
Author: Dr. John Lindsay
Created: 16/06/2017
Last Modified: 18/10/2019
DInfFlowAccumulation
This tool is used to generate a flow accumulation grid (i.e. contributing area) using the D-infinity algorithm
(Tarboton, 1997). This algorithm is an examples of a multiple-flow-direction (MFD) method because the flow entering
each grid cell is routed to one or two downslope neighbour, i.e. flow divergence is permitted. The user must
specify the name of the input digital elevation model or D-infinity pointer raster (--input
). If an input DEM is
specified, the DEM should have been hydrologically corrected
to remove all spurious depressions and flat areas. DEM pre-processing is usually achieved using the
BreachDepressionsLeastCost or FillDepressions tool.
In addition to the input DEM/pointer raster name, the user must specify the output type (--out_type
). The output
flow-accumulation
can be 1) specific catchment area (SCA), which is the upslope contributing area divided by the contour length (taken
as the grid resolution), 2) total catchment area in square-metres, or 3) the number of upslope grid cells. The user
must also specify whether the output flow-accumulation grid should be log-tranformed, i.e. the output, if this option
is selected, will be the natural-logarithm of the accumulated area. This is a transformation that is often performed
to better visualize the contributing area distribution. Because contributing areas tend to be very high along valley
bottoms and relatively low on hillslopes, when a flow-accumulation image is displayed, the distribution of values on
hillslopes tends to be 'washed out' because the palette is stretched out to represent the highest values.
Log-transformation (--log
) provides a means of compensating for this phenomenon. Importantly, however, log-transformed
flow-accumulation grids must not be used to estimate other secondary terrain indices, such as the wetness index, or
relative stream power index.
Grid cells possessing the NoData value in the input DEM/pointer raster are assigned the NoData value in the output flow-accumulation image. The output raster is of the float data type and continuous data scale.
Reference:
Tarboton, D. G. (1997). A new method for the determination of flow directions and upslope areas in grid digital elevation models. Water resources research, 33(2), 309-319.
See Also: DInfPointer, MDInfFlowAccumulation, BreachDepressionsLeastCost, FillDepressions,`
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster DEM or D-infinity pointer file |
-o, --output | Output raster file |
--out_type | Output type; one of 'cells', 'sca' (default), and 'ca' |
--threshold | Optional convergence threshold parameter, in grid cells; default is infinity |
--log | Optional flag to request the output be log-transformed |
--clip | Optional flag to request clipping the display max by 1% |
--pntr | Is 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
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:
Flag | Description |
---|---|
--dem | Input raster DEM file |
--loading | Input loading raster file |
--efficiency | Input efficiency raster file |
--absorption | Input absorption raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--zero_background | Flag 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
Author: Dr. John Lindsay
Created: 11/07/2017
Last Modified: 05/12/2019
DownslopeDistanceToStream
This tool can be used to calculate the distance from each grid cell in a raster to the nearest stream cell,
measured along the downslope flowpath. The user must specify the name of an input digital elevation model (--dem
)
and streams raster (--streams
). The DEM must have been pre-processed to remove artifact topographic depressions
and flat areas (see BreachDepressions). The streams raster should have been created using one of the DEM-based
stream mapping methods, i.e. contributing area thresholding. Stream cells are designated in this raster as all
non-zero values. The output of this tool, along with the ElevationAboveStream tool, can be useful for preliminary
flood plain mapping when combined with high-accuracy DEM data.
By default, this tool calculates flow-path using the D8 flow algorithm. However, the user may specify (--dinf
) that
the tool should use the D-infinity algorithm instead.
See Also: ElevationAboveStream, DistanceToOutlet
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--streams | Input raster streams file |
-o, --output | Output raster file |
--dinf | Use the D-infinity flow algoirthm 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'
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:
Flag | Description |
---|---|
--d8_pntr | Input D8 pointer raster file |
--watersheds | Optional input watershed raster file |
--weights | Optional input weights raster file |
-o, --output | Output raster file |
--esri_pntr | D8 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
Author: Dr. John Lindsay
Created: 08/07/2017
Last Modified: 18/10/2019
ElevationAboveStream
This tool can be used to calculate the elevation of each grid cell in a raster above the nearest stream cell,
measured along the downslope flowpath. This terrain index, a measure of relative topographic position, is
essentially equivalent to the 'height above drainage' (HAND), as described by Renno et al. (2008). The user must
specify the name of an input digital elevation model (--dem
) and streams raster (--streams
). The DEM
must have been pre-processed to remove artifact topographic depressions and flat areas (see BreachDepressions).
The streams raster should have been created using one of the DEM-based stream mapping methods, i.e. contributing
area thresholding. Stream cells are designated in this raster as all non-zero values. The output of this tool,
along with the DownslopeDistanceToStream tool, can be useful for preliminary flood plain mapping when combined
with high-accuracy DEM data.
The difference between ElevationAboveStream and ElevationAboveStreamEuclidean is that the former calculates distances along drainage flow-paths while the latter calculates straight-line distances to streams channels.
Reference:
Renno, C. D., Nobre, A. D., Cuartas, L. A., Soares, J. V., Hodnett, M. G., Tomasella, J., & Waterloo, M. J. (2008). HAND, a new terrain descriptor using SRTM-DEM: Mapping terra-firme rainforest environments in Amazonia. Remote Sensing of Environment, 112(9), 3469-3481.
See Also: ElevationAboveStreamEuclidean, DownslopeDistanceToStream, ElevAbovePit, BreachDepressions
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--streams | Input raster streams file |
-o, --output | Output 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'
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--streams | Input raster streams file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 11/03/2018
Last Modified: 12/10/2018
Fd8FlowAccumulation
This tool is used to generate a flow accumulation grid (i.e. contributing area) using the FD8 algorithm (Freeman,
1991). This algorithm is an examples of a multiple-flow-direction (MFD) method because the flow entering each
grid cell is routed to each downslope neighbour, i.e. flow divergence is permitted. The user must specify the
name (--dem
) of the input digital elevation model (DEM). The DEM must have been hydrologically
corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achived using
either the BreachDepressions or FillDepressions tool. A value must also be specified for the exponent parameter
(--exponent
), a number that controls the degree of dispersion in the resulting flow-accumulation grid. A lower
value yields greater apparent flow dispersion across divergent hillslopes. Some experimentation suggests that a
value of 1.1 is appropriate (Freeman, 1991), although this is almost certainly landscape-dependent.
In addition to the input DEM, the user must specify the output type. The output flow-accumulation
can be 1) cells
(i.e. the number of inflowing grid cells), catchment area
(i.e. the upslope area),
or specific contributing area
(i.e. the catchment area divided by the flow width. The default value
is cells
. The user must also specify whether the output flow-accumulation grid should be
log-tranformed (--log
), i.e. the output, if this option is selected, will be the natural-logarithm of the
accumulated flow value. This is a transformation that is often performed to better visualize the
contributing area distribution. Because contributing areas tend to be very high along valley bottoms
and relatively low on hillslopes, when a flow-accumulation image is displayed, the distribution of
values on hillslopes tends to be 'washed out' because the palette is stretched out to represent the
highest values. Log-transformation provides a means of compensating for this phenomenon. Importantly,
however, log-transformed flow-accumulation grids must not be used to estimate other secondary terrain
indices, such as the wetness index, or relative stream power index.
The non-dispersive threshold (--threshold
) is a flow-accumulation value (measured in upslope grid cells,
which is directly proportional to area) above which flow dispersion is not longer permited. Grid cells with
flow-accumulation values above this threshold will have their flow routed in a manner that is similar to
the D8 single-flow-direction algorithm, directing all flow towards the steepest downslope neighbour. This
is usually done under the assumption that flow dispersion, whilst appropriate on hillslope areas, is not
realistic once flow becomes channelized.
Grid cells possessing the NoData value in the input flow-pointer grid are assigned the NoData value in the output flow-accumulation image.
Reference:
Freeman, T. G. (1991). Calculating catchment area with divergent flow based on a regular grid. Computers and Geosciences, 17(3), 413-422.
See Also: D8FlowAccumulation, DInfFlowAccumulation
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--out_type | Output type; one of 'cells', 'specific contributing area' (default), and 'catchment area' |
--exponent | Optional exponent parameter; default is 1.1 |
--threshold | Optional convergence threshold parameter, in grid cells; default is infinity |
--log | Optional flag to request the output be log-transformed |
--clip | Optional 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
Author: Dr. John Lindsay
Created: 26/06/2017
Last Modified: 21/02/2020
Fd8Pointer
This tool is used to generate a flow pointer grid (i.e. flow direction) using the FD8 (Freeman, 1991) algorithm.
FD8 is a multiple-flow-direction (MFD) method because the flow entering each grid cell is routed one or more
downslope neighbours, i.e. flow divergence is permitted. The user must specify the name of a digital elevation model
(DEM; --dem
) that has been hydrologically corrected to remove all spurious depressions and flat areas.
DEM pre-processing is usually achived using the BreachDepressions or FillDepressions tools.
By default, D8 flow pointers use the following clockwise, base-2 numeric index convention:
. | . | . |
---|---|---|
64 | 128 | 1 |
32 | 0 | 2 |
16 | 8 | 4 |
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 28/06/2017
Last Modified: 12/10/2018
FillBurn
Burns streams into a DEM using the FillBurn (Saunders, 1999) method. This tool uses the algorithm described in:
Lindsay JB. 2016. The practice of DEM stream burning revisited. Earth Surface Processes and Landforms, 41(5): 658-668. DOI: 10.1002/esp.3888
And:
Saunders, W. 1999. Preparation of DEMs for use in environmental modeling analysis, in: ESRI User Conference. pp. 24-30.
Parameters:
Flag | Description |
---|---|
--dem | Input raster DEM file |
--streams | Input vector streams file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--fix_flats | Optional flag indicating whether flat areas should have a small gradient applied |
--flat_increment | Optional elevation increment applied to flat areas |
--max_depth | Optional 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--fix_flats | Optional flag indicating whether flat areas should have a small gradient applied |
--flat_increment | Optional 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--fix_flats | Optional flag indicating whether flat areas should have a small gradient applied |
--flat_increment | Optional 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
--d8_pntr | Input D8 pointer raster file |
--streams | Input raster streams file |
-o, --output | Output 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'
Author: Dr. John Lindsay
Created: 11/07/2017
Last Modified: 12/10/2018
FlattenLakes
This tool can be used to set the elevations contained in a set of input vector lake polygons (--lakes
) to
a consistent value within an input (--dem
) digital elevation model (DEM). Lake flattening is
a common pre-processing step for DEMs intended for use in hydrological applications. This algorithm
determines lake elevation automatically based on the minimum perimeter elevation for each lake
polygon. The minimum perimeter elevation is assumed to be the lake outlet elevation and is assigned
to the entire interior region of lake polygons, excluding island geometries. Note, this tool will not
provide satisfactory results if the input vector polygons contain wide river features rather than true
lakes. When this is the case, the tool will lower the entire river to the elevation of its mouth, leading
to the creation of an artifical gorge.
See Also: FillDepressions
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--lakes | Input lakes vector polygons file |
-o, --output | Output 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'
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--out_dem | Output raster DEM file |
--out_pntr | Output raster flow pointer file |
--out_accum | Output raster flow accumulation file |
--out_type | Output type; one of 'cells', 'sca' (default), and 'ca' |
--log | Optional flag to request the output be log-transformed |
--clip | Optional flag to request clipping the display max by 1% |
--esri_pntr | D8 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
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:
Flag | Description |
---|---|
--d8_pntr | Input D8 pointer raster file |
-o, --output | Output raster file |
--esri_pntr | D8 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
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:
Flag | Description |
---|---|
--d8_pntr | Input raster D8 pointer file |
--streams | Input raster streams file |
-o, --output | Output raster file |
--esri_pntr | D8 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'
Author: Dr. John Lindsay
Created: 16/07/2017
Last Modified: 18/10/2019
ImpoundmentSizeIndex
This tool can be used to calculate the impoundment size index (ISI) from a digital elevation model (DEM).
The ISI is a land-surface parameter related to the size of the impoundment that would result from inserting
a dam of a user-specified maximum length (--damlength
) into each DEM grid cell. In addition to an
output dam-height raster (same name as --output
file but with an _dam_height suffix appended), the tool outputs
a measure of impoundment size (--out_type
) related to impoundment average depth, total volume, or flooded area.
Please note that this tool performs an extremely complex and computationally intensive flow-accumulation operation.
As such, it may take a substantial amount of processing time and may encounter issues (including memory issues) when
applied to very large DEMs. It is not necessary to pre-process the input DEM (--dem
) to remove topographic depressions
and flat areas. The internal flow-accumulation operation will not be confounded by the presence of these features.
Reference:
Lindsay, JB (2015) Modelling the spatial pattern of potential impoundment size from DEMs. Online resource: Whitebox Blog
See Also: InsertDams, StochasticDepressionAnalysis
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output file |
--out_type | Output type; one of 'mean depth' (default), 'volume', 'area', 'max depth' |
--damlength | Maximum length of the dam |
Python function:
wbt.impoundment_size_index(
dem,
output,
damlength,
out_type="mean depth",
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ImpoundmentSizeIndex -v ^
--wd="/path/to/data/" --dem=DEM.tif -o=out.tif ^
--out_type='max depth' --damlength=11
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--dam_pts | Input vector dam points file |
-o, --output | Output file |
--damlength | Maximum 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
Author: Dr. John Lindsay
Created: 19/02/2020
Last Modified: 20/02/2020
Isobasins
This tool can be used to divide a landscape into a group of nearly equal-sized watersheds, known as isobasins.
The user must specify the name (--dem
) of a digital elevation model (DEM), the output raster name (--output
),
and the isobasin target area (--size
) specified in units of grid cells. The DEM must have been hydrologically
corrected to remove all spurious depressions and flat areas. DEM pre-processing is usually achived using either
the BreachDepressions or FillDepressions tool. Several temporary rasters are created during the execution
and stored in memory of this tool.
The tool can optionally (--connections
) output a CSV table that contains the upstream/downstream connections
among isobasins. That is, this table will identify the downstream basin of each isobasin, or will list N/A in
the event that there is no downstream basin, i.e. if it drains to an edge. The output CSV file will have the
same name as the output raster, but with a *.csv file extension.
See Also: Watershed, Basins, BreachDepressions, FillDepressions
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--size | Target basin size, in grid cells |
--connections | Output 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
Author: Dr. John Lindsay
Created: 03/12/2017
Last Modified: 24/07/2020
JensonSnapPourPoints
The JensonSnapPourPoints tool can be used to move the location of vector pour points (i.e. outlets used in a Watershed
operation) (--pour_pts
) to the location coincident with the nearest stream cell (--stream
) value within
a specified maximum distance (--snap_dist
). The pour points file (--pour_pts
) must be a vector file of Point ShapeType.
If the output of the JensonSnapPourPoints tool is to be used with the Watershed tool, the streams raster should
be generated by extracting the streams using the D8FlowAccumulation algorithm. The snap distance (--snap_dist
), measured
in map units (e.g meters), must also be specified. This distance will serve as the search radius placed around each pour
point during the search for the nearst stream cell.
Lindsay et al. (2008) provide a detailed discussion of the JensonSnapPourPoints technique, and other less sophisticated but commonly used techniques (SnapPourPoints) for adjusting pour point locations used in watershedding operations. In most cases, the JensonSnapPourPoints tool should be prefered over SnapPourPoints for applications of repositioning outlet points used in watershedding operations onto the digital stream lines contained in local drainage direction rasters. Jenson's method relocates outlet points to the nearest stream cell while SnapPourPoints relocated outlets to the largest stream (designated by the largest flow accumulation value). In the common situation where outlet cells are position near the confluence point of smaller tributary streams, the SnapPourPoints tool may re-position outlets on the main-trunk stream, which will result in watershed delineation of incorrect sub-basins.
Reference:
Jenson, S. K. (1991), Applications of hydrological information automati-cally extracted from digital elevation models, Hydrological Processes, 5, 31–44, doi:10.1002/hyp.3360050104.
Lindsay JB, Rothwell JJ, and Davies H. 2008. Mapping outlet points used for watershed delineation onto DEM-derived stream networks, Water Resources Research, 44, W08442, doi:10.1029/2007WR006507.
See Also: Watershed, SnapPourPoints, D8FlowAccumulation
Parameters:
Flag | Description |
---|---|
--pour_pts | Input vector pour points (outlet) file |
--streams | Input raster streams file |
-o, --output | Output vector file |
--snap_dist | Maximum 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
--basins | Input raster basins file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 29/10/2018
Last Modified: 29/10/2018
LowPointsOnHeadwaterDivides
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool locates low points, or passes, on the drainage divides between subbasins that are situated on headwater divides. A subbasin is the catchment draining to a link in a stream network. A headwater catchment is the portion of a subbasin that drains to the channel head. Only first-order streams contain channel heads and headwater catchments are sometimes referred to as zero-order basins. The lowest points along a zero-order catchment is likely to coincide with mountain passes in alpine environments.
The user must input a depressionless DEM (i.e. a DEM that has been pre-processed to remove all topographic depressions) and a raster stream network. The tool will work best if the raster stream network, generally derived by thresholding a flow-accumulation raster, is processed to remove shorter headwater streams. You can use the RemoveShortStreams tool remove shorter streams in the input raster. It is recommended to remove streams shorter than 2 or 3 grid cells in length. The algorithm proceeds by first deriving the D8 flow pointer from the input DEM. It then identifies all channel head cells in the input streams raster and the zero-order basins that drain to them. The stream network is then processed to assign a unique identifier to each segment, which is then used to extract subbasins. Lastly, zero-order basin edge cells are identified and the location of lowest grid cells for each pair of neighbouring basins is entered into the output vector file.
See Also: RemoveShortStreams
Parameters:
Flag | Description |
---|---|
-d, --dem | Name of the input DEM raster file |
--streams | Name of the input stream channel raster file |
-o, --output | Name 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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 25/06/2017
Last Modified: 28/10/2019
MdInfFlowAccumulation
This tool is used to generate a flow accumulation grid (i.e. contributing area) using the MD-infinity algorithm
(Seibert and McGlynn, 2007). This algorithm is an examples of a multiple-flow-direction (MFD) method because the flow entering
each grid cell is routed to one or two downslope neighbour, i.e. flow divergence is permitted. The user must
specify the name of the input digital elevation model (--dem
). The DEM should have been hydrologically corrected
to remove all spurious depressions and flat areas. DEM pre-processing is usually achieved using the
BreachDepressions or FillDepressions tool.
In addition to the input flow-pointer grid name, the user must specify the output type (--out_type
). The output
flow-accumulation
can be 1) specific catchment area (SCA), which is the upslope contributing area divided by the contour length (taken
as the grid resolution), 2) total catchment area in square-metres, or 3) the number of upslope grid cells. The user
must also specify whether the output flow-accumulation grid should be log-tranformed, i.e. the output, if this option
is selected, will be the natural-logarithm of the accumulated area. This is a transformation that is often performed
to better visualize the contributing area distribution. Because contributing areas tend to be very high along valley
bottoms and relatively low on hillslopes, when a flow-accumulation image is displayed, the distribution of values on
hillslopes tends to be 'washed out' because the palette is stretched out to represent the highest values.
Log-transformation (--log
) provides a means of compensating for this phenomenon. Importantly, however, log-transformed
flow-accumulation grids must not be used to estimate other secondary terrain indices, such as the wetness index, or
relative stream power index.
Grid cells possessing the NoData value in the input DEM raster are assigned the NoData value in the output flow-accumulation image. The output raster is of the float data type and continuous data scale.
Reference:
Seibert, J. and McGlynn, B.L., 2007. A new triangular multiple flow direction algorithm for computing upslope areas from gridded digital elevation models. Water resources research, 43(4).
See Also: D8FlowAccumulation, DInfFlowAccumulation, FD8FlowAccumulation, BreachDepressions
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--out_type | Output type; one of 'cells', 'specific contributing area' (default), and 'catchment area' |
--exponent | Optional exponent parameter; default is 1.1 |
--threshold | Optional convergence threshold parameter, in grid cells; default is infinity |
--log | Optional flag to request the output be log-transformed |
--clip | Optional 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
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 25/06/2017
Last Modified: 12/10/2018
RaiseWalls
This tool is used to increment the elevations in a digital elevation model (DEM) along
the boundaries of a vector lines or polygon layer. The user must specify the name of the
raster DEM (--dem
), the vector file (--input
), the output file name (--output
), the
increment height (--height
), and an optional breach lines vector layer (--breach
).
The breach lines layer can be used to breach a whole in the raised walls at intersections
with the wall layer.
Parameters:
Flag | Description |
---|---|
-i, walls, --input | Input vector lines or polygons file |
--breach | Optional input vector breach lines |
--dem | Input raster DEM file |
-o, --output | Output raster file |
--height | Wall 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
Author: Dr. John Lindsay
Created: 22/04/2018
Last Modified: 22/10/2019
Rho8Pointer
This tool is used to generate a flow pointer grid (i.e. flow direction) using the stochastic
Rho8 (J. Fairfield and P. Leymarie, 1991) algorithm. Like the D8 flow algorithm (D8Pointer),
Rho8 is a single-flow-direction (SFD) method because the flow entering each grid cell is routed
to only one downslope neighbour, i.e. flow divergence is not permitted. The user must specify the
name of a digital elevation model (DEM) file (--dem
) that has been hydrologically corrected to
remove all spurious depressions and flat areas (BreachDepressions, FillDepressions).
By default, the Rho8 flow pointers use the following clockwise, base-2 numeric index convention:
. | . | . |
---|---|---|
64 | 128 | 1 |
32 | 0 | 2 |
16 | 8 | 4 |
Notice that grid cells that have no lower neighbours are assigned a flow direction of zero. In a DEM that has been
pre-processed to remove all depressions and flat areas, this condition will only occur along the edges of the grid.
If the pointer file contains ESRI flow direction values instead, the --esri_pntr
parameter must be specified.
Grid cells possessing the NoData value in the input DEM are assigned the NoData value in the output image.
References:
Fairfield, J., & Leymarie, P. (1991). Drainage networks from grid digital elevation models. Water Resources Research, 27(5), 709-717.
See Also: D8Pointer, FD8Pointer, DInfPointer, BreachDepressions, FillDepressions
Parameters:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output raster file |
--esri_pntr | D8 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
Author: Dr. John Lindsay
Created: 16/07/2017
Last Modified: 18/10/2019
Sink
This tool identifies each sink (i.e. topographic depression) in a raster digital elevation model (DEM). A sink, or depression, is a bowl-like landscape feature, which is characterized by interior drainage. Each identified sink in the input DEM is assigned a unique, non-zero, positive value in the ouput raster. The Sink tool essentially runs the FillDepressions tool followed by the Clump tool on all modified grid cells.
See Also: FillDepressions, Clump
Parameters:
Flag | Description |
---|---|
-i, --dem, --input | Input raster DEM file |
-o, --output | Output raster file |
--zero_background | Flag 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
Author: Dr. John Lindsay
Created: 01/07/2017
Last Modified: 05/12/2019
SnapPourPoints
The SnapPourPoints tool can be used to move the location of vector pour points (i.e. outlets used in a Watershed
operation) (--pour_pts
) to the location coincident with the highest flow accumulation (--flow_accum
) value within
a specified maximum distance (--snap_dist
). The pour points file (--pour_pts
) must be a vector file of Point ShapeType.
If the output of the SnapPourPoints tool is to be used with the Watershed tool, the flow accumulation raster should
be generated using the D8FlowAccumulation algorithm. The snap distance (--snap_dist
), measured in map units (e.g.
meters), must also be specified. This distance will serve as the search radius placed around each pour point during the
search for the maximum flow accumulation. In general, each outlet will be relocated the distance specified by the snap
distance.
Lindsay et al. (2008) provide a detailed discussion of the SnapPourPoints technique, and other more sophisticated techniques for adjusting pour point locations used in watershedding operations including Jenson's snap pour points (JensonSnapPourPoints) method. In most cases, the JensonSnapPourPoints tool should be prefered for applications of repositioning outlet points used in watershedding operations onto the digital stream lines contained in local drainage direction rasters. Jenson's method relocates outlet points to the nearest stream cell while SnapPourPoints relocated outlets to the largest stream (designated by the largest flow accumulation value). In the common situation where outlet cells are position near the confluence point of smaller tributary streams, the SnapPourPoints tool may re-position outlets on the main-trunk stream, which will result in watershed delineation of incorrect sub-basins.
Reference:
Lindsay JB, Rothwell JJ, and Davies H. 2008. Mapping outlet points used for watershed delineation onto DEM-derived stream networks, Water Resources Research, 44, W08442, doi:10.1029/2007WR006507.
See Also: Watershed, JensonSnapPourPoints, D8FlowAccumulation
Parameters:
Flag | Description |
---|---|
--pour_pts | Input vector pour points (outlet) file |
--flow_accum | Input raster D8 flow accumulation file |
-o, --output | Output vector file |
--snap_dist | Maximum 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
Author: Dr. John Lindsay
Created: 27/072017
Last Modified: 12/10/2018
StochasticDepressionAnalysis
This tool performs a stochastic analysis of depressions within a DEM, calculating the probability of each cell belonging to a depression. This land-surface prameter (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:
-
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.
-
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.
-
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.
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output file |
--rmse | The DEM's root-mean-square-error (RMSE), in z units. This determines error magnitude |
--range | The error field's correlation length, in xy-units |
--iterations | The 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
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:
Flag | Description |
---|---|
--d8_pntr | Input raster D8 pointer file |
--streams | Input raster streams file |
-o, --output | Output raster file |
--esri_pntr | D8 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'
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:
Flag | Description |
---|---|
--d8_pntr | Input D8 pointer raster file |
--streams | Input raster streams file |
-o, --output | Output raster file |
--esri_pntr | D8 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'
Author: Dr. John Lindsay
Created: 01/07/2017
Last Modified: 13/02/2020
TraceDownslopeFlowpaths
This tool can be used to mark the flowpath initiated from user-specified locations downslope and
terminating at either the grid's edge or a grid cell with undefined flow direction. The user must
input the name of a D8 flow pointer grid (--d8_pntr
) and an input vector file indicating the location
of one or more initiation points, i.e. 'seed points' (--seed_pts
). The seed point file must be a
vector of the POINT ShapeType. Note that the flow pointer should be generated from a DEM that has
been processed to remove all topographic depression (see BreachDepressions and FillDepressions) and
created using the D8 flow algorithm (D8Pointer).
See Also: D8Pointer, BreachDepressions, FillDepressions, DownslopeFlowpathLength, DownslopeDistanceToStream
Parameters:
Flag | Description |
---|---|
--seed_pts | Input vector seed points file |
--d8_pntr | Input D8 pointer raster file |
-o, --output | Output raster file |
--esri_pntr | D8 pointer uses the ESRI style scheme |
--zero_background | Flag 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
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:
Flag | Description |
---|---|
--d8_pntr | Input D8 pointer raster file |
--pour_pts | Input vector pour points (outlet) file |
-o, --output | Output raster file |
--esri_pntr | D8 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'
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:
Flag | Description |
---|---|
-i, --dem | Input raster DEM file |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 21/11/2019
Last Modified: 21/11/2019
Watershed
This tool will perform a watershedding operation based on a group of input vector pour points (--pour_pts
),
i.e. outlets or points-of-interest, or a raster containing point points. Watershedding is a procedure that identifies
all of the cells upslope of a cell of interest (pour point) that are connected to the pour point by a flow-path. The
user must specify the name of a D8-derived flow pointer (flow direction) raster (--d8_pntr
), a vector pour point file
(--pour_pts
), and the output raster (--output
). The pour points must be of a Point ShapeType (i.e. Point, PointZ, PointM,
MultiPoint, MultiPointZ, MultiPointM). Watersheds will be assigned the input pour point FID value. The flow
pointer raster must be generated using the D8 algorithm, D8Pointer.
Pour point vectors can be attained by on-screen digitizing to designate these points-of-interest locations. Because pour points are usually, although not always, situated on a stream network, it is recommended that you use Jenson's method (JensonSnapPourPoints) to snap pour points on the stream network. This will ensure that the digitized outlets are coincident with the digital stream contained within the DEM flowpaths. If this is not done prior to inputting a pour-point set to the Watershed tool, anomalously small watersheds may be ouput, as pour points that fall off of the main flow path (even by one cell) in the D8 pointer will yield very different catchment areas.
If a raster pour point is specified instead of vector points, the watershed labels will derive their IDs from the grid cell values of all non-zero, non-NoData valued grid cells in the pour points file. Notice that this file can contain any integer data. For example, if a lakes raster, with each lake possessing a unique ID, is used as the pour points raster, the tool will map the watersheds draining to each of the input lake features. Similarly, a pour points raster may actually be a streams file, such as what is generated by the StreamLinkIdentifier tool.
By default, the pointer raster is assumed to use the clockwise indexing method used by WhiteboxTools.
If the pointer file contains ESRI flow direction values instead, the --esri_pntr
parameter must be specified.
There are several tools that perform similar watershedding operations in WhiteboxTools. Watershed is appropriate to use when you have a set of specific locations for which you need to derive the watershed areas. Use the Basins tool instead when you simply want to find the watersheds draining to each outlet situated along the edge of a DEM. The Isobasins tool can be used to divide a landscape into roughly equally sized watersheds. The Subbasins and StrahlerOrderBasins are useful when you need to find the areas draining to each link within a stream network. Finally, Hillslopes can be used to idenfity the areas draining the each of the left and right banks of a stream network.
Reference:
Jenson, S. K. (1991), Applications of hydrological information automati-cally extracted from digital elevation models, Hydrological Processes, 5, 31–44, doi:10.1002/hyp.3360050104.
Lindsay JB, Rothwell JJ, and Davies H. 2008. Mapping outlet points used for watershed delineation onto DEM-derived stream networks, Water Resources Research, 44, W08442, doi:10.1029/2007WR006507.
See Also: D8Pointer, Basins, Subbasins, Isobasins, StrahlerOrderBasins, Hillslopes, JensonSnapPourPoints, BreachDepressions, FillDepressions
Parameters:
Flag | Description |
---|---|
--d8_pntr | Input D8 pointer raster file |
--pour_pts | Input pour points (outlet) file |
-o, --output | Output raster file |
--esri_pntr | D8 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'
Author: Dr. John Lindsay
Created: 22/06/2017
Last Modified: 14/02/2020
Image Processing Tools
- ChangeVectorAnalysis
- Closing
- CreateColourComposite
- FlipImage
- IhsToRgb
- ImageSlider
- ImageStackProfile
- IntegralImage
- LineThinning
- Mosaic
- MosaicWithFeathering
- NormalizedDifferenceIndex
- Opening
- RemoveSpurs
- Resample
- RgbToIhs
- SplitColourComposite
- ThickenRasterLine
- TophatTransform
- WriteFunctionMemoryInsertion
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:
Flag | Description |
---|---|
--date1 | Input raster files for the earlier date |
--date2 | Input raster files for the later date |
--magnitude | Output vector magnitude raster file |
--direction | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
--red | Input red band image file |
--green | Input green band image file |
--blue | Input blue band image file |
--opacity | Input opacity band image file (optional) |
-o, --output | Output colour composite file |
--enhance | Optional flag indicating whether a balance contrast enhancement is performed |
--zeros | Optional 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--direction | Direction 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
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:
Flag | Description |
---|---|
--intensity | Input intensity file |
--hue | Input hue file |
--saturation | Input saturation file |
--red | Output red band file. Optionally specified if colour-composite not specified |
--green | Output green band file. Optionally specified if colour-composite not specified |
--blue | Output blue band file. Optionally specified if colour-composite not specified |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 25/07/2017
Last Modified: 22/10/2019
ImageSlider
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool creates an interactive 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:
Flag | Description |
---|---|
--i1, --input1 | Name of the left input image file |
--p1, --palette1 | Left 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, --reverse1 | Reverse left image palette? |
--l1, --label1 | Left image label (leave blank for none) |
--i2, --input2 | Name of the right input image file |
--p2, --palette2 | Right 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, --reverse2 | Reverse right image palette? |
--l2, --label2 | Right image label (leave blank for none) |
-o, --output | Name of the output HTML file (*.html) |
-h, --height | Image 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:
Flag | Description |
---|---|
-i, --inputs | Input multispectral image files |
--points | Input vector points file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output raster file |
--method | Resampling 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'
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:
Flag | Description |
---|---|
--i1, --input1 | Input raster file to modify |
--i2, --input2 | Input reference raster file |
-o, --output | Output raster file |
--method | Resampling 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
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:
Flag | Description |
---|---|
--input1 | Input image 1 (e.g. near-infrared band) |
--input2 | Input image 2 (e.g. red band) |
-o, --output | Output raster file |
--clip | Optional amount to clip the distribution tails by, in percent |
--correction | Optional 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--iterations | Maximum 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
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output raster file |
--cell_size | Optionally specified cell size of output raster. Not used when base raster is specified |
--base | Optionally specified input base raster file. Not used when a cell size is specified |
--method | Resampling 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
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:
Flag | Description |
---|---|
--red | Input red band image file. Optionally specified if colour-composite not specified |
--green | Input green band image file. Optionally specified if colour-composite not specified |
--blue | Input blue band image file. Optionally specified if colour-composite not specified |
--composite | Input colour-composite image file. Only used if individual bands are not specified |
--intensity | Output intensity raster file |
--hue | Output hue raster file |
--saturation | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input colour composite image file |
--red | Output red band file |
--green | Output green band file |
--blue | Output 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
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 diaganol 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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster 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 |
--variant | Optional 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
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:
Flag | Description |
---|---|
--i1, --input1 | Input raster file associated with the first date |
--i2, --input2 | Input raster file associated with the second date |
--i3, --input3 | Optional input raster file associated with the third date |
-o, --output | Output 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
Author: Dr. John Lindsay
Created: 18/07/2017
Last Modified: 13/10/2018
Image Processing Tools → Classification
- EvaluateTrainingSites
- ImageSegmentation
- KMeansClustering
- MinDistClassification
- ModifiedKMeansClustering
- ParallelepipedClassification
EvaluateTrainingSites
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool 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:
Flag | Description |
---|---|
-i, --inputs | Name of the input band images |
-p, --polys | Name of the input training site polygons shapefile |
-f, --field | Name of the attribute containing class name data |
-o, --output | Name 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
ImageSegmentation
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool 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:
Flag | Description |
---|---|
-i, --inputs | Names of the input band images |
-o, --output | Name of the output raster file |
--threshold | Distance threshold, in z-scores |
--steps | Number of steps |
--min_area | Minimum 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
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 initilization
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output raster file |
--out_html | Output HTML report file |
--classes | Number of classes |
--max_iterations | Maximum number of iterations |
--class_change | Minimum percent of cells changed between iterations before completion |
--initialize | How to initialize cluster centres? |
--min_class_size | Minimum 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
Author: Dr. John Lindsay
Created: 27/12/2017
Last Modified: 24/02/2019
MinDistClassification
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool 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:
Flag | Description |
---|---|
-i, --inputs | Names of the input band images |
-p, --polys | Name of the input training site polygons shapefile |
-f, --field | Name of the attribute containing class name data |
-o, --output | Name of the output raster file |
--threshold | Distance 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
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:
Flag | Description |
---|---|
-i, --inputs | Input raster files |
-o, --output | Output raster file |
--out_html | Output HTML report file |
--start_clusters | Initial number of clusters |
--merge_dist | Cluster merger distance |
--max_iterations | Maximum number of iterations |
--class_change | Minimum 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
Author: Dr. John Lindsay
Created: 30/12/2017
Last Modified: 24/02/2019
ParallelepipedClassification
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool 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:
Flag | Description |
---|---|
-i, --inputs | Name of the input band images |
-p, --polys | Name of the input training site polygons shapefile |
-f, --field | Name of the attribute containing class name data |
-o, --output | Name 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
- BilateralFilter
- CannyEdgeDetection
- ConservativeSmoothingFilter
- CornerDetection
- DiffOfGaussianFilter
- DiversityFilter
- EdgePreservingMeanFilter
- EmbossFilter
- FastAlmostGaussianFilter
- GaussianFilter
- HighPassFilter
- HighPassMedianFilter
- KNearestMeanFilter
- LaplacianFilter
- LaplacianOfGaussianFilter
- LeeSigmaFilter
- LineDetectionFilter
- MajorityFilter
- MaximumFilter
- MeanFilter
- MedianFilter
- MinimumFilter
- OlympicFilter
- PercentileFilter
- PrewittFilter
- RangeFilter
- RobertsCrossFilter
- ScharrFilter
- SobelFilter
- StandardDeviationFilter
- TotalFilter
- UnsharpMasking
- UserDefinedWeightsFilter
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:
Flag | Description |
---|---|
-i, --input | Input raster 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 |
--threshold | Difference 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--sigma_dist | Standard deviation in distance in pixels |
--sigma_int | Standard 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
Author: Dr. John Lindsay
Created: 27/06/2017
Last Modified: 30/01/2020
CannyEdgeDetection
Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).
This tool 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:
Flag | Description |
---|---|
-i, --input | Name of the input raster image file |
-o, --output | Name of the output raster image file |
-s, --sigma | Sigma value used in Gaussian filtering, default = 0.5 |
-l, --low | Low threshold, default = 0.05 |
-h, --high | High threshold, default = 0.15 |
-a, --add_back | Add 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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input boolean image |
-o, --output | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--sigma1 | Standard deviation distance in pixels |
--sigma2 | Standard 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filter | Size of the filter kernel |
--threshold | Maximum 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
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 | -1 | 0 |
0 | 0 | 0 |
0 | 1 | 0 |
Northeast (ne
)
. | . | . |
---|---|---|
0 | 0 | -1 |
0 | 0 | 0 |
-1 | 0 | 0 |
East (e
)
. | . | . |
---|---|---|
0 | 0 | 0 |
1 | 0 | -1 |
0 | 0 | 0 |
Southeast (se
)
. | . | . |
---|---|---|
1 | 0 | 0 |
0 | 0 | 0 |
0 | 0 | -1 |
South (s
)
. | . | . |
---|---|---|
0 | 1 | 0 |
1 | 0 | 0 |
0 | -1 | 0 |
Southwest (sw
)
. | . | . |
---|---|---|
0 | 0 | 1 |
0 | 0 | 0 |
-1 | 0 | 0 |
West (w
)
. | . | . |
---|---|---|
0 | 0 | 0 |
-1 | 0 | 1 |
0 | 0 | 0 |
Northwest (nw
)
. | . | . |
---|---|---|
-1 | 0 | 0 |
0 | 0 | 0 |
0 | 0 | 1 |
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--direction | Direction of reflection; options include 'n', 's', 'e', 'w', 'ne', 'se', 'nw', 'sw' |
--clip | Optional 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--sigma | Standard 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
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 signficantly 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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--sigma | Standard 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
Author: Dr. John Lindsay
Created: 26/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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
--sig_digits | Number of significant digits |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster 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 |
-k | k-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
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 | -1 | 0 |
-1 | 4 | -1 |
0 | -1 | 0 |
3x3(2)
. | . | . |
---|---|---|
0 | -1 | 0 |
-1 | 5 | -1 |
0 | -1 | 0 |
3x3(3)
. | . | . |
---|---|---|
-1 | -1 | -1 |
-1 | 8 | -1 |
-1 | -1 | -1 |
3x3(4)
. | . | . |
---|---|---|
1 | -2 | 1 |
-2 | 4 | -2 |
1 | -2 | 1 |
5x5(1)
. | . | . | . | . |
---|---|---|---|---|
0 | 0 | -1 | 0 | 0 |
0 | -1 | -2 | -1 | 0 |
-1 | -2 | 17 | -2 | -1 |
0 | -1 | -2 | -1 | 0 |
0 | 0 | -1 | 0 | 0 |
5x5(2)
. | . | . | . | . |
---|---|---|---|---|
0 | 0 | -1 | 0 | 0 |
0 | -1 | -2 | -1 | 0 |
-1 | -2 | 16 | -2 | -1 |
0 | -1 | -2 | -1 | 0 |
0 | 0 | -1 | 0 | 0 |
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--variant | Optional variant value. Options include 3x3(1), 3x3(2), 3x3(3), 3x3(4), 5x5(1), and 5x5(2) (default is 3x3(1)) |
--clip | Optional 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--sigma | Standard 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
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:
Flag | Description |
---|---|
-i, --input | Input raster 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 |
--sigma | Sigma value should be related to the standarad deviation of the distribution of image speckle noise |
-m | M-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
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)
. | . | . |
---|---|---|
-1 | 2 | -1 |
-1 | 2 | -1 |
-1 | 2 | -1 |
'h' (Horizontal)
. | . | . |
---|---|---|
-1 | -1 | -1 |
2 | 2 | 2 |
-1 | -1 | -1 |
'45' (Northeast-Southwest)
. | . | . |
---|---|---|
-1 | -1 | 2 |
-1 | 2 | -1 |
2 | -1 | -1 |
'135' (Northwest-Southeast)
. | . | . |
---|---|---|
2 | -1 | -1 |
-1 | 2 | -1 |
-1 | -1 | 2 |
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--variant | Optional variant value. Options include 'v' (vertical), 'h' (horizontal), '45', and '135' (default is 'v') |
--absvals | Optional flag indicating whether outputs should be absolute values |
--clip | Optional 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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 --filtery
flags.
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
--sig_digits | Number of significant digits |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
--sig_digits | Number of significant digits |
Python function:
wbt.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
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
. | . | . |
---|---|---|
-1 | 0 | 1 |
-1 | 0 | 1 |
-1 | 0 | 1 |
Y-direction slope
. | . | . |
---|---|---|
1 | 1 | 1 |
0 | 0 | 0 |
-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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--clip | Optional 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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|:
. | . |
---|---|
P1 | P2 |
P3 | P4 |
|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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--clip | Optional 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
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
. | . | . |
---|---|---|
3 | 0 | -3 |
10 | 0 | -10 |
3 | 0 | -3 |
Y-direction slope
. | . | . |
---|---|---|
3 | 10 | 3 |
0 | 0 | 0 |
-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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--clip | Optional 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
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
. | . | . |
---|---|---|
-1 | 0 | 1 |
-2 | 0 | 2 |
-1 | 0 | 1 |
Y-direction slope
. | . | . |
---|---|---|
1 | 2 | 1 |
0 | 0 | 0 |
-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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--variant | Optional variant value. Options include 3x3 and 5x5 (default is 3x3) |
--clip | Optional 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--filterx | Size of the filter kernel in the x-direction |
--filtery | Size of the filter kernel in the y-direction |
Python function:
wbt.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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--sigma | Standard deviation distance in pixels |
--amount | A percentage and controls the magnitude of each overshoot |
--threshold | Controls 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
--weights | Input weights file |
-o, --output | Output raster file |
--center | Kernel center cell; options include 'center', 'upper-left', 'upper-right', 'lower-left', 'lower-right' |
--normalize | Normalize 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
Author: Dr. John Lindsay
Created: 26/04/2018
Last Modified: 22/10/2019
Image Processing Tools → Image Enhancement
- BalanceContrastEnhancement
- CorrectVignetting
- DirectDecorrelationStretch
- GammaCorrection
- GaussianContrastStretch
- HistogramEqualization
- HistogramMatching
- HistogramMatchingTwoImages
- MinMaxContrastStretch
- PanchromaticSharpening
- PercentageContrastStretch
- SigmoidalContrastStretch
- StandardDeviationContrastStretch
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:
Flag | Description |
---|---|
-i, --input | Input colour composite image file |
-o, --output | Output raster file |
--band_mean | Band 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
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 reducuction 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:
Flag | Description |
---|---|
-i, --input | Input raster file |
--pp | Input principal point file |
-o, --output | Output raster file |
--focal_length | Camera focal length, in millimeters |
--image_width | Distance between photograph edges, in millimeters |
-n | The '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
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:
Flag | Description |
---|---|
-i, --input | Input colour composite image file |
-o, --output | Output raster file |
-k | Achromatic factor (k) ranges between 0 (no effect) and 1 (full saturation stretch), although typical values range from 0.3 to 0.7 |
--clip | Optional 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
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 = zin
gamma
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--gamma | Gamma 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
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: HistogramEqualization, MinMaxContrastStretch, PercentageContrastStretch, SigmoidalContrastStretch, StandardDeviationContrastStretch, HistogramMatching
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--num_tones | Number 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
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: HistogramMatching, HistogramMatchingTwoImages, GaussianContrastStretch
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--num_tones | Number 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
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:
Flag | Description |
---|---|
-i, --input | Input raster file |
--histo_file | Input reference probability distribution function (pdf) text file |
-o, --output | Output 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
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:
Flag | Description |
---|---|
--i1, --input1 | Input raster file to modify |
--i2, --input2 | Input reference raster file |
-o, --output | Output 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
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: GaussianContrastStretch, HistogramEqualization, PercentageContrastStretch, SigmoidalContrastStretch, StandardDeviationContrastStretch
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--min_val | Lower tail clip value |
--max_val | Upper tail clip value |
--num_tones | Number 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
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:
Flag | Description |
---|---|
--red | Input red band image file. Optionally specified if colour-composite not specified |
--green | Input green band image file. Optionally specified if colour-composite not specified |
--blue | Input blue band image file. Optionally specified if colour-composite not specified |
--composite | Input colour-composite image file. Only used if individual bands are not specified |
--pan | Input panchromatic band file |
-o, --output | Output colour composite file |
--method | Options 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'
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: GaussianContrastStretch, HistogramEqualization, MinMaxContrastStretch, SigmoidalContrastStretch, StandardDeviationContrastStretch
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--clip | Optional amount to clip the distribution tails by, in percent |
--tail | Specified which tails to clip; options include 'upper', 'lower', and 'both' (default is 'both') |
--num_tones | Number 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
Author: Dr. John Lindsay
Created: 13/07/2017
Last Modified: 30/01/2020
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: GaussianContrastStretch, HistogramEqualization, MinMaxContrastStretch, PercentageContrastStretch, StandardDeviationContrastStretch
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--cutoff | Cutoff value between 0.0 and 0.95 |
--gain | Gain value |
--num_tones | Number 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
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: GaussianContrastStretch, HistogramEqualization, MinMaxContrastStretch, PercentageContrastStretch, SigmoidalContrastStretch
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--clip, --stdev | Standard deviation clip value |
--num_tones | Number 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
Author: Dr. John Lindsay
Created: 13/07/2017
Last Modified: 30/01/2020
LiDAR Tools
- AsciiToLas
- ClassifyBuildingsInLidar
- ClassifyOverlapPoints
- ClipLidarToPolygon
- ErasePolygonFromLidar
- FilterLidarClasses
- FilterLidarScanAngles
- FindFlightlineEdgePoints
- FlightlineOverlap
- HeightAboveGround
- LasToAscii
- LasToMultipointShapefile
- LasToShapefile
- LasToZlidar
- LidarBlockMaximum
- LidarBlockMinimum
- LidarClassifySubset
- LidarColourize
- LidarDigitalSurfaceModel
- LidarElevationSlice
- LidarGroundPointFilter
- LidarHexBinning
- LidarHillshade
- LidarHistogram
- LidarIdwInterpolation
- LidarInfo
- LidarJoin
- LidarKappaIndex
- LidarNearestNeighbourGridding
- LidarPointDensity
- LidarPointStats
- LidarRansacPlanes
- LidarRbfInterpolation
- LidarRemoveDuplicates
- LidarRemoveOutliers
- LidarRooftopAnalysis
- LidarSegmentation
- LidarSegmentationBasedFilter
- LidarSibsonInterpolation
- LidarSortByTime
- LidarThin
- LidarThinHighDensity
- LidarTile
- LidarTileFootprint
- LidarTinGridding
- LidarTophatTransform
- NormalVectors
- SelectTilesByPolygon
- ZlidarToLas
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"
Value | Interpretation |
---|---|
x | x-coordinate |
y | y-coordinate |
z | elevation |
i | intensity value |
c | classification |
rn | return number |
nr | number of returns |
time | GPS time |
sa | scan angle |
r | red |
b | blue |
g | green |
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:
Flag | Description |
---|---|
-i, --inputs | Input LiDAR ASCII files (.csv) |
--pattern | Input field pattern |
--proj | Well-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
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
--buildings | Input vector polygons file |
-o, --output | Output 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'
Author: Dr. John Lindsay
Created: 17/11/2019
Last Modified: 17/11/2019
ClassifyOverlapPoints
Classifies or filters LAS points in regions of overlapping flight lines.
Parameters:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output LiDAR file |
--resolution | The size of the square area used to evaluate nearby points in the LiDAR data |
--filter | Filter out points from overlapping flightlines? If false, overlaps will simply be classified |
Python function:
wbt.classify_overlap_points(
i,
output,
resolution=2.0,
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
Author: Dr. John Lindsay
Created: 27/04/2018
Last Modified: 18/10/2019
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), wich
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, Clip, ClipRasterToPolygon
Parameters:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
--polygons | Input vector polygons file |
-o, --output | Output 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'
Author: Dr. John Lindsay
Created: 25/04/2018
Last Modified: 26/07/2019
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), wich
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, Clip, ClipRasterToPolygon
Parameters:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
--polygons | Input vector polygons file |
-o, --output | Output 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'
Author: Dr. John Lindsay
Created: 25/04/2018
Last Modified: 12/10/2018
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 Value | Meaning |
---|---|
0 | Created never classified |
1 | Unclassified |
2 | Ground |
3 | Low Vegetation |
4 | Medium Vegetation |
5 | High Vegetation |
6 | Building |
7 | Low Point (noise) |
8 | Reserved |
9 | Water |
10 | Rail |
11 | Road Surface |
12 | Reserved |
13 | Wire – Guard (Shield) |
14 | Wire – Conductor (Phase) |
15 | Transmission Tower |
16 | Wire-structure Connector (e.g. Insulator) |
17 | Bridge Deck |
18 | High 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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output LiDAR file |
--exclude_cls | Optional 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'
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output LiDAR file |
--threshold | Scan 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
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output 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"
Author: Dr. John Lindsay
Created: June 14, 2017
Last Modified: 12/10/2018
FlightlineOverlap
Reads a LiDAR (LAS) point file and outputs a raster containing the number of overlapping flight lines in each grid cell.
Parameters:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output file |
--resolution | Output 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
Author: Dr. John Lindsay
Created: 19/06/2017
Last Modified: 19/05/2020
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file (including extension) |
-o, --output | Output raster 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
Author: Dr. John Lindsay
Created: 08/11/2019
Last Modified: 15/12/2019
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 formated 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:
Flag | Description |
---|---|
-i, --inputs | Input 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"
Author: Dr. John Lindsay
Created: 16/07/2017
Last Modified: 29/02/2020
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --input | Input 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
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:
Flag | Description |
---|---|
-i, --inputs | Input LAS files |
--outdir | Output directory into which zlidar files are created. If unspecified, it is assumed to be the same as the inputs |
--compress | Compression method, including 'brotli' and 'deflate' |
--level | Compression 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"
Author: Dr. John Lindsay
Created: 13/05/2020
Last Modified: 15/05/2020
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output file |
--resolution | Output 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
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output file |
--resolution | Output 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
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 shoud follow the LAS specifications below:
Classification Value | Meaning |
---|---|
0 | Created never classified |
1 | Unclassified3 |
2 | Ground |
3 | Low Vegetation |
4 | Medium Vegetation |
5 | High Vegetation |
6 | Building |
7 | Low Point (noise) |
8 | Reserved |
9 | Water |
10 | Rail |
11 | Road Surface |
12 | Reserved |
13 | Wire – Guard (Shield) |
14 | Wire – Conductor (Phase) |
15 | Transmission Tower |
16 | Wire-structure Connector (e.g. Insulator) |
17 | Bridge Deck |
18 | High 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:
Flag | Description |
---|---|
--base | Input base LiDAR file |
--subset | Input subset LiDAR file |
-o, --output | Output LiDAR file |
--subset_class | Subset point class value (must be 0-18; see LAS specifications) |
--nonsubset_class | Non-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
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 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. You may use the LidarTileFootprint tool
to determine the spatial extent of the LAS file.
See Also: LidarTileFootprint
Parameters:
Flag | Description |
---|---|
--in_lidar | Input LiDAR file |
--in_image | Input colour image file |
-o, --output | Output 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"
Author: Dr. John Lindsay
Created: 18/02/2018
Last Modified: 12/10/2018
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file (including extension) |
-o, --output | Output raster file (including extension) |
--resolution | Output raster's grid resolution |
--radius | Search Radius |
--minz | Optional minimum elevation for inclusion in interpolation |
--maxz | Optional maximum elevation for inclusion in interpolation |
--max_triangle_edge_length | Optional 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
Author: Dr. John Lindsay
Created: 16/08/2020
Last Modified: 16/08/2020
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output LiDAR file |
--minz | Minimum elevation value (optional) |
--maxz | Maximum elevation value (optional) |
--class | Optional boolean flag indicating whether points outside the range should be retained in output but reclassified |
--inclassval | Optional parameter specifying the class value assigned to points within the slice |
--outclassval | Optional 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
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output LiDAR file |
--radius | Search Radius |
--min_neighbours | The 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_threshold | Maximum inter-point slope to be considered an off-terrain point |
--height_threshold | Inter-point height difference to be considered an off-terrain point |
--classify | Classify points as ground (2) or off-ground (1) |
--slope_norm | Perform initial ground slope normalization? |
--height_above_ground | Transform 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
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:
Flag | Description |
---|---|
-i, --input | Input base file |
-o, --output | Output vector polygon file |
--width | The grid cell width |
--orientation | Grid 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
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output file |
--azimuth | Illumination source azimuth in degrees |
--altitude | Illumination source altitude in degrees |
--radius | Search 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
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output HTML file (default name will be based on input file if unspecified) |
--parameter | Parameter; options are 'elevation' (default), 'intensity', 'scan angle', 'class' |
--clip | Amount 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
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file (including extension) |
-o, --output | Output raster file (including extension) |
--parameter | Interpolation parameter; options are 'elevation' (default), 'intensity', 'class', 'return_number', 'number_of_returns', 'scan angle', 'rgb', 'user data' |
--returns | Point return types to include; options are 'all' (default), 'last', 'first' |
--resolution | Output raster's grid resolution |
--weight | IDW weight value |
--radius | Search Radius |
--exclude_cls | Optional 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' |
--minz | Optional minimum elevation for inclusion in interpolation |
--maxz | Optional 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'
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:
Flag | Description |
---|---|
-i, --input | Input LiDAR file |
-o, --output | Output HTML file for summary report |
--vlr | Flag indicating whether or not to print the variable length records (VLRs) |
--geokeys | Flag indicating whether or not to print the geokeys |
Python function:
wbt.lidar_info(
i,
output=None,
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
Author: Dr. John Lindsay
Created: 01/06/2017
Last Modified: 18/10/2019
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:
Flag | Description |
---|---|
-i, --inputs | Input LiDAR files |
-o, --output | Output 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"
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:
Flag | Description |
---|---|
--i1, --input1 | Input LiDAR classification file |
--i2, --input2 | Input LiDAR reference file |
-o, --output | Output HTML file |
--class_accuracy | Output classification accuracy raster file |
--resolution | Output 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
Author: Dr. John Lindsay
Created: 24/09/2017
Last Modified: 04/01/2019