Ubuntu Manpage: r.fill.dir - Filters and generates a depressionless elevation map and a flow direction map from a given

name
keywords
synopsis
description
notes
examples
references
see also
authors
source code

NAME

       r.fill.dir   - Filters and generates a depressionless elevation map and a flow direction map from a given
       elevation raster map.

KEYWORDS

       raster, hydrology, sink, fill sinks, depressions

SYNOPSIS

       r.fill.dir
       r.fill.dir --help
       r.fill.dir [-f] input=name output=name  direction=name   [areas=name]    [format=string]    [--overwrite]
       [--help]  [--verbose]  [--quiet]  [--ui]

   Flags:
       -f
           Find unresolved areas only

       --overwrite
           Allow output files to overwrite existing files

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

   Parameters:
       input=name [required]
           Name of input elevation raster map

       output=name [required]
           Name for output depressionless elevation raster map

       direction=name [required]
           Name for output flow direction map for depressionless elevation raster map

       areas=name
           Name for output raster map of problem areas

       format=string
           Aspect direction format
           Options: agnps, answers, grass
           Default: grass

DESCRIPTION

r.fill.dir filters and generates a depressionless elevation map and a flow direction map from a given
raster elevation map. The method adopted to filter the elevation map and rectify it is based on the
paper titled "Extracting topographic structure from digital elevation model data for geographic
information system analysis" by S.K. Jenson and J.O. Domingue (1988).

The procedure takes an elevation layer as input and initially fills all the depressions with one pass
across the layer. Next, the flow direction algorithm tries to find a unique direction for each cell. If
the watershed program detects areas with pothholes, it delineates this area from the rest of the area and
once again the depressions are filled using the neighborhood technique used by the flow direction
routine. The final output will be a depressionless elevation layer and a unique flow direction layer.

This (D8) flow algorithm performs as follows: At each raster cell the code determines the slope to each
of the 8 surrounding cells and assigns the flow direction to the highest slope out of the cell. If there
is more than one equal, non-zero slope then the code picks one direction based on preferences that are
hard-coded into the program. If the highest slope is flat and in more than one direction then the code
first tries to select an alternative based on flow directions in the adjacent cells. r.fill.dir iterates
that process, effectively propagating flow directions from areas where the directions are known into the
area where the flow direction cannot otherwise be resolved.

The format parameter is the type of format at which the user wishes to create the flow direction map.
The flow direction map can be encoded in GRASS GIS aspect format, ANSWERS (Beasley et.al, 1982), or AGNPS
(Young et.al, 1985) format, so that it can be readily used as input to other GRASS GIS modules or the
aforementioned hydrological models. The grass format gives the same category values as r.slope.aspect
gives for aspect, i.e. angles in degrees counter-clockwise from east in 45 degree increments. The agnps
format gives category values from 1-8, with 1 facing north and increasing values in the clockwise
direction. The answers format gives category values from 0-360 degrees, with 0 (represented as 360)
facing east and values increasing in the counter-clockwise direction at 45 degree increments.

In case of local problems, those unfilled areas can be stored optionally. Each unfilled area in this
maps is numbered. The -f flag instructs the program to fill single-cell pits but otherwise to just find
the undrained areas and exit. With the -f flag set the program writes an elevation map with just
single-cell pits filled, a direction map with unresolved problems and a map of the undrained areas that
were found but not filled. This option was included because filling DEMs was often not the best way to
solve a drainage problem. These options let the user get a partially-fixed elevation map, identify the
remaining problems and fix the problems appropriately.

In some cases it may be necessary to run r.fill.dir repeatedly (using output from one run as input to the
next run) before all of problem areas are filled.

The resulting depressionless elevation raster map can further be processed to derive slopes and other
attributes required by other hydrological models.

As any GRASS GIS module, r.fill.dir is sensitive to the computational region settings. Thus the module
can be used to generate a flow direction map for any sub-area within the full map layer. Also, r.fill.dir
is sensitive to any raster MASK in effect.

