1GDAL_VIEWSHED(1)                     GDAL                     GDAL_VIEWSHED(1)
2
3
4

NAME

6       gdal_viewshed  -  Calculates a viewshed raster from an input raster DEM
7       for a user defined point
8

SYNOPSIS

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

DESCRIPTION

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
26       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
31       -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
37              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
45       -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
51       -a_nodata <value>
52              The value to be set for the cells in the output raster that have
53              no data.
54
55              NOTE:
56                 Currently, no special processing of input cells at  a  nodata
57                 value is done (which may result in erroneous results).
58
59       -ox <value>
60              The X position of the observer (in SRS units).
61
62       -oy <value>
63              The Y position of the observer (in SRS units).
64
65       -oz <value>
66              The  height  of the observer above the DEM surface in the height
67              unit of the DEM. Default: 2
68
69       -tz <value>
70              The height of the target above the DEM  surface  in  the  height
71              unit of the DEM. Default: 0
72
73       -md <value>
74              Maximum distance from observer to compute visibiliy.  It is also
75              used to clamp the extent of the output raster.
76
77       -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
83              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
88                              {CurvCoeff}=1-{RefractionCoeff}
89
90              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
96                {SphereDiameterFactor}=1/{CurvCoeff}=1/(1-{RefractionCoeff})
97
98
99
100              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
108              The height of the DEM is corrected according  to  the  following
109              formula:
110
111              Height_{Corrected}=Height_{DEM}-{CurvCoeff}\frac{{TargetDistance}^2}{SphereDiameter}
112
113              Typical  coefficient  values  are  given in the table below (use
114              Curvature Coeff value for the cc option)
115
116           ┌──────────────┬──────────────────┬─────────────────┬──────────────────┐
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
129       -iv <value>
130              Pixel value to set for invisible areas. Default: 0
131
132       -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
137       -vv <value>
138              Pixel value to set for visible areas. Default: 255
139
140       -om <output mode>
141              Sets what information the output contains.
142
143              Possible values: NORMAL, DEM, GROUND
144
145              NORMAL  returns  a  raster of type Byte containing visible loca‐
146              tions.
147
148              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
153              Default NORMAL
154

C API

156       Functionality   of   this   utility   can   be   done   from   C   with
157       GDALViewshedGenerate().
158

EXAMPLE

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
164          gdal_viewshed -md 500 -ox -10147017 -oy 5108065 source.tif destination.tif
165
166       [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

AUTHOR

173       Tamas Szekeres <szekerest@gmail.com>
174
176       1998-2023
177
178
179
180
181                                 Oct 30, 2023                 GDAL_VIEWSHED(1)
Impressum