Developer

Map display control

Request Access

Map display control

The MapDisplayManager provides control over the map camera, including zoom levels, camera modes, and camera positioning. Use these features to provide a better navigation and browsing experience.

Overview

MapDisplayManager provides functionality for:

  • Setting absolute zoom levels
  • Changing zoom incrementally (zoom in/out)
  • Observing zoom level changes
  • Setting camera modes (2D, 3D, overview)
  • Recentering the camera to current position

Setting camera zoom level

Set an absolute zoom level directly:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
3import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setZoomLevel.SetCameraZoomLevelCallback
4import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setZoomLevel.SetCameraZoomLevelParameters
5import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setZoomLevel.SetCameraZoomLevelResponse
6import com.tomtom.automotive.integration.client.common.Callback
7

8private val TAG = "MapDisplay"
9

10fun applyZoomLevel(mapDisplayManager: MapDisplayManager, zoomLevel: Double) {
11    mapDisplayManager.setCameraZoomLevel(
12        SetCameraZoomLevelParameters(zoomLevel),
13        object : SetCameraZoomLevelCallback {
14            override fun onResponse(response: SetCameraZoomLevelResponse) {
15                Log.d(TAG, "Zoom level set to: ${response.currentZoomLevel}")
16            }
17

18            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
19                Log.e(TAG, "Set zoom level unavailable: ${reason.devMessage}")
20            }
21        }
22    )
23}

Zoom level ranges

Zoom levels typically range from:

  • Minimum: 1 (world view)
  • Maximum: 23 (street-level detail)
  • Recommended for navigation: 14-17
  • Recommended for POI search: 13-15

Changing zoom incrementally

Zoom in or out by a number of steps:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
3import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelCallback
4import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelParameters
5import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelResponse
6import com.tomtom.automotive.integration.client.common.Callback
7

8private val TAG = "MapDisplay"
9

10fun zoomInBy(mapDisplayManager: MapDisplayManager, steps: Double) {
11    mapDisplayManager.changeCameraZoomLevel(
12        ChangeCameraZoomLevelParameters.CameraZoomIn(steps),
13        object : ChangeCameraZoomLevelCallback {
14            override fun onResponse(response: ChangeCameraZoomLevelResponse) {
15                Log.d(TAG, "Zoomed in to level: ${response.currentZoomLevel}")
16            }
17

18            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
19                Log.e(TAG, "Zoom in unavailable: ${reason.devMessage}")
20            }
21        }
22    )
23}
1import android.util.Log
2import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
3import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelCallback
4import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelParameters
5import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelResponse
6import com.tomtom.automotive.integration.client.common.Callback
7

8private val TAG = "MapDisplay"
9

10fun zoomOutBy(mapDisplayManager: MapDisplayManager, steps: Double) {
11    mapDisplayManager.changeCameraZoomLevel(
12        ChangeCameraZoomLevelParameters.CameraZoomOut(steps),
13        object : ChangeCameraZoomLevelCallback {
14            override fun onResponse(response: ChangeCameraZoomLevelResponse) {
15                Log.d(TAG, "Zoomed out to level: ${response.currentZoomLevel}")
16            }
17

18            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
19                Log.e(TAG, "Zoom out unavailable: ${reason.devMessage}")
20            }
21        }
22    )
23}

Observing zoom level changes

Subscribe to receive updates when the zoom level changes:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
3import com.tomtom.automotive.integration.client.api.mapdisplay.camera.observeZoomLevel.CameraZoomLevelInfo
4import com.tomtom.automotive.integration.client.api.mapdisplay.camera.observeZoomLevel.ChangeCameraZoomLevelListener
5import com.tomtom.automotive.integration.client.common.Callback
6import com.tomtom.automotive.integration.client.common.SdkReleasable
7

8private val TAG = "MapDisplay"
9private var observeCameraZoomLevelReleasable: SdkReleasable? = null
10

