Enumerations

Factory for creating an off-road ArrivalDetectionEngine instance.

Off-road arrival detection engine detects when the driver has reached their final destination during off-road navigation.

Example of creating an OffRoadArrivalDetectionEngine with the default value for destinationArrivalDistanceThreshold:

let offRoadArrivalDetectionEngine = OffRoadArrivalDetectionEngineFactory.create()

Example of creating an OffRoadArrivalDetectionEngine with a specific value for destinationArrivalDistanceThreshold:

let offRoadArrivalDetectionEngine = OffRoadArrivalDetectionEngineFactory.create(destinationArrivalDistanceThreshold: .tt.meters(5))

To create a default off-road Navigation, check the OffRoadTomTomNavigationFactory class.

See more

public enum OffRoadArrivalDetectionEngineFactory

Off-road navigation is designed for areas without roads, such as rural or wilderness areas or where traditional road navigation systems are inaccurate. You can enable off-road navigation using routes imported from GPS Exchange Format (GPX) files.

To create off-road Navigation instance, use the OffRoadTomTomNavigationFactory class:

let configuration = OffRoadTomTomNavigationFactory.Configuration(locationProvider: DefaultCLLocationProvider())
let tomTomNavigation = OffRoadTomTomNavigationFactory.create(configuration: configuration)

Next parse the imported GPX file to turn it into an array of CLLocationCoordinate2D. You can use your own or a third-party GPX parser library to create a list of coordinates from a GPX file. For this example CoreGPX is being used.

import CoreGPX

guard let inputPath = Bundle.main.path(forResource: "Test", ofType: "gpx"),
let gpx = GPXParser(withPath: inputPath)?.parsedData() else { return }

// list of coordinates from waypoints
let coordinates = gpx.waypoints.map { ($0.latitude, $0.longitude) }

// list of coordinates from tracks
let coordinates = gpx.tracks[0].segments[0].points.map{ ($0.latitude, $0.longitude) }

Once you have the array of CLLocationCoordinate2D, create the Route instance. For example see the implementation of createRoute function:

// Creates a ``Route`` from a list of [CLLocationCoordinate2D] representing a route.
// The created route contains:
//   - One leg with geometry as provided [coordinates].
//   - Origin as the first point from provided [coordinates].
//   - Destination as the last point from provided [coordinates].
//   - Total length of the route.
//   - Calculated route points.

// The created route doesn't contain:
//   - Travel, departure, and arrival time.
//   - Guidance instructions.

// Parameter: coordinates: The geometry of the [Route].
// Returns: Created ``Route``
// Throws: Error when `coordinates` doesn't contain at least two points.

func createRoute(coordinates: [CLLocationCoordinate2D]) throws -> Route {
    // Calculate the total distance covered by all items in the input CLLocationCoordinate2D array.
    let routeLength = coordinates.totalDistance()

    // Create a route summary
    let summary = Summary(
        length: Measurement.tt.meters(routeLength),
        travelTime: Measurement.tt.minutes(0),
        trafficLength: Measurement.tt.meters(0),
        trafficDelay: Measurement.tt.minutes(0),
        departureTime: Date(),
        arrivalTime: Date(),
        consumptionForWholeLength: nil,
        consumptionUpToReachableOffset: nil,
        remainingBudget: nil,
        reachableOffset: nil
    )

    // Create a route leg
   let routeLegs = RouteLeg(geometry: coordinates, instructions: [], summary: summary)

    // Calculate cumulative distance and create an array of route points
    var cumulativeDistance = 0.0
    let routePoints = coordinates.enumerated().map { index, coordinate -> RoutePoint in
        if index > 0 {
            cumulativeDistance += coordinate.distanceTo(coordinate: coordinates[index - 1])
        }
       return RoutePoint(
            coordinate: coordinate,
            routeOffset: Measurement.tt.meters(cumulativeDistance),
       travelTime: Measurement.tt.hours(0)
     )
   }

    // Create a route
    let route = Route (
        summary: summary,
        legs: [routeLegs],
        routeStops: [],
        sections: TomTomSDKRoute.Sections(),
        routePoints: routePoints
     )

    guard let route = route else {
      // route could be nil; one of the reasons is: the coordinates array contains less than two points.
      throw "Can't create a route"
    }

    return route
}

To be notified of the navigated route changes, observe the route tracking change updates. The information about the route state is represented by RouteTrackingState. When the user deviates or returns to the planned route, the navigation engine sends route-tracking state updates to the observer.

The state can be either RouteTrackingState.followed or RouteTrackingState.deviated, depending on whether the user is on the planned route or has deviated from it. Route tracking state updates are provided through the onRouteTrackingStateUpdate(routeTrackingState:) observer method, which is called throughout the route navigation process. To handle these updates, implement the NavigationRouteTrackingStateUpdateObserver protocol.

