GDAL-RASTER-VIEWSHED(1) GDAL GDAL-RASTER-VIEWSHED(1)
gdal-raster-viewshed - Compute the viewshed of a raster dataset.
Added in version 3.11.
Usage: gdal raster viewshed [OPTIONS] <INPUT> <OUTPUT>
Compute the viewshed of a raster dataset.
Positional arguments:
-i, --input <INPUT> Input raster datasets [required]
-o, --output <OUTPUT> Output raster dataset [required]
Common Options:
-h, --help Display help message and exit
--json-usage Display usage as JSON document and exit
--config <KEY>=<VALUE> Configuration option [may be repeated]
-q, --quiet Quiet mode (no progress bar)
Options:
-f, --of, --format, --output-format <OUTPUT-FORMAT> Output format ("GDALG" allowed)
--co, --creation-option <KEY>=<VALUE> Creation option [may be repeated]
--overwrite Whether overwriting existing output is allowed
Mutually exclusive with --append
--append Append as a subdataset to existing output
Mutually exclusive with --overwrite
-p, --pos, --position <X,Y> or <X,Y,H> Observer position [2..3 values]
-z, --height <HEIGHT> Observer height
--target-height <TARGET-HEIGHT> Height of the target above the DEM surface in the height unit of the DEM. (default: 0)
--mode <MODE> Sets what information the output contains.. MODE=normal|DEM|ground|cumulative (default: normal)
--max-distance <MAX-DISTANCE> Maximum distance from observer to compute visibility. It is also used to clamp the extent of the output raster.
--min-distance <MIN-DISTANCE> Mask all cells less than this distance from the observer. Must be less than 'max-distance'.
--start-angle <START-ANGLE> Mask all cells outside of the arc ('start-angle', 'end-angle'). Clockwise degrees from north. Also used to clamp the extent of the output raster.
--end-angle <END-ANGLE> Mask all cells outside of the arc ('start-angle', 'end-angle'). Clockwise degrees from north. Also used to clamp the extent of the output raster.
--high-pitch <HIGH-PITCH> Mark all cells out-of-range where the observable height would be higher than the 'high-pitch' angle from the observer. Degrees from horizontal - positive is up. Must be greater than 'low-pitch'.
--low-pitch <LOW-PITCH> Bound observable height to be no lower than the 'low-pitch' angle from the observer. Degrees from horizontal - positive is up. Must be less than 'high-pitch'.
--curvature-coefficient <CURVATURE-COEFFICIENT> Coefficient to consider the effect of the curvature and refraction.
-b, --band <BAND> Input band (1-based index) (default: 1)
--visible-value <VISIBLE-VALUE> Pixel value to set for visible areas (default: 255)
--invisible-value <INVISIBLE-VALUE> Pixel value to set for invisible areas (default: 0)
--out-of-range-value <OUT-OF-RANGE-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)
--dst-nodata <DST-NODATA> The value to be set for the cells in the output raster that have no data.
--observer-spacing <OBSERVER-SPACING> Cell Spacing between observers (default: 10)
-j, --num-threads <NUM-THREADS> Number of jobs (or ALL_CPUS) (default: 3)
Advanced Options:
--if, --input-format <INPUT-FORMAT> Input formats [may be repeated]
--oo, --open-option <KEY>=<VALUE> Open options [may be repeated]
gdal raster viewshed creates a binary visibility raster from one band
of the input raster elevation model (DEM). The output raster will be
of type Byte. Using the DEM or ground values of --mode can also
create a minimum visible height raster of type Float64.
It uses the method defined in [Wang2000] for a user defined point.
This subcommand is also available as a potential step of gdal raster
pipeline (since GDAL 3.12)
-f, --of, --format, --output-format <OUTPUT-FORMAT>
Which output raster format to use. Allowed values may be given
by gdal --formats | grep raster | grep rw | sort
--co, --creation-option <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.
May be repeated.
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.
--overwrite
Allow program to overwrite existing target file or dataset.
Otherwise, by default, gdal errors out if the target file or
dataset already exists.
-b, --band <band>
Select an input 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.
--dst-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).
-p, --pos, --position <X,Y> or <X,Y,H>
The X,Y or X,Y,H(Height) position of the observer (in SRS
units for X and Y, and in the height unit of the DEM for H).
If the coordinate is outside of the raster, all space between
the observer and the raster is assumed not to occlude
visibility of the raster. (Not supported in cumulative mode.)
If H is not specified, it defaults to 2.
--target-height <value>
The height of the target above the DEM surface in the height
unit of the DEM. Default: 0
--max-distance <value>
Maximum distance from observer to compute visibility. It is
also used to clamp the extent of the output raster. (Not
supported in cumulative mode)
--min-distance <value>
Added in version 3.12.
Minimum distance from observer to compute visibility. Must be
less than '--max-distance' (Not supported in cumulative mode)
--start-angle <value>
Added in version 3.12.
Start angle for visibility. Measured clockwise from 0 North,
in degree. (Not supported in cumulative mode)
--end-angle <value>
Added in version 3.12.
End angle for visibility. Measured clockwise from 0 North, in
degree. (Not supported in cumulative mode)
--high-pitch <value>
Added in version 3.12.
High angle for visibility. Measured up from 0 horizontal, in
degree. Input values above the high pitch are marked out of
range. Must be greater than '--low-pitch'. (Not supported in
cumulative mode)
--low-pitch <value>
Added in version 3.12.
Low angle for visibility. Measured up from 0 horizontal, in
degree. Input cell values below the pitch are are clamped to
be no lower than the intersection of the angle. Must be less
than '--high-pitch'. (Not supported in cumulative mode)
--curvature-coefficient <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 | Curvature Coeff | Sphere Diameter |
| | Coeff | | 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 |
+--------------+--------------+-----------------+-----------------+
--invisible-value <value>
Pixel value to set for invisible areas. (Not supported in
cumulative mode) Default: 0
--out-of-range-value <value>
Pixel value to set for the cells that fall outside of the
range specified by the observer location and the maximum
distance. (Not supported in cumulative mode) Default: 0
--visible-value <value>
Pixel value to set for visible areas. (Not supported in
cumulative mode) Default: 255
--mode normal|DEM|ground|cumulative
Sets what information the output contains.
+o normal (the default) returns a raster of type Byte
containing visible locations.
+o DEM and ground return a raster of type Float64 containing
the minimum target height for the target to be visible from
the DEM surface or ground level respectively. That is to
say, if the minimum target height for the target to be
visible at a point is h and the value of the input raster at
that point is E, for DEM, E + h will be the output value.
For ground, h will be output value. Options
--target-height, --invisible-value and --visible-value will
be ignored.
+o cumulative creates an eight bit raster the same size as the
input raster where each cell represents the relative
observability from a grid of observer points. See the
--observer-spacing option.
--observer-spacing <value>
Cell spacing between observers (only supported in cumulative
mode). Default: 10
-j, --num-threads <value>
Number of jobs to run at once. (only supported in cumulative
mode). Default: 3
Added in version 3.12.
GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET)
This program supports serializing the command line as a JSON file
using the GDALG output format. The resulting file can then be opened
as a raster dataset using the GDALG: GDAL Streamed Algorithm driver,
and apply the specified pipeline in a on-the-fly / streamed way.
NOTE:
However this algorithm is not natively streaming compatible.
Consequently a temporary dataset will be generated, which may
cause significant processing time at opening.
Example 1
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 raster viewshed --max-distance=500 --pos=-10147017,5108065 source.tif destination.tif
Even Rouault <even.rouault@spatialys.com>
1998-2026
March 20, 2026 GDAL-RASTER-VIEWSHED(1)
NAME
gdal-raster-viewshed - Compute the viewshed of a raster dataset.
Added in version 3.11.
SYNOPSIS
Usage: gdal raster viewshed [OPTIONS] <INPUT> <OUTPUT>
Compute the viewshed of a raster dataset.
Positional arguments:
-i, --input <INPUT> Input raster datasets [required]
-o, --output <OUTPUT> Output raster dataset [required]
Common Options:
-h, --help Display help message and exit
--json-usage Display usage as JSON document and exit
--config <KEY>=<VALUE> Configuration option [may be repeated]
-q, --quiet Quiet mode (no progress bar)
Options:
-f, --of, --format, --output-format <OUTPUT-FORMAT> Output format ("GDALG" allowed)
--co, --creation-option <KEY>=<VALUE> Creation option [may be repeated]
--overwrite Whether overwriting existing output is allowed
Mutually exclusive with --append
--append Append as a subdataset to existing output
Mutually exclusive with --overwrite
-p, --pos, --position <X,Y> or <X,Y,H> Observer position [2..3 values]
-z, --height <HEIGHT> Observer height
--target-height <TARGET-HEIGHT> Height of the target above the DEM surface in the height unit of the DEM. (default: 0)
--mode <MODE> Sets what information the output contains.. MODE=normal|DEM|ground|cumulative (default: normal)
--max-distance <MAX-DISTANCE> Maximum distance from observer to compute visibility. It is also used to clamp the extent of the output raster.
--min-distance <MIN-DISTANCE> Mask all cells less than this distance from the observer. Must be less than 'max-distance'.
--start-angle <START-ANGLE> Mask all cells outside of the arc ('start-angle', 'end-angle'). Clockwise degrees from north. Also used to clamp the extent of the output raster.
--end-angle <END-ANGLE> Mask all cells outside of the arc ('start-angle', 'end-angle'). Clockwise degrees from north. Also used to clamp the extent of the output raster.
--high-pitch <HIGH-PITCH> Mark all cells out-of-range where the observable height would be higher than the 'high-pitch' angle from the observer. Degrees from horizontal - positive is up. Must be greater than 'low-pitch'.
--low-pitch <LOW-PITCH> Bound observable height to be no lower than the 'low-pitch' angle from the observer. Degrees from horizontal - positive is up. Must be less than 'high-pitch'.
--curvature-coefficient <CURVATURE-COEFFICIENT> Coefficient to consider the effect of the curvature and refraction.
-b, --band <BAND> Input band (1-based index) (default: 1)
--visible-value <VISIBLE-VALUE> Pixel value to set for visible areas (default: 255)
--invisible-value <INVISIBLE-VALUE> Pixel value to set for invisible areas (default: 0)
--out-of-range-value <OUT-OF-RANGE-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)
--dst-nodata <DST-NODATA> The value to be set for the cells in the output raster that have no data.
--observer-spacing <OBSERVER-SPACING> Cell Spacing between observers (default: 10)
-j, --num-threads <NUM-THREADS> Number of jobs (or ALL_CPUS) (default: 3)
Advanced Options:
--if, --input-format <INPUT-FORMAT> Input formats [may be repeated]
--oo, --open-option <KEY>=<VALUE> Open options [may be repeated]
DESCRIPTION
gdal raster viewshed creates a binary visibility raster from one band
of the input raster elevation model (DEM). The output raster will be
of type Byte. Using the DEM or ground values of --mode can also
create a minimum visible height raster of type Float64.
It uses the method defined in [Wang2000] for a user defined point.
This subcommand is also available as a potential step of gdal raster
pipeline (since GDAL 3.12)
Standard options
-f, --of, --format, --output-format <OUTPUT-FORMAT>
Which output raster format to use. Allowed values may be given
by gdal --formats | grep raster | grep rw | sort
--co, --creation-option <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.
May be repeated.
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.
--overwrite
Allow program to overwrite existing target file or dataset.
Otherwise, by default, gdal errors out if the target file or
dataset already exists.
-b, --band <band>
Select an input 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.
--dst-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).
-p, --pos, --position <X,Y> or <X,Y,H>
The X,Y or X,Y,H(Height) position of the observer (in SRS
units for X and Y, and in the height unit of the DEM for H).
If the coordinate is outside of the raster, all space between
the observer and the raster is assumed not to occlude
visibility of the raster. (Not supported in cumulative mode.)
If H is not specified, it defaults to 2.
--target-height <value>
The height of the target above the DEM surface in the height
unit of the DEM. Default: 0
--max-distance <value>
Maximum distance from observer to compute visibility. It is
also used to clamp the extent of the output raster. (Not
supported in cumulative mode)
--min-distance <value>
Added in version 3.12.
Minimum distance from observer to compute visibility. Must be
less than '--max-distance' (Not supported in cumulative mode)
--start-angle <value>
Added in version 3.12.
Start angle for visibility. Measured clockwise from 0 North,
in degree. (Not supported in cumulative mode)
--end-angle <value>
Added in version 3.12.
End angle for visibility. Measured clockwise from 0 North, in
degree. (Not supported in cumulative mode)
--high-pitch <value>
Added in version 3.12.
High angle for visibility. Measured up from 0 horizontal, in
degree. Input values above the high pitch are marked out of
range. Must be greater than '--low-pitch'. (Not supported in
cumulative mode)
--low-pitch <value>
Added in version 3.12.
Low angle for visibility. Measured up from 0 horizontal, in
degree. Input cell values below the pitch are are clamped to
be no lower than the intersection of the angle. Must be less
than '--high-pitch'. (Not supported in cumulative mode)
--curvature-coefficient <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 | Curvature Coeff | Sphere Diameter |
| | Coeff | | 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 |
+--------------+--------------+-----------------+-----------------+
--invisible-value <value>
Pixel value to set for invisible areas. (Not supported in
cumulative mode) Default: 0
--out-of-range-value <value>
Pixel value to set for the cells that fall outside of the
range specified by the observer location and the maximum
distance. (Not supported in cumulative mode) Default: 0
--visible-value <value>
Pixel value to set for visible areas. (Not supported in
cumulative mode) Default: 255
--mode normal|DEM|ground|cumulative
Sets what information the output contains.
+o normal (the default) returns a raster of type Byte
containing visible locations.
+o DEM and ground return a raster of type Float64 containing
the minimum target height for the target to be visible from
the DEM surface or ground level respectively. That is to
say, if the minimum target height for the target to be
visible at a point is h and the value of the input raster at
that point is E, for DEM, E + h will be the output value.
For ground, h will be output value. Options
--target-height, --invisible-value and --visible-value will
be ignored.
+o cumulative creates an eight bit raster the same size as the
input raster where each cell represents the relative
observability from a grid of observer points. See the
--observer-spacing option.
--observer-spacing <value>
Cell spacing between observers (only supported in cumulative
mode). Default: 10
-j, --num-threads <value>
Number of jobs to run at once. (only supported in cumulative
mode). Default: 3
Added in version 3.12.
GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET)
This program supports serializing the command line as a JSON file
using the GDALG output format. The resulting file can then be opened
as a raster dataset using the GDALG: GDAL Streamed Algorithm driver,
and apply the specified pipeline in a on-the-fly / streamed way.
NOTE:
However this algorithm is not natively streaming compatible.
Consequently a temporary dataset will be generated, which may
cause significant processing time at opening.
EXAMPLES
Example 1
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 raster viewshed --max-distance=500 --pos=-10147017,5108065 source.tif destination.tif
AUTHOR
Even Rouault <even.rouault@spatialys.com>
COPYRIGHT
1998-2026
March 20, 2026 GDAL-RASTER-VIEWSHED(1)