Visibility (3D Analyst)

Summary

Determines the raster surface locations visible to a set of observer features, or identifies which observer points are visible from each raster surface location.

The Geodesic Viewshed tool provides enhanced functionality or performance.

Illustration

Visibility output with the Frequency option, displayed on a hillshaded elevation surface

Visibility output with the Observers option, displayed on a hillshaded elevation surface

Usage

• This tool supports two visibility analysis types, Frequency and Observers, which is controlled by the Analysis type tool parameter. For the first type, the tool determines which raster surface locations are visible to a set of observers. For the other, it identifies which observers are visible from each raster surface location.

• If the input raster contains undesirable noise caused by sampling errors, you can smooth the raster with a low-pass filter, such as the Mean option of the Focal Statistics tool, before running this tool.

• The visibility of each cell center is determined by comparing the altitude angle to the cell center with the altitude angle to the local horizon. The local horizon is computed by considering the intervening terrain between the point of observation and the current cell center. If the point lies above the local horizon, it is considered visible.

• An optional above-ground-level (AGL) output raster is provided by the tool. Each cell on the AGL output raster records the minimum height that needs to be added to that cell to make it visible by at least one observer.

  When the input observer features contain multiple observers, the output value is the minimum of the AGL values from all of the individual observers.

• Use the observer parameters to gain more control over the visibility analysis process. For example, through the observer offset parameter, you may specify an offset to the observer elevation in the visibility analysis.

• 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.

Parameters

Dialog

Label	Explanation	Data Type
Input raster	The input surface raster.	Raster Layer
Input point or polyline observer features	The feature class that identifies the observer locations. The input can be point or polyline features.	Feature Layer
Output raster	The output raster. The output will either record the number of times that each cell location in the input surface raster can be seen by the input observation locations (the frequency analysis type), or record which observer locations are visible from each cell in the raster surface (the observers type option).	Raster Dataset
Output above ground level raster (Optional)	The output above-ground-level (AGL) raster. The AGL result is a raster where each cell value is the minimum height that must be added to an otherwise nonvisible cell to make it visible by at least one observer. Cells that were already visible will have a value of 0 in this output raster.	Raster Dataset
Analysis type (Optional)	The visibility analysis type. Frequency—The output records 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). This is the default. Observers—The output identifies exactly which observer points are visible from each raster surface location.	String
Use NoData for non-visible cells (Optional)	Value assigned to nonvisible cells. Unchecked—0 is assigned to nonvisible cells. This is the default. Checked—NoData is assigned to nonvisible cells.	Boolean
Z factor (Optional)	Number of ground x,y units in one surface z unit. The z-factor adjusts the units of measure for the z units when they are different from the x,y units of the input surface. The z-values of the input surface are multiplied by the z-factor when calculating the final output surface. If the x,y units and z units are in the same units of measure, the z-factor is 1. This is the default. If the x,y units and z units are in different units of measure, the z-factor must be set to the appropriate factor, or the results will be incorrect. For example, if your z units are feet and your x,y units are meters, you would use a z-factor of 0.3048 to convert your z units from feet to meters (1 foot = 0.3048 meter).	Double
Use earth curvature corrections (Optional)	Specifies whether correction for the earth's curvature will be applied. Unchecked—No curvature correction will be applied. This is the default. Checked—Curvature correction will be applied.	Boolean
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. By default, a numerical field OFFSETB is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, the default value is 0.	Double; 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. By default, a numerical field SPOT is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it will be estimated through bilinear interpolation with the surface elevation values in the neighboring cells of the observer location.	Double; 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. By default, a numerical field OFFSETA is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it defaults to 1.	Double; 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. It can be a positive or negative integer or floating point value. If it is a positive value, then it is interpreted as three-dimensional, line-of-sight distance. If it is a negative value, then it is interpreted as two-dimensional planimetric distance. You can select a field in the input observers dataset, or you can specify a numerical value. By default, a numerical field RADIUS1 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, the default value is 0.	Double; Field
Outer radius (Optional)	The maximum distance from which visibility is determined. Cells beyond this distance are excluded from the analysis. It can be a positive or negative integer or floating point value. If it is a positive value, then it is interpreted as three-dimensional, line-of-sight distance. If it is a negative value, then it is interpreted as two-dimensional planimetric distance. You can select a field in the input observers dataset, or you can specify a numerical value. By default, a numerical field RADIUS2 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it defaults to infinity.	Double; Field
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. By default, a numerical field AZIMUTH1 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, the default value is 0.	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. By default, a numerical field AZIMUTH2 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it defaults to 360.	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. By default, a numerical field VERT1 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it defaults to 90.	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. By default, a numerical field VERT2 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it defaults to -90.	Double; Field