NOTES

           •   The r.fill.dir module can be used not only to fill depression, but also to detect water bodies or
               potential water bodies based on the nature of the terrain and the digital elevation model used.

           •   Not all depressions are errors in digital elevation models. In fact, many  are  wetlands  and  as
               Jenkins  and  McCauley  (2006)  note  careless  use  of depression filling may lead to unintended
               consequences such as loss of wetlands.

           •   Although many hydrological algorithms require depression filling,  advanced  algorithms  such  as
               those  implemented in r.watershed and r.sim.water do not require depressionless digital elevation
               model to work.

           •   The flow direction map can be visualized with d.rast.arrow.

EXAMPLES

       Generic example: create a depressionless (sinkless) elevation map ansi.fill.elev and a flow direction map
       ansi.asp for the type "grass":
       r.fill.dir input=ansi.elev output=ansi.fill.elev direction=ansi.asp

       North Carolina sample dataset example: The LiDAR derived 1m elevation map is sink-filled. The outcome are
       a depressionless elevation map, the flow direction map and an error map.
       # set computational region to elevation map
       g.region raster=elev_lid792_1m -p
       # generate depressionless DEM and related maps
       r.fill.dir input=elev_lid792_1m output=elev_lid792_1m_filled \
                  direction=elev_lid792_1m_dir areas=elev_lid792_1m_error
       # generate elevation map of pixelwise differences to see obtained terrain alterations
       r.mapcalc "elev_lid792_1m_diff = elev_lid792_1m_filled - elev_lid792_1m"
       r.colors elev_lid792_1m_diff color=differences
       # assess univariate statistics of differences
       r.univar -e elev_lid792_1m_diff
       # vectorize filled areas (here all fills are of positive value, see r.univar output)
       r.mapcalc "elev_lid792_1m_fill_area = if(elev_lid792_1m_diff > 0.0, 1, null() )"
       r.to.vect input=elev_lid792_1m_fill_area output=elev_lid792_1m_fill_area type=area
       # generate shaded terrain for better visibility of results
       r.relief input=elev_lid792_1m_filled output=elev_lid792_1m_filled_shade
       d.mon wx0
       d.shade shade=elev_lid792_1m_filled_shade color=elev_lid792_1m_filled
       d.vect elev_lid792_1m_fill_area type=boundary color=red
       Figure: Sink-filled DEM (shown as shaded terrain) with areas of filling shown as vector polygons

REFERENCES

           •   Beasley, D.B. and L.F. Huggins. 1982. ANSWERS  (areal  nonpoint  source  watershed  environmental
               response simulation): User’s manual. U.S. EPA-905/9-82-001, Chicago, IL, 54 p.

           •   Jenkins,  D.  G.,  and  McCauley,  L.  A.  2006.   GIS,  SINKS,  FILL, and disappearing wetlands:
               unintended consequences in algorithm development  and  use.   In  Proceedings  of  the  2006  ACM
               symposium on applied computing (pp. 277-282).

           •   Jenson,  S.K.,  and  J.O. Domingue. 1988. Extracting topographic structure from digital elevation
               model data for geographic information system analysis. Photogram.  Engr.  and  Remote  Sens.  54:
               1593-1600.

           •   Young,  R.A.,  C.A.  Onstad,  D.D.  Bosch  and W.P. Anderson. 1985. Agricultural nonpoint surface
               pollution models (AGNPS) I and II model documentation. St. Paul: Minn. Pollution  control  Agency
               and Washington D.C., USDA-Agricultural Research Service.

AUTHORS

       Fortran version: Raghavan Srinivasan, Agricultural Engineering Department, Purdue University
       Rewrite to C with enhancements: Roger S. Miller

       Last changed: $Date: 2017-11-25 23:35:40 +0100 (Sat, 25 Nov 2017) $

SOURCE CODE

       Available at: r.fill.dir source code (history)

       Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2018 GRASS Development Team, GRASS GIS 7.4.0 Reference Manual