Whitebox.jl
A Julia frontend for WhiteboxTools
WhiteboxTools is an open-source command-line program for geospatial analysis created by Dr. John Lindsay.
Whitebox.jl installs WhiteboxTools (v2.1.0) and allows users to run any WhiteboxTools function from Julia.
Notes
- Whitebox.jl is not affiliated with WhiteboxTools.
- This package is in active development and testing.
- Report bugs here.
Installation
Whitebox.jl can be installed from the Pkg REPL (press ]
in the Julia REPL):
pkg> add Whitebox
Or directly from GitHub:
using Pkg
Pkg.add(url = "https://github.com/acgold/Whitebox.jl.git")
Installing Whitebox.jl will automatically install a version of WhiteboxTools within the Whitebox.jl package directory (see more about this in How it works)
Quick Example
Adapted from the Python frontend example.
import Whitebox as wbt
# Some helper functions
wbt.version()
wbt.help()
# Set working directory to your data location. By default, it is your project's working directory (found via `pwd()`)
wbt.set_working_dir(joinpath(pwd(),"Data"))
# Set the verbose mode to `false` if you want less printing
wbt.set_verbose_mode(false)
# Run some hydrology tools!
wbt.feature_preserving_smoothing(dem = "DEM.tif", output = "smoothed.tif")
wbt.breach_depressions(dem = "smoothed.tif", output = "breached.tif")
wbt.d_inf_flow_accumulation(i = "breached.tif", output = "flow_accum.tif")
Getting Started
Load the package
Load Whitebox.jl into your project with:
import Whitebox as wbt
Loading the package automatically configures your WhiteboxTools session by:
- Setting the working directory for WhiteboxTools to your current working directory (found with
pwd()
) - Setting the the path to the WhiteboxTools version that was installed with Whitebox.jl
- Setting up miscellaneous defaults such as the printing of results
In other words, just load the package and you should be good to go! Read more about this in How it works.
Find tools
WhiteboxTools contains approximately 485 tools that are organized into the following thematic toolboxes:
- Data Tools
- Geomorphometric Analysis
- GIS Analysis
- Hydrologic Analysis
- Image Analysis
- LiDAR Analysis
- Mathematical and Statistical Analysis
- Precision Agriculture
- Stream Network Analysis
Whitebox.jl provides a function to use each of the the tools provided by WhiteboxTools. Functions in Whitebox.jl use the snake_case convention for WhiteboxTools tool names.
For example, to use the AbsoluteValue
tool, you would use wbt.absolute_value()
.
View the Whitebox.jl Reference section for a full list of available functions and documentation.
Run tools
Function arguments for Whitebox.jl functions are keyword arguments, so the arguments must be included in the function call.
For example, use:
wbt.absolute_value(i = "DEM.tif", output = "abs_val.tif") # This works! ๐ฏ ๐
rather than:
wbt.absolute_value("DEM.tif", "abs_val.tif") # <- This won't work! ๐
Function help
We have a few different ways to find the required arguments or documentation for a function:
- Visit the WhiteboxTools user manual and look at the Python example for a function (those use snake_case too)
- Run
wbt.tool_parameters(tool_name::String)
, or - Enter
help?>
mode in the Julia REPL (Press?
), and search your function name
How it works
Getting WhiteboxTools
Whitebox.jl depends on the WhiteboxTools_jll.jl package to provide a build of WhiteboxTools.
The WhiteboxTools_jll.jl repo says:
"This is an autogenerated package constructed using BinaryBuilder.jl. The originating build_tarballs.jl script can be found on Yggdrasil, the community build tree. If you have any issue, please report it to the Yggdrasil bug tracker.
For more details about JLL packages and how to use them, see BinaryBuilder.jl documentation."
Setting defaults
Loading the Whitebox.jl package will automatically create an object containing info about default parameters, the working directory, and location of WhiteboxTools.
This object is called wbt_info
, and it is a struct of type WhiteboxTools.
Users can use dump
to view all its info:
dump(wbt.wbt_info)
# Whitebox.WhiteboxTools
# exe_name: String "whitebox_tools"
# exe_path: String "/Users/.../bin/whitebox_tools"
# work_dir: String "/Users/...your_wd"
# verbose: Bool true
# cancel_op: Bool false
# default_callback: default_callback (function of type typeof(Whitebox.default_callback))
# start_minimized: Bool false
# __compress_rasters: Bool false
Every function in the Whitebox.jl package requires an object of type WhiteboxTools, and every function uses the wbt_info
object as the default.
To change the default settings of the WhiteboxTools program for your session, you should change them using the provided functions.
For example:
wbt.set_verbose_mode(false)
Generating functions
Most of the functions in this package were generated using the included whitebox_plugin_generator.py
. This file was adapted from the file of the same name in the WhiteboxTools repo
Using a python script was intentional so that future updates or added functions could be generated from the Python package.
Some additional changes to the generated functions were required:
wbt.multiscale_topographic_position_image
: changedlocal
input argument references tolocalrast
.local
is a reserved word for Julia.wbt.conditional_evaluation
:true
andfalse
input arguments were changed toTrue
andFalse
.