GDAL-RASTER-VIEWSHED(1) GDAL 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] Compute the viewshed of a raster dataset. Positional arguments: -i, --input Input raster datasets [required] [not available in pipelines] -o, --output Output raster dataset [required] [not available in pipelines] Common Options: -h, --help Display help message and exit --json-usage Display usage as JSON document and exit --config = Configuration option [may be repeated] -q, --quiet Quiet mode (no progress bar or warning message) [not available in pipelines] Options: -f, --of, --format, --output-format Output format ("GDALG" allowed) [not available in pipelines] --co, --creation-option = Creation option [may be repeated] [not available in pipelines] --overwrite Whether overwriting existing output dataset is allowed [not available in pipelines] Mutually exclusive with --append --append Append as a subdataset to existing output [not available in pipelines] Mutually exclusive with --overwrite -p, --pos, --position or Observer position [2..3 values] -z, --height Observer height --sd-filename Filename of standard-deviation raster --target-height Height of the target above the DEM surface in the height unit of the DEM. (default: 0) --mode Sets what information the output contains.. MODE=normal|DEM|ground|cumulative (default: normal) --max-distance Maximum distance from observer to compute visibility. It is also used to clamp the extent of the output raster. --min-distance Mask all cells less than this distance from the observer. Must be less than 'max-distance'. --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 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 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 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 Coefficient to consider the effect of the curvature and refraction. -b, --band Input band (1-based index) (default: 1) --visible-value Pixel value to set for visible areas (default: 255) --invisible-value Pixel value to set for invisible areas (default: 0) --maybe-visible-value Pixel value to set for potentially visible areas (default: 2) --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) --output-nodata The value to be set for the cells in the output raster that have no data. --observer-spacing Cell Spacing between observers (default: 10) -j, --num-threads Number of jobs (or ALL_CPUS) (default: 3) Advanced Options: --if, --input-format Input formats [may be repeated] [not available in pipelines] --oo, --open-option = Open options [may be repeated] [not available in pipelines] 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) 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. PROGRAM-SPECIFIC OPTIONS -b, --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. --curvature-coefficient 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 | +--------------+------------------+-----------------+-----------------+ --end-angle Added in version 3.12. End angle for visibility. Measured clockwise from 0 North, in degree. (Not supported in cumulative mode) -z, --height Observer height --high-pitch 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) --invisible-value Pixel value to set for invisible areas. (Not supported in cumulative mode) Default: 0 --low-pitch 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) --max-distance 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 Added in version 3.12. Minimum distance from observer to compute visibility. Must be less than '--max-distance' (Not supported in cumulative mode) --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. -j, --num-threads Number of jobs to run at once. (only supported in cumulative mode). Default: 3 --observer-spacing Cell spacing between observers (only supported in cumulative mode). Default: 10 --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. (Not supported in cumulative mode) Default: 0 --output-nodata 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 or 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. --start-angle Added in version 3.12. Start angle for visibility. Measured clockwise from 0 North, in degree. (Not supported in cumulative mode) --target-height The height of the target above the DEM surface in the height unit of the DEM. Default: 0 --visible-value Pixel value to set for visible areas. (Not supported in cumulative mode) Default: 255 Added in version 3.13. --sd-filename Filename of raster containing standard deviations of the input raster values. The raster always comes from band 1 and the size must match that of the input raster. --maybe-visible-value Pixel value to set for visible areas. (Not supported in cumulative mode) Default: 255 STANDARD OPTIONS --append Append input raster as a new subdataset to an existing output file. Only works with drivers that support adding subdatasets such as GTiff -- GeoTIFF File Format and GPKG -- GeoPackage raster This also creates the output dataset if it does not exist yet. --co, --creation-option = 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. --if, --input-format Format/driver name to be attempted to open the input file(s). It is generally not necessary to specify it, but it can be used to skip automatic driver detection, when it fails to select the appropriate driver. This option can be repeated several times to specify several candidate drivers. Note that it does not force those drivers to open the dataset. In particular, some drivers have requirements on file extensions. May be repeated. --oo, --open-option = Dataset open option (format specific). May be repeated. -f, --of, --format, --output-format Which output raster format to use. Allowed values may be given by gdal --formats | grep raster | grep rw | sort --overwrite Allow program to overwrite existing target file or dataset. Otherwise, by default, gdal errors out if the target file or dataset already exists. RETURN STATUS CODE The program returns status code 0 in case of success, and non-zero in case of error (non-blocking errors emitted as warnings are considered as a successful execution). 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 COPYRIGHT 1998-2026 May 8, 2026 GDAL-RASTER-VIEWSHED(1)