Create Viewshed (Raster Analysis)

Summary

Creates areas where an observer can see objects on the ground. The input observer points can represent either observers (such as people on the ground or lookouts in a fire tower) or observed objects (such as wind turbines, water towers, vehicles, or other people).

Both the observers and the observed objects can have a height above ground, and these heights are used to determine visibility. For example, a viewshed computed for 300-foot wind turbines and a 6-foot tall person standing on the ground will typically be larger than a viewshed computed for 200-foot turbines and a 5-foot tall person.

The result layer records the number of times that each cell location in the input surface raster can be seen by the input observation points. Nonvisible cells are given NoData values.

Illustration

Create Viewshed tool illustration

Usage

  • This raster analysis portal tool is available when you are signed in to an ArcGIS Enterprise portal that has ArcGIS Image Server configured for Raster Analysis. When the tool is run, ArcGIS Pro serves as a client and the processing occurs in the servers federated with ArcGIS Enterprise. The portal tool accepts layers from your portal as input and creates output in your portal.

    The input raster layer supports a layer from the portal, a URI or URL to an image service, or the output from the Make Image Server Layer tool. The input feature layer can be a layer from the portal or a URI or URL to a feature service. This tool does not support local raster data or layers. While you can use local feature data and layers as input to this portal tool, best practice is to use layers from your portal as input.

  • The visibility of each cell center is determined by a line-of-sight test between the target and each observer.

Parameters

LabelExplanationData Type
Input Elevation Surface

The elevation surface that will be used for calculating the viewshed.

If the vertical unit of the input surface is different from the horizontal unit, such as when the elevation values are represented in feet but the coordinate system is in meters, the surface must have a defined vertical coordinate system. This is because the tool uses the vertical (z) and horizontal (x,y) units to compute a z-factor for the viewshed analysis. Without a vertical coordinate system, and having no z-unit information available, it is assumed that the z-unit is the same as the x,y unit. The result is an internal z-factor of 1.0 will be used for the analysis, which may give unexpected results.

The elevation surface can be integer or floating point.

Raster Layer; Image Service; String
Observer Features

The point features that represent the observer locations when calculating the viewsheds.

Feature Set
Output Name

The name of the output raster service.

The default name is based on the tool name and the input layer name. If the layer name already exists, you will be prompted to provide another name.

String
Optimize For
(Optional)

Specifies the optimization method that will be used to calculate the viewshed.

  • SpeedProcessing speed will be optimized, trading some accuracy in the result for better performance. This is the default.
  • AccuracyAccuracy in the results will be optimized, at the expense of a longer processing time.
String
Maximum Viewing Distance Type
(Optional)

Specifies how the maximum viewing distance will be determined.

If you change the type from Distance to Field, the Maximum Viewing Distance parameter will change to Maximum Viewing Distance Field.

  • DistanceThe maximum distance will be determined by the value you specify. This is the default method.
  • FieldThe maximum distance for each observer location will be determined by the values in a field you specify.
String
Maximum Viewing Distance
(Optional)

The cutoff distance that will be used where the computation of visible areas stops. Beyond this distance, it is unknown whether the observer points and the other objects can see each other.

The unit values are Kilometers, Meters, Statute Miles, International Yards, International Feet, US Survey Miles, US Survey Yards, and US Survey Feet.

The default value is 9 statute miles.

Linear Unit
Maximum Viewing Distance Field
(Optional)

The field containing the maximum viewing distance for each observer. The values contained in the field must be in the same unit as the x,y unit of the input elevation surface.

The maximum viewing distance is a cutoff distance where the computation of visible areas stops. Beyond this distance, it is unknown whether the observer points and the other objects can see each other.

Field
Minimum Viewing Distance Type
(Optional)

Specifies how the minimum visible distance will be determined.

If you change the type from Distance to Field, the Minimum Viewing Distance parameter will change to Minimum Viewing Distance Field.

  • DistanceThe minimum distance will be determined by the value you specify. This is the default method.
  • FieldThe minimum distance for each observer location will be determined by the values in a field you specify.
String
Minimum Viewing Distance
(Optional)

The distance that will be used where the computation of visible areas begins. Cells on the surface closer than this distance are not visible in the output but can still block visibility of the cells between the minimum and maximum viewing distance.

The unit values are Kilometers, Meters, Statute Miles, International Yards, International Feet, US Survey Miles, US Survey Yards, and US Survey Feet.

Linear Unit
Minimum Viewing Distance Field
(Optional)

