OffRoadTomTomNavigationFactory

public enum OffRoadTomTomNavigationFactory

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.