Map camera

A newer version of the Navigation SDK is available

This page uses v1.6.2 of the Mapbox Navigation SDK. A newer version of the SDK is available. Learn about the latest version, v2.21.0, in the Navigation SDK documentation.

The map camera refers to the on-screen field of view above the map. The camera can be tilted, rotated, zoomed. This guide provides instructions on adjusting the map camera for a navigation experience.

The core Navigation SDK doesn't have any code related to manipulating the map camera. You can combine navigation logic with the Maps SDK's MapboxMap and its camera logic to adjust the camera based on some navigation-related action.

For example, you can change the camera inside the onRoutesReady() callback in the Navigation SDK's RoutesRequestCallback interface:

 private val routesReqCallback = object : RoutesRequestCallback {
    override fun onRoutesReady(routes: List<DirectionsRoute>) {

        mapboxMap.moveCamera(CameraUpdateFactory.zoomTo(15.0))

    }

    override fun onRoutesRequestFailure(throwable: Throwable, routeOptions: RouteOptions) {

    }

    override fun onRoutesRequestCanceled(routeOptions: RouteOptions) {

    }
}

EXAMPLE

Basic Navigation SDK integration

See how to combine the Maps SDK with only the Navigation SDK.

mobile Navigation UI SDK

The Navigation UI SDK has several camera-related classes:

Camera

Camera is an abstract class and the lowest level class related to the camera. It provides methods for subclasses that eventually calculate the camera's zoom and tilt values during the turn-by-turn navigation experience.

SimpleCamera

SimpleCamera extends the Camera class and has more navigation logic than the Camera class does. It also holds the default zoom and tilt values used elsewhere in the Navigation UI SDK.

If you would like to customize the camera properties, create a concrete implementation of Camera class or SimpleCamera and update navigationMapboxMap.setCamera() or NavigationViewOptions.builder().camera().

DynamicCamera

DynamicCamera extends SimpleCamera and is the main camera engine used by the Navigation UI SDK. DynamicCamera is dynamic because its logic responds to the realtime navigation situation. It:

• Creates a tilt value based on the distance remaining for the LegStep.
• Creates a zoom value based on LatLngBounds that include the current location and upcoming maneuver location.

These tilt and zoom values are always slightly adjusting as the device navigates along the route, instead of a constant static tilt and zoom values.

NavigationCamera

The NavigationCamera class is the main manager of camera logic in the Navigation UI SDK. Because it's driven by the DynamicCamera engine, the NavigationCamera also reacts and adjusts to the information in the RouteProgress object as the device moves along a DirectionsRoute.

Using NavigationMapboxMap

Although you can create a NavigationCamera object (explained below this note) and use its methods, it's much better to let NavigationMapboxMap handle the NavigationCamera itself. Once the NavigationMapboxMap is created, you have various camera-related methods available to you, such asnavigationMapboxMap.startCamera(directionsRoute), which animates the camera to the start location of the DirectionsRoute you provided. navigationMapboxMap.addOnCameraTrackingChangedListener() is helpful to detect camera tracking is dismissed or the camera mode is updated.navigationMapboxMap.retrieveCamera() retrieves the NavigationCamera for you if you directly need the NavigationCamera.

To create an instance of NavigationCamera, you need at least a MapboxMap object.

val navigationCamera = NavigationCamera(mapboxMap)

Now that you have a NavigationCamera object, you can run its various methods including:

• showRouteOverview(int[] padding) will also adjust the camera to the bounds of the DirectionsRoute being traveled along with the given padding which is passed.
• resetCameraPositonWith(NAVIGATION_TRACKING_MODE_GPS) will reset the camera to the last known position update and will resume tracking of future updates with the mode you pass - in this case, tracking will resume with GPS tracking.
• updateCameraTrackingMode(NavigationCamera.NAVIGATION_TRACKING_MODE_NORTH). The NavigationCamera has the NAVIGATION_TRACKING_MODE_GPS and NAVIGATION_TRACKING_MODE_NORTH tracking modes. MODE_GPS follows the Location updates from the device based on the values provided by DynamicCamera. MODE_NORTH does the same, but with a bearing that is always 0.0, so that the camera will always be pointed north.

Custom NavigationView camera

The NavigationViewOptions's builder has a .camera() method, which lets you set custom camera logic for the NavigationView. Pass the method a concrete implementation of the abstract Camera class or your custom class that extends Camera. Your custom camera class can extend SimpleCamera or DynamicCamera because SimpleCamera or DynamicCamera extend the Camera class.

val optionsBuilder = NavigationViewOptions.builder()

optionsBuilder.camera(customCamera)                

navigationView.startNavigation(optionsBuilder.build())