whitebox Demo

How whitebox works

whitebox generates system() calls to a local WhiteboxTools binary: whitebox_tools or whitebox_tools.exe

You can find the binary path that the package is going to use with wbt_exe_path()

wbt_exe_path(shell_quote = FALSE)

This command always returns a “default” path, whether or not you have WhiteboxTools installed.

Interfacing with R spatial packages

WhiteboxTools input and output are specified as file paths to rasters in GeoTIFF format, shapefiles, HTML output, LiDAR-related files, and more.

In this vignette we will use the terra package for visualization. Just as easily we could have used raster, stars or other options available in the R ecosystem for handling the GeoTIFF output.

The main way to view your output is to save “output” file paths as a variable so that you can use them after processing to load the result into an R spatial object.

library(terra)
library(whitebox)

# DEMO: calculate slope with WhiteboxTools and raster

# Typically the input/output paths are stored as variables

# sample DEM input GeoTIFF
input <- sample_dem_data()

# output file (to be created)
output <- file.path(tempdir(), "slope.tif")

wbt_slope(input, output, units = 'radians')

if (file.exists(output)) {
  # create a SpatRaster from file output path
  outputras <- terra::rast(output)
}

if (file.exists(input) && file.exists(output) && !is.null(outputras)) {
  # par(mfrow = c(2, 1), mar = c(1, 1, 1, 1))
  
  # inspect the output graphically
  plot(
    outputras,
    main = "whitebox::wbt_slope() [radians]",
    axes = FALSE
  )
  
  # calculate equivalent using raster::terrain() on input
  plot(
    terra::terrain(terra::rast(input)),
    main = "terra::terrain() [radians]",
    axes = FALSE
  )
}

# the SpatRaster retains a reference to the input file name
terra::sources(outputras)

WhiteboxTools R setup

Installing WhiteboxTools

In whitebox wbt_init() is the standard way to set the “exe_path” for a session.

If you do not have WhiteboxTools installed in the default location, do not have whitebox_tools on your PATH, and have not set up your package options, the package will not be able to find your WhiteboxTools installation on load.

Usually you can use whitebox::install_whitebox() to download the latest binaries that correspond to the available version of the R package. However, this is not required. You may download/compile WhiteboxTools yourself and install anywhere for use with the whitebox R package.

For general information consult the WhiteboxTools User Manual: https://www.whiteboxgeo.com/manual/wbt_book/install.html

For more details on building from source see: https://github.com/jblindsay/whitebox-tools

Package Settings with wbt_init()

wbt_init() is used to set and check the path of the binary executable that commands are passed to.

The executable path and other options are stored as package options, and can be overridden by system environment variables. A default value wbt_exe_path(shell_quote = FALSE) is passed when the exe_path argument is unspecified.

# inspect where wbt_init() will be checking
wbt_exe_path(shell_quote = FALSE)

# TRUE when file is found at one of the user specified paths or package default
# FALSE when whitebox_tools does not exist at path
wbt_init()

This section will cover optional arguments to wbt_init() (exe_path, wd and verbose) and their corresponding options and helper functions.

# set path manually to whitebox_tools executable, for instance:
wbt_init(exe_path = '/home/andrew/workspace/whitebox-tools/target/release/whitebox_tools')

wbt_wd("") # "" equivalent to getwd()

# force output when run non-interactively (knitr)
wbt_verbose(TRUE)

#> wbt_breach_depressions - Elapsed Time (excluding I/O): 0.12s

Long-term Package Option Settings

The package will detect when you have added the WhiteboxTools directory to your PATH environment variable. For long-term package option settings you can put whitebox_tools on $PATH or set R_WHITEBOX_EXE_PATH in your user .Rprofile or .Renviron.

On Windows you can add the path to whitebox_tools.exe as a new entry R_WHITEBOX_EXE_PATH in User or System Environment variable.

On Linux/Mac you can set R_WHITEBOX_EXE_PATH directly with export R_WHITEBOX_EXE_PATH="/path/to/whitebox_tools".

• Note that if you set your $PATH in you regular shell profile (.profile/.bashrc/.zshrc) then it will not be sourced by RStudio for your R session by default.

This requires that you have the Unix tool which or one of its analogues.

You can also set R_WHITEBOX_EXE_PATH manually in R:

Sys.setenv(R_WHITEBOX_EXE_PATH = Sys.which("whitebox_tools"))

• Replace the Sys.which() call with a custom path string as needed such as "C:/path/to/whitebox_tools.exe".

All of the other package options can similarly be set as environment variables. They are prefixed with R_WHITEBOX_*. See ?whitebox for details.

Example: Compare input v.s. output with terra

We use the {terra} package to read the GeoTIFF file output by WhiteboxTools.

library(terra)

# sample DEM file path in package extdata folder
input <- sample_dem_data()

# output file name
output <- file.path(tempdir(), "output.tif")

