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 name | Description | Type | Optional |
|---|---|---|---|
id | A unique identifier of the directed edge. This identifier may be different for the same actual edge in different dataset versions. | Long | No |
level | The nesting level relative to MPP inside eHorizon (0 being the MPP, 1 branches of the MPP, 2 branches of level 1 branches). | Byte | No |
probability | The probability (as a percentage) that the driver will take this edge. The probabilities of all outgoing edges on a single intersection sum up to 1. | Double | No |
heading | The heading (sometimes referred to as bearing) when starting to move along the edge in degrees (0-360). | Double | No |
length | The edge's length in meters. | Double | No |
out | A list of outgoing edges. | List<Edge> | No |
parent | The parent edge. | Edge | Yes |
functionRoadClass | Functional road class (as defined by OpenStreetMap). One of the following: MOTORWAY, TRUNK, PRIMARY, SECONDARY, TERTIARY, UNCLASSIFIED, RESIDENTIAL, SERVICE_OTHER. | String | No |
speed | Average speed along the edge in meters per second. | Double | No |
ramp | If the edge is a ramp. | Boolean | No |
motorway | If the edge is a motorway. | Boolean | No |
bridge | If the edge is a bridge. | Boolean | No |
tunnel | If the edge is a tunnel. | Boolean | No |
toll | If there is a toll on the edge. | Boolean | No |
names | A list of road names. | List<RoadName> | No |
curvature | Binned number denoting the curvature degree of the edge (0-15). | Byte | No |
geometry | The edge's shape (polyline). This is only included when requested in the configuration options. | LineString | Yes |
speedLimit | The max speed of the edge (speed limit) in meters per second. | Double | Yes |
laneCount | The number of lanes on the edge (does not change mid-edge). | Byte | Yes |
meanElevation | The mean elevation along the edge in meters. | Double | Yes |
countryCode | The ISO 3166-1 alpha-3 country code. | String | Yes |
stateCode | A state inside a country (ISO 3166-2). | String | Yes |
How to configure Electronic Horizon
EHorizonOptions defines the options for the EHorizon.
| Attribute | Description | Type | Default value |
|---|---|---|---|
length | The 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 |
expansion | The 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 |
branchLength | When the expansion property is 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 |
includeGeometries | If geometries should be included for edges. Excluding the edge shapes may save processing time on shape extraction and decoding. | Boolean | false |
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 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)
}
EHorizonObserver activates the Electronic Horizon module.Don't forget to unregister the EHorizonObserver interface:
override fun onStop() {
super.onStop()
mapView.onStop()
mapboxNavigation.unregisterEHorizonObserver(eHorizonObserver)
}
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).