Whitebox Geospatial Analysis Tools Tutorial Series. Tutorial 1: Using Whitebox GAT

Transcription

1 1 Whitebox Geospatial Analysis Tools Tutorial Series Tutorial 1: Using Whitebox GAT

2 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, This tutorial has been prepared by John Lindsay as part of Government of Canada contract #AM W.

3 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 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 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 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 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 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 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 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 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 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 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 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.