NavigationVisualization

public protocol NavigationVisualization : AnyObject

Entry point for all methods related to the navigation visualization module. Instances of NavigationVisualization are created using NavigationVisualizationFactory.create(map:navigation:styleConfiguration:). You should call methods on these instances from the main thread only, otherwise an exception can occur.

A NavigationVisualization instance is used by first providing a RoutePlan with displayRoutePlan(:_). After that, the TomTomSDKRoute.Routes contained in the RoutePlan are displayed on the map, and you can use setActiveRoute(_:) to select a route to be navigated on. You can access the list of route primitives displayed on the map using routes. The selected route and the alternative routes are styled with the properties contained in the StyleConfiguration provided to NavigationVisualizationFactory.create(map:navigation:styleConfiguration:). After selecting the type of navigation guidance with selectGuidanceType(_:), you can start the navigation session with TomTomSDKNavigation.Navigation.start(). Once the navigation session is started, the route that is set becomes the active route. When you’re finished using NavigationVisualization, call TomTomSDKNavigation.Navigation.stop(). You can then call clearRoutePlan() to remove all the primitives that have been added to the map by the module. Visualization of on-route traffic incidents can be enabled or disabled using areTrafficIncidentsEnabled. If a TomTomSDKRoute.Route contained in the RoutePlan has traffic data available and areTrafficIncidentsEnabled is true, traffic incidents are displayed on the map on top of that TomTomSDKRoute.Route. You can access the list of traffic incidents that are on a route using trafficIncidents(on:).

The navigation visualization module subscribes to certain listeners during its life cycle, so that it can react automatically to important events:

  • TomTomSDKNavigation.NavigationStartObserver - Notifies the module when a navigation session starts. The module reacts by removing the alternative routes from the map, setting the camera tracking mode to TomTomSDKMapsDisplay.CameraTrackingMode.follow, and setting a default tilt angle.
  • TomTomSDKNavigation.NavigationProgressObserver - Notifies the module as the driver progresses on the route. The module reacts by updating the visual cue of the progress on the route (i.e., the grayed-out region behind the vehicle).
  • TomTomSDKNavigation.NavigationRouteObserver - Notifies the module if the driver deviates from the current route. A new route is provided along with the notification. The module reacts by replacing the current route with the new one.
  • TomTomSDKNavigation.NavigationGuidanceObserver - Notifies the module when new on-route instructions are available. The new instructions are provided along with the notification. The module reacts by updating the route with the new instructions.
  • TomTomSDKNavigation.NavigationArrivalObserver - Notifies the module when the driver reaches the destination. The module reacts by removing the route from the map, setting camera tracking mode to TomTomSDKMapsDisplay.CameraTrackingMode.follow, and setting the default 2D view. The module reacts by, for example, showing or hiding certain traffic markers (see RouteTrafficIncidentStyle.markerVisibilityByCategory).

Important

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

  • The list of TomTomSDKMapDisplay.Routes that is being displayed on the map. During display of a RoutePlan, this list contains the active route and the alternative This list will be empty after calling clear.

    Declaration

    Swift

    var routes: [TomTomSDKMapDisplay.Route] { get }

  • The active TomTomSDKMapDisplay.Route. This is nil before a RoutePlan has been displayed with displayRoutePlan(_:), or after calling clearRoutePlan().

    setActiveRoute(_:) For setting a different route to be navigated.

    Declaration

    Swift

    var activeRoute: TomTomSDKMapDisplay.Route? { get }

  • Configures whether automatic zoom is enabled. The default is true.

    Declaration

    Swift

    var isZoomToRoutePlanEnabled: Bool { get set }

  • Enables or disables visualization of on-route traffic incidents. This function can be called at any moment of the RoutingVisualization lifecycle. For example, if it is called when no traffic incidents are available (e.g., before displaying a route plan), the new visibility status (either enabled or disabled) is saved and applied later when traffic incidents are available. If it is called when traffic incidents are available (e.g., during the route planning phase), the new status takes effect immediately on the traffic incidents.

    Declaration

    Swift

    var areTrafficIncidentsEnabled: Bool { get set }

  • Displays a RoutePlan on the map. Adds a TomTomSDKRoute.Route instance to the map for each TomTomSDKRoute.Route 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 list of routes, then this method does nothing.

    Declaration

    Swift

    func displayRoutePlan(_ routePlan: TomTomSDKRoutingVisualization.RoutePlan)

    Parameters

    routePlan

    The RoutePlan to be displayed on the map.

  • Gets the list of TrafficIncidents that are being displayed on a certain TomTomSDKRoute.Route.

    Declaration

    Swift

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

    Parameters

    route

    The TomTomSDKMapDisplay.Route to get traffic incidents from.

    Return Value

    The list of TrafficIncidents on the route, or nil if the route is not in routes.

  • Set as active a TomTomSDKMapDisplay.Route from the routes displayed on the map. If the provided TomTomSDKMapDisplay.Route is not a route from the RoutePlan displayed with displayRoutePlan(_:), then this method does nothing.

    Declaration

    Swift

    func setActiveRoute(_ route: TomTomSDKMapDisplay.Route)

    Parameters

    route

    The TomTomSDKMapDisplay.Route to be active.

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

    Warning

    Do not remove manually the routes or markers which were added during displayRoutePlan(_:) using TomTomSDKMapDisplay.TomTomMap methods.

    Declaration

    Swift

    func clearRoutePlan()

  • Removes all alternative routes and corresponding traffic incidents added with displayRoutePlan(_:) from the map and keeps the activeRoute.

    Declaration

    Swift

    func clearAlternativeRoutes()

  • 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 module presents regular navigation guidance. When the type GuidanceType.laneLevel is selected, the module 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 module 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.

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

    Declaration

    Swift

    var safetyLocationVisualization: SafetyLocationVisualization { get }