Implements the Wang et al (2000) viewshed based on reference planes.

This algorithm was originally described in “Generating viewsheds without using sightlines”, authored by Jianjun Wang, Gary J. Robertson, and Kevin White, published in Photogrammetric Engineering & Remote Sensing, Vol. 66, No. 1, January 2000, pp. 87-90.

Calculations for adjusting the required height for curvature of the earth have been adapted from the ESRI ArcGIS documentation:

Consistent with the routing functionality of pygeoprocessing, neighbor directions follow the right-hand rule where neighbor indexes are interpreted as:

# 321 # 4X0 # 567

natcap.invest.scenic_quality.viewshed.viewshed(dem_raster_path_band, viewpoint, visibility_filepath, viewpoint_height=0.0, curved_earth=True, refraction_coeff=0.13, max_distance=None, aux_filepath=None)

Compute the Wang et al. reference-plane based viewshed.

  • dem_raster_path_band (tuple) – A tuple of (path, band_index) where path is a path to a GDAL-compatible raster on disk and band_index is the 1-based band index. This DEM must be tiled with block sizes as a power of 2. If the viewshed is being adjusted for curvature of the earth and/or refraction, the elevation units of the DEM must be in meters. The DEM need not be projected in meters.

  • viewpoint (tuple) – A tuple of 2 numbers in the order (east offset, north offset). These units must be of the same units as the coordinate system of the DEM. This index represents the viewpoint location. The closest pixel to this viewpoint index will be used as the viewpoint.

  • visibility_filepath (string) – A filepath on disk to where the visibility raster will be written. If a raster exists in this location, it will be overwritten.

  • viewpoint_height=0.0 (float) – The height (in the units of the DEM height) of the observer at the viewpoint.

  • curved_earth=True (bool) – Whether to adjust viewshed calculations for the curvature of the earth. If False, the earth will be treated as though it is flat.

  • refraction_coeff=0.13 (float) – The coefficient of atmospheric refraction that may be adjusted to accommodate varying atmospheric conditions. Default is 0.13. Set to 0 to ignore refraction calculations.

  • max_distance=None (float) – If provided, visibility will not be calculated for DEM pixels that are more than this distance (in meters) from the viewpoint.

  • aux_filepath=None (string) – A path to a location on disk where the raster containing the auxiliary matrix will be written. The auxiliary matrix defines the height that a DEM must exceed in order to be visible from the viewpoint. This matrix is very useful for debugging. If a raster already exists at this location, it will be overwritten. If this path is not provided by the user, the viewshed will create this file as a temporary file wherever the system keeps its temp files and remove it when the viewshed finishes. See python’s tempfile documentation for where this might be on your system.

  • ValueError – When either the viewpoint does not overlap with the DEM or the DEM is not tiled appropriately.

  • LookupError – When the viewpoint coordinate pair is over nodata.

  • AssertionError – When pixel dimensions are not square.