Developer

Camera and animations

VERSION 1.20.0

The camera position controls how the map is displayed. The camera position is a combination of its location, zoom, tilt, and rotation. To change the user’s view of the map, change the camera position. The map in the Map Display module is represented as a globe, so that the sizes and shapes of features are not distorted.

The default position of the camera is:

  • Located at 0 latitude and 0 longitude.
  • With a zoom of 0, which shows the whole globe.
  • Rotated to be north-up.
  • Tilted to point straight down.

Changing the camera position does not affect the map style, markers or any other map configuration.

Camera options

In the Map Display module, every change to the camera’s position has to be done using the CameraOptions class. It specifies the camera’s location, zoom, tilt, and rotation to set.

Location

The location is the geographical coordinate marking where the camera view should be pointed. The map view is always centered on it.

The position is specified with a GeoPoint object.

Zoom

The camera zoom can be set between 0 and 22. Approximate zoom scales:

  • 0 - The camera is fully zoomed out the whole globe is visible.
  • 5 - Country-level.
  • 10 - City-level.
  • 15 - Neighborhood-level.
  • 20 - Street-level.
  • 22 - Maximum zoom in.

Tilt

The tilt is the angle from the nadir (the camera pointing toward the center of the earth), where the tilt is set to zero 0. When the tilt is 90, the camera is pointing towards the horizon.

The closer the tilt level approaches 90, the more tiles may need to be downloaded. This can result in high data usage.

Rotation

Sets the cardinal direction that the camera is heading. By default, the rotation is set to 0, meaning that the orientation of the map is toward the north. The direction increases as the camera rotates clockwise. This means that east is 90 degrees, south is 180 degrees, and west is 270.

Current camera position

You can access the current camera position by reading TomTomMap.cameraPosition in the TomTomMap instance. The CameraPosition object that is returned contains a snapshot of the camera’s location, zoom, tilt, and rotation.

val cameraPosition = tomTomMap.cameraPosition

Moving the camera

The Map Display module provides two ways of changing the camera position: transitioning with a smooth animation or moving immediately to the new position.

To change the camera position immediately, call the moveCamera method on the TomTomMap object.

1val amsterdam = GeoPoint(52.379189, 4.899431)
2val cameraOptions =
3    CameraOptions(
4        position = amsterdam,
5        zoom = 10.0,
6        tilt = 45.0,
7        rotation = 90.0,
8    )
9tomTomMap.moveCamera(cameraOptions)

Animating the camera move

To animate a camera move, first define CameraOptions with the new camera position. Then use the animateCamera to set the duration of the animation. The animation time is set to 1.5 seconds by default.

Note that setting duration to null is equivalent to using the moveCamera method.

1val amsterdam = GeoPoint(52.379189, 4.899431)
2val newCameraOptions =
3    CameraOptions(
4        position = amsterdam,
5        zoom = 10.0,
6        tilt = 45.0,
7        rotation = 90.0,
8    )
9tomTomMap.animateCamera(newCameraOptions, 3.seconds)

The animation can also be monitored, so that you receive a notification when it completes or it is cancelled. You can cancel an animation by moving the camera before the animation is finished.

1val amsterdam = GeoPoint(52.379189, 4.899431)
2val newCameraOptions =
3    CameraOptions(
4        position = amsterdam,
5        zoom = 10.0,
6        tilt = 45.0,
7        rotation = 90.0,
8    )
9tomTomMap.animateCamera(
10    options = newCameraOptions,
11    animationDuration = 3.seconds,
12    actionCallback =
13        object : AnimateCameraCallback {
14            override fun onComplete() {
15                // YOUR CODE GOES HERE
16            }
17

18            override fun onCancelled() {
19                // YOUR CODE GOES HERE
20            }
21        },
22)

Tracking mode

The Map Display module allows you to set how the camera tracks the user locations to suit different interaction modes. Do this by setting CameraTrackingMode to the TomTomMap instance. There are five options for tracking mode:

  • None - The camera does not track the user’s location. This is the default setting and is mainly used to show the user’s location on the map.
  • FollowNorthUp - The camera follows the user’s location, but its tilt and zoom do not change.
  • FollowDirection - The camera follows the user’s location and heading to position the camera in the heading direction. Camera is always following from the top (the tilt is set to 0 degrees).
  • FollowRouteDirection - The camera follows the user’s location and heading to best present the route. Camera properties like tilt and zoom may be adjusted to better display the route and its guidance instructions.
  • FollowRouteNorthUp - The camera follows the user’s location; the camera is fixed to due north. Camera properties like tilt and zoom may be adjusted to better display the route and its guidance instructions.
  • RouteOverview - The camera tries to fit the routes in the current view, by changing the zoom level and other camera properties.

The last three modes are mainly used in navigation applications.

To apply a given tracking mode, set cameraTrackingMode:

tomTomMap.cameraTrackingMode = CameraTrackingMode.FollowRouteDirection

To check what tracking mode is currently set:

val cameraTrackingMode = tomTomMap.cameraTrackingMode

Camera listeners (Camera events)

The camera position can be modified by calling moveCamera and animateCamera. But users can also affect the camera when they use gestures to interact with the map. You can listen to camera changes by setting CameraChangeListener and CameraSteadyListener.

  • The CameraChangeListener reports on every change of a camera property. Be aware that doing too much inside this listener can slow down the application.
1tomTomMap.addCameraChangeListener(
2    object : CameraChangeListener {
3        override fun onCameraChange() {
4            // YOUR CODE GOES HERE
5        }
6    },
7)
  • The CameraSteadyListener reports when any camera property changes, but there are no more changes planned.
1tomTomMap.addCameraSteadyListener(
2    object : CameraSteadyListener {
3        override fun onCameraSteady() {
4            // YOUR CODE GOES HERE
5        }
6    },
7)

Both listeners can be removed when they are no longer needed. To remove them, call removeCameraChangeListener or removeCameraSteadyListener on the TomTomMap instance to which listeners were added. Specify which listener you want to remove by providing it as a parameter to the methods listed above.

Next steps

Since you have learned how to manipulate camera positions, here are the recommended next steps: