Skip to main content

Camera position

Additional Developer Resources

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 the center point is rendered.
  • anchor: The point in the map’s coordinate system about which zoom and bearing should be applied. This is mutually exclusive with center.
PLAYGROUND
Location Helper

To experiment with camera pitch, bearing, tilt, and zoom and get values to use in your code, try our Location Helper tool.

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
))
Default camera position

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)
  }

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))
EXAMPLE
Display the user's location

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.

Note

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)
EXAMPLE
Print out map events and data

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)
Additional Developer Resources
Was this page helpful?