Skip to content

Simulate Route

In this guide you will learn how to compute a route between a departure point and a destination point, render the route on an interactive map, and then simulate navigation along the route.

simulate_route - example flutter screenshot

Setup

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

Prerequisites

It is required that you complete the Environment Setup - Flutter Examples guide before starting this guide.

Build and run

Start a terminal/command prompt and go to the simulate_route directory, within the flutter examples directory - that is the name of this example project.

Note - the gem_kit directory containing the Maps SDK for Flutter should be in the plugins directory of the example, e.g. example_pathname/plugins/gem_kit - see the environment setup guide above. Replace example_pathname with the actual example path name, such as address_search

Download project dependencies:

example flutter upgrade screenshot

flutter upgrade

example flutter clean screenshot

run the following terminal commands in the project directory, where the pubspec.yaml file is located:

flutter clean

example flutter pub get screenshot

flutter pub get

Run the example:

flutter run

select chrome - example flutter screenshot

If such a question appears, select the chrome browser; in the above example, press 2.

First, verify that the ANDROID_SDK_ROOT environment variable is set to the root path of your android SDK.

In android/build.gradle add the maven {} block as shown, within the allprojects {} block, for both debug and release builds, without the line numbers, those are for reference:

1allprojects {
2    repositories {
3        google()
4        mavenCentral()
5        maven {
6           url "${rootDir}/../plugins/gem_kit/android/build"
7        }
8    }
9}

in android/app/build.gradle within the android {} block, in the defaultConfig {} block, the android SDK version minSdk must be set as shown below.

Additionally, for release builds, in android/app/build.gradle, within the android {} block, add the buildTypes {} block as shown:

Replace example_pathname with the actual example pathname, such as center_coordinates

 1android {
 2    defaultConfig {
 3        applicationId "com.magiclane.gem_kit.examples.example_pathname"
 4        minSdk 21
 5        targetSdk flutter.targetSdk
 6        versionCode flutterVersionCode.toInteger()
 7        versionName flutterVersionName
 8    }
 9    buildTypes {
10        release {
11            // TODO: Add your own signing config for the release build.
12            // Signing with the debug keys for now, so `flutter run --release` works.
13            minifyEnabled false
14            shrinkResources false
15            signingConfig signingConfigs.debug
16        }
17    }
18}

Then build the apk:

flutter build apk --debug
or
flutter build apk --release
the apk file is located in the build/app/outputs/apk/debug or build/app/outputs/apk/release subdirectory, for debug or release build respectively, within the current project directory, such as center_coordinates
The apk file name is app-release.apk or app-debug.apk
You can copy the apk to an android device using adb, for example:
adb push app-release.apk sdcard

And then click on the apk in the file browser on the device to install and run it.

In the ios/Podfile configuration text file, at the top, set the minimum ios platform to 13 like this:

platform :ios, '13.0'

Run pod install in the [ios folder] ./ios/
Then go back to the repository root folder and type flutter build ios to build a Runner.app.
Type flutter run to build and run on an attached device.
You can open the <path/to>/ios/Runner.xcworkspace project in Xcode and execute and debug from there.

How it works

In the example project directory, such as center_coordinates, there is a text file named pubspec.yaml which contains project configuration and dependencies. The most important lines from this file are shown here:

 1name: center_coordinates
 2description: A Flutter example using Maps SDK for Flutter.
 3
 4version: 1.0.0+1
 5
 6environment:
 7  sdk: '>=3.0.5 <4.0.0'
 8
 9dependencies:
10  flutter:
11    sdk: flutter
12  gem_kit:
13    path: plugins/gem_kit
14
15  cupertino_icons: ^1.0.2
16
17  intl: ^0.19.0
18
19  dev_dependencies:
20    flutter_test:
21      sdk: flutter
22
23    flutter_lints: ^3.0.2
24
25# The following section is specific to Flutter packages.
26flutter:
27  uses-material-design: true

The project must have a name and version. The dependencies list the Flutter SDK, and the gem_kit, Maps for Flutter SDK.

