Navigation Engines

Specifies the verbosity of guidance announcements. More verbose levels will result in more announcements, with more details.

Represents different guidance announcement types, which are used to prepare the driver for the maneuver. It is used while creating a TomTomSDKNavigationEngines/GuidanceAnnouncement to specify the type of the announcement.

Engine responsible for detecting arrival at the destination.

Guidance Instruction indicating arrival at the destination.

Specifies how to handle better route proposals.

Indicates a border crossing between two countries.

Instruction indicating an upcoming border crossing.

HorizonElement that contains data about a city.

To receive such elements in the horizon snapshot HorizonSnapshot, specify HorizonElementType.cityType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.cityType],
    ...
)

Snapshot of the current navigation configuration.

Country information.

HorizonElement that contains data about a country.

To receive such elements in the HorizonSnapshot, specify HorizonElementType.countryInformationType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.countryInformationType],
    ...
)

HorizonElement that contains data about a dangerous goods restriction.

To receive such elements in the HorizonSnapshot, specify HorizonElementType.dangerousGoodsRestrictionType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.dangerousGoodsRestrictionType],
    ...
)

The DataSourceSelectionEngine provides an interface for the map data source.

Guidance Instruction indicating departure from the origin.

Represents the status of arrival at a destination.

Specifies how to handle deviation route replanning.

Defines the error cases that can occur while calculating the current distance along a route.

Guidance Instruction indicating entering a vehicle transportation service through a terminal.

Guidance Instruction indicating entering a carpool lane by changing lanes.

Guidance Instruction indicating exiting a vehicle transportation service through a terminal.

Guidance Instruction indicating exiting a carpool lane by changing lanes.

Guidance Instruction indicating taking a highway exit.

Guidance Instruction indicating an exit from a roundabout.

Exceptions that can be thrown during creation of ExitRoundaboutGuidanceInstruction.

Policy that defines a search distance for the main path.

The main path is the path the user currently follows, extending along the most likely trajectory. If the horizon options specify this policy, the HorizonEngine only searches within an explicitly specified distance when extending the main path.

For more information on horizon paths see HorizonEngine.

For more information on horizon options see HorizonOptions.

To search along the entire route use the RouteLengthPolicy.

Guidance Instruction indicating that the current road should be followed for some distance.

Guidance Instruction indicating an upcoming fork in the road.

HorizonElement that contains data about general road properties.

To receive such elements in the HorizonSnapshot, specify HorizonElementType.generalRoadPropertiesType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.cityType],
    ...
)

Guidance update provided while navigating a route, including the list of upcoming instructions, guidance announcement and distance to the next maneuver.

Guidance announcement relating to a maneuver during navigation. The announcement text message is provided in both Speech Synthesis Markup Language (SSML) and plain-text formats.

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

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).

HorizonElement that contains data about a hazard.

To receive such elements in the HorizonSnapshot, specify HorizonElementType.hazardType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.hazardType],
    ...
)

Defines the interface to horizon elements.

Defines the interface to horizon element types.

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
    ...
}

Possible errors thrown in the by Horizon Engine methods.

Horizon configuration options.

Horizon options define the extent of the HorizonPath in the horizon and the map attributes to be collected for these paths. A set of horizon options consists of the following:

• The set of HorizonElementType the client is interested in.
• The path search options for the main path.
• The path search options for sub-paths.
• The maximum number of paths the client can receive.
• Minimum length of the horizon ahead for which a horizon snapshot update is triggered.

To specify horizon options, create an instance of this class:

let mainPathSearchOptions = try MainPathSearchOptions(
    searchTime: .tt.minutes(10),
    searchDistancePolicy: ExplicitDistancePolicy(
        searchDistance: PathSearchDistance(
            maxHorizonLength: .tt.kilometers(5)
        )
    )
)
let subPathSearchOptionsLevel1 = try SubPathSearchOptions(
    searchTime: .tt.minutes(5),
    searchDistance: PathSearchDistance(
        maxHorizonLength: .tt.kilometers(2)
    )
)
let subPathSearchOptionsLevel2 = try SubPathSearchOptions(
    searchTime: .tt.minutes(3),
    searchDistance: PathSearchDistance(
        maxHorizonLength: .tt.kilometers(1)
    )
)
let horizonOptions = try HorizonOptions(
    id: UUID(),
    elementTypes: [.speedLimitsType, .streetType],
    mainPathSearchOptions: mainPathSearchOptions,
    subPathSearchOptions: [subPathSearchOptionsLevel1, subPathSearchOptionsLevel2],
    numberOfPaths: 4
)

