1GDAL_VIEWSHED(1) GDAL GDAL_VIEWSHED(1)
2
6 gdal_viewshed - Calculates a viewshed raster from an input raster DEM
7 for a user defined point
8
10 gdal_viewshed [-b <band>]
11 [-a_nodata <value>] [-f <formatname>]
12 [-oz <observer_height>] [-tz <target_height>] [-md <max_distance>]
13 -ox <observer_x> -oy <observer_y>
14 [-vv <visibility>] [-iv <invisibility>]
15 [-ov <out_of_range>] [-cc <curvature_coef>]
16 [[-co NAME=VALUE] ...]
17 [-q] [-om <output mode>]
18 <src_filename> <dst_filename>
19
21 By default the gdal_viewshed generates a binary visibility raster from
22 one band of the input raster elevation model (DEM). The output raster
23 will be of type Byte. With the -mode flag can also return a minimum
24 visible height raster of type Float64.
25 NOTE:
27 The algorithm as implemented currently will only output meaningful
28 results if the georeferencing is in a projected coordinate reference
29 system.
30 -co <NAME=VALUE>
32 Many formats have one or more optional creation options that can
33 be used to control particulars about the file created. For in‐
34 stance, the GeoTIFF driver supports creation options to control
35 compression, and whether the file should be tiled.
36 The creation options available vary by format driver, and some
38 simple formats have no creation options at all. A list of op‐
39 tions supported for a format can be listed with the --formats
40 command line option but the documentation for the format is the
41 definitive source of information on driver creation options.
42 See Raster drivers format specific documentation for legal cre‐
43 ation options for each format.
44 -b <band>
46 Select an input band band containing the DEM data. Bands are
47 numbered from 1. Only a single band can be used. Only the part
48 of the raster within the specified maximum distance around the
49 observer point is processed.
50 -a_nodata <value>
52 The value to be set for the cells in the output raster that have
53 no data.
54 NOTE:
56 Currently, no special processing of input cells at a nodata
57 value is done (which may result in erroneous results).
58 -ox <value>
60 The X position of the observer (in SRS units).
61 -oy <value>
63 The Y position of the observer (in SRS units).
64 -oz <value>
66 The height of the observer above the DEM surface in the height
67 unit of the DEM. Default: 2
68 -tz <value>
70 The height of the target above the DEM surface in the height
71 unit of the DEM. Default: 0
72 -md <value>
74 Maximum distance from observer to compute visibiliy. It is also
75 used to clamp the extent of the output raster.
76 -cc <value>
78 Coefficient to consider the effect of the curvature and refrac‐
79 tion. When calculating visibility between two points (i.e. Line
80 Of Sight or Viewshed), The magnitude of this effect varies with
81 atmospheric conditions and depends on the wavelength.
82 Different applications for calculating visibility use different
84 interchangeable notation to describe this phenomena: Refraction
85 Coefficient, Curvature Coefficient, and Sphere Diameter Factor.
86 gdal_viewshed uses the Curvature Coefficient notation.
87 {CurvCoeff}=1-{RefractionCoeff}
89 Changes in air density curve the light downward causing an ob‐
91 server to see further and the earth to appear less curved, as if
92 the sphere (earth) diameter is larger then it actually is. The
93 ratio between that imaginary sphere diameter and the actual
94 sphere diameter is given by the formula:
95 {SphereDiameterFactor}=1/{CurvCoeff}=1/(1-{RefractionCoeff})
97 For visible light, the standard atmospheric refraction coeffi‐
101 cient that is generally used is 1/7. Thus the default value
102 (since GDAL 3.4) for CurvCoeff that gdal_viewshed uses is
103 0.85714 (=~ 1-1/7) for Earth CRS. Starting with GDAL 3.6, for
104 non-Earth CRS (those whole semi-major axis differs by more than
105 5% with the one of WGS 84), CurvCoeff default value is 1.0, to
106 account for the no refraction use case.
107 The height of the DEM is corrected according to the following
109 formula:
110 Height_{Corrected}=Height_{DEM}-{CurvCoeff}\frac{{TargetDistance}^2}{SphereDiameter}
112 Typical coefficient values are given in the table below (use
114 Curvature Coeff value for the cc option)
115 ┌──────────────┬──────────────────┬─────────────────┬──────────────────┐
117 │Use Case │ Refraction Coeff │ Curvature Coeff │ Sphere Diameter │
118 │ │ │ │ Factor │
119 ├──────────────┼──────────────────┼─────────────────┼──────────────────┤
120 │No Refraction │ 0 │ 1 │ 1 │
121 ├──────────────┼──────────────────┼─────────────────┼──────────────────┤
122 │Visible Light │ 1/7 │ 6/7 (=~0.85714) │ 7/6 (=~1.1666) │
123 ├──────────────┼──────────────────┼─────────────────┼──────────────────┤
124 │Radio Waves │ 0.25 ~ 0.325 │ 0.75 ~ 0.675 │ 1.33 ~ 1.48 │
125 ├──────────────┼──────────────────┼─────────────────┼──────────────────┤
126 │Flat Earth │ 1 │ 0 │ inf │
127 └──────────────┴──────────────────┴─────────────────┴──────────────────┘
128 -iv <value>
130 Pixel value to set for invisible areas. Default: 0
131 -ov <value>
133 Pixel value to set for the cells that fall outside of the range
134 specified by the observer location and the maximum distance. De‐
135 fault: 0
136 -vv <value>
138 Pixel value to set for visible areas. Default: 255
139 -om <output mode>
141 Sets what information the output contains.
142 Possible values: NORMAL, DEM, GROUND
144 NORMAL returns a raster of type Byte containing visible loca‐
146 tions.
147 DEM and GROUND will return a raster of type Float64 containing
149 the minimum target height for target to be visible from the DEM
150 surface or ground level respectively. Flags -tz, -iv and -vv
151 will be ignored.
152 Default NORMAL
154
156 Functionality of this utility can be done from C with
157 GDALViewshedGenerate().
158
160 Compute the visibility of an elevation raster data source with defaults
161 [image] A computed visibility for two separate -ox and -oy points on
162 a DEM..UNINDENT
163 gdal_viewshed -md 500 -ox -10147017 -oy 5108065 source.tif destination.tif
165 [Wang2000]
167 Generating Viewsheds without Using Sightlines. Wang, Jianjun,
168 Robinson, Gary J., and White, Kevin. Photogrammetric Engineering
169 and Remote Sensing. p81.
170 https://www.asprs.org/wp-content/uploads/pers/2000journal/january/2000_jan_87-90.pdf
171
173 Tamas Szekeres <szekerest@gmail.com>
174
176 1998-2023
177 Oct 30, 2023 GDAL_VIEWSHED(1)