1

Whitebox Geospatial Analysis Tools Tutorial Series

Tutorial 1: Using Whitebox GAT

2

Tutorial version 1.0, March, 2010

Written by John Lindsay, Whitebox Geospatial Analysis Tools Project Lead Developer, The Centre for

Hydrogeomatics, The University of Guelph, Guelph, Canada, jlindsay@uoguelph.ca.

This tutorial has been prepared by John Lindsay as part of Government of Canada contract

#AM1043433W.

3

Preamble

This tutorial will cover the following topics:

1. Introduce the Whitebox GAT software

2. Describe software installation

3. Describe the basics of getting started working with Whitebox GAT

4. Displaying and manipulating data layers

5. Navigating displayed maps

6. Using the Raster Calculator

7. How to get data into and out of Whitebox GAT

1.0 Introduction

Welcome to Whitebox GAT, an open-source and transparent software package for the analysis of

geospatial data. In this tutorial you will be introduced to some of the basic features of Whitebox GAT

and will learn how to display and manipulate data. Please note that the following tutorial has been

prepared with Whitebox GAT version 1.0.4. Some of the material contained in this document may not

be compatible with previous or future versions of the software.

1.1 Software Installation

Whitebox GAT can be installed on any computer running the MS Windows XP, Vista, or 7 32- or 64-bit

operating systems simply by copying the Whitebox folder and files contained therein onto the hard

drive. Alternatively, the Whitebox files can be saved to and run from portable storage devices such as

USB pen drives. Notice that there is no need to run any installation program. This feature is intended to

facilitate the copying of the software to multiple computers, which is ideal in educational and research

4

settings. Once the files have been saved, and uncompressed if necessary, you can launch Whitebox

simply by double-clicking the WhiteboxGAT.exe file contained in the main directory using Windows

Explorer. The disadvantage of having no installation program is that Whitebox GAT will not

automatically appear in the Start Menu, Taskbar, or computer Desktop. As such, you may wish to make

a shortcut for the Whitebox executable file on your desktop by right-clicking the file, selecting 'Send to'

and 'Desktop (create shortcut)'. This will make launching the program easier in the future. You may

also wish to make copies of the shortcut in the Taskbar and Start Menu for easier access.

1.2 Getting Started

The Whitebox user interface consists of the menu bar at the top, the toolbar beneath it, and the status

bar at the bottom. To the left of the main workspace there is a tabbed panel containing the Tools tab, the

Layers tab, and the Layer Properties tab. When Whitebox first opens, a map titled 'New Map' is

displayed and occupies most of the main workspace. This map will initially contain no map layers.

When you first launch Whitebox, the status bar at the bottom of the screen will tell you the number of

tools found in the Plugins and Scripts directories. The listing of available tools is updated every time

the software is launched or when the user selects Refresh Tools under the View menu.

Notice that the Tools tab contains a Windows Explorer-style listing of each of the geospatial analysis

tools available, known as the Tools Treeview. Tools are listed here within toolboxes which group

multiple similarly themed tools. For example, the Cost-Distance Analysis toolbox (itself contained

within the GIS Analysis toolbox) groups three tools, each of which can be used to perform cost-distance

analysis. Tools can be launched either by navigating the Tools Treeview or through the Tool Quick

Launch, an alphabetical listing of each tool. The Tool Quick Launch listing can save considerable time

when you know the name of the tool that you wish to access. Notice that the tools are listed in the Tool

Quick Launch by their tool name which sometimes differs slightly from their Tools Treeview label. For

example, the tool LiDAR_NN_Interpolation is labelled Nearest Neighbour Interpolation within the

LiDAR Tools toolbox in the Tools Treeview.

Expand the LiDAR Tools toolbox in the Tools Treeview. Notice that each tool has one of two associated

images; either a wrench or a scroll-like paper. The wrench image is associated with Whitebox plugins

that have been written in a .NET language such as VB.NET or C#. The scroll image is used to denote a

5

tool that has been written using the Python scripting/programming functionality embedded in

Whitebox. Other than the difference in the Tools Treeview image you will not notice any difference in

