Ubuntu Manpage: r.drain - Traces a flow through an elevation model on a raster map.

NAME

       r.drain  - Traces a flow through an elevation model on a raster map.

KEYWORDS

       raster, hydrology

SYNOPSIS

       r.drain
       r.drain help
       r.drain     [-cand]     input=name     [indir=string]     output=name     [voutput=string]
       [coordinate=x,y[,x,y,...]]   [vector_points=name[,name,...]]   [--overwrite]   [--verbose]
       [--quiet]

   Flags:
       -c
           Copy input cell values on output

       -a
           Accumulate input values along the path

       -n
           Count cell numbers along the path

       -d
           The  input  surface  is  a  cost surface (if checked, a direction surface must also be
           specified

       --overwrite
           Allow output files to overwrite existing files

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       input=name
           Name of elevation raster map

       indir=string
           Name of movement direction map associated with the cost surface

       output=name
           Name for output raster map

       voutput=string
           Output drain vector map (recommended for cost surface made using knight's move)

       coordinate=x,y[,x,y,...]
           Map coordinates of starting point(s) (E,N)

       vector_points=name[,name,...]
           Name of vector map(s) containing starting point(s)

DESCRIPTION

r.drain traces a flow through a least-cost path in an elevation model. The input elevation
surface (a raster map layer) might be a cumulative cost map generated by the r.cost
program. The output result (also a raster map layer) will show one or more least-cost
paths between each user-provided location(s) and the minima (low category values) in the
input map. By default, the output will be an integer CELL map with 1 along the least cost
path, and null cells elsewhere.

With the -c (copy) flag, the input map cell values are copied verbatim along the path.
With the -a (accumulate) flag, the accumulated cell value from the starting point up to
the current cell is written on output. With either the -c or the -a flags, the output map
is created with the same cell type as the input map (integer, float or double). With the
-n (number) flag, the cells are numbered consecutively from the starting point to the
final point. The -c, -a, and -n flags are mutually incompatible.

The path is calculated by choosing the steeper "slope" between adjacent cells. The slope
calculation accurately acounts for the variable scale in lat-lon projections.

The coordinate parameter consists of map E and N grid coordinates of a starting point.
Each x,y pair is the easting and northing (respectively) of a starting point from which a
least-cost corridor will be developed. The vector_points parameter can take multiple
vector maps containing additional starting points. Up to 1024 starting points can be
input from a combination of the coordinate and vector_points parameters.

NOTES

       r.drain  currently  finds  only  the  lowest  point (the cell having the smallest category
       value) in the input file that can be reached through directly adjacent cells that are less
       than or equal in value to the cell reached immediately prior to it; therefore, it will not
       necessarily reach the lowest point in the input file. It currently finds pits in the data,
       rather  than  the  lowest  point in the entire input map. The r.fill.dir, r.terraflow, and
       r.basins.fill modules can be used to fill in subbasins prior to processing with r.drain.

       r.drain will not give sane results at the region  boundary.  On  outer  rows  and  columns
       bordering the edge of the region, the flow direction is always directly out of the map. In
       this case, the user could try adjusting the region extents slightly with g.region to allow
       additional outlet paths for r.drain.

EXAMPLES

       Consider the following example:
       Input:                          Output:
         ELEVATION SURFACE               LEAST COST PATH

       The  user-provided starting location in the above example is the boxed 19 in the left-hand
       map. The path in the output shows the least-cost corridor for moving from the starting box
       to  the  lowest  (smallest) possible point. This is the path a raindrop would take in this
       landscape.

       With the -c (copy) flag, you get the following result:
       Input:                          Output:
         ELEVATION SURFACE               LEAST COST PATH
       Note that the last 0 will not be put in the null values map.

       With the -a (accumulate) flag, you get the following result:
       Input:                          Output:
         ELEVATION SURFACE               LEAST COST PATH

       With the -n (number) flag, you get the following result:
       Input:                          Output:
         ELEVATION SURFACE               LEAST COST PATH

BUGS

       Sometimes, when  the  differences  among  integer  cell  category  values  in  the  r.cost
       cumulative cost surface output are small, this cumulative cost output cannot accurately be
       used as input to  r.drain  (r.drain  will  output  bad  results).   This  problem  can  be
       circumvented by making the differences between cell category values in the cumulative cost
       output bigger. It is recommended that if the output from r.cost is to be used as input  to
       r.drain,  the  user  multiply  the r.cost input cost surface map by the value of the map's
       cell resolution, before running  r.cost.  This  can  be  done  using  r.mapcalc.  The  map
       resolution  can  be  found using g.region.  This problem doesn't arise with floating point
       maps.

AUTHOR

       Completely rewritten by Roger S. Miller, 2001

       July 2004 at WebValley 2004, error checking and vector  points  added  by  Matteo  Franchi
       (Liceo Leonardo Da Vinci, Trento) and Roberto Flor (ITC-irst, Trento, Italy)

       Last changed: $Date: 2012-12-27 08:11:57 -0800 (Thu, 27 Dec 2012) $

       Full index

       © 2003-2013 GRASS Development Team