The field containing the minimum viewing distance for each observer. The values contained in the field must be in the same unit as the x,y-unit of the input elevation surface.

The minimum viewing distance defines where the computation of visible areas begins. Cells on the surface closer than this distance are not visible in the output but can still block visibility of the cells between the minimum and maximum viewing distance.

Field
Viewing distances are 3D
(Optional)

Specifies whether the minimum and maximum viewing distance parameter values will be measured in 3D or 2D. A 2D distance is the simple linear distance measured between an observer and the target using their projected locations at sea level. A 3D distance provides a more realistic value by taking their relative heights into consideration.

  • Checked—The viewing distance will be measured in 3D distance.
  • Unchecked—The viewing distance will be measured in 2D distance. This is the default.
Boolean
Observers Elevation Type
(Optional)

Specifies how the elevation of the observers will be determined.

If you change the type from Elevation to Field, the Observers Elevation parameter will change to Observers Elevation Field.

  • ElevationThe observer elevation will be determined by the value you specify. This is the default method.
  • FieldThe elevation for each observer location will be determined by the values in a field you specify.
String
Observers Elevation
(Optional)

The elevation that will be used for the observer locations.

If 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, that 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.

The unit values are Kilometers, Meters, Statute Miles, International Yards, International Feet, US Survey Miles, US Survey Yards, and US Survey Feet.

Linear Unit
Observers Elevation Field
(Optional)

The field containing the elevation for the observers. The value contained in the field must be in the same unit as the z-unit of the input elevation surface.

If this parameter is not specified, the observer elevation will be obtained from the surface raster using bilinear interpolation.

Field
Observers Height Type
(Optional)

Specifies how the height of the observers will be determined.

If you change the type from Height to Field, the Observers Height parameter will change to Observers Height Field.

  • HeightThe observer height will be determined by the value you specify. This is the default method.
  • FieldThe height for each observer location will be determined by the values in a field you specify.
String
Observers Height
(Optional)

The height that will be used for the observer locations.

The unit values are Kilometers, Meters, Statute Miles, International Yards, International Feet, US Survey Miles, US Survey Yards, and US Survey Feet.

The default value is 6 international feet.

Linear Unit
Observers Height Field
(Optional)

The field containing the height for the observers. The value contained in the field must be in the same unit as the z-unit of the input elevation surface.

Field
Target Height Type
(Optional)

Specifies how the target height will be determined.

If you change the type from Height to Field, the Target Height parameter will change to Target Height Field.

  • HeightThe target height will be determined by the value you specify. This is the default method.
  • FieldThe height for each target will be determined by the values in a field you specify.
String
Target Height
(Optional)

The height of structures or people on the ground that will be used to establish visibility. The result viewshed are those areas where an observer point can see these other objects. The converse is also true; the other objects can see an observer point.

The unit values are Kilometers, Meters, Statute Miles, International Yards, International Feet, US Survey Miles, US Survey Yards, and US Survey Feet.

Linear Unit
Target Height Field
(Optional)

The field containing the height for the targets. The value contained in the field must be in the same unit as the z-unit of the input elevation surface.

Field
Above Ground Level Output Name
(Optional)

The name of 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 an otherwise nonvisible cell to make it visible by at least one observer. Cells that were already visible will be assigned 0 in this output raster.

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.

Linear Unit
Refractivity Coefficient
(Optional)

The coefficient of the refraction of visible light in air.

The default value is 0.13.

Double
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 observer features, or you can provide a numerical value.

String
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 observer features, or you can provide a numerical value.

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

You can select a field in the input observer features, or you can provide a numerical value.

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

You can select a field in the input observer features, or you can provide a numerical value.

String

Derived Output

LabelExplanationData Type
Output Raster

The output viewshed raster.

Raster Layer
Output Above Ground Level Raster

The output above ground level raster.

Raster Layer

arcpy.ra.CreateViewshed(inputElevationSurface, inputObserverFeatures, outputName, {optimizeFor}, {maximumViewingDistanceType}, {maximumViewingDistance}, {maximumViewingDistanceField}, {minimumViewingDistanceType}, {minimumViewingDistance}, {minimumViewingDistanceField}, {viewingDistanceIs3D}, {observersElevationType}, {observersElevation}, {observersElevationField}, {observersHeightType}, {observersHeight}, {observersHeightField}, {targetHeightType}, {targetHeight}, {targetHeightField}, {aboveGroundLevelOutputName}, {verticalError}, {refractivityCoefficient}, {horizontalStartAngle}, {horizontalEndAngle}, {verticalUpperAngle}, {verticalLowerAngle})
NameExplanationData Type
inputElevationSurface

