# Navigate a scene

In many ways, navigating a scene is similar to navigating a map. Both offer the ability to zoom in and out, and to pan the display. The three-dimensional display of a scene, however, adds some additional options for visualization. To fully understand navigating the display in three dimensions, you must understand the fundamentals of how a scene displays.

To display data in three dimensions, a scene uses the concept of a camera and a target. The camera represents the location of the observer in three-dimensional space (x,y,z) and the target is the location on the 3D surface that intersects the camera's line of sight. You can think of viewing a map in these same terms, where the camera is always perpendicular to the target on the two-dimensional surface. Bringing the camera closer has the effect of zooming in. Moving it further away zooms out. Likewise, panning moves the center of the map (the target) to a new location.

In addition to moving nearer or further relative to the target, in three-dimensional visualization, you can change the pitch, heading, and elevation of the camera (observer) to produce a different perspective of the data.

The following characteristics of the camera are taken into account when displaying a three-dimensional scene.

• Location (target) on the surface (x,y coordinates)
• Heading from the camera location (on the surface) to the target
• Elevation (z-coordinate)
• Pitch (tilt) relative to the surface

Navigation operations in a scene work by modifying one or several of the camera characteristics described previously.

• Zoom in and out—Moves the camera towards or away from the target along the line of sight. This also moves the camera location closer to the target along the direction of the heading while decreasing the elevation.
• Pan—Moves the camera to a new x,y location (without changing other properties).
• Pitch—Changes the angle of the camera relative to the surface.
• Rotate—Changes the camera location on the surface (x,y) and the camera heading without moving the target (or changing pitch or elevation). In other words, the target is the center point around which the entire scene rotates.
##### Note:

Changing the heading property of the camera is like turning it in a horizontal plane (that is, left or right). It turns the scene centered on the camera location and therefore changes the location of the target. Rotating turns the scene while centered on the target, which has the effect of changing the camera heading and x,y location but not the location of the target. Walking around the Eiffel Tower to view it from various perspectives is analogous to rotating a scene. By contrast, standing in one place and scanning the Paris skyline is like changing the heading without moving the camera.

The SceneView control has built-in interactions for mouse, touch, and keyboard that implement these operations for the user.

The following table summarizes the built-in navigation capabilities of the SceneView control. See the Navigate the map topic for the interaction capabilities built into MapView.

Pan

• Hold left button and drag
• Drag
• Flick
• Arrow keys

Zoom in

• Scroll wheel forward
• Hold center button and drag
• +

Zoom out

• Scroll wheel backward
• Hold center button and drag
• Pinch
• -
• Insert: zoom to initial extent

Rotate

• Hold right button and drag
• Multiple finger hold and twist

Change pitch

• Multiple fingers drag up/down
• W: tilt up
• S: tilt down
• P: perpendicular to surface

• Multiple fingers drag left/right
• A: move west
• D: move east
• N: set to true north

Change elevation

• U: move up
• J: move down

### Customize interaction options

Certain aspects of the built-in scene view navigation described in the previous section can be modified. The SceneInteractionOptions class contains properties that let you do things like enable or disable certain types of input (keyboard, mouse, touch, and so on), apply an inertia factor for panning, or set the direction of the mouse wheel for zooming.

To define the types of input to accept from the user, set the EnabledInputs property using one or more of the following values from the InteractionInputs enumeration.

• InteractionInputs.Touch
• InteractionInputs.Stylus
• InteractionInputs.Mouse
• InteractionInputs.Keyboard
• InteractionInputs.All
• InteractionInputs.None

The following example enables only touch and keyboard input for the scene view by setting the appropriate values for EnabledInputs.

``````// create a new SceneInteractionOptions
var interactionOptions = new SceneInteractionOptions();
// set the enabled inputs; use the bitwise OR (|) operator to define several inputs
interactionOptions.EnabledInputs = InteractionInputs.Keyboard | InteractionInputs.Touch;

// apply the interaction options to the scene view
MySceneView.InteractionOptions = interactionOptions;``````

The MouseWheelZoomInDirection property allows you to define the mouse wheel scroll direction used for zooming in to (and out of) the scene and ZoomFactor sets the factor for zooming, as shown in the following example.

