Geodesic Viewshed (Spatial Analyst)

Summary

Determines the raster surface locations visible to a set of observer features using geodesic methods.

Learn more about how the Geodesic Viewshed tool works

Illustration

The Geodesic Viewshed tool output with the Frequency option is displayed on a hillshaded elevation surface.

The Geodesic Viewshed tool output with the Observers option is displayed on a hillshaded elevation surface.

Usage

• This tool performs two types of visibility analysis, Frequency and Observers, that can be set using the Analysis type parameter.

• To ensure the accuracy of the output, assign a vertical coordinate system to the input raster if it does not already have one.

• This tool does not require a z-factor parameter. It will compute a z-factor internally using the vertical (z) unit and the map (xy) units from the spatial reference of the input raster.

• Input rasters that contain noise, most commonly seen in high-resolution data, may produce unexpected results. Before running this tool, you can either correct the data in a preprocessing step, or smooth out the noise using the Focal Statistics or the Filter tool before performing the viewshed operation.

• When the input raster needs to be resampled, the bilinear technique will be used. An example of when an input raster may be resampled is when the output coordinate system, extent, or cell size is different from that of the input.

• To enhance performance, you can explicitly set the Outer radius parameter to a value that represents the maximum viewing distance of interest for the analysis.

• By default, the Analysis Method parameter uses the All Sightlines option, which provides the most accurate output. To improve the performance of the tool in terms of processing time, use the Perimeter Sightlines option.

• The observer parameters related to height, such as Surface offset, Observer elevation and Observer offset, can be specified as a linear unit or as a field. During the calculation, the linear unit value will be converted internally to the z-unit of the input raster. However, if the linear unit is unknown or a numeric field is specified, the value is assumed to be in the z-unit of the input raster.

• The observer parameters related to viewing distances, such as Inner radius and Outer radius, can be specified as a linear unit or as a field. During the calculation, the linear unit value will be converted internally to the xy-units of the input raster. However, if the linear unit is unknown or a numeric field is specified, the value is assumed to be in the xy-unit of the input raster.

• The field specified for an observer parameter, such as Surface offset or Observer offset, can be string type that contains a numerical value and a unit. For example, if field obs_height is specified for Observer offset, it can contain values such as '6 Feet'.

  In scripting, the values for the observer parameters, such as observer_offset, can be specified in various forms of strings. In each form, a value and a linear unit is parsed from the string. The following table lists example input strings and how the linear unit is determined for each case. For other parameters, you can follow the same pattern.

  Examples of input strings and linear units

  Example of input string for Observer offset	Linear unit used
  ' ' or '#'	The default value and unit is used, which is 1 meter.
  '6'	The Observer offset is 6 and since no unit is specified, the tool will use the default unit, meter.
  '6 Feet'	The Observer offset is 6 feet.
  '6 Unknown'	The Observer offset is 6 and since no unit is specified, the tool will use the default unit, meter.

• This tool can be GPU accelerated, which means that if a compatible graphics processing unit (GPU) is available on your system, it will be used to enhance the performance of the tool. Use the Target device for analysis (analysis_target_device in Python) parameter to control whether the GPU or CPU will be used to run the tool.

  See GPU processing with Spatial Analyst for more details on compatible GPUs, configuring and working with GPU devices, as well as troubleshooting tips.

Parameters

Dialog

