TomTom LogoDocs
Products
Resources
Pricing
Sign in
Automotive Navigation Application
English
中文

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:

import android.util.Log
import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setZoomLevel.SetCameraZoomLevelCallback
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setZoomLevel.SetCameraZoomLevelParameters
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setZoomLevel.SetCameraZoomLevelResponse
import com.tomtom.automotive.integration.client.common.Callback


private val TAG = "MapDisplay"


fun applyZoomLevel(mapDisplayManager: MapDisplayManager, zoomLevel: Double) {
    mapDisplayManager.setCameraZoomLevel(
        SetCameraZoomLevelParameters(zoomLevel),
        object : SetCameraZoomLevelCallback {
            override fun onResponse(response: SetCameraZoomLevelResponse) {
                Log.d(TAG, "Zoom level set to: ${response.currentZoomLevel}")
            }


            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
                Log.e(TAG, "Set zoom level unavailable: ${reason.devMessage}")
            }
        }
    )
}

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:

import android.util.Log
import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelCallback
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelParameters
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelResponse
import com.tomtom.automotive.integration.client.common.Callback


private val TAG = "MapDisplay"


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


            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
                Log.e(TAG, "Zoom in unavailable: ${reason.devMessage}")
            }
        }
    )
}
import android.util.Log
import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelCallback
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelParameters
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.changeZoomLevel.ChangeCameraZoomLevelResponse
import com.tomtom.automotive.integration.client.common.Callback


private val TAG = "MapDisplay"


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


            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
                Log.e(TAG, "Zoom out unavailable: ${reason.devMessage}")
            }
        }
    )
}

Observing zoom level changes

Subscribe to receive updates when the zoom level changes:

import android.util.Log
import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.observeZoomLevel.CameraZoomLevelInfo
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.observeZoomLevel.ChangeCameraZoomLevelListener
import com.tomtom.automotive.integration.client.common.Callback
import com.tomtom.automotive.integration.client.common.SdkReleasable


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


fun observeCameraZoomLevel(mapDisplayManager: MapDisplayManager) {
    observeCameraZoomLevelReleasable = mapDisplayManager.observeCameraZoomLevel(
        object : ChangeCameraZoomLevelListener {
            override fun onCameraZoomLevelChanged(cameraZoomLevelInfo: CameraZoomLevelInfo) {
                val currentZoom = cameraZoomLevelInfo.currentZoomLevel
                Log.d(TAG, "Current zoom level: $currentZoom")
            }


            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
                Log.e(TAG, "Zoom level observation unavailable: ${reason.devMessage}")
            }
        }
    )
}


fun unObserveCameraZoomLevel() {
    observeCameraZoomLevelReleasable?.release()
    observeCameraZoomLevelReleasable = null
}

Setting camera mode

Switch between different camera following modes:

import android.util.Log
import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setCameraMode.SetCameraModeCallback
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setCameraMode.SetCameraModeFailure
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setCameraMode.SetCameraModeParameters
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.setCameraMode.SetCameraModeResponse
import com.tomtom.automotive.integration.client.api.model.camera.CameraMode
import com.tomtom.automotive.integration.client.common.Callback
import com.tomtom.automotive.integration.client.common.Result


private val TAG = "MapDisplay"


fun setCameraMode(mapDisplayManager: MapDisplayManager, cameraMode: CameraMode) {
    mapDisplayManager.setCameraMode(
        SetCameraModeParameters(cameraMode),
        object : SetCameraModeCallback {
            override fun onResult(result: Result<SetCameraModeResponse, SetCameraModeFailure>) {
                when (result) {
                    is Result.Success -> {
                        Log.d(TAG, "Camera mode set to: ${result.value.cameraMode}")
                    }
                    is Result.Failure -> {
                        Log.e(TAG, "Failed to set camera mode: ${result.failure}")
                    }
                }
            }


            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
                Log.e(TAG, "Set camera mode unavailable: ${reason.devMessage}")
            }
        }
    )
}

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:

import android.util.Log
import com.tomtom.automotive.integration.client.api.mapdisplay.MapDisplayManager
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.recenterCamera.RecenterCameraCallback
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.recenterCamera.RecenterCameraFailure
import com.tomtom.automotive.integration.client.api.mapdisplay.camera.recenterCamera.RecenterCameraResponse
import com.tomtom.automotive.integration.client.common.Callback
import com.tomtom.automotive.integration.client.common.Result


private val TAG = "MapDisplay"


fun recenterCamera(mapDisplayManager: MapDisplayManager) {
    mapDisplayManager.recenterCamera(
        object : RecenterCameraCallback {
            override fun onResult(result: Result<RecenterCameraResponse, RecenterCameraFailure>) {
                when (result) {
                    is Result.Success -> {
                        Log.d(TAG, "Camera recentered, was already centered: ${result.value.wasCameraCenteredPreviously}")
                    }
                    is Result.Failure -> {
                        Log.e(TAG, "Failed to recenter: ${result.failure}")
                    }
                }
            }


            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
                Log.e(TAG, "Recenter camera unavailable: ${reason.devMessage}")
            }
        }
    )
}