NAME
r.catchment - Creates a raster buffer of specified area around vector points using cost distances using r.walk.
KEYWORDS
raster,
buffer
SYNOPSIS
r.catchment
r.catchment --help
r.catchment [-ikcl] elevation=name [in_cost=name] start_points=name [friction=name] [walk_coeff=float] [lambda=float] [slope_factor=float] buffer=name [sigma=float] area=integer map_val=integer [name_column=name] [--overwrite] [--help] [--verbose] [--quiet] [--ui]
Flags:
- -i
- Iterate through each point in the input starting points vector map to create a series of catchment maps centered at each input point rather than a single map starting at all points. Maps will be named "'buffer'_'name'_'id#'", where 'buffer' is the value entered for option 'buffer', 'name' is the value in "name_column" for each input point and 'id#' is unique running id number. If no value specified in "name_column", cat value will be used in place of 'name'). NOTE: this function is NOT compatible with option "in_cost" or flag "l"
- -k
- Use knight's move for calculating cost surface (slower but more accurate)
- -c
- Keep cost surface(s) used to calculate buffers (follows similar naming convention from flag -i if -i is also selected)
- -l
- Show a list of all cost surface values and the area of the catchment that they delimit
- --overwrite
- Allow output files to overwrite existing files
- --help
- Print usage summary
- --verbose
- Verbose module output
- --quiet
- Quiet module output
- --ui
- Force launching GUI dialog
Parameters:
- elevation=name [required]
- Input elevation map (DEM)
- in_cost=name
- Input cost map (This will override the input elevation map, if none specified, one will be created from input elevation map with r.walk)
- start_points=name [required]
- Name of input vector map
- Name of input vector site points map
- friction=name
- Optional map of friction costs. If no map selected, default friction=0 making output reflect time costs only
- Default:
- walk_coeff=float
- Coefficients for walking energy formula parameters a,b,c,d
- Default: 0.72,6.0,1.9998,-1.9998
- lambda=float
- Lambda value for cost distance calculation (for combining friction costs with walking costs)
- Default: 1
- slope_factor=float
- Slope factor determines travel energy cost per height step
- Default: -0.2125
- buffer=name [required]
- Output buffer map name, or name-stem for all buffer maps created with flag -i
- sigma=float
- Slope threshold for mask
- area=integer [required]
- Area of buffer (Integer value to nearest 100 square map units)
- Default: 5000000
- map_val=integer [required]
- Integer value for output catchment area (all other areas will be Null)
- Default: 1
- name_column=name
- Database column for point names (with flag -i)
r.catchment is a module that facilitates modeling
"catchments" around point locations according to a walking cost
function. The module is particularly aimed at "Site Catchment
Analysis" for archaeology, but could be potentially useful in any
number of applications where delimiting an area based on
walking-costs is desirable. Although defining a catchment based on
a threshold in walking-costs (or time) can be undertaken using
r.walk or
r.cost alone, this addon module allows the
user to enter a pre-determined square meterage (option
area)
for the resultant catchment, which is a different approach. This is
useful for applications where the user wants to make a catchment of
a particular size (e.g., certain number of square meters needed for
farmed fields), and doesn't want to spend time via trial and error
experimenting with different cost radii.
Additionally, this module allows the user to enter a slope threshold
(option sigma), which will mask out areas of higher slope.
This is useful for delimiting catchments that are of generally flat
land (e.g., areas where agriculture are likely).
Optionally, you can iteratively loop through a series of input
starting points, and create catchments for each point. You can also
opt to save the cost map produced by r.walk for each input point.
This can be a useful timesaver for the creation of many cost maps
and/or catchment maps with minimal manual repetition.
Important: The user must run g.region first to make sure that
the region boundaries and the resolution match the input elevation map.
r.catchment requires an input elevation map,
elevation
, and an input vector points map of starting locations,
start_points.
area is also requited, which is an integer
value for the size of the desired catchment (in the map units of the
defined location/region). The final required parameter is
map_val
, which is the integer value to write to the areas defined as
part of the catchment in the output map,
buffer. The optional
value,
sigma is the slope threshold cut off value. Slopes
above
sigma will be masked out during the determination of
the catchment configuration. The optional value
name_column
is to be used in conjunction with the
-i flag (see below).
There are three native flags for
r.catchment.
-c
allows you to keep the interim cost surface maps made.
-l allows
you to show a list of the costv alues in that cost map, along with
the size of the catchments they delineate.
-i enable "iterative"
mode. Here, the module will loop through all the points in the input
vector file
start_points, calculating a cost map and catchment
map around each point. If
name_column is specified, then each
output map will contain the text value in that column as an prefix.
Otherwise, the cat number for each vector point will be used.
All other flags and options are inherited from
r.walk (see the
r.walk
help page for more information on these).
The module will attempt to find the cost radius that defines an area
close to the value of
area, but em will likely slightly
overestimate the catchment size. The module will display the actual
area of the defined catchment in the Command Output.
By default,
r.catchment will create a
friction map
of value 0, which, when input into
r.walk will yield a cost
surface based on walking times only. The user may optionally create
a
friction map, however, and, if used, r.walk will consider
these costs this as well when determining the cost surface used to
determine the catchment.
The input
start_points map should be a vector points map.
If the file contains other types of features (areas, lines, centroids),
these will be ignored. If you desire, a start points map could be
manually digitized (with
v.digit) over topographic or
cultural features, or could be created as a series of random points
(with
r.random or
v.random).
Unless the
-i flag is used, in the case of multiple input points,
the routine will attempt to equally divide the area (
area)
between all input points tod etermine catchments for each point. The
total area of all these catchments will sum (close) to
area.
If two input points are close, their catchments may overlap. In this
case, the routine will "meld" the two, and the melded catchment will
till be of an area close to
area. If truly overlapping
catchments are desired, then the routine should be run with the
-i flag. This will create completely independent catchments
around each input point.
Delimit a catchment of 5,000,000 square meters around a single start
point, ignoring areas of slope > 15 degrees:
r.catchment elevation=DEM10m start_points=site buffer=test_catchment
sigma=15 area=5000000 map_val=1
r.walk, r.cost
Isaac Ullah
Updated for GRASS 8, 02, Feb. 2023.
SOURCE CODE
Available at:
r.catchment source code
(history)
Latest change: Monday Jun 24 08:16:48 2024 in commit: 8939a985d18de5366340b88037ab0fe3a0814c9b
Main index |
Raster index |
Topics index |
Keywords index |
Graphical index |
Full index
© 2003-2024
GRASS Development Team,
GRASS GIS 8.4.1dev Reference Manual