whitebox examples

Qiusheng Wu

2019-02-03

About WhiteboxTools

Load the whitebox R package.

library(whitebox)

Prints the whitebox-tools help…a listing of available commands.

print(wbt_help())
##  [1] "whitebox-tools Help"                                                                                       
##  [2] ""                                                                                                          
##  [3] "The following commands are recognized:"                                                                    
##  [4] "--cd, --wd       Changes the working directory; used in conjunction with --run flag."                      
##  [5] "-h, --help       Prints help information."                                                                 
##  [6] "-l, --license    Prints the whitebox-tools license."                                                       
##  [7] "--listtools      Lists all available tools. Keywords may also be used, --listtools slope."                 
##  [8] "-r, --run        Runs a tool; used in conjuction with --wd flag; -r=\"LidarInfo\"."                        
##  [9] "--toolbox        Prints the toolbox associated with a tool; --toolbox=Slope."                              
## [10] "--toolhelp       Prints the help associated with a tool; --toolhelp=\"LidarInfo\"."                        
## [11] "--toolparameters Prints the parameters (in json form) for a specific tool; --toolparameters=\"LidarInfo\"."
## [12] "-v               Verbose mode. Without this flag, tool outputs will not be printed."                       
## [13] "--viewcode       Opens the source code of a tool in a web browser; --viewcode=\"LidarInfo\"."              
## [14] "--version        Prints the version information."                                                          
## [15] ""                                                                                                          
## [16] "Example Usage:"                                                                                            
## [17] ">> ./whitebox-tools -r=lidar_info --cd=\"/path/to/data/\" -i=input.las --vlr --geokeys"                    
## [18] ""

Prints the whitebox-tools license.

print(wbt_license())
##  [1] "whitebox-tools License"                                                                               
##  [2] "Copyright 2017-2019 John Lindsay"                                                                     
##  [3] ""                                                                                                     
##  [4] "Permission is hereby granted, free of charge, to any person obtaining a copy of this software and"    
##  [5] "associated documentation files (the \"Software\"), to deal in the Software without restriction,"      
##  [6] "including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,"
##  [7] "and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,"
##  [8] "subject to the following conditions:"                                                                 
##  [9] ""                                                                                                     
## [10] "The above copyright notice and this permission notice shall be included in all copies or substantial" 
## [11] "portions of the Software."                                                                            
## [12] ""                                                                                                     
## [13] "THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT"  
## [14] "NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND"               
## [15] "NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES" 
## [16] "OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN"  
## [17] "CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."

Prints the whitebox-tools version.

print(wbt_version())
## [1] "whitebox-tools v0.14.0 by Dr. John B. Lindsay (c) 2017-2019"

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"))
##  [1] "LidarInfo"                                                                                                                                                                              
##  [2] "Description:"                                                                                                                                                                           
##  [3] "Prints information about a LiDAR (LAS) dataset, including header, point return frequency, and classification data and information about the variable length records (VLRs) and geokeys."
##  [4] "Toolbox: LiDAR Tools"                                                                                                                                                                   
##  [5] "Parameters:"                                                                                                                                                                            
##  [6] "Flag               Description"                                                                                                                                                         
##  [7] "-----------------  -----------"                                                                                                                                                         
##  [8] "-i, --input        Input LiDAR file."                                                                                                                                                   
##  [9] "-o, --output       Output HTML file for summary report."                                                                                                                                
## [10] "--vlr              Flag indicating whether or not to print the variable length records (VLRs)."                                                                                         
## [11] "--geokeys          Flag indicating whether or not to print the geokeys."                                                                                                                
## [12] "Example usage:"                                                                                                                                                                         
## [13] ">>./tmpRtmpTW2o3HRinst452361794914whiteboxWBTwhitebox_tools -r=LidarInfo -v --wd=\"/path/to/data/\" -i=file.las --vlr --geokeys\""                                                      
## [14] "./tmpRtmpTW2o3HRinst452361794914whiteboxWBTwhitebox_tools -r=LidarInfo --wd=\"/path/to/data/\" -i=file.las"

Retrieves the tool parameter descriptions for a specific tool.

print(wbt_tool_parameters("slope"))
## [1] "{\"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\":\"1.0\",\"optional\":true}]}"

View the source code for a specific tool on the source code repository.

print(wbt_view_code("breach_depressions"))
## [1] "https://github.com/jblindsay/whitebox-tools//tree/master/src/tools/hydro_analysis/breach_depressions.rs"

How to run tools?

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, verbose_mode = TRUE)
breach_depressions("./smoothed.tif", "./breached.tif")
d_inf_flow_accumulation(dem, "./flow_accum.tif")