Skip to content

r.walk

Creates a raster map showing the anisotropic cumulative cost of moving between different geographic locations on an input raster map whose cell category values represent cost.

r.walk [-knrib] elevation=name friction=name output=name [solver=name] [nearest=name] [outdir=name] [start_points=name] [stop_points=name] [start_raster=name] [start_coordinates=east,north [,east,north,...]] [stop_coordinates=east,north [,east,north,...]] [max_cost=value] [null_cost=value] [memory=memory in MB] [walk_coeff=a,b,c,d] [lambda=float] [slope_factor=float] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.walk elevation=name friction=name output=name

grass.script.run_command("r.walk", elevation, friction, output, solver=None, nearest=None, outdir=None, start_points=None, stop_points=None, start_raster=None, start_coordinates=None, stop_coordinates=None, max_cost=0, null_cost=None, memory=300, walk_coeff="0.72,6.0,1.9998,-1.9998", lambda=1.0, slope_factor=-0.2125, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.walk", elevation="name", friction="name", output="name")

Parameters

elevation=name [required]
    Name of input elevation raster map
friction=name [required]
    Name of input raster map containing friction costs
output=name [required]
    Name for output raster map to contain walking costs
solver=name
    Name of input raster map solving equal costs
    Helper variable to pick a direction if two directions have equal cumulative costs (smaller is better)
nearest=name
    Name for output raster map with nearest start point
outdir=name
    Name for output raster map to contain movement directions
start_points=name
    Name of starting vector points map
    Or data source for direct OGR access
stop_points=name
    Name of stopping vector points map
    Or data source for direct OGR access
start_raster=name
    Name of starting raster points map
start_coordinates=east,north [,east,north,...]
    Coordinates of starting point(s) (E,N)
stop_coordinates=east,north [,east,north,...]
    Coordinates of stopping point(s) (E,N)
max_cost=value
    Maximum cumulative cost
    Default: 0
null_cost=value
    Cost assigned to null cells. By default, null cells are excluded
memory=memory in MB
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Default: 300
walk_coeff=a,b,c,d
    Coefficients for walking energy formula parameters a,b,c,d
    Default: 0.72,6.0,1.9998,-1.9998
lambda=float
    Lambda coefficients for combining walking energy and friction cost
    Default: 1.0
slope_factor=float
    Slope factor determines travel energy cost per height step
    Default: -0.2125
-k
    Use the 'Knight's move'; slower, but more accurate
-n
    Keep null values in output raster map
-r
    Start with values in raster map
-i
    Print info about disk space and memory requirements and exit
-b
    Create bitmask encoded directions
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

elevation : str, required
    Name of input elevation raster map
    Used as: input, raster, name
friction : str, required
    Name of input raster map containing friction costs
    Used as: input, raster, name
output : str, required
    Name for output raster map to contain walking costs
    Used as: output, raster, name
solver : str, optional
    Name of input raster map solving equal costs
    Helper variable to pick a direction if two directions have equal cumulative costs (smaller is better)
    Used as: input, raster, name
nearest : str, optional
    Name for output raster map with nearest start point
    Used as: output, raster, name
outdir : str, optional
    Name for output raster map to contain movement directions
    Used as: output, raster, name
start_points : str, optional
    Name of starting vector points map
    Or data source for direct OGR access
    Used as: input, vector, name
stop_points : str, optional
    Name of stopping vector points map
    Or data source for direct OGR access
    Used as: input, vector, name
start_raster : str, optional
    Name of starting raster points map
    Used as: input, raster, name
start_coordinates : list[tuple[float, float]] | tuple[float, float] | list[float] | str, optional
    Coordinates of starting point(s) (E,N)
    Used as: input, coords, east,north
stop_coordinates : list[tuple[float, float]] | tuple[float, float] | list[float] | str, optional
    Coordinates of stopping point(s) (E,N)
    Used as: input, coords, east,north
max_cost : int, optional
    Maximum cumulative cost
    Used as: value
    Default: 0
null_cost : float, optional
    Cost assigned to null cells. By default, null cells are excluded
    Used as: value
memory : int, optional
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Used as: memory in MB
    Default: 300
walk_coeff : tuple[str, str, str, str] | list[str] | str, optional
    Coefficients for walking energy formula parameters a,b,c,d
    Used as: a,b,c,d
    Default: 0.72,6.0,1.9998,-1.9998
lambda : float, optional
    Lambda coefficients for combining walking energy and friction cost
    Default: 1.0
slope_factor : float, optional
    Slope factor determines travel energy cost per height step
    Default: -0.2125
flags : str, optional
    Allowed values: k, n, r, i, b
    k
        Use the 'Knight's move'; slower, but more accurate
    n
        Keep null values in output raster map
    r
        Start with values in raster map
    i
        Print info about disk space and memory requirements and exit
    b
        Create bitmask encoded directions
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

r.walk computes anisotropic cumulative cost of moving between different geographic locations on an input elevation raster map whose cell category values represent elevation combined with an input raster map layer whose cell values represent friction cost.

r.walk outputs 1) a raster map showing the lowest cumulative cost (time) of moving between each cell and the user-specified starting points and 2) a second raster map showing the movement direction to the next cell on the path back to the start point (see Movement Direction). It uses an input elevation raster map whose cell category values represent elevation, combined with a second input raster map whose cell values represent friction costs.

This function is similar to r.cost, but in addition to a friction map, it considers an anisotropic travel time due to the different walking speed associated with downhill and uphill movements.

NOTES

