Electronic horizon

In the automotive industry, map data is sometimes used to power a car's Advanced Driver Assistance Systems (ADAS) and other advanced capabilities like adaptive cruise control and proactive driver alerts for upcoming congestion, speed change and dangerous curves, or available alternative paths. This is accomplished using an electronic horizon. An electronic horizon is a probable path (or paths) of a vehicle within the road network that allows the user to use map data to anticipate conditions beyond the physical "visible" horizon.

Mapbox Electronic Horizon provides similar capabilities to mobile devices. Mapbox Electronic Horizon correlates the vehicle's location to the road network and broadcasts updates as the vehicle's position and trajectory change.

Active guidance and free drive mode

The Mapbox Navigation SDK allows users to navigate in two different modes: active guidance and free-drive mode.

Active guidance is likely what comes to mind when you think about a typical turn-by-turn navigation experience: a user selects a route and receives turn-by-turn instructions as they progress along the route. When using active guidance mode the user-selected route and its metadata are used as the path for the Electronic Horizon.

Free-drive is a unique Mapbox Navigation SDK feature that allows drivers to navigate without a set destination. This mode is sometimes referred to as passive navigation. When using free-drive mode there is no active route selected so Mapbox Electronic Horizon will determine the most probable path from the vehicle's current location.

For both active guidance and free-drive, the Electronic Horizon and its metadata are exposed via the same interface in the Navigation SDK as described below.

Most probable path (MPP)

Mapbox Electronic Horizon represents the road network ahead of the user as a tree of edges. Each intersection has outbound edges and each edge has a probability of transition to another edge as well as metadata that can be used to implement sophisticated features on top of it.

Based on the device's location and user-selected route (if applicable), Mapbox Electronic Horizon determines the most likely path a user may take and provides a most probable path (MPP). The MPP contains data in a tree-like structure where edges have a level attribute equal to 0 and side-branches have a level attribute equal to 1 or higher based on their position relative to the current edge.

In most cases Electronic Horizon will return one MPP, but if there are two or more alternatives at an intersection that have a similar probability (a difference less or equal to 5%) Electronic Horizon might return several MPP paths. You can choose the MPP with a slightly higher probability or, if you have additional information about the road conditions, you can suggest which MPP the user should choose.

Edge metadata

Property nameDescriptionTypeOptional
idA unique identifier of the directed edge. This identifier may be different for the same actual edge in different dataset versions.LongNo
levelThe nesting level relative to MPP inside eHorizon (0 being the MPP, 1 branches of the MPP, 2 branches of level 1 branches).ByteNo
probabilityThe probability (as a percentage) for this edge to be taken by the driver. The probabilities of all outgoing edges on a single intersection sum up to 1.DoubleNo
headingThe heading (sometimes referred to as bearing) when starting to move along the edge in degrees (0-360).DoubleNo
lengthThe edge's length in meters.DoubleNo
outA list of outgoing edges.List<Edge>No
parentThe parent edge.EdgeYes
functionRoadClassFunctional road class (as defined by OpenStreetMap). One of the following: MOTORWAY, TRUNK, PRIMARY, SECONDARY, TERTIARY, UNCLASSIFIED, RESIDENTIAL, SERVICE_OTHER.StringNo
speedAverage speed along the edge in meters per second.DoubleNo
rampIf the edge is a ramp.BooleanNo
motorwayIf the edge is a motorway.BooleanNo
bridgeIf the edge is a bridge.BooleanNo
tunnelIf the edge is a tunnel.BooleanNo
tollIf there is a toll on the edge.BooleanNo
namesA list of road names.List<NameInfo>No
curvatureBinned number denoting the curvature degree of the edge (0-15).ByteNo
geometryThe edge's shape (polyline). This is onlt included when requested in the configuration options.LineStringYes
speedLimitThe max speed of the edge (speed limit) in meters per second.DoubleYes
laneCountThe number of lanes on the edge (does not change mid-edge).ByteYes
meanElevationThe mean elevation along the edge in meters.DoubleYes
countryCodeThe ISO 3166-1 alpha-3 country code.StringYes
stateCodeA state inside a country (ISO 3166-2).StringYes

How to configure Electronic Horizon

EHorizonOptions defines the options for the EHorizon.

AttributeDescriptionTypeDefault value
lengthThe minimum length of the MPP in meters. This does not include the trailingLength. The actual MPP length may be bigger.Double in range [1.0, 20000.0]500
expansionThe number of branches to include from the MPP. When set to 0 only the MPP is returned. Higher values will result in deeper nesting.Int in range [0, 2]0
branchLengthWhen expansion is set to anything but 0, this specifies the minimum length in meters branches will be expanded from the MPP.Double in range [1.0, 5000.0]50
includeGeometriesIf geometries should be included for edges. Excluding the edge shapes may save processing time on shape extraction and decoding.Booleanfalse

These can be specified through the NavigationOptions.

Listen to Electronic Horizon

The Navigation SDK's EHorizonObserver interface consists of two parts: onElectronicHorizonUpdated provides the Electronic Horizon and onPositionUpdated provides the position. This will always relate to the EHorizon previously conveyed through onElectronicHorizonUpdated. The position contains the edge and the progress along that edge in the Electronic Horizon.

Create the EHorizonObserver interface object:

val eHorizonObserver = object : EHorizonObserver {
    override fun onElectronicHorizonUpdated(horizon: EHorizon, type: String) {

    }

    override fun onPositionUpdated(position: EHorizonPosition) {

    }
}

Register the EHorizonObserver object with your already-instantiated MapboxNavigation object.

override fun onStart() {
    super.onStart()
    mapView.onStart()

    mapboxNavigation.registerEHorizonObserver(eHorizonObserver)
}
Note

Registering an EHorizonObserver activates the Electronic Horizon module.

Don't forget to unregister the EHorizonObserver interface:

override fun onStop() {
    super.onStop()
    mapView.onStop()

    mapboxNavigation.unregisterEHorizonObserver(eHorizonObserver)
}
Note

Unregistering all observers deactivates the module.

Use the Electronic Horizon output

The EHorizon is a tree structure that can be navigated by traversing the edges and their outgoing connections. This can be accomplished by looping over the edges. For common cases, some utilities have been added which are described below.

Get the current Edge

To get the current edge from the EHorizon, an EHorizon#current utility function is provided.

Get the MPP

To collect the entire MPP from the EHorizon, an EHorizon#mpp() utility function is provided that returns an ordered list of edges.

To collect only the edges starting at the current edge (which is important when the trailing length is greater than 0), pass in the current EHorizonPosition EHorizon#mpp(position).