TomTomSDKNavigationEngines

  • Engine responsible for detecting arrival at the destination.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol ArrivalDetectionEngine : ManageableEngine
  • Represents the status of arrival at a destination.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct DestinationArrivalStatus
  • Defines the states that a waypoint can assume during navigation.

    See more

    Declaration

    Swift

    public enum WaypointState
  • Represents the status of a waypoint in a route.

    See more

    Declaration

    Swift

    public struct WaypointStatus
  • The DataSourceSelectionEngine provides an interface for the map data source.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol DataSourceSelectionEngine : ManageableEngine
  • 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.

    See more

    Declaration

    Swift

    public enum AnnouncementType : Int
  • 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.

    See more

    Declaration

    Swift

    public struct GuidanceAnnouncement : Equatable
  • Declaration

    Swift

    extension SSMLParser: XMLParserDelegate
  • Declaration

    Swift

    extension TaggedMessagesParser: XMLParserDelegate
  • Specifies the verbosity of guidance announcements. More verbose levels will result in more announcements, with more details.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum AnnouncementMode : CaseIterable
  • Responsible for generation of Guidance and LaneGuidance related to upcoming road maneuvers.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol GuidanceEngine : ManageableEngine
  • Guidance update provided while navigating a route, including the list of upcoming instructions, guidance announcement and distance to the next maneuver.

    See more

    Declaration

    Swift

    public struct Guidance
  • Indicates a border crossing between two countries.

    See more

    Declaration

    Swift

    public struct BorderCrossing
  • Country information.

    See more

    Declaration

    Swift

    public struct Country : Equatable
  • Guidance Instruction indicating an upcoming fork in the road.

    See more

    Declaration

    Swift

    public struct ForkGuidanceInstruction : GuidanceInstruction
  • 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

    Declaration

    Swift

    public protocol GuidanceInstruction
  • Holds information about LaneGuidance and whether it is starting or ending.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct LaneGuidanceUpdate
  • Type of LaneGuidanceUpdate.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum LaneGuidanceUpdateType
  • Location context contains detailed information about the current location during navigating.

    To retrieve location context:

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

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

    See more

    Declaration

    Swift

    public struct LocationContext : Equatable
  • The ManageableEngine protocol provides functionality related to engine data management.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol ManageableEngine
  • 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)
    

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol MapMatchingEngine : ManageableEngine
  • 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.

    See more

    Declaration

    Swift

    public struct MapMatchingResult
  • Snapshot of the current navigation configuration.

    See more

    Declaration

    Swift

    public struct ConfigurationSnapshot
  • Snapshot of the current location information during navigation.

    See more

    Declaration

    Swift

    public struct LocationSnapshot
  • 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.

    See more

    Declaration

    Swift

    public struct NavigationSnapshot
  • Represents the currently followed and unfollowed routes in the current navigation session.

    See more

    Declaration

    Swift

    public struct RouteTrackingState
  • 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.

    See more

    Declaration

    Swift

    public struct UnfollowedRoute
  • Snapshot that contains information about the trip.

    See more

    Declaration

    Swift

    public struct TripSnapshot
  • Defines the error cases that can occur while calculating the current distance along a route.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum DistanceAlongRouteCalculatorError : Error
  • Defines the error cases that can occur while fetching route segments.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum SegmentsFilterError : Error
  • Represents progress along the route.

    See more

    Declaration

    Swift

    public struct RouteProgress
  • Defines the error cases that can occur in the RouteProgressEngine.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum RouteProgressCalculationError : Error
  • The RouteProgressEngine protocol provides functionality related to the calculation of progress along the route.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol RouteProgressEngine : ManageableEngine
  • Represents current progress along the route till given TomTomSDKRoute/RouteStop.

    See more

    Declaration

    Swift

    public struct RouteStopProgress
  • ActiveRouteData stores the active route and an optional better route proposal.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public struct ActiveRouteData
  • 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().

    See more

    Declaration

    Swift

    public struct RoutePlan
  • Specifies how to handle better route proposals.

    See more

    Declaration

    Swift

    public enum BetterProposalAcceptanceMode
  • Specifies how to handle deviation route replanning.

    See more

    Declaration

    Swift

    public enum DeviationReplanningMode
  • Describes the reason for the replanning request.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum ReplanRequestReason
  • Selector responsible for choosing the routes according to protocol’s adoptee expectations

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol RouteProposalSelector
  • Engine responsible for replanning a route.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol RouteReplanningEngine
  • A result of route replanning.

    Important

    This is a Public Preview API. It may be changed or removed at any time.

    Declaration

    Swift

    public typealias RouteReplanningResult = Result<(routes: [Route], reason: RouteReplanningReason), Error>
  • Describes why the route has been replanned and how it is different from the previous route.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

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

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum RouteUpdateMode
  • 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 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
        ...
    }
    

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public protocol HorizonEngine
  • Possible errors thrown in the by Horizon Engine methods.

    Important

    This is a Public Preview API. It may be changed or removed at any time.
    See more

    Declaration

    Swift

    public enum HorizonEngineError : Error, Equatable
  • 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.

    See more

    Declaration

    Swift

    public struct HorizonOptions
    extension HorizonOptions: Hashable
  • Defines the interface to horizon element types.

    See more

    Declaration

    Swift

    public struct HorizonElementType : RawRepresentable, Hashable
  • 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.

    See more

    Declaration

    Swift

    public struct MainPathSearchOptions
  • 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.

    See more

    Declaration

    Swift

    public struct SubPathSearchOptions
  • 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.
    See more

    Declaration

    Swift

    public struct HorizonSnapshot
  • 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.

    See more

    Declaration

    Swift

    public struct HorizonPath : Equatable
  • 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.

    See more

    Declaration

    Swift

    public struct HorizonPosition
  • State of the HorizonSnapshot that the HorizonEngine generates based on a set of registered HorizonOptions.

    See more

    Declaration

    Swift

    public struct HorizonSnapshotState : Equatable
  • 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.

    See more

    Declaration

    Swift

    public struct PathSearchDistance : Equatable
  • 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.

    See more

    Declaration

    Swift

    public struct RouteLengthPolicy : PathSearchDistancePolicy