``````// create a new SceneInteractionOptions
var interactionOptions = new SceneInteractionOptions();
// set the mouse wheel direction for zooming in the scene
interactionOptions.MouseWheelZoomInDirection = MouseWheelDirection.Backward;
// set the factor used for default zoom operations (mouse wheel click, key press, etc.)
interactionOptions.ZoomFactor = 10;

// apply the interaction options to the scene view
MySceneView.InteractionOptions = interactionOptions;``````

The FlickInertia property allows you to specify an inertia factor when panning the scene with a flick gesture, as shown in the following example. A factor of 0, which is the default value, disables inertia when panning.

``````// create a new SceneInteractionOptions
var interactionOptions = new SceneInteractionOptions();
// set the inertia factor when panning (flicking) the scene
interactionOptions.FlickInertia = 10;

// apply the interaction options to the scene view
MySceneView.InteractionOptions = interactionOptions;``````

### Navigate with the mouse

The SceneView control provides built-in support for navigating a scene using the mouse. The following list describes how mouse controls map to navigation operations.

• Left button + drag—Pan
• Right button + drag—Rotate
• Middle button + drag—Zoom in and out
• Mouse wheel—Zoom in and out

### Navigate with touch

The SceneView control provides built-in support for navigating a scene using touch.

There are three navigation modes available using touch: single finger pan, multiple finger zoom and pan, and multiple finger rotate and pitch. Place one finger on the display to use single finger pan. Spread, pinch, or drag two or more fingers on the display to enter pan and zoom mode, or place multiple fingers on the display at a consistent distance to navigate in heading and pitch mode. The following list describes the touch gestures used to execute navigation operations in each mode.

• Pan mode (single finger)
• Drag—Pans
• Flick—Pans
• Pan and zoom mode (multiple fingers)
• Pinch—Zooms out
• Drag—Pans
• Pivot—Rotates
• Heading and pitch mode (multiple fingers)
• Drag up and down—Changes pitch
• Drag left and right—Changes heading
##### Tip:

If the desired navigation gesture is not initially recognized, remove your fingers and replace them on the display.

### Keyboard shortcuts

The SceneView control provides built-in support for navigating a scene using keyboard input. The following list describes the keys that can be used to execute navigation operations.

• Arrow keys (up, down, right, left)—Pan (north, south, east, west)
• Q + mouse—Fly mode (combination pan and rotate based on mouse position)
• W, S—Change pitch
• U, J—Elevation
• P—Moves pitch to perpendicular to the surface
• N—Moves the heading to north
• Insert—Zooms to initial extent

## Pan interactively

Most often, when panning a scene using touch or mouse, the location you start panning from will be anchored to the pointer as you drag. You will find certain contexts, however, where the pan interaction behaves significantly differently. The exceptions to the usual pan behavior described in this section are built into the scene view to ensure a better experience for certain types of interaction.

### Pan near or beyond the horizon

To ensure a smooth panning experience, the scene will pan at a constant rate and will not be anchored to the pointer as the pan location nears (or goes beyond) the horizon. The following example illustrates a scenario in which you panning will start with a map location anchored to the pointer then unanchor when the horizon is approached.

Click a location on the scene and hold.

Move the pointer (the mouse or your finger, in other words) and this location follows the pointer as you pan.

Continue to pan in a single direction until the pointer crosses the horizon (into space, in other words). As the pointer nears the horizon, the original location is unanchored from the pointer and the scene now pans at a consistent rate as you move. This prevents the scene from panning too quickly or erratically near the horizon, where a short distance on the display represents a large distance on the scene (a small scale, in other words).

Bring the pointer back within the scene (inside the horizon), and the pointer will again anchor to a location on the map (but probably not the original one).

### Elevate or pan

If you click or tap a location on the surface that is within a tolerance of the horizon and drag the pointer forward or back, the camera increases or decreases elevation rather than panning. Moving the pointer left and right, however, pans with the pointer anchored to the point. Clicks outside of the horizon area will start a pan operation as described in the section above. The following images illustrate clicking near the horizon and dragging down to elevate the camera.

##### Note:

The tolerance for clicks near the horizon (instantiating an elevate operation, in other words) is defined using a 5º angle from the horizon towards the camera target. The ability to elevate the camera from a click near the horizon is not available when the scene is displayed at a relatively small scale (displaying a larger area, in other words).

## Set camera position programmatically

The Camera class gives you fine-grained control over the position of the observer in your scene. Using the Camera, you can control elevation, heading, pitch, and so on to provide a particular view of the scene. The following example gets the camera from the SceneView, defines a new heading and pitch, then applies the new camera to the scene.

``````// get the camera used for the initial display of the scene
var initialCamera = MySceneView.Camera;

// create a new camera by rotating and tilting the initial one

// apply the new camera to the scene
await MySceneView.SetViewAsync(rotatedCamera);``````

The following methods are available to manipulate the characteristics of a Camera. These are useful for defining a new camera relative to an existing one. Each of these methods returns a new Camera object that can then be applied to the scene using SceneView.SetViewAsync.

• Elevate—apply a delta elevation value to the current z-coordinate value.
• MoveForward—move the camera a delta distance (meters) along the line of sight to the target.
• MoveToward—move the camera a specified distance (meters) towards a specified location (point).
• Rotate—apply a delta heading and delta pitch relative to the current camera.
• RotateAround—apply a delta heading and delta pitch relative to a specified location (point).
• SetLocation—specify an absolute location (point).
• SetPitch—specify an absolute pitch angle.
• ZoomToward—zoom the camera towards or away from a specified location (point) at a specified zoom factor.

A Camera can also be created new, as shown in the following example. The constructor allows you to define values for location (x, y, z coordinates), heading, and pitch.

``````var camera = new Esri.ArcGISRuntime.Controls.Camera(centerLatitude, centerLongitude, headingDegrees, pitchAngle);
await MySceneView.SetViewAsync(camera, animationVelocity, showLiftOff);``````

##### Tip:

You can animate the updated camera as it is applied to the scene using an appropriate overload of SceneView.SetViewAsync.

### Work with view points

The concepts of extent and scale only have real meaning when applied to two-dimensional maps. In three dimensions, scale is continuous across the scene. Areas that are closer to the camera display at a larger scale and the scale decreases as you move further away (towards the horizon, for example). Similarly, although there is obviously a visible area displayed in a scene, it usually cannot be represented as an Envelope, as the extent is in a two-dimensional map.

Despite the differences with how geographic space is defined in a map versus a scene, they both implement a Viewpoint object to describe the area currently displayed. The Viewpoint.Camera property is used to set the display in a scene view, but is ignored when used in a map view.

A new view point can be created using only a geometry, a geometry and a scale value, a geometry and a camera, or several other combinations of geometry, camera, rotation, scale and so on. You can get the current view point for a scene or map view using the ViewBase.GetCurrentViewpoint method. Likewise, a view point can be applied to a scene or map view using the ViewBase.SetViewAsync method.

The Viewpoint class is used by both map view and scene view controls to display a specified geographic location. If you need to synchronize the area displayed between a scene view and map view in your app, you can pass Viewpoint objects between these controls. The Camera property is ignored for two-dimensional display and is null for view points returned from a map view. If applied to a scene view, however, the camera will be created using the other information available from the view point.

The following example defines a view point using a camera, target geometry, and rotation then applies it to a scene view and map view.

``````// define a new camera over Paris
var camera = new Camera(48.8636, 2.2816, 330.0, 126.0, 73.0);
// create a ViewPoint with the camera, a target geometry (Envelope), and rotation (same as camera heading)
var viewPoint = new Viewpoint(camera, new Envelope(2.2552, 48.7973, 2.4897, 48.8942, SpatialReferences.Wgs84),126.0);
var animationDuration = new TimeSpan(0, 0, 2);

// apply the view point to a scene view and map view (animate the change in the scene view)
await MySceneView.SetViewAsync(viewPoint, animationDuration, true);
await MyMapView.SetViewAsync(viewPoint);``````

The SceneView control raises CameraChanged and NavigationCompleted events. In general, NavigationCompleted is the best event to handle if you want to respond each time the user navigates the scene. The CameraChanged event is much more granular and may fire several times for a single navigation operation.

The following code handles the NavigationCompleted event to get information about the current camera position.

``````private async void MySceneView_NavigationCompleted(object sender, EventArgs e)
{
// get the camera used to render the current scene
var camera = MySceneView.Camera;

// get info about the camera
var latitude = camera.Location.Y;
var longitude = camera.Location.X;
var pitch = camera.Pitch;