Provided by: gdal-bin_3.9.3+dfsg-1build1_amd64 
NAME
gdal_viewshed - Calculates a viewshed raster from an input raster DEM for a user defined
point
SYNOPSIS
gdal_viewshed [--help] [--help-general] [-b <band>]
[-a_nodata <value>] [-f <formatname>]
[-oz <observer_height>] [-tz <target_height>] [-md <max_distance>]
-ox <observer_x> -oy <observer_y>
[-vv <visibility>] [-iv <invisibility>]
[-ov <out_of_range>] [-cc <curvature_coef>]
[-co <NAME>=<VALUE>]...
[-q] [-om <output mode>]
<src_filename> <dst_filename>
DESCRIPTION
By default the gdal_viewshed generates a binary visibility raster from one band of the
input raster elevation model (DEM). The output raster will be of type Byte. With the -mode
flag can also return a minimum visible height raster of type Float64.
NOTE:
The algorithm as implemented currently will only output meaningful results if the
georeferencing is in a projected coordinate reference system.
--help Show this help message and exit
--help-general
Gives a brief usage message for the generic GDAL commandline options and exit.
-co <NAME>=<VALUE>
Many formats have one or more optional creation options that can be used to control
particulars about the file created. For instance, the GeoTIFF driver supports
creation options to control compression, and whether the file should be tiled.
The creation options available vary by format driver, and some simple formats have
no creation options at all. A list of options supported for a format can be listed
with the --formats command line option but the documentation for the format is the
definitive source of information on driver creation options. See Raster drivers
format specific documentation for legal creation options for each format.
-b <band>
Select an input band band containing the DEM data. Bands are numbered from 1. Only
a single band can be used. Only the part of the raster within the specified maximum
distance around the observer point is processed.
-a_nodata <value>
The value to be set for the cells in the output raster that have no data.
NOTE:
Currently, no special processing of input cells at a nodata value is done (which
may result in erroneous results).
-ox <value>
The X position of the observer (in SRS units).
-oy <value>
The Y position of the observer (in SRS units).
-oz <value>
The height of the observer above the DEM surface in the height unit of the DEM.
Default: 2
-tz <value>
The height of the target above the DEM surface in the height unit of the DEM.
Default: 0
-md <value>
Maximum distance from observer to compute visibiliy. It is also used to clamp the
extent of the output raster.
-cc <value>
Coefficient to consider the effect of the curvature and refraction. When
calculating visibility between two points (i.e. Line Of Sight or Viewshed), The
magnitude of this effect varies with atmospheric conditions and depends on the
wavelength.
Different applications for calculating visibility use different interchangeable
notation to describe this phenomena: Refraction Coefficient, Curvature Coefficient,
and Sphere Diameter Factor. gdal_viewshed uses the Curvature Coefficient notation.
{CurvCoeff}=1-{RefractionCoeff}
Changes in air density curve the light downward causing an observer to see further
and the earth to appear less curved, as if the sphere (earth) diameter is larger
then it actually is. The ratio between that imaginary sphere diameter and the
actual sphere diameter is given by the formula:
{SphereDiameterFactor}=1/{CurvCoeff}=1/(1-{RefractionCoeff})
For visible light, the standard atmospheric refraction coefficient that is
generally used is 1/7. Thus the default value (since GDAL 3.4) for CurvCoeff that
gdal_viewshed uses is 0.85714 (=~ 1-1/7) for Earth CRS. Starting with GDAL 3.6, for
non-Earth CRS (those whole semi-major axis differs by more than 5% with the one of
WGS 84), CurvCoeff default value is 1.0, to account for the no refraction use case.
The height of the DEM is corrected according to the following formula:
Height_{Corrected}=Height_{DEM}-{CurvCoeff}\frac{{TargetDistance}^2}{SphereDiameter}
Typical coefficient values are given in the table below (use Curvature Coeff value
for the cc option)
┌──────────────┬──────────────────┬─────────────────┬─────────────────────┐
│Use Case │ Refraction Coeff │ Curvature Coeff │ Sphere Diameter │
│ │ │ │ Factor │
├──────────────┼──────────────────┼─────────────────┼─────────────────────┤
│No Refraction │ 0 │ 1 │ 1 │
├──────────────┼──────────────────┼─────────────────┼─────────────────────┤
│Visible Light │ 1/7 │ 6/7 (=~0.85714) │ 7/6 (=~1.1666) │
├──────────────┼──────────────────┼─────────────────┼─────────────────────┤
│Radio Waves │ 0.25 ~ 0.325 │ 0.75 ~ 0.675 │ 1.33 ~ 1.48 │
├──────────────┼──────────────────┼─────────────────┼─────────────────────┤
│Flat Earth │ 1 │ 0 │ inf │
└──────────────┴──────────────────┴─────────────────┴─────────────────────┘
-iv <value>
Pixel value to set for invisible areas. Default: 0
-ov <value>
Pixel value to set for the cells that fall outside of the range specified by the
observer location and the maximum distance. Default: 0
-vv <value>
Pixel value to set for visible areas. Default: 255
-om <output mode>
Sets what information the output contains.
Possible values: NORMAL, DEM, GROUND
NORMAL returns a raster of type Byte containing visible locations.
DEM and GROUND will return a raster of type Float64 containing the minimum target
height for target to be visible from the DEM surface or ground level respectively.
Flags -tz, -iv and -vv will be ignored.
Default NORMAL
C API
Functionality of this utility can be done from C with GDALViewshedGenerate().
EXAMPLE
Screenshot of 2 combined viewshed analysis, with the yellow pixels showing the area that
is visible from the both observation locations (the green dots), while the small green
area is only visible from one location.
[image]
Create a viewshed raster with a radius of 500 for a person standing at location
(-10147017, 5108065).
gdal_viewshed -md 500 -ox -10147017 -oy 5108065 source.tif destination.tif
REFERENCE
[Wang2000]
Generating Viewsheds without Using Sightlines. Wang, Jianjun, Robinson, Gary J., and
White, Kevin. Photogrammetric Engineering and Remote Sensing. p81.
https://www.asprs.org/wp-content/uploads/pers/2000journal/january/2000_jan_87-90.pdf
AUTHOR
Tamas Szekeres <szekerest@gmail.com>
COPYRIGHT
1998-2024
Oct 07, 2024 GDAL_VIEWSHED(1)