README.md

whiteboxR

Binder Binder Build Status AppVeyor build status docs License: MIT Donate

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.

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, analyized 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:10.1016/j.cageo.2016.07.003.

Installation

There are three ways to install the whitebox R package.

1. CRAN

whitebox will be available on CRAN soon. Once it is available on CRAN, you can install it with:

install.packages("whitebox")

2. R-Forge

whitebox is now available on R-Forge, so you can install it with:

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

3. GitHub

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

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

You’ll 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 HERE. Check out this demo for examples.

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). See below for an example. If you are interested in using the WhiteboxTools command-line program, check WhiteboxTools Usage.

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)

Available Tools

The WhiteboxTools library currently contains more than 396 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. The following is a complete listing of available tools, with brief tool descriptions.

Data Tools

Geomorphometric Analysis

GIS Analysis

Hydrological Analysis

Image Analysis

LiDAR Analysis

Mathematical and Statistical Analysis

Stream Network Analysis

Contributing

If you would like to contribute to the project as a developer, follow these instructions to get started:

  1. Fork the whiteboxR repository (https://github.com/giswqs/whiteboxR)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion in the work shall be licensed as the MIT license without any additional terms or conditions.

License

The WhiteboxR package is distributed under the MIT license, a permissive open-source (free software) license.

Reporting Bugs

whiteboxR is distributed as is and without warranty of suitability for application. If you encounter flaws with the software (i.e. bugs) please report the issue. Providing a detailed description of the conditions under which the bug occurred will help to identify the bug. Use the Issues tracker on GitHub to report issues with the software and to request feature enchancements. Please do not email Dr. Lindsay directly with bugs.



Try the whitebox package in your browser

Any scripts or data that you put into this service are public.

whitebox documentation built on Feb. 8, 2019, 1:04 a.m.