Horizon hazards

The Hazards Warning service helps drivers anticipate potential dangers on the road. It provides safety-related warnings about upcoming hazardous situations, such as slippery surfaces, animals or objects in the roadway, reduced visibility due to fog, and other hazards.

The Hazards SDK provides data for various categories of hazards, including:

• Traffic hazards
• Weather hazards
• Road hazards
• Generic hazards

Configuring horizon

After completing the Retrieving horizon data guide, you can subscribe for horizon updates and start navigation to retrieve horizon data.

Specifying horizon options

To subscribe to hazard horizon elements, create HorizonOptions via the createHorizonOptions method and specify HazardElementType in the list of element types of interest. The horizon path parameters defined within createHorizonOptions are appropriate for most use cases and can be utilized in both free driving and active guidance scenarios.

val horizonOptions = buildHorizonOptions(listOf(HazardElementType))

1val horizonOptions =
2    HorizonOptions(
3        elementTypes = listOf(HazardElementType),
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 for horizon updates with the horizon options you have defined.

tomTomNavigation.addHorizonUpdatedListener(horizonOptions, horizonUpdatedListener)

Starting navigation

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

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

Retrieving hazards

With navigation started, you will now listen to horizon updates and retrieve hazard data.

If a hazard zone stretches beyond the end of the horizon, the SDK only provides data for the part of the zone within the horizon length. As the horizon is extended ahead of the vehicle while the vehicle moves along the zone hazard location, the end offset of the hazard horizon element is updated accordingly.

Filtering hazards

Some of the retrieved hazards may not be relevant to the driver. For example, the driver may not be interested in strong winds as it is not a concern for the vehicle location. To filter out irrelevant hazards, you can simply add additional filtering during the retrieval of the hazard horizon elements:

1private fun HorizonPath.retrieveHazardElements(): List<HazardElement> = getElements(HazardElementType)
2    .map { it as HazardElement }
3    .filter { element ->
4        // Filters out hazards of type StrongWind
5        element.hazard.type != HazardType.StrongWind
6    }

Next steps

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

• Retrieving horizon data