1r.viewshed(1) GRASS GIS User's Manual r.viewshed(1)
2
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
12 raster, viewshed, line of sight, LOS
13
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 Flags:
24 -c
25 Consider the curvature of the earth (current ellipsoid)
26 -r
28 Consider the effect of atmospheric refraction
29 -b
31 Output format is invisible = 0, visible = 1
32 -e
34 Output format is invisible = NULL, else current elev - view‐
35 point_elev
36 --overwrite
38 Allow output files to overwrite existing files
39 --help
41 Print usage summary
42 --verbose
44 Verbose module output
45 --quiet
47 Quiet module output
48 --ui
50 Force launching GUI dialog
51 Parameters:
53 input=name [required]
54 Name of input elevation raster map
55 output=name [required]
57 Name for output raster map
58 coordinates=east,north [required]
60 Coordinates of viewing position
61 observer_elevation=value
63 Viewing elevation above the ground
64 Default: 1.75
65 target_elevation=value
67 Offset for target elevation above the ground
68 Default: 0.0
69 max_distance=value
71 Maximum visibility radius. By default infinity (-1)
72 Default: -1
73 direction_range=min,max
75 Minimum and maximum horizontal angle limiting viewshed (0 is East,
76 counterclockwise)
77 Options: 0-360
78 refraction_coeff=float
80 Refraction coefficient
81 Options: 0.0-1.0
82 Default: 0.14286
83 memory=value
85 Amount of memory to use in MB
86 Default: 500
87 directory=string
89 Directory to hold temporary files (they can be large)
90
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
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 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 The output raster map may have one of three possible formats, based on
109 which flags are set.
110 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 If the -b flag is set, the output is in boolean-mode, and each point in
121 the output map is marked as:
122 • 0 if the point is no-data/null or not visible
124 • 1 if the point is visible.
126 If the -e flag is set, the output is in elevation-mode, and each point
128 in the output map is marked as:
129 • no-data (null), if the respective point in the elevation map is
131 no-data (null)
132 • -1, if the point is not visible
134 • the difference in elevation between the point and the view‐
136 point, if the point is visible.
137 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 By default the elevations are not adjusted for the curvature of the
143 earth. The user can turn this on with flag -c.
144 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 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 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 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 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 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 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 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 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 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 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 The sweep-line. The active cells.
231
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
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 • 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
257 r.mapcalc
258
260 Laura Toma (Bowdoin College): ltoma@bowdoin.edu
261 Yi Zhuang (Carnegie-Mellon University): yzhuang@andrew.cmu.edu
263 William Richard (Bowdoin College): willster3021@gmail.com
265 Markus Metz
267
269 Available at: r.viewshed source code (history)
270 Accessed: Saturday Jan 21 20:39:27 2023
272 Main index | Raster index | Topics index | Keywords index | Graphical
274 index | Full index
275 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
277GRASS 8.2.1 r.viewshed(1)