Hydrology toolset

Documentation | Other Specifications | Hydrology toolset

The Hydrology toolset is intended to support water resources applications. It provides the most commonly used functions in hydrological analysis.

The typical hydrologic analysis workflow consists of a digital elevation model (DEM) preparation, a channel network extraction, basins, watersheds delineation and vectorization of the results.

The TatukGIS Developer Kernel (DK) includes various hydrologic tools required in the workflow mentioned above. All of these tools are shared as methods of the TGIS_Hydrology class.

A hydrological workflow may contain steps as follows:

• Identifying DEM problems
  Use Sink method to generate the grid with pit cells and cells for which the flow direction cannot be determined.
• Fill sinks
  Use Fill method to generate the hydrologically conditioned DEM.
• Resolve flats
  Use ResolveFlat method to resolve flat areas in a DEM.
• Flow direction
  Use FlowDirection method to generate a flow direction grid from a DEM.
• Flow accumulation
  Use FlowAccumulation method to generate a flow accumulation grid from a flow direction grid.
• Basin
  Use Basin method to generate a basin grid from a flow direction grid.
• Watershed
  Use Watershed method to generate a watershed grid from a flow direction grid and pour points (vector or grid layer).
• Stream ordering
  Use StreamOrder method to generate a stream order grid from a flow direction and flow accumulation grids and a specified method.
• Hydrology results vectorization
  Use StreamToPolyline method to convert a stream network to polylines, and GridToPolygon class to convert basins/watersheds to polygon.

When performing hydrological analyses, the sequence in which maps are prepared is important. Always start with a DEM with filled sinks (Fill), and then run tools in the order required for the workflow:

• Fill
  • FlowDirection
    • Basin
    • Watershed
    • FlowAccumulation
      • StreamOrder
        • StreamToPolyline
      • StreamToPolyline

So to achieve, e.g. StreamOrder, the following sequence is required:

Fill → FlowDirection → FlowAccumulation → StreamOrder

Tools API is consistent and easy to use, which can be checked out below in the Pipeline script or Hydrology sample application.

Base.Say "Hydrology tutorial"
Layer.Open Result=$dem Name=DEM Path="E:\GisData\TatukGIS\Data\Samples11\World\Countries\Poland\DEM\Bytowski_County.tif"
GIS.FullExtent

; Create layers
Layer.CreateGrid Result=$sink Name=Sink CS=$dem Extent=$dem Width=$dem Height=$dem
Layer.CreateGrid Result=$fill_dem Name=Fill CS=$dem Extent=$dem Width=$dem Height=$dem
Layer.CreateGrid Result=$flow_dir Name=FlowDirection CS=$dem Extent=$dem Width=$dem Height=$dem
Layer.CreateGrid Result=$flow_acc Name=FlowAccumulation CS=$dem Extent=$dem Width=$dem Height=$dem
Layer.CreateGrid Result=$basin Name=Basin CS=$dem Extent=$dem Width=$dem Height=$dem
Layer.CreateGrid Result=$strahler Name=StrahlerOrder CS=$dem Extent=$dem Width=$dem Height=$dem
Layer.CreateVector Result=$basins_vec Name=Basins CS=$dem ShapeType=Polygon
Layer.AddField Layer=$basins_vec Name=BASIN_ID Type=Number Width=10
Layer.CreateVector Result=$streams_vec Name=Streams CS=$dem ShapeType=Arc
Layer.AddField Layer=$streams_vec Name=STREAM_ID Type=Number Width=10