Return Value

Label	Explanation	Data Type
Output raster	The output raster. The output will either record the number of times that each cell location in the input surface raster can be seen by the input observation locations (the frequency analysis type), or record which observer locations are visible from each cell in the raster surface (the observers type).	Raster

Python

arcpy.ddd.Visibility(in_raster, in_observer_features, out_raster, {out_agl_raster}, {analysis_type}, {nonvisible_cell_value}, {z_factor}, {curvature_correction}, {refractivity_coefficient}, {surface_offset}, {observer_elevation}, {observer_offset}, {inner_radius}, {outer_radius}, {horizontal_start_angle}, {horizontal_end_angle}, {vertical_upper_angle}, {vertical_lower_angle})

Name	Explanation	Data Type
in_raster	The input surface raster.	Raster Layer
in_observer_features	The feature class that identifies the observer locations. The input can be point or polyline features.	Feature Layer
out_raster	The output raster. The output will either record the number of times that each cell location in the input surface raster can be seen by the input observation locations (the frequency analysis type), or record which observer locations are visible from each cell in the raster surface (the observers type option).	Raster Dataset
out_agl_raster (Optional)	The output above-ground-level (AGL) raster. The AGL result is a raster where each cell value is the minimum height that must be added to an otherwise nonvisible cell to make it visible by at least one observer. Cells that were already visible will have a value of 0 in this output raster.	Raster Dataset
analysis_type (Optional)	The visibility analysis type. FREQUENCY—The output records 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). This is the default. OBSERVERS—The output identifies exactly which observer points are visible from each raster surface location.	String
nonvisible_cell_value (Optional)	Value assigned to non-visible cells. ZERO—0 is assigned to nonvisible cells. This is the default. NODATA—NoData is assigned to nonvisible cells.	Boolean
z_factor (Optional)	Number of ground x,y units in one surface z unit. The z-factor adjusts the units of measure for the z units when they are different from the x,y units of the input surface. The z-values of the input surface are multiplied by the z-factor when calculating the final output surface. If the x,y units and z units are in the same units of measure, the z-factor is 1. This is the default. If the x,y units and z units are in different units of measure, the z-factor must be set to the appropriate factor, or the results will be incorrect. For example, if your z units are feet and your x,y units are meters, you would use a z-factor of 0.3048 to convert your z units from feet to meters (1 foot = 0.3048 meter).	Double
curvature_correction (Optional)	Specifies whether correction for the earth's curvature will be applied. FLAT_EARTH—No curvature correction will be applied. This is the default. CURVED_EARTH—Curvature correction will be applied.	Boolean
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. By default, a numerical field OFFSETB is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, the default value is 0.	Double; 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. By default, a numerical field SPOT is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it will be estimated through bilinear interpolation with the surface elevation values in the neighboring cells of the observer location.	Double; 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. By default, a numerical field OFFSETA is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it defaults to 1.	Double; 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. It can be a positive or negative integer or floating point value. If it is a positive value, then it is interpreted as three-dimensional, line-of-sight distance. If it is a negative value, then it is interpreted as two-dimensional planimetric distance. You can select a field in the input observers dataset, or you can specify a numerical value. By default, a numerical field RADIUS1 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, the default value is 0.	Double; Field
outer_radius (Optional)	The maximum distance from which visibility is determined. Cells beyond this distance are excluded from the analysis. It can be a positive or negative integer or floating point value. If it is a positive value, then it is interpreted as three-dimensional, line-of-sight distance. If it is a negative value, then it is interpreted as two-dimensional planimetric distance. You can select a field in the input observers dataset, or you can specify a numerical value. By default, a numerical field RADIUS2 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it defaults to infinity.	Double; Field
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. By default, a numerical field AZIMUTH1 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, the default value is 0.	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. By default, a numerical field AZIMUTH2 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it defaults to 360.	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. By default, a numerical field VERT1 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it defaults to 90.	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. By default, a numerical field VERT2 is used if it exists in the input observer features attribute table. You may overwrite it by specifying another numerical field or a value. If this parameter is unspecified and the default field does not exist in the input observer features attribute table, it defaults to -90.	Double; Field

