r.flow(1)	       Grass User's Manual		r.flow(1)



NNAAMMEE
       _r_._f_l_o_w  -  construction of slope curves (flowlines), flow-
       path lengths, and flowline densities (upslope areas)  from
       a raster digital elevation model(DEM)

       _(_G_R_A_S_S _R_a_s_t_e_r_/_V_e_c_t_o_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..ffllooww

       rr..ffllooww help

       rr..ffllooww  [[--uu33mmMMqqhh]]  eelleevviinn  =name [aassppiinn=name] [bbaarriinn=name]
       [sskkiipp=value]  [bboouunndd=value]  [ooffffsseett=value]   [fflloouutt=name]
       [llggoouutt=name] [ddssoouutt =name]

DDEESSCCRRIIPPTTIIOONN
       This  program generates flowlines using a combined raster-
       vector  approach  (see  Mitasova  and  Hofierka	1993  and
       Mitasova  et al. 1995)) from an input elevation raster map
       _e_l_e_v_i_n (integer or  floating  point),  and  optionally  an
       input  aspect  raster  map  _a_s_p_i_n  and/or an input barrier
       raster map _b_a_r_i_n. There are  three  possible  output  maps
       which can be produced in any combination simultaneously: a
       vector file _f_l_o_u_t of flowlines,	a  raster  map	_l_g_o_u_t  of
       flowpath  lengths, and a raster map _d_s_o_u_t of flowline den-
       sities (which are equal upslope contributed areas per unit
       width, when multiplied by resolution).

       Aspect used for input must follow the same rules as aspect
       computed  in  other  GRASS  programs  (see  s.surf.rst  or
       r.slope.aspect).

       Flowline output is given in a vector map _f_l_o_u_t, (flowlines
       generated downhill). The line segments of flowline vectors
       have endpoints on edges of a grid formed by drawing imagi-
       nary lines through the centers of the cells in the  eleva-
       tion  map. Flowlines are generated from each cell downhill
       by default; they can be generated uphill  using	the  flag
       _-_u. A flowline stops if its next segment would reverse the
       direction of flow (from up to down or vice-versa), cross a
       barrier,  or  arrive at a cell with undefined elevation or
       aspect. Another option, _s_k_i_p=val, indicates that only  the
       flowlines  from	every  val-th  cell are to be included in
       _f_l_o_u_t.  The default _s_k_i_p is max(1, /50, /50).  A high _s_k_i_p
       usually	speeds	up processing time and often improves the
       readability of a visualization of _f_l_o_u_t.

       Flowpath length output is given in a raster map _l_g_o_u_t. The
       value  in  each grid cell is the sum of the planar lengths
       of all segments of the flowline generated from that  cell.
       If  the	flag _-_3 is given, elevation is taken into account
       in calculating the length of each segment.

       Flowline density downhill or uphill output is given  in	a
       raster  map _d_s_o_u_t_. The value in each grid cell is the num-
       ber of flowlines which pass through that grid  cell,  that
       means  the  number  of flowlines from the entire map which
       have segment endpoints within that cell.



