Camera
The Maps SDK's camera is the user's viewpoint above the map. The camera can be tilted, rotated, zoomed, and/or moved by on-screen gestures such as pinching or with written code. It's important to know that the camera object will not make any changes to markers, layers, sources, or other annotations that you've added without you directly influencing this behavior.
A few camera event listeners are provided in the Maps SDK to notify when, for example, the camera is adjusted. You can read more about these listeners inside the events page.
Camera position
The Maps SDK includes a CameraPosition
class which is comprised of the camera's target, angle, zoom, tilt, and padding. These camera options shape the user's perspective of the map tile(s).
Target
The target is a single latitude and longitude coordinate that the camera centers itself on. Changing the camera's target will move the camera to the inputted coordinates. The target is a LatLng
object. The target coordinate is always at the center of the viewport.
Dragging the map with a finger will pan the map and thus, the camera target.
Tilt
Tilt is the camera's angle from the nadir (directly facing the Earth) and uses unit degrees. The camera's minimum (default) tilt is 0 degrees, and the maximum tilt is 60. Tilt levels use six decimal point of precision, which enables you to restrict/set/lock a map's bearing with extreme precision.
The map camera tilt can also adjust by placing two fingertips on the map and moving both fingers up and down in parallel at the same time or
Bearing
Bearing is the direction that the camera is pointing in and measured in degrees clockwise from north.
The camera's default bearing is 0 degrees (as in "true north") causing the map compass to hide until the camera bearing becomes a non-zero value. The mapbox_uiCompass
boolean XML attribute allows change of the compass' visibility. Bearing levels use six decimal point precision, which enables you to restrict/set/lock a map's bearing with extreme precision. Besides programmatically adjusting the camera bearing, the user can place two fingertips on the map and rotate their fingers.
Zoom
Zoom controls the scale of the map and consumes any value between 0 and 22. At zoom level 0, the viewport shows continents and other world features. A middle value of 11 will show city level details, and at a higher zoom level, the map will begin to show buildings and points of interest. The camera can zoom in the following ways:
- Pinch motion two fingers to zoom in and out.
- Quickly tap twice on the map with a single finger to zoom in.
- Quickly tap twice on the map with a single finger and hold your finger down on the screen after the second tap. Then slide the finger up to zoom out and down to zoom out.
Read Designing maps for mobile devices, about the art/science of maps and visual information, to make sure your map style shows the right data at the correct camera positions.
Get the current camera position
The MapboxMap
class' getCameraPosition()
method helps your code understand what is going on with your map's camera and what the user's viewing. Retrieve the map's CameraPosition
via the MapboxMap
object once the map has been successfully initialized. Various camera values are in that CameraPosition
object.
CameraPosition currentCameraPosition = mapboxMap.getCameraPosition();
double currentZoom = currentCameraPosition.zoom;
double currentTilt = currentCameraPosition.tilt;
val currentCameraPosition = mapboxMap.cameraPosition
val currentZoom = currentCameraPosition.zoom
val currentTilt = currentCameraPosition.tilt