MapboxRouteLineApi

class MapboxRouteLineApi(routeLineOptions: MapboxRouteLineOptions)

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.

Parameters

routeLineOptions

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

Constructors

MapboxRouteLineApi
Link copied to clipboard
fun MapboxRouteLineApi(routeLineOptions: MapboxRouteLineOptions)
used for determining the appearance and/or behavior of the route line

Types

Companion
Link copied to clipboard
object Companion

Functions

cancel
Link copied to clipboard
fun cancel()
Cancels any/all background tasks that may be running.
clearRouteLine
Link copied to clipboard
fun clearRouteLine(consumer: MapboxNavigationConsumer<Expected<RouteLineError, RouteLineClearValue>>)
Clears the route line data.
equals
Link copied to clipboard
open operator fun equals(other: Any?): Boolean
findClosestRoute
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.
getPrimaryRoute
Link copied to clipboard
fun getPrimaryRoute(): DirectionsRoute?
getRouteDrawData
Link copied to clipboard
fun getRouteDrawData(consumer: MapboxNavigationConsumer<Expected<RouteLineError, RouteSetValue>>)
Gathers the data necessary to draw the route line(s) on the map based on the current state.
getRoutes
Link copied to clipboard
fun getRoutes(): List<DirectionsRoute>
getVanishPointOffset
Link copied to clipboard
fun getVanishPointOffset(): Double
hashCode
Link copied to clipboard
open fun hashCode(): Int
setRoutes
Link copied to clipboard
fun setRoutes(newRoutes: List<RouteLine>, consumer: MapboxNavigationConsumer<Expected<RouteLineError, RouteSetValue>>)
Sets the routes that will be operated on.
setVanishingOffset
Link copied to clipboard
fun setVanishingOffset(offset: Double): Expected<RouteLineError, RouteLineUpdateValue>
Sets the value of the vanishing point of the route line to the value specified.
showRouteWithLegIndexHighlighted
Link copied to clipboard
fun showRouteWithLegIndexHighlighted(legIndexToHighlight: Int, consumer: MapboxNavigationConsumer<Expected<RouteLineError, RouteLineUpdateValue>>)
If successful this method returns a RouteLineUpdateValue that when rendered will display the route line with the route leg indicated by the provided leg index highlighted.
toString
Link copied to clipboard
open fun toString(): String
updateTraveledRouteLine
Link copied to clipboard
fun updateTraveledRouteLine(point: Point): Expected<RouteLineError, RouteLineUpdateValue>
Indicates the point the route line should change from its default color to the vanishing color behind the puck.
updateWithRouteProgress
Link copied to clipboard
fun updateWithRouteProgress(routeProgress: RouteProgress, consumer: MapboxNavigationConsumer<Expected<RouteLineError, RouteLineUpdateValue>>)
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.

Extensions

clearRouteLine
Link copied to clipboard
suspend fun MapboxRouteLineApi.clearRouteLine(): Expected<RouteLineError, RouteLineClearValue>
Clears the route line data.
findClosestRoute
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.
getRouteDrawData
Link copied to clipboard
suspend fun MapboxRouteLineApi.getRouteDrawData(): Expected<RouteLineError, RouteSetValue>
setRoutes
Link copied to clipboard
suspend fun MapboxRouteLineApi.setRoutes(newRoutes: List<RouteLine>): Expected<RouteLineError, RouteSetValue>
Sets the routes that will be operated on.
showRouteWithLegIndexHighlighted
Link copied to clipboard
suspend fun MapboxRouteLineApi.showRouteWithLegIndexHighlighted(legIndex: Int): Expected<RouteLineError, RouteLineUpdateValue>
If successful this method returns a RouteLineUpdateValue that when rendered will display the route line with the route leg indicated by the provided leg index highlighted.