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:
Enable the feature in the MapboxRouteLineOptions
MapboxRouteLineOptions.Builder(context)
.withVanishingRouteLineEnabled(true)
.build()
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.)
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);
}
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
used for determining the appearance and/or behavior of the route line
Constructors
Types
Functions
Clears the route line data.
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.
Gathers the data necessary to draw the route line(s) on the map based on the current state.
Sets the routes that will be operated on.
Sets the routes that will be operated on.
Replaces the traffic back fill road classes derived from RouteLineResources.
Sets the routes that will be operated on.
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 MapboxRouteLineOptions.
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. All the other legs will only show a simple line with RouteLineColorResources.inActiveRouteLegsColor.
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 MapboxRouteLineOptions.
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
Clears the route line data.
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.
Sets the routes that will be operated on.
Sets the routes that will be operated on.
Sets the routes that will be operated on.
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. All the other legs will only show a simple line with RouteLineColorResources.inActiveRouteLegsColor.