ArcGIS Runtime SDK for macOS

Analyze visibility in a scene view

Visibility analysis means determining which areas or specific features are visible from a hypothetical observer (location, heading, field of view, and so on). This can help answer questions like: Which apartments have a view of the beach? Which areas of the forest are visible from a car driving through it? Does anything block the view between my office window and my parking spot?

For evaluating visibility in a scene view, ArcGIS Runtime provides AGSViewshed and AGSLineOfSight classes. Viewshed analysis highlights areas in the scene that are visible from a given observer. Line of sight shows which segments are visible along a line drawn between an observer and a target location. In either type of analysis, the observer may be moving or stationary.

For visibility analysis, elevation surfaces, scene layers (buildings, for example), and 3D graphics (such as models) are considered obstructions to visibility. Billboarded (flat) graphics, such as text and simple graphics are not considered in the analysis. Visibility analysis is reactive, meaning that as data are added to (or removed from) the scene, visibility will be reevaluated and updated dynamically in the display.

Scene analyses versus geoprocessing

At version 100.2, ArcGIS Runtime introduced analysis and analysis overlay classes to provide fast and dynamic (but strictly visual) analysis results in a scene view. The AGSAnalysis classes (including the visibility analysis classes described in this topic) allow you to define analyses to be performed using data in the current scene, then render results that are updated dynamically (as layers are added or removed, features are updated, camera position changes, and so on). Analysis results are displayed using an analysis overlay. For more information about working with analysis overlays, see Manage analysis with analysis overlays.

Scene analyses produce results that are strictly visual, rendered dynamically and quickly by the GPU. As analyses are evaluated, results are rendered in the scene view for display only. This is ideal for use cases that require interactive and visual evaluation of results that change frequently. However, there are no features (such as graphics) or output geometry produced, so use cases like persisting result shapes or performing hit tests with other features are not supported.

Scene analysis uses the data currently available in the scene view to perform analysis (evaluate visibility, for example) and then quickly render the result. Since the data in the scene view changes according to the level of detail (distance of the camera to the surface, in other words), the analysis results may change as you interact with the scene view (zoom in or out, change camera tilt, and so on). Resolution of surface elevation data varies according to level of detail and for visibility analysis will affect the result, as shown in the following image.

Level of detail affects viewshed results

Geoprocessing provides another way to perform analysis using a suite of specialized GIS analysis tools that run on a service. The results returned from geoprocessing vary by task, but may include a map image, output features, raster images, data files, and so on. Geoprocessing usually gives you the ability to access the resulting features (or geometry) from the task, allowing you to save your results or use them for further analysis (find all the points inside the visible area, for example). Geoprocessing generally requires several inputs from the client, and takes some time to execute and return results from the server. See the Geoprocessing topic to learn more.

As a general guide, scene analysis allows you to interactively explore data visually, but lacks accuracy and does not provide tangible results. Geoprocessing provides better accuracy, gives you more control over the analysis, and can provide result features or geometry, but is not well suited for quickly and interactively exploring a variety of scenarios.

Viewshed analysis

Viewsheds are a type of visibility analysis that show the visible and obstructed areas within a directed field of view. Viewshed analysis shows you the areas of the scene that are visible from a given observer, determined by the terrain (represented by an elevation surface), buildings and other 3D features (represented by scene layers, graphics, and so on), and the properties of the observer.

The 3D shape inside which visibility is evaluated is called the frustum. The frustum is defined by the observer's location, horizontal and vertical angles of vision, heading, pitch, and so on. You can think of the frustum as the full volume being evaluated within the observer's field of vision.

Frustum and the settings that define it

The following properties define the frustum:

  • Heading—a value in degrees (azimuth) that defines the direction of the observer's line of vision. This is the direction of the center of the frustum. The value is normalized to between 0 - 360.
  • Minimum distance—the distance (meters) from the observer at which viewshed analysis begins.
  • Maximum distance—the distance (meters) from the observer beyond which the viewshed is not evaluated.
  • Horizontal angle—an angle that defines the observer's horizontal field of vision. The angle is split evenly on the right and left sides of the heading. This value must be greater than zero to produce a valid frustum, and no greater than the maximum of 360 degrees.
  • Vertical angle—an angle that defines the observer's vertical field of vision. The angle is split evenly on the top and bottom sides of the heading. This value must be greater than zero to produce a valid frustum, and no greater than the maximum of 360 degrees.
  • Pitch—the angle of the observer's tilt relative to the surface. Pitch does not affect the shape of the frustum, but tilts it relative to the surface. Pitch values must be between 0 (looking straight down towards the center of the earth) and 180 (looking straight up).
Note:

The area between the observer and the near plane of the frustum (defined by the minimum distance) is not included in the viewshed analysis. If an object exists in that area (a building or hill, for example), it will not be considered an obstruction to visibility. In other words, only the space represented by the frustum is analyzed for visibility. In general, the minimum distance value should be used to prevent nearby objects from interfering with the analysis (such as the corner of a building, for example) and should be relatively small. However, you could use a larger minimum distance to answer questions like "what would the view from my window be like if the neighbor's house wasn't there?".

The frustum can be displayed as part of the viewshed analysis result, which may be helpful for troubleshooting or verifying the observer properties. To toggle the visibility of the frustum on or off, use the IsFrustumOutlineVisible property. The default frustum outline symbol is a fully opaque blue line, but you can specify a custom color if you like. The frustum color you provide will be applied to all viewshed analyses in the scene view.

Viewshed results are displayed as two visual classes in the scene view: one representing visible areas, and one representing areas of obstructed visibility. By default, these are rendered green and red respectively, but you can specify your own colors. Areas that are not symbolized for visibility are outside of the frustum and therefore not evaluated. In the image below, the green areas are visible and the red areas are obstructed. Everything else is outside of the frustum.

As with the frustum color, the colors you provide for visible and obstructed areas will be applied to all viewshed analyses in your scene view. These colors cannot be set individually on each analysis, in other words. If adding several viewshed analyses to your scene view, transparency in your visibility colors will help visualize overlapping areas by making them appear darker.

Caution:

A scene view can support a limited number of viewshed analyses. The actual number will vary according to the available memory on your device and the size of viewshed frustums but will typically be between three and seven for mobile devices and up to fifteen or so on a desktop machine. If you exceed the number of viewsheds your device can display, they will cease rendering in the scene view.

Viewshed result for a portion of a city

The observer for viewshed analysis may be represented by a point (x, y, and z coordinate values) or by a AGSGeoElement with point geometry.

Location viewshed

Use the AGSLocationViewshed to define the observer using a point location. You also need to provide heading, pitch, and roll, the vertical and horizontal angles of vision, and minimum/maximum distance of the viewshed analysis to define the frustum. You can dynamically update the observer for the viewshed using a camera object that encapsulates these properties of an observer.

To add AGSLocationViewshed analysis to your scene view:

  1. Create a new AGSLocationViewshed. In the constructor, pass values that define the observer (frustum): location, heading, pitch, horizontal and vertical angles, and the minimum and maximum distance. Optionally, you could create a camera to represent the observer, and pass that to the constructor along with minimum and maximum distance.
  2. (Optional) Assign custom colors for analysis results: visible areas, obstructed areas, and frustum. To show the frustum in the results, set IsFrustumOutlineVisible to true.
  3. Add the analysis to an AGSAnalysisOverlay to display the results (as described in the Manage analyses with analysis overlays topic).
  4. You may update the analysis after it's associated with your scene view by changing the observer position or result colors. A convenience method allows you to update the observer using a camera.
Location viewshed with frustum

GeoElement viewshed

You may want to see a viewshed for an observer whose location, heading, or pitch update frequently. For example, you may want to display a viewshed for the pilot of a search plane as it flies over the terrain. As an element representing the aircraft changes its position in the scene view, you'd like the viewshed result to update accordingly. This can be accomplished using AGSGeoElementViewshed scene analysis, which takes a AGSGeoElement (of point geometry type) to define the observer's position. Since the viewshed is based on the AGSGeoElement, any change in its position (location, heading, pitch, and so on) will update the viewshed result. You can also specify offset values for the observer relative to the element. This is useful for more accurately representing an observer position inside a moving craft, for example.

Note:

A AGSGeoElement can be a AGSFeature or a AGSGraphic. See Features and graphics for more information.