Return Value

Name	Explanation	Data Type
out_raster	The output raster. The output will either record the number of times that each cell location in the input surface raster can be seen by the input observation locations (the frequency analysis type), or record which observer locations are visible from each cell in the raster surface (the observers type).	Raster

Code sample

Visibility example 1 (Python window)

This example determines surface locations visible to a set of observers defined in a shapefile.

import arcpy
from arcpy import env
from arcpy.sa import *

env.workspace = "c:/sapyexamples/data"

outvis = arcpy.sa.Visibility("elevation", "observers.shp", "c:/sapyexamples/output/aglout1",
                            "FREQUENCY", "NODATA", "1", "CURVED_EARTH", "0.13",
                            "OFFSETB", "SPOT", "OFFSETA", "RADIUS1", "RADIUS2",
                            "AZIMUTH1", "AZIMUTH2", "VERT1", "VERT2")

outvis.save("c:/sapyexamples/output/visiout1")

Visibility example 2 (stand-alone script)

This example determines which observers are visible at each surface location.

# Name: Visibility_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"
inObserverFeatures = "observers.shp"
aglOutput = "c:/sapyexamples/output/aglout1"
analysisType = "OBSERVERS"
nonVisibleValue = "ZERO"
zFactor = 1
useEarthCurvature = "CURVED_EARTH"
refractivityCoefficient = 0.13
surfaceOffset = 500
observerElevation = 2000
observerOffset = 500
innerRadius = 20000
outerRadius = 100000
horizStartAngle = 45
horizEndAngle = 215
vertUpperAngle = 5
vertLowerAngle = -5

# Execute Visibility
outvis = arcpy.sa.Visibility(inRaster, inObserverFeatures, algOutput, analysisType,
                            nonVisibleValue, zFactor, useEarthCurvature,
                            refractivityCoefficient, surfaceOffset, observerElevation,
                            observerOffset, innerRadius, outerRadius, horizStartAngle,
                            horizEndAngle, vertUpperAngle, vertLowerAngle)

# Save the output
outvis.save("c:/sapyexamples/output/visiout1")

Visibility example 1 (Python window)

This example determines surface locations visible to a set of observers defined in a shapefile.

import arcpy
from arcpy import env
env.workspace = "c:/data"

arcpy.Visibility_3d("elevation", "observers.shp", "c:/output/visiout1", 
                    "c:/output/aglout1", "FREQUENCY", "NODATA", "1", 
                    "CURVED_EARTH", "0.13", "OFFSETB", "SPOT", "OFFSETA", 
                    "RADIUS1", "RADIUS2", "AZIMUTH1", "AZIMUTH2", 
                    "VERT1", "VERT2")

Visibility example 2 (stand-alone script)

This example determines which observers are visible at each surface location.

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

# Import system modules
import arcpy
from arcpy import env

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

# set local variables
inRaster = "elevation"
inObserverFeatures = "observers.shp"
outRaster = "c:/output/visiout1"
aglOutput = "c:/output/aglout1"
analysisType = "OBSERVERS"
nonVisibleValue = "ZERO"
zFactor = 1
useEarthCurvature = "CURVED_EARTH"
refractivityCoefficient = 0.13
surfaceOffset = 500
observerElevation = 2000
observerOffset = 500
innerRadius = 20000
outerRadius = 100000
horizStartAngle = 45
horizEndAngle = 215
vertUpperAngle = 5
vertLowerAngle = -5

# Execute Visibility
arcpy.ddd.Visibility(inRaster, inObserverFeatures, outRaster, algOutput,
                     analysisType, nonVisibleValue, zFactor, useEarthCurvature,
                     refractivityCoefficient, surfaceOffset, observerElevation,
                     observerOffset, innerRadius, outerRadius, horizStartAngle,
                     horizEndAngle, vertUpperAngle, vertLowerAngle)

Environments

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