.TH r.fill.dir 1grass "" "GRASS 7.8.5" "GRASS GIS User's Manual"
.SH NAME
\fI\fBr.fill.dir\fR\fR  \- Filters and generates a depressionless elevation map and a flow direction map from a given elevation raster map.
.SH KEYWORDS
raster, hydrology, sink, fill sinks, depressions
.SH SYNOPSIS
\fBr.fill.dir\fR
.br
\fBr.fill.dir \-\-help\fR
.br
\fBr.fill.dir\fR [\-\fBf\fR] \fBinput\fR=\fIname\fR \fBoutput\fR=\fIname\fR \fBdirection\fR=\fIname\fR  [\fBareas\fR=\fIname\fR]   [\fBformat\fR=\fIstring\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBhelp\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR]  [\-\-\fBui\fR]
.SS Flags:
.IP "\fB\-f\fR" 4m
.br
Find unresolved areas only
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-help\fR" 4m
.br
Print usage summary
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.IP "\fB\-\-ui\fR" 4m
.br
Force launching GUI dialog
.SS Parameters:
.IP "\fBinput\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name of input elevation raster map
.IP "\fBoutput\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name for output depressionless elevation raster map
.IP "\fBdirection\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name for output flow direction map for depressionless elevation raster map
.IP "\fBareas\fR=\fIname\fR" 4m
.br
Name for output raster map of problem areas
.IP "\fBformat\fR=\fIstring\fR" 4m
.br
Aspect direction format
.br
Options: \fIagnps, answers, grass\fR
.br
Default: \fIgrass\fR
.SH DESCRIPTION
\fIr.fill.dir\fR 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 \(dqExtracting topographic structure from
digital elevation model data for geographic information system analysis\(dq
by S.K. Jenson and J.O. Domingue (1988).
.PP
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.
.PP
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. \fIr.fill.dir\fR 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.
.PP
The \fBformat\fR parameter is the type of format at which the user wishes to create
the flow \fBdirection\fR 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 \fIgrass\fR format gives the same category
values as \fIr.slope.aspect\fR
gives for aspect, i.e. angles in degrees counter\-clockwise from east
in 45 degree increments.
The \fIagnps\fR format gives category values from
1\-8, with 1 facing north and increasing values in the clockwise direction.
The \fIanswers\fR 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 all cases, NULL (no data) values are used for cells where direction
cannot be determined.
.PP
In case of local problems, those unfilled areas can be stored optionally.
Each unfilled area in this maps is numbered. The \fB\-f\fR flag
instructs the program to fill single\-cell pits but otherwise to just find
the undrained areas and exit. With the \fB\-f\fR 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.
.PP
In some cases it may be necessary to run \fIr.fill.dir\fR repeatedly (using output
from one run as input to the next run) before all of problem areas are
filled.
.PP
The resulting depressionless elevation
raster map can further be processed to derive slopes and other
attributes required by other hydrological models.
.PP
As any GRASS GIS module, \fIr.fill.dir\fR 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, \fIr.fill.dir\fR is
sensitive to any raster \fIMASK\fR in effect.
.SH NOTES
.RS 4n
.IP \(bu 4n
The \fIr.fill.dir\fR 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.
.IP \(bu 4n
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.
.IP \(bu 4n
Although many hydrological algorithms require depression filling,
advanced algorithms such as those implemented in
\fIr.watershed\fR and
\fIr.sim.water\fR do not require
depressionless digital elevation model to work.
.IP \(bu 4n
The flow direction map can be visualized with
\fId.rast.arrow\fR.
.RE
.SH EXAMPLES
Generic example: create a depressionless (sinkless) elevation
map \fIansi.fill.elev\fR and a flow direction map \fIansi.asp\fR for the
type \(dqgrass\(dq:
.br
.nf
\fC
r.fill.dir input=ansi.elev output=ansi.fill.elev direction=ansi.asp
\fR
.fi
.PP
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.
.br
.nf
\fC
# 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 \(rs
           direction=elev_lid792_1m_dir areas=elev_lid792_1m_error
# generate elevation map of pixelwise differences to see obtained terrain alterations
r.mapcalc \(dqelev_lid792_1m_diff = elev_lid792_1m_filled \- elev_lid792_1m\(dq
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 \(dqelev_lid792_1m_fill_area = if(elev_lid792_1m_diff > 0.0, 1, null() )\(dq
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
\fR
.fi
.br
\fIFigure: Sink\-filled DEM (shown as shaded terrain) with areas of filling shown as vector polygons\fR
.SH REFERENCES
.RS 4n
.IP \(bu 4n
Beasley, D.B. and L.F. Huggins. 1982. ANSWERS (areal nonpoint source watershed environmental
response simulation): User\(cqs manual. U.S. EPA\-905/9\-82\-001, Chicago, IL, 54 p.
.IP \(bu 4n
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).
.IP \(bu 4n
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.
.IP \(bu 4n
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.
.RE
.SH SEE ALSO
\fI
d.rast.arrow,
d.shade,
g.region,
r.fillnulls,
r.relief,
r.slope.aspect
\fR
.SH AUTHORS
Fortran version:
Raghavan Srinivasan, Agricultural Engineering Department, Purdue
University
.br
Rewrite to C with enhancements:
Roger S. Miller
.SH SOURCE CODE
.PP
Available at: r.fill.dir source code (history)
.PP
Main index |
Raster index |
Topics index |
Keywords index |
Graphical index |
Full index
.PP
© 2003\-2020
GRASS Development Team,
GRASS GIS 7.8.5 Reference Manual