GRASS GIS manual: r.cva

NAME

r.cva - Cumulative visibility/viewshed analysis

KEYWORDS

SYNOPSIS

r.cva
r.cva help
r.cva [-fharimn] elevation=name output=name mode=string [sites=name] [layer=integer] [obs_height=float] [target_height=float] [max_dist=float] [sample=float] [seed=integer] [obs_mask=name] [target_mask=name] [spot=float] [offseta=float] [offsetb=float] [azimuth1=float] [azimuth2=float] [vert1=float] [vert2=float] [radius1=float] [radius2=float] [curvc=float] [memory=integer] [--overwrite] [--verbose] [--quiet]

Flags:

-f: Calculate 'visibility from' instead of 'visibility of' observer
-h: Adjust observer sites that are below surface
-a: Interpret sample size as absolute no. of cells
-r: Allow replacement during random sampling
-i: Ignore site attributes
-m: Differentiate masked 0 cells from elevation value '0'
-n: Convert '-1' to 'no data' in output map
--overwrite: Allow output files to overwrite existing files
--verbose: Verbose module output
--quiet: Quiet module output

Parameters:

elevation=name: Elevation input raster map
output=name: Name of result raster map
mode=string: Operation mode of viewshed analysis; Options: sites,systematic,random,all; Default: sites
sites=name: Points vector map with observer sites (mode 'sites')
layer=integer: Layer number; A single vector map can be connected to multiple database tables. This number determines which table to use.; Default: 1
obs_height=float: Observer height (in elevation map units); Default: 1.75
target_height=float: Target height (in elevation map units); Default: 0.0
max_dist=float: Max viewing distance in map units; Options: 0.0-9999999.9; Default: 2000.0
sample=float: Sampling frequency as a percentage of cells (modes 'systematic' and 'random'); Default: 10.0
seed=integer: Seed for the random number generator; Options: 0-32767; Default: 1
obs_mask=name: Binary (0/1) raster mask for observer cells
target_mask=name: Binary (0/1) raster mask for target cells
spot=float: Absolute elevation for observer sites
offseta=float: Observer elevation offset (OFFSETA)
offsetb=float: target elevation offset (OFFSETB)
azimuth1=float: Minimum observer view azimuth (AZIMUTH1); Options: 0.0-360.0
azimuth2=float: Maximum observer view azimuth (AZIMUTH2); Options: 0.0-360.0
vert1=float: Minimum observer vertical view angle (VERT1); Options: 0.0-90.0
vert2=float: Maximum observer vertical view angle (VERT2); Options: -90.0-0.0
radius1=float: Minimum distance from observer (RADIUS1)
radius2=float: Maximum distance to observer (RADIUS2)
curvc=float: Earth curvature correction threshold (0.0 = off); Default: 0.0
memory=integer: Memory limit (max. blocking points in one LOS); Options: 100-1000000000; Default: 1000000

r.cva

NAME

r.cva - Performs cumulative visibility/viewshed analysis with flexible processing options

QUICKSTART

Examples of common cumulative viewshed analyses, with "MyDEM" being a raster map containing elevation data (this program supports both integer and floating point type elevation maps):

For each cell of the elevation raster map, count the number of cells from which it can be seen (mode=all):

r.cva elevation=MyDEM mode=all

For each cell that contains a point in an input vector map, compute the binary viewshed (0=invisible, 1=visible) from it and accumulate the results for all points (mode=sites):

r.cva -f elevation=MyDEM sites=observers output=visibility mode=sites

DESCRIPTION

This program performs multiple line-of-sight checks between one or more observer cells and multiple cells within a distance threshold from the current observer. The number of cells within all unbroken lines of sight is recorded for each observer and stored in the raster output map as a cumulative count.

Two fundamental types of visibility can be computed:

"visibility of" (default) - The visibility of an observer is the count of cells from which it can be seen.
"visibility from" (when -f flag is set) - The visibility from an observer is the set of cells that can be seen by it (commonly called a "viewshed").

In addition, there are several modes of operation, specified using the mode option:

"sites" - Visibility of/from observer sites (points) in a vector map.
"systematic" - Visibility of/from a subset of cells in the elevation input map.
"random" - Visibility of/from a random sample of cells in the elevation input map.
"all" - Visibility of/from all cells in the elevation input map.

