1r.viewshed(1)                 Grass User's Manual                r.viewshed(1)
2
3
4

NAME

6       r.viewshed   -  Computes the viewshed of a point on an elevation raster
7       map.
8       Default format: NULL (invisible), vertical angle wrt  viewpoint  (visi‐
9       ble).
10

KEYWORDS

12       raster, viewshed, line of sight, LOS
13

SYNOPSIS

15       r.viewshed
16       r.viewshed --help
17       r.viewshed   [-crbe]   input=name   output=name  coordinates=east,north
18       [observer_elevation=value]      [target_elevation=value]      [max_dis‐
19       tance=value]     [refraction_coeff=float]     [memory=value]    [direc‐
20       tory=string]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]
21
22   Flags:
23       -c
24           Consider the curvature of the earth (current ellipsoid)
25
26       -r
27           Consider the effect of atmospheric refraction
28
29       -b
30           Output format is invisible = 0, visible = 1
31
32       -e
33           Output format is invisible  =  NULL,  else  current  elev  -  view‐
34           point_elev
35
36       --overwrite
37           Allow output files to overwrite existing files
38
39       --help
40           Print usage summary
41
42       --verbose
43           Verbose module output
44
45       --quiet
46           Quiet module output
47
48       --ui
49           Force launching GUI dialog
50
51   Parameters:
52       input=name [required]
53           Name of input elevation raster map
54
55       output=name [required]
56           Name for output raster map
57
58       coordinates=east,north [required]
59           Coordinates of viewing position
60
61       observer_elevation=value
62           Viewing elevation above the ground
63           Default: 1.75
64
65       target_elevation=value
66           Offset for target elevation above the ground
67           Default: 0.0
68
69       max_distance=value
70           Maximum visibility radius. By default infinity (-1)
71           Default: -1
72
73       refraction_coeff=float
74           Refraction coefficient
75           Options: 0.0-1.0
76           Default: 0.14286
77
78       memory=value
79           Amount of memory to use in MB
80           Default: 500
81
82       directory=string
83           Directory to hold temporary files (they can be large)
84

DESCRIPTION

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

NOTES

