Mapping Watersheds in Whitebox GAT

Two of the most common activities involving digital elevation models (DEMs) include extracting stream networks and mapping watersheds. A watershed, often referred to as a drainage basin, is the land area that drains surface waters to a particular location, or outlet, in the landscape. I frequently get asked how to map watersheds using Whitebox GAT and so I thought that I would cover that topic in a blog. The Watershed tool, located in the Hydrological Tools toolbox, is used to map the areas draining to one or more outlets.

Whitebox's Watershed Tool

Whitebox’s Watershed Tool (click for full size)

The Watershed tool requires two input files. The first input is a flow pointer raster derived using the D8 flow algorithm. The D8 flow pointer raster is a remarkably useful grid and, although it isn’t much to look at, it is used as a main input for dozens of tools in Whitebox GAT. That’s because it can be used to determine the local drainage direction network, that is, the tree graph that connects every grid cell in a DEM to the upslope cells that drain to each cell and the downslope flow path that each cell drains to. This grid must be created using the D8, or steepest descent, flow algorithm and it must be created from a DEM that has been pre-processed to remove all artefact topographic depressions, i.e. areas of internal drainage. This is usually achieved by either filling or breaching (channelling) the depressions in the DEM. The D8 flow pointer raster is actually quite fast to create from a hydrologically corrected DEM, so you might wonder why Whitebox’s Watershed tool doesn’t just have you input the DEM and then it calculates the D8 pointer internally, saving you the hassle. After all, you’re unlikely to ever want to display the pointer raster. The answer is that a common terrain analysis workflow may involve numerous analyses (stream network extraction, stream network analysis, watershed extraction, etc.) that each require this pointer grid. They could all start off by calculating the pointer grid from your DEM but that would be terribly redundant. And since each workflow is unique this approach is the most flexible.

Now then, the second input to the Watershed tool is a pour point, or outlet, file. This can be either a raster grid or a vector points file (shapefile). If the D8 flow pointer is used to figure out how each grid cell in a raster DEM is connected to the network of overland flow paths, then the pour point file tells the tool which points in the network to extract the drainage basin, i.e. all of the upslope grid cells that drain to a particular pour point. If the pour points file is a shapefile containing multiple points, a watershed will be extracted for each of these points, with a unique identifier (usually the FID) assigned to each watershed. If the pour points file is a raster, watersheds will be extracted for all non-zero positive valued grid cells and the watershed identifier will be the same as the pour point values.

So, where are you going to get these pour points? Chances are that if you’re extracting watersheds then you likely have some points of interest in mind for which you’d like to map the drainage basin. These are usually points along the stream network. Sometimes they’re locations where you have data collected, for example a hydrometric station where you have information about stream discharge and water quality. You may even have the GPS coordinates for the points that you’ve imported into Whitebox GAT (see the Import CSV and Import XYZ tools). If this isn’t the case, then you’re probably going to want to digitize pour points using Whitebox’s on-screen digitizing capabilities. Take a look at the tutorial in the Whitebox help documentation called, How to digitize new vectors, for detailed instructions on how to do this. To summarize this process briefly, the steps involved in doing this are as follows. First, create either a flow accumulation grid using the D8 flow accumulation tool and display the raster (a vector streams layer can also be useful for this). Larger values in the flow accumulation grid will coincide with valley bottoms and streams channels. Second, create a new vector points file (Create New Shapefile tool). Zooming into the areas of interest, use the functions of on-screen digitizing tools to digitize individual pour points.

On-screen digitizing (click on image for full size)

On-screen digitizing (click on image for full size)

