1  Bldgrds

Bldgrds creates a digital representation of a channel network; a “stream layer” in GIS terminology. The steps for doing that are described in Chapter 3. The primary input is a Digital Elevation Model (DEM). Bldgrds can utilize a variety of auxiliary input files to control where channels may and may not occur and to direct channel courses (e.g., drainage enforcement to another existing stream layer). To build the channel network, bldgrds will modify elevations within the DEM, for example, to carve an outlet from a closed depression. These altered elevations are used to define flow directions. All subsequent analyses, finding hillslope and channel gradients for example, are based on the original DEM elevations.

1.1 Run-time options

Bldgrds can be run in three ways, controlled by the presence or absence of certain keywords in the input file.

  1. Calibrate. With the CALIBRATE keyword (no arguments), bldgrds will calculate flow directions and flow accumulation without initiating any channels. The D-infinity flow-direction algorithm is used for all DEM cells. Flow-direction and flow-accumulation rasters are produced. Two additional output files are also created:

    1. areathreshold_ID.csv. This is a comma delimited file. There are a series of eight header lines with details about the parameters used for the bldgrds run. These are: i) the path to the DEM and other input data files, ii) the dataset ID, iii) whether or not specific contributing area (area divided by the contour length crossed by flow exiting a DEM cell) was used, iv) Smin, the gradient limit below which DEM cells are classified as low-gradient terrain, v) Smax, the gradient limit above which DEM cells are classified as high-gradient terrain, vi) alpha, the exponent used for slope with the area-slope function for channel initiation, vii) Accumulation length scale, diameter in meters overwhich slope aspect is measured, and viii) Gradient length scale, the diameter in meters over which hillslope gradient is measured. Following the header lines are two columns, one for the area-slope function value and one for the channel density obtained (km/km2) using that area-slope value as the threshold for channel initiation. Units for the AREA column depend on whether or not specific area was used. If it was, the units are meters, if not, the units are square meters. The values for high-gradient areas are listed first, followed by the values for low-gradient areas. These entries are used to plot the log-log plots of threshold value versus channel density, used to find ball-park values for area-slope thresholds for channel initiation.

    2. threshold_ID.flt. A binary floating point raster indicating the area-slope threshold required to allow channel initiation at each DEM cell. This can be plotted in a GIS to see how far upslope different threshold values extend.

  2. No Channels. Initiated with the NO CHANNELS keyword. This is similar to a calibration run, in that no channels are initiated, but the two threshold output files are not created.

  3. If neither of the CALIBRATE or NO CHANNELS keywords are included in the input file, bldgrds will create a channel network with the associated output files.

1.2 Input data files

1.2.1 DEM raster

The primary and only required input file is a DEM (keyword DEM FILE), consisting of a raster of elevation values in either binary floating point (.flt) or tiff (.tif) format (only uncompressed tiff files or those with LZW compression can currently be read). NetStream programs use a default DEM file name of elev_ID, where “ID” is a character string that identifies the dataset. It is copied from the DEM-file name and applied as a suffix to output data files created from the DEM.

A variety of optional input files can be used to control placement of channels.

1.2.2 GMI or Flow-Indicator raster

A “Geomorphic Index” raster (keyword GMI RASTER). These are used by the US Geological Survey to aid contractors building elevation-derived hydrography (see New Developments in Elevation-Derived Hydrography Acquisition Specifications and Validation). These prove useful for guiding channel courses in low-relief terrain. The NetStream program FlowCat can be used to build a GMI raster.

1.2.3 Topographic Position Index (TPI)

A topographic position index raster (keyword LOCAL RELIEF RASTER) can be used as a criteria for identifying channel initiation points and/or for guiding channel courses, similar to a GMI raster. The NetStream program makeGrids can be used to build a topographic position raster (also referred to as a local relief raster).

1.2.4 Water mask

One or more water-mask files may be specified (keyword WATER MASK). A water mask delineates areas of open water along larger river channels and water bodies and is provided as either a polygon shapefile or a raster with nonzero values indicating the mask. Lidar laser signals are largely absorbed by water, so zones of open water lack signal returns in the lidar point cloud. The DEM elevations through these zones are interpolated from signals along the edge of the channel or are set to a constant elevation by hydro-flattening. In either case, the DEM provides no guidance for channel courses through these zones and the traced channel centerlines can wonder back and forth within the zone, as described in Section 3.4.2. Where this occurs, measured channel length will be too long and calculated channel gradients will therefore be too small.