how these two types of tools, plugins and scripts, operate. (In fact, there is usually a short delay when

the first script is launched after opening Whitebox; however, this delay does not occur again after the

first script launching. Python is also a slightly slower executing language.)

Click on either the LiDAR_NN_Interpolation tool in the Tool Quick Launch or its counterpart listing in

the Tools Treeview. A dialog box similar to the one in Figure 1 should be displayed. Notice that the

dialog box, as with all Whitebox tool dialogs, is divided into two halves. On the left there are a number

of user input parameters. For example, here the user is asked for the names of input and output files and

a number of other parameters related to the tool. The vertical scroll bar at the right of the parameter

interface can be used to scroll down to parameters that are not visible when the dialog box is first

displayed. The tool's help entry, if one exists, is displayed on the right-hand side of the dialog box. This

embedded help contains valuable information about how the tool works, information to guide the user

with the various input parameters, and information about other related tools, the tool creator and

creation date. The help file is in hypertext format, which allows for exploration of other help topics by

following hypertext links much like in a web browser. The green forward and backward arrow buttons

can help be used to navigate the help entries.

Figure 1. An example of a Whitebox tool dialog box.

6

The dialog boxes for all Whitebox tools should have a 'View Code' button. This button allows the user

to view the code related to the tool without resorting to searching the entire Whitebox source code to

find the relevant lines of code. In many instances the user may optionally convert the original source

code into other programming languages. This unique characteristic of Whitebox GAT is central to the

philosophy of transparent software that has been developed for the Whitebox project. The 'View Code'

button can provide a far deeper level of understanding about the details of how a tool operates than can

be achieved by reading the help entry alone.

1.3 Displaying and Manipulating Data Layers

If you have any tool dialog boxes open close them now by pressing the Cancel button. Data layers can

be added to an open map in one of three ways, including: 1) pressing the 'Add Data Layer to the Active

Map' button on the toolbar at the top of the Whitebox user interface, 2) selecting 'Add Layers to Map'

from either the View or File menus, and 3) pressing the 'Add Layers' button on the Layers tab. Multiple

data layer can be added at one time. Press the 'Add Data Layer to the Active Map' button on the toolbar,

navigate to the 'Samples' directory within the Whitebox main folder and add the layers 'Mad River

DEM.dep' and 'Hillshade.dep' to the active map. If no map is currently open, Whitebox will

automatically create one to add the layers onto.

Click on the Layers tab. Each of the two data layers are listed here in order from top to bottom. The

active layer is highlighted in white. Any layer can be made visible or invisible simply by checking or

unchecking the check-box to the left of the layer's title. Layers within a stack can be demoted (lowered)

or promoted (raised) either by right-clicking the layer on the Layers tab and selecting the appropriate

action or by pressing the corresponding button on the toolbar. When there are several files in a map's

layers stack, the Layer to Top and Layer to Bottom functions can be useful for reordering layers within

the stack.

Ensure that 'Mad River DEM' is the top layer then double-click the layer in the Layers tab. You will

automatically be brought to the Layer Properties tab. This tab allows the user to manipulate several

common display properties for the active layer. Change the palette by selecting an alternative palette

from the available list. Suitable palettes for DEM data include high_relief, atlas_relief, earthtones, and

spectrum. Change the transparency of the layer to 15%; this allows the shaded relief image beneath to

7

partly show through, creating a composite relief model that is particularly effective for conveying

information about the topography in an area.

Select the Layers tab once again and double-click the Hillshade layer. This will bring you back to the

Layer Properties tab but this time the properties for the Hillshade layer, which is now the active layer,

will be presented. Being a hillshade, or shaded relief, image the grey palette is the most appropriate of

the available palettes. Notice that the display minimum and maximum are set to 0 and 1 respectively.

These values are used in scaling the palette. Linear interpolation is used to determine which colour in

the palette will be assigned to each grid cell based on the relative distance of a cell's value between the

display minimum and maximum values. Press the View Layer Statistics and Histogram button. Notice

that the data in this image does not occupy the entire range of values between 0 and 1, i.e. several bins

are empty. As such, there are some colours (shades of grey) in the palette that are not currently being

used. Now close the statistics and histogram dialog box and press the Clip by Std. Dev. button. Notice