The formula from Aitken 1977/Langmuir 1984 (based on Naismith's rule for walking times) has been used to estimate the cost parameters of specific slope intervals:

T = a*delta_S + b*delta_H_uphill + c*delta_H_moderate_downhill + d*delta_H_steep_downhill

where:

  • T is time of movement in seconds,
  • delta S is the horizontal distance covered in meters,
  • delta H is the altitude difference in meters.

The a, b, c, d walk_coeff parameters take in account movement speed in the different conditions and are linked to:

  • a: time in seconds it takes to walk for 1 meter a flat surface (1/walking speed)
  • b: additional walking time in seconds, per meter of elevation gain on uphill slopes
  • c: additional walking time in seconds, per meter of elevation loss on moderate downhill slopes (use positive value for decreasing cost)
  • d: additional walking time in seconds, per meter of elevation loss on steep downhill slopes (use negative value for increasing cost)

It has been proved that moving downhill is favourable up to a specific slope value threshold, after that it becomes unfavourable. The default slope value threshold (slope_factor) is -0.2125, corresponding to tan(-12), calibrated on human behaviour (>5 and \<12 degrees: moderate downhill; >12 degrees: steep downhill). The default values for a, b, c, d walk_coeff parameters are those proposed by Langmuir (0.72, 6.0, 1.9998, -1.9998), based on man walking effort in standard conditions.

The friction cost parameter represents a time penalty in seconds of additional walking time to cross 1 meter distance. Friction cost can be any floating point value ≥ 0. A friction map is a required parameter; if no friction costs are desired, a friction map should be a raster in which all cells have a value of 0.

The lambda parameter is a dimensionless scaling factor of the friction cost:

total cost = movement time cost + lambda * friction costs * delta_S

For a more accurate result, the "knight's move" option can be used (although it is more time consuming). In the diagram below, the center location (O) represents a grid cell from which cumulative distances are calculated. Those neighbours marked with an x are always considered for cumulative cost updates. With the "knight's move" option, the neighbours marked with a K are also considered.

  K   K
K x x x K
  x O x
K x x x K
  K   K

The minimum cumulative costs are computed using Dijkstra's algorithm, that find an optimum solution (for more details see r.cost, that uses the same algorithm).

Movement Direction

The movement direction surface is created to record the sequence of movements that created the cost accumulation surface. This movement direction surface can be used by r.path to recover a path from an end point back to the start point. The direction of each cell points towards the next cell. The directions are recorded as degrees CCW from East:

       112.5      67.5         i.e. a cell with the value 135
157.5  135   90   45   22.5    means the next cell is to the north-west
       180   x   360
202.5  225  270  315  337.5
       247.5     292.5

Once r.walk computes the cumulative cost map as a linear combination of friction cost (from friction map) and the altitude and distance covered (from the digital elevation model), the associated movement direction map can be used by r.path to find the minimum cost path.

r.walk, like most all GRASS raster programs, is also made to be run on maps larger that can fit in available computer memory. As the algorithm works through the dynamic list of cells it can move almost randomly around the entire area. r.walk divides the entire area into a number of pieces and swaps these pieces in and out of memory (to and from disk) as needed. This provides a virtual memory approach optimally designed for 2-D raster maps. The amount of memory to be used by r.walk can be controlled with the memory option, default is 300 MB. For systems with less memory this value will have to be set to a lower value.

EXAMPLES

We compute a map showing how far a lost person could get from the point where he or she was last seen while taking into account the topography and landcover.

g.region swwake_30m -p

# create friction map based on land cover
r.recode landclass96 out=friction rules=- << EOF
1:3:0.1:0.1
4:5:10.:10.
6:6:1000.0:1000.0
7:7:0.3:0.3
EOF

r.walk -k elevation=elev_ned_30m friction=friction output=walkcost \
    start_coordinates=635576,216485 lambda=0.5 max=10000

# compute contours on the cost surface to better understand
# how far the person can get in certain time (1000 is in seconds)
r.contour walkcost output=walkcost step=1000

r.walk example
Figure: Walkshed over a cost surface derived from topography and landcover

REFERENCES

  • Aitken, R. 1977. Wilderness areas in Scotland. Unpublished Ph.D. thesis. University of Aberdeen.
  • Steno Fontanari, University of Trento, Italy, Ingegneria per l'Ambiente e il Territorio, 2000-2001.
  • Langmuir, E. 1984. Mountaincraft and leadership. The Scottish Sports Council/MLTB. Cordee, Leicester.

SEE ALSO

r.cost, r.path, r.in.ascii, r.mapcalc, r.recode, r.out.ascii

AUTHORS

Based on r.cost written by :
Antony Awaida, Intelligent Engineering, Systems Laboratory, M.I.T.
James Westervelt, U.S.Army Construction Engineering Research Laboratory
Updated for Grass 5 by Pierre de Mouveaux (pmx@audiovu.com)

Initial version of r.walk:
Steno Fontanari, 2002

Current version of r.walk:
Franceschetti Simone, Sorrentino Diego, Mussi Fabiano and Pasolli Mattia
Correction by: Fontanari Steno, Napolitano Maurizio and Flor Roberto
In collaboration with: Franchi Matteo, Vaglia Beatrice, Bartucca Luisa, Fava Valentina and Tolotti Mathias, 2004

Updated for GRASS 6.1:
Roberto Flor and Markus Neteler

Updated for GRASS GIS 7:
Markus Metz
Multiple path directions sponsored by mundialis

SOURCE CODE

Available at: r.walk source code (history)
Latest change: Friday Mar 07 07:39:48 2025 in commit e1e37d8