1.2.5 Road crossings

One or more polyline shapefiles can be specified for breaching high points in a DEM (keyword LINE EXCAVATE). With high-resolution DEMs, road prisms are resolved and can act to divert the traced flow paths. Culverts and other drainage structures are not generally visible in the DEM and need to be specified from other data sources. This is typically done by manually digitizing a line that crosses the road prism at known or inferred culvert locations, as described in Section 3.5.

Bldgrds will find the points of highest and lowest elevation along the digitized line and “excavate” a swale following the line from the high point to the low point. The modified DEM is then used for determining flow accumulation and resulting channel courses.

1.2.6 Channel mask

One or more polyline shapefiles may be specified for drainage enforcement (keyword CHANNEL MASK). Drainage enforcement can be performed in two ways

  1. By excavating a swale into the DEM along the channel-mask line, a technique referred to as “stream burning”. Keyword arguments specify the depth and width of the swale. Flow directions are then determined for the DEM with the burned-in swale. All elevation derivatives, however, such as channel gradient, are calculated using the original DEM, so if the enforced channel does not follow accurate channel flow paths on the DEM, for example, if it goes up the side of the valley wall, calculated channel attributes will be in error.

  2. By setting flow directions to explicitly follow the channel mask line. This over rides flow directions based on elevation relationships in the DEM. Up- and down-stream flow directions are based on the order in which the vertices along the channel mask line occur, so all lines must be digitized in a consistent direction, either all upstream or all downstream. This directional enforcement is triggered with the argument DIRECTIONAL. The default digitization direction assumed is downstream. If digitization is upstream, then the argument UPSTREAM is required.

A combination of both burning in and directional enforcement can be used. In that case, the flow directions are set by the digitized line and the depth and width of the swale determine the distance overwhich flow is directed towards the enforced channel.

Channel masks are useful for guiding channel locations through low-relief areas where the DEM topography provides little guidance or to force traced channels to match an existing stream layer.

1.3 Output data files

Linked-node list. A binary file that stores the traced channel network in a linked-node data structure. The file is named nodeNet_ID.dat, where the “ID” is the character string taken from the DEM file name (elev_ID). An ascii log file (nodeNet_ID.log) is also created which provides information about how and when the data file was created.

Flow accumulation raster. A binary floating point raster file giving the contributing area to each DEM cell in number of inflowing cells. The file is named accum_ID.flt, with accompanying ascii header (accum_ID.hdr) and log (accum_ID.log) files.

Flow direction raster. A binary floating point raster file giving the flow direction for each DEM grid point in radians measured from north. The file is named ang_ID.flt, with accompanying ascii header (ang_ID.hdr) and log (ang_ID.log) files.

1.4 Keyword: arguments for input files

1.4.1 DEM File

DEM FILE: Filename # required.

  • Filename specifies either a binary floating point raster (.flt) or tiff (.tif) file (only uncompressed tiff files or those with LZW compression can currently be read). DEM files are named elev_ID, where the “ID” is a character string indicating the data set. The file extention does not need to be included, but the entire path is required (e.g., c:\data\wrangell\elev_wrangell).

1.4.2 GMI Raster

GMI RASTER: Filename, DIG = x, INIT, MIN GMI = i # optional. Geomorphic Index Raster.

  • Filename, either a .flt or .tif file, specified with the full path name. No default name.

  • “DIG” triggers drainage enforcement along GMI patches, with “x” indicating a value in meters. The value of a GMI-raster pixel indicates the number of topographic indices indicative of a channel at the location of that pixel. These values typically range from zero up to four, because four topographic indices are typically used to generate a GMI raster. Where GMI cells have a value greater than zero, the DEM elevation is lowered by the value GMI*x. So if DIG = 0.5 is specified and GMI = 4, the elevation at that DEM cell is lowered 2 meters. If DIG = 0. or no DIG argument is included, then no drainage enforcement is performed with the GMI raster.

  • MIN GMI, if present, limits channel initiation to pixels where the GMI value is greater than or equal to the specified value. MIN GMI = 2 will limit channel initiation to locations where the GMI value is \(\geq\) 2. If no MIN GMI argument is included, channel initiation can occur anywhere the channel-initiation criteria are met.

