Protocols

Engine responsible for detecting arrival at the destination.

See more

public protocol ArrivalDetectionEngine : ManageableEngine

The DataSourceSelectionEngine provides an interface for the map data source.

See more

public protocol DataSourceSelectionEngine : ManageableEngine

Responsible for generation of Guidance and LaneGuidance related to upcoming road maneuvers.

See more

public protocol GuidanceEngine : ManageableEngine

Protocol for a Guidance Instruction, which provides information to the user about the next action to take on the route.

Contains a set of attributes common to all GuidanceInstructions. e.g., ‘Turn right’, ‘Keep left’, ‘Take the ferry’, ‘Take the motorway’, ‘Arrive’.

Different types of GuidanceInstruction‘s will implement this, and may add extra attributes specific to the TomTomSDKRoute/Instruction type.

• TurnGuidanceInstruction: Implements the GuidanceInstruction protocol and additionally contains TomTomSDKRoute/Instruction/turnAngle, which is the angle where the turn should be made, and TomTomSDKRoute/Instruction/turnDirection, which is the direction of the turn (left/right).
• TurnInstruction: Implements the Instruction protocol and additionally contains TomTomSDKRoute/Instruction/turnAngle, which is the angle where the turn should be made, and TomTomSDKRoute/Instruction/turnDirection, which is the direction of the turn (left/right).

See more

public protocol GuidanceInstruction

The ManageableEngine protocol provides functionality related to engine data management.

See more

public protocol ManageableEngine

The MapMatchingEngine provides an interface for map matching functionality.

See more

public protocol MapMatchingEngine : ManageableEngine

The RouteProgressEngine protocol provides functionality related to the calculation of progress along the route.

See more

public protocol RouteProgressEngine : ManageableEngine

The RouteProjectionEngine is responsible for projecting the input route to obtain map references if they are not provided.

See more

public protocol RouteProjectionEngine : ManageableEngine

Selector responsible for choosing the routes according to protocol’s adoptee expectations

See more

public protocol RouteProposalSelector

Engine responsible for replanning a route.

See more

public protocol RouteReplanningEngine

Responsible for detecting whether the Routes are being followed or deviated from.

See more

public protocol RouteTrackingEngine : ManageableEngine

Defines the interface to horizon elements.

See more

public protocol HorizonElement

Interface to a Virtual Horizon engine.

Virtual Horizon is a digital assistant that provides location context data extending beyond the driver’s visible horizon. UI components can use it to inform the driver of what is ahead. Examples of such data include speed limits, street data, traffic sign information, and more. The purpose of the engine is to generate this Virtual Horizon data, which we can refer to simply as horizon.

To generate the horizon, the engine uses a context-dependent simplification of the road network based on the digital map. Central to this approach is a path model: the road network is represented as a graph where edges correspond to roads and vertices to intersections where these roads connect. The edges and vertices combine to form trajectories over the road network. The path model identifies which of these trajectories the user may follow in the near future. We refer to these possible trajectories as paths. The horizon consists of the physically reachable paths within a pre-configured distance ahead of the user’s current position.

The set of HorizonPaths includes a so-called main path and, possibly, one or more so-called sub-paths. The main path is the path that the user currently follows, extending along the most likely trajectory. In turn-by-turn navigation mode, the most likely trajectory corresponds to the planned route. In free-driving mode, it is the Virtual Horizon path model that determines the most likely trajectory. A sub-path is any horizon path that is not the main path.

Horizon paths have path levels. The level of the main path is 0. The level of a sub-path is the number of times the user would have to deviate, starting from the main path, in order to reach that sub-path. If a user can physically deviate from a path to follow another path (regardless of whether this is a legal maneuver), the former is the parent path of the latter. A path can have either no parents or a single parent. Children of the main path are level 1 paths, their children are level 2 sub-paths, and so on. When the user deviates to one of the level 1 sub-paths, that path becomes the new main path, with its level updated to 0. The levels of the children of the new main path are also adjusted accordingly (decreased by 1).

