MapboxRouteLineApi

Responsible for generating route line related data which can be rendered on the map to visualize a line representing a route. The route related data returned should be rendered with the MapboxRouteLineView class. In addition to setting route data this class can be used to generate the data necessary to hide and show routes already drawn on the map and generally control the visual aspects of a route line.

The two principal classes for the route line are the MapboxRouteLineApi and the MapboxRouteLineView. The MapboxRouteLineApi consumes data produced by the Navigation SDK and produces data that can be used to visualize the data on the map. The MapboxRouteLineView consumes the data from the MapboxRouteLineApi and calls the appropriate map related commands to produce a line on the map representing one or more routes.

A simple example would involve an activity instantiating the MapboxRouteLineApi and MapboxRouteLineView classes and maintaining a reference to them. Both classes need a reference to an instance of MapboxRouteLineOptions. The default options can be used as a starting point so the simplest usage would look like:

MapboxRouteLineOptions mapboxRouteLineOptions = new MapboxRouteLineOptions.Builder(context).build();
MapboxRouteLineApi mapboxRouteLineApi = new MapboxRouteLineApi(mapboxRouteLineOptions);
MapboxRouteLineView mapboxRouteLineView = new MapboxRouteLineView(mapboxRouteLineOptions);

or

val mapboxRouteLineOptions = MapboxRouteLineOptions.Builder(context).build()
val mapboxRouteLineApi = MapboxRouteLineApi(mapboxRouteLineOptions)
val mapboxRouteLineView = MapboxRouteLineView(mapboxRouteLineOptions)

When one or more DirectionsRoute objects are retrieved from MapboxNavigation they can be displayed on the map by calling mapboxRouteLineApi.setRoutes() and then passing the object returned to the view class via MapboxRouteLineView.renderRouteDrawData which will draw the route(s) on the map. Note, if passing more than one route to the setRoutes method, the first route in the collection will be considered the primary route.

Calls to the MapboxRouteLineView.renderRouteDrawData command always take the current MapboxMap object as an argument. It is important to ensure the Style object is always current. If the application changes the map style at runtime the new Style should be passed as an argument to the render method following the style change.

Each Layer added to the map by this MapboxRouteLineView is a persistent layer - it will survive style changes. This means that if the data has not changed, it does not have to be manually redrawn after a style change. See Style.addPersistentStyleLayer.

In order to display traffic congestion indications on the route line it is necessary to request routes with specific RouteOptions. At a minimum the following options are necessary:

val routeOptions = RouteOptions.builder()
    .baseUrl(Constants.BASE_API_URL)
    .user(Constants.MAPBOX_USER)
    .profile(DirectionsCriteria.PROFILE_DRIVING_TRAFFIC)
    .overview(DirectionsCriteria.OVERVIEW_FULL)
    .steps(true)
    .annotationsList(
        listOf(
            DirectionsCriteria.ANNOTATION_CONGESTION_NUMERIC,
            DirectionsCriteria.ANNOTATION_DURATION,
            DirectionsCriteria.ANNOTATION_DISTANCE,
        )
    )
    .requestUuid("")
    .accessToken("mapToken")
    .coordinatesList(listOf(origin, destination))
    .build()

A good starting point might be RouteOptions.Builder.applyDefaultNavigationOptions() which will include the options above.

Vanishing Route Line: The "vanishing route line" is a feature which changes the appearance of the route line behind the puck to a specific color or makes it transparent. This creates a visual difference between the section of the route that has been traveled and the section that has yet to be traveled. In order to enable and use this feature do the following:

1. Enable the feature in the MapboxRouteLineOptions

MapboxRouteLineOptions.Builder(context)
.withVanishingRouteLineEnabled(true)
.build()

1. Register an OnIndicatorPositionChangedListener with the LocationComponentPluginImpl:

mapView.getPlugin(LocationComponentPluginImpl.class).addOnIndicatorPositionChangedListener(myIndicatorPositionChangedListener)

(Be sure to unregister this listener appropriately according to the lifecycle of your activity or Fragment in order to prevent resource leaks.)

1. In your OnIndicatorPositionChangedListener implementation update the MapboxRouteLineApi with the Point provided by the listener and render the state returned by MapboxRouteLineApi.

val vanishingRouteLineData = mapboxRouteLineApi.updateTraveledRouteLine(point)
if (vanishingRouteLineData != null && mapboxMap.getStyle() != null) {
mapboxRouteLineView.renderRouteLineUpdate(mapboxMap.getStyle(), vanishingRouteLineData);
}

1. Register a RouteProgressObserver with MapboxNavigation and pass the data to the MapboxRouteLineApi (Be sure to unregister this listener appropriately according to the lifecycle of your activity or Fragment in order to prevent resource leaks.)

override fun onRouteProgressChanged(routeProgress: RouteProgress) {
mapboxRouteLineApi.updateWithRouteProgress(routeProgress) { result ->
mapboxRouteLineView.renderRouteLineUpdate(mapboxMap.getStyle(), result)
}

In order to keep the point on the route line indicating traveled vs not traveled in sync with the puck, data from both OnIndicatorPositionChangedListener and the RouteProgressObserver are needed.