The source code is in example_pathname/lib/main.dart Replace example_pathname with the actual example path name, such as center_coordinates

 1import 'package:gem_kit/core.dart';
 2import 'package:gem_kit/map.dart';
 3import 'package:gem_kit/navigation.dart';
 4import 'package:gem_kit/routing.dart';
 5
 6import 'bottom_navigation_panel.dart';
 7import 'top_navigation_panel.dart';
 8import 'utility.dart';
 9
10import 'package:flutter/material.dart' hide Route, Animation;

The dart material package is imported, as well as the required gem_kit packages.

1void _onMapCreated(GemMapController controller) {
2  // Save controller for further usage.
3  _mapController = controller;
4}

This callback function is called when the interactive map is initialized and ready to use.

simulate_route - example flutter screenshot

 
 1void _onBuildRouteButtonPressed(BuildContext context) {
 2  // Define the departure.
 3  final departureLandmark = Landmark.withLatLng(latitude: 45.6517672, longitude: 25.6271132);
 4
 5  // Define the destination.
 6  final destinationLandmark = Landmark.withLatLng(latitude: 44.4379187, longitude: 26.0122374);
 7
 8  // Define the route preferences.
 9  final routePreferences = RoutePreferences();
10  _showSnackBar(context, message: 'The route is calculating.');
11
12  // Calling the calculateRoute SDK method.
13  // (err, results) - is a callback function that gets called when the route computing is finished.
14  // err is an error enum, results is a list of routes.
15  _routingHandler =
16      RoutingService.calculateRoute([departureLandmark, destinationLandmark], routePreferences, (err, routes) async {
17    // If the route calculation is finished, we don't have a progress listener anymore.
18    _routingHandler = null;
19
20    ScaffoldMessenger.of(context).clearSnackBars();
21
22    // If there aren't any errors, we display the routes.
23    if (err == GemError.success) {
24      // Get the routes collection from map preferences.
25      final routesMap = _mapController.preferences.routes;
26
27      // Display the routes on map.
28      for (final route in routes!) {
29        routesMap.add(route, route == routes.first, label: route.getMapLabel());
30      }
31
32      // Center the camera on routes.
33      _mapController.centerOnRoutes(routes);
34    }
35    setState(() {
36      _areRoutesBuilt = true;
37    });
38  });
39}

When the route button in the upper right corner is pressed, a route is computed from the preset departure position to the preset destination position.

A route must have at least 2 waypoints, one for the departure, and one for the destination. Optionally, 0 or more intermediate waypoints may be specified, through which the route will pass, in order from departure to destination.

Each waypoint is a Landmark and has latitude and longitude coordinates.
Then the route is calculated:
RoutingService.calculateRoute()
If there are no errors, the list of resulting routes (as there may be a few alternatives), is added to the map:
routesMap.add()
the first resulting route is autoselected as the main route, and then the map is centered on the resulting routes, such that they fit in the viewport:
_mapController.centerOnRoutes(routes);

simulate_route - example flutter screenshot

 
 1void _startSimulation() {
 2  final routes = _mapController.preferences.routes;
 3
 4  _navigationHandler = NavigationService.startSimulation(routes.mainRoute, (type, instruction) async {
 5    if (type == NavigationEventType.destinationReached || type == NavigationEventType.error) {
 6      // If the navigation has ended or if and error occured while navigating, remove routes.
 7      setState(() {
 8        _isSimulationActive = false;
 9        _cancelRoute();
10      });
11      return;
12    }
13    _isSimulationActive = true;
14
15    if (instruction != null) {
16      setState(() => currentInstruction = instruction);
17    }
18  });
19
20  // Set the camera to follow position.
21  _mapController.startFollowingPosition();
22}
Once a route is computed, tapping the play button in the upper right starts simulated navigation on the selected route.
Follow position means the camera tracks the position of the phone/device, indicated by an arrow moving along the route on the map.
_mapController.startFollowingPosition();

Flutter Examples

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