Provided by: grass-doc_7.8.2-1build3_all bug

NAME

       r.viewshed  - Computes the viewshed of a point on an elevation raster map.
       Default format: NULL (invisible), vertical angle wrt viewpoint (visible).

KEYWORDS

       raster, viewshed, line of sight, LOS

SYNOPSIS

       r.viewshed
       r.viewshed --help
       r.viewshed    [-crbe]    input=name    output=name   coordinates=east,north    [observer_elevation=value]
       [target_elevation=value]       [max_distance=value]        [refraction_coeff=float]        [memory=value]
       [directory=string]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

   Flags:
       -c
           Consider the curvature of the earth (current ellipsoid)

       -r
           Consider the effect of atmospheric refraction

       -b
           Output format is invisible = 0, visible = 1

       -e
           Output format is invisible = NULL, else current elev - viewpoint_elev

       --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:
       input=name [required]
           Name of input elevation raster map

       output=name [required]
           Name for output raster map

       coordinates=east,north [required]
           Coordinates of viewing position

       observer_elevation=value
           Viewing elevation above the ground
           Default: 1.75

       target_elevation=value
           Offset for target elevation above the ground
           Default: 0.0

       max_distance=value
           Maximum visibility radius. By default infinity (-1)
           Default: -1

       refraction_coeff=float
           Refraction coefficient
           Options: 0.0-1.0
           Default: 0.14286

       memory=value
           Amount of memory to use in MB
           Default: 500

       directory=string
           Directory to hold temporary files (they can be large)

DESCRIPTION

       r.viewshed  is  a  module  that  computes  the viewshed of a point on a raster terrain. That is, given an
       elevation raster, and the location of an observer, it generates a raster output map showing  which  cells
       are  visible  from  the  given  location.   The  algorithm  underlying  r.viewshed minimizes both the CPU
       operations and the transfer of data between main memory and disk; as a result  r.viewshed  runs  fast  on
       very large rasters.

