Routing On Map

_|

In this guide you will learn how to render an interactive map, compute and render a route on the map and fly to the route.

Displayed routes

Centered route

Routing Service

Inside MainActivity.kt retain a RoutingService instance. Normally in Android's MVVM, services are retained in the Repository layer, injected via dependency injection, and ultimately consumed by ViewModels but for the scope of this example we will use it inside an activity. The routing service has onStarted and onCompleted callbacks which will update the UI.

MainActivity.kt

class MainActivity : AppCompatActivity()
{
    //...

    private val routingService = RoutingService(
        onStarted = {
            progressBar.visibility = View.VISIBLE
        },
        onCompleted = { routes, errorCode, _ ->
            progressBar.visibility = View.GONE
            when (errorCode) {
                GemError.NoError -> {
                    SdkCall.execute {
                        gemSurfaceView.mapView?.presentRoutes(routes, displayBubble = true)
                    }
                }
                GemError.Cancel -> {
                    // The routing action was cancelled.
                }
                else -> {
                    // There was a problem at computing the routing operation.
                    Toast.makeText(
                        this@MainActivity,
                        "Routing service error: ${GemError.getMessage(errorCode)}",
                        Toast.LENGTH_SHORT
                    ).show()
                }
            }
        }
    )
    //...
}

Calculating route

MainActivity.kt

class MainActivity : AppCompatActivity()
{
    //...
    override fun onCreate(savedInstanceState: Bundle?)
    {
        //...
        // Defines an action that should be done when the world map is ready (Updated/ loaded).
        SdkSettings.onMapDataReady = onMapDataReady@{ isReady ->
            if (!isReady) return@onMapDataReady
            calculateRoute()
            //...
        }
        //...
    }
    //...
}

In the calculateRoute() function 2 Landmark instances are defined, one for the departure, and one for the destination coordinates of the route endpoints. A route must have at least 2 Landmark instances(waypoints), but optionally can have more, for any optional additional waypoints along the route.

The starting, or departure point of the route is the first waypoint in a list of 2 or more Landmarks (2 in this case), each containing a name, latitude (in degrees) and longitude (in degrees). The destination point is the last waypoint in the list.

In this example, the route departure point is London, and the destination is Paris, as specified by the Coordinates in the 2 Landmark instances. The list of waypoints is passed to the routingService to calculate the route.

MainActivity.kt

private fun calculateRoute() {
  val waypoints = arrayListOf(
    Landmark("London", Coordinates(51.5073204, -0.1276475)),
    Landmark("Paris", Coordinates(48.8566932, 2.3514616))
  )
  routingService.calculateRoute(waypoints)
}

When the map is ready, that is, instantiated and loaded, the calculateRoute() function shown above is called. When the route calculation completes, the routing service callback is triggered and the resulting route(s) are rendered on the map.

Selecting routes on the map

MainActivity.kt

class MainActivity : AppCompatActivity()
{
    //...
    override fun onCreate(savedInstanceState: Bundle?)
    {
        //...
        // Defines an action that should be done when the world map is ready (Updated/ loaded).
        SdkSettings.onMapDataReady = onMapDataReady@{ isReady ->
            if (!isReady) return@onMapDataReady
            //...
            gemSurfaceView.mapView?.onTouch = { xy ->
                // xy are the coordinates of the touch event
                SdkCall.execute {
                    // tell the map view where the touch event happened
                    gemSurfaceView.mapView?.cursorScreenPosition = xy

                    // get the visible routes at the touch event point 
                    val routes = gemSurfaceView.mapView?.cursorSelectionRoutes
                    // check if there is any route
                    if (!routes.isNullOrEmpty())
                    {
                        // set the touched route as the main route and center on it
                        val route = routes[0]
                        gemSurfaceView.mapView?.apply {
                            preferences?.routes?.mainRoute = route
                            centerOnRoutes(routesList)
                        }
                    }
                }
            }
        }
        //...
    }
    //...
}