Label	Explanation	Data Type
Input raster	The input surface raster. It can be an integer or a floating-point raster. The input raster is transformed into a 3D geocentric coordinate system during the visibility calculation. NoData cells on the input raster do not block the visibility determination.	Raster Layer
Input point or polyline observer features	The input feature class that identifies the observer locations. It can be point, multipoint, or polyline features. The input feature class is transformed into a 3D geocentric coordinate system during the visibility calculation. Observers outside of the extent of the surface raster or located on NoData cells will be ignored in the calculation.	Feature Layer
Output above ground level raster (Optional)	The output above ground level (AGL) raster. The AGL result is a raster in which each cell value is the minimum height that must be added to a cell that is not visible to make it visible by at least one observer. Cells that are already visible will be assigned 0 in this output raster. When the vertical error parameter is 0, the output AGL raster will be a one-band raster. When the vertical error is greater than 0, to account for the random effects from the input raster, the output AGL raster will be created as a three-band raster. The first band represents the mean AGL values, the second band represents the minimum AGL values, and the third band represents the maximum AGL values.	Raster Dataset
Analysis type (Optional)	Specifies the type of visibility analysis that will be performed, either determining how visible each cell is to the observers or identifying the observers that are visible for each surface location. Frequency—The number of times that each cell location in the input surface raster can be seen by the input observation locations (as points or as vertices for polyline observer features) will be recorded in the output. This is the default. Observers—The observer points that are visible from each raster surface location will be identified in the output. The maximum number of input observer locations allowed for this analysis type is 32.	String
Vertical error (Optional)	The amount of uncertainty (the root mean square [RMS] error) in the surface elevation values. It is a floating-point value representing the expected error of the input elevation values. When this parameter is assigned a value greater than 0, the output visibility raster will be floating point. In this case, each cell value on the output visibility raster represents the sum of probabilities that the cell is visible to any of the observers. When the Analysis type parameter value is Observers or the Analysis method parameter value is Perimeter Sightlines, this parameter is disabled.	Linear Unit
Output observer-region relationship table (Optional)	The output table for identifying the regions that are visible to each observer. This table can be related to the input observer feature class and the output visibility raster for identifying the regions visible to given observers. This output is only created when the analysis type is Observers.	Table
Refractivity coefficient (Optional)	The coefficient of the refraction of visible light in air. The default value is 0.13.	Double
Surface offset (Optional)	A vertical distance to be added to the z-value of each cell as it is considered for visibility. It must be a positive integer or floating-point value. You can select a field in the input observers dataset, or you can specify a numerical value. For example, if the object to be observed is a vehicle, specify the height of the vehicle here. When this parameter is set to a value, the value will be used by all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset. The default value is 0.	Linear Unit; Field
Observer elevation (Optional)	The surface elevations of the observer points or vertices. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is not specified, the observer elevation will be obtained from the surface raster using bilinear interpolation. If this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset.	Linear Unit; Field
Observer offset (Optional)	A vertical distance to be added to the observer elevation. It must be a positive integer or floating-point value. You can select a field in the input observers dataset, or you can specify a numerical value. For example, if an observer is looking from a tower, specify the height of the tower here. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset. The default value is 1 meter.	Linear Unit; Field
Inner radius (Optional)	The start distance from which visibility is determined. Cells closer than this distance are not visible in the output but can still block visibility of the cells between inner radius and outer radius. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset. The default value is 0.	Linear Unit; Field
Inner radius is 3D distance (Optional)	Specifies the type of distance that will be used for the inner radius parameter. Unchecked—The inner radius will be interpreted as a 2D distance. This is the default. Checked—The inner radius will be interpreted as a 3D distance.	Boolean
Outer radius (Optional)	The maximum distance from which visibility is determined. Cells beyond this distance are excluded from the analysis. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset.	Linear Unit; Field
Outer radius is 3D distance (Optional)	Specifies the type of distance that will be used for the outer radius parameter. Unchecked—The outer radius will be interpreted as a 2D distance. This is the default. Checked—The outer radius will be interpreted as a 3D distance.	Boolean
Horizontal start angle (Optional)	The start angle of the horizontal scan range. Provide the value in degrees from 0 to 360 with 0 oriented to north. The value can be integer or floating point. The default value is 0. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset.	Double; Field
Horizontal end angle (Optional)	The end angle of the horizontal scan range. Provide the value in degrees from 0 to 360 with 0 oriented to north. The value can be integer or floating point. The default value is 360. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset.	Double; Field
Vertical upper angle (Optional)	The upper vertical angle limit of the scan relative to the horizontal plane. Provide the value in degrees from above -90 up to and including 90. The value can be integer or floating point. The default value is 90 (straight up). This parameter value must be greater than the Vertical lower angle parameter value. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset. The default value is 90 (straight up).	Double; Field
Vertical lower angle (Optional)	The lower vertical angle limit of the scan relative to the horizontal plane. Provide the value in degrees from -90 up to but not including 90. The value can be integer or floating point. The default value is -90 (straight down). This parameter value must be less than the Vertical upper angle parameter value. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset. The default value is -90 (straight down).	Double; Field
Analysis method (Optional)	Specifies the method that will be used to calculate visibility. This parameter allows you to decide on performance level. All Sightlines—A sightline will be run to every cell on the raster to establish visible areas, which may decrease performance depending on the number of sightlines. This is the default method. Perimeter Sightlines—Sightlines will only be run to the cells on the perimeter of the visible areas to establish visibility areas, which can increase performance because fewer sightlines are run in the calculation.	String
Target device for analysis (Optional)	Specifies the device that will be used to perform the calculation. GPU then CPU—If a compatible GPU is found, it will be used to perform the calculation. Otherwise, the CPU will be used. This is the default. CPU only—The calculation will only be performed on the CPU. GPU only—The calculation will only be performed on the GPU.	String

Return Value

Label	Explanation	Data Type
Output raster	The output raster. For the FREQUENCY analysis type, when the vertical error parameter is 0 or not specified, the output raster records the number of times that each cell location in the input surface raster can be seen by the input observation points. When the vertical error parameter is greater than 0, each cell on the output raster records the sum of probabilities that the cell is visible to any of the observers. For the OBSERVERS analysis type, the output raster records the unique region IDs for the visible areas, which can be related back to the observer features through the output observer-region relationship table.	Raster