For more information on horizon element types and horizon paths see HorizonEngine.

A client application can 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.

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

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

Path in the horizon. The length of the path as well as which types of horizon elements HorizonElement it contains are determined by the set of horizon options HorizonOptions for which horizon data was generated. For information on how to manage horizon options see HorizonEngine.registerHorizonOptions and HorizonEngine.unregisterHorizonOptions.///

For more information on horizon paths see HorizonEngine.

The best map-matched position on the horizon. It can be either on-road or off-road. If off-road, it can be either:

• The likeliest on-road position on the horizon, but flagged as off-road, if the likeliest position is off-road, but there are also on-road candidates. The user can extract horizon elements to facilitate the decision to join the road.
• Or an off-road position with an invalid path ID and an unmatched raw location, if the likeliest position is off-road and there are no on-road candidates on the horizon.

Horizon position can be extracted from the result HorizonResult of the call HorizonEngine.generateHorizon with a preregistered set of HorizonOptionsused as an argument.

Output of the HorizonEngine.

Entry of horizon result is consisted of one HorizonSnapshot, HorizonPosition and set of previously registered HorizonOptions. HorizonSnapshot holds current snapshot of horizon which includes available paths, status of the horizon snapshot and ID of the main path. Horizon result additionally contains HorizonOptions provided by user and HorizonPosition representing current position. Both HorizonOptions and HorizonPosition determine contents of the HorizonSnapshot.

Horizon results can be obtained by creating instance of HorizonEngine, registering desired HorizonOptions with call HorizonEngine .registerHorizonOptions and making direct request to generate horizon HorizonEngine .generateHorizon providing HorizonOptions and current NavigationSnapshot.

Snapshot of the horizon.

Snapshot of the horizon provided by the HorizonEngine for a set of registered HorizonOptions. These options define the extent of the paths HorizonPath on the horizon and which map attributes are collected for those paths.

Horizon snapshot holds state of the horizon for HorizonOptions provided by user and current position. Snapshot contains data such as:

• paths: List of horizon paths HorizonPath, consisting of the main path and zero or more sub-paths. The main path is the path on which the likeliest map-matched on-road position is located. If there is no on-road map-matched position candidate, there is no main path either. This is because no horizon can be provided if there is no on-road map-matched position. See HorizonPosition for more details. A sub-path is any path in the horizon snapshot that is not the main path. For a horizon snapshot to contain sub-paths, the options HorizonOptions for which it was generated must specify sub-path search options SubPathSearchOptions for at least one sub-path level.
• state: The horizon snapshot state HorizonSnapshotState
• mainPathID: The ID of the main path HorizonPath. Nil if there is no on-road map-matched position candidate. See HorizonPosition for more details.

State of the HorizonSnapshot that the HorizonEngine generates based on a set of registered HorizonOptions.

Represents instruction triggering phase.

Contains information about lane guidance.

Holds information about LaneGuidance and whether it is starting or ending.

Type of LaneGuidanceUpdate.

Location context contains detailed information about the current location during navigating.

To retrieve location context:

