TomTom SDK for iOS NavigationVisualization

NavigationVisualization

public protocol NavigationVisualization : AnyObject

Entry point for all methods related to the navigation visualization module. Instances of NavigationVisualization are created using 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 navigate. 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 create(map:navigation:styleConfiguration:). After selecting the type of navigation guidance with the property guidanceType, 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/followNorthUp, 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/GuidanceUpdateObserver - 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/NavigationDestinationArrivalObserver - 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/followNorthUp, and setting the default 2D view.
    • TomTomSDKMapDisplay/CameraEventObserver - Notifies the module when a parameter of the camera changes. The module reacts by, for example, showing or hiding certain traffic markers (see markerVisibilityByCategory).

  • 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 routes. The alternative routes are removed from this list when a navigation session starts, so that it only contains the activeRoute. This list is empty after calling clearRoutePlan().

    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 has an immediate effect 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 from which to get traffic incidents.

    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 manually remove the routes or markers added during displayRoutePlan(_:) using TomTomSDKMapDisplay/TomTomMap methods. It may cause unpredictable behavior.

    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()

  • Configures the camera tracking mode and updates it if needed.

    This function allows you to set camera configuration parameters for a given tracking mode. The configuration gets updated immediately if the provided mode matches the current mode active on the map.

    Note

    If the current camera tracking mode on the map matches the provided mode, the map’s camera tracking mode will be updated with the new configuration. Otherwise, the configuration is stored internally and will be applied when that mode is activated later on.

    Declaration

    Swift

    func setCameraTrackingMode(_ trackingMode: TomTomSDKMapDisplay.CameraTrackingMode)

    Parameters

    trackingMode

    The CameraTrackingMode value that specifies the desired camera tracking mode configuration.

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

    When the type regular is selected, the module presents regular navigation guidance. When the type laneLevel is selected, the module is instructed to present lane-level guidance, but it may still present regular navigation guidance. This occurs because of an internal fallback mechanism that switches from lane-level guidance mode to regular guidance mode 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 this property is unaffected when this fallback mechanism activates. laneLevel shouldn’t be used, unless the lane-level style is enabled.

    The default is regular.

    Declaration

    Swift

    var guidanceType: GuidanceType { get set }

  • Object to address visualization of safety locations such as configuration, user interaction, etc.

    Important

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

    Declaration

    Swift

    var safetyLocationVisualization: SafetyLocationVisualization { get set }