The elevation surface that will be used for calculating the viewshed.

If the vertical unit of the input surface is different from the horizontal unit, such as when the elevation values are represented in feet but the coordinate system is in meters, the surface must have a defined vertical coordinate system. This is because the tool uses the vertical (z) and horizontal (x,y) units to compute a z-factor for the viewshed analysis. Without a vertical coordinate system, and having no z-unit information available, it is assumed that the z-unit is the same as the x,y unit. The result is an internal z-factor of 1.0 will be used for the analysis, which may give unexpected results.

The elevation surface can be integer or floating point.

Raster Layer; Image Service; String
inputObserverFeatures

The point features that represent the observer locations when calculating the viewsheds.

Feature Set
outputName

The name of the output raster service.

The default name is based on the tool name and the input layer name. If the layer name already exists, you will be prompted to provide another name.

String
optimizeFor
(Optional)

Specifies the optimization method that will be used to calculate the viewshed.

  • SPEEDProcessing speed will be optimized, trading some accuracy in the result for better performance. This is the default.
  • ACCURACYAccuracy in the results will be optimized, at the expense of a longer processing time.
String
maximumViewingDistanceType
(Optional)

Specifies how the maximum viewing distance will be determined.

  • DISTANCEThe maximum distance will be determined by the value you specify. This is the default method.
  • FIELDThe maximum distance for each observer location will be determined by the values in a field you specify.
String
maximumViewingDistance
(Optional)

The cutoff distance that will be used where the computation of visible areas stops. Beyond this distance, it is unknown whether the observer points and the other objects can see each other.

The unit values are Kilometers, Meters, MilesInt, YardsInt, FeetInt, Miles, Yards, and Feet.

The default value is 9 statute miles.

Linear Unit
maximumViewingDistanceField
(Optional)

The field containing the maximum viewing distance for each observer. The values contained in the field must be in the same unit as the x,y unit of the input elevation surface.

The maximum viewing distance is a cutoff distance where the computation of visible areas stops. Beyond this distance, it is unknown whether the observer points and the other objects can see each other.

Field
minimumViewingDistanceType
(Optional)

Specifies how the minimum visible distance will be determined.

  • DISTANCEThe minimum distance will be determined by the value you specify. This is the default method.
  • FIELDThe minimum distance for each observer location will be determined by the values in a field you specify.
String
minimumViewingDistance
(Optional)

The distance that will be used where the computation of visible areas begins. Cells on the surface closer than this distance are not visible in the output but can still block visibility of the cells between the minimum and maximum viewing distance.

The unit values are Kilometers, Meters, MilesInt, YardsInt, FeetInt, Miles, Yards, and Feet.

Linear Unit
minimumViewingDistanceField
(Optional)

The field containing the minimum viewing distance for each observer. The values contained in the field must be in the same unit as the x,y-unit of the input elevation surface.

The minimum viewing distance defines where the computation of visible areas begins. Cells on the surface closer than this distance are not visible in the output but can still block visibility of the cells between the minimum and maximum viewing distance.

Field
viewingDistanceIs3D
(Optional)

Specifies whether the minimum and maximum viewing distance parameter values will be measured in 3D or 2D. A 2D distance is the simple linear distance measured between an observer and the target using their projected locations at sea level. A 3D distance provides a more realistic value by taking their relative heights into consideration.

  • 2DThe viewing distance will be measured in 2D distance. This is the default.
  • 3DThe viewing distance will be measured in 3D distance.
Boolean
observersElevationType
(Optional)

Specifies how the elevation of the observers will be determined.

  • ELEVATIONThe observer elevation will be determined by the value you specify. This is the default method.
  • FIELDThe elevation for each observer location will be determined by the values in a field you specify.
String
observersElevation
(Optional)

The elevation that will be used for the observer locations.

If 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, that 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.

The unit values are Kilometers, Meters, MilesInt, YardsInt, FeetInt, Miles, Yards, and Feet.

Linear Unit
observersElevationField
(Optional)

The field containing the elevation for the observers. The value contained in the field must be in the same unit as the z-unit of the input elevation surface.

If this parameter is not specified, the observer elevation will be obtained from the surface raster using bilinear interpolation.

Field
observersHeightType
(Optional)

Specifies how the height of the observers will be determined.

  • HEIGHTThe observer height will be determined by the value you specify. This is the default method.
  • FIELDThe height for each observer location will be determined by the values in a field you specify.
String
observersHeight
(Optional)

The height that will be used for the observer locations.

The unit values are Kilometers, Meters, MilesInt, YardsInt, FeetInt, Miles, Yards, and Feet.

The default value is 6 international feet.

Linear Unit
observersHeightField
(Optional)

The field containing the height for the observers. The value contained in the field must be in the same unit as the z-unit of the input elevation surface.

Field
targetHeightType
(Optional)

Specifies how the target height will be determined.

  • HEIGHTThe target height will be determined by the value you specify. This is the default method.
  • FIELDThe height for each target will be determined by the values in a field you specify.
String
targetHeight
(Optional)

The height of structures or people on the ground that will be used to establish visibility. The result viewshed are those areas where an observer point can see these other objects. The converse is also true; the other objects can see an observer point.

The unit values are Kilometers, Meters, MilesInt, YardsInt, FeetInt, Miles, Yards, and Feet.

Linear Unit
targetHeightField
(Optional)

The field containing the height for the targets. The value contained in the field must be in the same unit as the z-unit of the input elevation surface.

Field
aboveGroundLevelOutputName
(Optional)

The name of 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 an otherwise nonvisible cell to make it visible by at least one observer. Cells that were already visible will be assigned 0 in this output raster.

String
verticalError
(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.

Linear Unit
refractivityCoefficient
(Optional)

The coefficient of the refraction of visible light in air.

The default value is 0.13.

Double
horizontalStartAngle
(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 observer features, or you can provide a numerical value.

String
horizontalEndAngle
(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 observer features, or you can provide a numerical value.

String
verticalUpperAngle
(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).

You can select a field in the input observer features, or you can provide a numerical value.

String
verticalLowerAngle
(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).

You can select a field in the input observer features, or you can provide a numerical value.

String

Derived Output

NameExplanationData Type
outputRaster

The output viewshed raster.

Raster Layer
outputAboveGroundLevelRaster

The output above ground level raster.

Raster Layer

Code sample

CreateViewshed example 1 (Python window)

This example creates a viewshed image service using specified surface and observer points.

import arcpy

arcpy.ra.CreateViewshed(
    "https://myserver/rest/services/elevation/ImageServer", 
    "https://myserver/rest/services/destination/FeatureServer/0", 
    "outview1", "SPEED", "DISTANCE", "9 Miles", "#", "DISTANCE",
    "0 Meters", "#", "2D", "ELEVATION", "#", "#", "HEIGHT",
    "6 Feet", "#", "HEIGHT", "3 Feet", "#", "outagl1")
CreateViewshed example 2 (stand-alone script)

This example creates a viewshed image service using specified surface and observer points.

#---------------------------------------------------------------------------
# Name: CreateViewshed_example02.py
# Description: Creates a viewshed image service raster from given surface
#   and observer points.
#
# Requirements: ArcGIS Image Server

# Import system modules
import arcpy

# Set local variables
inSurface = "https://myserver/rest/services/elevation/ImageServer"
inObservers = "https://myserver/rest/services/destination/FeatureServer/0"
outputViewshed = "outview1"
optimizeFor = "Speed"
maxDistType = "Distance"
maxDist = "9 Miles"
maxDistField = "#"
minDistType = "Distance"
minDist = "0 Miles"
minDistField = "#"
distanceIs3D = "2D"
obsElevationType = "Elevation"
obsElevation = "#"
obsElevationField = "#"
obsOffsetType = "Height"
obsOffset = "6 Feet"
obsOffsetField = "#"
surfOffsetType = "Height"
surfOffset = "3 Feet"
surfOffsetField = "#"
outputAgl = "outagl1"

# Execute Create Viewshed raster analysis tool
arcpy.ra.CreateViewshed(
    inSurface, inObservers, outputViewshed, optimizeFor,
    maxDistType, maxDist, maxDistField, minDistType, minDist,
    minDistField, distanceIs3D, obsElevationType, obsElevation,
    obsElevationField, obsOffsetType, obsOffset, obsOffsetField,
    surfOffsetType, surfOffset, surfOffsetField, outputAgl)

Licensing information

  • Basic: Requires ArcGIS Image Server
  • Standard: Requires ArcGIS Image Server
  • Advanced: Requires ArcGIS Image Server

Related topics