Continuous replanning

VERSION 0.2.3404
PUBLIC PREVIEW

The Navigation SDK for iOS is only available upon request. Contact us to get started.

Introduction

Every trip takes time, and the situation on the road is constantly changing, so routes can become stale even while you’re driving. Continuous replanning provides users with the most up-to-date route path. This can be a new path, for example, if traffic conditions mean that it will be faster or if a road blockage appears on the original route. It can also be the same path with updated delay information, if a change in the traffic changes the Estimated Time of Arrival (ETA).

The Continuous Replanning component performs a route refresh by checking for better route alternatives in the background, then applying them based on how the component is configured. The component is fully customizable, so you can configure the definition of a better route, the mode for applying a new route, and the interval time between replans.

Configuration

Modes and options

Route Replanning Mode

There are three replanning modes:

The default mode is Automatic.

Route Replanning Options

The following options can be used to configure TomTomRouteReplanningEngine:

  • routeReplanInterval - The time interval between replannings.
  • minimalTrafficDelay - The minimum traffic delay time required for an alternative route to be used.
  • minimalTimeDifference - The minimum time difference required for an alternative route to be used.
  • routeReplanningPolicy - How Continuous Replanning will work.

Route Replanning Policy

ContinuousReplanningPolicy specifies how continuous replanning will work.

It has two possible values:

  • Refresh Only - the Continuous Replanning component will only refresh the route along the existing path.
  • Find Better - the Continuous replanning component will search for better routes. It only refreshes if no better routes are found.

The default mode is Refresh Only.

Enabling/Disabling Continuous Replanning

ContinuousReplanningMode is specified using NavigationConfiguration.

1let navigationConfiguration = NavigationConfiguration(
2    apiKey: Keys.navigation,
3    locationProvider: locationEngine,
4    routeReplanner: routeReplanner,
5    continuousReplanningMode: .automatic
6)
7let navigation = Navigation(configuration: navigationConfiguration)
1let navigationConfiguration = NavigationConfiguration(
2    apiKey: Keys.navigation,
3    locationProvider: locationEngine,
4    routeReplanner: routeReplanner,
5    continuousReplanningMode: .manual
6)
7

8let navigation = Navigation(configuration: navigationConfiguration)

Continuous Replanning can be disabled by specifying ContinuousReplanningMode as .none.

1let navigationConfiguration = NavigationConfiguration(
2    apiKey: Keys.navigation,
3    locationProvider: locationEngine,
4    routeReplanner: routeReplanner,
5    continuousReplanningMode: .none
6)
7

8let navigation = Navigation(configuration: navigationConfiguration)

Specifying the Route Replanning Policy

To configure the replanning policy, you must create a TomTomRouteReplanningEngine by passing RouteReplanningEngineOptions with preferred ContinuousReplanningPolicy.

1let routeReplanningEngineOptions = RouteReplanningEngineOptions(
2    routeReplanInterval: .tt.minutes(5),
3    minimalTrafficDelay: .tt.minutes(10),
4    minimalTimeDifference: .tt.minutes(5),
5    routeReplanningPolicy: .findBetter
6)
7let routeReplanningEngine = TomTomRouteReplanningEngine(options: routeReplanningEngineOptions)
8

9let navigationConfiguration = NavigationConfiguration(
10    apiKey: Keys.navigation,
11    locationProvider: locationEngine,
12    routeReplanner: routeReplanner,
13    routeReplanningEngine: routeReplanningEngine
14)
15

16let navigation = Navigation(configuration: navigationConfiguration)

Providing a custom Better Route Selector

TomTomRouteReplanningEngine can accept a custom RouteProposalSelector for advanced customisation of the better route selection process. To use a custom RouteProposalSelector, pass a class conforming to RouteProposalSelector as an init parameter.

1let routeProposalSelector = CustomRouteProposalSelector()
2

3let routeReplanningEngine = TomTomRouteReplanningEngine(
4    options: routeReplanningEngineOptions,
5    routeProposalSelector: routeProposalSelector
6)
7

8let navigationConfiguration = NavigationConfiguration(
9    apiKey: Keys.navigation,
10    locationProvider: locationEngine,
11    routeReplanner: routeReplanner,
12    routeReplanningEngine: routeReplanningEngine
13)
14

15let navigation = Navigation(configuration: navigationConfiguration)

Working with manual replanning mode

To use manual replanning mode, specify ContinuousReplanningMode as .manual and set up a NavigationRouteObserver::func didProposeRoutePlan(routePlan: RoutePlan, reason: RouteReplanningReason) callback.

.
1func didProposeRoutePlan(routePlan: RoutePlan, reason: RouteReplanningReason) {
2    /* YOUR CODE GOES HERE */
3}

Incremental guidance computation

If the guidanceProgressOffset of the route is less than the length in the route summary, the route needs to be updated. Instead of calling the planRoute method, the replanning engine can call the advanceGuidanceProgress method. This adds more instructions and corresponding lane guidance to the route and increases the guidanceProgressOffset of the route.

Route Deviation

Introduction

The Navigation module detects when the user has diverged from the navigated route. Route Deviation is a specific case of the more general Continuous Replanning feature, but with its own wide range of possibilities for customization. You can configure the definition of a deviation (not tracking a route) with a custom RouteTrackingEngine or specify how route deviation will work with a separate ReplanningRetryPolicy for deviations. Whenever a deviation is detected, the notification is sent via NavigationRouteObserver::func didDeviateFromRoute(currentRoute: Route, location: GeoLocation). The location provided by the callback is the location where the deviation from the route was detected. The currentRoute parameter is the Route that the user deviated from.

1func didDeviateFromRoute(currentRoute: Route, location: GeoLocation) {
2    /* YOUR CODE GOES HERE */
3}

Configuration

Modes and options

Deviation Replanning Mode

There are two replanning modes for deviation:

The default mode is Automatic.

Route Tracking Engine

Deviation is not tracking a route. To configure the route tracking engine, create a custom engine that implements the RouteTrackingEngine protocol and set this engine using NavigationConfiguration.

1let navigationConfigurationNone = NavigationConfiguration(
2    apiKey: Keys.navigation,
3    locationProvider: locationEngine,
4    routeReplanner: routeReplanner,
5    routeTrackingEngine: customEngine
6)

Enabling/Disabling Route Deviation

DeviationReplanningMode is specified using NavigationConfiguration.

1let navigationConfiguration = NavigationConfiguration(
2    apiKey: Keys.navigation,
3    locationProvider: locationEngine,
4    routeReplanner: routeReplanner,
5    deviationReplanningMode: .automatic
6)

Route Deviation can be disabled by specifying DeviationReplanningMode as .none.

1let navigationConfigurationNone = NavigationConfiguration(
2    apiKey: Keys.navigation,
3    locationProvider: locationEngine,
4    routeReplanner: routeReplanner,
5    deviationReplanningMode: .none
6)

Specifying the Route Deviation Retry Policy

To configure the replanning retry policy, you need to create a custom class which implements the ReplanningRetryPolicy protocol.

1let navigationConfigurationNone = NavigationConfiguration(
2    apiKey: Keys.navigation,
3    locationProvider: locationEngine,
4    routeReplanner: routeReplanner,
5    routeDeviationReplanningRetryPolicy: customRetryPolicy
6)