## NAME

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

## KEYWORDS

raster

## SYNOPSIS

r.drain
r.drain help
r.drain [-can] input=name output=name [coordinate=x,y[,x,y,...]] [vector_points=name[,name,...]] [--overwrite]

### Flags:

-c
  Copy input cell values on output
-a
  Accumulate input values along the path
-n
  Count cell numbers along the path
--overwrite
  Force overwrite of output files

### Parameters:

input=name
  Name of existing raster map containing elevation surface
output=name
  Output drain raster map
coordinate=x,y[,x,y,...]
  The E and N coordinates of starting point(s)
vector_points=name[,name,...]
  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 low spot (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 cells values are copied verbatim along the path. With the -a (accumulate) flag, the accumulated cells value from the starting point up to the current cell is written on output. With the -c and 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 from the starting point to the final point. The -c, -a, and -n flags are mutually incompatible.

The path is calculated by choosing the stepper "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.

## EXAMPLES

Consider the following example:

    Input:                          Output:
      ELEVATION SURFACE               LEAST COST PATH
    . . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 20| 19| 17. 16. 17. 16. 16.    .   . 1 . 1 . 1 .   .   .   .
    . . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 1 .   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 1 .   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 17. 15. 15. 15. 10. 8 . 8 .    .   .   .   .   .   . 1 .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 24. 16. 8 . 7 . 8 . 0 .12 .    .   .   .   .   .   . 1 .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 17. 9 . 8 . 7 . 8 . 6 .12 .    .   .   .   .   .   .   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .

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
    . . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 20| 19| 17. 16. 17. 16. 16.    .   . 19. 17. 16.   .   .   .
    . . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 15.   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 10.   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 17. 15. 15. 15. 10. 8 . 8 .    .   .   .   .   .   . 8 .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 24. 16. 8 . 7 . 8 . 0 .12 .    .   .   .   .   .   . 0 .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 17. 9 . 8 . 7 . 8 . 6 .12 .    .   .   .   .   .   .   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .

    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
    . . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 20| 19| 17. 16. 17. 16. 16.    .   . 19. 36. 52.   .   .   .
    . . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 67.   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 77.   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 17. 15. 15. 15. 10. 8 . 8 .    .   .   .   .   .   . 85.   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 24. 16. 8 . 7 . 8 . 0 .12 .    .   .   .   .   .   . 85.   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 17. 9 . 8 . 7 . 8 . 6 .12 .    .   .   .   .   .   .   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .

With the -n (number) flag, you get the following result:

    Input:                          Output:
      ELEVATION SURFACE               LEAST COST PATH
    . . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 20| 19| 17. 16. 17. 16. 16.    .   . 1 . 2 . 3 .   .   .   .
    . . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 4 .   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 5 .   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 17. 15. 15. 15. 10. 8 . 8 .    .   .   .   .   .   . 6 .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 24. 16. 8 . 7 . 8 . 0 .12 .    .   .   .   .   .   . 7 .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 17. 9 . 8 . 7 . 8 . 6 .12 .    .   .   .   .   .   .   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .

## BUGS

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 present. Thr r.fill.dir and r.basins.fill modules can be used to fill in subbasins prior to processing with r.drain.

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 (t.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.

## SEE ALSO

g.region, r.cost, r.fill.dir, r.basins.fill, r.mapcalc, r.walk

## 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: 2006/04/19 05:51:17 $

Main index - raster index - Full index