com.mapbox.services.android.navigation.v5

Class RouteUtils

java.lang.Object

com.mapbox.services.android.navigation.v5.RouteUtils

public class RouteUtils
extends java.lang.Object

A few utilities to work with RouteLeg objects.

This is an experimental API. Experimental APIs are quickly evolving and might change or be removed in minor versions.

Since:

0.1.0

Field Summary

Fields

Modifier and Type	Field and Description
static double	DEFAULT_OFF_ROUTE_THRESHOLD_KM

Constructor Summary

Constructors

Constructor and Description
RouteUtils() Deprecated. All methods in RouteUtils are now static.
RouteUtils(double offRouteThresholdKm) Deprecated. All methods in RouteUtils are now static.

Method Summary

Modifier and Type	Method and Description
static int	getClosestStep(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg) Get the closest routeLeg step to the given position.
static double	getDistanceToEndOfRoute(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.DirectionsRoute route, int geometryPrecision, java.lang.String units) Measures from the provided position (typically the user location), to the end of a DirectionsRoute.
static double	getDistanceToEndOfRoute(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.DirectionsRoute route, java.lang.String units) Measures from the provided position (typically the user location), to the end of a DirectionsRoute.
static double	getDistanceToNextLeg(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg, java.lang.String units, int geometryPrecision) Measures the distance from a position to the end of the given RouteLeg.
static double	getDistanceToNextStep(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg, int stepIndex) Measures the distance from a position to the end of the route step.
static double	getDistanceToNextStep(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg, int stepIndex, java.lang.String units) Measures the distance from a position to the end of the route step.
static double	getDistanceToNextStep(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg, int stepIndex, java.lang.String units, int geometryPrecision) Measures the distance from a position to the end of the route step.
static double	getDistanceToStep(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg, int stepIndex) Computes the distance between the position and the closest point in routeLeg step.
static com.mapbox.services.commons.geojson.LineString	getGeometryRemainingOnRoute(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.DirectionsRoute route) Get the remaining route geometry from the position provided to the end of the directions route.
static com.mapbox.services.commons.geojson.LineString	getGeometryRemainingOnRoute(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.DirectionsRoute route, int geometryPrecision) Get the remaining route geometry from the position provided to the end of the directions route.
double	getOffRouteThresholdKm() Deprecated. All methods in RouteUtils are now static.
static com.mapbox.services.commons.models.Position	getSnapToRoute(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg, int stepIndex) Snaps given position to a RouteLeg step.
static com.mapbox.services.commons.models.Position	getSnapToRoute(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg, int stepIndex, int geometryPrecision) Snaps given position to a RouteLeg step.
boolean	isInStep(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg, int stepIndex) Deprecated. use the static equivalent of this method.
static boolean	isInStep(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg, int stepIndex, double threshold) Compute the distance between the position and the step line (the closest point), and checks if it's within the off-route threshold.
boolean	isOffRoute(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg) Deprecated. Use the new static isOffRoute() method.
static boolean	isOffRoute(com.mapbox.services.commons.models.Position position, com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg, double threshold) Method to check whether the position given is outside the routeLeg using the threshold.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_OFF_ROUTE_THRESHOLD_KM

public static final double DEFAULT_OFF_ROUTE_THRESHOLD_KM

See Also:

Constant Field Values

Constructor Detail

RouteUtils

@Deprecated
public RouteUtils()

Deprecated. All methods in RouteUtils are now static.

RouteUtils constructor using default threshold of 100 meters.

Since:

0.1.0

RouteUtils

@Deprecated
public RouteUtils(double offRouteThresholdKm)

Deprecated. All methods in RouteUtils are now static.

RouteUtils constructor allowing you to pass in a threshold value.

Parameters:

offRouteThresholdKm - Double value using unit kilometers. This value determines the distance till you are notified.

Since:

0.1.0

Method Detail

getOffRouteThresholdKm

@Deprecated
public double getOffRouteThresholdKm()

Deprecated. All methods in RouteUtils are now static.

Returns:

the RouteUtils threshold as a double value; defaults 100 meters.

Since:

0.1.0

isInStep

@Deprecated
public boolean isInStep(com.mapbox.services.commons.models.Position position,
                                    com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg,
                                    int stepIndex)
                             throws com.mapbox.services.api.ServicesException,
                                    com.mapbox.services.api.utils.turf.TurfException

Deprecated. use the static equivalent of this method.

Compute the distance between the position and the step line (the closest point), and checks if it's within the off-route threshold.

Parameters:

position - you want to verify is on or near the routeLeg step. If using for navigation, this would typically be the users current location.

routeLeg - a directions routeLeg.

stepIndex - integer index for step in routeLeg.

Returns:

true if the position is outside the OffRoute threshold.

Throws:

com.mapbox.services.api.ServicesException - if error occurs Mapbox API related.

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0

isInStep

public static boolean isInStep(com.mapbox.services.commons.models.Position position,
                               com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg,
                               int stepIndex,
                               double threshold)

