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 target cells within a distance threshold from the current observer. The number of target 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 must 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). obs_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 observer cell. Alternatively, specifying "no_sea" as the obs_mask would count any cells visible from observers on land. Finally, specifying "no_sea" as both the target_mask and obs_mask would count cells on land that are visible from observers 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 value of obs_elev is added to each observation cell 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 an observer is visible, or if the -f flag is set, the number of observer cells which it is possible to see from each other cell.

A particular set of observer cells 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:

-f

Mark each cell in the output map with the number of observers from which it can be seen (i.e. compute viewsheds).

-h

Adjust elevation of oberserver points so that they never fall below surface level. This is useful in conjunction with the spot parameter/attribute (see below) or when using 3D points in mode "sites".

-a

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

-r

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

-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-observer 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 ("no data") cells instead of "-1" to output map.

Parameters:

elevation=name

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

output=name

Name of a new raster map with result visibility counts.

mode=value

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

sites=name

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

obs_height=value

Height of the observer (in map units) above the elevation of the associated cell in the DEM. Default: 1.75 (m).

target_height=value

Height of the target (in map units) above the elevation of the associated cell in the DEM. Default: 0.

max_dist=value

Maximum distance (in map units) from the observer within which the line-of-sight analysis will be performed. Options: 0.0-9999999.9. Default: 2000. Note that the default value is probably too small, and will have to be adjusted in most situations.

sample=value

The sampling frequency as a percentage of the number of map cells in the current region (for modes "systematic" and "random"). Options: 0.0-100.0. Default: 10.0.

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.

obs_mask=name

Name of a binary raster map in which observer cells within the areas of interest are assigned the category value "1 and all other cells are assigned the category value "0".

target_mask=name

Name of a binary raster map in which target cells within the area 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 an observer cell (note, therefore, that observers are targets when viewed from other observers).

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

See below) for a description of what these options mean.

curvc=value

Earth curvature correction will be applied if the distance from the observer location exceeds the given threshold. Set this to "0.0" to disable curvature correction (default). While correction slows down calculations, it is recommended 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" operation mode, r.cva checks for the presence of a number of special fields in the input vector map's attribute table. Each attribute, if present, can be used to control the analysis and must be of integer or double type. The following attribute names (note uppercase spelling!) and value ranges are available:

SPOT: This sets absolute observer height for an observer site. If this attribute is present, observer height will no longer be determined from the DEM. r.cva can automatically raise this value to that of the DEM cell below the oberserver's location, if the value in SPOT would cause the observer to lie below ground level (use the -h flag).
OFFSETA: Use this to add an offset to each oberver point's elevation. 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 cell 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 specific 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 line-of-sight checks. Limits are measured in degrees with 0.0 representing north and values increasing clock-wise. Thus, if one wanted to limit visibility scans to eastward directions only, one 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 at the ground and at 90 degress up into the zenith.
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.

Note: Interpretation of all control attributes can be turned off by using the -i flag.

Note also that you can use the same control values in operation modes other than "sites", if you specify the equivalent options (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 elevation 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 GRASS region, but ignores the current mask. Masking is achieved by specifying "target_mask" and/or "obs_mask". For accurate results, the program must be run with the resolution of the region set equal to the resolution of the elevation raster map/DEM (see g.region).

It is assumed that N-S and E-W resolution of the current region are the same. If they differ, distances thresholds for limiting the line-of-sight distance will be imprecise.

The number of cells visible from a given observer location includes the observer itself only if the observer is a target cell. Consequently, if neither the observer cell nor any other cell within max_dist of it is a target cell, then the size of that observer's viewshed will be zero. Set the -m flag to locate such observers (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 observer 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 the screen 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 regions and low resolution. The sample achieved may be further reduced when an obs_mask has been specified. This will not occur with the option "random", because its algorithm repeatedly allocates observers 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 observers without reference to the mask and then simply ignore those that fall in mask cells coded "0".

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.

AUTHORS

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.

Last changed: 2015-11-10