Setup
Load the whitebox library.
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()
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.
Working with Raster Data
A demonstration employing the {terra} package follows:
library(terra)
#> terra 1.7.60
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")Run a tool such as wbt_slope() or
"Slope".
WhiteboxTools reads from input and writes to
output.
if (file.exists(output)) {
# create a SpatRaster from file output path
outputras <- terra::rast(output)
}In this case, we can achieve a similar slope map result using
terra::terrain(), so we will create and plot a SpatRaster
from output and compare the two.
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, RasterLayer and related
classes in the terra and raster packages are perfect for maintaining the
linkage between file output and an R object with the data in or out of
memory.
Use terra::sources() to get the “source” file name(s).
If you are using a raster RasterLayer objects the
equivalent method is raster::filename().
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)
#> [1] "/home/andrew/.local/share/R/whitebox/WBT/whitebox_tools"
# 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.
exe_path argument
The exe_path argument to wbt_init() sets
the whitebox.exe_path package option. exe_path
is the path to a WhiteboxTools executable file. The default value is the
package installation directory, subdirectory "WBT",
followed by whitebox_tools.exe or
whitebox_tools depending on your operating system.
# set path manually to whitebox_tools executable, for instance:
wbt_init(exe_path = '/home/andrew/workspace/whitebox-tools/target/release/whitebox_tools')The package will automatically find an existing installation when
whitebox_tools is in a directory on your PATH.
Package options other than exe_path (as detailed in
?whitebox::whitebox and ?wbt_init) can be set
with wbt_init(exe_path, ...), where ... is
additional named arguments corresponding to the * suffix in
whitebox.* package options names. Use
wbt_options() or specific methods like
wbt_verbose(), wbt_wd() to get all values or
set specific values.
wd argument
The wd argument can be used to set the WhiteboxTools
working directory.
A working directory specifies a base folder path where WhiteboxTools
can find inputs and create outputs. Setting the whitebox.wd
package option (via the wd argument to
wbt_init() or wbt_wd()) aids the process of
setting file paths. If a value is set for the option the
--wd directory flag is added for tools that support it.
Before you set the working directory in a session the default output
will be in your current R working directory unless directory is
specified in your input/output arguments. You can change working
directory at any time by setting the wd argument to
wbt_wd() and running a tool.
NOTE: once you have set a working directory in a session, the directory needs to be set somewhere new to “replace” the old value; just dropping the flag will not automatically change the working directory back to your R working directory* and your output will show up in whatever folder you set initially.
A helper method for setting the whitebox.wd option is
wbt_wd().
To “unset” the option in the R package you can use
wbt_wd("") which is equivalent to
wbt_wd(getwd()). The next tool call will change the
WhiteboxTools working directory setting to the new path. After this
point the flag need not be specified [until you wish to change
again].
verbose argument
The verbose argument is used to set the package option
related to tool “verbosity”: whitebox.verbose. When
whitebox.verbose is FALSE no output will be
cat() to the console by running tools.
A helper method for getting and setting the
whitebox.verbose option is wbt_verbose().
wbt_verbose() is used throughout the package to check what
level of verbosity should be used.
By default, the result of wbt_verbose() is the result of
interactive() so tools will print extra console output when
you are there to see it. This is used in a variety of wbt_*
methods to allow the package option to control output for many functions
in a consistent manner, hide output in your automated tests, markdown
documents, vignettes etc.
In this vignette we use wbt_verbose(TRUE) so the package
option whitebox.verbose is set to TRUE
This is mainly to print out the tool name and elapsed time whenever we run a tool:
#> wbt_breach_depressions - Elapsed Time (excluding I/O): 0.12sThis package-level verbose option can also control the
verbose_mode values passed to wbt_* tool
functions. Turning on “full” output requires a third option to be set
for this argument: "all". Use
wbt_verbose("all"). wbt_verbose() will still
return TRUE when the whitebox.verbose option
is "all".
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
$PATHin 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:
- 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.