; Run hydrology tools
Hydrology.Sink Destination=$sink SourceDEM=$dem
Hydrology.Fill Destination=$fill_dem SourceDEM=$dem
Hydrology.FlowDirection Destination=$flow_dir SourceDEM=$fill_dem
Hydrology.FlowAccumulation Destination=$flow_acc SourceFlowDirection=$flow_dir
Hydrology.Basin Destination=$basin SourceFlowDirection=$flow_dir Threshold=1000
Hydrology.StreamOrder Destination=$strahler SourceFlowDirection=$flow_dir SourceFlowAccumulation=$flow_acc
Hydrology.StreamToPolyline SourceFlowDirection=$flow_dir SourceStream=$strahler Destination=$streams_vec Field=STREAM_ID
Vectorization.GridToPolygon Source=$basin Destination=$basins_vec Field=BASIN_ID

GIS.Update

All the implemented methods are based on the D8 flow model. In this model, a single flow direction in the direction of the steepest slope towards one of the eight (cardinal and diagonal) grid cells neighboring is used to represent the flow field.

Local depressions (pits, sinks) in the DEM can cause inaccuracy when determining channel networks. These problematic grid cells can be detected by the TGIS_Hydrology.Sink method which generates a map identifying all sinks, flat areas and cells flow towards each other. Sample problematic cells are shown in gray below.

Every hydrological analysis starts with creating a depressionless DEM.

Using information about local artefacts of a dem from map with sinks, user can fix it manually, or use the TGIS_Hydrology.Fill method to generate DEM without pits and flat areas.

Having a hydrologically conditioned DEM, it is possible to use other hydrological tools implemented in the DK with a high degree of certainty about the quality of the results.

The Fill tool with enabled _applySlope option generates a hydrologically conditioned DEM and ensures proper delineation of basins and streams. This is the default.

This tool with the disabled _applySlope option may generate a DEM with flat areas that may still cause unexpected results. Such models need further preparation. The ResolveFlat tool may be use for this purpose.

The next problem to solve, beyond the sinks, is the correction of DEM for flat areas. This is a necessary process for hydrological analyses and modeling, such as the determination of flow directions and accumulations, and the delineation of drainage networks and basins.

If area of interest consists large flat areas, especially in lowlands, TGIS_Hydrology.ResolveFlat method can be used to assign drainage directions over flats. It can be done in two ways:

• Reassigning a flow direction dataset only where the flat area is detected.

• Generating a new DEM with slightly altered elevation for cells in flats.

Flow direction is the first necessary hydrologic characteristic of a terrain. It can be generated using TGIS_Hydrology.FlowDirection method. The flow direction for a cell is the direction water will flow out of the cell. It is encoded to correspond to the orientation of one of the eight cells that surround the cell, as follows.

Using a DEM as an input layer, this method generates a flow direction grid as follows.

What can be illustrated using arrows.

See an example map of the flow direction.

There are four possible conditions to consider in determining flow direction:

• All eight neighboring cells have elevations higher than the center cell. The flow direction is encoded as negative.

• The distance-weighted drop from the center cell is higher for one cell in the neighborhood over all of the other seven and the flow direction is assigned to this cell. This condition occurs for most cells (all cells for a hydrologically conditioned DEM).

• When two or more cells are equal in having the greatest distance-weighted drop, the flow direction is arbitrarily assigned at the last occurrence of the greatest drop.

• All cells are equal. In this case, the cell is located in a flat area and the locations of those neighbors are encoded by summing their neighbor location codes.

Use TGIS_Hydrology.FlowAccumulation method to generate the flow accumulation map.

In the flow accumulation data set, each cell is assigned a value equal to the number of cells that flow to it.

The local highest topographic cells (ridges) have a value of zero and the flow accumulation values increase downwards. Cells that lie on drainage networks have substantially higher values than cells on hill slopes.

In order to improve the visualization of the resulting flow accumulation map, a GeometricalInterval method of classification can be applied.

The drainage basin is a land area where precipitation runs off into streams, rivers, lakes, and reservoirs. It is a land feature that can be identified by tracing a line along the highest elevations between two areas on a map, often a ridge.

TGIS_Hydrology.Basin method delineates areas of land that drain all the streams and rainfall to common outlets localized at the edge of analyzed terrain. These areas are marked with successive identifiers as grid values.

