Follow a graphic in a scene view

Graphics can represent dynamic objects in the scene. A service might provide near real-time locations for a fleet of vehicles, for example. Your device might read GPS information and display your current location as a graphic, or you might simply animate graphics on the scene view by reading a hard-coded list of geographic coordinates. For these use cases, there are two ways in which your user might want to visualize moving graphics in a scene view. They might want to view several graphics at once as they interactively explore the entire scene, or they might want to continuously focus the camera relative to a specific element and track it as it moves through the scene. Your app might even allow the user to interact both ways, sometimes selecting a particular graphic to follow, and then switching to explore the entire scene.

Visualize dynamic graphics in a scene

A scene view uses the concept of a camera and a focal point to display data in three dimensions. The camera represents the location of the observer in three-dimensional space (x, y, z), and the camera's focal point is the location that intersects the camera's line of sight. By default, a scene view allows the user to interactively change the camera position to center on a focal point of their choice. However, you may need to set the camera's focal point relative to a specific graphic or location in the scene view. In the case of a moving graphics, you may want to continuously update the camera to maintain focus on a particular graphic as it moves through the scene.

To simplify the code required to keep the camera in sync with a moving graphic, ArcGIS Runtime provides a CameraController to implement this behavior.

Note:

A camera controller does not honor obstacles (such as terrain, extruded buildings, or other graphics) as it follows a graphic. In other words, the camera does not move to avoid such obstacles as it follows a graphic.

Prepare your graphics

To ensure your graphics can be tracked and properly displayed using the method described in this topic, follow these guidelines:

  • Graphics you want to follow should have attributes to store the current heading, pitch, and roll.
  • Each graphics overlay containing graphics you want to follow should have a renderer assigned.
  • The graphics overlay renderer should have heading, pitch, and roll expressions defined in the renderer scene properties. These expressions should use the corresponding graphic attributes.
  • The graphics overlay that contains the graphic to follow must be added to the scene view.
Note:

Renderer scene property expressions can use hard-coded values, but they usually contain the name of an attribute. For example, the expression [heading] + 3.5 indicates that the renderer will add 3.5 to the value of the attribute named heading for each graphic in the graphics overlay. When referring to attributes in an expression, the attribute name should be in square brackets, such as [heading].

You may need to adjust the heading, pitch, and roll properties on your symbol to make sure its initial appearance is correct.

The following example creates a graphics overlay with the appropriate scene properties, adds a single point graphic to it, and then adds it to the scene view. The graphic is now ready to follow in the scene.

// create a new simple renderer and apply the scene properties that use the corresponding graphic attribute names
SimpleRenderer graphicsRenderer = new SimpleRenderer();
graphicsRenderer.getSceneProperties().setHeadingExpression("[Heading]");
graphicsRenderer.getSceneProperties().setPitchExpression("[Pitch]");
graphicsRenderer.getSceneProperties().setRollExpression("[Roll]");

// create a new graphics overlay, define absolute placement of graphics, and apply the renderer
GraphicsOverlay followGraphicsOverlay = new GraphicsOverlay();
followGraphicsOverlay.getSceneProperties().setSurfacePlacement(SurfacePlacement.ABSOLUTE);
followGraphicsOverlay.setRenderer(graphicsRenderer);

// create a plane graphic to track
Point startPoint = new Point(-117.00, 31.50, 2000, SpatialReferences.getWgs84());
Graphic planeGraphic = new Graphic(startPoint, planeSymbol);
planeGraphic.getAttributes().put("Heading", 270.0);
planeGraphic.getAttributes().put("Pitch", 45.0);
planeGraphic.getAttributes().put("Roll", 12.0);

// add the graphic to the overlay
followGraphicsOverlay.getGraphics().add(planeGraphic);

// add the graphics overlay to the scene view
sceneView.getGraphicsOverlays().add(followGraphicsOverlay);

Update graphic position

When using a camera controller to follow a graphic, update the position of the graphic and the camera updates its location accordingly. Provide a new Point for the graphic's geometry, and update the heading, pitch, and roll attributes as needed. The graphics overlay renderer (and associated scene properties) controls updating the display of the graphic's heading, pitch, and roll.

This code updates the geometry and attributes of the graphic being tracked.

planeGraphic.setGeometry(newPoint);
planeGraphic.getAttributes().put("Heading", newHeading);
planeGraphic.getAttributes().put("Pitch", newPitch);
planeGraphic.getAttributes().put("Roll", newRoll);

Camera controllers

A scene view has an associated controller that manages the camera for the scene. Each type of camera controller is designed to provide a specific user experience for interacting with the scene display. The camera controller and its properties can be changed at run time, so your app can provide the scene interaction experience best suited for the current context.

ArcGIS Runtime SDK provides the following camera controllers:

  • GlobeCameraController (default) —Provides the default scene view camera behavior. Allows the user to freely move and focus the camera anywhere in the scene.
  • OrbitGeoElementCameraController—Locks the scene view's camera to maintain focus relative to a (possibly moving) graphic. The camera can only move relative to the target graphic.
  • OrbitLocationCameraController—Locks the scene view's camera to orbit a fixed location (map point). The camera can only move relative to the target map point.

When any camera controller other than GlobeCameraController is active, the scene view's viewpoint cannot be assigned. Attempts to do so do not raise an exception, but they are ignored.

Note:

At this release, OrbitGeoElementCameraController works only with graphics.

Use a camera controller to follow a graphic

The OrbitGeoElementCameraController updates the camera focal point relative to a specified (stationary or moving) graphic. As the user interacts with the scene view, the scene view's camera follows a focal point specified by the target graphic. Using this controller, the camera moves in sync with the target.

