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 options objects to be configured. The default options can be used as a starting point so the simplest usage would look like:

MapboxRouteLineApiOptions mapboxRouteLineApiOptions = new MapboxRouteLineApiOptions.Builder().build();
MapboxRouteLineViewOptions mapboxRouteLineViewOptions = new MapboxRouteLineViewOptions.Builder(context).build();
MapboxRouteLineApi mapboxRouteLineApi = new MapboxRouteLineApi(mapboxRouteLineApiOptions);
MapboxRouteLineView mapboxRouteLineView = new MapboxRouteLineView(mapboxRouteLineViewOptions);

or

val mapboxRouteLineApiOptions = MapboxRouteLineApiOptions.Builder().build()
val mapboxRouteLineViewOptions = MapboxRouteLineViewOptions.Builder(context).build()
val mapboxRouteLineApi = MapboxRouteLineApi(mapboxRouteLineApiOptions)
val mapboxRouteLineView = MapboxRouteLineView(mapboxRouteLineViewOptions)

Note that it's possible to have one instance of MapboxRouteLineApi and multiple instances of MapboxRouteLineView that will consume the data from the same MapboxRouteLineApi. Those MapboxRouteLineView might have different styling configurations.

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,
)
)
.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 MapboxRouteLineApiOptions

MapboxRouteLineApiOptions.Builder()
.vanishingRouteLineEnabled(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.

Parameters

routeLineOptions

used for determining the appearance and/or behavior of the route line

Constructors

Link copied to clipboard
constructor(options: MapboxRouteLineApiOptions)

Creates an instance of MapboxRouteLineApi.

Types

Link copied to clipboard
object Companion

Functions

Link copied to clipboard
fun cancel()

Cancels any/all background tasks that may be running.

Link copied to clipboard

Clears the route line data.

Link copied to clipboard

Clears the route line data.

Link copied to clipboard
fun findClosestRoute(target: Point, mapboxMap: MapboxMap, padding: Float, resultConsumer: MapboxNavigationConsumer<Expected<RouteNotFound, ClosestRouteValue>>)

The map will be queried for a route line feature at the target point or a bounding box centered at the target point with a padding value determining the box's size. If a route feature is found the index of that route in this class's route collection is returned. The primary route is given precedence if more than one route is found.

Link copied to clipboard
suspend fun MapboxRouteLineApi.findClosestRoute(target: Point, mapboxMap: MapboxMap, padding: Float): Expected<RouteNotFound, ClosestRouteValue>

The map will be queried for a route line feature at the target point or a bounding box centered at the target point with a padding value determining the box's size. If a route feature is found the index of that route in this class's route collection is returned. The primary route is given precedence if more than one route is found.

Link copied to clipboard
Link copied to clipboard

Gathers the data necessary to draw the route line(s) on the map based on the current state.

Link copied to clipboard
Link copied to clipboard
Link copied to clipboard
fun setNavigationRouteLines(newRoutes: List<NavigationRouteLine>, activeLegIndex: Int, alternativeRoutesMetadata: List<AlternativeRouteMetadata>, consumer: MapboxNavigationConsumer<Expected<RouteLineError, RouteSetValue>>)

Sets the routes that will be operated on.

Link copied to clipboard
suspend fun MapboxRouteLineApi.setNavigationRouteLines(newRoutes: List<NavigationRouteLine>, activeLegIndex: Int, alternativeRoutesMetadata: List<AlternativeRouteMetadata>): Expected<RouteLineError, RouteSetValue>

Sets the routes that will be operated on.

Link copied to clipboard
fun setNavigationRoutes(newRoutes: List<NavigationRoute>, activeLegIndex: Int, consumer: MapboxNavigationConsumer<Expected<RouteLineError, RouteSetValue>>)
fun setNavigationRoutes(newRoutes: List<NavigationRoute>, activeLegIndex: Int, alternativeRoutesMetadata: List<AlternativeRouteMetadata>, consumer: MapboxNavigationConsumer<Expected<RouteLineError, RouteSetValue>>)

Sets the routes that will be operated on.

Link copied to clipboard
suspend fun MapboxRouteLineApi.setNavigationRoutes(newRoutes: List<NavigationRoute>, activeLegIndex: Int): Expected<RouteLineError, RouteSetValue>
suspend fun MapboxRouteLineApi.setNavigationRoutes(newRoutes: List<NavigationRoute>, activeLegIndex: Int, alternativeRoutesMetadata: List<AlternativeRouteMetadata>): Expected<RouteLineError, RouteSetValue>

Sets the routes that will be operated on.

Link copied to clipboard
fun setRoadClasses(roadClasses: List<String>)

Replaces the traffic back fill road classes derived from MapboxRouteLineApiOptions.

Link copied to clipboard

Sets the value of the vanishing point of the route line to the value specified. This is used for the vanishing route line feature and is only applicable only if the feature was enabled in the MapboxRouteLineApiOptions.

Link copied to clipboard

Indicates the point the route line should change from its default color to the vanishing color behind the puck. Calling this method has no effect if the vanishing route line feature was not enabled in the MapboxRouteLineApiOptions.

Link copied to clipboard

Updates the state of the route line based on data in the RouteProgress passing a result to the consumer that should be rendered by the MapboxRouteLineView.