Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
r.viewshed(1)		    GRASS GIS User's Manual		 r.viewshed(1)

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

       raster, viewshed, line of sight,	LOS

       r.viewshed --help
       r.viewshed  [-crbe] input=name output=name coordinates=east,north  [ob-
       server_elevation=value]	     [target_elevation=value]	     [max_dis-
       tance=value]	[refraction_coeff=float]     [memory=value]    [direc-
       tory=string]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

	   Consider the	curvature of the earth (current	ellipsoid)

	   Consider the	effect of atmospheric refraction

	   Output format is invisible =	0, visible = 1

	   Output format is invisible  =  NULL,	 else  current	elev  -	 view-

	   Allow output	files to overwrite existing files

	   Print usage summary

	   Verbose module output

	   Quiet module	output

	   Force launching GUI dialog

       input=nameA [required]
	   Name	of input elevation raster map

       output=nameA [required]
	   Name	for output raster map

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

	   Viewing elevation above the ground
	   Default: 1.75

	   Offset for target elevation above the ground
	   Default: 0.0

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

	   Refraction coefficient
	   Options: 0.0-1.0
	   Default: 0.14286

	   Amount of memory to use in MB
	   Default: 500

	   Directory to	hold temporary files (they can be large)

       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

       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

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

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

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

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

	   o   -1, if the point	is not visible

	   o   the  difference	in  elevation  between the point and the view-
	       point, 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 en-
       tered 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	compu-
       tation.	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	inter-
       polated.	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 interpo-
       lated  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	 radi-
       ally  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	struc-
       ture; 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 ac-
       tive 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	 algo-
       rithm  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 oper-
       ations  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.

       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

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

	   o   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  /	 Work-
	       shop  on	 Analytic  Algorithms and Combinatorics	(ALENEX/ANALCO


       Laura Toma (Bowdoin College):

       Yi Zhuang (Carnegie-Mellon University):

       William Richard (Bowdoin	College):

       Markus Metz

       Available at: r.viewshed	source code (history)

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

       A(C) 2003-2020 GRASS Development	Team, GRASS GIS	7.8.4 Reference	Manual

GRASS 7.8.4							 r.viewshed(1)


Want to link to this manual page? Use this URL:

home | help