The definition of which cells constitute "observers" depends on the mode of operation:

In mode "sites", an observer is a point in the input vector map.
In mode "all", every cell of the input elevation map eventually becomes an observer once Note that the results of "visibility from" and "visibility to" are not necessarily identical in this mode, due to the assymetric effects of options such as observer/target height on line-of-sight computations.
In modes "systematic" and "random", only some cells of the input elevation map become observer cells once.

In all modes, the number of potentially visible cells/extent of viewsheds may be limited by many options, such as a distance from observer threshold and viewing angle ranges.

DETAILS

r.cva generates a cumulative visibility/viewshed map. When run without the -f flag, each observer cell is marked with the number of surrounding cells from which it can be seen. In this mode the only cells that contain visibility counts in the output map are the observer cells. Alternatively, if the -f flag is set then each cell in the output map stores the number of observer cells from which it can be seen. In either case, observer cells may be chosen in one of four ways. The first (mode=all) treats every cell as an observer once. This is so computationally demanding that it is unlikely to be feasible unless the number of cells in the current region and/or max_dist are relatively small. The second (mode=systematic) uses a systematic sample of cells arranged on a rectangular grid. The third (mode=random) uses a random sample. By default the random sampling algorithm does not allow replacement (i.e. a cell can be selected as an observer only once), but this behaviour can be altered by setting the -r flag. The fourth option (mode=sites) uses the points in the specified sites map. The options "systematic" and "random" allow the user to specify any sampling frequency between 0% and 100%.

The cells used in the analysis can be constrained by one or both of two masks. Both masks should be binary raster maps in which the areas of interest are coded "1" and all other cells "0". target_mask determines which cells are targets: a cell which is not a target will be returned as not visible from a given viewpoint even if it is actually visible according to the line-of-sight analysis (i.e. this mask performs the same function as patt_map in r.los). viewpt_mask constrains which cells may be treated as observers. For example, suppose that the raster map `no_sea' codes sea (elevation = 0) as `0' and land (elevation > 0) as `1'. In this case, specifying `no_sea' as the target_mask would cause r.cva to count cells on land that are visible from any viewpoint. Alternatively, specifying `no_sea' as the viewpt_mask would count any cells visible from viewpoints on land. Finally, specifying `no_sea' as both the target_mask and viewpt_mask would count cells on land that are visible from viewpoints on land.

The geometry of the potential line of sight between each pair of cells may be altered by means of two offsets, obs_elev and target_elev. The height obs_elev is added to the viewpoint and the height target_elev to each target cell. Note that by swapping these values it is possible to produce maps showing the number of cells from which a viewpoint is visible, or if the -f flag is set, the number of viewpoints which it is possible to see from each map cell.

A particular set of viewpoint locations in a random sample can be repeated by specifying the same value for seed. Alternatively, different values can be used to produce independent samples for statistical testing.

OPTIONS

Flags:

-a

Treat the specified sample size as an absolute number of cells rather than a percentage. Note, this flag is only for use with random sampling.

-f

Mark each cell in the output map with the number of viewpoints from which it can be seen.

-h

Adjust height of oberserver points so that they will never fall below surface level. This is only useful in conjunction with the spot parameter or attribute (see below).

-i

Do not interpret control attributes in input vector map (sites=) as described below).

-m

Differentiate between genuine zero data values and null data in the output map. When the -f flag has not been set this ensures that all non-viewpoint cells are coded `-1'. When the -f flag has been set then all cells coded `0' in the target_mask (if there is one) are coded `-1'. See below for guidance when to set this flag.

-n

In conjunction with -m: write NULL values instead of '-1' to output map.

-o

Overwrite the output raster map if it already exists.

-q

Be quiet about progress, confirming only the output file and sampling frequency. This is useful when r.cva is invoked from a script with standard output redirected to a disk file.

-r

Allow replacement during random sampling (i.e. allow a given cell to be picked as a viewpoint more than once). Note that no cumulation occurs for replacement viewpoints; this ensures that the resulting cumulative viewshed will be as though the viewpoint was selected once only (the final output map will, of course, be different because replacement effectively results in the use of fewer viewpoints for a given sampling frequency).

-s

Be silent about progress, in which case it is strongly recommended that you use r.info to confirm what sampling frequency was actually achieved.

Parameters:

elevation=name