The size of the delineated basins can be limited using the _threshold parameter. This parameter specifies the minimum number of cells needed to create a basin. The default value is 0.

A watershed is an upslope area that contributes flow to a common outlet. The outlet, or pour point, is the point on the surface at which water flows out of an area. It is the lowest point along the boundary of a watershed.

TGIS_Hydrology.Watershed method requires both flow direction data and outlets as a grid, or vector (points) data. Each watershed is marked as grid value, based on its outlet identifier taken from cell values if the input is a grid, or the specified field if the input is a point vector layer.

To obtain better results, pour points should be located to cells of high accumulated flow.

TGIS_Hydrology.StreamOrder method uses both flow direction and flow accumulation data to order branches of the drainage network.

TatukGIS offers up to four ordering methods widely used in hydrological analyses:

• Hack It is a classic stream order with a bottom-up hierarchy that allocates the first order to the river with its mouth at the sea or DEM border (the main stem). Its tributaries are given a number one greater than that of the river or stream into which they discharge.

• Shreve This ordering method gives the outermost tributaries the first order and, at a confluence, the two orders are added together.

• Strahler It is a top-down method in which rivers of the first order are the outermost tributaries. If two streams of the same order merge, the resulting stream is given a number whose value is higher by one. If two rivers with different stream orders merge, the resulting stream is given the higher of the two numbers.

• Topological This bottom-up method of ordering calculates the topological distance of every stream from the outlet.

Similar to the Basin tool, a delineated ordered stream can be limited by the _threshold parameter. This parameter is applied to the flow accumulation dataset and only cells with values greater, or equal than the threshold, are processed. The recommended value is 1% of the maximum value from the flow accumulation grid. This value is automatically assigned by default (_threshold=-1).

For some applications, the vector representation of the hydrologic data is more suitable. Raster to vector conversion can be achieved using TatukGIS DK tools:

• TGIS_Hydrology.StreamToPolyline method for conversion of linear network. The stream network may be represented by flow accumulation, or stream order grid, and the conversion process can be controlled by _threshold parameter. Similar to before, if the input data is flow accumulation, the recommended value is 1% of the maximum value from the flow accumulation grid.
• TGIS_GridToPolygon class for conversion of catchment areas, such as basins and watersheds.

• Barnes, Lehman, Mulla. An Efficient Assignment of Drainage Direction Over Flat Surfaces In Raster Digital Elevation Models“. Computers & Geosciences. Vol 62, Jan 2014, pp 128-135.
• Edwards, P., Williard, K., & Schoonover, J. (2015). Fundamentals of watershed hydrology. Journal of Contemporary Water Research & Education, 154, 3-20.
• Jenson, S. and Domingue, J. (1988) Extracting Topographic Structure from Digital Elevation Data for Geographic Information System Analysis. Photogrammetric Engineering and Remote Sensing, 54, 1593-1600.
• Jurgen Garbrecht, Lawrence W Martz. (1997) The assignment of drainage direction over flat surfaces in raster digital elevation models, Journal of Hydrology, Volume 193, Issues 1–4, Pages 204-213.
• O’Callaghan, J.F. and Mark, D.M. (1984) The Extraction of Drainage Networks from Digital Elevation Data. Computer Vision, Graphics and Image Processing, 28, 328-344.
• Planchon, O., and F. Darboux. 2002. A Fast, Simple and Versatile Algorithm to Fill the Depressions of Digital Elevation Models. Catena 46: 159–176.
• Tarboton, D. G., Bras, R. L. and Rodriguez‐Iturbe, I. (1991), On the extraction of channel networks from digital elevation data. Hydrol. Process., 5: 81-100.
• Zhou, G., Wei, H. & Fu, S. A fast and simple algorithm for calculating flow accumulation matrices from raster digital elevation. Front. Earth Sci. 13, 317–326 (2019).