Whitebox Workflows for Python

What is Whitebox Workflows?

Whitebox Workflows (WbW) is a Python library for advanced geoprocessing, including more than 400 functions for GIS and remote sensing analysis and for for manipulating geospatial data (raster, vector, and LiDAR). WbW enables you to write powerful geoprocessing scripts.

WbW provides a more natural Python-Whitebox interaction than the WhiteboxTools Open Core. Interacting directly with geospatial data objects significantly decreases the number of read/write operations during intermediate processing in WbW scripts, improving performance of complex workflows and reducing wear and tear on your system hardware. WbW also has an improved memory model for raster data and generally results in shorter and more easily maintained scripts.

Installing WbW is just: pip install whitebox-workflows. WbW is freeware and contains the same ~400 functions found in the WhiteboxTools Open Core. There is also a pay-for-use tier, WbW-Pro, that unlocks the same functions found in the Whitebox Toolset Extension (WTE). Purchasing a WbW-Pro license provides users with a floating license. This means that you can easily use WbW and WbW-Pro in any Python environment on any computer.

Want to see Whitebox Workflows in action?

The following links provide WbW tutorials, as Jupyter Notebooks, to learn how to use WbW for common hydrological and DEM analysis operations:

“I think anybody who starts doing some scripting with Whitebox Workflows will see that the individual tool runtimes are much faster than the total script due to the reading and saving of data. And the code is easier to write too! …I see no downside so far!“
Matt Chaney, PE
Water Resources Engineer, AECOM

How does Whitebox Workflows compare?

Whitebox Workflows (WbW) is based on the WhiteboxTools Open Core (WbOC) open-source codebase. While the two products share many characteristics and functionality, there are important differences.

Whitebox Workflows for Python	WhiteboxTools Open Core
Whitebox Workflows (WbW) is a native python extension library, which allows a much more intimate level of communication between WbW and your Python geoprocessing script.	WbTOC is a command line back-end program that interfaces with various front ends such as QGIS, ArcGIS and the R and Python programming languages.
With WbW you can directly manipulate raster, vector and lidar data objects, enabling a level of geoprocessing power that would be impossible with WbTOC.	You cannot manipulate geospatial data directly from Python using the WbTOC.
WbW take in-memory geospatial objects as input parameters and also return output objects. There is significantly less reading/writing operations of data to the disc. This allows for faster geoprocessing and less wear on your valuable hard-drives.	Data files are provided as file names and read into memory during tool operation and output data are written to disc for each intermediate step.
Uses a more natural in-line Python-based map algebra for rasters analysis.	Raster calculator tool is used for complex raster map algebra.
Proprietary freeware license. Optional paid license for WbW-Pro tier.	Open-source license and freely available. Optional paid license for Whitebox Toolset Extension (WTE).

Time to switch to Workflows

Overall, if you’re using the Whitebox platform to develop Python scripts for geoprocessing tasks, Whitebox Workflows is the clear winner. It provides easier-to-write and faster-running scripting with less strain on your expensive hardware. Simply put, it’s a more productive geoprocessing environment.

WbW is also freeware and there is no charge for using it. If you’d like to upgrade your experience and have the full functionality of the Whitebox Workflows platform, you may opt to purchase a license for the Professional tier product, WbW-Pro.

Geoprocessing with Whitebox Workflows for Python

Data manipulation

Each of the more than 400 geoprocessing tools that users love about the WbOC are also found in WbW. The library design of WbW affords a much more intimate level of communication between it and your Python geoprocessing script. For instance, with WbW you can directly manipulate raster, vector, and lidar data objects, to perform low-level geoprocessing in a way that is impossible with the open-core. For example, to the right we manipulate raster data directly in Python using WbW.

No intermediate read/write operations

WbW equivalent functions take in-memory geospatial objects as input parameters. WbW functions also return output objects. This means that for a typical geoprocessing workflow there is significantly less reading/writing of data to the disc. There is no performance cost incurred by read/write operations during the intermediate processing. WbW has been designed to meet enterprise-scale geoprocessing workflow needs.

The following example Python script interpolates a lidar file to a digital elevation model (DEM), performs some common pre-processing steps on the DEM, and then runs a flow accumulation operation, before outputting the flow accumulation grid to file.

Notice how each of the five tool functions return data objects that then serve as the inputs for later operations. While there’s only one read operation and one write operation in the script, an equivalent WbOC workflow would result in 10 individual read/write operations. This characteristic can result in significant gains in overall workflow performance. It is often the case that read/write operations can be the bottle-neck in geoprocessing performance. Fewer read/write operations also means significantly less wear on your hardware.

Python is your raster calculator

The design of WbW also allows for more natural geoprocessing of data objects. For example, rather than using individual raster math tools (e.g. Add, Divide, Sin etc.), or a raster calculator tool, with WbW, you can often treat raster objects like any other numerical variables in scripts. With WbW, Python becomes your raster calculator! This allows for exceedingly powerful yet expressive GIS scripting.

The WbW User Manual documents each of the mathematical functions that can be applied to raster objects and their parameters.