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.

	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.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_2_/_0_5 _1_2_:_4_6_:_0_3 _$



GRASS 5.0							     r.flow(1)
