Camera position
The Mapbox Maps SDK for iOS gives you complete control over the position of the map camera. The camera’s location and behavior is defined by its properties:
center
: The longitude and latitude at which the camera is pointed.bearing
: The visual rotation of the map. The bearing value is the compass direction the camera points to show the user which way is "up". For example, a bearing of 90° orients the map so that east is up.pitch
: The visual tilt of the map. A pitch of 0° is perpendicular to the surface, looking straight down at the map, while a greater value like 60° looks ahead towards the horizon.zoom
: The zoom level specifies how close the camera is to the features being viewed. At zoom level 0, the viewport shows continents and oceans. A middle value of 11 shows city-level details, and at a higher zoom level the map begins to show buildings and points of interest.padding
: Insets from each edge of the map. Impacts the location at which thecenter
point is rendered.anchor
: The point in the map’s coordinate system about whichzoom
andbearing
should be applied. Mutually exclusive withcenter
.
Set camera position
The Maps SDK allows you to set the camera's position on map initialization, or after the map has already been initialized. You can also set the camera's position based on the user's location or fit the camera to a specific shape.
Set camera on map initialization
You can specify the camera position when you initialize the map by defining CameraOptions
, passing those options to MapInitOptions
, and using those options when initializing the MapView
. This approach is best if you know what part of the world you want to show a user first. Since the SDK will load the tiles around the specified location first, the map may appear to load faster.
CameraOptions
parameters are optional. For any parameters that aren’t specified, the SDK will use the default value.
// Define center coord, zoom, pitch, bearing
let cameraOptions = CameraOptions(center: CLLocationCoordinate2D(latitude: 40.7135, longitude: -74.0066),
zoom: 15.5,
bearing: -17.6,
pitch: 45)
// Pass camera options to map init options
let options = MapInitOptions(cameraOptions: cameraOptions)
// Pass options when initializing the map
mapView = MapView(frame: view.bounds, mapInitOptions: options)
If you don’t specify the camera position when the style is loaded, default values will be used. If the style being loaded has center
, bearing
, pitch
, and zoom
properties defined, the position will be determined by those values. If these properties are not defined in the style JSON, the map will be centered on the coordinates 0,0
with a bearing
and pitch
of 0
at zoom
level 0
.
Set after map initialization
In some cases you may want to set the camera's position after the map has been initialized based on an event or user interaction. For example, you may want to center the map camera on an annotation when a user taps on it.
// Initialize map
let mapView = MapView(frame: view.bounds)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
view.addSubview(mapView)
// Add a tap gesture recognizer
let tapGestureRecognizer = UITapGestureRecognizer(target: mapView,
action: #selector(handleTapGestureRecognizer))
mapView.addGestureRecognizer(tapGestureRecognizer)
...
// Set the camera's position
@objc func handleTapGestureRecognizer() {
mapView.mapboxMap.setCamera(to: CameraOptions(center: self.newYork))
}
Set camera based on device location
You can set the camera based on the location of the device. Users must grant permission before an app can access information about their location. For more information about asking for the user’s location, see the User location guide.
After the user has granted this permission, you can pass their location to the app using addLocationConsumer
and center the camera on it.
if let locationCoordinate = self.mapView?.location.latestLocation?.coordinate {
mapView.mapboxMap.setCamera(to: CameraOptions(center: locationCoordinate, zoom: 15))
}
You can also set the camera position to update as the user’s location changes. For example, the map can stay centered on a user’s location as they walk down the street.
// Create class which conforms to LocationConsumer, update the camera's centerCoordinate when a locationUpdate is received
public class CameraLocationConsumer: LocationConsumer {
weak var mapView: MapView?
init(mapView: MapView) {
self.mapView = mapView
}
public func locationUpdate(newLocation: Location) {
mapView.mapboxMap.setCamera(to: CameraOptions(center: newLocation.coordinate, zoom: 15))
}
}
Use addLocationConsumer
to update the camera based on a user's location.
Fit the camera to a given shape
You can position the camera to fit a specified shape within the viewport.
- To create a camera for a given geometry, call
camera(for:padding:bearing:pitch:)
functions onMapboxMap
. - To fit the camera to a set of rectangular coordinate bounds (in other words, a bounding box), call
CameraBoundsOptions
.
This example fits the camera to a bounding box:
// Define bounding box
let bounds = CoordinateBounds(southwest: CLLocationCoordinate2D(latitude: 63.33, longitude: -25.52),
northeast: CLLocationCoordinate2D(latitude: 66.61, longitude: -13.47))
// Center the camera on the bounds
let camera = mapView.mapboxMap.camera(for: bounds, padding: .zero, bearing: 0, pitch: 0)
Use CameraBoundsOptions
to set the camera view to fit a specified triangular region.
Listen for camera changes
The Maps SDK provides several ways to detect whether camera change events have happened.
Use CameraChanged
to listen for camera updates:
// Accuracy ring is only shown when zoom is greater than or equal to 18
mapView.mapboxMap.onEvery(.cameraChanged, handler: { [weak self] _ in
guard let self = self else { return }
self.toggleAccuracyRadiusButton.isHidden = self.mapView.cameraState.zoom < 18.0
})
Get camera position
Once the map has been initialized, you can retrieve the camera's position to understand what the user is viewing, and other camera-related information, using the CameraState
property.
For example, you could display the longitude and latitude of the center point of the map as text:
let centerCoordinate = mapView.cameraState.center
Restrict camera
Use mapboxMap
's setCameraBounds
function to restrict a user's panning to limit the map camera to a chosen area.
For example, you could create a location-specific app experience in which a user's panning behavior is limited to a specific country, like Iceland.
let bounds = CoordinateBounds(southwest: CLLocationCoordinate2D(latitude: 63.33, longitude: -25.52),
northeast: CLLocationCoordinate2D(latitude: 66.61, longitude: -13.47))
// Restrict the camera to `bounds`.
try? mapView.mapboxMap.setCameraBounds(with: CameraBoundsOptions(bounds: bounds))
// Center the camera on the bounds
let camera = mapView.mapboxMap.camera(for: bounds, padding: .zero, bearing: 0, pitch: 0)
// Set the camera's center coordinate.
mapView.mapboxMap.setCamera(to: camera)
Use mapboxMap.setCameraBounds
to set the camera view and restrict user gestures to fit a specified bounding box.