Visual lane guidance

Visual lane guidance is only available with the Navigate license and a separate visual lane guidance license.

The HERE SDK supports visual lane guidance during turn-by-turn navigation to help drivers understand lane-level situations along a guided route.

This feature is intended for navigation scenarios where the application follows a Route with the VisualNavigator. It renders a route carpet that visualizes lane structure on the road and highlights the highly recommended lane (HLR) as a blue line to indicate where the driver should stay to follow the route.

If you are looking for lane data to build a custom lane UI, use the lane guidance APIs from the Get lane assistance chapter. Those APIs provide lane recommendations for the next maneuver (for example, recommended lanes and lane attributes), while physical lane-level road rendering comes from visual lane guidance. Visual lane guidance, in contrast, is a continuous on-road map rendering aid: it draws the route carpet and HLR directly on the road while guidance is active.

Visual lane guidance builds on a running turn-by-turn navigation session. To use it, make sure the following requirements are met:

1. Make sure you have a Navigate license and a separate visual lane guidance license.
2. Set a map scheme that supports lane rendering. MapScheme.clusterDay is recommended.
3. Make sure MapFeatureModes.terrain3d is disabled.
4. Set a supported camera behavior on the VisualNavigator: TransitionCameraBehavior or AutomotiveCameraBehavior. AutomotiveCameraBehavior is recommended.
5. If you use offline maps, enable LayerConfiguration.HD_LANES.

Visual lane guidance has the following limitations:

• Road types: Lane-level visualization is available on highways and freeways, including highway or freeway segments within cities.
• Roadworks: Lane-level visualization is not available on segments with road construction works. In this case, the guidance view can fall back to the standard navigation view.
• Coverage: The feature is available in North America (NAR), West Europe (WEU), and East Europe (EEU).

The VisualLaneGuidance example app on GitHub shows a possible implementation.

Step 1: Provide a route for guidance

Make sure guidance has a Route instance available before enabling visual lane guidance. Route calculation itself is covered in Calculate routes.

Step 2: Choose and initialize camera behaviors

Before implementing this step, choose how camera behavior should work for your guidance:

• TransitionCameraBehavior lets the HERE SDK automatically switch between lane-level visualization and the standard navigation view, based on route context and map data availability.
• AutomotiveCameraBehavior uses an automotive-style camera model and can be configured from a JSON asset for external tuning.

In this example, camera behavior setup is centralized in a dedicated CameraBehaviors class. The initializer creates both behaviors, sets AutomotiveCameraBehavior as default, and applies the active behavior to the VisualNavigator.

init(visualNavigator: VisualNavigator) {
	self.visualNavigator = visualNavigator
	self.transitionCameraBehavior = TransitionCameraBehavior.init()

	let configJson = CameraBehaviors.loadAutomotiveConfigJson()
	self.automotiveCameraBehavior = try! AutomotiveCameraBehavior(configJson: configJson)
	self.automotiveCameraBehavior.activeCameraType = .tracking

	self.activeCameraBehavior = self.automotiveCameraBehavior
	self.visualNavigator.cameraBehavior = self.activeCameraBehavior
}

Use TransitionCameraBehavior

Use TransitionCameraBehavior when you want the HERE SDK to switch automatically between lane-level visualization and the standard navigation view, based on the guided route and available map content.

func useTransitionCameraBehavior() {
	activeCameraBehavior = transitionCameraBehavior
	visualNavigator.cameraBehavior = activeCameraBehavior
}

Use AutomotiveCameraBehavior

Use AutomotiveCameraBehavior when you want to apply an automotive-style camera model. This behavior can be created from a JSON asset so that the camera tuning is configured externally.

Create the camera behavior like below:

private static func loadAutomotiveConfigJson() -> String {
	let path = Bundle.main.path(forResource: "AutomotiveCameraConfig", ofType: "json")!
	let content = try! String(contentsOfFile: path, encoding: .utf8)
	return content
}

Apply AutomotiveCameraBehavior like below:

func useAutomotiveCameraBehavior() {
	automotiveCameraBehavior.activeCameraType = .tracking
	activeCameraBehavior = automotiveCameraBehavior
	visualNavigator.cameraBehavior = activeCameraBehavior
}

The JSON asset used by this example is AutomotiveCameraConfig.json. This allows you to tune the automotive camera behavior externally instead of hardcoding all values in Swift. The loading code is shown above in the loadAutomotiveConfigJson() method.

Step 3: Start guidance with the VisualNavigator

Once a route is available and a camera behavior is selected, guidance can be started.

visualNavigator.startRendering(mapView: mapView)
visualNavigator.route = route

This is the point where visual lane guidance can become visible, provided that guidance is active and the route enters supported coverage.

Step 4: Feed location updates into the navigator

Forward each new location update to the VisualNavigator (from your positioning source or from a LocationSimulator).

visualNavigator.onLocationUpdated(location)

Without location updates, route progress cannot be detected and no guidance-related visualization can be updated.

The VisualLaneGuidance example app on GitHub shows how to calculate a route, start simulated guidance, use TransitionCameraBehavior for automatic mode switching based on map data availability, and switch to AutomotiveCameraBehavior configured from JSON.