NavigationVisualization

public protocol NavigationVisualization : AnyObject

Entry point for all methods related to the navigation visualization.

To start using the navigation visualization, create an instance using NavigationVisualizationFactory.create(map:navigation:styleConfiguration:). Then provide the instance with a collection of TomTomSDKRoute.Route using the NavigationVisualization.displayRoutePlan(_:) method. After that, the TomTomSDKRoute.Route contained in the collection is displayed on the map, and you can use NavigationVisualization.setActiveRoute(_:) to select a route on which to navigate. You can access the collection of route primitives displayed on the map using routes property. The active route and the alternative routes are styled with the properties contained in the StyleConfiguration provided to NavigationVisualizationFactory.create(map:navigation:styleConfiguration:). Next, select the type of navigation guidance with NavigationVisualization.selectGuidanceType(_:), and start the navigation session with Navigation.start(). Once the navigation session is started, the route that is selected becomes the active route. When you’re done using a NavigationVisualization instance, call Navigation.stop(). Then call NavigationVisualization.clear() to remove all the primitives that have been added to the map by the add-on.

If a TomTomSDKRoute.Route has traffic data available, traffic incidents are displayed on the map on top of the TomTomSDKRoute.Route. You can access the list of traffic incident lines that are on a route using NavigationVisualization.trafficOnRoutes(_:) property by UUID of corresponding TomTomSDKMapDisplay.Route.

The navigation visualization add-on observes certain events during its lifecycle so that it can react automatically to important events:

  • NavigationArrivalObserver.didStart(with:): The add-on observes when a navigation session starts.
  • NavigationRouteObserver.didReplanRoute(replannedRoute:reason:) : The add-on observes when the current route is updated.
  • NavigationProgressObserver.didUpdateProgress(progress:): The add-on observes when progress is updated on the current route.

  • NavigationArrivalObserver.didArriveAtDestinationOn(route:): The add-on observes when the driver reaches the destination.

Important

This is a Public Preview API. It may be changed or removed at any time.

  • The list of routes displayed on the map contains the: - active route - alternative routes.

    The active route is available after calling the setActiveRoute(_:) method. When a navigation session starts, the alternative routes are removed from this list. The list contains only the active route (activeRoute). After calling clear(), the list is empty.

    Declaration

    Swift

    var routes: [TomTomSDKMapDisplay.Route] { get }

  • The TomTomSDKMapDisplay.Route selected for navigation. This property contains the active route during a navigation session. This is nil (empty) before routes have been displayed with displayRoutePlan(_:), or after calling clear().

    Declaration

    Swift

    var activeRoute: TomTomSDKMapDisplay.Route? { get }

  • Enables or disables automatic zoom to routes when displayRoutePlan(_:) is invoked.

    The default is true.

    Declaration

    Swift

    var zoomToRoutesEnabled: Bool { get set }

  • Displays a RoutePlan on the map. Adds a Route instance to the map for each RoutePlan contained in the route plan. By default, the first route of the plan is active, but you can set a different route using setActiveRoute(_:) Consecutive calls of this method replace the previous RoutePlan being displayed. If the provided RoutePlan contains an empty collection of routes, then this method does nothing.

    Declaration

    Swift

    func displayRoutePlan(_ routePlan: TomTomSDKRoutingVisualization.RoutePlan)

  • Set an active TomTomSDKMapDisplay.Route to be navigated, when a navigation session starts.

    If the provided TomTomSDKMapDisplay.Route is not a route displayed with displayRoutePlan(_:), then this method does nothing.

    Declaration

    Swift

    func setActiveRoute(_ route: TomTomSDKMapDisplay.Route)

    Parameters

    route

    Route to be highlighted.

  • Retrieves the collection of traffic incidents.

    Declaration

    Swift

    func trafficOnRoute(route: TomTomSDKMapDisplay.Route) -> [TrafficIncident]

  • Removes all routes that have been added with displayRoutePlan(_:) from the map, and sets activeRoute to nil.

    Declaration

    Swift

    func clear()

  • The type of navigation guidance selected.

    The default is GuidanceType.regular. You can call selectGuidanceType(:_) to select a different navigation guidance type.

    Declaration

    Swift

    var guidanceType: GuidanceType { get }

  • Selects the type of guidance to be used when a navigation session starts.

    When the type GuidanceType.regular is selected, the add-on presents regular navigation guidance. When the type GuidanceType.laneLevel is selected, the add-on is instructed to present lane-level guidance, but it may still present regular navigation guidance. This happens because of an internal fallback mechanism that switches from lane-level guidance mode to the regular one when no lane-level data is available. The add-on switches back to lane-level guidance mode as soon as lane-level data is available again. Note that the property guidanceType is not affected when this fallback mechanism kicks in.

    Important

    DO NOT USE GuidanceType.lanelevel. THIS FEATURE IS NOT IMPLEMENTED YET.

    Declaration

    Swift

    func selectGuidanceType(_ guidanceType: GuidanceType)

    Parameters

    guidanceType

    The GuidanceType to be used during the navigation session.

  • Toggle the visibility of traffic incidents on route.

    The default is true.

    Declaration

    Swift

    var trafficIncidentsEnabled: Bool { get set }

  • Object to address visualization of vehicle-horizon such as configuration, user interaction, etc.

    Declaration

    Swift

    var horizonVisualization: HorizonVisualization { get }