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
Update the camera position
The MapboxMap class in the Maps SDK has several methods to change the camera's position. Each camera movement API takes in a CameraUpdate object. You should use the CameraUpdateFactory class to provide the new camera position information. CameraUpdateFactory can build several different CameraUpdate objects including a newLatLngZoom(), zoomBy(), newLatLngBounds(), and several more. A method in CameraUpdate is newCameraPosition() which is how you'd pass in a built CameraPosition.
Change the camera target, bearing, zoom, and tilt by animating the camera.
A CameraPosition object can change a single property of the camera object such as the zoom or it can change multiple properties at the same time. For example, you could have the camera change its target, zoom out, and tilt all at the same time:
CameraPosition position = new CameraPosition.Builder()
.target(new LatLng(51.50550, -0.07520))
.zoom(10)
.tilt(20)
.build();
val position = CameraPosition.Builder()
.target(LatLng(51.50550, -0.07520))
.zoom(10.0)
.tilt(20.0)
.build()
Read all about MapView XML attributes to learn about setting the camera's initial position with XML rather with Java or Kotlin. You should either set the initial camera position in XML or through MapboxMapOptions to prevent unnecessary downloading of map tiles using up your user's data.
mapboxMap.animateCamera(CameraUpdateFactory.newCameraPosition(position), millisecondSpeed);
mapboxMap.animateCamera(CameraUpdateFactory.newCameraPosition(position), millisecondSpeed)
Aside from consuming a CameraUpdate object, a callback can be added to know when the animation finishes or if the user cancels the camera move by performing a gesture on the map. The easeCamera() or animateCamera() methods have an optional duration parameter (in milliseconds), which lets you control how quickly the camera travels to the new map location.
| Method | Description |
|---|---|
moveCamera() | Instantaneously re-position the camera according to the instructions defined in CameraUpdate object parameter. moveCamera() quickly moves the camera, which can be visually jarring for a user. Strongly consider using either the easeCamera() or animateCamera() methods instead because they're less abrupt. |
easeCamera() | Gradually move the camera according to the instructions defined in CameraUpdate object parameter. The camera eases with a default duration. A second parameter can be passed to declare a custom duration in milliseconds. The camera's zoom level will not be affected unless specified in the CameraUpdate object. If you're using this method to have the map camera track the user as the device location changes, use the LocationComponent's CameraMode.TRACKING mode instead of easing the camera yourself. Another one of easeCamera()'s optional parameters is a boolean to set whether the animation interpolator is used. Disabling the interpolator results in a linear animation to the new position. This Java SDK Isochrone API example uses the animation interpolation. |
animateCamera() | Animate the camera to a new location defined within a CameraUpdate object. The pre-defined camera animation evokes powered flight. This example uses this method. |
Center the camera within a map area
The camera can also centered within a map area like how the camera can be restricted to a region (see below). First you'll need a defined LatLngBounds object that includes at least two coordinates. You'll then be able to update the camera position using the available newLatLngBounds() method, which takes your bounding box and adjusts the viewport so that the specified region will be within view. Besides the bounding box being passed into the camera update factory, you will also need to provide an int value defining the padding between the edge of the screen and the actual bounded region. You also have the option to provide different padding values for each side of the box.
Adjust the camera position to fit a bounding box within the viewport.
LatLngBounds latLngBounds = new LatLngBounds.Builder()
.include(first marker position)
.include(second marker position)
.build();
mapboxMap.animateCamera(CameraUpdateFactory.newLatLngBounds(latLngBounds, 10));
val latLngBounds = LatLngBounds.Builder()
.include(first marker position)
.include(second marker position)
.build()
mapboxMap.animateCamera(CameraUpdateFactory.newLatLngBounds(latLngBounds, 10));
Restricting the user's panning to a given area
The setLatLngBoundsForCameraTarget method in the MapboxMap class can limit the map camera to any area of the world that you'd like. If you feed the LatLngBounds object a minimum of two LatLng objects/coordinates, an invisible rectangle will automatically be created to restrict the camera to the region.
Limit the map movement to within a region using a bounding box.
Camera and device location
Read about the LocationComponent's camera options if you'd like to learn more about the relationship between controlling the camera and the device location UI experience. The Maps SDK provides convenient methods for making the camera follow the device location puck, adjusting based on the device rotation, and much more.