Protocols

The following protocols are available globally.

  • 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

DataSourceSelectionEngine

  • 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
  • Responsible for generation of Guidance and LaneGuidance related to upcoming road maneuvers.

    See more

    Declaration

    Swift

    public protocol GuidanceEngine : ManageableEngine
  • The protocol for a Guidance Instruction.

    Contains a set of attributes common to all GuidanceInstructions. It contains a set of default attributes common to all GuidanceInstruction‘s.

    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 Instruction type.

    e.g., TurnInstruction will contain turnAngleInDegrees and turnDirection.

    See more

    Declaration

    Swift

    public protocol GuidanceInstruction
  • The LocationContextProviderEngine protocol provides functionality related to information about a matched location.

    Important

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

    Declaration

    Swift

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

MapMatchingEngine

  • The MapMatchingEngine provides an interface for map matching functionality.

    Important

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

    Declaration

    Swift

    public protocol MapMatchingEngine : ManageableEngine
  • 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
  • The RouteProjectionEngine is responsible for projecting the input route to obtain map references if they are not provided.

    Important

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

    Declaration

    Swift

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

RouteReplanningEngine

  • 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
  • Responsible for detecting whether the Routes are being followed or deviated from.

    Important

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

    Declaration

    Swift

    public protocol RouteTrackingEngine : ManageableEngine
  • Defines the interface to horizon elements.

    Important

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

    Declaration

    Swift

    public protocol HorizonElement

HorizonEngine

  • 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

PathSearchDistancePolicy