# run breach_depressions tool
wbt_breach_depressions(dem = input, output = output)

# create raster object from input file
input <- rast(input)

if (file.exists(output)) {
  # create raster object from output file
  output <- rast(output)
  
  # par(mar = c(2, 1, 2, 1))
  # inspect input v.s. output
  plot(input, axes = FALSE, main = "DEM")
  plot(output, axes = FALSE, main = "DEM (Breached Depressions)")
  
  # inspect numeric difference (output - input) 
  plot(output - input, axes = FALSE,  main = "Difference ([Breached Depressions] - [DEM])")
}

Example: Identifying Tributaries

Here we will take our processing of DEMs a bit further by performing several WhiteboxTools operations in sequence.

We are interested in identifying and ranking tributaries of watercourses (streams and rivers).

An R package that makes use of the whitebox R package is hydroweight. Here is a brief example on the beginning of the hydroweight README showing how the breached DEM above can be used in a spatial analysis of stream networks.

library(whitebox)
library(terra)

## Sample DEM from whitebox package
toy_file <- sample_dem_data()
toy_dem <- rast(x = toy_file)

## Generate wd as a temporary directory. 
## Replace with your own path, or "." for current directory
wd <- tempdir()

## Write toy_dem to working directory
writeRaster(
  x = toy_dem, filename = file.path(wd, "toy_dem.tif"),
  overwrite = TRUE
)

## Breach depressions to ensure continuous flow
wbt_breach_depressions(
  dem = file.path(wd, "toy_dem.tif"),
  output = file.path(wd, "toy_dem_breached.tif")
)

## Generate d8 flow pointer (note: other flow directions are available)
wbt_d8_pointer(
  dem = file.path(wd, "toy_dem_breached.tif"),
  output = file.path(wd, "toy_dem_breached_d8.tif")
)

## Generate d8 flow accumulation in units of cells (note: other flow directions are available)
wbt_d8_flow_accumulation(
  input = file.path(wd, "toy_dem_breached.tif"),
  output = file.path(wd, "toy_dem_breached_accum.tif"),
  out_type = "cells"
)

## Generate streams with a stream initiation threshold of 100 cells
wbt_extract_streams(
  flow_accum = file.path(wd, "toy_dem_breached_accum.tif"),
  output = file.path(wd, "toy_dem_streams.tif"),
  threshold = 100
)

wbt_tributary_identifier(
  d8_pntr = file.path(wd, "toy_dem_breached_d8.tif"),
  streams = file.path(wd, "toy_dem_streams.tif"),
  output = file.path(wd, "toy_dem_tributaries.tif")
)

if (file.exists(file.path(wd, "toy_dem_streams.tif"))) {
  par(mfrow = c(2, 1), mar = c(3, 1, 2, 1))
  
  plot(
    rast(file.path(wd, "toy_dem_streams.tif")),
    main = "Streams",
    col = "black"
  )
  
  plot(
    rast(file.path(wd, "toy_dem_tributaries.tif")),
    main = "TributaryIdentifier"
  )
}

wbt_help()

wbt_help() prints the WhiteboxTools help: a listing of available commands for executable

wbt_help()

wbt_license()

wbt_license() prints the WhiteboxTools license

wbt_license()

wbt_version()

Prints the WhiteboxTools version

wbt_version()

wbt_list_tools()

Use wbt_list_tools() to list all available tools in WhiteboxTools. In version 2.4.0 there are over 0 tools! See all the available toolboxes and extensions.

wbt_list_tools()

The full list can be an overwhelming amount of output, so you pass the keywords argument to search and filter.

For example we list tools with keyword ‘flowaccumulation’ in tool name or description.

wbt_list_tools(keywords = "flowaccumulation")

wbt_tool_help()

Once we find a tool that we are interested in using, we can investigate what sort of parameters it takes. The R methods generally take the same named parameters.

R functions have the naming scheme wbt_tool_name where _ is used for spaces, whereas the tools themselves have no spaces.

wbt_tool_help("tributaryidentifier") shows the command line help for a tool by name.

wbt_tool_help("tributaryidentifier")

?wbt_tributary_identifier shows the corresponding R function help, which is derived from the command line help page and other metadata.

wbt_toolbox()

Another way that tools are organized in WhiteboxTools is by “toolbox.”

wbt_toolbox() prints the toolbox for a specific tool (or all tools if none specified)

wbt_toolbox(tool_name = "aspect")

Print the full list by not specifying tool_name

wbt_toolbox()

wbt_tool_parameters()

wbt_tool_parameters() retrieves the tool parameter descriptions for a specific tool as JSON formatted string.

wbt_tool_parameters("slope")

wbt_view_code()

WhiteboxTools is written in Rust and is open source. You can view the source code for a specific tool on the source code repository.

wbt_view_code("breach_depressions")

Use the argument viewer=TRUE to use browseURL() to open a browser window to the corresponding GitHub page.