HorizonEngine

public protocol 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 SpeedLimits, CountryInformation, 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 Region element also includes:

• the name of the country,
• the name of the region/province/state.

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