Truck Profile

In this guide you will learn how to compute a route based on the accessibility given by the physical characteristics of a truck, such as height, weight, length, width and number of axles, and then render the route on the map.

Setup

First, get an API key token, see the Getting Started guide.

Download the Maps & Navigation SDK for Android archive file

Download the TruckProfile project archive file or clone the project with Git

See the Configure Android Example guide.

Run the example

In Android Studio, from the File menu, select Sync Project with Gradle Files

An android device should be connected via USB cable.

Press SHIFT+F10 to compile, install and run the example on the android device.

How it works

You can open the MainActivity.kt file to see how the truck route is computed and rendered on the map based on the accessibility given by the physical characteristics of the truck.

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

A routing service is instantiated to compute and render the truck route.

The onStarted and onCompleted routing callbacks are overridden and implemented, to show, and then hide, respectively, the routing computation progress bar, which is useful for very slow devices, where the route computation may take long enough to be noticeable by the user.

When the route calculation is completed, if there is no error, the resulting routes (as there could be more than one alternate route in the resulting set between the specified departure and destination points) are drawn on the map:

gemSurfaceView.mapView?.presentRoutes()

Then the settings button is set to visible, so that the user can introduce the physical characteristics of the truck. Upon saving these, the route is computed again, in case it has to change to accomodate the updated characteristics of the truck, such as its dimensions and weight.

override fun onCreate(savedInstanceState: Bundle?)
{
     super.onCreate(savedInstanceState)
     setContentView(R.layout.activity_main)
     gemSurfaceView = findViewById(R.id.gem_surface_view)
     progressBar = findViewById(R.id.progress_bar)
     settingsButtons = findViewById<FloatingActionButton?>(R.id.settings_button).also {
         it.setOnClickListener {
             onSettingsButtonClicked()
         }
     }
     SdkSettings.onMapDataReady = onMapDataReady@{ isReady ->
         if (!isReady) return@onMapDataReady
         // Defines an action that should be done when the world map is ready (Updated/ loaded).
         SdkCall.execute {
             waypoints = arrayListOf(
                 Landmark("London", 51.5073204, -0.1276475),
                 Landmark("Paris", 48.8566932, 2.3514616)
             )
             routingService.calculateRoute(waypoints)
         }
         gemSurfaceView.mapView?.onTouch = { xy ->
             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)
                     }
                 }
             }
         }
     }
     SdkSettings.onApiTokenRejected = {
         showDialog("TOKEN REJECTED")
     }
     if (!Util.isInternetConnected(this))
     {
         showDialog("You must be connected to the internet!")
     }
}

The onCreate() function is overridden in the MainActivity: AppCompatActivity() class, and checks if internet access is available, showing a dialog message if not.

findViewById() is used to obtain pointers to the various graphical user interface elements where text or graphical data is to be displayed.

A click listener is set for the settings button, to recompute the route when the user changes the physical parameters of the truck.

it.setOnClickListener { onSettingsButtonClicked() }

When the map is loaded and ready,

onMapDataReady@{}

the routing service instantiated and shown above is used to calculate the route between a list of 2 predefined waypoints where the first is the departure point and the second is the destination point:

routingService.calculateRoute(waypoints)

Each waypoint is a Landmark containing a name, a latitude, in degrees, and a longitude, in degrees:

Landmark("Paris", 48.8566932, 2.3514616)

The list of waypoints from which a route is calculated must have at least 2 elements, for the departure and destination, respectively, but can have more elements, for additional waypoints along the route. In this example there are 2 waypoints in the list.

A touch listener is defined

gemSurfaceView.mapView?.onTouch = { xy ->

and gemSurfaceView.mapView?.cursorSelectionRoutes is used to see if the user touched one or more routes on the map. If so, the first touched route (at index 0) is selected and set as the main route, which causes it to be drawn in dark blue on the map.

Then the camera centers on the bounding box containing all routes between the departure and destination points.

centerOnRoutes(routesList)

private val adapter = TruckProfileSettingsAdapter(getInitialDataSet())

A variable in the class MainActivity : AppCompatActivity() is created to hold the truck dimensions and other attributes.

private fun getInitialDataSet(): List<TruckProfileSettingsModel>

The getInitialDataSet() function sets the default initial values in the form with the truck dimensions and other attributes required for identifying a corresponding route between the given departure and destination which is navigable by the specified truck.

private fun onSettingsButtonClicked()
{
     val builder = AlertDialog.Builder(this)
     val convertView = layoutInflater.inflate(R.layout.truck_profile_settings_view, null)
     val listView = convertView.findViewById<RecyclerView>(R.id.truck_profile_settings_list).apply
     {
         layoutManager = LinearLayoutManager(this@MainActivity)
         addItemDecoration(DividerItemDecoration(applicationContext,
         (layoutManager as LinearLayoutManager).orientation))
     }
     listView.adapter = adapter
     builder.setTitle(getString(R.string.app_name))
     builder.setView(convertView)
     builder.setNeutralButton(getString(R.string.save)) { dialog, _ ->
         onSaveButtonClicked()
         dialog.dismiss()
     }
     val dialog = builder.create()
     dialog.show()
}

The onSettingsButtonClicked() function is called by the listener defined in the onCreate() function above, when the user clicks the industrial wheel settings button to modify the truck profile attributes.

This function uses the adapter variable defined above to display the truck attribute values and enable the user to modify them, so they can then be used to find a route appropriate for the truck.

A save button is defined, which closes the dialog and calls the onSaveButtonClicked() function to calculate the route using the updated truck parameter values.

private fun onSaveButtonClicked()
{
     val dataSet = adapter.dataSet
     // convert m to cm
     val width = (dataSet[ETruckProfileSettings.Width.ordinal].currentDoubleValue * 100).toInt()
     val height = (dataSet[ETruckProfileSettings.Height.ordinal].currentDoubleValue * 100).toInt()
     val length = (dataSet[ETruckProfileSettings.Length.ordinal].currentDoubleValue * 100).toInt()
     // convert t to kg
     val weight = (dataSet[ETruckProfileSettings.Weight.ordinal].currentDoubleValue * 1000).toInt()
     val axleWeight = (dataSet[ETruckProfileSettings.AxleWeight.ordinal].currentDoubleValue * 1000).toInt()
     // convert km/h to m/s
     val maxSpeed = dataSet[ETruckProfileSettings.MaxSpeed.ordinal].currentIntValue * 0.27778
     SdkCall.execute {
         routingService.apply {
             preferences.alternativesSchema = ERouteAlternativesSchema.Never
             preferences.transportMode = ERouteTransportMode.Lorry
             preferences.truckProfile = TruckProfile(
                 massKg = weight,
                 heightCm = height,
                 lengthCm = length,
                 widthCm = width,
                 axleLoadKg = axleWeight,
                 maxSpeedMs = maxSpeed
             )
             calculateRoute(waypoints)
         }
     }
}

The onSaveButtonClicked() function sets the truck profile attributes in the preferences and then calculates the route using

calculateRoute(waypoints)

Android Examples

Maps SDK for Android Examples can be downloaded or cloned with Git