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



NNAAMMEE
       _r_._f_l_o_w  -  construction	of slope curves (flowlines), flowpath 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 densities (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 imaginary lines through the centers
       of the cells in the elevation 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  number  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  specifies  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 command line  and
       the  program  will  ask for parameter values and flag settings interac-
       tively, 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 performance penalty but is the
       only way to handle arbitrarily-large data files. If this flag is given,
       the --mm flag will be ignored.

       --qq  Quiet  operation.  Do  not  print  diagnostic  messages  indicating
       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  precision  units
       (e.g.,  centimeters)  so that flowlines do not terminate prematurely in
       flat areas.  To prevent the creation 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  differ-
       ent  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 res-
       olution on maps with square cells.

       The values in length maps computed using the --uu flag represent the dis-
       tances from each cell to an upland flat or singular  point.  Such  dis-
       tances  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 density  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	multi-
       plied  by the resolution can be used as an approximation of the upslope
       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 erosion 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
       (r.fill.dir can be used to fill pits).

	To  label  the vector flowlines automatically, the user can use v.lla-
       bel.

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  (vec-
       tor) 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 algo-
       rithm, 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 process 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 properly.

	       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 dif-
       ference 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.fill.dir,   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.	Mathematical  Geology  25,  p.
       641-655.  (online)

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

       Mitasova,  H.,  Mitas,  L.,  Brown, W.M., Gerdes, D.P., Kosinovsky, I.,
       Baker, T., 1995: Modeling spatially and temporally distributed  phenom-
       ena: New methods and tools for GRASS GIS. International Journal of Geo-
       graphical Information 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. Jour-
       nal of Geographical Information Science, 10(5), 629-641.  (reply  to  a
       comment	to  this paper appears in 1997 in Int. Journal of Geographical
       Information 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_3_/_0_7_/_0_4 _0_8_:_3_5_:_3_4 _$



GRASS 5.0							     r.flow(1)
