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 the following 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, which impacts the location at which thecenter
point is rendered.anchor
: The point in the map’s coordinate system about whichzoom
andbearing
should be applied. This is mutually exclusive withcenter
.
Set camera position
The Mapbox Maps SDK for iOS 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 map. This approach is best if you know what part of the world you want to show to the user first. Since the SDK will load the tiles around the specified location first, the map may appear to load faster.
Map(initialViewport: .camera(
center: CLLocationCoordinate2D(latitude: 40.7135, longitude: -74.0066),
zoom: 15.5,
bearing: -17.6,
pitch: 45
))
// 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 camera 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.
@State private var viewport = Viewport.camera()
Map(viewport: $viewport)
.onMapTapGesture { context in
viewport = .camera(center: context.coordinate)
}
final class MapViewController: UIViewController {
private var mapView: MapView!
private var cancellables: Set<AnyCancelable> = []
override func viewDidLoad() {
super.viewDidLoad()
// Initializes map
mapView = MapView(frame: view.bounds)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
view.insertSubview(mapView, at: 0)
// Add a tap observer
mapView.gestures.onMapTap.observe { [unowned self] context in
// // Set the camera to tap's position.
self.mapView.mapboxMap.setCamera(to: CameraOptions(center: context.coordinate))
}.store(in: &cancellables)
}
}
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 permission to access location's data, you can observe their location using LocationManager
APIs.
if let latestLocation = mapView.location.latestLocation.coordinate {
mapView.mapboxMap.setCamera(to: CameraOptions(center: latestLocation, 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.
// Observe location changes.
mapView.location.onLocationChange.observe { [weak mapView] locations in
guard let mapView, let latestLocation = locations.last?.coordinate else { return }
// Set camera to latest location.
mapView.mapboxMap.setCamera(to: .init(center: latestLocation, zoom: 15))
}.store(in: &cancellables)
In SwiftUI you can access LocationManager
instance using MapReader
to get the latest location.
@State var viewport = Viewport.camera()
MapReader { proxy in
Map(viewport: $viewport)
.onAppear {
if let latestLocation = proxy.location.latestLocation.coordinate {
viewport = .camera(center: latestLocation, zoom: 15)
}
}
}
And if you want to follow the user location, the simplest way to do so in SwiftUI would be the .followPuck
viewport.
Map(initialViewport: .followPuck(zoom: 15))
Update camera based on user's location.
Fit the camera to a given shape
You can position the camera to fit a specified shape within the viewport.
-
To fit a camera for a given geometry, call
MapboxMap/camera(for:camera:coordinatesPadding:maxZoom:offset:)
-
To fit the camera to a set of rectangular coordinate bounds (in other words, a bounding box), call
MapboxMap/CameraBoundsOptions
To fit a given shape/geometry at least 2 points on the map should be provided. If you want to fit camera to a single coordinate, use CameraOptions/init(center:padding⚓zoom:bearing:pitch:)
This example fits the camera to a collection of coordinates:
// Define collection of coordinates.
let triangleCoordinates = [
CLLocationCoordinate2DMake(43.274580742195845, -2.938070297241211),
CLLocationCoordinate2DMake(43.258768377941465, -2.9680252075195312),
CLLocationCoordinate2DMake(43.24063848114794, -2.912750244140625),
CLLocationCoordinate2DMake(43.274580742195845, -2.938070297241211),
]
// The reference camera options which will be applied before calculating a camera fitting the given coordinates.
// If any of the fields in this referencecamera options is not provided then the current value from the map will be used.
let referenceCamera = CameraOptions(zoom: 5, bearing: 45)
// Fit camera to the given coordinates.
let camera = try? mapView.mapboxMap.camera(
for: triangleCoordinates,
camera: referenceCamera,
coordinatesPadding: .zero,
maxZoom: nil,
offset: nil)
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)
Listen for camera changes
The Maps SDK provides several ways to detect whether camera change events have happened.
To listen to camera updates, you can use instance property MapboxMap/onCameraChanged
, which provides an instance of CameraChanged
containing information about new camera in its callback.
// Accuracy ring is only shown when zoom is greater than or equal to 18.
mapView.mapboxMap.onCameraChanged.observe { [weak self] cameraChanged in
guard let self else { return }
self.toggleAccuracyRadiusButton.isHidden = cameraChanged.cameraState.zoom < 18
}.store(in: &cancellables)
Print out map events and data.
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, by accessing instance property MapboxMap/cameraState
.
For example, you could display the longitude and latitude of the center point of the map as text:
let centerCoordinate = mapView.mapboxMap.cameraState.center
Restrict camera
Use MapboxMap/setCameraBounds(with:)
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)