Note:

By default, the target graphic is also the camera focal point. The focal point can also be placed relative to the target graphic by applying offsets. See Adjust the display for details.

Using a camera controller to follow a moving airplane graphic

The following example creates a new OrbitGeoElementCameraController and assigns it to the SceneView. The Graphic to follow is passed to the object's constructor, along with the initial distance from the target to the camera. By default, the camera is positioned with a heading of 0 and a pitch of 45 degrees. See Adjust the display for information about modifying camera settings.

// create an OrbitGeoElementCameraController, pass in the target graphic and initial camera distance
OrbitGeoElementCameraController orbitGraphicController = new OrbitGeoElementCameraController(planeGraphic, 1000);
sceneView.setCameraController(orbitGraphicController);

The graphic associated with an OrbitGeoElementCameraController cannot be changed after the controller is initialized. To follow another graphic, you must create a new OrbitGeoElementCameraController for the other graphic and set it as the scene view's camera controller.

Adjust the display

Although the OrbitGeoElementCameraController locks the camera to a target graphic, the exact location of the camera in relation to the target can be adjusted using offset values. Other aspects of the scene display can also be modified, such as whether or not the camera should automatically adjust its heading, pitch, and roll when those values change in the tracked graphic. Adjustments to the camera display, as well as limiting user interaction with the scene view, can be changed dynamically at run time.

Camera target offsets

The position of the camera focal point relative to the target graphic can be adjusted using x, y, and z target offsets. This allows you to make precise adjustments to the display of the scene, for example, placing the camera inside the cockpit of an airplane graphic. These offsets can be assigned individually or applied at once using an animation.X, y, and z offsets for a camera target

The following example applies offsets for the OrbitGeoElementCameraController.

// set the x, y, and z camera target offsets (animate change over 2 seconds)
orbitGraphicController.setTargetOffsetsAsync(43, 0, -55, 2);

You can also use TargetVerticalScreenFactor to adjust the vertical position of the target in the display. Acceptable values range from 0 (bottom of the display) to 1 (top of the display). The default is 0.5, which places the target in the center of the display.

Auto heading, pitch, and roll

Auto heading, when enabled for the camera controller, means that the camera will rotate to follow changes in the graphic's heading and therefore provide a consistent view of the graphic. When auto heading is disabled, the camera remains at a constant heading and the graphic may appear to rotate as its heading changes.

Auto pitch and auto roll have similar effects. When enabled, the camera rotates with the target's pitch or roll and the surface appears to rotate around the graphic, as shown on the left in the following image. When disabled, the camera is not affected by changes in the graphic's pitch or roll.

Auto roll enabled (left) and disabled (right) for a graphic with a 270-degree roll

These settings are true by default.

  • AutoHeadingEnabled
  • AutoPitchEnabled
  • AutoRollEnabled

Move the camera

While the OrbitGeoElementCameraController is associated with the scene view, the camera can be moved relative to the target graphic (either programmatically or interactively).

  • Camera distance—The distance in meters between the camera and its target. The camera position is derived from this distance plus the camera offsets.
  • Camera heading offset—The clockwise angle measured in the target element symbol's horizontal plane starting directly behind the symbol (default is 0). Any angle in degrees is valid but will be normalized between the minimum and maximum camera heading offsets. If after normalization the value is outside of the allowed range, the nearest value within the range will be used.
  • Camera pitch offset—The counterclockwise angle from the positive z-axis of the target element's symbol relative to the symbol's horizontal plane, as illustrated in the following image (default is 45). If the value specified is outside of the range defined by the minimum and maximum camera pitch offsets, the nearest value within the range will be used.

The following example moves the camera using the OrbitGeoElementCameraController.

// update camera position: delta values for distance, heading, pitch, and roll (animate change over 2 seconds)
orbitGraphicController.moveCameraAsync(300, 0, 45, 2);

Note:

You can also change the offset properties individually as an alternative to using the moveCameraAsync method.

Limit user interaction

When using an OrbitGeoElementCameraController or OrbitLocationCameraController, you can define minimum and maximum values for the camera distance, heading, pitch, and roll properties if you want to further restrict user interaction with the scene view. User interactions and scene view animations obey these limits.

Tip:

Since the camera controllers don't recognize obstacles (for example, terrain) when tracking a graphic, limiting or restricting the possible camera positions can help avoid them.

The following example limits the distance and pitch for the camera, but not the heading.

// limit the camera distance to between 1,000 and 10,000 meters
orbitGraphicController.setMinCameraDistance(1000);
orbitGraphicController.setMaxCameraDistance(10000);
// limit the camera pitch to between 25 and 75 degrees
orbitGraphicController.setMinCameraPitchOffset(25);
orbitGraphicController.setMaxCameraPitchOffset(75);

Types of scene view interaction can also be completely disabled if needed. You may want the user to interact with the scene view by changing the camera heading and pitch, but not the camera distance, for example.

The following code disables the ability for the user to modify the camera distance when interacting with the scene view.

// restrict the ability to interactively change the camera distance
orbitGraphicController.setCameraDistanceInteractive(false);

Stop following a graphic

To stop following a graphic, reset the scene view's camera controller to the default, GlobeCameraController.

In general, the only time you need to assign this camera controller to the scene view is to return to the default behavior after applying one of the nondefault controllers.

The following code applies a new GlobeCameraController to the SceneView.

// apply the (default) globe camera controller
sceneView.setCameraController(new GlobeCameraController());

The globe camera controller allows the user to interactively change the camera position, focal point, and any of the camera properties. Use this controller to let your user freely explore the scene. See Navigate a scene view for more information about interacting with a scene view using the globe camera controller.