whitebox

<!-- badges: start -->

<!-- badges: end -->

WhiteboxTools R Frontend.

This repository is related to the whitebox R package for geospatial analysis, which is an R frontend of a stand-alone executable command-line program called WhiteboxTools.

• Authors: John Lindsay (https://jblindsay.github.io/ghrg/index.html)
• Contributors:
  • Qiusheng Wu (https://wetlands.io)
  • Andrew G. Brown (https://humus.rocks)
• GitHub repo: https://github.com/opengeos/whiteboxR
• CRAN link: https://cran.r-project.org/package=whitebox
• WhiteboxTools: https://github.com/jblindsay/whitebox-tools
• User Manual: https://jblindsay.github.io/wbt_book/
• Free software: MIT license

Contents

1. Description
2. Installation
3. Usage
4. Available Tools
5. Contributing
6. License
7. Reporting Bugs

Description

The whitebox R package is built on WhiteboxTools, an advanced geospatial data analysis platform developed by Prof. John Lindsay (webpage; jblindsay) at the University of Guelph’s Geomorphometry and Hydrogeomatics Research Group. 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 mosaicing, numerous filtering operations, simple classification (k-means), and common image transformations. WhiteboxTools also contains advanced tooling for spatial hydrological analysis (e.g. flow-accumulation, watershed delineation, stream network analysis, sink removal), terrain 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. Suggested citation: Lindsay, J. B. (2016). Whitebox GAT: A case study in geomorphometric analysis. Computers & Geosciences, 95, 75-84. doi: http://dx.doi.org/10.1016/j.cageo.2016.07.003

Installation

There are three ways to install the whitebox R package.

1. CRAN

whitebox is now available on CRAN, so you can install it with:

install.packages("whitebox")

2. GitHub

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

if (!require("remotes")) install.packages('remotes')
remotes::install_github("opengeos/whiteboxR", build = FALSE)

Usage

The function wbt_init() checks the path to the ‘WhiteboxTools’ binary.

wbt_init()

It (invisibly) returns a logical (TRUE/FALSE) value reflecting whether a file is found at one of the default paths, including those specified by package options. See ?whitebox::whitebox.

If you have ‘WhiteboxTools’ installed already but in a non-standard location run wbt_init(exe_path=...) to set up your options for your current R session.

wbt_init(exe_path = 'C:/home/user/path/to/whitebox_tools.exe')

Additional arguments to wbt_init() can set other package options, such as whether tools print their standard console output with cat().

If you want to turn this off, set verbose = FALSE, for instance:

wbt_init(exe_path = 'C:/home/user/path/to/whitebox_tools.exe', verbose = FALSE)

Documentation

For whitebox package documentation in R, ask for help:

??whitebox

For list of functions, try the wbt_ prefix in your search:

??wbt_

A complete list of functions available in the whitebox R package can be found HERE.

Check out this demo for examples.

Installing ‘WhiteboxTools’

The quickest way to get started if you are on 64-bit Windows, Linux or MacOS architectures is to download and install the ‘WhiteboxTools’ binary. Linux binaries compiled with ‘musl’ instead of ‘glibc’ on Ubuntu 22.04 are available with platform="linux_musl". On MacOS, Intel and Apple ‘M’ series processors (‘arm64’) are supported.

A method install_whitebox() is provided to download a version of the binaries that corresponds to the wrapper functions available in the package.

whitebox::install_whitebox()

By default this will install ‘WhiteboxTools’ to your whitebox R package data directory (see wbt_data_dir()), subdirectory “WBT”.

whitebox

How do I run tools?

Tool names in the whitebox R package can be called by corresponding function using wbt_snake_case() naming convention (e.g. wbt_lidar_info() R function for "LidarInfo" ‘WhiteboxTools’ tool name).

First we load the library and perform any necessary setup.

library(whitebox)

# set up as needed
wbt_init()

Many ‘WhiteboxTools’ will take GeoTIFF files as input, but ‘WhiteboxTools’ supports several grid input formats. There is a sample Digital Elevation Model (DEM) included in the whitebox package. You can get path as follows for this demo:

# Set input raster DEM file
dem <- sample_dem_data()

We will use this DEM in a sequence of ‘WhiteboxTools’ processing routines. Run tools by passing file paths for the input and output files.

1. Apply feature-preserving smoothing (FeaturePreservingSmoothing)

2. Breach depressions in a DEM (BreachDepressions)

3. Calculate D-Infinity flow accumulation (DInfFlowAccumulation)

The filter argument to wbt_feature_preserving_smoothing() sets the size of the filter kernel.

## 1. FeaturePreservingSmoothing
wbt_feature_preserving_smoothing(
  dem = dem,
  output = "./smoothed.tif",
  filter = 9
)

## 2. BreachDepressions
wbt_breach_depressions(dem = "./smoothed.tif", output = "./breached.tif")

## 3. DInfFlowAccumulation
wbt_d_inf_flow_accumulation(input = dem, output = "./flow_accum.tif")

if (requireNamespace('terra')) {
  terra::plot(terra::rast("./flow_accum.tif"))
}
#> Loading required namespace: terra

<img src="man/figures/README-terra-plot-facc-1.jpeg" width="100%" />

About ‘WhiteboxTools’

library(whitebox)

# cat() output in non-interactive mode
wbt_verbose(TRUE)

# Prints the whitebox-tools help...a listing of available commands
wbt_help()
#> WhiteboxTools Help
#> 
#> The following commands are recognized:
#> --cd, --wd          Changes the working directory; used in conjunction with --run flag.
#> --compress_rasters  Sets the compress_raster option in the settings.json file; determines if newly created rasters are compressed. e.g. --compress_rasters=true
#> -h, --help          Prints help information.
#> -l, --license       Prints the whitebox-tools license. Tool names may also be used, --license="Slope"
#> --listtools         Lists all available tools. Keywords may also be used, --listtools slope.
#> --max_procs         Sets the maximum number of processors used. -1 = all available processors. e.g. --max_procs=2
#> -r, --run           Runs a tool; used in conjunction with --wd 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.
#> 
#> Example Usage:
#> >> ./whitebox_tools -r=lidar_info --cd="/path/to/data/" -i=input.las --vlr --geokeys

# Prints the whitebox-tools license
wbt_license()
#> WhiteboxTools License
#> Copyright 2017-2023 John Lindsay
#> 
#> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
#> associated documentation files (the "Software"), to deal in the Software without restriction,
#> including without limitation the rights to use, copy,