Whitebox Workflows for Python v1.0 User Manual
Written by John Lindsay, PhD
© 2022 Whitebox Geospatial Inc. All rights reserved.
www.whiteboxgeo.com

Introduction

What is Whitebox Workflows for Python?

Whitebox Workflows (WbW) is a Python library for advanced geoprocessing, including more than 400 functions for GIS and remote sensing analysis operations and for for manipulating common types of raster, vector and LiDAR geospatial data.

WbW allows you to write Python scripts for automated data processing in areas such as geographical information systems (GIS), remote sensing (image processing and LiDAR point cloud processing), digital elevation model (DEM) analysis, spatial hydrology, stream network analysis, and many related spatial analysis fields. WbW is developed at Whitebox Geospatial Inc, a Canadian based geomatics company with deep roots in the geospatial industry.

The WbW codebase is based on the open-source project WhiteboxTools Open Core (WbOC), also developed at Whitebox Geospatial Inc. Compared with WbOC, WbW has a number of advantages for Python based geoprocessing. The largest difference between the two projects is that WbW is compiled as a Python native extension module, much like NumPy and SciPy, whereas WbOC is a command-line application. Because WbW is a Python extension module, it affords a much deeper level of interaction with geospatial data, allowing users to manipulate raster, vector, and lidar data objects directly. This reduces the need to read/write files considerably, significantly improving the performance of complex workflows with many intermediate steps and reducing the wear on system hardware.

Interacting directly with spatial objects also means that WbW has a more natural scripting style, providing a much richer geoprocessing environment. For example, you can use Python directly for raster map algebra, rather than a raster calculator or individual tools (e.g. add, divide, etc.):
result = (raster1 + raster2) / 2.0

WbW also has an improved memory model for raster data. With WbOC, raster data are always stored in memory as 64-bit floats, which can lead to large memory requirements. WbW, however, stores rasters in computer memory using their native data format; a raster storing 16-bit integers or 32-bit floating point values will require substantially less memory.

However, WbW is proprietary, unlike the open-source WbOC. WbW requires a license to use, which can be purchased from www.whiteboxgeo.com. Annual licenses are only about US$10 per seat.

WbW vs. WbW-Pro

In addition to the standard version of WbW, which is based on the functionality of WhiteboxTools Open Core, there is also a professional-level verison known as WbW-Pro.

Getting Started

Installing Whitebox Workflows

You'll need to install WbW on your computer or virtual environment to use it. If you have Python installed on your computer, simply type the following line at the command prompt of your terminal application:

pip install whitebox-workflows

If your default Python is v2.X, you may need to use the pip3 command instead. You may wish to use a Python virtual environment (venv, Conda, etc.) to test the whitebox-workflows package but this isn't necessary.

WbW is supported on Windows (64-bit), Mac (Intel and ARM) and Linux (x86_64).

If you have an older version of WbW installed and want to update it to the latest version, simply type the following command:

pip install whitebox-workflows -U

Updating your WbW to a newer version won't impact your license. You should update every time a new version is released.

For a demonstration of the install process, please see the video below:

Running your first script

Now that we have WbW installed, it's time to start using it. Create a new Python file called wbw_test.py and type the following script into the file.

wbw_test.py

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()

print(wbe.version())

Notice the underscore in the WbW library name whitebox_workflows compared with the hyphen used in the pip package name whitebox-workflows.

This above script does a few things. First, it imports the whitebox_workflows library and gives it the shorter alias wbw. Next, we set up the Whitebox Environment, WbEnvrionment, which is one of the most important classes contained within the whitebox_workflows module. It's the class that is used to manipulate environmental settings, e.g. setting the current working directory. Importantly, all of the tools for processing spatial data are methods of the WbEnvironment class. Lastly, the version() method is called, printing information about our installed version of WbW.

When you run the above script, it should print something similar to this:

License activated for Trial License - Whitebox Workflows for Python. There are 0
seats remaining in the key. Please enjoy!

You can use Whitebox Workflows for Python for free over the next 3 days. After
that, you will need to purchase a license from
https://www.whiteboxgeo.com/whitebox-workflows-for-python/. Annual licenses are
about $10+tax.

The license for "Trial License - Whitebox Workflows for Python" will expire in 3
days. Please visit www.whiteboxgeo.com, or contact Whitebox Geospatial Inc. at
support@whiteboxgeo.com, to renew your license.

Whitebox Workflows for Python v0.9.8 by Whitebox Geospatial Inc. 
Developed by Dr. John B. Lindsay, (c) 2022

Description:
Whitebox Workflows for Python is an advanced geospatial data analysis platform 
and Python extension module.