Name of a raster map layer containing elevation data (i.e. a DEM), used to compute lines of sight.

target_mask=name

Name of a binary raster map layer in which target cells within the areas of interest are assigned the category value `1' and all other cells are assigned the category value `0'. A cell is treated as a target when it is viewed from a viewpoint (note, therefore, that viewpoints are targets when viewed from other viewpoints).

viewpt_mask=name

Name of a binary raster map layer in which viewpoints within the areas of interest are assigned the category value `1' and all other cells are assigned the category value `0'.

sites=name

The name of an input vector map containing the "sites" (vector points) that are to be treated as viewpoints/observer locations. Sites falling outside the current region are ignored.

obs_elev=value

Height of the observer (in metres) above the elevation of the viewpoint. Default: 1.75 m

target_elev=value

Height of the object of interest (in metres) above the elevation of the target cell. Default: 0.0 m

max_dist=value

Maximum distance (in metres) from the viewing point within which the line-of-sight analysis will be performed. Options: 0-99999 (stated in map units). Default: 100

seed=value

The seed for the random number generator used during random sampling. This option allows exact reproduction of a previous result. Options: 0-32767. Default: 1

sample=value

The sampling frequency as a percentage of the number of map cells in the current region. Options: 0.0-100.0. Default: 10.0

type=value

The type of sampling regime used to select viewpoints for analysis. See above for details. Options: "all", "systematic", "random", "sites".

spot, offseta, offsetb, azimuth1, azimuth2, vert1, vert2, radius1, radius2

See below) for a description of what they do.

curvc=value

Earth curvature correction will be applied if the distance from the observer point exceeds the given threshold. Set this to 0.0 to disable curvature correction (default). While correction slows down calculations, it is recommend for viewing distances of more than about 3 km. The correction uses a simplified formula which is accurate to 1 in 10,000 for distances up to 40 km:

d(height)=dist^2/(2*Re)

With Re being the radius of the earth (ca. 6,356,766 m).

Vector map attributes:

When using 'sites' type operation mode, r.cva checks for the presence of a number of attributes in the input vector map's attribute table. Each attribute, if present, must be of integer or double type. The following attribute names and value ranges are recognised and interpreted:

SPOT: This determines absolute observer height. If this attribute is given, observer height will no longer be determined from the DEM. r.cva can automatically raise this value to that of the DEM point below the oberserver's position, if the value in SPOT would cause the observer to get below ground level (use the -h flag).
OFFSETA: Use this to add an offset to each oberver point's height. This is just an alias for the obs_elev option and exists for compatibility reasons.
OFFSETB: The value stored in 'OFFSETB' will be added to each target point at the moment it is considered for visibility. All blocking points on the line-of-sight between observer and target will be left untouched. This is different from the target_elev parameter. It can be used to simulate visibility of targets with a certain height.
AZIMUTH1, AZIMUTH2: These attributes must be given as values between 0.0 and 360.0 and can be used to limit the horizontal scan range of the viewshed. Limits are measured in degrees with 0.0 in the North and values increasing clock-wise. Thus, if you wanted to limit visibility scans to eastward directions only, you would set AZIMUTH1=1 and AZIMUTH2=180.
VERT1, VERT2: In analogy to 'AZIMUTH1' and 'AZIMUTH2', these attributes can be used to limit the vertical range of the scan. The range is -90 to 0 for 'VERT1' and 0 to 90 for 'VERT2'. At -90 degrees, the observer looks straight down to the ground and at 90 degress up into the sky.
RADIUS1, RADIUS2: Finally, two attributes exist to limit the distance of the scan. 'RADIUS1' determines the minimum distance from the observer and 'RADIUS2' the maximum distance. The latter is thus equivalent to using the max_dist parameter and exists for compatibility reasons.

Interpretation of these attributes can be turned off by using the -i flag.

Note that you can use the same control values in operation modes other than 'sites', if you specify the equivalent parameters (see above). The latter will also work as global settings in 'sites' mode. Attributes stored in the vector map table will override these global settings unless the -i flag is specified. The meaning of OFFSETA, OFFSETB and RADIUS1 is the same as obs_elev, target_elev and max_dist. The latter still exists for compatibility with earlier versions of r.cva.

NOTES

