Reconstructing a route from a polyline

VERSION 0.53.1
PUBLIC PREVIEW

In addition to route planning, this method provides another approach to obtain routes from the SDK. It offers the flexibility to import routes from custom sources, such as GPX files, or routes generated by different planning services.

Reconstruction modes

Polyline reconstruction comes in three distinct reconstruction modes. If no mode is specified, the SDK defaults to track.

  • track: Use this mode when the given polyline originates from a third-party source like for example a track recording. This mode provides flexibility when the provided route polyline does not perfectly align with the road network, allowing the reconstruction of the most sensible route. The input polyline may have inconsistencies such as gaps and loops. When reconstructing the route using this mode, the algorithm will try to respect the driving conditions.
  • route: This mode is suitable when the given polyline originates from a route previously planned by the same planner on the same map. The goal is to reconstruct the given route as closely as possible to the provided route polyline while adhering to driving and legal restrictions. The input polyline is expected to be normalized (aligned with the road network present on the map), without any loops or gaps. In cases where there are road restrictions on the input path, the algorithm attempts to find a local detour to accommodate these restrictions. The resulting reconstructed route tries to accurately follow the road network and comply with driving restrictions.
  • update: Use this mode when the given polyline originates from a route previously planned by the same planner on the same map. The goal is to reconstruct the given route as closely as possible to the provided route polyline, ignoring driving and legal restrictions in order to keep the input polyline geometry stable. The input polyline is expected to be normalized, without any loops or gaps. The resulting reconstructed route tries to accurately follow the road network and might result in an illegal route due to potential violation of driving restrictions.

These reconstruction modes offer a range of options for customizing the route reconstruction process, ensuring flexibility and accuracy based on the source of the input polyline.

The provided Swift code demonstrates how to reconstruct a route from a list of supporting points that adheres to the itinerary, utilizing the specified reconstruction mode to achieve the desired route representation:

1private func geometryToRoute(
2 geometry: [[CLLocationCoordinate2D]],
3 onRouteReady: ((TomTomSDKRoute.Route) -> ())? = nil,
4 completion: @escaping (Result<RoutePlanningResponse, Error>) -> ()
5) {
6 let origin = geometry.first?.first.map { ItineraryPoint(coordinate: $0) }
7 let destination = geometry.last?.last.map { ItineraryPoint(coordinate: $0) }
8 let waypoints = geometry.dropLast().compactMap { $0.last.map { ItineraryPoint(coordinate: $0) } }
9
10 let routingOptions: RoutePlanningOptions
11 do {
12 routingOptions = try RoutePlanningOptions(
13 itinerary: Itinerary(origin: origin!, destination: destination!, waypoints: waypoints),
14 routeLegOptions: geometry.map { RouteLegOptions(supportingPoints: $0) },
15 reconstructionMode: .track
16 )
17 } catch {
18 print("Invalid planning options: \(error.localizedDescription)")
19 return
20 }
21
22 routePlanner.planRoute(options: routingOptions, onRouteReady: onRouteReady) { result in
23 completion(result)
24
25 switch result {
26 case let .success(response):
27 print(response.routes)
28 case let .failure(error):
29 print(error)
30 }
31 }
32}

In this function, we define the itinerary, supply a list of supporting points that depict the desired route geometry, and designate the reconstruction mode to be utilized. This enables the generation of routes tailored to specific track data.

Next steps

After learning about polyline reconstruction, here are recommendations for the next steps: