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

Usage

  • This raster analysis portal tool is available when you are signed in to an ArcGIS Enterprise Link to Understanding analysis in ArcGIS Enterprise portal that has an ArcGIS Image Server Link to What is ArcGIS Image Server configured for Raster Analysis Link to Configure and deploy raster analytics. When the tool is invoked, 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.

Syntax

arcpy.ra.CreateViewshed(inputElevationSurface, inputObserverFeatures, outputName, {optimizeFor}, {maximumViewingDistanceType}, {maximumViewingDistance}, {maximumViewingDistanceField}, {minimumViewingDistanceType}, {minimumViewingDistance}, {minimumViewingDistanceField}, {viewingDistanceIs3D}, {observersElevationType}, {observersElevation}, {observersElevationField}, {observersHeightType}, {observersHeight}, {observersHeightField}, {targetHeightType}, {targetHeight}, {targetHeightField}, {aboveGroundLevelOutputName})
ParameterExplanationData Type
inputElevationSurface

The elevation surface to use 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. The reason for this is that the tool uses the vertical (Z) and horizontal (XY) units to compute a z-factor for the viewshed analysis. Without a vertical coordinate system, and thus having no Z unit information available, the tool will assume that the Z unit is the same as the XY unit. The result of this is that 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)

The optimization method to use for calculating the viewshed.

  • SPEEDThis method optimizes the processing speed, trading some accuracy in the result for higher performance. This is the default.
  • ACCURACYThis method is optimized for accuracy in the results, at the expense of a longer processing time.
String
maximumViewingDistanceType
(Optional)

The method by which the maximum viewing distance will be determined.

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

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

The units can be Kilometers, Meters, Miles, Yards, or Feet.

The default is miles.

Linear Unit
maximumViewingDistanceField
(Optional)

This is a field you can use to specify the maximum viewing distance for each observer. The values contained in the field must be in the same unit as the XY 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)

Choose the method by which the minimum visible distance will be determined.

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

This is a distance 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 units can be Kilometers, Meters, Miles, Yards, or Feet.

The default units are Meters.

Linear Unit
minimumViewingDistanceField
(Optional)

This is a field you can use to specify the minimum viewing distance for each observer. The values contained in the field must be in the same unit as the XY 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)

Specify whether the minimum and maximum viewing distance parameters are measured in a three-dimensional way or a simpler, two-dimensional way. 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 gives a more realistic value by taking their relative heights into consideration.

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

The method by which the elevation of the observers will be determined.

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

This is the elevation of your 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 units can be Kilometers, Meters, Miles, Yards, or Feet.

The default units are Meters.

Linear Unit
observersElevationField
(Optional)

This is a field you can use to specify 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)

The method by which the height of the observers will be determined.

  • HEIGHTThe observer height is obtained from the value you specify. This is the default method.
  • FIELD The height for each observer location is determined by the values in a field you specify.
String
observersHeight
(Optional)

This is the height used for your observer locations.

The units can be Kilometers, Meters, Miles, Yards, or Feet.

The default units are Meters.

Linear Unit
observersHeightField
(Optional)

This is a field you can use to specify 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)

The method by which the height of the targets will be determined.

  • HEIGHTThe target height is obtained from the value you specify. This is the default method.
  • FIELD The height for each target is determined by the values in a field you specify.
String
targetHeight
(Optional)

This is the height of structures or people on the ground 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 units can be Kilometers, Meters, Miles, Yards, or Feet.

The default units are Meters.

Linear Unit
targetHeightField
(Optional)

This is a field used to specify 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 aboveground-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 be assigned 0 in this output raster.

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 given surface and observer points.

import arcpy

arcpy.CreateViewshed_ra(
    "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 given 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.CreateViewshed_ra(
    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