dwww: tpablo.net

r.fill.dir(1grass) GRASS GIS User's Manual r.fill.dir(1grass)

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 pa-
per 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 direc-
tion 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 us-
ing 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 as-
signs 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 prop-
agating 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 an-
swers format gives category values from 0-360 degrees, with 0 (repre-
sented as 360) facing east and values increasing in the counter-clock-
wise direction at 45 degree increments. In all cases, NULL (no data)
values are used for cells where direction cannot be determined.

In case of local problems, those unfilled areas can be stored option-
ally. Each unfilled area in this maps is numbered. The -f flag in-
structs 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 ar-
eas are filled.

The resulting depressionless elevation raster map can further be pro-
cessed to derive slopes and other attributes required by other hydro-
logical 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 direc-
tion 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 con-
sequences such as loss of wetlands.

• Although many hydrological algorithms require depression fill-
ing, advanced algorithms such as those implemented in r.water-
shed and r.sim.water do not require depressionless digital ele-
vation 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 in-
formation 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.

SEE ALSO
d.rast.arrow, d.shade, g.region, r.fillnulls, r.relief, r.slope.aspect

AUTHORS
Fortran version: Raghavan Srinivasan, Agricultural Engineering Depart-
ment, Purdue University
Rewrite to C with enhancements: Roger S. Miller

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

Accessed: unknown

GRASS 7.8.7 r.fill.dir(1grass)

Generated by dwww version 1.14 on Sat Jun 13 11:06:05 CEST 2026.