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 point the camera at 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.

A CameraController is provided to simplify the code required to keep the camera in sync with a moving 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.

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

You can create a graphics overlay with the appropriate scene properties, add a single point graphic to it, and then add it to a scene view. The graphic m_graphic3d would then be ready to follow in the scene.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Create a new graphics overlay and add it to the SceneView
GraphicsOverlay* sceneOverlay = new GraphicsOverlay(this);
sceneOverlay->setSceneProperties(LayerSceneProperties(SurfacePlacement::Absolute));
m_sceneView->graphicsOverlays()->append(sceneOverlay);

// This renderer applies each Graphic's attributes for heading, pitch, and
// roll to orient the model in space
SimpleRenderer* renderer3D = new SimpleRenderer(this);
RendererSceneProperties renderProperties = renderer3D->sceneProperties();
renderProperties.setHeadingExpression(QString("[%1]").arg(HEADING));
renderProperties.setPitchExpression(QString("[%1]").arg(PITCH));
renderProperties.setRollExpression(QString("[%1]").arg(ROLL));
renderer3D->setSceneProperties(renderProperties);
sceneOverlay->setRenderer(renderer3D);

// Create the ModelSceneSymbol to be followed
if (!m_model3d)
{
  float modelScale = 10.0;
  m_model3d = new ModelSceneSymbol(QUrl(m_dataPath + "/Bristol/Collada/Bristol.dae"),
                                   modelScale, this);
}

if (!m_graphic3d)
{
  // Create a graphic using the model scene symbol
  m_graphic3d = new Graphic(Point(-117.10, 34.085, 1600.0,
                            m_sceneView->spatialReference()),
                            m_model3d, this);
  m_graphic3d->attributes()->insertAttribute(HEADING, 270.0);
  m_graphic3d->attributes()->insertAttribute(PITCH, -15.0); // relative to ground
  m_graphic3d->attributes()->insertAttribute(ROLL, 0.0);

  // Add the graphic to the graphics overlay
  m_sceneView->graphicsOverlays()->at(0)->graphics()->append(m_graphic3d);
}

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.

1
2
3
4
5
6
7
// Move 3D graphic to the new position
m_graphic3d->setGeometry(Point(lon, lat, elevation, m_sceneView->spatialReference()));

// Update attribute expressions to immediately update rotation
m_graphic3d->attributes()->replaceAttribute(HEADING, heading);
m_graphic3d->attributes()->replaceAttribute(PITCH, pitch);
m_graphic3d->attributes()->replaceAttribute(ROLL, roll);

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.

The following camera controllers are provided:

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

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.

You could create a new OrbitGeoElementCameraController and assign 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.

1
2
3
4
5
// Create the camera controller to follow the graphic
double distanceFromTarget=500.0; // meters
m_followingController = new OrbitGeoElementCameraController(m_graphic3d, distanceFromTarget, this);
resetOffsetsOnFollowingController(); // Set offsets to starting values
m_sceneView->setCameraController(m_followingController);

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 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 how to limit 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.

You can apply offsets for the OrbitGeoElementCameraController.

1
2
m_followingController->setCameraPitchOffset(angle);
m_followingController->setCameraDistance(zoomDist);

You can also use OrbitGeoElementCameraController::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.

These settings are true by default:

• OrbitGeoElementCameraController::isAutoHeadingEnabled
• OrbitGeoElementCameraController::isAutoPitchEnabled
• OrbitGeoElementCameraController::isAutoRollEnabled

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.

You can move the camera using the OrbitGeoElementCameraController.

1
2
3
4
5
double distanceDelta = 0.0; // meters
double headingDelta = 45.0; // degrees
double pitchDelta = 0.0;    // degrees
float  duration = 2.0;      // seconds
m_followingController->moveCamera(distanceDelta, headingDelta, pitchDelta, duration);

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.

You could limit the distance and pitch for the camera, but not the heading.

1
2
3
4
5
6
7
// limit the camera distance
m_followingController->setMinCameraDistance(500.0);  // meters
m_followingController->setMaxCameraDistance(1000.0); // meters

// limit the camera pitch
m_followingController->setMinCameraPitchOffset(45.0); // degrees
m_followingController->setMinCameraPitchOffset(75.0); // degrees

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.

You could disable the ability for the user to modify the camera distance when interacting with the scene view.

1
2
// restrict the ability to interactively change the camera distance
m_followingController->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 non-default controllers.

You can apply a new GlobeCameraController to the SceneView.

1
m_sceneView->setCameraController(new GlobeCameraController()); // Use free-roaming controller

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.