• implement the NavigationLocationContextObserver protocol
• add the observer using the TomTomNavigation.addLocationContextObserver(_:) method of the initialized TomTomNavigation object After navigation has started (with or without a route), you will receive LocationContext via the NavigationLocationContextObserver.didDetectLocationContext(locationContext:) method. “`

class NavigationLocationContextObserverImpl : NavigationLocationContextObserver { override func didDetectLocationContext(locationContext: LocationContext) {} }

private let navigationLocationContextObserver = NavigationLocationContextObserverImpl() … tomTomNavigation.addLocationContextObserver(navigationLocationContextObserver)

Snapshot of the current location information during navigation.

Horizon search options for the main path.

These options specify the search distance policy PathSearchDistancePolicy and the search time for the main path. The main path is the path the user currently follows, extending along the most likely trajectory. The search distance policy and the search time define the extent of the main path.

To specify horizon options for the main path, create an instance of this class:

let mainPathSearchOptions = try MainPathSearchOptions(
    searchTime: .tt.minutes(10),
    searchDistancePolicy: ExplicitDistancePolicy(
        searchDistance: PathSearchDistance(
            maxHorizonLength: .tt.kilometers(5)
        )
    )
)

For more information on horizon paths see HorizonEngine.

For more information on horizon options see HorizonOptions.

The PathSearchDistancePolicy determines whether the horizon engine must search along the entire route (see RouteLengthPolicy) or within an explicitly specified distance (see ExplicitDistancePolicy).

The main path will be extended until search time and search distance have both reached their limits.

The ManageableEngine protocol provides functionality related to engine data management.

Guidance Instruction indicating a turn which is legally required.

Exceptions that can be thrown during creation of MandatoryTurnGuidanceInstruction.

Interface to a Map Matcher Engine.

Map Matcher is a component that tries to match position input (includes GNSS data, existing Route) to a point on a map. The output of the MapMatchingEngine is a MapMatchingResult that contains an accurate (matched) location along with additional information such as alternative and predicted locations (GeoLocation). Depending on the availability of geolocation input data, Map Matcher works in two modes:

• When available - retrieving a map-matched location based on the input data.
• When not available - extrapolating the location based on the last known location. It is used when there is no GNSS data available, for instance, when the device is in a tunnel. If there is no last known location, extrapolation is not possible, and the map-matching result is null.

The Navigation SDK provides factories to create map matcher engines. One of them is the TileStoreMapMatchingEngineFactory which creates a map matcher engine. This factory creates an engine that attempts to match the position input to the navigation tile data (provided by an online map). To do so, it uses a map-based tile data store (NavigationTileStore). A client application must specify the data store when creating the engine.

To create a NavigationTileStore an API key is required. With the key you configure the store by setting up the NavigationTileStoreConfiguration:

let navigationTileStoreConfiguration = NavigationTileStoreConfiguration(apiKey: TOMTOM_API_KEY)
let navigationTileStore = try NavigationTileStore(config: navigationTileStoreConfiguration)

To create a map-matching engine, use the TileStoreMapMatchingEngineFactory class:

let mapMatcherEngine = try TileStoreMapMatchingEngineFactory.create(tileStore: navigationTileStore)

To match the location to a position on a map, use the [matchLocation] function:

let mapMatchingResult = try mapMatcherEngine.matchLocation(navigationSnapshot: navigationSnapshot)

To extrapolate the location, use the [extrapolateLocation] function:

let mapMatchingResult = try mapMatcherEngine.extrapolateLocation(navigationSnapshot: navigationSnapshot)

Output of the MapMatchingEngine that represents accurate (map matched) location. This is used in driving mode to snap the chevron shown on the map to the road network. MapMatchingEngine provides an individual MapMatchingResult for each TomTomSDKLocationProvider/GeoLocation.

Guidance Instruction indicating a merge onto another road.

NavigationProcessingError contains information about any problems that occur during RouteProgressEngine, RouteTrackingEngine, ArrivalDetectionEngine.

Navigation snapshot containing information about the state of the trip at a certain moment.

Because it provides other engines with input data, the navigation snapshot always contains current information about the navigation session, such as current location, matched location, and progress along a route. It is updated whenever new values are available.

Describes path geometry of the HorizonElement.

To receive such elements in the HorizonSnapshot, specify HorizonElementType.pathGeometryType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.pathGeometryType],
    ...
)

Horizon path search distance configuration.

The search distance defines the extent of the path in the horizon.

For more information on horizon paths see HorizonEngine.

For more information on horizon options see HorizonOptions.

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.

SpeedLimit that is specific to a region in a country.

Describes the reason for the replanning request.

Road information relating to a GuidanceInstruction.

Guidance Instruction indicating an upcoming roundabout.

Exceptions that can be thrown during creation of RoundaboutGuidanceInstruction.

Policy that binds the horizon path to the entire route.

The main path is the path the user currently follows, extending along the most likely trajectory. If the horizon options specify this policy, the horizon engine HorizonEngine searches along the entire route when extending the main path.

For more information on horizon paths see HorizonEngine.

For more information on horizon options see HorizonOptions.

To search within a specific distance use the ExplicitDistancePolicy.

Route plan defines parameters required for a single route in navigation session.

To specify a route plan, first plan a TomTomSDKRoute/Route using TomTomSDKRoutePlanner/RoutePlanner and TomTomSDKRoutePlanner/RoutePlanningOptions.

For more information on navigation session see start(), TomTomNavigation/start(_:), TomTomNavigation/update(_:) and stop().

Represents progress along the route.

Defines the error cases that can occur in the RouteProgressEngine.

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

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

Engine responsible for replanning a route.

Describes why the route has been replanned and how it is different from the previous route.

A result of route replanning.

Snapshot of the route.

Represents current progress along the route till given TomTomSDKRoute/RouteStop.

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

Represents the currently followed and unfollowed routes in the current navigation session.

Specifies whether or not the system should try to periodically update the active route and look for better route proposals.

HorizonElement that contains data about a safety location.

To receive such elements in the HorizonSnapshot, specify HorizonElementType.safetyLocationType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.safetyLocationType],
    ...
)

Defines the error cases that can occur while fetching route segments.

Contains information about the signpost for the GuidanceInstruction.

HorizonElement that contains data about a speed limit.

To receive such elements in the HorizonSnapshot, specify HorizonElementType.speedLimitType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.speedLimitType],
    ...
)

HorizonElement that contains data about a street.

To receive such elements in the HorizonSnapshot, specify HorizonElementType.streetType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.streetType],
    ...
)

Horizon search options for a sub-path level.

These options specify the search distance and the search time for a sub-path level. 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. The search distance and the search time define the extent of sub-paths of that level in the horizon.

To specify options for a sub-path level, create an instance of this class:

let subPathSearchOptionsLevel1 = try SubPathSearchOptions(
    searchTime: .tt.minutes(5),
    searchDistance: PathSearchDistance(
        maxHorizonLength: .tt.kilometers(2)
    )
)

For more information on horizon paths see HorizonEngine.

For more information on horizon options see HorizonOptions.

If both search time and search distance are specified (i.e., the options specify both a search time and a search distance) for a given sub-path level, the HorizonEngine extends horizon sub-paths of that level until both time and distance have reached the limit.

If only the search distance is specified for a given sub-path level, the horizon engine works with a default value Defaults/pathSearchTime for the search time and extends the sub-paths of that level based on the search distance.

If only the search time is specified for a given sub-path level, the horizon engine works with a default value of Defaults/pathSearchDistance maximum extension length for the search distance and extends sub-paths of that level until both time and distance reach the limit.

Guidance Instruction indicating changing highways by following an exit ramp.

Guidance instruction indicating the driver is approaching a tollgate or ETC terminal.

HorizonElement that contains data about a traffic sign.

To receive such elements in the HorizonSnapshot, specify HorizonElementType.trafficSignType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.trafficSignType],
    ...
)

Snapshot that contains information about the trip.

Guidance Instruction indicating the driver should turn around when it is possible.

Guidance Instruction indicating a turn at a road junction.

Exceptions that can be thrown during creation of TurnGuidanceInstruction.

Represents the routes that are not currently followed (unfollowed) within the TomTomSDKNavigation/NavigationSession. An unfollowed route comprises a TomTomSDKRoute/Route within the TomTomSDKNavigation/NavigationSession that is not currently followed and a back-to-route point. This is the closest point on the route to the current location.

HorizonElement that contains data about a vehicle restriction.

To receive such elements in the HorizonSnapshot, specify HorizonElementType.vehicleRestrictionType in the HorizonOptions that you register with the HorizonEngine:

let horizonOptions = HorizonOptions(
    id: UUID(),
    elementTypes: [.vehicleRestrictionType],
    ...
)

Guidance Instruction indicating that a waypoint on the route is reached.

Defines the states that a waypoint can assume during navigation.

Represents the status of a waypoint in a route.