1r.fill.dir(1) GRASS GIS User's Manual r.fill.dir(1)
2
3
4
6 r.fill.dir - Filters and generates a depressionless elevation map and
7 a flow direction map from a given elevation raster map.
8
10 raster, hydrology, sink, fill sinks, depressions
11
13 r.fill.dir
14 r.fill.dir --help
15 r.fill.dir [-f] input=name output=name direction=name [areas=name]
16 [format=string] [--overwrite] [--help] [--verbose] [--quiet]
17 [--ui]
18
19 Flags:
20 -f
21 Find unresolved areas only
22
23 --overwrite
24 Allow output files to overwrite existing files
25
26 --help
27 Print usage summary
28
29 --verbose
30 Verbose module output
31
32 --quiet
33 Quiet module output
34
35 --ui
36 Force launching GUI dialog
37
38 Parameters:
39 input=name [required]
40 Name of input elevation raster map
41
42 output=name [required]
43 Name for output depressionless elevation raster map
44
45 direction=name [required]
46 Name for output flow direction map for depressionless elevation
47 raster map
48
49 areas=name
50 Name for output raster map of problem areas
51
52 format=string
53 Aspect direction format
54 Options: agnps, answers, grass
55 Default: grass
56
58 r.fill.dir filters and generates a depressionless elevation map and a
59 flow direction map from a given raster elevation map. The method
60 adopted to filter the elevation map and rectify it is based on the pa‐
61 per titled "Extracting topographic structure from digital elevation
62 model data for geographic information system analysis" by S.K. Jenson
63 and J.O. Domingue (1988).
64
65 The procedure takes an elevation layer as input and initially fills all
66 the depressions with one pass across the layer. Next, the flow direc‐
67 tion algorithm tries to find a unique direction for each cell. If the
68 watershed program detects areas with pothholes, it delineates this area
69 from the rest of the area and once again the depressions are filled us‐
70 ing the neighborhood technique used by the flow direction routine. The
71 final output will be a depressionless elevation layer and a unique flow
72 direction layer.
73
74 This (D8) flow algorithm performs as follows: At each raster cell the
75 code determines the slope to each of the 8 surrounding cells and as‐
76 signs the flow direction to the highest slope out of the cell. If
77 there is more than one equal, non-zero slope then the code picks one
78 direction based on preferences that are hard-coded into the program.
79 If the highest slope is flat and in more than one direction then the
80 code first tries to select an alternative based on flow directions in
81 the adjacent cells. r.fill.dir iterates that process, effectively prop‐
82 agating flow directions from areas where the directions are known into
83 the area where the flow direction cannot otherwise be resolved.
84
85 The format parameter is the type of format at which the user wishes to
86 create the flow direction map. The flow direction map can be encoded
87 in GRASS GIS aspect format, ANSWERS (Beasley et.al, 1982), or AGNPS
88 (Young et.al, 1985) format, so that it can be readily used as input to
89 other GRASS GIS modules or the aforementioned hydrological models. The
90 grass format gives the same category values as r.slope.aspect gives for
91 aspect, i.e. angles in degrees counter-clockwise from east in 45 degree
92 increments. The agnps format gives category values from 1-8, with 1
93 facing north and increasing values in the clockwise direction. The an‐
94 swers format gives category values from 0-360 degrees, with 0 (repre‐
95 sented as 360) facing east and values increasing in the counter-clock‐
96 wise direction at 45 degree increments. In all cases, NULL (no data)
97 values are used for cells where direction cannot be determined.
98
99 In case of local problems, those unfilled areas can be stored option‐
100 ally. Each unfilled area in this maps is numbered. The -f flag in‐
101 structs the program to fill single-cell pits but otherwise to just find
102 the undrained areas and exit. With the -f flag set the program writes
103 an elevation map with just single-cell pits filled, a direction map
104 with unresolved problems and a map of the undrained areas that were
105 found but not filled. This option was included because filling DEMs was
106 often not the best way to solve a drainage problem. These options let
107 the user get a partially-fixed elevation map, identify the remaining
108 problems and fix the problems appropriately.
109
110 In some cases it may be necessary to run r.fill.dir repeatedly (using
111 output from one run as input to the next run) before all of problem ar‐
112 eas are filled.
113
114 The resulting depressionless elevation raster map can further be pro‐
115 cessed to derive slopes and other attributes required by other hydro‐
116 logical models.
117
118 As any GRASS GIS module, r.fill.dir is sensitive to the computational
119 region settings. Thus the module can be used to generate a flow direc‐
120 tion map for any sub-area within the full map layer. Also, r.fill.dir
121 is sensitive to any raster MASK in effect.
122
124 • The r.fill.dir module can be used not only to fill depression,
125 but also to detect water bodies or potential water bodies based
126 on the nature of the terrain and the digital elevation model
127 used.
128
129 • Not all depressions are errors in digital elevation models. In
130 fact, many are wetlands and as Jenkins and McCauley (2006) note
131 careless use of depression filling may lead to unintended con‐
132 sequences such as loss of wetlands.
133
134 • Although many hydrological algorithms require depression fill‐
135 ing, advanced algorithms such as those implemented in r.water‐
136 shed and r.sim.water do not require depressionless digital ele‐
137 vation model to work.
138
139 • The flow direction map can be visualized with d.rast.arrow.
140
142 Generic example: create a depressionless (sinkless) elevation map
143 ansi.fill.elev and a flow direction map ansi.asp for the type "grass":
144 r.fill.dir input=ansi.elev output=ansi.fill.elev direction=ansi.asp
145
146 North Carolina sample dataset example: The LiDAR derived 1m elevation
147 map is sink-filled. The outcome are a depressionless elevation map, the
148 flow direction map and an error map.
149 # set computational region to elevation map
150 g.region raster=elev_lid792_1m -p
151 # generate depressionless DEM and related maps
152 r.fill.dir input=elev_lid792_1m output=elev_lid792_1m_filled \
153 direction=elev_lid792_1m_dir areas=elev_lid792_1m_error
154 # generate elevation map of pixelwise differences to see obtained terrain alterations
155 r.mapcalc "elev_lid792_1m_diff = elev_lid792_1m_filled - elev_lid792_1m"
156 r.colors elev_lid792_1m_diff color=differences
157 # assess univariate statistics of differences
158 r.univar -e elev_lid792_1m_diff
159 # vectorize filled areas (here all fills are of positive value, see r.univar output)
160 r.mapcalc "elev_lid792_1m_fill_area = if(elev_lid792_1m_diff > 0.0, 1, null() )"
161 r.to.vect input=elev_lid792_1m_fill_area output=elev_lid792_1m_fill_area type=area
162 # generate shaded terrain for better visibility of results
163 r.relief input=elev_lid792_1m_filled output=elev_lid792_1m_filled_shade
164 d.mon wx0
165 d.shade shade=elev_lid792_1m_filled_shade color=elev_lid792_1m_filled
166 d.vect elev_lid792_1m_fill_area type=boundary color=red
167 Figure: Sink-filled DEM (shown as shaded terrain) with areas of filling
168 shown as vector polygons
169
171 • Beasley, D.B. and L.F. Huggins. 1982. ANSWERS (areal nonpoint
172 source watershed environmental response simulation): User’s
173 manual. U.S. EPA-905/9-82-001, Chicago, IL, 54 p.
174
175 • Jenkins, D. G., and McCauley, L. A. 2006. GIS, SINKS, FILL,
176 and disappearing wetlands: unintended consequences in algorithm
177 development and use. In Proceedings of the 2006 ACM symposium
178 on applied computing (pp. 277-282).
179
180 • Jenson, S.K., and J.O. Domingue. 1988. Extracting topographic
181 structure from digital elevation model data for geographic in‐
182 formation system analysis. Photogram. Engr. and Remote Sens.
183 54: 1593-1600.
184
185 • Young, R.A., C.A. Onstad, D.D. Bosch and W.P. Anderson. 1985.
186 Agricultural nonpoint surface pollution models (AGNPS) I and II
187 model documentation. St. Paul: Minn. Pollution control Agency
188 and Washington D.C., USDA-Agricultural Research Service.
189
191 d.rast.arrow, d.shade, g.region, r.fillnulls, r.relief, r.slope.aspect
192
194 Fortran version: Raghavan Srinivasan, Agricultural Engineering Depart‐
195 ment, Purdue University
196 Rewrite to C with enhancements: Roger S. Miller
197
199 Available at: r.fill.dir source code (history)
200
201 Accessed: Saturday Oct 28 18:17:32 2023
202
203 Main index | Raster index | Topics index | Keywords index | Graphical
204 index | Full index
205
206 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
207
208
209
210GRASS 8.3.1 r.fill.dir(1)