OOPPTTIIOONNSS
       The program will run non-interactively  if the user speci-
       fies  program  arguments  and flag settings on the command
       line using the following form:

       rr..ffllooww [[ --uu33mmMMqqhh ]] eelleevviinn = name [ aassppiinn = name ] [  bbaarriinn
       = name ] [ sskkiipp = val ] [ bboouunndd = val ] [ ooffffsseett = val ] [
       fflloouutt = name ] [ llggoouutt = name ] [ ddssoouutt = name ].

       Alternatively, the user can simply type rr..ffllooww on the com-
       mand  line  and	the program will ask for parameter values
       and flag settings interactively, using the standard  GRASS
       parser interface.



   FFllaaggss::
       --uu  Generate flowlines uphill (default generates flowlines
       downhill).

       --33 Compute  three-dimensional  lengths  (default  is  two-
       dimensional).

       --mm  Use less memory and compute aspect at each cell on the
       fly.  This option incurs a severe performance penalty.  If
       this  flag is given, the aspect input map (if any) will be
       ignored.

       --MM Use a fixed size memory and  utilize	page-swapping  to
       handle large input files. This option incurs a severe per-
       formance penalty but is the only way to	handle	arbitrar-
       ily-large  data	files. If this flag is given, the --mm flag
       will be ignored.

       --qq Quiet operation. Do not print diagnostic messages indi-
       cating progress.

       --hh Display reference information.



   PPaarraammeetteerrss::
       eelleevviinn=_n_a_m_e

	   Use	the  existing raster file name with elevations as
       input (required).

       aassppiinn=_n_a_m_e

	   Use the existing raster  file  name	with  aspects  as
       input.

       bbaarriinn=_n_a_m_e

	   Use the existing raster file name with non-zero values
       representing barriers as input.

       sskkiipp=_v_a_l

	   Set the number of cells between flowlines in the fflloouutt
       output map to val.

       bboouunndd=_v_a_l

	   Set the maximum number of segments of each flowline to
       val (default is the maximum possible).

       ooffffsseett=_v_a_l

	   Maximum magnitude of random grid point offset (default
       is 0).

       fflloouutt=_n_a_m_e

	   Output coordinates of flowlines to a vector file name.

       llggoouutt=_n_a_m_e

	   Output flowpath length values to a raster file name.

       ddssoouutt=_n_a_m_e

	   Output flowline density values to a raster file  name.



NNOOTTEESS
       For  best results, use input elevation maps with high pre-
       cision units (e.g., centimeters) so that flowlines do  not
       terminate  prematurely in flat areas.  To prevent the cre-
       ation of tiny flowline segments with imperceivable changes
       in  elevation,  an endpoint which would land very close to
       the center of a grid cell is quantized to the exact center
       of  that cell. The maximum distance between the intercepts
       along each axis of a single diagonal segment  and  another
       segment	of  1/2  degree  different  aspect is taken to be
       "very close" for that axis. Note that this  distance  (the
       so-called "quantization error") is about 1-2% of the reso-
       lution on maps with square cells.

       The values in length maps computed using the --uu flag  rep-
       resent  the  distances from each cell to an upland flat or
       singular point. Such distances are useful in water erosion
       modeling  for computation of the LS factor in the standard
       form of USLE. Uphill flowlines merge on	ridge  lines;  by
       redirecting the order of the flowline points in the output
       vector map, dispersed waterflow can be simulated. The den-
       sity map can be used for the extraction of ridge lines.

       Computing the flowlines downhill simulates the actual flow
       (also known as the raindrop method). These flowlines  tend
       to  merge in valleys; they can be used for localization of
       areas with waterflow accumulation and for  the  extraction
       of  channels. The downslope flowline density multiplied by
       the resolution can be used as an approximation of the ups-
       lope  contributing  area per unit contour width. This area
       is a measure of potential water flux for the steady  state
       conditions  and	can be used in the modeling of water ero-
       sion for the computation of the unit stream power based LS
       factor or sediment transport capacity.

       The  program  has  been	designed  for modeling erosion on
       hillslopes and has rather  strict  conditions  for  ending
       flowlines.  It  is  therefore  not  very  suitable for the
       extraction of stream networks or delineation of watersheds
       unless a DEM without pits or flat areas is available.

	To label the vector flowlines automatically, the user can
       use v.llabel.

AAllggoorriitthhmm bbaacckkggrroouunndd
       1. Construction of flow-lines (slope-lines):  r.flow  uses
       an  original  vector-grid algorithm which uses an infinite
       number of directions  between  0.0000...  and  360.0000...
       and traces the flow as a line (vector) in the direction of
       gradient (rather than from cell to cell in one  of  the	8
       directions = D-infinity algorithm). They are traced in any
       direction using aspect (so there is  no	limitation  to	8
       directions here). The D8 algorithm produces zig-zag lines.
       The value in the outlet is very similar	for  both  r.flow
       and  r.flowmd  algorithms  (because  it is essentially the
       watershed area), however the spatial distribution of flow,
       especially on hillslopes is quite different. It is still a
       1D flow routing so the dispersal flow  is  not  accurately
       described, but still better than D8.

       2. Computation of contributing areas: r.flow uses a single
       flow algorithm, i.e. all flow is transported to	a  single
       cell downslope.

