Camera and animations
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 SDK 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 1, 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 SDK, 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 CLLocationCoordinate2D
object.
Zoom
The camera zoom can be set between 0 and 22. Approximate zoom scales:
- 1 - 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 calling the TomTomMap.cameraOptions
parameter on the TomTomMap
instance. The CameraOptions
object that is returned contains a snapshot of the camera’s location, zoom, tilt, and rotation.
let cameraOptions = tomTomMap.cameraOptions
Moving the camera
The Map Display SDK provides two ways of changing the camera position: transitioning with a smooth animation, or moving immediately to the new position.
To immediately change the camera position, call the moveCamera
method on the TomTomMap
object.
1let amsterdam = CLLocationCoordinate2D(latitude: 52.379189, longitude: 4.899431)2let cameraOptions = CameraOptions(3 position: amsterdam,4 zoom: 10.0,5 tilt: 45.0,6 rotation: 90.07)8tomTomMap.moveCamera(cameraOptions)
Animating the camera move
To animate a camera move, first define CameraOptions
with the new camera position. Then use the TimeInterval
class to set the duration of the animation. The animation time is set to 1.5 seconds by default.
1let amsterdam = CLLocationCoordinate2D(latitude: 52.379189, longitude: 4.899431)2let cameraOptions = CameraOptions(3 position: amsterdam,4 zoom: 10.0,5 tilt: 45.0,6 rotation: 90.07)8tomTomMap.animateCamera(cameraOptions)
The animation can also be monitored so that you receive a completion block when it completes. You can cancel an animation by moving the camera before the animation is finished.
1let amsterdam = CLLocationCoordinate2D(latitude: 52.379189, longitude: 4.899431)2let cameraOptions = CameraOptions(3 position: amsterdam,4 zoom: 10.0,5 tilt: 45.0,6 rotation: 90.07)8tomTomMap.animateCamera(cameraOptions, animationDuration: 0.4) { success in9 if success {10 /* YOUR CODE GOES HERE */11 }12}
Tracking mode
The Map Display SDK allows you to set how the camera tracks the user’s locations to suit different interaction modes. Do this by setting CameraTrackingMode
to the TomTomMap
instance. There are three 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.FOLLOW
- The camera follows the user’s location, but its tilt and zoom do not change.FOLLOW_WITH_HEADING
- The camera follows the user’s location. As the user moves, the camera properties change to show where the user is heading.
The last two modes are mainly used in navigation applications.
To apply a given tracking mode, set the cameraTrackingMode
parameter:
tomTomMap.cameraTrackingMode = .followWithHeading
To check what tracking mode is currently set:
let cameraTrackingMode = tomTomMap.cameraTrackingMode
Listening on 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 TomTomMapDelegate
methods.
In the first step you have to set the delegate:
tomTomMap.delegate = self
- The
didChangeCameraProperties
reports on every change of a camera property. Be aware that doing too much inside this listener can slow down the application.func tomTomMap(_: TomTomMap, didChangeCameraProperties _: CameraProperties) {} - The
didSteadyCamera
reports when any camera property changes, but there are no more changes planned.func tomTomMap(_: TomTomMap, didSteadyCamera _: CameraProperties) {}