The engine publishes data along these horizon paths in the form of HorizonElement of various HorizonElementType, for example SpeedLimitElement, CountryInformationElement, and so on. The elements are attached to paths at specific offsets (point-wise attachments) or specific offset ranges (span attachments). Regardless of type, every element encapsulates the following information:

• An element identifier.
• An identifier of the path to which the element belongs.
• A start offset: distance from the path start where the element starts.
• An end offset: distance from the path start where the element ends.

In addition to these properties that all element types have in common, each element type has its own set of specific properties. For example, a CityElement also includes the name of the city.

The engine generates horizon data based on previously registered HorizonOptions. The options define the length of the horizon paths and what type of horizon data is collected for these paths.

A client application register multiple sets of horizon options and request the engine to provide data for all or only some of the registered option sets. The engine generates a separate HorizonResult for each set of options in the request. The client can also update horizon configuration by registering a new set of options or unregistering a previously registered set.

The HorizonResult generated for a specific set of options comprises:

• The set of HorizonOptions.
• A HorizonSnapshot of the horizon generated for these options.
• The current HorizonPosition along the horizon.

The HorizonPosition encapsulates data about the likeliest map-matched position on the horizon. The position is either on-road or off-road.

The HorizonSnapshot consists of:

• A list of HorizonPath decorated with horizon elements of the HorizonElementType requested via the horizon options.
• Data related to the state of the snapshot, which can be used to determine if the snapshot was updated since the previous call to HorizonEngine .generateHorizon.
• An identifier of the main HorizonPath (or null if there is no on-road map-matched position).

The Navigation SDK provides class TileStoreHorizonEngineFactory to create a default horizon engine. This default engine can retrieve certain horizon elements, for example speed limits, directly from the map. To do so, it uses a map-based data store. However, for other horizon elements, for example safety locations, retrieving data requires a dedicated data source. The default engine uses so-called HorizonDataAdapter to collect data for such elements. Each adapter works with a specific element/data type. A client application must specify the data store as well as the horizon data adapters (if applicable) when creating the default horizon engine. The list of data adapters should be empty if the client application does not need to collect data for any horizon elements that require data sources.

To create a default horizon engine, use the TileStoreHorizonEngineFactory class:

let horizonEngine = TileStoreHorizonEngineFactory.create(dataStore: dataStore, dataAdapters: dataAdapters)

To register a set of horizon options, call the registerHorizonOptions function:

horizonEngine.registerHorizonOptions(options: horizonOptions1)
horizonEngine.registerHorizonOptions(options: horizonOptions2)

To unregister a set of horizon options, call the unregisterHorizonOptions function:

horizonEngine.registerHorizonOptions(options: horizonOptions1)
horizonEngine.registerHorizonOptions(options: horizonOptions2)
...
horizonEngine.unregisterHorizonOptions(options: horizonOptions2)

To generate horizon results for specific sets of options, call the generateHorizon function:

horizonEngine.registerHorizonOptions(options: horizonOptions1)
horizonEngine.registerHorizonOptions(options: horizonOptions2)
horizonEngine.registerHorizonOptions(options: horizonOptions3)
...
let horizonResults = generateHorizon(
    options: [horizonOptions1, horizonOptions3],
    navigationSnapshot: navigationSnapshot
)
result.forEach { result in
    let options = result.horizonOptions
    let snapshot = result.snapshot
    let position = result.position
    ...
}

See more

public protocol HorizonEngine

Interface to the path search policy.

The path search policy specifies whether the HorizonEngine must search along the entire route (see RouteLengthPolicy) or within an explicitly defined distance (see ExplicitDistancePolicy).

For more information on horizon paths see HorizonEngine.

For more information on horizon options see HorizonOptions.

public protocol PathSearchDistancePolicy