that the display minimum value increases from 0, the display minimum value decreases from 1, and

that the contrast of the hillshading image is improved considerably. Display the layer's histogram a

second time and observe how the histogram now occupies the whole range of values between the

display minimum and maximum values.

Save the displayed map by selecting 'Save Map As' in the File menu or by pressing the Save Map

button in the toolbar. Be sure to chose an appropriate and descriptive name for the map. Now close the

map. It will ask you if you would like to save the map; select 'No'. Now select 'Open Map' in the File

menu or press the Open Map button in the toolbar. Open your previously saved map. The map will be

displayed with all of the custom display properties that were specified before. It is important to

emphasize that a data layer is an individual data set, such as an image or vector (as of the time of

writing, Whitebox GAT does not support display of vector data but work is currently underway to add

this support) and does not contain any inherent information about how the data should be displayed. By

comparison, a map is a collection of one or more data layers in a stack, each with specified display

properties.

It is possible to have multiple maps open at one time but there is only ever one active map. The active

map is the open map that was selected most recently. When there are multiple maps open at one time,

be sure to select the appropriate map before adding new layers, otherwise the layers may be added to an

unintended map target.

8

Click on the Layers tab. Select the 'Mad River DEM' layer, right-click and select 'View File Attributes'.

A new window will appear displaying all of the attribute data for the layer, including information about

the georeferencing, the number of rows and columns, the file size, units, and any metadata entries.

Some of these data are also adjustable. For example, it is possible to rename a file simply by changing

the Name property (note that altering this field will update the name of both the .dep header file and the

.tas data file of Whitebox rasters). Metadata, i.e. data about the data, entries can also be added to the

file using View File Attributes. Some tools will automatically add metadata entries, commonly the tool

name that created the data layer and the date of creation. Users also commonly add information about

the data source and accuracy, when they are known, in the metadata.

1.4 Navigating the Map Display

Move the mouse over top of the displayed map. Notice that as the mouse moves the x- and y-

coordinates, the row and column numbers, and the z-value (i.e. attributes) are updated and displayed on

the status bar at the bottom of the user interface. The z-value data corresponds to the active layer, which

is not necessarily the top image in an overlaying stack such as the Mad River DEM and Hillshade map.

Make sure that the Zoom button is selecting in the toolbar. A blue box will be drawn around it when it is

selected. Experiment with zooming into a section of the map by placing the mouse in a position over

the map, pressing and holding the left mouse button down, and moving the mouse. A black box will be

drawn on the map, depicting the zoom window. When the left mouse button is released, the map image

will be updated, after having zoomed into the sub-region depicted by the zoom window. It is also

possible to zoom into the map by a set amount by pressing the Zoom In button in the toolbar or simply

by pressing the “+” button on the keyboard when the mouse is over the map. Similarly it is possible to

zoom outward by a set amount either by selecting the Zoom Out button in the toolbar, pressing the “-”

on the keyboard, or by right-clicking the mouse. The scroll button on some types of mice can also be

used to zoom in and out when the mouse if over top of the map.

Now select the Pan button, which resembles a black cross of arrows, from the toolbar. A blue box will

be drawn around the Pan button when it is selected. Note that Whitebox is always either in zoom mode

or pan mode. Experiment with panning around the map when you are zoomed in. Panning can also be

achieved by pressing the arrow keys on the keyboard when the mouse is over the map. You can zoom

9

out to either the full extent (i.e. the extent that includes all layers in the stack) or the active layer extent

by pressing the appropriate button from the toolbar or by pressing Ctrl+f (full extent) or Ctrl+a (active

layer extent) when the mouse is over the map.

You can resize the map in the same way that any window can be resized. This can be useful in

situations when data layers do not occupy much of a displayed map. This is often the case since the

empty map that is displayed with Whitebox is first launched is sized to occupy most of the workspace.

It may be necessary to zoom to full extent after resizing a map.

1.5 The Raster Calculator

If the hillshaded DEM map that was created in the earlier sections of this tutorial is not currently open,

open it now. Select 'Raster Calculator' under the Tools menu or press the Raster Calculator button on

the toolbar. The Raster Calculator window will appear (Figure 2).

