Add `wbt_options()` and wbt utils updates

[brownag]

cat()/invisible() output for wbt.R

• Console output from tools is returned invisibly, and when verbose is TRUE (interactive use, or if option is set) it is nicely cat() out for readability

Cleanup

• added package documentation page with documentation of new options and key functions
• wbt_run_tool(): use gsub() not substring() should be more robust to whether uses R package function names with "wbt_" prefix or results from wbt_list_tools(); gsub() logic abstracted and used in other cases where tool_name is used as argument in wbt.R
• wbt_view_code(): Add viewer argument that uses utils::browseURL to navigate to the github rust source code; tests only use FALSE for this new arg

Add tests for wbt utils in wbt.R

• Includes a few simple tests that do not require WhiteboxTools

Add wbt_options() and wbt_verbose()

• Set environment variable R_WHITEBOX_VERBOSE or option whitebox.verbose to over-ride default (interactive()) value
• wbt_options(): optionally specify either exe_path or verbose arguments; returns invisible list of current settings
• wbt_verbose(): logical argument verbosesets option whitebox.verbose and returns the value of the option

wbt_init/install logic changes

• wbt_init() should not set sys env var R_WHITEBOX_EXE_PATH, only option whitebox.exe_path
• wbt_install() should not error if one of the three options for pre-compiled binaries are not met
• Better messages about installation options/setup

[brownag]

A demo of functionality:

library(whitebox)
#> 
#> ------------------------------------------------------------------------
#> Could not find WhiteboxTools Binary!
#> ------------------------------------------------------------------------
#> 
#> Your next step is to download and install the WhiteboxTools binary:
#>     > whitebox::install_whitebox()
#> 
#> If you have WhiteboxTools installed already, set the path with:
#>     > Sys.setenv(R_WHITEBOX_EXE_PATH = 'C:/path/to/whitebox_tools.exe')
#> 
#> Or run `wbt_init()` to set package option 'whitebox.exe_path': 
#>     > wbt_init('/home/user/path/to/whitebox_tools')
#> 
#> For whitebox package documentation, ask for help:
#>     > ??whitebox
#> 
#> For more information visit https://giswqs.github.io/whiteboxR/
#> 
#> ------------------------------------------------------------------------

# returns false because I have not run install_whitebox() to create WBT folder in package
wbt_init()
#> [1] FALSE

# force output when run non-interactively
wbt_verbose(TRUE)
#> [1] TRUE

# set path to custom whitebox_tools executable
wbt_init('/home/andrew/workspace/whitebox-tools/target/release/whitebox_tools')
#> [1] TRUE

# Prints the whitebox-tools help: a listing of available commands for executable
wbt_help()
#> WhiteboxTools Help
#> 
#> The following commands are recognized:
#> --cd, --wd       Changes the working directory; used in conjunction with --run flag.
#> -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.
#> -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-2020 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, modify, merge, publish, distribute, sublicense,
#> and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
#> subject to the following conditions:
#> 
#> The above copyright notice and this permission notice shall be included in all copies or substantial
#> portions of the Software.
#> 
#> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
#> NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
#> NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
#> OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
#> CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

# Prints the whitebox-tools version
wbt_version()
#> WhiteboxTools v1.5.0 by Dr. John B. Lindsay (c) 2017-2021
#> 
#> WhiteboxTools is an advanced geospatial data analysis platform developed at
#> the University of Guelph's Geomorphometry and Hydrogeomatics Research 
#> Group (GHRG). See www.whiteboxgeo.com for more details.

# Prints the toolbox for a specific tool (or all tools if none specified)
wbt_toolbox("aspect")
#> Geomorphometric Analysis

# List all available tools in whitebox-tools (n=448)
# wbt_list_tools()

# Lists tools with keyword 'wetness' in tool name or description.
wbt_list_tools("wetness")
#> All 1 Tools containing keywords:
#> WetnessIndex: Calculates the topographic wetness index, Ln(A / tan(slope)).

# Prints the help for a specific tool.
wbt_tool_help("tributaryidentifier")
#> TributaryIdentifier
#> Description:
#> Assigns a unique identifier to each tributary in a stream network.
#> Toolbox: Stream Network Analysis
#> Parameters:
#> 
#> Flag               Description
#> -----------------  -----------
#> --d8_pntr          Input raster D8 pointer file.
#> --streams          Input raster streams file.
#> -o, --output       Output raster file.
#> --esri_pntr        D8 pointer uses the ESRI style scheme.
#> --zero_background  Flag indicating whether a background value of zero should be used.
#> 
#> 
#> Example usage:
#> >>./homeandrewworkspacewhitebox-toolstargetreleasewhitebox_tools -r=TributaryIdentifier -v --wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif -o=output.tif
#> >>./homeandrewworkspacewhitebox-toolstargetreleasewhitebox_tools -r=TributaryIdentifier -v --wd="/path/to/data/" --d8_pntr=D8.tif --streams=streams.tif -o=output.tif --esri_pntr --zero_background

# Retrieves the tool parameter descriptions for a specific tool.
wbt_tool_parameters("slope")
#> {"parameters": [{"name":"Input DEM File","flags":["-i","--dem"],"description":"Input raster DEM file.","parameter_type":{"ExistingFile":"Raster"},"default_value":null,"optional":false},{"name":"Output File","flags":["-o","--output"],"description":"Output raster file.","parameter_type":{"NewFile":"Raster"},"default_value":null,"optional":false},{"name":"Z Conversion Factor","flags":["--zfactor"],"description":"Optional multiplier for when the vertical and horizontal units are not the same.","parameter_type":"Float","default_value":null,"optional":true},{"name":"Units","flags":["--units"],"description":"Units of output raster; options include 'degrees', 'radians', 'percent'","parameter_type":{"OptionList":["degrees","radians","percent"]},"default_value":"degrees","optional":true}]}

# View the source code for a specific tool on the source code repository.
wbt_view_code("breach_depressions")
#> https://github.com/jblindsay/whitebox-tools/blob/master/whitebox-tools-app/src/tools/hydro_analysis/breach_depressions.rs