11fun observeCameraZoomLevel(mapDisplayManager: MapDisplayManager) {
12    observeCameraZoomLevelReleasable = mapDisplayManager.observeCameraZoomLevel(
13        object : ChangeCameraZoomLevelListener {
14            override fun onCameraZoomLevelChanged(cameraZoomLevelInfo: CameraZoomLevelInfo) {
15                val currentZoom = cameraZoomLevelInfo.currentZoomLevel
16                Log.d(TAG, "Current zoom level: $currentZoom")
17            }
18

19            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
20                Log.e(TAG, "Zoom level observation unavailable: ${reason.devMessage}")
21            }
22        }
23    )
24}
25

26fun unObserveCameraZoomLevel() {
27    observeCameraZoomLevelReleasable?.release()
28    observeCameraZoomLevelReleasable = null
29}

Setting camera mode

Switch between different camera following modes:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
3import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setCameraMode.SetCameraModeCallback
4import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setCameraMode.SetCameraModeFailure
5import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setCameraMode.SetCameraModeParameters
6import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setCameraMode.SetCameraModeResponse
7import com.tomtom.automotive.integration.client.api.model.camera.CameraMode
8import com.tomtom.automotive.integration.client.common.Callback
9import com.tomtom.automotive.integration.client.common.Result
10

11private val TAG = "MapDisplay"
12

13fun setCameraMode(mapDisplayManager: MapDisplayManager, cameraMode: CameraMode) {
14    mapDisplayManager.setCameraMode(
15        SetCameraModeParameters(cameraMode),
16        object : SetCameraModeCallback {
17            override fun onResult(result: Result<SetCameraModeResponse, SetCameraModeFailure>) {
18                when (result) {
19                    is Result.Success -> {
20                        Log.d(TAG, "Camera mode set to: ${result.value.cameraMode}")
21                    }
22                    is Result.Failure -> {
23                        Log.e(TAG, "Failed to set camera mode: ${result.failure}")
24                    }
25                }
26            }
27

28            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
29                Log.e(TAG, "Set camera mode unavailable: ${reason.devMessage}")
30            }
31        }
32    )
33}

Available camera modes

  • CameraMode.FOLLOW_ROUTE_2D - Top-down camera focused on the chevron, oriented in the same direction
  • CameraMode.FOLLOW_ROUTE_3D - Tilted camera focused on the chevron, oriented in the same direction
  • CameraMode.NORTH_UP - Top-down camera focused on the chevron, oriented towards the North
  • CameraMode.ROUTE_OVERVIEW - Route overview camera that fits the entire route on the screen (requires active route)

Recentering camera

Recenter the map to the current vehicle position:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
3import com.tomtom.automotive.integration.client.api.mapdisplay.camera.recenterCamera.RecenterCameraCallback
4import com.tomtom.automotive.integration.client.api.mapdisplay.camera.recenterCamera.RecenterCameraFailure
5import com.tomtom.automotive.integration.client.api.mapdisplay.camera.recenterCamera.RecenterCameraResponse
6import com.tomtom.automotive.integration.client.common.Callback
7import com.tomtom.automotive.integration.client.common.Result
8

9private val TAG = "MapDisplay"
10

11fun recenterCamera(mapDisplayManager: MapDisplayManager) {
12    mapDisplayManager.recenterCamera(
13        object : RecenterCameraCallback {
14            override fun onResult(result: Result<RecenterCameraResponse, RecenterCameraFailure>) {
15                when (result) {
16                    is Result.Success -> {
17                        Log.d(TAG, "Camera recentered, was already centered: ${result.value.wasCameraCenteredPreviously}")
18                    }
19                    is Result.Failure -> {
20                        Log.e(TAG, "Failed to recenter: ${result.failure}")
21                    }
22                }
23            }
24

25            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
26                Log.e(TAG, "Recenter camera unavailable: ${reason.devMessage}")
27            }
28        }
29    )
30}