Python

Viewshed2(in_raster, in_observer_features, {out_agl_raster}, {analysis_type}, {vertical_error}, {out_observer_region_relationship_table}, {refractivity_coefficient}, {surface_offset}, {observer_elevation}, {observer_offset}, {inner_radius}, {inner_radius_is_3d}, {outer_radius}, {outer_radius_is_3d}, {horizontal_start_angle}, {horizontal_end_angle}, {vertical_upper_angle}, {vertical_lower_angle}, {analysis_method}, {analysis_target_device})

Name	Explanation	Data Type
in_raster	The input surface raster. It can be an integer or a floating-point raster. The input raster is transformed into a 3D geocentric coordinate system during the visibility calculation. NoData cells on the input raster do not block the visibility determination.	Raster Layer
in_observer_features	The input feature class that identifies the observer locations. It can be point, multipoint, or polyline features. The input feature class is transformed into a 3D geocentric coordinate system during the visibility calculation. Observers outside of the extent of the surface raster or located on NoData cells will be ignored in the calculation.	Feature Layer
out_agl_raster (Optional)	The output above ground level (AGL) raster. The AGL result is a raster in which each cell value is the minimum height that must be added to a cell that is not visible to make it visible by at least one observer. Cells that are already visible will be assigned 0 in this output raster. When the vertical error parameter is 0, the output AGL raster will be a one-band raster. When the vertical error is greater than 0, to account for the random effects from the input raster, the output AGL raster will be created as a three-band raster. The first band represents the mean AGL values, the second band represents the minimum AGL values, and the third band represents the maximum AGL values.	Raster Dataset
analysis_type (Optional)	Specifies the type of visibility analysis that will be performed, either determining how visible each cell is to the observers or identifying the observers that are visible for each surface location. FREQUENCY—The number of times that each cell location in the input surface raster can be seen by the input observation locations (as points or as vertices for polyline observer features) will be recorded in the output. This is the default. OBSERVERS—The observer points that are visible from each raster surface location will be identified in the output. The maximum number of input observer locations allowed for this analysis type is 32.	String
vertical_error (Optional)	The amount of uncertainty (the root mean square [RMS] error) in the surface elevation values. It is a floating-point value representing the expected error of the input elevation values. When this parameter is assigned a value greater than 0, the output visibility raster will be floating point. In this case, each cell value on the output visibility raster represents the sum of probabilities that the cell is visible to any of the observers. When the analysis_type parameter value is OBSERVERS or the analysis_method parameter value is PERIMETER_SIGHTLINES, this parameter is disabled.	Linear Unit
out_observer_region_relationship_table (Optional)	The output table for identifying the regions that are visible to each observer. This table can be related to the input observer feature class and the output visibility raster for identifying the regions visible to given observers. This output is only created when the analysis type is OBSERVERS.	Table
refractivity_coefficient (Optional)	The coefficient of the refraction of visible light in air. The default value is 0.13.	Double
surface_offset (Optional)	A vertical distance to be added to the z-value of each cell as it is considered for visibility. It must be a positive integer or floating-point value. You can select a field in the input observers dataset, or you can specify a numerical value. For example, if the object to be observed is a vehicle, specify the height of the vehicle here. When this parameter is set to a value, the value will be used by all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset. The default value is 0.	Linear Unit; Field
observer_elevation (Optional)	The surface elevations of the observer points or vertices. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is not specified, the observer elevation will be obtained from the surface raster using bilinear interpolation. If this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset.	Linear Unit; Field
observer_offset (Optional)	A vertical distance to be added to the observer elevation. It must be a positive integer or floating-point value. You can select a field in the input observers dataset, or you can specify a numerical value. For example, if an observer is looking from a tower, specify the height of the tower here. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset. The default value is 1 meter.	Linear Unit; Field
inner_radius (Optional)	The start distance from which visibility is determined. Cells closer than this distance are not visible in the output but can still block visibility of the cells between inner radius and outer radius. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset. The default value is 0.	Linear Unit; Field
inner_radius_is_3d (Optional)	Specifies the type of distance that will be used for the inner radius parameter. GROUND—The inner radius will be interpreted as a 2D distance. This is the default. 3D—The inner radius will be interpreted as a 3D distance.	Boolean
outer_radius (Optional)	The maximum distance from which visibility is determined. Cells beyond this distance are excluded from the analysis. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset.	Linear Unit; Field
outer_radius_is_3d (Optional)	Specifies the type of distance that will be used for the outer radius parameter. GROUND—The outer radius will be interpreted as a 2D distance. This is the default. 3D—The outer radius will be interpreted as a 3D distance.	Boolean
horizontal_start_angle (Optional)	The start angle of the horizontal scan range. Provide the value in degrees from 0 to 360 with 0 oriented to north. The value can be integer or floating point. The default value is 0. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset.	Double; Field
horizontal_end_angle (Optional)	The end angle of the horizontal scan range. Provide the value in degrees from 0 to 360 with 0 oriented to north. The value can be integer or floating point. The default value is 360. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset.	Double; Field
vertical_upper_angle (Optional)	The upper vertical angle limit of the scan relative to the horizontal plane. Provide the value in degrees from above -90 up to and including 90. The value can be integer or floating point. The default value is 90 (straight up). This parameter value must be greater than the Vertical lower angle parameter value. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset. The default value is 90 (straight up).	Double; Field
vertical_lower_angle (Optional)	The lower vertical angle limit of the scan relative to the horizontal plane. Provide the value in degrees from -90 up to but not including 90. The value can be integer or floating point. The default value is -90 (straight down). This parameter value must be less than the Vertical upper angle parameter value. You can select a field in the input observers dataset, or you can specify a numerical value. When this parameter is set to a value, the value will be applied to all the observers. To specify different values for each observer, set this parameter to a field in the input observer features dataset. The default value is -90 (straight down).	Double; Field
analysis_method (Optional)	Specifies the method that will be used to calculate visibility. This parameter allows you to decide on performance level. ALL_SIGHTLINES—A sightline will be run to every cell on the raster to establish visible areas, which may decrease performance depending on the number of sightlines. This is the default method. PERIMETER_SIGHTLINES—Sightlines will only be run to the cells on the perimeter of the visible areas to establish visibility areas, which can increase performance because fewer sightlines are run in the calculation.	String
analysis_target_device (Optional)	Specifies the device that will be used to perform the calculation. GPU_THEN_CPU—If a compatible GPU is found, it will be used to perform the calculation. Otherwise, the CPU will be used. This is the default. CPU_ONLY—The calculation will only be performed on the CPU. GPU_ONLY—The calculation will only be performed on the GPU.	String