func onRouteTrackingStateUpdate(routeTrackingState: TomTomSDKNavigationEngines.RouteTrackingState) {
   switch routeTrackingState {
   case let .deviated(route: route, backToRoutePoint: backToRoutePoint):
   // One of the possible ways of deviation handling is to show a dotted line indicating the shortest path back to the planned route from the user's current location,
   // using the coordinates from backToRoutePoint, the point where the user has deviated from the planned route.
       let currentloc = defaultLocationProvider.location!.location.coordinate
       mapCoordinator?.drawBackToRoutePolyline(coordinates: [backToRoutePoint, currentloc])
   case let .followed(route: route):
   // When the user is back on the planned route the previously added dotted line can be removed.
       mapCoordinator?.removeBackToRoutePolyline()
   }
}

To start receiving route tracking state updates, become an observer using Navigation.addRouteTrackingStateUpdateObserver(_ observer:):

let routeTrackingStateObserver: NavigationRouteTrackingStateUpdateObserver = ...
navigation.addRouteTrackingStateUpdateObserver(routeTrackingStateObserver)

To stop receiving route tracking state updates, remove the previously added observer using Navigation.removeRouteTrackingStateUpdateObserver(_ observer:):

navigation.removeRouteTrackingStateUpdateObserver(routeTrackingStateObserver)

Finally, remember that an imported off-road route from a GPX file is parsed as it is and not checked for impassable places or closed roads. It also provides no routing guidance.

See more

public enum OffRoadTomTomNavigationFactory

Factory for creating an off-road GuidanceEngine instance.

Off-road navigation guidance provides directions and help for travel on unpaved or unmarked paths, such as trails, dirt roads, or open terrain. This API provides a way to create GuidanceEngine instances that handle off-road navigation guidance.

To create a default off-road Navigation, check the OffRoadTomTomNavigationFactory class.

See more

public enum OffRoadGuidanceEngineFactory

Factory for creating an off-road LocationContextProviderEngine instance.

Location context provides environmental data about the user’s current location. For off-road navigation, the LocationContext is different from traditional navigation due to the lack of mapped data about the surroundings.

To create a default off-road Navigation, check the OffRoadTomTomNavigationFactory class.

See more

public enum OffRoadLocationContextProviderEngineFactory

Factory for creating an off-road MapMatchingEngine instance.

Map-matching is the process of aligning GPS traces with the road network data on a digital map. It involves matching GPS coordinates to the roads on the map and snapping the points to the nearest roadway. For off-road navigation there’s no information on the roads to map-match it on a digital map, instead the raw location of the user is shown on the map.

To create a default off-road Navigation, check the OffRoadTomTomNavigationFactory class.

See more

public enum OffRoadMapMatchingEngineFactory

Factory for creating an off-road RouteProgressEngine instance.

This factory creates an instance of the RouteProgressEngine that is specifically designed for off-road navigation. The RouteProgressEngine is used to calculate the progress along the route, including the user’s position, speed, estimated time of arrival, and current location.

For off-road navigation, progress is calculated using RoutePoints along the route in straight-line distance without taking into account the estimated time of arrival or speed, only the raw location of the vehicle.

To create a default off-road Navigation, check the OffRoadTomTomNavigationFactory class.

See more

public enum OffRoadRouteProgressEngineFactory

Factory for creating an off-road RouteProjectionEngine instance.

Route projection is used in road navigation to match the route used by the map matcher and vehicle horizon, ensuring a consistent experience for users. In off-road navigation, there is no map data available, so route projection is not used to match the route. However, an off-road route projection engine is still needed as part of the navigation configuration.

To create a default off-road Navigation, check the OffRoadTomTomNavigationFactory class.

See more

public enum OffRoadRouteProjectionEngineFactory

Factory for creating an off-road RouteReplanner instance.

Route replanning is used in road navigation to refresh the route and plan a new route when deviation is detected. Deviation occurs when the driver leaves the planned route or when unexpected road closures or traffic incidents occur. In off-road navigation, a GPX file is used to plan the route, but the functionalities for refreshing the route and handling deviation are not supported. If replanning is enabled, the OffRoadRouteReplanner will throw a notSupportedForOffRoadNavigation error.

To create a default off-road Navigation, check the OffRoadTomTomNavigationFactory class.

See more

public enum OffRoadRouteReplannerFactory

Factory for creating an off-road RouteTrackingEngine instance.

The RouteTrackingEngine monitors if the driver is following the planned route or deviating from it and informs listeners of the NavigationRouteTrackingStateUpdateObserver. The engine uses data from the NavigationSnapshot to determine whether the driver is on track. Then it returns a RouteTrackingState with information about whether the driver is following the route.

To create a default off-road Navigation, check the OffRoadTomTomNavigationFactory class.

See more

public enum OffRoadRouteTrackingEngineFactory