SCRATCH DIRECTORY: directory path # required. Location for writing temporary files to disk, e.g., c:\temp.

WATER MASK: FILE=filename, MINIMUM PATCH SIZE = x, MINIMUM GRADIENT = x, RADIUS = x, MINIMUM WIDTH = x, INCISE = x, PRECLUDE INITIATION, ALLOW INITIATION, FORCE INITIATION, SET TO MINIMUM ELEVATION, LOWER ELEVATION, INCISE TO CENTER

  • FILE = filename, full path and name of either a polygon shapefile or a raster file indicating a water mask. If a polygon file, all polygons are interpreted as part of the mask. If a raster file, any pixel with value greater than zero is interpreted as part of the mask.

  • MINIMUM PATCH SIZE = x, MINIMUM GRADIENT = x. These influence the size of the masked zones that get interpreted as a water mask. Optimal values need to be determined by trial and error because they vary depending on the shape and complexity of the masks. Default values are set to MINIMUM PATCH SIZE = 250. and MINIMUM GRADIENT = 0.75. These will work well for most cases.

  • RADIUS = x, limits the width of water-mask patches that can be resolved. Larger values cause longer run times, but the radius must be at least half as large as the largest width of any river or water body within the dataset, otherwise the traced channel centerlines will not follow the center of the mask.

  • MINIMUM WIDTH = x, water mask patches with a along-flow-direction width less than x are ignored, with x in meters.

  • PRECLUDE INITIATION. If this argument is included, channel initiation is not allowed within the water mask.

  • ALLOW INITIATION. If this argument is included, channel initiation is allowed, but not required, within the water mask.

  • FORCE INITIATION. If this argument is included, channel initiation is forced so that all water-mask centerlines are included in the channel network.

  • SET TO MINIMUM ELEVATION. This argument will cause all elevations within the watermask to be set to the minimum elevation found within the mask. This is appropriate for water bodies, which (typically) have a constant water-surface elevation. This is not generally used for river water masks.

  • INCISE TO CENTER. This argument is used to force traced channel flow paths to the center of the water mask polygons.

  • Multiple water-mask files may be specified, each with its own set of arguments. For example, separate water masks might be used for rivers and for water bodies, or for small rivers, for which a small radius can be specified (with a shorter run time) and large rivers, such as at river mouths at estuaries, for which a large radius may be required (with a longer run time).

CHANNEL MASK: FILE=filename, DIG = x, RADIUS = x, MAX SLOPE = x, INIT, FORCE INITIATION, DIRECTIONAL, UPSTREAM, TOP POINT, POINT RADIUS

  • FILE = filename, full path and name of a polyline shapefile.

  • DIG = x, the depth in meters to excavate the channel-enforcement swale.

  • RADIUS = x, the width of the swale in meters measured from the channel centerline. The total swale width will be twice the radius. The DIG and RADIUS arguments determine the size of the swale. Flow directions within the swale will be directed toward the center of the swale.

  • MAX SLOPE = x, channel enforcement is not performed where the slope gradient exceeds this value. This can be used to prevent poorly located enforcement lines from extending onto channel-adjacent hillslopes.

  • INIT, if this argument is included, channel initiation is allowed along enforced channels if all channel-initiation criteria are met.

  • FORCE INITIATION, if this argument is included, channel initiation is forced within enforced channels, even if the channel-initiation criteria are not met.

  • DIRECTIONAL, this argument indicates that the channel-mask polylines are digitized consistently in either a downstream or upstream direction. It then forces the flow directions to follow the digitized line. The default direction is downstream. If the polylines are digitized in an upstream direction, then the UPSTREAM argument must also be included.

  • UPSTREAM, this argument indicates that the channel-mask polylines are digitized in an upstream direction. This argument is only required if the DIRECTIONAL argument.

  • TOP POINT, if this argument is present, the enforcement lines are traced to their upstream end and a channel initiation point placed at the most likely initiation location within the radius (in meters) specified by the POINT RADIUS argument. The channels are not enforced downstream of that point.

  • POINT RADIUS, the radius (meters) overwhich to search for the most likely channel initiation point at the upstream end of channel-enforcement lines.