r.viewshed.exposure

Visual exposure to defined exposure source.

Computes visual exposure to defined exposure source using weighted parametrised cumulative viewshed analysis.

r.viewshed.exposure [-cr] input=name output=name [source=name] [sourcecat=value] [sampling_points=name] [weights=name] [observer_elevation=value] [range=value] [function=name] [b1_distance=value] [sample_density=value] [seed=value] [refraction_coeff=value] [memory=memory in MB] [nprocs=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.viewshed.exposure input=name output=name sampling_points=name

grass.script.run_command("r.viewshed.exposure", input, output, source=None, sourcecat="*", sampling_points=None, weights=None, observer_elevation=1.5, range=100, function="Distance_decay", b1_distance=10, sample_density=25, seed=None, refraction_coeff=0.14286, memory=300, nprocs=1, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.viewshed.exposure", input="name", output="name", sampling_points="name")

Parameters

Command linePython (grass.script)

input=name [required]
    Name of input digital surface raster map
    Name of input raster map
output=name [required]
    Name of output raster map of visual exposure
    Name for output raster map
source=name
    Name of input raster map of exposure source
    Name of input raster map
sourcecat=value
    Raster values to use as exposure source
    1-
    Default: *
sampling_points=name
    Name of input vector map of sampling points
    Or data source for direct OGR access
weights=name
    Name of input raster map of viewshed weights
    Name of input raster map
observer_elevation=value
    Observer elevation above the ground
    0.0-
    Allowed values: 0.0-
    Default: 1.5
range=value
    Exposure range
    0.0- , -1 for infinity
    Allowed values: 0.0-
    Default: 100
function=name
    Viewshed parametrisation function
    Binary, Distance_decay, Fuzzy_viewshed, Visual_magnitude, Solid_angle
    Allowed values: Binary, Distance_decay, Fuzzy_viewshed, Visual_magnitude, Solid_angle
    Default: Distance_decay
b1_distance=value
    Radius around the observer where clarity is perfect. Used in fuzzy viewshed function.
    Default: 10
sample_density=value
    Density of sampling points
    0.0-100.0
    Allowed values: 0.0-100.0
    Default: 25
seed=value
    Random seed, default [random]
    0-
    Allowed values: 0-
refraction_coeff=value
    Refraction coefficient
    0.0-1.0
    Allowed values: 0.0-1.0
    Default: 0.14286
memory=memory in MB
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Default: 300
nprocs=integer
    Number of threads for parallel computing
    Default: 1
-c
    Consider the curvature of the earth (current ellipsoid)

-r
Consider the effect of atmospheric refraction

--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

input : str, required
    Name of input digital surface raster map
    Name of input raster map
    Used as: input, raster, name
output : str, required
    Name of output raster map of visual exposure
    Name for output raster map
    Used as: output, raster, name
source : str, optional
    Name of input raster map of exposure source
    Name of input raster map
    Used as: input, raster, name
sourcecat : str, optional
    Raster values to use as exposure source
    1-
    Used as: value
    Default: *
sampling_points : str, optional
    Name of input vector map of sampling points
    Or data source for direct OGR access
    Used as: input, vector, name
weights : str, optional
    Name of input raster map of viewshed weights
    Name of input raster map
    Used as: input, raster, name
observer_elevation : float, optional
    Observer elevation above the ground
    0.0-
    Used as: value
    Allowed values: 0.0-
    Default: 1.5
range : float, optional
    Exposure range
    0.0- , -1 for infinity
    Used as: value
    Allowed values: 0.0-
    Default: 100
function : str, optional
    Viewshed parametrisation function
    Binary, Distance_decay, Fuzzy_viewshed, Visual_magnitude, Solid_angle
    Used as: name
    Allowed values: Binary, Distance_decay, Fuzzy_viewshed, Visual_magnitude, Solid_angle
    Default: Distance_decay
b1_distance : float, optional
    Radius around the observer where clarity is perfect. Used in fuzzy viewshed function.
    Used as: value
    Default: 10
sample_density : float, optional
    Density of sampling points
    0.0-100.0
    Used as: value
    Allowed values: 0.0-100.0
    Default: 25
seed : int, optional
    Random seed, default [random]
    0-
    Used as: value
    Allowed values: 0-
refraction_coeff : float, optional
    Refraction coefficient
    0.0-1.0
    Used as: value
    Allowed values: 0.0-1.0
    Default: 0.14286
memory : int, optional
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Used as: memory in MB
    Default: 300
nprocs : int, optional
    Number of threads for parallel computing
    Default: 1
flags : str, optional
    Allowed values: c, r
    c
        Consider the curvature of the earth (current ellipsoid)

r
Consider the effect of atmospheric refraction

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.viewshed.exposure computes visual exposure to given exposure source(s) using weighted (optional) parametrised (optional) cumulative viewshed.

The algorithm

The processing workflow of the module consists of five steps:

Random sampling of exposure source raster map with vector points,
Calculating binary viewshed for each exposure source point,
Optional parametrisation of the binary viewshed,
Optional weighting of the (parametrised) viewshed,
Cumulating the (weighted) (parametrised) viewsheds.

Processing workflow

1. Random sampling of exposure source raster map with vector points

To improve computational efficiency, the exposure source raster map is randomly sampled with defined density (0-100%; option sample_density). In general, lower sampling densities lead to lower accuracy, higher uncertainty of the result and lower processing time, while higher sampling densities lead to higher accuracy, lower uncertainty of the result and longer processing time. Alternatively, it is possible to replace the exposure source raster map with own vector map of exposure source points (option sampling_points).

2. Binary viewshed for each exposure source point

A binary viewshed for each exposure source point is calculated using r.viewshed module. The height of exposure source point above the surface is 0m. The height of observer point (exposure receiver) above the surface is specified by option observer_elevation. Viewshed radius (range of visual exposure) is specified by option max_distance.

3. (optional) Parametrisation of the binary viewshed

The module supports different parametrization functions to better reflect human visual perspective by accounting for the variable contribution of the exposure source pixels to visual exposure depending on their distance, slope and aspect relative to the observer (option function). Four parametrisation functions are implemented: distance decay function, fuzzy viewshed function, visual magnitude function and solid angle function.

In distance decay function, the contribution of an exposure source pixel xi to visual exposure at the observer pixel decreases in proportion to the square of distance between the exposure source pixel and the observer: D(xi) = A/v²; A is the area of the exposure source pixel, v is the distance between the exposure source pixel and the observer. See Grêt-Regamey et al. (2007) and Chamberlain and Meitner (2013) for more details.

In fuzzy viewshed function, the contribution of an exposure source pixel xi to visual exposure at the observer pixel depends on the distance between the exposure source pixel and the observer and the radius of perfect clarity. See Fisher (1994) and Ogburn (2006) for more details.

In visual magnitude function, the contribution of an exposure source pixel xi to visual exposure at the observer pixel depends on the pixel's slope, aspect and distance relative to the observer. See Chamberlain and Meitner (2013) for more details.

In solid angle function, the contribution of an exposure source pixel xi to visual exposure at the observer pixel is calculated as a solid angle, i.e. the area (in sterradians) of the observer's eye retina covered by the exposure source pixel. See Domingo-Santos et al. (2011) for more details.

4. (optional) Weighting of the (parametrised) viewshed

Weighting of the individual (parametrised) viewsheds enables modelling variable intensities of the exposure sources. The individual viewsheds are multiplied by values extracted from the weights raster map (option weights) at the exposure source points.

5. Cumulating the (weighted) (parametrised) viewsheds

After each iteration, the partial viewsheds are cumulated (added), resulting in a raster of (weighted) (parametrised) cumulative viewshed. This raster represents visual exposure to the exposure source.

Memory and parallel processing

Options memory specifies the amount of memory allocated for viewshed computation. Option nprocs specifies the number of cores used in parallel processing. In parallel processing, the computation of individual viewsheds is randomly distributed across the specified cores.

EXAMPLES

Computation of visual exposure to major roads in South-West Wake county, North Carolina. Input data are a terrain model and a raster map of major roads from NC dataset. Viewshed parametrisation function is set to none (example 1) and solid angle (example 2). Sampling density is set to 50%, exposure range to 2km.

# set computation region to terrain model
g.region raster=elevation@PERMANENT

# calculate visual exposure
# no viewshed parametrisation function (binary viewshed)
r.viewshed.exposure input=elevation@PERMANENT
  output=exposure_roadsmajor_b
  source=roadsmajor@PERMANENT
  observer_elevation=1.50
  max_distance=2000
  sample_density=50 memory=5000 nprocs=25

# calculate visual exposure
# solid anfle viewshed parametrisation function
r.viewshed.exposure input=elevation@PERMANENT
  output=exposure_roadsmajor_s
  source=roadsmajor@PERMANENT
  observer_elevation=1.50
  max_distance=2000
  function=solid_angle
  sample_density=50 memory=5000 nprocs=25

# scale solid angle values for visualisation purposes
# (see Domingo-Santos et al., 2011)
r.mapcalc expression=exposure_roadsmajor_s_rescaled =
  if(exposure_roadsmajor_s@user1>=0.2*3.1416,1,1/
  (-1* log(exposure_roadsmajor_s@user1 /(2*3.1416))))

Example of r.viewshed.exposure (1)

Example of r.viewshed.exposure (2)

TODO

Implement variable exposure source height.
Implement possibility to switch between absolute and relative values of visual exposure (now absolute).

REFERENCES

Cimburova, Z., Blumentrath, S., 2022. Viewshed-based modelling of visual exposure to urban greenery - an efficient GIS tool for practical applications. Landscape and Urban Planning 222, 104395. https://doi.org/10.1016/j.landurbplan.2022.104395
Chamberlain, B.C., Meitner, M.J., 2013. A route-based visibility analysis for landscape management. Landscape and Urban Planning 111, 13-24. https://doi.org/10.1016/j.landurbplan.2012.12.004
Domingo-Santos, J.M., de Villarán, R.F., Rapp-Arrarás, Í., de Provens, E.C.-P., 2011. The visual exposure in forest and rural landscapes: An algorithm and a GIS tool. Landscape and Urban Planning 101, 52-58. https://doi.org/10.1016/j.landurbplan.2010.11.018
Fisher, P., 1994. Probable and fuzzy models of the viewshed operation, in: Worboys, M.F. (Ed.), Innovations in GIS. Taylor & Francis, London, pp. 161-176.
Grêt-Regamey, A., Bishop, I.D., Bebi, P., 2007. Predicting the scenic beauty value of mapped landscape changes in a mountainous region through the use of GIS. Environment and Planning B: Planning and Design 34, 50-67. https://doi.org/10.1068/b32051
Ogburn, D.E., 2006. Assessing the level of visibility of cultural objects in past landscapes. Journal of Archaeological Science 33, 405-413. https://doi.org/10.1016/j.jas.2005.08.005

AUTHORS

Zofie Cimburova, NINA
Stefan Blumentrath, NINA

SOURCE CODE

Available at: r.viewshed.exposure source code (history)
Latest change: Friday Feb 21 10:10:05 2025 in commit 7d78fe3