## NAME

r.drain - Traces a flow through an elevation model on a raster map layer.
(GRASS Raster Program)

## SYNOPSIS

r.drain
r.drain help
r.drain [-c] [-a] [-n] input=name output=name [coordinate=x,y[,x,y,...]]

## DESCRIPTION

r.drain traces a flow through a least-cost path in an elevation model. The elevation surface (a raster map layer input) might be the 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 model. 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 withe the same cell type than the input map (integer, float or double). The -c and -a flags are mutually incompatible. If both are specified, the -a flag will superceed the -c flag, and a warning message will be issued. With the -n (number) flag, the cells are numbered from the starting point to the final point.

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

The program will be run non-interactively, if the user specifies the names of raster map layers and any desired options on the command line, using the form

  r.drain [-c] [-a] [-n] input=name output=name [coordinate=x,y[,x,y,...]]

where the input name is the name of a raster map layer to be used in calculating drainage, the output name is the name of the raster map layer to contain output, and each x,y coordinate pair is the geographic location of a point from which drainage is to be calculated.

Alternately, the user can simply type r.drain on the command line, without program arguments. In this case, the user will be prompted for needed parameter values using the standard GRASS parser interface.

## OPTIONS

Program parameters are as follows.

### Flags:

-c
  Input map cells values are copied verbatim along the least cost path.
-a
  Accumulated input map cells values along the least cost path are written on output.
-n
  Count cell numbers along the path

### Parameters:

input=name
  Name of raster map layer containing cell cost information.
output=name
  Name of raster map layer to contain program output.
coordinate=x,y[,x,y,...]
  Each x,y pair is the easting and northing (respectively) of a starting point from which a least-cost corridor will be developed. As many points as desired can be input. (But, see BUGS below.)

## 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. 28. 44.   .   .   .
    . . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 59.   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 69.   .   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 17. 15. 15. 15. 10. 8 . 8 .    .   .   .   .   .   . 77.   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 24. 16. 8 . 7 . 8 . 0 .12 .    .   .   .   .   .   . 77.   .
    . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
    . 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.

Sometimes, when using an integer cell map and the differences among 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 input cost surface map to r.cost by the value of the map resolution, before running r.cost. This can be done using r.mapcalc or other programs. The map resolution can be found using g.region.

## SEE ALSO

g.region
r.cost
r.mapcalc
parser

## AUTHOR

Completely rewritten by Roger S. Miller

Last changed: $Date: 2002/03/01 00:08:31 $