Viewshed

Viewshed task

The Viewshed task is used to identify visible areas based on observer locations you provide as well as ArcGIS Online Elevation data.

Request URL

http://elevation.arcgis.com/arcgis/rest/services/Tools/Elevation/GPServer/Viewshed/submitJob

Description

The Viewshed task is used to identify visible areas. You specify the places you are interested in, either from a file or interactively, and the Viewshed task combines this with Esri-maintained elevation data to create output polygons of visible areas. Some questions you can answer with the Viewshed task include the following:

  • What areas can I see from this location?
  • What areas can see me?
  • Can I see the proposed wind farm?
  • What areas can be seen from this proposed fire tower location?

Depending upon the DEM resolution selected, different data sources will be used by the task.

  • By default, this task currently works worldwide between 60 degrees north and 56 degrees south based on the 3 arc-second (approximately 90 meter) resolution SRTM dataset.
  • For 30m, the task will use 1 arc-second resolution data in North America (Canada, United States, and Mexico) from the USGS National Elevation Dataset (NED), SRTM DEM-S dataset from Geoscience Australia in Australia and SRTM data between 60 degrees north and 56 degrees south in the remaining parts of the world (Africa, South America, most of Europe and continental Asia, the East Indies, New Zealand, and islands of the western Pacific).
  • For 24m, the task will use 0.8 arc-second (approximately 24 meter) data from the global dataset WorldDEM4Ortho from Airbus Defence and Space GmbH, excluding the counties of Azerbaijan, DR Congo and Ukraine.
  • For 10m, the task will use 1/3 arc-second resolution data in the continental United States from USGS National Elevation Dataset (NED) and approximately 10 meter data covering Norway, Finland, Denmark, Austria and Spain from various authoritative sources.

Please refer to the locator map to see the areas covered and to learn more about the data sources currently available.

Usage

  • The task will return an error message if the specified resolution is not available at any of the input feature locations.

  • If the DEMResolution parameter is empty or not supplied, the resolution of 90 meters will be used.

  • If FINEST is specified for the parameter, the task will use the smallest resolution available at your observer location that is allowed by the MaximumDistance parameter. This means when the MaximumDistance is less than or equal to 5 kilometers, and for areas where it is available, the 10m resolution data will be used. If the maximum distance is greater than 5 kilometers but less than or equal to 15 kilometers, and where it is available, the 24m resolution data will be used. Otherwise, if the distance is greater than 15 kilometers, the 90m resolution data will be used.

  • For the MaximumDistance parameter itself, the allowed value for the 10m, 24m and 30m DEM resolutions is 15 kilometers or less. For the 90m DEM resolution, the allowed value is 50 kilometers or less. If this parameter is not specified, the task will use a default value based on the DEM resolution parameter. For 10m resolution, the default maximum distance is 5 kilometers. For the 24m, 30m and 90m DEM resolutions, the default distance is 15 kilometers.

  • The task uses a single resolution elevation source for the input features. All the input features must fit into a single resolution, or the task will pick the highest resolution that can cover the features.

  • Visibility into water is limited, so the tool uses the water surface as the elevation. Oceans have been assigned a value of zero, and major water bodies have been assigned an appropriate flat local elevation.

  • It is possible to control the viewshed analysis using the observer attribute fields. The supported fields are OFFSETA, OFFSETB, AZIMUTH1, AZIMUTH2, VERT1, VERT2, and SPOT. The attribute fields RADIUS1 and RADIUS2 are not supported by the Viewshed task. Fields OFFSETA and OFFSETB are available on the input observer feature set schema template if you are using the task in ArcMap. For additional explanation of using these fields to control your analysis, see Using Viewshed and Observer Points for visibility analysis.

  • The output viewshed is returned as polygon features. The field named Frequency is used to record the number of observation points that can see each polygon. The field named DEMResolution is used to record the source DEM resolution for the viewshed computation.

  • A lower DEM resolution will result in a faster response from the task. For example, the 90m resolution typically has the shortest response time. The tradeoff is that a lower DEM resolution has a lower accuracy in the viewshed result compared to that of a higher DEM resolution.

  • The MaximumDistance parameter may also affect the response time. In general, using a smaller distance results in a shorter response time.

  • The maximum number of input points is 1000. If additional input points are provided, the task will return an error and will not execute.

  • Using this task consumes credits. The rate of use is 1 credit per 1000 input features.

    For more information, see the Service Credits Overview.

Request Parameters

ParameterDescription

InputPoints

(Required)

The point features to use as the observer locations.

  • Type: Feature Set

  • Syntax:

    {
    "geometryType":"geometryType",
    "spatialReference":<spatialReference>,
    "fields":<fields>,
    "features":<features>,
    }

MaximumDistance

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

It is useful for modeling current weather conditions or a given time of day, such as dusk. Large values increase computation time.

Unless specified, a default maximum distance will be computed based on the resolution and extent of the source DEM. The allowed maximum value is 50 kilometers.

Use MaximumDistanceUnits to set the units for MaximumDistance.

  • Type: Double

MaximumDistanceUnits

The units for the MaximumDistance parameter.

  • Type: String

  • Values: Meters | Kilometers | Feet | Yards | Miles

  • Default: Meters

DEMResolution

The approximate spatial resolution (cell size) of the source elevation data used for the calculation.

The default is 90m.

The resolution values are an approximation of the spatial resolution of the digital elevation model. While many elevation sources are distributed in units of arc seconds, the keyword is an approximation of those resolutions in meters for easier understanding.

  • Type: String

  • Values: FINEST | 10m | 24m | 30m | 90m

ObserverHeight

This is the height above the ground of the observer locations.

The default is 1.75 meters, which is approximately the average height of a person. If you are looking from an elevated location, such as an observation tower or a tall building, use that height instead.

Use ObserverHeightUnits to set the units for ObserverHeight.

  • Type: Double

ObserverHeightUnits

The units for the ObserverHeight parameter.

  • Type: String

  • Values: Meters | Kilometers | Feet | Yards | Miles

  • Default: Meters

SurfaceOffset

The height above the surface of the object you are trying to see.

The default value is 0.0. If you are trying to see buildings or wind turbines, use their height here.

  • Type: Double

SurfaceOffsetUnits

The units for the SurfaceOffset parameter.

  • Type: String

  • Values: Meters | Kilometers | Feet | Yards | Miles

  • Default: Meters

GeneralizeViewshedPolygons

Determines whether or not the viewshed polygons are to be generalized.

The viewshed calculation is based on a raster elevation model that creates a result with stair-stepped edges. To create a more pleasing appearance and improve performance, the default behavior is to generalize the polygons. The generalization process smooths the boundary of the visible areas and may remove some single-cell visible areas.

  • Type: Boolean

  • Values: true | false

  • Default: True

Response

When you submit a request, the task assigns a unique job ID for the transaction.

Syntax:

{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}

After the initial request is submitted you can use the jobId to periodically check the status of the job and messages as described in the topic Checking job status for Elevation services. Once the job has successfully completed, use the jobId to retrieve the results. To track the status, you can make a request of the following form:

http://elevation.arcgis.com/arcgis/rest/services/Tools/Elevation/GPServer/Viewshed/jobs/<jobId>

Accessing results

When the status of the job request is esriJobSucceeded, you can access the results of the analysis by making a request of the following form:

http://elevation.arcgis.com/arcgis/rest/services/Tools/Elevation/GPServer/Viewshed/jobs/<jobId>/results/OutputViewshed?token=<your token>&f=json