Horizon safety locations

Safety locations are used worldwide to enforce speed limits and other traffic regulations. Cameras are frequently placed in high-risk areas to minimize the impact of difficult and dangerous stretches of road.

The Safety Cameras SDK provides data for various types of safety locations, including:

• Red light cameras
• Fixed speed cameras
• Mobile speed cameras
• Speed enforcement zones
• Restricted areas
• Danger zones
• Risk zones

Configuring horizon

Having completed the Retrieving horizon data guide, you are now able to subscribe for horizon updates and start navigation to retrieve horizon data.

Specifying horizon options

To subscribe to safety location horizon elements, create HorizonOptions via the buildHorizonOptions method and specify SafetyLocationElementType in the list of element types of interest. The horizon path parameters defined within buildHorizonOptions are appropriate for most use cases and can be utilized in both free driving and active guidance scenarios. The buildHorizonOptions method will create a HorizonOptions instance with a main path search distance that is the minimum between 25 km and the remaining route length when navigating with a route, or 10 km when free driving.

1
val horizonOptions =
2
    buildHorizonOptions(listOf(SafetyLocationElementType))

1
val horizonOptions =
2
    HorizonOptions(
3
        elementTypes = listOf(SafetyLocationElementType),
4
        mainPathSearchOptions =
5
            MainPathSearchOptions(
6
                searchDistancePolicy = ExplicitDistancePolicy(
7
                    searchDistance = PathSearchDistance(maxHorizonLength = Distance.kilometers(2)),
8
                ),
9
            ),
10
        subPathSearchOptions = listOf(
11
            SubPathSearchOptions(
12
                searchDistance = PathSearchDistance(maxHorizonLength = Distance.meters(100)),
13
            ),
14
        ),
15
        numberOfPaths = 10,
16
    )

Registering a horizon updated listener

Before starting navigation, register a HorizonUpdatedListener to listen to horizon updates for the horizon options you defined.

1
tomTomNavigation.addHorizonUpdatedListener(horizonOptions, horizonUpdatedListener)

Starting navigation

Then, start navigation with a route as described in the Retrieving horizon data guide.

1
val routePlan = RoutePlan(route, routePlanningOptions)
2
val navigationOptions = NavigationOptions(routePlan)
3
tomTomNavigation.start(navigationOptions)

Retrieving safety locations

With navigation started, you can listen to horizon updates and retrieve safety location data.

Filtering safety locations

Some of the retrieved safety locations might be located in a country where it is prohibited to use devices that alert the driver about safety locations. Moreover, the legislation of a country may also be ambiguous with respect to safety locations. You have to assess the situation and, if necessary, filter out safety locations for which it is illegal to issue alerts.

Crossing into another country implies complying with different legislation. To filter out safety locations from countries where reporting them is illegal, you can take the following steps:

1. Configure HorizonOptions to also subscribe to country information in addition to safety locations:

   1
   val horizonOptions =
   2
       buildHorizonOptions(listOf(SafetyLocationElementType, CountryInformationElementType))

