GDAL_VIEWSHED(1)

📦
version 3.13.3 · 11 versions
, in alpine 3.24, arch rolling, ubuntu stonking

💖 NAME 💖

okay so bestie, gdal_viewshed — it calculates a viewshed raster from an input raster DEM for a user defined point. like, who can see what from where, map edition. ✨

🦋 SYNOPSIS 🦋

Usage: gdal_viewshed [--help] [--long-usage] [--help-general]
                     [-of <output_format>] [-ox <value>] [-oy <value>]
                     [-oz <value>] [-vv <value>] [-iv <value>] [-ov <value>]
                     [-co <NAME>=<VALUE>]... [-a_nodata <value>] [-tz <value>]
                     [-md <value>] [-j <value>] [-cc <value>] [-b <value>]
                     [-om NORMAL|DEM|GROUND|ACCUM] [-os <value>] [-sd <value>]
                     [--quiet]
                     <src_filename> <dst_filename>

🌸 DESCRIPTION 🌸

So by default, gdal_viewshed makes you a binary visibility raster from one band of the input raster elevation model (DEM). The output raster is type Byte. And if you use the -mode flag it can also hand you back a minimum visible height raster of type Float64. options on options, we love to see it 💅

NOTE: the algorithm as implemented currently will only output meaningful results if the georeferencing is in a projected coordinate reference system. for real, don't come at it with unprojected coords, it's not gonna slay.
TIP: Equivalent in new gdal command line interface: See gdal raster viewshed

okay now let's meet the options, one by one, no skips, no cuts, we're doing the whole list 🫶

  • --help — shows this help message and exits. classic.
  • --help-general — gives you a brief usage message for the generic GDAL commandline options, then exits.
  • -q, --quiet — suppresses progress messages and other non-error output. for when you want it silent but deadly 🍓
  • -co <NAME>=<VALUE> — so many formats have one or more optional creation options that can control the particulars of the file being 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. you can list the options supported for a format with the --format command line option, but the documentation for the format is the definitive source of info 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). yeah. it's giving "we know, we know" 😭
  • -ox <value> — the X position of the observer (in SRS units). 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.)
  • -oy <value> — the Y position of the observer (in SRS units). 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.)
  • -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 visibility. it's also used to clamp the extent of the output raster. (Not supported in cumulative mode.)
  • -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 below (use the Curvature Coeff value for the cc option):

  • No Refraction — Refraction Coeff: 0, Curvature Coeff: 1, Sphere Diameter Factor: 1
  • Visible Light — Refraction Coeff: 1/7, Curvature Coeff: 6/7 (=~0.85714), Sphere Diameter Factor: 7/6 (=~1.1666)
  • Radio Waves — Refraction Coeff: 0.25 ~ 0.325, Curvature Coeff: 0.75 ~ 0.675, Sphere Diameter Factor: 1.33 ~ 1.48
  • Flat Earth — Refraction Coeff: 1, Curvature Coeff: 0, Sphere Diameter Factor: inf

the vibes? immaculate 🌈

  • -iv <value> — pixel value to set for invisible areas. (Not supported in cumulative mode.) 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. (Not supported in cumulative mode.) Default: 0
  • -vv <value> — pixel value to set for visible areas. (Not supported in cumulative mode.) Default: 255
  • -om <output mode> — sets what information the output contains.

Possible values: NORMAL, DEM, GROUND, ACCUM

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. 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. flags -tz, -iv and -vv will be ignored.

Cumulative (ACCUM) mode will create 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 -os option.

Default NORMAL

  • -os <value> — Cell Spacing between observers (only supported in cumulative mode). Default: 10
  • -j <value> — Number of jobs to run at once. (only supported in cumulative mode.) Default: 3

👑 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). so a warning is not a fail, okay? don't panic 💀

🧚 C API 🧚

the functionality of this utility can be done from C with GDALViewshedGenerate(). yup, you can do all this from C too, main character energy 🔥

🌟 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_viewshed -md 500 -ox -10147017 -oy 5108065 source.tif destination.tif

ate. no crumbs. 💅

💜 REFERENCE 💜

🎀 AUTHOR 🎀

Tamas Szekeres <szekerest@gmail.com> — icon, legend, the blueprint 🫶

1998-2026

and that's the whole page bestie, every last flag and formula accounted for, periodt. this was GDAL_VIEWSHED(1), from the GDAL fam, dated Aug 18, 2026. go forth and viewshed responsibly, mwah 💖🌈👑

📦 where this page comes from