95       To  run  r.viewshed, the user must specify an input elevation map name,
96       an output raster map name, and the location of the viewpoint.
97
98       For the time being the viewpoint (coordinates parameter) is assumed  to
99       be  located inside the terrain.  The viewpoint location is given in map
100       coordinates.
101
102       The output raster map may have one of three possible formats, based  on
103       which flags are set.
104
105       By  default,  if  no flag is set, the output is in angle-mode, and each
106       point in the output map is marked as NULL if the point is  not  visible
107       or  the  respective  point  in the elevation map is NULL.  Otherwise, a
108       value in [0, 180] representing the vertical angle with  regard  to  the
109       viewpoint,  in  degrees,  if  the  point  is  visible.  A value of 0 is
110       directly below the specified viewing position, 90  is  due  horizontal.
111       The  angle to the cell containing the viewing position is undefined and
112       set to 180.
113
114       If the -b flag is set, the output is in boolean-mode, and each point in
115       the output map is marked as:
116
117           ·   0 if the point is no-data/null or not visible
118
119           ·   1 if the point is visible.
120
121       If  the -e flag is set, the output is in elevation-mode, and each point
122       in the output map is marked as:
123
124           ·   no-data (null), if the respective point in the elevation map is
125               no-data (null)
126
127           ·   -1, if the point is not visible
128
129           ·   the  difference  in  elevation  between the point and the view‐
130               point, if the point is visible.
131
132       If you wish to identify the area of the map which is within the  search
133       radius  but not visible, a combination of r.buffer and r.mapcalc can be
134       used to create a negative of the viewshed map.
135
136       By default the elevations are not adjusted for  the  curvature  of  the
137       earth. The user can turn this on with flag -c.
138
139       By  default the observer is assumed to have height 1.75 map units above
140       the terrain.  The user can change this using option observer_elevation.
141       The value entered is in the same units as the elevation.
142
143       By  default  the  target is assumed to have height of 0 map units above
144       the terrain.  The user can change this using option target_elevation to
145       determine  if  objects  of  a  given height would be visible. The value
146       entered is in the same units as the elevation.
147
148       By default there is no restriction on the maximum distance to which the
149       observer  can  see.   The user can set a maximum distance of visibility
150       using option max_distance.  The value entered is in the same  units  as
151       the cell size of the raster.
152
153       Main  memory  usage: By default r.viewshed assumes it has 500MB of main
154       memory, and sets up its internal data structures so that  it  does  not
155       require  more  than this amount of RAM.  The user can set the amount of
156       memory used by the program by setting the memory to the number of MB of
157       memory they would like to be used.
158
159   Memory mode
160       The  algorithm  can  run  in two modes: in internal memory, which means
161       that it keeps all necessary data structures in memory during the compu‐
162       tation.  And  in  external memory, which means that the data structures
163       are external, i.e. on disk.  r.viewshed decides which mode  to  run  in
164       using  the  amount  of main memory specified by the user.  The internal
165       mode is (much) faster than the external mode.
166
167       Ideally, the user should specify on the  command  line  the  amount  of
168       physical  memory  that  is free for the program to use. Underestimating
169       the memory may result in r.viewshed running in external mode instead of
170       internal, which is slower. Overestimating the amount of free memory may
171       result in r.viewshed running in internal mode and using virtual memory,
172       which is slower than the external mode.
173
174   The algorithm
175       r.viewshed  uses  the  following  model for determining visibility: The
176       height of a cell is assumed to be variable, and the actual height of  a
177       point falling into a cell, but not identical the cell center, is inter‐
178       polated. Thus the terrain is viewed as a smooth  surface.   Two  points
179       are visible to each other if their line-of-sight does not intersect the
180       terrain. The height for an arbitrary point x in the terrain is interpo‐
181       lated  from  the  4  surrounding neighbours. This means that this model
182       does a bilinear interpolation of heights.  This model is  suitable  for
183       both  low  and high resolution rasters as well as terrain with flat and
184       steep slopes.
185
186       The  core  of  the  algorithm  is  determining,  for  each  cell,   the
187       line-of-sight  and its intersections with the cells in the terrain. For
188       a (square) grid of n cells, there can be O(n 1/2) cells that  intersect
189       the LOS. If we test every single such cell for every point in the grid,
190       this adds up to O(n3/2) tests. We can do all these tests faster  if  we
191       re-use information from one point to the next (two grid points that are
192       close to each other will be intersected by a lot of  the  same  points)
193       and organize the computation differently.
194
195       More precisely, the algorithm uses a technique called line sweeping: It
196       considers a half-line centered at the viewpoint, and rotates  it  radi‐
197       ally  around  the  viewpoint,  360  degrees.  During the sweep it keeps
198       track of all the cells that intersect the  sweep  line  at  that  time;
199       These are called the active cells. A cell has 3 associated events: when
200       it is first met by the sweep line and inserted into the  active  struc‐
201       ture; when it is last met by the sweep line and deleted from the active
202       structure; and when the sweep line  passes  over  its  centerpoint,  at
203       which  time  its visibility is determined.  To determine the visibility
204       of a cell all cells that intersect the line-of-sight must be active, so
205       they  are  in  the  active  structure.   The algorithm looks at all the
206       active cells that are between the point and the  viewpoint,  and  finds
207       the maximum gradient among these.  If the cell’s gradient is higher, it
208       is marked as visible, whereas if it is lower, it is marked  as  invisi‐
209       ble.
210
211       For  a (square) raster of n point in total, the standard viewshed algo‐
212       rithm uses O(n sqrt(n))= O(n3/2) time, while the  sweep-line  algorithm
213       uses O(n lg n) time.  This algorithm is efficient in terms of CPU oper‐
214       ations and can be also made efficient in terms of I/O-operations.   For
215       all details see the REFERENCES below.
216
217
218
219       The sweep-line.                                              The active cells.
220
221

EXAMPLES

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

REFERENCES

235           ·   Computing  Visibility  on  Terrains  in External Memory. Herman
236               Haverkort, Laura Toma and Yi Zhuang. In ACM Journal on  Experi‐
237               mental Algorithmics (JEA) 13 (2009).
238
239           ·   Computing  Visibility  on  Terrains  in External Memory. Herman
240               Haverkort, Laura Toma and Yi Zhuang. In the Proceedings of  the
241               9th  Workshop  on Algorithm Engineering and Experiments / Work‐
242               shop on Analytic Algorithms  and  Combinatorics  (ALENEX/ANALCO
243               2007).
244

SEE ALSO

246        r.mapcalc
247

AUTHORS

249       Laura Toma (Bowdoin College): ltoma@bowdoin.edu
250
251       Yi Zhuang (Carnegie-Mellon University): yzhuang@andrew.cmu.edu
252
253       William Richard (Bowdoin College): willster3021@gmail.com
254
255       Markus Metz
256

SOURCE CODE

258       Available at: r.viewshed source code (history)
259
260       Main  index  | Raster index | Topics index | Keywords index | Graphical
261       index | Full index
262
263       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
264
265
266
267GRASS 7.8.2                                                      r.viewshed(1)
Impressum