2. Implement a listener to get horizon updates and filter out safety locations:

   1
   private val horizonUpdatedListener =
   2
       object : HorizonUpdatedListener {
   3
           private var horizonSnapshot: HorizonSnapshot? = null
   4
   
   5
           override fun onPositionUpdated(
   6
               options: HorizonOptions,
   7
               position: HorizonPosition,
   8
           ) {
   9
               horizonSnapshot?.let { horizonSnapshot ->
   10
                   horizonSnapshot.mainPath()?.let { mainPath ->
   11
                       val forbiddenCountryInformationElements =
   12
                           mainPath.retrieveForbiddenCountryInformationElements()
   13
                       val safetyLocationElements =
   14
                           mainPath.retrieveSafetyLocationElements()
   15
   
   16
                       val legalSafetyLocationElements =
   17
                           retrieveLegalSafetyLocationElements(
   18
                               safetyLocationElements,
   19
                               forbiddenCountryInformationElements,
   20
                           )
   21
   
   22
                       Log.v(TAG, "Safety locations for which alerts are legal:")
   23
                       legalSafetyLocationElements.forEach { safetyLocation ->
   24
                           Log.v(TAG, "$safetyLocation")
   25
                       }
   26
                       getRemainingDistanceInZone(safetyLocationElements, position)
   27
                       logAverageSpeedInAverageSpeedZone(safetyLocationElements, position)
   28
                   }
   29
               }
   30
           }
   31
   
   32
           override fun onHorizonReset(options: HorizonOptions) {
   33
               Log.v(TAG, "Horizon reset")
   34
           }
   35
   
   36
           override fun onSnapshotUpdated(
   37
               options: HorizonOptions,
   38
               snapshot: HorizonSnapshot,
   39
           ) {
   40
               horizonSnapshot = snapshot
   41
           }

3. Extract the country information elements that correspond to countries where reporting safety locations is illegal.

   1
   private fun HorizonPath.retrieveForbiddenCountryInformationElements(): List<CountryInformationElement> =
   2
       getElements(CountryInformationElementType)
   3
           .map { it as CountryInformationElement }
   4
           .filter {
   5
               // Allows only country information elements from Germany or the US state of California
   6
               (it.countryCodeIso3 == "DEU") ||
   7
                   (it.countryCodeIso3 == "USA" && it.regionCode == "CA")
   8
           }

4. Filter out the safety locations from those countries:

   1
   private fun retrieveLegalSafetyLocationElements(
   2
       safetyLocationElements: List<SafetyLocationElement>,
   3
       forbiddenCountryInformationElements: List<CountryInformationElement>,
   4
   ): List<SafetyLocationElement> = safetyLocationElements.filterNot { safetyLocationElement ->
   5
       forbiddenCountryInformationElements.map { countryInformationElement ->
   6
           safetyLocationElement.isInCountry(countryInformationElement)
   7
       }.any { it }
   8
   }
   9
   
   10
   private fun SafetyLocationElement.isInCountry(
   11
       countryInformationElement: CountryInformationElement,
   12
   ): Boolean = if (this.pathId == countryInformationElement.pathId) {
   13
       this.startOffset >= countryInformationElement.startOffset &&
   14
           this.startOffset < countryInformationElement.endOffset ||
   15
           this.endOffset > countryInformationElement.startOffset &&
   16
           this.endOffset <= countryInformationElement.endOffset
   17
   } else {
   18
       false
   19
   }

You can also filter out specific safety location types:

1
private fun HorizonPath.retrieveSafetyLocationElements(): List<SafetyLocationElement> =
2
    getElements(SafetyLocationElementType)
3
        .map { it as SafetyLocationElement }
4
        .filter { element ->
5
            // Filters out safety locations of type RestrictionCamera
6
            element.safetyLocation.type != SafetyLocationType.RestrictionCamera
7
        }

Understanding the isFinal state of safety location elements

The horizon path extends ahead as the vehicle progresses. Depending on the configured horizon search distance and the safety location zone’s own length, it might initially stretch beyond the end of the horizon path. If this is the case, the horizon snapshot will include only part of the safety location zone. As the vehicle moves along the zone, the horizon path continues to extend, overlapping a gradually increasing section of the zone. The end offset and the geometry of the safety location element are updated dynamically and reflect the extent to which the current horizon snapshot covers the zone. The isFinal flag indicates when this dynamic updating stops. It switches to true once the horizon snapshot fully covers the exit point of the safety location zone. From that moment on, the end offset and the element geometry become stable and are no longer updated.

This mechanism enables you to:

• Evaluate the remaining distance to the end of the zone. As long as isFinal remains false, the remaining distance is greater than the configured horizon search distance. Once isFinal becomes true, you can compute the remaining distance as the difference between the end offset of the element and the offset of the vehicle position.
• Place end marker icons on the map. While isFinal is still false, the icon would change position frequently. To avoid that, you can choose to only display the icon after isFinal becomes true.

1
private fun getRemainingDistanceInZone(
2
    safetyLocationElements: List<SafetyLocationElement>,
3
    horizonPosition: HorizonPosition,
4
) {
5
    safetyLocationElements
6
        .filter { it.safetyLocation.type == SafetyLocationType.AverageSpeedZone }
7
        .forEach { element ->
8
            if (horizonPosition.pathId == element.pathId &&
9
                horizonPosition.offset in element.startOffset..element.endOffset
10
            ) {
11
                if (element.isFinal) {
12
                    val remainingDistance = element.endOffset - horizonPosition.offset
13
                    Log.v(TAG, "Remaining distance to end of zone: $remainingDistance")
14
                }
15
            }
16
        }
17
}

Average speed in average speed zones

An AverageSpeedZone is a fixed zone in which multiple cameras calculate the average speed of vehicles traveling through the zone. When a safety location of this type is present on the horizon, the Navigation SDK provides the current average speed of the vehicle from the moment it enters the zone. This value is updated in real time as new speed data is collected, and is available only while the vehicle remains inside the zone.

1
private fun logAverageSpeedInAverageSpeedZone(
2
    safetyLocationElements: List<SafetyLocationElement>,
3
    horizonPosition: HorizonPosition,
4
) {
5
    safetyLocationElements
6
        .filter { it.safetyLocation.type == SafetyLocationType.AverageSpeedZone }
7
        .forEach { element ->
8
            if (horizonPosition.pathId == element.pathId &&
9
                horizonPosition.offset in element.startOffset..element.endOffset
10
            ) {
11
                val averageSpeed = element.currentAverageSpeed
12
                if (averageSpeed != null) {
13
                    Log.v(TAG, "Current average speed in zone: $averageSpeed")
14
                }
15
            }
16
        }
17
}

Next steps

Now that you know how to retrieve horizon safety locations, here are the recommendations on what to explore next:

• Retrieving horizon data
• Retrieving horizon hazards
• Safety Locations