To add a AGSGeoElementViewshed analysis to your scene view:

  1. Create a point AGSGeoElement to represent the observer in the viewshed. Add the element to the scene view.
  2. Create a new AGSGeoElementViewshed. In the constructor, define the observer by passing in the AGSGeoElement, horizontal and vertical field of view, minimum and maximum distance, and heading and pitch offsets.
  3. [Optional] Define offset values to define the X, Y, and Z location of the observer relative to the element. These offsets are defined in meters using a coordinate system relative to the center of the object, where X is to the right or left, Y is forward or back, and Z is up and down. To place an observer in the driver's seat of a car, for example, you might place her 60 centimeters from the left of the car center, 70 centimeters forward from center, and 40 centimeters above the center. These offset values would be (-0.6, 0.7, 0.4).
  4. (Optional) Provide custom colors for analysis results: visible areas, obstructed areas, and frustum. To show the frustum in the results, set IsFrustumOutlineVisible to true.
  5. Add the analysis to an AGSAnalysisOverlay to display the results (as described in the Manage analyses with analysis overlays topic).

As the position of the AGSGeoElement changes, the viewshed results will update accordingly.

Viewshed results for a moving graphic

Line of sight analysis

Line of sight analysis shows visibility along a line drawn between an observer and a target location. The result shows which segments of the line can be seen by the observer and which segments are blocked by an obstruction. In the image below, the cyan segment of the line is the portion of the sight line that is not blocked, while the magenta segments are obstructed by the terrain (and therefore not visible).

Line of sight analysis between two locations

In addition to visible and obstructed line segments, you may see portions of the line that have an unknown visibility state. These are lines drawn in gray to indicate that visibility cannot be reliably evaluated with the currently available data. For example, visibility may become unknown if the camera position is changed such that the target and/or observer for the line of sight are no longer displayed. In that situation, data outside the visible display may have been unloaded from the scene. The unloaded data may have contained obstructions to the line of sight that are no longer present. Obstructed lines, however, may still render as obstructed when the target or observer moves off the display, since the obstruction is assumed to still exist even if the data have unloaded.

A line of sight analysis represents a single line from observer to target. To make sight lines from multiple vantage points, you must create multiple analysis instances. A group of related line of site analyses (for the same observer, for example) can be managed in a single analysis overlay (see the Manage analyses with analysis overlays topic).

Caution:

A scene view is restricted to a maximum of sixty-four line of sight analyses. Be aware of performance considerations when adding many analyses to a scene view.

Location line of sight

Use the AGSLocationLineOfSight to define the observer and target using point locations. You can then handle the TargetVisibilityChanged event to receive a notification each time the target becomes visible or obstructed from the observer.

To add a AGSLocationLineOfSight analysis to your scene view:

  1. Create map points to define the location of the observer and target in the line of sight analysis.

  2. Create a new AGSLocationLineOfSight. In the constructor, provide the points that define the observer and target.

  3. (Optional) Assign custom colors for the analysis results: visible and obstructed line segments. The colors you assign will be used for all line of sight analyses in the scene view.

  4. Add the analysis to an AGSAnalysisOverlay to display the results (as described in the Manage analyses with analysis overlays topic).
  5. Add an observer to identify when the target visibility changes.

Location line of sight is generally used for evaluating visibility between a fixed observer and target, although those locations could be updated. Other factors in the scene view could also change the target visibility, such as adding or removing 3D features or updating surface data.

GeoElement line of sight

A more dynamic approach for evaluating line of sight is to use a AGSGeoElementLineOfSight analysis. This analyzes visibility between point geoelements that represent the observer and target. As the position of these elements is updated (from a GPS feed, for example), the line of sight result will also be updated. As with the AGSLocationLineOfsight analysis, you can handle the TargetVisibilityChanged event to receive a notification each time the target becomes visible or obstructed. In the following image, for example, the target geoelement is selected when it becomes visible and unselected when it's obstructed.

Target geoelement is selected when visible

Note:

Geo elements used to define an observer and target in a geo element line of sight analysis must have point geometry.

To add a GeoElementLineOfSight analysis to your scene view:

  1. Create a new AGSGeoElementLineOfSight. In the constructor, define the observer and target by passing in geo elements (with point geometry) that define their location.

  2. (Optional) Define offset values to apply to the observer and/or target locations (x, y, z). These offsets are defined in meters using a coordinate system relative to the center of the object, where X is to the right or left, Y is forward or back, and Z is up and down. To place an observer in the driver's seat of a car, for example, you might place her 60 centimeters from the left of the car center, 70 centimeters forward from center, and 40 centimeters above the center. These offset values would be (-0.6, 0.7, 0.4).

  3. (Optional) Assign custom colors for analysis results: visible and obstructed line segments. These are green and red by default.

  4. Add the analysis to an AGSAnalysisOverlay to display the results (as described in the Manage analyses with analysis overlays topic).
  5. Add an observer to identify when the target visibility changes.

Lines of sight for a moving GeoElement