Developer

Reconstructing a route from a polyline

VERSION 2.3.0-rc03

This guide describes features that are part of the Maps and Navigation SDK Extended flavor, available upon request. Contact us to get started.

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

Reconstruction modes

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

Before diving into specifics of each reconstruction mode, it’s very important to understand the common behavior:

  • No reconstruction mode (not even update) guarantees that the resulting route will preserve geometry exactly, even if the input polyline was computed by the same planner, on the same map.
  • Every reconstruction mode can result in a NoRouteFoundFailure.
    • To understand why this can happen, imagine the polyline that goes over the only bridge connecting an island. If that bridge is not present on the map, no route can be found.
    • How quickly will reconstruction give up and return NoRouteFoundFailure depends on the specified reconstruction mode, detailed below.
  • Every reconstruction mode may produce an illegal route.
    • More often than not, illegal route is deemed more useful than NoRouteFoundFailure. The illegal route includes SectionType.VehicleRestricted sections that explain why a legal route could not be found.
    • Therefore, users are expected to always check resulting route sections for illegality, regardless of the used reconstruction mode.

Available reconstruction modes:

  • track – Use this mode for importing "routes" from various sources of uncertain quality such as GPS tracks.
    • Input requirements:
      • The polyline does not have to closely match road geometry on the map where it’s being reconstructed.
      • Big gaps between polyline points are allowed.
      • The polyline can have loops, i.e. traverse the same road multiple times in the same route leg.
    • Behavior:
      • Loosely follows the polyline during route search.
      • Has the highest chance of reconstructing a legal route, but that route will often not go over the intended path, especially if traffic and/or routing restrictions are on that path.
  • route – Use this mode for importing routes originating from a (possibly custom or 3rd party) routing service.
    • Input requirements:
      • The polyline is expected to reasonably match road geometry on the map where it’s being reconstructed.
      • The polyline is expected to have no big gaps between points.
      • The polyline is expected to have no loops in the same leg.
    • Behavior:
      • Strictly follows the polyline during route search and doesn’t tolerate big deviations from it.
      • Makes a best effort to find a legal and locally optimized route at the cost of smaller deviations from the polyline.
      • Has the highest chance of resulting in NoRouteFoundFailure if traffic closures or other routing restrictions are encountered on the intended path.
  • update – Use this mode for obtaining up-to-date information for a route originating from a (possibly custom or 3rd party) routing service, while preserving its geometry.
    • Input requirements:
      • The polyline is expected to reasonably match road geometry on the map where it’s being reconstructed.
      • The polyline is expected to have no big gaps between points.
      • The polyline is expected to have no loops in the same leg.
    • Behavior:
      • Strictly follows the polyline during route search and doesn’t tolerate big deviations from it.
      • Makes a best effort to preserve the geometry of the input polyline.
      • During route search ConsiderTraffic is being ignored.
      • Has the highest chance of reconstructing a route, though that route will often be suboptimal or illegal if traffic and/or routing restrictions are on the intended path.

Decision guide for choosing a reconstruction mode

1flowchart TD
2

3  %% Q1
4  A{Is your route of good quality?}
5

6  %% Q1 → No
7  A -- No --> T[track]
8

9  %% Q1 → Yes → Q2
10  A -- Yes --> B{Do you want locally optimized version of it?}
11

12  %% Q2 branches
13  B -- No --> U1[update]
14  B -- Yes --> R[route]
15

16  %% Q3 after choosing route
17  R --> C{Unhappy with the result and wonder how your original route would look like?}
18

19  %% Q3 branch (Yes only)
20  C -- Yes --> U2[update]

Code snippet

The provided Kotlin 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:

1fun trackToRoute(track: List<List<GeoPoint>>) {
2    val waypoints = (track.dropLast(1).map { it.last() })
3    val routePlanningOptions = RoutePlanningOptions(
4        itinerary = Itinerary(
5            origin = track.first().first(),
6            destination = track.last().last(),
7            waypoints = waypoints,
8        ),
9        routeLegOptions = track.map { legPoints ->
10            RouteLegOptions(supportingPoints = legPoints)
11        },
12        reconstructionMode = ReconstructionMode.Track,
13    )
14    val cancellable = routePlanner.planRoute(routePlanningOptions, routePlanningCallback)
15}

In this function, we define the itinerary, provide a list of supporting points that depict the desired route geometry, and designate the reconstruction mode to use. 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: