MapboxNavigationViewportDataSource

class MapboxNavigationViewportDataSource(mapboxMap: MapboxMap) : ViewportDataSource

Default implementation of ViewportDataSource to use with the NavigationCamera.

Use:

  • onRouteChanged to produce overview geometries that need to be framed

  • onRouteProgressChanged (requires also onRouteChanged) to produce following geometries of the current step and overview geometries of the remaining points on the route that need to be framed. This will make the frame in following mode change zoom level depending on the proximity to the upcoming maneuver and resize the frame in overview mode to fit only the remaining portion of the route.

  • onLocationChanged to pass a point to be framed and used as a source of bearing for the following camera frame

  • additionalPointsToFrameForFollowing - points that also need to be visible in the following camera frame

  • additionalPointsToFrameForOverview - points that also need to be visible in the overview camera frame

Whenever a set of these arguments is provided or refreshed, you need to call evaluate to process the data and compute an opinionated ViewportData update that NavigationCamera observes and applies.

Based on the provided data, the class will make decisions on how the camera should be framed. However, that might not always match with your expectations or needs. Let’s imagine that you would like to temporarily zoom in (when the user double-tapped the map) or change the camera’s bearing to focus on a POI. To serve those use-cases, all of the camera property values that this data source produces can be overridden. The source will keep producing the default, opinionated values, but as long as the override is present, they won’t be used. Passing null as an override resets it to the default value.

The class also offers various mutable options that can be modified at any point in time to influence the style of frames that are produced. Make sure to get familiar with all of the public nested fields and their documentation in MapboxNavigationViewportDataSourceOptions. The options can be mutated by accessing options field.

Whenever any changes are made to the data source (new values provided, overrides added/removed, or options changed), remember to call evaluate to recompute frames and notify observers.

Padding and framing behavior

This data source initializes at the null island (0.0, 0.0). Make sure to first provide at least onLocationChanged for following mode framing and onRouteChanged for overview mode framing (or the additionalPointsToFrameForOverview and additionalPointsToFrameForFollowing).

Overview

overviewPadding is used to generate the correct zoom level while positioning the contents on screen and is also applied to the resulting default ViewportData.cameraForOverview. The default bearing for overview framing is north (0.0).

Following

followingPadding is used to generate the correct zoom level while positioning the contents on screen but the padding value is not applied the ViewportData.cameraForFollowing. Instead, the frame contains a specific CameraOptions.padding value that manipulates the vanishing point of the camera to provide a better experience for end users when the camera is pitched.

This vanishing point change cannot be recovered from automatically without impacting the camera position. That's why, if you use the MapboxNavigationViewportDataSource, you should explicitly define CameraOptions.padding in all other transition that your app is running. The side-effect of not recovering from the vanishing point change can be the center of the camera that's offset from the center of the MapView.

When following frame is used, the first point of the framed geometry list will be placed at the bottom edge of this padding, centered horizontally. This typically refers to the user's location provided via onLocationChanged, if available. This can be influenced by FollowingFrameOptions.maximizeViewableGeometryWhenPitchZero when there are at least 2 points available for framing.

