1r.stream.extract(1)           Grass User's Manual          r.stream.extract(1)
2
3
4

NAME

6       r.stream.extract  - Performs stream network extraction.
7

KEYWORDS

9       raster, hydrology, stream network
10

SYNOPSIS

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=integer]      [stream_raster=name]
17       [stream_vector=name]     [direction=name]     [--overwrite]    [--help]
18       [--verbose]  [--quiet]  [--ui]
19
20   Flags:
21       --overwrite
22           Allow output files to overwrite existing files
23
24       --help
25           Print usage summary
26
27       --verbose
28           Verbose module output
29
30       --quiet
31           Quiet module output
32
33       --ui
34           Force launching GUI dialog
35
36   Parameters:
37       elevation=name [required]
38           Name of input elevation raster map
39
40       accumulation=name
41           Name of input accumulation raster map
42           Stream  extraction will use provided accumulation instead of calcu‐
43           lating it anew
44
45       depression=name
46           Name of input raster map with real depressions
47           Streams will not be routed out of real depressions
48
49       threshold=float [required]
50           Minimum flow accumulation for streams
51           Must be > 0
52
53       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
58       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
64       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
69       memory=integer
70           Maximum memory to be used (in MB)
71           Cache size for raster rows
72           Default: 300
73
74       stream_raster=name
75           Name for output raster map with unique stream ids
76
77       stream_vector=name
78           Name for output vector map with unique stream ids
79
80       direction=name
81           Name for output raster map with flow direction
82

DESCRIPTION

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

NOTES

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
93       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
102       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
118       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
123       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
127       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
133   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
143       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
157       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
162   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
171       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
175       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
182   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
190   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
197       Output stream_raster raster map stores extracted streams.  Cell  values
198       encode a unique ID for each stream segment.
199
200       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

EXAMPLE

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
237       Weight map (spatial subset with lake in the southern half)
238
239       Original  flow accumulation map (spatial subset with lake in the south‐
240       ern half)
241
242       Weighed flow accumulation map (spatial subset with lake in the southern
243       half)
244
245       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
259       Now display both stream maps and decide which one is more realistic.
260
261       Extracted streams from original flow accumulation map
262
263       Extracted streams from weighed flow accumulation map
264

REFERENCES

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
273           ·   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
278           ·   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

SEE ALSO

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
288       See also r.streams.*  modules wiki page.
289

AUTHOR

291       Markus Metz
292

SOURCE CODE

294       Available at: r.stream.extract source code (history)
295
296       Main  index  | Raster index | Topics index | Keywords index | Graphical
297       index | Full index
298
299       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
300
301
302
303GRASS 7.8.2                                                r.stream.extract(1)
Impressum