Okay, here’s an important point, whether you’ve imported your pour points from GPS coordinates gathered in the field or digitized them on-screen, it is quite unlikely that the your pour points coincide with the digital stream. Even if you used a surveyor-grade, highly precise GPS to get coordinates down to the nearest millimetre and you know for certain that the points are on the actual stream, it really only matters if the points lie on the path of the digital stream, i.e. the stream within the overland flow network in the DEM. Otherwise, if one or more of the pour points fall off of the digital stream even by one grid cell, you’ll extract a ‘stub watershed’ (I think I just made this term up, but it’s a good one!). The image below is an example of this. The pour point was clearly intended to be located at the outlet to the smaller basin just above the confluence (where stream tributaries join). Whether or not it is on the actual stream, or even the mapped stream, if it falls off of the path of the digital flow path, the mapped watershed will not be the intended watershed.

A stub watershed outlined in pale green for the red pour point.

A stub watershed outlined in pale green for the red pour point.

To fix this particular problem, you need to relocate your pour points so that they are coincident with the digital stream, denoted either by the DEM extracted stream network or the flow accumulation raster from which the extracted streams are derived. This task is what in ArcGIS terminology is known as Snap Pour Points, so named by the tool used to perform the operation, which is supposed to snap the pour point onto the digital stream. Whitebox GAT also has a Snap Pour Points tool, which works the same way. You give the tool a file containing one or more pour points and a flow accumulation raster, and the tool will reposition each outlet to coincide with the grid cell with the highest flow accumulation value within a circular neighbourhood of a specified radius. Here’s the thing…don’t use this tool! It’s effect can be profoundly awful, particularly when you have pour points located at the outlets of sub-basins in a larger network, which is often the case. Take the example in the ‘stub-watershed’ figure above. The pour point is intended to be located above the confluence at the outlet of the smaller tributary. Snap Pour Points will relocated it below the confluence (the highest flow accumulation value) and the extracted watershed will not only include the smaller sub-basin but also will include the main stream trunk as well…it will be many times larger than intended. Instead, I recommend using the Jenson Snap Pour Points tool, which will reposition each pour point to the nearest stream cell, which is much more likely to coincide with the position that you intended and less likely to result in over-sized watersheds. I wrote a paper on this topic that if you’re interested in you can contact me and I’ll forward to you.

So that’s it, after you have your D8 flow pointer, extracted from your hydrologically corrected DEM, and a file containing one or more properly positioned pour points, you can run the Watershed tool and you’ll get an output raster containing the drainage basins which direct surface waters to each of your specified outlets. You may want to use the Raster To Vector Polygons tool to turn the watersheds into a vector layer for map display as a last step. Oh, and by the way, if you have an extracted stream network you can extract all sorts of interesting watershed related layers like sub-basins, hillslopes, and Strahler order basins. Watershed mapping can reveal important information about drainage within a landscape and is a very powerful form of spatial analysis. If you have any questions, post them to the comments section below. And, as always, best wishes and happy geoprocessing.

John Lindsay



5 thoughts on “Mapping Watersheds in Whitebox GAT

  1. I have used the ArcGIS hydrology toolsets before. Glad to see all kinds of Hydrological Tools in Whitebox.The Jenson Snap Pour Points is definitely better than the ArcGIS method.

  2. William Lidberg says:

    I have a large number of pour points and i want to extract a individual watershed for each one. The problem i have is that Whitebox gives me “sub basins”. For example, the outlet of the entire watershed should generate a watershed with the entire catchment. but instead i get a watershed with half the catchment from the outlet point and then overlapping sub basins from the other pour points. Is there a way to extract the complete watershed for each point in a shapefile with a lot of pour points?

    • Okay William, what you want is the Unnest Basins tool, which I have been meaning to write for quite a long time. Your comment has prompted me to finally do so. I’ll email you shortly with the script and details on how to use it. Essentially it will take a D8 flow pointer and a shapefile of outlet points and will output a series of rasters containing the complete watershed of each outlet. All upstream outlets of a certain outlet will be found in separate rasters. Rasters can contain multiple watersheds, but each watershed in a raster will have a similar ‘nesting order’, where nesting is determined as the number of downstream outlets.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s