HorizonUpdatedListener

Used to inform the caller that the horizon information has been updated.

The Navigation SDK Virtual Horizon 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 safety locations, street data, traffic sign information, and more.

To generate the horizon, a context-dependent simplification of the road network is used 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 active-guidance 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).

Data is published along these horizon paths in the form of horizon elements of various types, for example safety locations, traffic, 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 SafetyLocationElement also includes safety location details, such as an Identifier and a type of this safety location.

To retrieve data on horizon according to their preferences, users must take the following steps:

1. Define a set of horizon options to configure Navigation SDK Horizon according to these preferences.

2. Register a listener to get horizon data update notifications for the set of horizon options defined at step 1.

3. Process the notifications received via the listener defined at step 2.

Navigation SDK supports multiple horizon configurations in the same application. Users can define multiple sets of horizon options and listen to horizon data updates for each such set.

A horizon update listener notifies users about changes to:

• The current horizon position along the horizon main path.

• The horizon snapshot generated according to the set of options for which the listener was registered.

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 types 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 com.tomtom.sdk.navigation.horizon.HorizonEngine.generateHorizon.

• An identifier of the main horizon path (or null if there is no on-road map-matched position).

Horizon information is updated with each location update.

In order to listen to the horizon updates while navigating, implement this interface to create a listener, for instance:

val horizonUpdatedListener = object : HorizonUpdatedListener {
    override fun onSnapshotUpdated(options: HorizonOptions, snapshot: HorizonSnapshot) {
        // Implement the necessary functionality for handling the horizon snapshot update
    }
    override fun onPositionUpdated(options: HorizonOptions, position: HorizonPosition) {
        // Implement the necessary functionality for handling the horizon position update
    }
}

Subsequently, add this listener using TomTomNavigation.addHorizonUpdatedListener: To stop listening to the horizon updates, remove the listener using TomTomNavigation.removeHorizonUpdatedListener: