WhiteboxTools Frontends

WhiteboxTools is an advanced geospatial data analysis platform developed by Prof. John Lindsay at the University of Guelph's Geomorphometry and Hydrogeomatics Research Group. The WhiteboxTools library currently contains 440 tools, which are each grouped based on their main function into one of the following categories: Data Tools, GIS Analysis, Hydrological Analysis, Image Analysis, LiDAR Analysis, Mathematical and Statistical Analysis, Stream Network Analysis, and Terrain Analysis. For a listing of available tools, complete with documentation and usage details, please see the WhiteboxTools User Manual.

WhiteboxTools can be accessed either from a command prompt (i.e. terminal) or through one of the following front-ends:

• Python Package
• R Package
• ArcGIS Python Toolbox
• QGIS Plugin
• Command-line Interface

Python Package

Links

• GitHub repo: https://github.com/giswqs/whitebox-python
• PyPI: https://pypi.org/project/whitebox/
• conda-forge: https://anaconda.org/conda-forge/whitebox
• Documentation: https://whitebox.readthedocs.io
• Maintainer: Qiusheng Wu

Installation

The whitebox Python package can be installed using the following command:

pip install whitebox

The whitebox Python package is also available on conda-forge, which can be installed using the following command:

conda install -c conda-forge whitebox

Usage

Tool names in the whitebox Python package can be called using the snake_case convention (e.g. lidar_info). See below for an example Python script.

import os
import pkg_resources
import whitebox

wbt = whitebox.WhiteboxTools()
print(wbt.version())
print(wbt.help())

# identify the sample data directory of the package
data_dir = os.path.dirname(pkg_resources.resource_filename("whitebox", 'testdata/'))

wbt.set_working_dir(data_dir)
wbt.verbose = False
wbt.feature_preserving_smoothing("DEM.tif", "smoothed.tif", filter=9)
wbt.breach_depressions("smoothed.tif", "breached.tif")
wbt.d_inf_flow_accumulation("breached.tif", "flow_accum.tif")

WhiteboxTools also provides a Graphical User Interface (GUI) - WhiteboxTools Runner, which can be invoked using the following Python script:

import whitebox
whitebox.Runner()

R Package

Links

• GitHub repo: https://github.com/giswqs/whiteboxR
• R-Forge: https://r-forge.r-project.org/R/?group_id=2337
• Documentation: https://giswqs.github.io/whiteboxR/
• Maintainer: Qiusheng Wu

Installation

The whitebox R package is available on R-Forge, which can be installed using the following command:

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

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

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

RStudio Screenshot

Usage

Tool names in the whitebox R package can be called using the snake_case (e.g. wbt_lidar_info). See below for an example.

library(whitebox)

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

# Run tools
wbt_feature_preserving_smoothing(dem, "./smoothed.tif", filter=9, verbose_mode = TRUE)
wbt_breach_depressions("./smoothed.tif", "./breached.tif")
wbt_d_inf_flow_accumulation(dem, "./flow_accum.tif")

ArcGIS Python Toolbox

Links

• GitHub repo: https://github.com/giswqs/WhiteboxTools-ArcGIS
• Maintainer: Qiusheng Wu

Installation

Step 1: Download the toolbox

1. Go to the WhiteboxTools-ArcGIS GitHub repo and click the green button (Clone or download) on the upper-right corner of the page to download the toolbox as a zip file.

   

2. Depcompress the downloaded zip file.

Step 2: Connect to the toolbox

1. Navigate to the Folder Connections node in the catalog window tree.

2. Right-click the node and choose Connect To Folder.

   

3. Type the path or navigate to the WhiteboxTools-ArcGIS folder and click OK.

4. Browse into the toolbox and start using its tools.

   

Usage

Open any tool within the toolbox and start using it. Check out the WhiteboxTools User Mannual for more detailed help documentation of each tool.

ArcGIS Pro Screenshot

ArcMap Screenshots

QGIS Plugin

Links

• Documentation: https://jblindsay.github.io/wbt_book/qgis_plugin.html
• GitHub repo: https://github.com/alexbruy/processing-wbt
• Maintainer: Alexander Bruy

Installation

Please follow the installation guide here.

Screenshot

Command-line Interface

Links

• GitHub repo: https://github.com/jblindsay/whitebox-tools
• User Manual: https://jblindsay.github.io/wbt_book/index.html
• Maintainer: John Lindsay

Installation

You can download a copy of the WhiteboxTools executable for your operating system from the Geomorphometry and Hydrogeomatics Research Group website. Once you've downloaded WhiteboxTools and decompressed (unzipped) the folder, you can open a command prompt and start using it.

Usage

WhiteboxTools is a command-line program and can be run by calling it with appropriate commands and arguments, from a terminal application. 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; --toolparameters="LidarInfo".
-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 hyphen (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).

For examples of how to call functions and run tools from WhiteboxTools, see the whitebox_example.py Python script, which itself uses the whitebox_tools.py script as an interface for interacting with the executable file.

In addition to direct command-line and script-based interaction, a very basic user-interface called WB Runner can be used to call the tools within the WhiteboxTools executable file, providing the required tool arguments.

Example command prompt:

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

Notice the quotation marks (single or double) used around directories and filenames, and string tool arguments in general. Use the '-v' flag (run in verbose mode) to force the tool 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. The '>>' is shorthand for the command prompt and is not intended to be typed. 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.