Camera

Using Mappedin SDK for iOS with your own map requires a Pro license. Try a demo map for free or refer to the Pricing page for more information.

Controlling the view of the map allows apps to create visually rich experiences using Mappedin SDKs. This guide shows how to focus the map view on targets, move the camera and listen to camera events.

tip

A complete example demonstrating Camera can be found in the Mappedin iOS Github repo: CameraDemoViewController.swift

tip

Note that the MapView class instantiates the Camera class and exposes it as MapView.Camera. Use MapView.Camera to utilize Camera's methods.

Focus the Camera on Targets

Mappedin SDK for iOS built in functionality to focus the camera on one ore more targets using a single or array of FocusTarget objects. When multiple targets are used, the SDK will ensure that all targets are visible.

The following sample code acts on the click event to focus on the Space the user clicked on. Note that the Space must be set to interactive to allow it to be clickable. Refer to the Interactivity guide for more information on how to set a space to interactive.

// Focus the camera on the click location.
mapView.on(Events.click) { [weak self] clickPayload in
  guard let self = self, let click = clickPayload else { return }
  self.mapView.camera.focusOn(coordinate: click.coordinate)
}

Controlling the Camera

To control the camera, set it with new pitch, bearing or zoom using Camera.set(). It accepts a CameraTarget object that contains bearing, center coordinate, pitch and zoom level. These parameters are all optional, allowing the camera to by moved by adjusting one or more of these values.

CameraTarget

• bearing: Bearing for the camera target in degrees.
• center: Center Coordinate for the camera target.
• pitch: Pitch for the camera target in degrees.
• zoomLevel: Zoom level for the camera target in mercator zoom levels.

let transform = CameraTarget(bearing: 30, pitch: 80, zoomLevel: 19.5)
self.mapView.camera.set(target: transform) { result in
    switch result {
    case .success:
        print("Camera set successfully")
    case .failure(let error):
        print("Camera set failed: \(error)")
    }
}

Animation

The camera can also be animated into position using the same transforms described in the Controlling the Camera section above. This is done using the Camera.animateTo() method. Similar to Camera.set(), the animateTo method accepts a CameraTarget object, but it is optional. This allows the camera to changed by adjusting its bearing, pitch or zoomLevel without specifying a new target to move to. In addition, animateTo also accepts CameraAnimationOptions that allow setting of the duration of the animation in milliseconds and setting the easing curve.

The next code snippet animates to the center of the camera's current position and zooms in to a zoom level of 21.0, pitches the camera to 60.0 degrees and rotates the camera to 180.0 degrees over 3000 milliseconds using the easing function ease-in-out.

mapView.camera.center { [weak self] result in
    guard let self = self else { return }
    if case .success(let center) = result, let center = center {
        let transform = CameraTarget(
            bearing: 180.0,
            center: center,
            pitch: 60.0,
            zoomLevel: 21.0
        )
        let options = CameraAnimationOptions(duration: 3000, easing: EasingFunction.EASE_IN_OUT, interruptible: nil)
        self.mapView.camera.animateTo(target: transform, options: options) { _ in }
    }
}

The types of easing animations are defined in EasingFunction.

EasingFunction

• Linear: This function implies a constant rate of change. It means the animation proceeds at the same speed from start to end. There's no acceleration or deceleration, giving a very mechanical feel.
• Ease-in: This function causes the animation to start slowly and then speed up as it progresses. Initially, there's gradual acceleration, and as the function moves forward, the rate of change increases.
• Ease-out: Contrary to ease-in, ease-out makes the animation start quickly and then slow down towards the end. It begins with a faster rate of change and gradually decelerates.
• Ease-in-out: This function combines both ease-in and ease-out. The animation starts slowly, speeds up in the middle, and then slows down again towards the end. It offers a balance of acceleration and deceleration.

Resetting The Camera

While there is no method in Mappedin SDKs to reset the camera to its default position, this can be easily built into an app. To do so, store the camera position after the map is shown and then use those values to reposition the camera at a later time.

The code sample below stores the initial camera position. When a user clicks on a location it first focuses on that space. The next click will return the camera to its original position.

private var defaultPitch: Double?
private var defaultZoomLevel: Double?
private var defaultBearing: Double?
private var defaultCenter: Coordinate?

...

// Store default camera values
mapView.camera.pitch { [weak self] result in
    if case .success(let pitch) = result {
        self?.defaultPitch = pitch
    }
}
mapView.camera.zoomLevel { [weak self] result in
    if case .success(let zoomLevel) = result {
        self?.defaultZoomLevel = zoomLevel
    }
}
mapView.camera.bearing { [weak self] result in
    if case .success(let bearing) = result {
        self?.defaultBearing = bearing
    }
}
mapView.camera.center { [weak self] result in
    if case .success(let center) = result {
        self?.defaultCenter = center
    }
}

...

// Set the camera to the default position
let transform = CameraTarget(
    bearing: defaultBearing,
    center: defaultCenter,
    pitch: defaultPitch,
    zoomLevel: defaultZoomLevel
)
mapView.camera.set(target: transform) { _ in }

Listening to Camera Events

There are several camera events that can be acted on by setting a listener with mapView.on(Events.cameraChange). The camera-change event contains a CameraTransform object. CameraTransform provides the bearing, center coordinate, pitch and zoom level.

// Log camera change events to the console.
mapView.on(Events.cameraChange) { [weak self] cameraTransform in
  guard self != nil, let transform = cameraTransform else { return }
  print("Camera changed to bearing: \(transform.bearing), pitch: \(transform.pitch), zoomLevel: \(transform.zoomLevel), center: Lat: \(transform.center.latitude), Lon: \(transform.center.longitude)")
}

tip

A complete example demonstrating Camera can be found in the Mappedin iOS Github repo: CameraDemoViewController.swift