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

DESCRIPTION

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

NOTES

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

EXAMPLES

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

REFERENCES

246           •   Computing Visibility on Terrains  in  External  Memory.  Herman
247               Haverkort,  Laura Toma and Yi Zhuang. In ACM Journal on Experi‐
248               mental Algorithmics (JEA) 13 (2009).
249
250           •   Computing Visibility on Terrains  in  External  Memory.  Herman
251               Haverkort,  Laura Toma and Yi Zhuang. In the Proceedings of the
252               9th Workshop on Algorithm Engineering and Experiments  /  Work‐
253               shop  on  Analytic  Algorithms and Combinatorics (ALENEX/ANALCO
254               2007).
255

SEE ALSO

257        r.mapcalc
258

AUTHORS

260       Laura Toma (Bowdoin College): ltoma@bowdoin.edu
261
262       Yi Zhuang (Carnegie-Mellon University): yzhuang@andrew.cmu.edu
263
264       William Richard (Bowdoin College): willster3021@gmail.com
265
266       Markus Metz
267

SOURCE CODE

269       Available at: r.viewshed source code (history)
270
271       Accessed: Saturday Jan 21 20:39:27 2023
272
273       Main index | Raster index | Topics index | Keywords index  |  Graphical
274       index | Full index
275
276       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
277
278
279
280GRASS 8.2.1                                                      r.viewshed(1)
Impressum