The geometries that are below the bottom edge of the following padding on screen (based on camera's bearing) are ignored and not being framed. It's impossible to find a zoom level that would fit geometries that are below the vanishing point of the camera, since the vanishing point is placed at the bottom edge of the provided padding.

The default pitch for following frames is FollowingFrameOptions.defaultPitch and zoom is determined based on upcoming geometries or FollowingFrameOptions.maxZoom.

Debugging

This feature is currently experimental an subject to change.

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 NavigationCamera.debugger.

Examples

Show route overview with padding

private val routesObserver = object : RoutesObserver {
override fun onRoutesChanged(result: RoutesUpdatedResult) {
if (result.navigationRoutes.isNotEmpty()) {
viewportDataSource.onRouteChanged(routes.first())
viewportDataSource.overviewPadding = overviewEdgeInsets
viewportDataSource.evaluate()
navigationCamera.requestNavigationCameraToOverview()
} else {
navigationCamera.clearRouteData()
}
}
}

Update current location

private val locationObserver = object : LocationObserver {
override fun onNewRawLocation(rawLocation: Location) {
// no impl
}
override fun onNewLocationMatcherResult(locationMatcherResult: LocationMatcherResult) {
viewportDataSource.onLocationChanged(locationMatcherResult.enhancedLocation)
viewportDataSource.evaluate()
}
}

Update route progress

private val routeProgressObserver = object : RouteProgressObserver {
override fun onRouteProgressChanged(routeProgress: RouteProgress) {
viewportDataSource.onRouteProgressChanged(routeProgress)
viewportDataSource.evaluate()
}
}

Request state to following with padding

viewportDataSource.onLocationChanged(enhancedLocation)
viewportDataSource.followingPadding = followingEdgeInsets
viewportDataSource.evaluate()
navigationCamera.requestNavigationCameraToFollowing()

Update current location and reset frame

private val locationObserver = object : LocationObserver {
override fun onNewRawLocation(rawLocation: Location) {}
override fun onNewLocationMatcherResult(locationMatcherResult: LocationMatcherResult) {
viewportDataSource.onLocationChanged(locationMatcherResult.enhancedLocation)
viewportDataSource.evaluate()
if (locationMatcherResult.isTeleport) {
navigationCamera.resetFrame()
}
}
}

Run your own animation to a POI

private fun animateToPOI() {
// request camera to idle first or use `NavigationBasicGesturesHandler` or `NavigationScaleGestureHandler`
mapView.camera.flyTo(
CameraOptions.Builder()
.padding(edgeInsets)
.center(point)
.bearing(0.0)
.zoom(14.0)
.pitch(0.0)
.build(),
MapAnimationOptions.mapAnimationOptions {
duration(1000L)
}
)
}

Constructors

Link copied to clipboard
fun MapboxNavigationViewportDataSource(mapboxMap: MapboxMap)

Functions

Link copied to clipboard
fun additionalPointsToFrameForFollowing(points: List<Point>)

Provide additional points that should be fitted into the following frame update.

Link copied to clipboard
fun additionalPointsToFrameForOverview(points: List<Point>)

Provide additional points that should be fitted into the overview frame update.

Link copied to clipboard
fun clearFollowingOverrides()

Helper method that clears all user-set overrides for camera properties when in following.

Link copied to clipboard
fun clearOverviewOverrides()

Helper method that clears all user-set overrides for camera properties when in overview.

Link copied to clipboard
fun clearRouteData()

Clears all data associated with onRouteChanged and onRouteProgressChanged calls.

Link copied to clipboard
fun evaluate()

Computes ViewportData based on the available data, saves the value, and notifies the ViewportDataSourceUpdateObservers.

Link copied to clipboard
fun followingBearingPropertyOverride(value: Double?)

Whenever evaluate is called, the source produces ViewportData updates with opinionated values for all camera properties.

Link copied to clipboard
fun followingCenterPropertyOverride(value: Point?)

Whenever evaluate is called, the source produces ViewportData updates with opinionated values for all camera properties.

Link copied to clipboard
fun followingPitchPropertyOverride(value: Double?)

Whenever evaluate is called, the source produces ViewportData updates with opinionated values for all camera properties.

Link copied to clipboard
fun followingZoomPropertyOverride(value: Double?)

Whenever evaluate is called, the source produces ViewportData updates with opinionated values for all camera properties.

Link copied to clipboard
open override fun getViewportData(): ViewportData

Get the latest ViewportData.

Link copied to clipboard
fun onLocationChanged(location: Location)

Call whenever new user location is available.

Link copied to clipboard
fun onRouteChanged(route: NavigationRoute)

Call whenever the primary route changes. This produces and stores geometries that need to be framed for overview.

Link copied to clipboard
fun onRouteProgressChanged(routeProgress: RouteProgress)

Call whenever RouteProgress changes to produce following geometries of the current step and overview geometries of the remaining points on the route that need to be framed. This will make the following frame change zoom level and pitch depending on the proximity to the upcoming maneuver and resize overview to fit only remaining portion of the route.

Link copied to clipboard
fun overviewBearingPropertyOverride(value: Double?)

Whenever evaluate is called, the source produces ViewportData updates with opinionated values for all camera properties.

Link copied to clipboard
fun overviewCenterPropertyOverride(value: Point?)

Whenever evaluate is called, the source produces ViewportData updates with opinionated values for all camera properties.

Link copied to clipboard
fun overviewPitchPropertyOverride(value: Double?)

Whenever evaluate is called, the source produces ViewportData updates with opinionated values for all camera properties.

Link copied to clipboard
fun overviewZoomPropertyOverride(value: Double?)

Whenever evaluate is called, the source produces ViewportData updates with opinionated values for all camera properties.

Link copied to clipboard
open override fun registerUpdateObserver(viewportDataSourceUpdateObserver: ViewportDataSourceUpdateObserver)

Register an observer that gets called whenever the available ViewportData changes. The observer also gets notified with latest data on registration.

Link copied to clipboard
open override fun unregisterUpdateObserver(viewportDataSourceUpdateObserver: ViewportDataSourceUpdateObserver)

Properties

Link copied to clipboard
Link copied to clipboard
var followingPadding: EdgeInsets

Holds a padding (in pixels, in reference to the MapView's size) used for generating a following frame.

Link copied to clipboard
val options: MapboxNavigationViewportDataSourceOptions

Holds options that impact generation of camera frames.

Link copied to clipboard
var overviewPadding: EdgeInsets

Holds a padding (in pixels, in reference to the MapView's size) used for generating an overview frame.