NavigationCamera

NavigationCamera is a class that tries to simplify management of the Map's camera object in typical navigation scenarios. It's fed camera frames via the ViewportDataSource, generates transitions with NavigationCameraStateTransition and executes them.

NavigationCamera's lifecycle can't exceed the lifecycle of the MapboxMap (or indirectly MapView) that it's attached to without risking reference leaks.

States

The NavigationCamera is an entity that offers to maintain 3 distinct NavigationCameraStates: IDLE, FOLLOWING, and OVERVIEW. States can be requested at any point in runtime.

When the camera is transitioning between states, it reports that status with TRANSITION_TO_FOLLOWING and TRANSITION_TO_OVERVIEW helper states. These helper transition states cannot be directly requested.

Change to IDLE state is always instantaneous.

Data

In order to be able to perform state transitions or later frame updates, the NavigationCamera needs data. This is provided by the ViewportDataSource argument. The source is an observable interface that produces CameraOptions that frame the camera for both FOLLOWING and OVERVIEW states.

On creation, NavigationCamera subscribes to the data source and listens for updates.

MapboxNavigationViewportDataSource is a default implementation of the source that helps to generate camera frames based on the current route’s geometry, road's graph, trip's progress, etc.

Transitions

When NavigationCamera is supplied with data and a state request, it invokes the NavigationCameraStateTransition that generates a set of Map SDK CameraAnimators that perform the transition to the desired camera position created by the data source.

When a state is requested, NavigationCamera takes the latest computed ViewportData values and passes them to the NavigationCameraStateTransition to create the NavigationCameraStateTransition.transitionToFollowing or NavigationCameraStateTransition.transitionToOverview transitions.

When NavigationCamera already is in one of the FOLLOWING or OVERVIEW states, data source updates trigger creation of NavigationCameraStateTransition.updateFrameForFollowing or NavigationCameraStateTransition.updateFrameForOverview transitions.

After generating the transitions, NavigationCamera handles registering them to Maps SDK, executing, listening for cancellation, adjusting states, etc.

Gestures and other camera interactions

When FOLLOWING or OVERVIEW states are engaged, the NavigationCamera assumes full ownership of the CameraAnimationsPlugin. This means that if any other camera transition is scheduled outside of the NavigationCamera’s context, there might be side-effects or glitches. Consequently, if you want to perform other camera transitions, first call requestNavigationCameraToIdle, and only after that perform the desired transition.

Alternatively, you can use one of the default implementations of CameraAnimationsLifecycleListener that automate the response of the NavigationCamera for gesture interactions and other camera animations:

• NavigationBasicGesturesHandler transitions NavigationCamera to NavigationCameraState.IDLE when any camera transitions outside of the NavigationCamera context is started.

• NavigationScaleGestureHandler behaves as above, but allows for executing various scale gestures to manipulate the camera's zoom level when in NavigationCameraState.FOLLOWING without immediately falling back to NavigationCameraState.IDLE.

Debugging

If you are using the MapboxNavigationViewportDataSource instance, you can use debugger to provide a MapboxNavigationViewportDataSourceDebugger instance which will draw various info on the screen when the NavigationCamera operates to together with the MapboxNavigationViewportDataSource.

Make sure to also provide the same instance to MapboxNavigationViewportDataSource.debugger.