Compute the distance between the position and the step line (the closest point), and checks if it's within the off-route threshold.

Parameters:

position - you want to verify is on or near the routeLeg step. If using for navigation, this would typically be the users current location.

routeLeg - a directions routeLeg.

stepIndex - integer index for step in routeLeg.

Returns:

true if the position is outside the OffRoute threshold.

Since:

0.1.0

getDistanceToStep

public static double getDistanceToStep(com.mapbox.services.commons.models.Position position,
                                       com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg,
                                       int stepIndex)
                                throws com.mapbox.services.api.ServicesException,
                                       com.mapbox.services.api.utils.turf.TurfException

Computes the distance between the position and the closest point in routeLeg step.

Parameters:

position - you want to measure distance to from route. If using for navigation, this would typically be the users current location.

routeLeg - a directions routeLeg.

stepIndex - integer index for step in routeLeg.

Returns:

double value giving distance in kilometers.

Throws:

com.mapbox.services.api.ServicesException - if error occurs Mapbox API related.

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0

getDistanceToNextStep

public static double getDistanceToNextStep(com.mapbox.services.commons.models.Position position,
                                           com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg,
                                           int stepIndex)
                                    throws com.mapbox.services.api.ServicesException,
                                           com.mapbox.services.api.utils.turf.TurfException

Measures the distance from a position to the end of the route step. The position provided is snapped to the route before distance is calculated.

Parameters:

position - you want to measure distance to from route. If using for navigation, this would typically be the users current location.

routeLeg - a directions route.

stepIndex - integer index for step in route.

Returns:

double value giving distance in kilometers.

Throws:

com.mapbox.services.api.ServicesException - if error occurs Mapbox API related.

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0

getDistanceToNextStep

public static double getDistanceToNextStep(com.mapbox.services.commons.models.Position position,
                                           com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg,
                                           int stepIndex,
                                           java.lang.String units)
                                    throws com.mapbox.services.api.ServicesException,
                                           com.mapbox.services.api.utils.turf.TurfException

Measures the distance from a position to the end of the route step. The position provided is snapped to the route before distance is calculated.

Parameters:

position - you want to measure distance to from route. If using for navigation, this would typically be the users current location.

routeLeg - a directions RouteLeg.

stepIndex - integer index for step in route.

Returns:

double value giving distance in kilometers.

Throws:

com.mapbox.services.api.ServicesException - if error occurs Mapbox API related.

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0

getDistanceToNextStep

public static double getDistanceToNextStep(com.mapbox.services.commons.models.Position position,
                                           com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg,
                                           int stepIndex,
                                           java.lang.String units,
                                           int geometryPrecision)
                                    throws com.mapbox.services.api.ServicesException,
                                           com.mapbox.services.api.utils.turf.TurfException

Measures the distance from a position to the end of the route step. The position provided is snapped to the route before distance is calculated.

Parameters:

position - you want to measure distance to from route. If using for navigation, this would typically be the users current location.

routeLeg - a directions route.

stepIndex - integer index for step in route.

geometryPrecision - either Constants.PRECISION_5 or Constants.PRECISION_6

Returns:

double value giving distance in kilometers.

Throws:

com.mapbox.services.api.ServicesException - if error occurs Mapbox API related.

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0

getDistanceToNextLeg

public static double getDistanceToNextLeg(com.mapbox.services.commons.models.Position position,
                                          com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg,
                                          java.lang.String units,
                                          int geometryPrecision)

Measures the distance from a position to the end of the given RouteLeg. The position provided is snapped to the route before distance is calculated.

Parameters:

position - you want to measure distance to from route. If using for navigation, this would typically be the users current location.

routeLeg - a directions RouteLeg.

Returns:

double value giving distance in specified units

getDistanceToEndOfRoute

public static double getDistanceToEndOfRoute(com.mapbox.services.commons.models.Position position,
                                             com.mapbox.services.api.directions.v5.models.DirectionsRoute route,
                                             java.lang.String units)

Measures from the provided position (typically the user location), to the end of a DirectionsRoute. The Position provided will be automatically snapped to the closest point to the route.

Parameters:

position - you want to measure distance to from route. If using for navigation, this would typically be the users current location.

route - a DirectionsRoute.

units - pass in the measurement units.

Returns:

double value giving distance in kilometers.

Since:

0.1.0

getDistanceToEndOfRoute

public static double getDistanceToEndOfRoute(com.mapbox.services.commons.models.Position position,
                                             com.mapbox.services.api.directions.v5.models.DirectionsRoute route,
                                             int geometryPrecision,
                                             java.lang.String units)

Measures from the provided position (typically the user location), to the end of a DirectionsRoute. The Position provided will be automatically snapped to the closest point to the route.

Parameters:

position - you want to measure distance to from route. If using for navigation, this would typically be the users current location.

route - a DirectionsRoute.

units - pass in the measurement units.

geometryPrecision - either Constants.PRECISION_5 or Constants.PRECISION_6