NOTES

       To  run r.viewshed, the user must specify an input elevation map name, an output raster map name, and the
       location of the viewpoint.

       For the time being the viewpoint (coordinates parameter) is assumed to be  located  inside  the  terrain.
       The viewpoint location is given in map coordinates.

       The output raster map may have one of three possible formats, based on which flags are set.

       By default, if no flag is set, the output is in angle-mode, and each point in the output map is marked as
       NULL if the point is not visible or the respective point in the elevation  map  is  NULL.   Otherwise,  a
       value  in [0, 180] representing the vertical angle with regard to the viewpoint, in degrees, if the point
       is visible.  A value of 0 is directly below the specified viewing position, 90  is  due  horizontal.  The
       angle to the cell containing the viewing position is undefined and set to 180.

       If the -b flag is set, the output is in boolean-mode, and each point in the output map is marked as:

           •   0 if the point is no-data/null or not visible

           •   1 if the point is visible.

       If the -e flag is set, the output is in elevation-mode, and each point in the output map is marked as:

           •   no-data (null), if the respective point in the elevation map is no-data (null)

           •   -1, if the point is not visible

           •   the difference in elevation between the point and the viewpoint, if the point is visible.

       If  you  wish  to  identify  the  area  of  the  map which is within the search radius but not visible, a
       combination of r.buffer and r.mapcalc can be used to create a negative of the viewshed map.

       By default the elevations are not adjusted for the curvature of the earth. The user can turn this on with
       flag -c.

       By  default the observer is assumed to have height 1.75 map units above the terrain.  The user can change
       this using option observer_elevation. The value entered is in the same units as the elevation.

       By default the target is assumed to have height of 0 map units above the terrain.  The  user  can  change
       this  using option target_elevation to determine if objects of a given height would be visible. The value
       entered is in the same units as the elevation.

       By default there is no restriction on the maximum distance to which the observer can see.  The  user  can
       set  a  maximum distance of visibility using option max_distance.  The value entered is in the same units
       as the cell size of the raster.

       Main memory usage: By default r.viewshed assumes it has 500MB of main memory, and sets  up  its  internal
       data structures so that it does not require more than this amount of RAM.  The user can set the amount of
       memory used by the program by setting the memory to the number of MB of memory  they  would  like  to  be
       used.

   Memory mode
       The  algorithm  can  run  in  two modes: in internal memory, which means that it keeps all necessary data
       structures in memory during the computation. And in external memory, which means that the data structures
       are  external,  i.e.  on  disk.   r.viewshed decides which mode to run in using the amount of main memory
       specified by the user.  The internal mode is (much) faster than the external mode.

       Ideally, the user should specify on the command line the amount of physical memory that is free  for  the
       program  to  use. Underestimating the memory may result in r.viewshed running in external mode instead of
       internal, which is slower. Overestimating the amount of free memory may result in r.viewshed  running  in
       internal mode and using virtual memory, which is slower than the external mode.

   The algorithm
       r.viewshed  uses  the  following  model for determining visibility: The height of a cell is assumed to be
       variable, and the actual height of a point falling into a cell, but not identical  the  cell  center,  is
       interpolated.  Thus  the  terrain is viewed as a smooth surface.  Two points are visible to each other if
       their line-of-sight does not intersect the terrain. The height for an arbitrary point x in the terrain is
       interpolated  from the 4 surrounding neighbours. This means that this model does a bilinear interpolation
       of heights.  This model is suitable for both low and high resolution rasters as well as terrain with flat
       and steep slopes.

       The core of the algorithm is determining, for each cell, the line-of-sight and its intersections with the
       cells in the terrain. For a (square) grid of n cells, there can be O(n 1/2) cells that intersect the LOS.
       If  we  test every single such cell for every point in the grid, this adds up to O(n3/2) tests. We can do
       all these tests faster if we re-use information from one point to the next  (two  grid  points  that  are
       close  to  each  other  will  be  intersected  by  a lot of the same points) and organize the computation
       differently.

       More precisely, the algorithm uses a technique called line sweeping: It considers a half-line centered at
       the  viewpoint,  and  rotates  it  radially around the viewpoint, 360 degrees.  During the sweep it keeps
       track of all the cells that intersect the sweep line at that time; These are called the active  cells.  A
       cell  has  3  associated  events:  when  it  is  first met by the sweep line and inserted into the active
       structure; when it is last met by the sweep line and deleted from the  active  structure;  and  when  the
       sweep  line  passes  over  its centerpoint, at which time its visibility is determined.  To determine the
       visibility of a cell all cells that intersect the line-of-sight must be active, so they are in the active
       structure.  The algorithm looks at all the active cells that are between the point and the viewpoint, and
       finds the maximum gradient among these.  If the cell’s gradient is  higher,  it  is  marked  as  visible,
       whereas if it is lower, it is marked as invisible.

       For  a  (square)  raster  of n point in total, the standard viewshed algorithm uses O(n sqrt(n))= O(n3/2)
       time, while the sweep-line algorithm uses O(n lg n) time.  This algorithm is efficient in  terms  of  CPU
       operations and can be also made efficient in terms of I/O-operations.  For all details see the REFERENCES
       below.

       The sweep-line.                                              The active cells.

EXAMPLES

       Using the North Carolina dataset:  Compute viewshed from a observation point (coordinates: 638728.087167,
       220609.261501) which is 5 meters above ground:
       g.region raster=elev_lid792_1m -p
       r.viewshed input=elev_lid792_1m output=elev_lid792_1m_viewshed coordinates=638728,220609 observer_elevation=5.0
       Viewshed  shown  on shaded terrain (observer position in the north-east quadrant with white dot; 5m above
       ground) Using the Spearfish dataset:  calculating the viewpoint from top of a mountain:
       g.region raster=elevation.10m
       r.viewshed input=elevation.10m output=viewshed coordinates=598869,4916642 memory=800

REFERENCES

           •   Computing Visibility on Terrains in External Memory. Herman Haverkort, Laura Toma and Yi  Zhuang.
               In ACM Journal on Experimental Algorithmics (JEA) 13 (2009).

           •   Computing  Visibility on Terrains in External Memory. Herman Haverkort, Laura Toma and Yi Zhuang.
               In the Proceedings of the 9th Workshop on Algorithm Engineering and  Experiments  /  Workshop  on
               Analytic Algorithms and Combinatorics (ALENEX/ANALCO 2007).

SEE ALSO

        r.mapcalc

AUTHORS

       Laura Toma (Bowdoin College): ltoma@bowdoin.edu

       Yi Zhuang (Carnegie-Mellon University): yzhuang@andrew.cmu.edu

       William Richard (Bowdoin College): willster3021@gmail.com

       Markus Metz

SOURCE CODE

       Available at: r.viewshed source code (history)

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

       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual