Flags:

-b

Create a simple visible-not visible raster map

-c

Consider the curvature of the earth (current ellipsoid)

-d

allow only downward view direction (can be used for drone view)

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

points=name [required]

Name of input vector map

Name of the input points map (representing the survey location). It can not be a 3D vector layer.

dem=name [required]

Name of the input DEM layer

output=name [required]

Prefix for the output visibility layers

maxdist=float [required]

max distance from the input points

Default: 1000

treesmap=name

Name of input vector map

Name of the vector layer representing the forested areas

buildingsmap=name

Name of input vector map

Name of the vector layer representing the buildings

obs_heigh=double [required]

observer_elevation

Default: 1.75

treesheigh=string

field of the attribute table containing information about threes heigh

buildingsheigh=string

field of the attribute table containing information about buildings heigh

obsabselev=string

field of the attribute table containing information about observer absolute elevation above the same datum used by the DEM (e.g. geodetic elevation)

layer=string

layer of the attribute table of the point map (can be usefull for obsabselev option)

Default: 1

viewangle_threshold=double [required]

cut the output layers at a given threshold value (between 90 and 180 degrees)

Default: 90.01

object_radius=double

radius of the surveyed object in unit of map (default is half the DEM resolution)

nprocs=integer

Number of processes

Default: 1

memory=integer

Amount of memory to use in MB (for r.viewshed analysis)

Default: 500

DESCRIPTION

Depending on the purpose of the study, one can be interested in searching the closest position to observe a given territory while for others, having a frontal view can be more relevant. In some cases, the objective could be the combined balance between the closest and the most frontal view, in order to evaluate how much of the human field of view is occupied by a given object (solid angle).

r.survey is deeply based on the powerfull r.viewshed GRASS GIS module.

r.survey wants to provide the user the necessary information to answer questions such as:

In a survey trip, from how many places is something visible?

During a field work, which place would be the best position to observe a given point/area (according to the distance, the angle or both)?

Which portion of the territory is visible along a survey path/flight?

Are objects of a given size visible from a survey path/flight?

Three principal outputs (visibility indexes) are given, based on trigonometric calculations in order to provide qualitative and quantitative information about how the terrain is perceived from the selected observation point (or viewpoint). This information concerns the three-dimensional distance, the relative orientation (View Angle) and the Solid Angle, of each target pixel with respect to the viewpoint.

A map containing a set of points (having different categories - cat values) describing the locations of the observer and a digital elevation model (DEM) are the mandatory inputs for r.survey. In addition, maps of buildings and trees, portraying height information, can be used to alter the DEM.

Many other options can be set according to the aim of the analysis, such as: observer height respect to the ground or respect to an elevation datum (absolute elevation), maximum distance to perform the calculations, a view-angle threshold to exclude, a priori, cell oriented almost perpendicularly to the lines of sight, the average size of the observed object. The input points map must be provided to the tool as a vector layer. In case it represents the positions of a UAV, an helicopter or of a satellite, it must include an attribute field containing absolute elevation values with respect to a vertical datum (the same datum used by the input DEM). Observer height (respect to the ground, the default is 1.75 m) and maximum distance of observation (default is 1000 m) are parameters needed by the r.viewshed module. The object radius is used to approximate, with an equivalent circle, the minimum size of an object centered in the cells center and oriented according to the slope and aspect of the cells. Since r.survey produces different types of outputs, a name to be used for the prefix of the output maps is requested.

3D Distance is the three dimensional linear distance between a viewpoint and a target pixel (see the illutratio bellow). The min3dDistance map portrays the value of the minimum three-dimensional distance between each pixel and the closest viewpoint, in meters.

Given a viewpoint, r.survey calculate the unit vector describing direction and sense of the line of sight between that viewpoint and each visible pixel (see illustration bellow). We define View Angle as the angle between the line of sight unit vector and the versor normal to the terrain surface in each pixel. The maxViewAngle map shows the value of the maximum View Angle between each pixel and the viewpoints, in degrees. It is a measure of the most frontal view each single cell is visible from. View angle output is always larger than 90° and smaller than 180°.

Solid Angle is one of the best and most objective indicators for quantifying the visibility. The idea is that any observed object will be progressively less apreciable the more far away and the more tilted it is with regard to the viewpoint. As a consequence Solid Angle depends on the size of the observed object as well as on the distance and the orientation from where this object is observed. Solid Angle of a surface is, by definition, equal to the projected spherical surface in the evolving sphere divided by the square of the radius of the sphere. As an aproximation, we use the ellipse surface area in place of the projected spherical surface in the evolving sphere. The maxSolidAngle map shows the value of the maximum Solid Angle among those measured from the different viewpoints. In this map, the closest pixels to the observation points have to be interpreted with special attention, considering that the error, respect to the real Solid Angle, can reach until the 10% in the immediate neighbor pixels

Other three maps (pointOfViewWithMin3dDistance, pointOfViewWithMmaxAngle and pointOfViewWithMmaxSolidAngle) are used to register, in each cell, the identifier of the viewpoints from where an observer can get, respectively, (i) the minimum values of 3D Distance, (ii) the maximum values of View Angle and (iii) the maximum value of the Solid Angle. Another relevant output is the numberOfViews map which portraits the number of viewpoints from where each pixel is visible.

NOTES

Multi-core processing is used by r.survey for reducing the computational time. When the aim is to derive the values of the visibility indexes along a given path (e.g. a road or a UAV track) viewpoints can be very dense in terms of number per unit of distance and the more the viewpoints are, the longer the computational time becomes.

Parallel computation was implemented exploiting the Python Multiprocessing library and the ability of GRASS GIS to set a temporary spatial region centered on the considered point without affecting the parallel computation of the other points.

EXAMPLES

1) This example shows how to run r.survey calculating the solid angle for an object of radius equal to 20 m and using 4 parallel processes.

g.region raster=dtm 
r.survey points=pt_map dem=dtm output=example maxdist=500 object_radius=20 nprocs=4

2) This second example shows how to run r.survey calculating the same layers as in example 1, but this time the outputs are filtered by a View Angle threshold of 100 degrees.

g.region raster=dtm 
r.survey points=pt_map dem=dtm output=example2 maxdist=500 object_radius=20 nprocs=4 viewangle_threshold=100

3) This example shows how to run r.survey in flight mode and with the downward view. The observation points correspond for the path of an UAV flying in a irregular height above the ground. A field with the points altitude information (above de sea level) is mandatory.

g.region raster=dtm 
r.survey -d points=fly_pt_map dem=dtm output=example3 maxdist=1000 nprocs=4 obsabselev=Altitude

SEE ALSO

AUTHORS

SOURCE CODE

Available at: r.survey.py

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2020 GRASS Development Team, GRASS GIS 7.8.4dev Reference Manual