Input sites can also be 3D points, in which case absolute observer height is represented by the z coordinate. If spot= has been specified or a 'SPOT' attribute is present in the input vector map's attribute table, then these settings will override the z coordinate. Make sure that the top and bottom settings of the current region are set to a range that encompasses all points of interest (use g.region -p -3 to review current 3D region settings).

r.cva works in the current geographic region, but ignores the current mask. Masking is achieved by specifying a target_mask and/or a viewpt_mask. For accurate results, the program must be run with the resolution of the geographic region set equal to the resolution of the data (see g.region).

This program assumes all height and distance measurements in meters. Legacy units must be converted to meters by the user before running r.cva.

It is also assumed, that N-S and E-W resolution of the current region are the same. If they differ, distances calculated for limiting the viewshed will be imprecise and results affected accordingly.

The number of cells visible from a given viewpoint includes the viewpoint itself only if the viewpoint is a target cell. Consequently, if neither the viewpoint nor any other cell within max_dist of it is a target cell then the size of that viewpoint's viewshed will be zero. Set the -m flag to locate such viewpoints (they will show as cells coded `0' as opposed to `-1'). Similarly, set the -m flag when the -f flag has been set in order to differentiate cells which are genuinely not visible from any viewpoint as opposed to those that are not target cells.

r.cva always informs the user what sampling frequency was attempted and subsequently achieved. This information is printed to standard output and is also placed in the output map's history file (which can be viewed using r.info). The sample attempted may differ slightly from that requested owing to the need to sample a whole number of cells. Any such discrepancy will be greatest in the case of small maps of coarse resolution. The sample achieved may be further reduced when a viewpt_mask has been specified. This will not occur with the option `random', because its algorithm repeatedly allocates viewpoints until the number that fall within mask cells coded `1' produces the frequency attempted. Such a reduction can, however, occur with the options `all', `systematic' and `sites', because their algorithms allocate viewpoints without reference to the mask and then simply ignore those that fall in mask cells coded `0'.

AUTHOR

Mark Lake, Institute of Archaeology, University College London (the author).

With contributions by: Benjamin Ducke, Institute of Archaeology, University of Kiel, Germany.

ACKNOWLEDGEMENTS

This version of r.cva was completed during the author's tenure of a Leverhulme Trust Special Research Fellowship at the Institute of Archaeology, University College London, U.K.

The first version of r.cva was written by the author as part of the MAGICAL Project directed by Dr. Steven Mithen (Dept. of Archaeology, University of Reading, U.K.). The MAGICAL Project was made possible by a Natural Environment Research Council award (NERC GR3/9540) to Dr. Mithen.

r.cva draws heavily on the code for r.los, which was written by Kewan Q. Khawaja, Intelligent Engineering Systems Laboratory, M.I.T.

Adaptation to GRASS 6 vector and raster formats, additional functionality, documentation updates by Benjamin Ducke.

CAVEATS

Handling "no data" (null) cells in viewshed analyses is a tricky problem. Physical terrain does not feature "no elevation" locations and thus the semantics of "no data" cells are hard to define in the context of a line of sight computation. This program will simply ignore "no data" cells but, for the reason above, that does not mean that a physically accurate viewshed will be computed. This concern may be negligible on those cases where the "no data" cells occur strictly outside the region of interest.

This program's memory footprint is small, but computation times can be excessive for large regions. If this becomes a problem in mode "all", consider using modes "systematic" or "random" instead. In addition, consider using as a smaller setting for max_dist.

The default option values for observer/target heights and distance limits assume that the map units are meters.

BUGS

Missing values in site attributes are currently not handled.

When max_dist is set to 100, the N-S and E-W resolutions are 50, and a target_mask has been specified, the cells immediately NE, SE, SW and NW of the viewpoint may not be masked when they should be. Please report any others that you find to the author.

Note that r.cva fixes two bugs in the original version of r.los: that obs_elev is truncated to its integer component and that the target mask (patt_map in r.los) does not apply to the viewpoint or its eight immediate neighbours.

Last changed: 2015-11-10

Main index - raster index - Full index

NAME

KEYWORDS

SYNOPSIS

Flags:

Parameters:

NAME

QUICKSTART

DESCRIPTION

DETAILS

OPTIONS

Flags:

Parameters:

Vector map attributes:

NOTES

SEE ALSO

AUTHOR

ACKNOWLEDGEMENTS

CAVEATS

BUGS