Figure 2. The Whitebox Raster Calculator.

10

The Raster Calculator is a powerful tool for manipulating raster data either through so-called map

algebra or logical expressions. Equivalent calculator-type tools are available in most GIS packages. The

Raster Calculator is used by building expressions that involve one or more raster data layers. Raster

layers are denoted in the expressions by using square brackets. When a raster layer is within the

working directory identified at the bottom of the Raster Calculator, only the layer name needs to be

contained within the square brackets; otherwise it is necessary to place the entire directory and file

name in brackets to identify the layer. As such, it is wise to change the working directory to the

appropriate directory before using the Raster Calculator. If the working directory is not set to the

samples directory, change it now. Type the following expression into the Expression section of the

dialog:

[High Areas]=[Mad River DEM]>800

This expression will result in the creation of a new raster image called 'High Areas', which will be

automatically displayed when the expression has been completed.

Notice that the image contains Boolean data, i.e. it contains ones and zeros only. Boolean and

categorical images should be displayed differently than continuous data, such as the DEM or hillshade

image. Select 'High Areas' as the active map and view the Layer Properties tab. Change the palette to

qual (a qualitative palette that is ideal for non-continuous data) and uncheck the 'Apply linear stretch'

checkbox (this will ensure that no contrast stretch is performed when displaying the layer) and press the

'Apply Changes' button. The background of the image is coloured black. For our purposes, it would be

useful to have the hillshaded DEM show through in the areas beyond the identified high areas. Open

the Set NoData Value tool from within the Conversion Tools toolbox or using the Tools Quick Launch.

Specify 'High Areas' as the input file and run the tool. When it has completed press the Zoom to Full

Extent/Refresh button in the toolbar. The map should now look something like the one displayed in

Figure 3 below.

11

Figure 4. Final Mad River map with high areas highlighted.

1.6 Getting Data Into and Out of Whitebox

Whitebox supports the import from and export to several common raster data formats. The tools in the

Data Import/Export toolbox include methods for converting the file formats of ArcGIS, GRASS,

IDRISI, and Surfer. In addition, users are able to import common image file formats (with an

accompanying world file for georeferencing) and generic file formats for storing multispectal data (.bil,

.bsq, and .bip). As support for vector data structures are incorporated in future versions of the software,

vector import/export tools will also appear.

Because of its widespread use, a worked example of transferring data between Whitebox and ArcGIS is

given below. (Note: you will need ArcGIS installed on your computer to complete the following tasks.)

Open the Export ArcGIS Grid (.flt) tool from within the Data Import/Export toolbox. This tool can be

used to export a Whitebox GAT raster file to an ArcGIS floating-point grid file. This is the

12

recommended way to get Whitebox GAT raster files into ArcGIS, although an alternative approach is

provided by the support for the common ArcGIS ASCII grid file format. Floating-point grid files

consist of a header file (.hdr) and data files (.flt). The user must specify the name of one or more

Whitebox GAT raster files to be exported and the tool will create ArcGIS raster floating-point files

(.hdr and .flt files) for each input file. Output file names are the same of the input files, but have the

modified file extensions. Input the 'Mad River DEM' layer and press OK.

If ArcGIS is not already open, launch the program now. Use the Float to Raster tool, found within the

Conversion Tools toolbox of ArcGIS to ingest the floating-point grid file ('Mad River DEM.flt' and

'Mad River DEM.hdr') into ArcGIS. ArcGIS will convert this generic file format into its native format

for storing raster data and will then automatically display the resulting image.

Notice that the process is reversed to import raster data from ArcGIS to Whitebox GAT. The Raster to

Float tool can be used to create floating-point grid files from ArcGIS raster files and the Whitebox

GAT tool Import ArcGIS Grid (.flt) can then be used to convert this generic file format into a Whitebox

GAT raster grid. Because the ArcGIS binary grid (.flt) format is very similar to a floating-point type

Whitebox GAT binary raster file (.tas) the import and export of these files is usually very quick. The

binary files are simply copied and their extensions, changing the extensions accordingly, and the new

ASCII header files are created. As such, this is a very efficient method for transferring data between the

two programs, particularly when the file sizes are large.