1r.stream.extract(1) GRASS GIS User's Manual r.stream.extract(1)
2
6 r.stream.extract - Performs stream network extraction.
7
9 raster, hydrology, stream network
10
12 r.stream.extract
13 r.stream.extract --help
14 r.stream.extract elevation=name [accumulation=name] [depres‐
15 sion=name] threshold=float [d8cut=float] [mexp=float]
16 [stream_length=integer] [memory=memory in MB] [stream_raster=name]
17 [stream_vector=name] [direction=name] [--overwrite] [--help]
18 [--verbose] [--quiet] [--ui]
19 Flags:
21 --overwrite
22 Allow output files to overwrite existing files
23 --help
25 Print usage summary
26 --verbose
28 Verbose module output
29 --quiet
31 Quiet module output
32 --ui
34 Force launching GUI dialog
35 Parameters:
37 elevation=name [required]
38 Name of input elevation raster map
39 accumulation=name
41 Name of input accumulation raster map
42 Stream extraction will use provided accumulation instead of calcu‐
43 lating it anew
44 depression=name
46 Name of input raster map with real depressions
47 Streams will not be routed out of real depressions
48 threshold=float [required]
50 Minimum flow accumulation for streams
51 Must be > 0
52 d8cut=float
54 Use SFD above this threshold
55 If accumulation is larger than d8cut, SFD is used instead of MFD.
56 Applies only if no accumulation map is given.
57 mexp=float
59 Montgomery exponent for slope, disabled with 0
60 Montgomery: accumulation is multiplied with pow(slope,mexp) and
61 then compared with threshold
62 Default: 0
63 stream_length=integer
65 Delete stream segments shorter than stream_length cells
66 Applies only to first-order stream segments (springs/stream heads)
67 Default: 0
68 memory=memory in MB
70 Maximum memory to be used (in MB)
71 Cache size for raster rows
72 Default: 300
73 stream_raster=name
75 Name for output raster map with unique stream ids
76 stream_vector=name
78 Name for output vector map with unique stream ids
79 direction=name
81 Name for output raster map with flow direction
82
84 r.stream.extract extracts streams in both raster and vector format from
85 a required input elevation map and optional input accumulation map.
86
88 NULL (nodata) cells in the input elevation map are ignored, zero and
89 negative values are valid elevation data. Gaps in the elevation map
90 that are located within the area of interest must be filled beforehand,
91 e.g. with r.fillnulls, to avoid distortions.
92 All non-NULL and non-zero cells of depression map will be regarded as
94 real depressions. Streams will not be routed out of depressions. If an
95 area is marked as depression but the elevation model has no depression
96 at this location, streams will not stop there. If a flow accumulation
97 map and a map with real depressions are provided, the flow accumulation
98 map must match the depression map such that flow is not distributed out
99 of the indicated depressions. It is recommended to use internally com‐
100 puted flow accumulation if a depression map is provided.
101 Option threshold defines the minimum (optionally modified) flow accumu‐
103 lation value that will initiate a new stream. If Montgomery’s method
104 for channel initiation is used, the cell value of the accumulation
105 input map is multiplied by (tan(local slope))mexp and then compared to
106 threshold. If mexp is given than the method of Montgomery and
107 Foufoula-Georgiou (1993) to initiate a stream with this value. The cell
108 value of the accumulation input map is multiplied by (tan(local
109 slope))mexp and then compared to threshold. If threshold is reached or
110 exceeded, a new stream is initiated. The default value 0 disables Mont‐
111 gomery. Montgomery and Foufoula-Georgiou (1993) generally recommend to
112 use 2.0 as exponent. mexp values closer to 0 will produce streams more
113 similar to streams extracted with Montgomery disabled. Larger mexp
114 values decrease the number of streams in flat areas and increase the
115 number of streams in steep areas. If weight is given, the weight is
116 applied first.
117 Option d8cut defines minimum amount of overland flow (accumulation)
119 when SFD (D8) will be used instead of MFD (FD8) to calculate flow accu‐
120 mulation. Only applies if no accumulation map is provided. Setting to 0
121 disables MFD completely.
122 Option stream_length defines minimum stream length in number of cells
124 for first-order (head/spring) stream segments. All first-order stream
125 segments shorter than stream_length will be deleted.
126 Output direction raster map contains flow direction for all non-NULL
128 cells in input elevation. Flow direction is of D8 type with a range of
129 1 to 8. Multiplying values with 45 gives degrees CCW from East. Flow
130 direction was adjusted during thinning, taking shortcuts and skipping
131 cells that were eliminated by the thinning procedure.
132 Stream extraction
134 If no accumulation input map is provided, flow accumulation is deter‐
135 mined with a hydrological analysis similar to r.watershed. The algo‐
136 rithm is MFD (FD8) after Holmgren 1994, as for r.watershed. The thresh‐
137 old option determines the number of streams and detail of stream net‐
138 works. Whenever flow accumulation reaches threshold, a new stream is
139 started and traced downstream to its outlet point. As for r.watershed,
140 flow accumulation is calculated as the number of cells draining through
141 a cell.
142 If accumulation is given than the accumulation values of the provided
144 accumulation map are used and not calculated from the input elevation
145 map. In this case the elevation map must be exactly the same map used
146 to calculate accumulation. If accumulation was calculated with r.ter‐
147 raflow, the filled elevation output of r.terraflow must be used. Fur‐
148 ther on, the current region should be aligned to the accumulation map.
149 Flow direction is first calculated from elevation and then adjusted to
150 accumulation. It is not necessary to provide accumulation as the number
151 of cells, it can also be the optionally adjusted or weighed total con‐
152 tributing area in square meters or any other unit. When an original
153 flow accumulation map is adjusted or weighed, the adjustment or weigh‐
154 ing should not convert valid accumulation values to NULL (nodata) val‐
155 ues.
156 In case of getting the error message ERROR: Accumulation raster map is
158 NULL but elevation map is not NULL the computational region must be
159 carefully adjusted to exclude NULL pixels in the accumulation raster
160 map prior to stream extraction.
161 Weighed flow accumulation
163 Flow accumulation can be calculated first, e.g. with r.watershed, and
164 then modified before using it as input for r.stream.extract. In its
165 general form, a weighed accumulation map is generated by first creating
166 a weighing map and then multiplying the accumulation map with the
167 weighing map using r.mapcalc. It is highly recommended to evaluate the
168 weighed flow accumulation map first, before using it as input for
169 r.stream.extract.
170 This allows e.g. to decrease the number of streams in dry areas and
172 increase the number of streams in wet areas by setting weight to
173 smaller than 1 in dry areas and larger than 1 in wet areas.
174 Another possibility is to restrict channel initiation to valleys deter‐
176 mined from terrain morphology. Valleys can be determined with
177 r.param.scale method=crosc (cross-sectional or tangential curvature).
178 Curvature values < 0 indicate concave features, i.e. valleys. The size
179 of the processing window determines whether narrow or broad valleys
180 will be identified (See example below).
181 Defining a region of interest
183 The stream extraction procedure can be restricted to a certain region
184 of interest, e.g. a subbasin, by setting the computational region with
185 g.region and/or creating a MASK. Such region of interest should be a
186 complete catchment area, complete in the sense that the complete area
187 upstream of an outlet point is included and buffered with at least one
188 cell.
189 Stream output
191 The output raster and vector contains stream segments with unique IDs.
192 Note that these IDs are different from the IDs assigned by r.watershed.
193 The vector output also contains points at the location of the start of
194 a stream segment, at confluences and at stream network outlet loca‐
195 tions.
196 Output stream_raster raster map stores extracted streams. Cell values
198 encode a unique ID for each stream segment.
199 Output stream_vector vector map stores extracted stream segments and
201 points. Points are written at the start location of each stream segment
202 and at the outlet of a stream network. In layer 1, categories are
203 unique IDs, identical to the cell value of the raster output. The
204 attribute table for layer 1 holds information about the type of stream
205 segment: start segment, or intermediate segment with tributaries, and
206 about the stream network this stream or node belongs to. Columns are
207 cat int,stream_type varchar(),type_code int,network int. The network
208 attribute is the network ID of the stream/node. The encoding for
209 type_code is 0 = start, 1 = intermediate. In layer 2, categories are
210 identical to type_code in layer 1 with additional category 2 = outlet
211 for outlet points. Points with category 1 = intermediate in layer 2 are
212 at the location of confluences.
213
215 This example is based on the elevation map "elev_ned_30m" in the North
216 Carolina sample dataset and uses valleys determined with r.param.scale
217 to weigh an accumulation map produced with r.watershed.
218 # set region
219 g.region -p raster=elev_ned_30m@PERMANENT
220 # calculate flow accumulation
221 r.watershed ele=elev_ned_30m@PERMANENT acc=elev_ned_30m.acc
222 # curvature to get narrow valleys
223 r.param.scale input=elev_ned_30m@PERMANENT output=tangential_curv_5 size=5 method=crosc
224 # curvature to get a bit broader valleys
225 r.param.scale input=elev_ned_30m@PERMANENT output=tangential_curv_7 size=7 method=crosc
226 # curvature to get broad valleys
227 r.param.scale input=elev_ned_30m@PERMANENT output=tangential_curv_11 size=11 method=crosc
228 # create weight map
229 r.mapcalc "weight = if(tangential_curv_5 < 0, -100 * tangential_curv_5, \
230 if(tangential_curv_7 < 0, -100 * tangential_curv_7, \
231 if(tangential_curv_11 < 0, -100 * tangential_curv_11, 0.000001)))"
232 # weigh accumulation map
233 r.mapcalc expr="elev_ned_30m.acc.weighed = elev_ned_30m.acc * weight"
234 # copy color table from original accumulation map
235 r.colors map=elev_ned_30m.acc.weighed raster=elev_ned_30m.acc
236 Weight map (spatial subset with lake in the southern half)
238 Original flow accumulation map (spatial subset with lake in the south‐
240 ern half)
241 Weighed flow accumulation map (spatial subset with lake in the southern
243 half)
244 Display both the original and the weighed accumulation map. Compare
246 them and proceed if the weighed accumulation map makes sense.
247 # extract streams using the original accumulation map
248 r.stream.extract elevation=elev_ned_30m@PERMANENT \
249 accumulation=elev_ned_30m.acc \
250 threshold=1000 \
251 stream_rast=elev_ned_30m.streams.noweight
252 # extract streams from weighed map
253 # note that the weighed map is a bit smaller than the original map
254 r.stream.extract elevation=elev_ned_30m@PERMANENT \
255 accumulation=elev_ned_30m.acc.weighed \
256 threshold=1000 \
257 stream_rast=elev_ned_30m.streams
258 Now display both stream maps and decide which one is more realistic.
260 Extracted streams from original flow accumulation map
262 Extracted streams from weighed flow accumulation map
264
266 · Ehlschlaeger, C. (1989). Using the AT Search Algorithm to
267 Develop Hydrologic Models from Digital Elevation Data, Proceed‐
268 ings of International Geographic Information Systems (IGIS)
269 Symposium ’89, pp 275-281 (Baltimore, MD, 18-19 March 1989).
270 URL: http://fac‐
271 ulty.wiu.edu/CR-Ehlschlaeger2/older/IGIS/paper.html
272 · Holmgren, P. (1994). Multiple flow direction algorithms for
274 runoff modelling in grid based elevation models: An empirical
275 evaluation. Hydrological Processes Vol 8(4), pp 327-334. DOI:
276 10.1002/hyp.3360080405
277 · Montgomery, D.R., Foufoula-Georgiou, E. (1993). Channel network
279 source representation using digital elevation models. Water
280 Resources Research Vol 29(12), pp 3925-3934.
281
283 r.mapcalc, r.param.scale, r.stream.channel (Addon), r.stream.distance
284 (Addon), r.stream.order (Addon), r.stream.segment (Addon),
285 r.stream.slope (Addon), r.stream.snap (Addon), r.stream.stats (Addon),
286 r.terraflow, r.thin, r.to.vect, r.watershed
287 See also r.streams.* modules wiki page.
289
291 Markus Metz
292
294 Available at: r.stream.extract source code (history)
295 Main index | Raster index | Topics index | Keywords index | Graphical
297 index | Full index
298 © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
300GRASS 7.8.5 r.stream.extract(1)