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 horizon paths 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 horizon elements of various types, for example com.tomtom.sdk.navigation.horizon.elements.speedlimit.SpeedLimitElement, com.tomtom.sdk.navigation.horizon.elements.countryinformation.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.

• A 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 com.tomtom.sdk.navigation.horizon.elements.city.CityElement also includes the name of the city.

The engine generates horizon data based on previously registered horizon options. 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 horizon result 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 horizon result generated for a specific set of options comprises:

• The set of horizon options.

• A snapshot of the horizon generated for these options.

• The current position along the horizon.

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

The horizon snapshot consists of:

• A list of horizon paths 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 horizon path (or null if there is no on-road map-matched position).

The Navigation SDK provides class com.tomtom.sdk.navigation.horizon.tilestore.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 com.tomtom.sdk.navigation.horizon.dataadapter.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 com.tomtom.sdk.navigation.horizon.tilestore.TileStoreHorizonEngineFactory class:

val horizonEngine = TileStoreHorizonEngineFactory.create(dataStore, horizonDataAdapters)

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

horizonEngine.registerHorizonOptions(horizonOptions1)
horizonEngine.registerHorizonOptions(horizonOptions2)

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

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

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

horizonEngine.registerHorizonOptions(horizonOptions1)
horizonEngine.registerHorizonOptions(horizonOptions2)
horizonEngine.registerHorizonOptions(horizonOptions3)
...
val horizonResults = generateHorizon(
    options = listOf(horizonOptions1, horizonOptions3),
    navigationSnapshot = navigationSnapshot
)
horizonResults.forEach { result ->
    val options = result.options
    val snapshot = result.snapshot
    val position = result.position
    ...
}

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