Return Value

Name	Explanation	Data Type
out_raster	The output raster. For the FREQUENCY analysis type, when the vertical error parameter is 0 or not specified, the output raster records the number of times that each cell location in the input surface raster can be seen by the input observation points. When the vertical error parameter is greater than 0, each cell on the output raster records the sum of probabilities that the cell is visible to any of the observers. For the OBSERVERS analysis type, the output raster records the unique region IDs for the visible areas, which can be related back to the observer features through the output observer-region relationship table.	Raster

Code sample

Viewshed2 example 1 (Python window)

This example determines the surface locations visible to a set of observers without using any observer parameters.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outViewshed2 = Viewshed2("elevation", "obser1.shp", "", "OBSERVERS", "",
                         "C:/sapyexamples/output/obstable01.dbf",
                         analysis_method="ALL_SIGHTLINES")
outViewshed2.save("C:/sapyexamples/output/outvwshd2_01")

Viewshed2 example 2 (stand-alone script)

This example determines the surface locations visible to a set of observers using attributes in the input feature class as the observer parameters.

# Name: Viewshed2_Ex_02.py
# Description: Determines the raster surface locations visible to a set of
#              observer features.
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *

# Set environment settings
env.workspace = "C:/sapyexamples/data"

# set local variables
inRaster = "elevation"
inObservers = "obser2.shp"
outAGL = ""
analysisType = "OBSERVERS"
verticalError = ""
outAnalysisRelationTable = "C:/sapyexamples/output/obser_region2.dbf"
refractCoeff = ""
surfaceOffset = "offsetb"
observerElevation = "spot"
observerOffset = "offseta"
innerRadius = "radius1"
innerIs3D = "False"
outerRadius = "radius2"
outerIs3D = "True"
horizStartAngle = "azimuth1"
horizEndAngle = "azimuth2"
vertUpperAngle = "vert1"
vertLowerAngle = "vert2"
analysisMethod = "ALL_SIGHTLINES"

# Execute Viewshed2
outViewshed2 = Viewshed2(inRaster, inObservers, outAGL, analysisType,
                         verticalError, outAnalysisRelationTable, refractCoeff,
                         surfaceOffset, observerElevation, observerOffset,
                         innerRadius, innerIs3D, outerRadius, outerIs3D,
                         horizStartAngle, horizEndAngle, vertUpperAngle,
                         vertLowerAngle, analysisMethod)

# Save the output
outViewshed2.save("C:/sapyexamples/output/outvwshd2_02")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Compression, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Parallel Processing Factor, Scratch Workspace, Snap Raster, Tile Size