GDAL_VIEWSHED(1)

📦
version 3.4.3 · 2 versions
, in epel 9

💅 GDAL_VIEWSHED(1) — the GDAL manual, bestie edition

okay so you're reading the GDAL manual page GDAL_VIEWSHED(1) and it's lowkey iconic. buckle up 🎀

✨ NAME ✨

gdal_viewshed — literally calculates a viewshed raster from an input raster DEM for a user defined point. yes bestie, it's giving "who can see what from where" energy 👀

🌸 SYNOPSIS 🌸

   gdal_viewshed [-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 🦋

So by default gdal_viewshed generates a binary visibility raster from one band of the input raster elevation model (DEM). The output raster is of type Byte. And with the -mode flag it can also return a minimum visible height raster of type Float64. two vibes, one tool, 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. fr fr, don't come crying to me about your lat/lon, it's not gonna slay for you 😭

🌈 OPTIONS 🌈

  • -co <NAME=VALUE> — okay so many formats have one or more optional creation options that control particulars about the file created. For instance, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled. iconic of them tbh.

The creation options available vary by format driver, and some simple formats have no creation options at all — not every format is a main character. 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. iykyk 💅

  • -b <band> — selects an input band band containing the DEM data. Bands are numbered from 1. Only a single band can be used — one band only bestie, sharing is not caring here. Only the part of the raster within the specified maximum distance around the observer point is processed. lowkey efficient ✨
  • -a_nodata <value> — the value to be set for the cells in the output raster that have no data. yes, the "i literally have nothing" cells 🫠
NOTE: currently, no special processing of input cells at a nodata value is done (which may result in erroneous results). so like... your garbage goes in, your garbage comes out, that's the whole entire vibe check 💀
  • -ox <value> — the X position of the observer (in SRS units).
  • -oy <value> — the Y position of the observer (in SRS units). the observer is the main character of this whole operation 👑
  • -oz <value> — the height of the observer above the DEM surface, in the height unit of the DEM. Default: 2. short king representation 🙈
  • -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. boundaries, bestie, we're setting them 🚧
  • -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. nerd hours but like, in a hot way 🧚

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). periodt.

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. flat earth girlies stay losing 💀
  • -iv <value> — pixel value to set for invisible areas. Default: 0. the "you literally cannot see this" zones 🙈
  • -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. off the map, out of the group chat ✌️
  • -vv <value> — pixel value to set for visible areas. Default: 255. bestie you're SO visible, ate 💖
  • -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 — sorry babe, they're benched for this one.

Default NORMAL

💜 C API 💜

Functionality of this utility can be done from C with GDALViewshedGenerate(). if C is your love language, we got you 🫶

⭐ EXAMPLE ⭐

Compute the visibility of an elevation raster data source with defaults:

[image] A computed visibility for two separate -ox and -oy points on a DEM..UNINDENT

   gdal_viewshed -md 500 -ox -10147017 -oy 5108065 source.tif destination.tif

[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> — an absolute legend, we stan 🌟

1998-2026

and that's the whole page, bestie 💅✨ xoxo, sourced from GDAL_VIEWSHED(1) dated Jan 08, 2026 — go touch some DEMs 🦋🌸

📦 where this page comes from