Navigation

Turn-by-turn navigation

You can add a turn-by-turn navigation to your app using the ready-to-use interface components and the NavigationManager class.

To do that, first add a NavigationView and a DefaultNavigationControls to your MapView.

<ru.dgis.sdk.map.MapView
    android:id="@+id/mapView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    >
    <ru.dgis.sdk.navigation.NavigationView
        android:id="@+id/navigationView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        >
        <ru.dgis.sdk.navigation.DefaultNavigationControls
            android:layout_width="match_parent"
            android:layout_height="match_parent"/>
    </ru.dgis.sdk.navigation.NavigationView>
</ru.dgis.sdk.map.MapView>

Then, add a My location marker to the map and create a NavigationManager object.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    sdkContext = DGis.initialize(applicationContext, apiKeys)

    // Register the geolocation source
    locationProvider = ManagerLocationSource(applicationContext)
    registerPlatformLocationSource(sdkContext, locationProvider)

    setContentView(R.layout.activity_navigation)

    findViewById<MapView>(R.id.mapView).apply { mapView ->
        lifecycle.addObserver(mapView)

        mapView.getMapAsync { map ->
            // Add a marker for the current location
            map.addSource(
                MyLocationMapObjectSource(
                    sdkContext,
                    MyLocationDirectionBehaviour.FOLLOW_SATELLITE_HEADING,
                    createSmoothMyLocationController()
                )
            )
        }
    }

    // Create a NavigationManager object
    navigationManager = NavigationManager(sdkContext)

    findViewById<NavigationView>(R.id.navigationView).apply {
        // Attach the created NavigationManager object to the NavigationView
        navigationManager = this@NavigationActivity.navigationManager
    }

    // Start navigation in a free-drive mode
    navigationManager.start()
}

You can start navigation in one of three modes: free-drive, turn-by-turn, and the simulated navigation mode.

Additional navigation settings can be changed using the properties of the NavigationManager object.

Free-drive mode

In free-drive mode, no route will be displayed on the map, but the user will still be informed about speed limits, traffic cameras, incidents, and road closures.

To start navigation in this mode, call the start() method without arguments.

navigationManager.start()

Turn-by-turn mode

In turn-by-turn mode, a route will be displayed on the map and the user will receive navigation instructions as they move along the route.

To start navigation in this mode, call the start() method and specify a RouteBuildOptions object - arrival coordinates and route settings.

val routeBuildOptions = RouteBuildOptions(
    finishPoint = RouteSearchPoint(
        coordinates = GeoPoint(latitude = 55.752425, longitude = 37.613983)
    ),
    routeSearchOptions = CarRouteSearchOptions(
        avoidTollRoads = true,
        avoidUnpavedRoads = false,
        avoidFerry = false,
        routeSearchType = RouteSearchType.JAM
    )
)

navigationManager.start(routeBuildOptions)

Additionally, when calling the start() method, you can specify a TrafficRoute object - a complete route object for navigation (see Building a route). In this case, NavigationManager will use the specified route instead of building a new one.

navigationManager.start(routeBuildOptions, trafficRoute)

Simulated navigation

In this mode, NavigationManager will not track the current location of the device. Instead, it will simulate a movement along the specified route.

This mode is useful for debugging.

To use this mode, call the startSimulation() method and specify a RouteBuildOptions object (route settings) and a TrafficRoute object (the route itself).

You can change the speed of the simulated movement using the SimulationSettings.speed property (specified in meters per second).

navigationManager.simulationSettings.speed = 30 / 3.6
navigationManager.startSimulation(routeBuildOptions, trafficRoute)

To stop the simulation, call the stop() method.

navigationManager.stop()

Traffic display

To display traffic on the map, add a TrafficSource data source.

val trafficSource = TrafficSource(sdkContext)
map.addSource(trafficSource)

Custom geolocation source

You can use your own geolocation source within the SDK. To do this, first implement the LocationSource interface.

public class CustomLocationSource: LocationSource {
    override fun activate(listener: LocationChangeListener?) {
        // Geolocation source has been activated
    }

    override fun deactivate() {
        // Geolocation source has been deactivated
    }

    override fun setDesiredAccuracy(accuracy: DesiredAccuracy?) {
        // Change of required accuracy level has been requested
    }
}

Then, register the created source in the SDK using the registerPlatformLocationSource() function.

val customSource = CustomLocationSource()
registerPlatformLocationSource(sdkContext, customSource)

The entry point of the interface is the activate() function. When the SDK requires a geolocation, it will call this function passing a LocationChangeListener object. After that, to report the current geolocation, you need to pass an array of Location objects (ordered from oldest to newest) to the onLocationChanged() method.

val location = Location(...)
val newLocations = arrayOf(location)
listener.onLocationChanged(newLocations)

To notify of a change in source availability, use the onAvailabilityChanged() method.

Optionally, you can add additional logic to handle different levels of geolocation accuracy. The required accuracy is passed to the setDesiredAccuracy() function as a DesiredAccuracy object.

When the geolocation source is no longer needed, the SDK will call the deactivate() function.

Indoor navigation

  

The SDK provides the ability to build routes within certain buildings for which there are floor plans. For example, you can build a route to a specific store in a mall, make a complex route between several points, etc.

This type of navigation is included in the Full SDK, but has a number of limitations:

• Can only be activated in pedestrian navigation mode
• Due to the way modern positioning systems work, the ability to determine the position inside buildings is severely limited. When the system determines that the device has entered the limits of the building, the geopositioning tracking and its display will be disabled, leaving the constructed route and recommendations for the passage. We are working to overcome these challenges and hope to provide a reliable way to determine the location inside buildings in the future.

Creating a route

Creating a route follows the principles described in Turn-by-turn mode with a few important additions. Let's take an example:

// RouteBuildOptions object is also required
val routeBuildOptions = RouteBuildOptions(
    finishPoint = RouteSearchPoint(
        coordinates = GeoPoint(latitude = 55.752425, longitude = 37.613983),
        objectId = ..., // You can get it from DgisMapObject
        levelId = ..., // You can get it from DirectoryObject or RenderedObjectInfo
    ),
    // routeSearchOptions must be of type PedestrianRouteSearchOptions
    routeSearchOptions = PedestrianRouteSearchOptions()
)

As you can see, the objectId and levelId parameters are mandatory when creating a route endpoint RouteSearchPoint

Displaying

If you use the standard set of NavigationView and DefaultNavigationControls, as recommended in beginning of section, this feature is already available and does not require preconfiguration.

When using your own controllers in the UI, you can use the standard SDK features to detect when entering the indoor navigation mode, namely subscribing to indoorChannel. This channel can be obtained from [NavigationManager](/en/android/sdk/reference/7.0/ru.dgis.sdk.navigation.NavigationManager#nav-lvl1--val indoorDetector)