That is a lot of information, so let's break it down. Because this is the first time that we've run WbW, the library looks for a valid license for the software. Finding no license, it activates a 3-day free trial license. After it installed the trial license, the script then continued to print the versioning information of our installed WbW. Between issuing the trial license and printing the versioning information, the script output the statement The license for "Trial License - Whitebox Workflows for Python" will expire in.... This warning reminds you that your license is soon to expire and that you should update. If the script runs without error, we can be assured that WbW has been installed correctly on our system.

Floating Licenses vs. Node-locked Licenses

A purchase of WbW comes with an equal number of node-locked and floating licenses. For example, if you've purchased two seats, you will be able to register two node-locked licenses on two computers, but you will also be able to check-out two silmutaneous floating licenses at any time from any computer.

The code above uses a node-locked WbW license, i.e., the license is tied to the machine that it was registered on. Sometimes, you will want to use WbW in other computing environments, e.g. on different computers within a network, or on cloud-based computing platforms like Google Colab. When this is the case, you need to use a floating license. If you've purchased a WbW license (and you aren't using a trial license), then you will have been provided a floating license ID in an email that was sent to you after registering your license activation code.

Your floating-license user ID is unique to you and you should keep this string private. Sharing your user ID with other people will result in the early termination of your license.

If you would instead like to use your floating license, simply provide your floating-license user ID as a parameter in the wbw.WbEnvironment() constructor, e.g. wbw.WbEnvironment('white-bolting-camel'). Here's an example of a script using a floating license:

wbw_test_floating_license.py

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment('your-license-id')
try:
    print(wbe.version())
except Exception as e:
  print("The error raised is: ", e)
finally:
    print(wbe.check_in_license('your-license-id')) # print to confirm the successful check-in

A note on checking-in your license: Because the floating license uses a Check-out/Check-in model, you must remember to check-in your license after you have completed processing your script. The last thing you do in each script, therefore, should be to call the WbEnvironment.check_in_license method.

When we specify our floating-license user ID in the WbEnvironment initializer in the script above, the program, when run, will communicate with the Whitebox Geospatial Inc. remote license server web app. It will check to see if there is an available seat associated with the specified user ID. Importantly, while your script is running, and until you check-in your license, it will not be available for use again. This means that it is very important that the last thing you successfully check-in the license at the end of the script, which is why we call check_in_license within the finally block of a try-finally construct in the script above. This way, if the script throws an error, we can still be sure that the license will be checked back in and we'll be able to use it again in the future.

If all of the existing 'seats' of a license are unavailable because they are either in use, or haven't yet been checked back in, you will receive an error indicating that 'All floating licenses are currently in use'. The number of 'users' that you specified when you purchased your WbW license will indicate how many silmutaneous floating license seats you have to work with.

