GRASS GIS manual: r.terracost

Note: This document is for an older version of GRASS GIS that is outdated. You should upgrade, and read the current addon manual page.

NAME

r.terracost - Computes a least-cost surface for a given cost grid and set of start points.

KEYWORDS

raster, cost surface, cumulative costs

SYNOPSIS

r.terracost
r.terracost help
r.terracost [-hqisd01234] input=name start_raster=name output=name [numtiles=integer] [memory=integer] [STREAM_DIR=string] [VTMPDIR=string] [tileStr=string] [bndStr=string] [bspStr=string] [sbspStr=string] [config=string] [phase2Bnd=string] [stats=string] [tilesAreSorted=string] [--overwrite] [--verbose] [--quiet]

Flags:

-h: Help
-q: Quiet
-i: Info (print suggested numtiles information and exit)
-s: Dbg: Save output to ASCII file "DIST_GRID"
-d: Dbg: Print (a lot of) debug info (developer use)
-0: Dbg: Step 0 only (default: run all)
-1: Dbg: Step 1 only (default: run all)
-2: Dbg: Step 2 only (default: run all)
-3: Dbg: Step 3 only (default: run all)
-4: Dbg: Step 4 only (default: run all)
--overwrite: Allow output files to overwrite existing files
--verbose: Verbose module output
--quiet: Quiet module output

Parameters:

input=name: Name of raster map containing grid cell cost information
start_raster=name: Name of starting raster points map
output=name: Output distance grid raster map
numtiles=integer: Number of tiles (default: 1); Default: 1
memory=integer: Main memory size (in MB); Default: 400
STREAM_DIR=string: Location of temporary STREAMs; Default: /var/tmp
VTMPDIR=string: Location of intermediate STREAMs; Default: /var/tmp/martinl
tileStr=string: Dbg: Stream name stem for step 0 output; Default: terracost.tileStr
bndStr=string: Dbg: Stream name for boundary data structure; Default: terracost.bndStr
bspStr=string: Dbg: Output file for step 1; Default: terracost.bspStr
sbspStr=string: Dbg: Output file for source to boundary stream; Default: terracost.sbspStr
config=string: Dbg: Name for config file; Default: terracost.config
phase2Bnd=string: Dbg: Name for phase2Bnd file; Default: terracost.phase2Bnd
stats=string: Dbg: Stats file; Default: terracost.stats
tilesAreSorted=string: Dbg: Tiles are sorted (used in grid version) (y/n); Default: no

DESCRIPTION

r.terracost is a scalable approach for computing least-cost-path surfaces on massive grid terrains. The module outperforms standard solutions as dataset size increases relative to available memory.

NOTES

r.terracost computes a least-cost surface for a given cost grid and set of start points using an approach that scales to large grids. For details, see paper "TerraCost: A Versatile and Scalable Approach for Path Computations on Massive Grid-Based Terrains" by Hazel, Toma, Vahrenhold and Wickremesinghe (2006). The basic idea is to split the grid in tiles. numtiles is the number of tiles. Run with -i to see the recommended value for numtiles. When numtiles=1 it runs Dijkstra's algorithm in memory. When numtiles > 1 it runs an external SP algorithm that consists of 5 steps. For debugging purposes, it is possible to run the five steps separately. When running in separate steps, an intermediate config file stores temporary information, and other streams (see below) contain intermediate data.

Step 0 (setup) inputs from GRASS; outputs are "S0OUT" and "S0BND"
Step 1 (compute substitute graph: intra-tile Dijkstra) inputs are "S0OUT" and "S0BND"; outputs are "S1OUT" and "S2BOUT"
Step 2 (sorting) input is "S1OUT"; output is "S1OUT"
Step 3 (inter-tile) inputs are "S0OUT", "S0BND", "S1OUT", and "S2BOUT"; output is "PHASE2BND"
Step 4 (final-tile) inputs are "S0OUT" and "PHASE2BND"; output goes to GRASS maps: Map names are specified relative to "VTMPDIR", or with absolute path (name beginning with /).

IOLibrary temporary streams will be in STREAM_DIR.

REFERENCES

Hazel, T., Toma, L., Vahrenhold, J., and Wickremesinghe, R. 2006. TerraCost: a versatile and scalable approach to computing least-cost-path surfaces for massive grid-based terrains. In: Proceedings of the 2006 ACM Symposium on Applied Computing (Dijon, France, April 23-27, 2006). SAC '06. ACM, New York, NY, 52-57.
[ PDF ]
Toma, L., 2006. TerraCost: Scalable Computation of Least-Cost-Path Surfaces. Talk at FOSS4G 2006, Lausanne, Switzerland.
[ Abstract and PDF ]

AUTHOR

Laura I. Toma, http://www.bowdoin.edu/~ltoma/research.html

Last changed: $Date: 2010-10-09 21:13:35 -0700 (Sat, 09 Oct 2010) $

Main index - raster index - Full index