Returns:

double value giving distance your specified unit of measurement.

Since:

0.1.0

getSnapToRoute

public static com.mapbox.services.commons.models.Position getSnapToRoute(com.mapbox.services.commons.models.Position position,
                                                                         com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg,
                                                                         int stepIndex)
                                                                  throws com.mapbox.services.api.ServicesException,
                                                                         com.mapbox.services.api.utils.turf.TurfException

Snaps given position to a RouteLeg step.

Parameters:

position - that you want to snap to routeLeg. If using for navigation, this would typically be the users current location.

routeLeg - that you want to snap position to.

stepIndex - integer index for step in routeLeg.

Returns:

your position snapped to the route.

Throws:

com.mapbox.services.api.ServicesException - if error occurs Mapbox API related.

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0

getSnapToRoute

public static com.mapbox.services.commons.models.Position getSnapToRoute(com.mapbox.services.commons.models.Position position,
                                                                         com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg,
                                                                         int stepIndex,
                                                                         int geometryPrecision)
                                                                  throws com.mapbox.services.api.ServicesException,
                                                                         com.mapbox.services.api.utils.turf.TurfException

Snaps given position to a RouteLeg step.

Parameters:

position - that you want to snap to routeLeg. If using for navigation, this would typically be the users current location.

routeLeg - that you want to snap position to.

stepIndex - integer index for step in routeLeg.

geometryPrecision - either Constants.PRECISION_5 or Constants.PRECISION_6

Returns:

your position snapped to the route.

Throws:

com.mapbox.services.api.ServicesException - if error occurs Mapbox API related.

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0

isOffRoute

@Deprecated
public boolean isOffRoute(com.mapbox.services.commons.models.Position position,
                                      com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg)
                               throws com.mapbox.services.api.ServicesException,
                                      com.mapbox.services.api.utils.turf.TurfException

Deprecated. Use the new static isOffRoute() method.

Method to check whether the position given is outside the routeLeg using the threshold.

Parameters:

position - you want to verify is on or near the routeLeg. If using for navigation, this would typically be the users current location.

routeLeg - a directions routeLeg.

Returns:

true if the position is beyond the threshold limit from the routeLeg.

Throws:

com.mapbox.services.api.ServicesException - if error occurs Mapbox API related.

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0

isOffRoute

public static boolean isOffRoute(com.mapbox.services.commons.models.Position position,
                                 com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg,
                                 double threshold)

Method to check whether the position given is outside the routeLeg using the threshold.

Parameters:

position - you want to verify is on or near the routeLeg. If using for navigation, this would typically be the users current location.

routeLeg - a directions routeLeg.

threshold - double value used to determine if position is outside the range.

Returns:

true if the position is beyond the threshold limit from the routeLeg.

Since:

0.1.0

getClosestStep

public static int getClosestStep(com.mapbox.services.commons.models.Position position,
                                 com.mapbox.services.api.directions.v5.models.RouteLeg routeLeg)
                          throws com.mapbox.services.api.utils.turf.TurfException,
                                 com.mapbox.services.api.ServicesException

Get the closest routeLeg step to the given position. Ties will go to the furthest step in the routeLeg.

Parameters:

position - that you want to get closest routeLeg step to.

routeLeg - a directions routeLeg.

Returns:

integer step index in routeLeg.

Throws:

com.mapbox.services.api.ServicesException - if error occurs Mapbox API related.

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0

getGeometryRemainingOnRoute

public static com.mapbox.services.commons.geojson.LineString getGeometryRemainingOnRoute(com.mapbox.services.commons.models.Position position,
                                                                                         com.mapbox.services.api.directions.v5.models.DirectionsRoute route)
                                                                                  throws com.mapbox.services.api.utils.turf.TurfException

Get the remaining route geometry from the position provided to the end of the directions route. This is useful when the user location is traversing along the route and you don't want the past route geometry to show on the map.

Parameters:

position - the new starting postion of the route geometry. If using for navigation, this would typically be the users current location.

route - a Directions route.

Returns:

the LineString representing the new route geometry.

Throws:

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0

getGeometryRemainingOnRoute

public static com.mapbox.services.commons.geojson.LineString getGeometryRemainingOnRoute(com.mapbox.services.commons.models.Position position,
                                                                                         com.mapbox.services.api.directions.v5.models.DirectionsRoute route,
                                                                                         int geometryPrecision)
                                                                                  throws com.mapbox.services.api.utils.turf.TurfException

Get the remaining route geometry from the position provided to the end of the directions route. This is useful when the user location is traversing along the route and you don't want the past route geometry to show on the map.

Parameters:

position - the new starting postion of the route geometry. If using for navigation, this would typically be the users current location.

route - a Directions route.

geometryPrecision - either Constants.PRECISION_5 or Constants.PRECISION_6

Returns:

the LineString representing the new route geometry.

Throws:

com.mapbox.services.api.utils.turf.TurfException - signals that a Turf exception of some sort has occurred.

Since:

0.1.0