FFUURRTTHHEERR NNOOTTEESS
       Differences between _r_._f_l_o_w and _r_._f_l_o_w_m_d



	       r.flow  has  an option to compute slope and aspect
	      internally thus making the program capable to  pro-
	      cess  much  larger  data sets than r.flowmd. It has
	      also 2 additional options  for  handling	of  large
	      data  sets but it is not known that they work prop-
	      erly.

	       the programs handle the	special  cases	when  the
	      flowline passes exactly (or very close) through the
	      grid vertices differently.

	       r.flowmd has the simplified multiple flow addition
	      so the results are smoother.

       In  conclusion,	_r_._f_l_o_w_m_d  produces  nicer  results but is
       slower and it does not  support	as  large  data  sets  as
       _r_._f_l_o_w.

DDIIAAGGNNOOSSTTIICCSS
       ERROR: GISRC - variable not set

       The program was run outside of GRASS.

       Usage:	 r.flow    [-u3mMqh]   elevin=name   [aspin=name]
       [barin=name]  [skip=value]  [bound=value]   [offset=value]
       [flout=name] [lgout=name] [dsout=name]

       Invalid options were specified on the command line.

       ERROR: r.flow: error getting current region

       ERROR: r.flow: unable to reset current region

       ERROR: r.flow: cannot open vector file

       "ERROR: r.flow: cell file " filename " not found"

       "ERROR: r.flow: cannot get header for " filename

       "ERROR: r.flow: unable to create raster map " filename

       Self-explanatory or beyond explanation.

       "ERROR:	r.flow:  " input " file's resolution differs from
       current" region resolution

       The resolutions of all input files and the current  region
       must match.

       "ERROR: r.flow: resolution too unbalanced (" val " x " val
       ")" The difference in length between the  two  axes  of	a
       grid  cell  is  so great that quantization error is larger
       than one of the	dimensions.  Resample  the  map  and  try
       again.

SSEEEE AALLSSOO
       r.flowmd,   r.basins.fill,  r.drain,  r.water.outlet.html,
       r.watershed v.llabel

AAUUTTHHOORRSS
       _O_r_i_g_i_n_a_l _v_e_r_s_i_o_n _o_f _p_r_o_g_r_a_m_:

       Maros Zlocha and Jaroslav Hofierka,  Comenius  University,
       Bratislava, Slovakia,

       _T_h_e _c_u_r_r_e_n_t _v_e_r_s_i_o_n _o_f _t_h_e _p_r_o_g_r_a_m _(_a_d_a_p_t_e_d _f_o_r _G_R_A_S_S_5_._0_):

       Joshua Caplan, Mark Ruesink, Helena  Mitasova,  University
       of  Illinois  at  Urbana-Champaign  with  support from USA
       CERL.

       GMSL/University of Illinois at Urbana-Champaign



RREEFFEERREENNCCEESS
       Mitasova, H., L. Mitas, 1993, Interpolation by regularized
       spline with tension : I. Theory and implementation. Mathe-
       matical Geology 25, p. 641-655.	(online)

       Mitasova and Hofierka 1993 : Interpolation by  Regularized
       Spline  with  Tension: II. Application to Terrain Modeling
       and  Surface  Geometry  Analysis.   Mathematical   Geology
       25(6), 657-669. (online)

       Mitasova,  H., Mitas, L., Brown, W.M., Gerdes, D.P., Kosi-
       novsky, I., Baker, T., 1995: Modeling spatially and tempo-
       rally  distributed  phenomena:  New  methods and tools for
       GRASS GIS. International Journal of Geographical  Informa-
       tion Systems 9(4), 433-446.

       Mitasova,  H., J. Hofierka, M. Zlocha, L.R. Iverson, 1996,
       Modeling topographic potential for erosion and  deposition
       using  GIS.  Int. Journal of Geographical Information Sci-
       ence, 10(5), 629-641. (reply to a comment  to  this  paper
       appears	in  1997 in Int. Journal of Geographical Informa-
       tion Science, Vol. 11, No. 6)

       Mitasova, H.(1993): Surfaces and modeling.  Grassclippings
       (winter and spring) p.18-19.

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_3_/_0_1 _0_0_:_0_8_:_3_1 _$



GRASS 5.0						r.flow(1)
