Overview

Map camera

SDKs covered:
Navigation SDK
Navigation UI SDK

The Navigation SDK provides control over the map camera throughout the navigation app experience. This guide provides instructions on how to set the map camera using NavigationView and MapboxNavigation. You can find more details on how the map camera works in the Maps SDK for Android documentation.

Using the Navigation UI SDK, you can specify the initial camera position and update the camera position as the user progresses along the route or when the user interacts with the UI.

Set the initial camera position

You can initialize the NavigationView with a CameraPosition of your choice. This way, the MapView does not need to zoom in to the initial Location of the device from the world view.

CameraPosition initialPosition = new CameraPosition.Builder()
.target(new LatLng(ORIGIN.latitude(), ORIGIN.longitude()))
.zoom(INITIAL_ZOOM)
.build();
navigationView.initialize(this, initialPosition);

Update the camera position

Driven by DynamicCamera engine, the NavigationCamera holds all the logic needed to drive a MapboxMap camera that reacts and adjusts to the current progress along a DirectionsRoute.

To create an instance of NavigationCamera, you need a MapboxMap, MapboxNavigation, and LocationComponent object:

NavigationCamera camera = new NavigationCamera(mapboxMap, mapboxNavigation, locationComponent);
}

Calling NavigationCamera#start(DirectionsRoute route) will begin an animation to the start of the DirectionsRoute you provided:

camera.start(directionsRoute);
}

The NavigationCamera has two tracking modes: NAVIGATION_TRACKING_MODE_GPS and NAVIGATION_TRACKING_MODE_NORTH. They offer two different behaviors. 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 zero, so the camera will always be pointed north. To adjust these, use:

camera.updateCameraTrackingMode(NavigationCamera.NAVIGATION_TRACKING_MODE_NORTH);
}

NavigationCamera#showRouteOverview(int[] padding) will also adjust the camera to the bounds of the DirectionsRoute being traveled along with the given padding which is passed.

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

Custom camera engine

The Navigation SDK provides a SimpleCamera by default. You're also able to create your own CameraEngine and give it to the Navigation SDK like so: MapboxNavigation#setCameraEngine(CameraEngine cameraEngine).

Example

The DynamicCamera provided by the libandroid-navigation-ui library (described above) is an example of a custom CameraEngine. In DynamicCamera, calculations are being made based on the user's location along the given route.

MapboxNavigation creates a SimpleCamera by default that you can access with the MapboxNavigation#getCameraEngine() method. SimpleCamera extends from Camera and is required to provide values for bearing, tilt, zoom, and a target Point given a RouteInformation.

A RouteInformation object can be created from a DirectionsRoute, Location, or RouteProgress. Depending on which objects are provided, SimpleCamera will return a value for each camera method:

RouteInformation.create(route, location, routeProgress);

For example, if RouteInformation has a DirectionsRoute, the SimpleCamera will return the List of Points based on the route geometry for Camera#overview(RouteInformation routeInformation):

public List<Point> overview(RouteInformation routeInformation) {
...
if (invalidCoordinates) {
buildRouteCoordinatesFromRouteData(routeInformation);
}
return routeCoordinates;
}

You can then use the returned List to update the MapboxMap camera. In this case, you can use the list to build a LatLngBounds that the camera will move to include:

Camera cameraEngine = navigation.getCameraEngine();
List<Point> routePoints = cameraEngine.overview(routeInformation);
LatLngBounds routeBounds = ...
CameraUpdateFactory.newLatLngBounds(routeBounds, padding[0], padding[1], padding[2], padding[3]);
mapboxMap.easeCamera(CameraUpdateFactory.newCameraPosition(position));
Was this page helpful?