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
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 Flags:
23 -c
24 Consider the curvature of the earth (current ellipsoid)
25 -r
27 Consider the effect of atmospheric refraction
28 -b
30 Output format is invisible = 0, visible = 1
31 -e
33 Output format is invisible = NULL, else current elev - view‐
34 point_elev
35 --overwrite
37 Allow output files to overwrite existing files
38 --help
40 Print usage summary
41 --verbose
43 Verbose module output
44 --quiet
46 Quiet module output
47 --ui
49 Force launching GUI dialog
50 Parameters:
52 input=name [required]
53 Name of input elevation raster map
54 output=name [required]
56 Name for output raster map
57 coordinates=east,north [required]
59 Coordinates of viewing position
60 observer_elevation=value
62 Viewing elevation above the ground
63 Default: 1.75
64 target_elevation=value
66 Offset for target elevation above the ground
67 Default: 0.0
68 max_distance=value
70 Maximum visibility radius. By default infinity (-1)
71 Default: -1
72 refraction_coeff=float
74 Refraction coefficient
75 Options: 0.0-1.0
76 Default: 0.14286
77 memory=value
79 Amount of memory to use in MB
80 Default: 500
81 directory=string
83 Directory to hold temporary files (they can be large)
84
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
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 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 The output raster map may have one of three possible formats, based on
103 which flags are set.
104 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 If the -b flag is set, the output is in boolean-mode, and each point in
115 the output map is marked as:
116 · 0 if the point is no-data/null or not visible
118 · 1 if the point is visible.
120 If the -e flag is set, the output is in elevation-mode, and each point
122 in the output map is marked as:
123 · no-data (null), if the respective point in the elevation map is
125 no-data (null)
126 · -1, if the point is not visible
128 · the difference in elevation between the point and the view‐
130 point, if the point is visible.
131 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 By default the elevations are not adjusted for the curvature of the
137 earth. The user can turn this on with flag -c.
138 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 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 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 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 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 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 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 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 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 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 The sweep-line. The active cells.
220
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
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 · 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
246 r.mapcalc
247
249 Laura Toma (Bowdoin College): ltoma@bowdoin.edu
250 Yi Zhuang (Carnegie-Mellon University): yzhuang@andrew.cmu.edu
252 William Richard (Bowdoin College): willster3021@gmail.com
254 Markus Metz
256
258 Available at: r.viewshed source code (history)
259 Main index | Raster index | Topics index | Keywords index | Graphical
261 index | Full index
262 © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
264GRASS 7.8.5 r.viewshed(1)