Sometimes a script may panic, which is an unrecoverable type of error. This happens for example, if you provide an unexpected input parameter to a function. When this is the case, our checked-out license may not be checked back in correctly. What do we do in this case? Well, after a certain amount of time (usually two hours), an un-checked-in license will be returned to the pool of available licenses. But, of course, that leaves us in a difficult situation for those hours wihtout being able to run further WbW scripts. When this occurs, we can call the check_in_license function associated directly with the whitebox_workflows module, i.e. whitebox_workflows.check_in_license('your-license-id'). Note, you should always prefer using WbEnvironment.check_in_license('your-license-id) over whitebox_workflows.check_in_license('your-license-id') because the latter will throw an error if there is no unchecked-in license to check-in. However, in the event that a script panic results in a 'zombie' floating license seat, this method is a usable solution to get you up-and-running with WbW geoprocessing once again.

import whitebox_workflows as wbw

print(wbw.check_in_license('your-license-id')) # print to confirm the successful check-in

Scripting and type hints

Scripting with WbW is much easier when you use a good Python editor. Python editors, or general purpose programming editors like Visual Studio Code, will provide syntax highlighting, line numbering, and if configured correctly, autocomplete. Autocomplete features in particular are useful when using WbW, and allow you to explore the WbW application programming interface (API).

Type hinting in WbW

This feature can also help the programmer to learn about the arguments that are required by a function as they type.

Type hinting in WbW

You may also want to take advantage of Python's built-in help function to learn more about individual members of the WbW API, e.g. help(wbw.Raster.con) can be used to provide the help documentation for the con (conditional evaluation) method of the Raster class.

WbW has been designed to provide Python editors with type hints and default values of arguments. These features can greatly enhance the programming experience.

Registering your license

When you first install the software on your system, and after running your first script, WbW should initialize a trial license, as it did in the output from the previous section. While this allows you to use WbW without restrictions for the trial period, after this time you'll need to purchase a license from www.whiteboxgeo.com and register it to continue to use the software. An annual license only costs US$10 per seat and you may purchase multiple seats at the same time. After the purchase, you'll be redirected to a website providng you with an activation key. If you've purchased multiple seats, you'll be provided a single activation key that contains your purchased number of seats.

Be sure to copy your activation key, or the embedded Python script, before closing the redirect page. You will need this to activate your license.

To register your license, you need run the following Python script:

import whitebox_workflows as wbw

# Be sure to replace the key below with your issued key; this one is just an
# example. Also update with your first and last name and email address. Note,
# by running the script, you are agreeing to the terms of the license, found
# on www.whiteboxgeo.com
wbw.activate_license(
key="889d88d3c7ccc6c9d3ccc9cad3c8d3ced3cecbc6cbcfd3cbcacdc6c7d3cec9c9cec8c8cfc", 
firstname="Jane", 
lastname="Doe", 
email="jdoe@gmail.com", 
agree_to_license_terms=True
)

Node-locked and floating licenses

When you register your license, WbW writes information about your license on your computer. This will allow you to use WbW on your computer at any time, even when you are not connected to the Internet. This is a so-called 'node-locked' license (i.e., it is tied to a specific computer). However, when you register your license, you will also be sent an email confirming the registration. This email will contain a floating-license user ID, which consists of a three-word string, e.g. 'white-bolting-camel'. This string connects your floating license with the WbW license server and allows you to use WbW on any computer or computing environment (e.g., Google Colab or Jupyter Notebooks).

Notice, it is important that use your correct email when registering your license or you will not be able to access your floating-license user ID and you will only be able to use the node-locked license on the computer system that you registered WbW from.

Using your floating license is easy. Instead of using the usual means of intializing a WbEnvironment:

import whitebox_workflows as wbw

# Checks for a valid node-locked WbW license stored locally
wbe = wbw.WbEnvironment()

You simply need to specify your floating-license user ID as an optional parameter, being sure to check-in the license when you have completed:

import whitebox_workflows as wbw

# Checks for a valid floating license stored on remote server
wbe = wbw.WbEnvironment('your-license-id') 
try:
    # Do some processing here...
except Exception as e:
  print("The error raised is: ", e)
finally:
    wbe.check_in_license('your-license-id')

When you specify your floating-license user ID in the WbEnvironment initializer, the program will communicate with the Whitebox Geospatial Inc. remote license server web app. This requires Internet access. Thus, if you are unable to access the Internet for a time, you should fall back on your node-locked license instead.

Your floating-license user ID is unique to you and you should keep this string private. Sharing your user ID with other people will result in the early termination of your license.

How much time remains on my license?

To determine how much time is remaining on your license, you may use the license_info method:

import whitebox_workflows as wbw

# on the host machine with the node-locked license...
print(whitebox_workflows.license_info())

# or for a floating license...
print(whitebox_workflows.license_info('white-bolting-camel')) # specify your floating-license user ID

Transfering and deactivating licenses

Licenses are transferable, if for example you would like to move your node-locked license to a different system. For this, you need to use the wbw.transfer_license() method, which will issue you a new activation key, with the number of days remaining on your license; you may then use the issued key to register WbW on the other machine. Transfering a license will deactivate the license on the current computer.

import whitebox_workflows as wbw

wbw.transfer_license()
# Note, this function will print out the information that you will need to register the
# license on another computer, including the required activation key. Also note that
# after the license has been transferred, there may be a print out that says something 
# like, "The data in the license file appears to be corrupt..." This is simply because
# after transfering the license, WbW can no longer be used on this current machine,
# without registering another license. In fact, if you would like to re-register it 
# on the current computer using the issued activation code, that will work fine too.

Similarly, the wbw.deactivate_license() method is used to deactivate a license, although note that this simply removes the license but does not uninstall WbW from your system. To uninstall the software, use pip uninstall whitebox-workflows.

For a demonstration of the registration process, please see the video below:

Setting up the Whitebox Environment

We saw in an earlier section that the WbEnvironment class is used to set up the Whitebox geoprocessing environment. This important initialization step should be one of the first things that we do in most WbW scripts.

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment() # Create a WbEnvironment object, here named wbe.
# We can use this object to provide settings to tools that are run later in the script.
# If you aren't on the computer that you registered WbW on, you may use your
# floating-license user ID as a parmeter, e.g. wbe = wbw.WbEnvironment('cute-flying-pig').
# This ID will have been emailed to you upon registration.

# `max_procs` determines the number of processors used by functions that are parallelized. 
# If set to -1, the default, all available processors will be used.
wbe.max_procs = -1

# To limit tools to a certain number of processors, set `max_procs` to a positive whole 
# number less than the number of system processors. This can be important in cloud-based
# and distributed computing environments where you may not want WbW to fully utilize all
# available processors.
wbe.max_procs = 4

# `verbose` determines whether tool output sto stdout (`wbe.verbose=True`), or if
# output is suppressed (`wbe.verbose=False`). Tools are often very chatty, outputting
# frequent updates of progress. When you're running long workflows, it can be useful to
# turn this stream of tool output on and off during critical parts of the workflow.
wbe.verbose = True
# Run something critical...
wbe.verbose = False
# Run something less critical...

# Of course, when verbose=False, you will not be able to see any warnings or errors 
# issued by the tool, so this may not be desirable while testing a script.

# You can set and get the working directory as follows:
wbe.working_directory = '/path/to/my/data'

print(wbe.working_directory)

# How much time is remaining on your license?
print(wbw.license_info()) # Also takes the optional floating-license user ID.

# The working directory is the current path used to find data resources. When reading and 
# writing data, the working directory is the default location in which the data are read 
# from and written to.

my_raster = wbe.read_raster('image1.tif') # Will search for file "/path/to/my/data/image1.tif"

# You can also use full path names when specifying data.
my_raster = wbe.read_raster('/other/path/to/my/data/image2.tif')

# You can update the working directory multiple times in a script.
wbe.working_directory = '/other/path/to/my/data'
my_vector = wbe.read_vector('vector1.shp') # Will search for file "/other/path/to/my/data/vector1.shp"

Working with Whitebox Workflows

Sample datasets

There are a number of available sample datasets that can be readily used to test Whitebox Workflows for Python. The following is a description of all available datasets:

Dataset Name	File Name	Description	Compressed Size
Guelph_landsat	band1.tif...band7.tif	7 bands of a sub-area of a Landsat 5 data set	10.9 MB
Grand_Junction	DEM.tif	A small digital elevation model (DEM) in high-relief	5.8 MB
GTA_lidar	GTA_lidar.laz	An airborne lidar point cloud, in LAZ format	54.3 MB
Jay_State_Forest	DEM.tif	A lidar raster digital elevatio model (DEM)	27.7 MB
Kitchener_lidar	Kitchener_lidar.laz	An airborne lidar point cloud, in LAZ format	41.6 MB
London_air_photo	London_air_photo.tif	A high-res RGB air photo	87.3 MB
Southern_Ontario_roads	roads_utm.shp	Vector roads layer for a section of Southern Ontario	7.1 MB
StElisAk	StElisAk.laz	An airborne lidar point cloud, in LAZ format	54.5 MB

The data can be downloaded using the download_sample_data function within the whitebox_workflows module. For example,

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()

wbe.working_directory = wbw.download_sample_data('Kitchener_lidar')
print(f'Data have been stored in: {wbe.working_directory}')

The data will be downloaded to a location within your HOME directory and the download_sample_data function will return the address of the dataset directory. This can be useful for updating the WbEnvironment.working_directory property, as in the script above. The data will be downloaded in a compressed file format (zip) and will be automatically decompressed after the download has completed. The download_sample_data function will automatically terminate after two minutes. You may encounter this issue if you attempt to download some of the larger sample datasets using a slower Internet connection.

Reading and writing data

WbW supports reading and writing many types of raster, vector, and LiDAR data formats.

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()

wbe.working_directory = 'path/containing/data/files'

# Reading raster data
my_raster = wbe.read_raster('file_name.tif')

# Or read_rasters (with an 's') for multiple rasters at once...
my_raster1, my_raster2 = wbe.read_rasters('file_name1.tif', 'file_name2.tif')

# Writing raster data
wbe.write_raster(my_raster, 'output.tif')

# You can also ask WbW to compress the written raster
wbe.write_raster(my_raster, 'output.tif', compress=True) # Only GeoTIFF compression is supported.

# Reading vector data
my_vector = wbe.read_vector('file_name.shp')

my_vector1, my_vector2 = wbe.read_vectors('file_name1.shp', 'file_name2.shp')

# Writing vector data
wbe.write_vector(my_vector, 'output.shp')

# Reading LiDAR data
my_lidar = wbe.read_lidar('file_name.laz')

my_lidar1, my_lidar2 = wbe.read_lidars('file_name1.laz', 'file_name2.laz')

# Writing LiDAR data
wbe.write_lidar(my_lidar, 'output.laz')

Supported Data Formats

Raster formats

WbW can currently support reading/writing raster data in several common formats.

Format	Extension	Read	Write
GeoTIFF	.tif, .tiff	X	X
Big GeoTIFF	.tif, .tiff	X	X
Esri ASCII	.txt, .asc	X	X
Esri BIL	.bil, .hdr	X	X
Esri Binary	.flt and .hdr	X	X
GRASS ASCII	.txt, .asc	X	X
Idrisi	.rdc and .rst	X	X
SAGA Binary	.sdat and .sgrd	X	X
Surfer ASCII	*.grd	X	X
Surfer Binary	*.grd	X	X
Whitebox	.tas and .dep	X	X

Throughout this manual code examples that manipulate raster files all use the GeoTIFF format (.tif) but any of the supported file extensions can be used in its place.

WbW is able to read GeoTIFFs compressed using the PackBits, DEFLATE, and LZW methods. Compressed GeoTIFFs, created using the DEFLATE algorithm, can also be output from any tool that generates raster output files by using compress=True.

Vector Formats

At present, there is limited support in WbW for working with vector geospatial data formats. The only supported vector format is the ESRI Shapefile. Shapefiles geometries (.shp) and attributes (.dbf) can be read and written.

While the Shapefile format is extremely common, it does have certain limitations for vector representation. For example, owing to their 32-bit indexing, Shapefiles are limited in the number of geometries that can be stored in these files. Furthermore, Shapefiles are incapable of storing geometries of more than one type (point, lines, polygons) within the same file. As such, the vector-related tools in WhiteboxTools also carry these same limitations imposed by the Shapefile format.

Point Cloud (LiDAR) Formats

LiDAR data can be read/written in the common LAS and compressed LAZ data formats.

Using tool functions

Most of WbW's tools exist as functions of the WbEnvironment class.

import whitebox_workflows as wbw
import math

wbe = wbw.WbEnvironment()
wbe.verbose = True
wbe.max_procs = -1

# Let's begin by downloading the Whitebox Workflows 'Guelph_landsat' sample data
wbe.working_directory = wbw.download_sample_data('Guelph_landsat')
print(f'Data have been stored in: {wbe.working_directory}')

# Read some of the image bands into memory
band2, band3, band4, band5 = wbe.read_rasters('band2.tif', 'band3.tif', 'band4.tif', 'band5.tif')

# Now let's call the create_colour_composite tool
true_colour_composite = wbe.create_colour_composite(
    red=band4, 
    green=band3, 
    blue=band2,
    enhance=False,
    treat_zeros_as_nodata=False
)
# The result 'true_colour_composite' is an in-memory raster. If we want to
# save it to disc to visualize it, we need to call 'write_raster'.
# wbe.write_raster(true_colour_composite, 'true_cc.tif', compress=True) # Uncomment this line to save to file

# Notice, that we don't need to specify the argument names of positional
# arguments (red, green, and blue above), and that we don't need to specify
# values for optional arguments if we accept their default values.
false_colour_composite = wbe.create_colour_composite(band5, band4, band3, enhance=False)
# wbe.write_raster(false_colour_composite, 'false_cc.tif', compress=True) # Uncomment this line to save to file

# If we don't want to see all of the progress updates output to stdout, 
# turn verbose mode off. But we also won't see errors or warnings.
wbe.verbose = False

# Now let's perform some image enhancements...
bce = wbe.balance_contrast_enhancement(true_colour_composite)

dds = wbe.direct_decorrelation_stretch(bce, achromatic_factor=0.3)
wbe.write_raster(dds, 'final_true_cc.tif', True)

# We can overwrite objects as well.
bce = wbe.balance_contrast_enhancement(false_colour_composite)

dds = wbe.direct_decorrelation_stretch(bce, achromatic_factor=0.3)
wbe.write_raster(dds, 'final_false_cc.tif', True)

There are also a large number of functions associated with the Raster class for manipulating raster data sets. Each of these Raster functions allow for Python-based raster algebra operations. For example:

# Calculate the normalized difference vegetation index...
ndvi = (band5 - band4) / (band5 + band4)
wbe.write_raster(ndvi, 'ndvi.tif', compress=True)

# use a multiplier and offset to adjust the values of a raster
multiplier = 0.012152
offet = -60.76071
sun_elev = math.radians(64.31337609)
reflectance = (band1 * multiplier + offset) * math.sin(sun_elev)

max_val = band1.max(band2)

Working with raster data

import whitebox_workflows as wbw
from whitebox_workflows import PhotometricInterpretation, RasterDataType

wbe = wbw.WbEnvironment()
wbe.verbose = True
wbe.max_procs = -1

# Let's begin by downloading the Whitebox Workflows 'Jay_State_Forest' sample data
wbe.working_directory = wbw.download_sample_data('Jay_State_Forest')
print(f'Data have been stored in: {wbe.working_directory}')

# Now read the 'DEM.tif' file...
dem = wbe.read_raster('DEM.tif')

# The RasterConfigs of a Raster object contains useful metadata about the Raster.
print(f'Rows: {dem.configs.rows}')
print(f'Columns: {dem.configs.columns}')
print(f'Resolution (x direction): {dem.configs.resolution_x}')
print(f'Resolution (y direction): {dem.configs.resolution_y}')
print(f'North: {dem.configs.north}')
print(f'South: {dem.configs.south}')
print(f'East: {dem.configs.east}')
print(f'West: {dem.configs.west}')
print(f'Min value: {dem.configs.minimum}')
print(f'Max value: {dem.configs.maximum}')
print(f'EPSG code: {dem.configs.epsg_code}') # 0 if not set
print(f'Nodata value: {dem.configs.nodata}')
# What data type are stored in raster grid cells?
# See the RasterDataType class for more info.
print(f'Data type: {dem.configs.data_type}') 
# What is the photometric interpretation, continuous, categorical, RGB, etc.?
# See the PhotometricInterpretation class for more info.
print(f'Photometric interpretation: {dem.configs.photometric_interp}')

# We create new rasters most frequently by copying the RasterConfigs from another
# existing Raster object. We can also create a new RasterConfigs manually but
# when we want to create a new Raster that has the same rows, columns and extent
# as another Raster, copying the other Raster's RasterConfigs, and modifying it
# as needed, is a good way forward.
out_configs = dem.configs

# Once you create a new Raster, you cannot change certain things about it, such
# as the number of rows and columns and the data type. The RasterDataType must
# be able to hold the data values. In the case below, we are reclassifying the
# raster to a Boolean, with 1's and 0's. So we really only need small, integer
# level data. I16 is used in this case to allow for NoData values, which will
# be set to -32768, the smallest possible 16-bit int.
out_configs.data_type = RasterDataType.I16 
out_configs.nodata = -32768.0
out_configs.photometric_interp = PhotometricInterpretation.Categorical

# Now let's create the new raster, based on our customized RasterConfigs...
high_areas = wbe.new_raster(out_configs)

# When we create a new raster, it is initially filled with NoData values, as
# set in its RasterConfigs.
print(f'Cell(500, 500) = {high_areas[500, 500]}') # = -32768.0

# Let's manipulate the raster data at the individual grid cell level.
print("Finding high elevations")
old_progress = -1
for row in range(dem.configs.rows):
    for col in range(dem.configs.columns):
        elev = dem[row, col] # Read a cell value from a Raster
        if elev > 800.0 and elev != dem.configs.nodata:
            high_areas[row, col] = 1.0 # Write the cell value of a Raster

            # Regardless of the RasterDataType used to store the cell
            # data in memory and in file, data are always passed to and
            # returned from rasters as floats. Note that the cell value
            # is set to 1.0 above and not 1.
        elif elev != dem.configs.nodata:
            # We must do the check for NoData, or else we'll replace
            # NoData values in the input raster with 0's in the output. 
            # NoData in must be NoData out.
            high_areas[row, col] = 0.0
    
    # Update the progress after each completed row scan.
    progress = int(((row + 1.0) / dem.configs.rows) * 100.0)
    if progress != old_progress:
        old_progress = progress
        print(f'Progress: {progress}%')

# Write the new Raster to file.
print('Saving data to file...')
wbe.write_raster(high_areas, 'high_areas.tif', compress=True)

# This allows for very fine-grained raster manipulation for custom data processing.
# But if the same functionality exists within the WbW toolset, you should always 
# prefer the native solution, because it will be faster than the Python alternative. 
# The code above could have been more efficiently processed using the following:
high_areas = dem > 800.0

Working with vector data

import whitebox_workflows as wbw
from whitebox_workflows import AttributeField, FieldData, FieldDataType, VectorGeometryType

wbe = wbw.WbEnvironment()

# Let's begin by downloading the Whitebox Workflows 'Southern_Ontario_roads' sample data
wbe.working_directory = wbw.download_sample_data('Southern_Ontario_roads')
print(f'Data have been stored in: {wbe.working_directory}')

# Read in the roads file
roads = wbe.read_vector('roads_utm.shp')

# Let's see some of the properties of this file...
print(f'Vector geometry type: {roads.header.shape_type}') # A VectorGeometryType.PolyLine
print(f'Min X: {roads.header.x_min}')
print(f'Max X: {roads.header.x_max}')
print(f'Min Y: {roads.header.y_min}')
print(f'Max Y: {roads.header.y_max}')
print(f'Number of records: {roads.num_records}')
print(f'Projection: {roads.projection}')

# To retrieve a vector geometry, use the [] syntax.
geom = roads[100]
print(f'Geometry type: {geom.shape_type}')
print(f'Num vertices: {geom.num_points}')
print(f'Num parts: {geom.num_parts}')
print(f'Min X: {geom.x_min}') # There min/max x, y, measure, and z
print(f'First vertex: ({geom.points[0].x}, {geom.points[0].y})')

# What about the file attributes?
print(f'Num records: {roads.attributes.header.num_records}') # Should be same as roads.num_records
print(f'Num fields: {roads.attributes.get_num_fields()}')

# Retrieve and print the attribute fields
att_fields = roads.get_attribute_fields()
for i in range(len(att_fields)):
    print(att_fields[i])

# What's the index of a specific field, by attribute name?
index_of_road_class = roads.get_attribute_field_num("ROAD_CLASS")

# Let's create a new Vector object...

# First, we need to create the attribute fields used for the new vector
out_att_fields = [
    AttributeField("FID", FieldDataType.Int, 6, 0),
    AttributeField("SRC_FID", FieldDataType.Int, 6, 0),
]

# Now create the Vector itself.
out_roads = wbe.new_vector(VectorGeometryType.PolyLine, out_att_fields, proj=roads.projection)

# You can also add a new attribute field after creating the file.
out_roads.add_attribute_field(att_fields[index_of_road_class])

# Now let's filter all the records to find those geometries with a ROAD_CLASS of indicating major highways
old_progress = -1
fid = 1
for i in range(roads.num_records):
    road_class = roads.get_attribute_value(i, 'ROAD_CLASS').get_as_string().lower()
    if 'freeway' in road_class or 'collector' in road_class or 'expressway' in road_class:
        geom = roads[i]
        out_roads.add_record(geom) # Add the record to the output Vector

        # Create the output attribute record...
        att_rec = roads.get_attribute_record(i)
        rec_data = [
            FieldData.new_int(fid), 
            FieldData.new_int(i+1),
            att_rec[index_of_road_class]
        ]
        fid += 1
        # then add it to the table.
        out_roads.add_attribute_record(rec_data, deleted=False)

    # Update the progress after completing each 1% of the records.
    progress = int((i + 1.0) / roads.num_records * 100.0)
    if progress != old_progress:
        old_progress = progress
        print(f'Progress: {progress}%')


# Write the output to file.
print('Writing vector to file...')
wbe.write_vector(out_roads, 'out_roads.shp')

Working with LiDAR data

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()

# Let's begin by downloading the Whitebox Workflows 'Kitchener_lidar' sample data
wbe.working_directory = wbw.download_sample_data('Kitchener_lidar')
print(f'Data have been stored in: {wbe.working_directory}')

# Read in an existing lidar data set
lidar = wbe.read_lidar('Kitchener_lidar.laz')

# To create a new Lidar object, you need a LidarHeader, which documents metadata
# about a LiDAR file. It is the LiDAR equivalent to the RasterConfigs.
print(f'File creation day: {lidar.header.file_creation_day}')
print(f'File creation year: {lidar.header.file_creation_day}')
print(f'Generating software: {lidar.header.generating_software}')
num_points = lidar.header.get_num_points()
print(f'Number of points: {num_points}')
print(f'Version major: {lidar.header.version_major}')
print(f'Version minor: {lidar.header.version_minor}')
print(f'Point format: {lidar.header.point_format}')
print(f'Min X: {lidar.header.min_x}')
print(f'Max X: {lidar.header.max_x}')
print(f'Min Y: {lidar.header.min_y}')
print(f'Max Y: {lidar.header.max_y}')
print(f'Min Z: {lidar.header.min_z}')
print(f'Max Z: {lidar.header.max_z}')

# Now, create a new Lidar object. In doing so, the new Lidar object will copy 
# over some of the properties in the source LidarHeader, but won't copy any of 
# the things like generating software, creation day/year, point extent values,
# or the source point data. It's a newly initialized file ready to receive its
# own point data.
lidar_out = wbe.new_lidar(lidar.header)

# You likely want to copy over the VariableLengthRecord (VLR) data too. VLRs
# usually contain important information, such as the coordinate reference 
# system.
lidar_out.vlr_data = lidar.vlr_data

print('Filtering point data...')
old_progress = -1
for i in range(num_points):
    # Notice that if the file does not contain time, colour, or waveform data,
    # each of these will simply be None. You can use the has_time_data(),
    # has_colour_data(), and has_waveform_data() methods to determine if these
    # data are stored in the file.
    point_data, time, colour, waveform = lidar.get_point_record(i)

    # The PointData returned by the get_point_record method has the raw
    # untransformed point coordinate information as well as all the info
    # about point intensity, class, return values, etc. If you simply want
    # the transformed x,y,z coordinates, use the get_transformed_xyz method
    # instead.
    
    # Now let's filter the data based on return data...
    if point_data.is_first_return() or point_data.is_intermediate_return():
        # Save the point to lidar_out
        lidar_out.add_point(point_data, time, colour, waveform)

    # Update the progress once we've completed another 1% of the points.
    progress = int((i + 1.0) / num_points * 100.0)
    if progress != old_progress:
        old_progress = progress
        print(f'Progress: {progress}%')


# Write lidar_out to file
wbe.write_lidar(lidar_out, "new_lidar.laz")

Tool documentation

Tool help documentation

Each of the following functions are methods of WbEnvironment class. Tools may be called using the convention in the following example:

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()
# Set up the environment, e.g. working directory, verbose mode, num_procs
raster = wbe.read_raster('my_raster.tif') # Read some kind of data
result = wbe.mean_filter(raster) # Call some kind of function
...

accumulation_curvature

License Information

Use of this function requires a license for Whitebox Workflows for Python Professional (WbW-Pro). Please visit www.whiteboxgeo.com to purchase a license.

Description

This tool calculates the accumulation curvature from a digital elevation model (DEM). Accumulation curvature is the product of profile (vertical) and tangential (horizontal) curvatures at a location (Shary, 1995). This variable has positive values, zero or greater. Florinsky (2017) states that accumulation curvature is a measure of the extent of local accumulation of flows at a given point in the topographic surface. Accumulation curvature is measured in units of m^-2.

The user must specify the name of the input DEM (dem) and the output raster (output). The The Z conversion factor (zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10ⁿ|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

adaptive_filter

This tool performs a type of adaptive filter on a raster image. An adaptive filter can be used to reduce the level of random noise (shot noise) in an image. The algorithm operates by calculating the average value in a moving window centred on each grid cell. If the absolute difference between the window mean value and the centre grid cell value is beyond a user-defined threshold (threshold), the grid cell in the output image is assigned the mean value, otherwise it is equivalent to the original value. Therefore, the algorithm only modifies the image where grid cell values are substantially different than their neighbouring values.

Neighbourhood size, or filter size, is specified in the x and y dimensions using filterx and filtery. These dimensions should be odd, positive integer values (e.g. 3, 5, 7, 9, etc.).

Value	Interpretation
x	x-coordinate
y	y-coordinate
z	elevation
i	intensity value
c	classification
rn	return number
nr	number of returns
time	GPS time
sa	scan angle
r	red
b	blue
g	green

.	.	.
64	128	1
32	0	2
16	8	4

Classification Value	Meaning	Default Colour
0	Created never classified
1	Unclassified
2	Ground
3	Low Vegetation
4	Medium Vegetation
5	High Vegetation
6	Building
7	Low Point (noise)
8	Reserved
9	Water
10	Rail
11	Road Surface
12	Reserved
13	Wire – Guard (Shield)
14	Wire – Conductor (Phase)
15	Transmission Tower
16	Wire-structure Connector (e.g. Insulator)
17	Bridge Deck
18	High noise

.	.	.
64	128	1
32	0	2
16	8	4

Whitebox Workflows for Python User Manual

Installing Whitebox Workflows

Running your first script

Registering your license

Node-locked and floating licenses

How much time remains on my license?

Transfering and deactivating licenses

accumulation_curvature

adaptive_filter

add_point_coordinates_to_table

aggregate_raster

anova

ascii_to_las

aspect

assess_route

attribute_correlation

attribute_histogram

attribute_scattergram

average_flowpath_slope

average_normal_vector_angular_deviation

average_overlay

average_upslope_flowpath_length

balance_contrast_enhancement

basins

bilateral_filter

block_maximum

block_minimum

bool_and

bool_not

bool_or

bool_xor

boundary_shape_complexity

breach_depressions_least_cost

breach_single_cell_pits

breakline_mapping

buffer_raster

burn_streams_at_roads

canny_edge_detection

centroid_raster

centroid_vector

change_vector_analysis

check_in_license

circular_variance_of_aspect

classify_buildings_in_lidar