MBMCameraManager

 

@interface MBMCameraManager : MBMStyleManager

Interface for managing camera.

  • Convenience method that returns the camera options object for given parameters.

    Declaration

    Objective-C

    - (nonnull MBMCameraOptions *)
    cameraForCoordinateBoundsForBounds:(nonnull MBMCoordinateBounds *)bounds
                               padding:(nonnull MBMEdgeInsets *)padding
                               bearing:(nullable NSNumber *)bearing
                                 pitch:(nullable NSNumber *)pitch;

    Swift

    func cameraForCoordinateBounds(for bounds: MBMCoordinateBounds, padding: MBMEdgeInsets, bearing: NSNumber?, pitch: NSNumber?) -> MBMCameraOptions

    Parameters

    bounds

    The coordinate bounds of the camera.
    padding

    The edge insets of the camera.
    bearing

    The bearing of the camera.
    pitch

    The pitch of the camera.

    Return Value

    The camera options object representing the provided parameters.

  • Convenience method that returns the camera options object for given parameters.

    Declaration

    Objective-C

    - (nonnull MBMCameraOptions *)
    cameraForCoordinatesForCoordinates:
        (nonnull NSArray<CLLocation *> *)coordinates
                               padding:(nonnull MBMEdgeInsets *)padding
                               bearing:(nullable NSNumber *)bearing
                                 pitch:(nullable NSNumber *)pitch;

    Swift

    func cameraForCoordinates(forCoordinates coordinates: [CLLocation], padding: MBMEdgeInsets, bearing: NSNumber?, pitch: NSNumber?) -> MBMCameraOptions

    Parameters

    coordinates

    The coordinates representing the bounds of the camera.
    padding

    The edge insets of the camera.
    bearing

    The bearing of the camera.
    pitch

    The pitch of the camera.

    Return Value

    The camera options object representing the provided parameters.

  • Convenience method that adjusts the provided camera options object for given parameters.

    Returns the provided camera options with zoom adjusted to fit coordinates into the box, so that coordinates on the left, top, right, and bottom of the effective camera center at the principal point of the projection (defined by padding) fit into the box. Returns the provided camera options object unchanged upon an error.

    The method fails if the principal point is positioned outside of the box or if there is no sufficient screen space, defined by principal point and the box, to fit the geometry. Additionally, in cases when the principal point is positioned exactly on one of the edges of the box, any geometry point that spans further than that edge on the same axis cannot possibly be framed and is ignored for zoom level calculation purposes.

    This API isn’t supported by Globe projection.

    Declaration

    Objective-C

    - (nonnull MBMCameraOptions *)
    cameraForCoordinatesForCoordinates:
        (nonnull NSArray<CLLocation *> *)coordinates
                                camera:(nonnull MBMCameraOptions *)camera
                                   box:(nonnull MBMScreenBox *)box;

    Swift

    func cameraForCoordinates(forCoordinates coordinates: [CLLocation], camera: MBMCameraOptions, box: MBMScreenBox) -> MBMCameraOptions

    Parameters

    coordinates

    The coordinates representing the bounds of the camera.
    camera

    The camera options for which zoom should be adjusted. Note that the camera.center, and camera.zoom (as fallback) is required.
    box

    The screen box into which coordinates should fit.

    Return Value

    The camera options object with the zoom level adjusted to fit coordinates into the box.

  • Convenience method that returns the camera options object for given parameters.

    Declaration

    Objective-C

    - (nonnull MBMCameraOptions *)
    cameraForGeometryForGeometry:(nonnull MBXGeometry *)geometry
                         padding:(nonnull MBMEdgeInsets *)padding
                         bearing:(nullable NSNumber *)bearing
                           pitch:(nullable NSNumber *)pitch;

    Swift

    func cameraForGeometry(for geometry: MBXGeometry, padding: MBMEdgeInsets, bearing: NSNumber?, pitch: NSNumber?) -> MBMCameraOptions

    Parameters

    geometry

    The geometry representing the bounds of the camera.
    padding

    The edge insets of the camera.
    bearing

    The bearing of the camera.
    pitch

    The pitch of the camera.

    Return Value

    The camera options object representing the provided parameters.

  • Returns the coordinate bounds for a given camera.

    Note that if the given camera shows the antimeridian, the returned wrapped coordinate bounds might not represent the minimum bounding box.

    Declaration

    Objective-C

    - (nonnull MBMCoordinateBounds *)coordinateBoundsForCameraForCamera:
    (nonnull MBMCameraOptions *)camera;

    Swift

    func coordinateBoundsForCamera(forCamera camera: MBMCameraOptions) -> MBMCoordinateBounds

    Parameters

    camera

    The camera options to use for calculating coordinate bounds.

    Return Value

    The coordinate bounds object representing a given camera.

  • Returns the coordinate bounds for a given camera.

    This method is useful if the camera shows the antimeridian.

    Declaration

    Objective-C

    - (nonnull MBMCoordinateBounds *)coordinateBoundsForCameraUnwrappedForCamera:
    (nonnull MBMCameraOptions *)camera;

    Swift

    func coordinateBoundsForCameraUnwrapped(forCamera camera: MBMCameraOptions) -> MBMCoordinateBounds

    Parameters

    camera

    The camera options to use for calculating coordinate bounds.

    Return Value

    The coordinate bounds object representing a given camera.

  • Returns the coordinate bounds and the zoom for a given camera.

    Note that if the given camera shows the antimeridian, the returned wrapped coordinate bounds might not represent the minimum bounding box.

    Declaration

    Objective-C

    - (nonnull MBMCoordinateBoundsZoom *)coordinateBoundsZoomForCameraForCamera:
    (nonnull MBMCameraOptions *)camera;

    Swift

    func coordinateBoundsZoomForCamera(forCamera camera: MBMCameraOptions) -> MBMCoordinateBoundsZoom

    Parameters

    camera

    The camera options to use for calculating coordinate bounds and zoom.

    Return Value

    The object representing coordinate bounds and zoom for a given camera.

  • Returns the unwrapped coordinate bounds and zoom for a given camera.

    This method is useful if the camera shows the antimeridian.

    Declaration

    Objective-C

    - (nonnull MBMCoordinateBoundsZoom *)
    coordinateBoundsZoomForCameraUnwrappedForCamera:
        (nonnull MBMCameraOptions *)camera;

    Swift

    func coordinateBoundsZoomForCameraUnwrapped(forCamera camera: MBMCameraOptions) -> MBMCoordinateBoundsZoom

    Parameters

    camera

    The camera options to use for calculating coordinate bounds and zoom.

    Return Value

    The object representing coordinate bounds and zoom for a given camera.

  • Calculates a screen coordinate that corresponds to a geographical coordinate (i.e., longitude-latitude pair).

    The screen coordinate is in platform pixels relative to the top left corner of the map (not of the whole screen).

    Declaration

    Objective-C

    - (nonnull MBMScreenCoordinate *)pixelForCoordinateForCoordinate:
    (CLLocationCoordinate2D)coordinate;

    Swift

    func pixelForCoordinate(for coordinate: CLLocationCoordinate2D) -> MBMScreenCoordinate

    Parameters

    coordinate

    A geographical coordinate on the map to convert to a screen coordinate.

    Return Value

    A screen coordinate on the screen in platform pixels.

  • Calculates a geographical coordinate (i.e., longitude-latitude pair) that corresponds to a screen coordinate.

    The screen coordinate is in platform pixelsrelative to the top left corner of the map (not of the whole screen).

    Declaration

    Objective-C

    - (CLLocationCoordinate2D)coordinateForPixelForPixel:
    (nonnull MBMScreenCoordinate *)pixel;

    Swift

    func coordinateForPixel(forPixel pixel: MBMScreenCoordinate) -> CLLocationCoordinate2D

    Parameters

    pixel

    A screen coordinate on the screen in platform pixels.

    Return Value

    A geographical coordinate corresponding to a given screen coordinate.

  • Calculates screen coordinates that correspond to geographical coordinates (i.e., longitude-latitude pairs).

    The screen coordinates are in platform pixels relative to the top left corner of the map (not of the whole screen).

    Declaration

    Objective-C

    - (nonnull NSArray<MBMScreenCoordinate *> *)pixelsForCoordinatesForCoordinates:
    (nonnull NSArray<CLLocation *> *)coordinates;

    Swift

    func pixelsForCoordinates(forCoordinates coordinates: [CLLocation]) -> [MBMScreenCoordinate]

    Parameters

    coordinates

    A geographical coordinates on the map to convert to screen coordinates.

    Return Value

    A screen coordinates in platform pixels for a given geographical coordinates.

  • Calculates geographical coordinates (i.e., longitude-latitude pairs) that correspond to screen coordinates.

    The screen coordinates are in platform pixels relative to the top left corner of the map (not of the whole screen).

    Declaration

    Objective-C

    - (nonnull NSArray<CLLocation *> *)coordinatesForPixelsForPixels:
    (nonnull NSArray<MBMScreenCoordinate *> *)pixels;

    Swift

    func coordinatesForPixels(forPixels pixels: [MBMScreenCoordinate]) -> [CLLocation]

    Parameters

    pixels

    A screen coordinates in platform pixels.

    Return Value

    A geographical coordinates that correspond to a given screen coordinates.

  • Changes the map view by any combination of center, zoom, bearing, and pitch, without an animated transition. The map will retain its current values for any details not passed via the camera options argument. It is not guaranteed that the provided camera options will be set, the map may apply constraints resulting in a different camera state.

    Declaration

    Objective-C

    - (void)setCameraForCameraOptions:(nonnull MBMCameraOptions *)cameraOptions;

    Swift

    func setCameraFor(_ cameraOptions: MBMCameraOptions)

    Parameters

    cameraOptions

    The new camera options to be set.

  • Returns the current camera state.

    Declaration

    Objective-C

    - (nonnull MBMCameraState *)getCameraState;

    Swift

    func getCameraState() -> MBMCameraState

    Return Value

    The current camera state.

  • Sets the map view with the free camera options.

    The free camera options provides more direct access to the underlying camera entity. For backwards compatibility the state set using this API must be representable with camera options as well. Parameters are clamped to a valid range or discarded as invalid if the conversion to the pitch and bearing presentation is ambiguous. For example orientation can be invalid if it leads to the camera being upside down or the quaternion has zero length.

    Declaration

    Objective-C

    - (void)setCameraForFreeCameraOptions:
    (nonnull MBMFreeCameraOptions *)freeCameraOptions;

    Swift

    func setCameraFor(_ freeCameraOptions: MBMFreeCameraOptions)

    Parameters

    freeCameraOptions

    The free camera options to set.

  • Gets the map’s current free camera options. After mutation, it should be set back to the map.

    Declaration

    Objective-C

    - (nonnull MBMFreeCameraOptions *)getFreeCameraOptions;

    Swift

    func getFreeCameraOptions() -> MBMFreeCameraOptions

    Return Value

    The current free camera options.

  • Returns the camera bounds of the map.

    Declaration

    Objective-C

    - (nonnull MBMCameraBounds *)getBounds;

    Swift

    func getBounds() -> MBMCameraBounds

    Return Value

    A camera bounds of the map.

  • Prepares the drag gesture to use the provided screen coordinate as a pivot point. This function should be called each time when user starts a dragging action (e.g. by clicking on the map). The following dragging will be relative to the pivot.

    Declaration

    Objective-C

    - (void)dragStartForPoint:(nonnull MBMScreenCoordinate *)point;

    Swift

    func dragStart(forPoint point: MBMScreenCoordinate)

    Parameters

    point

    The pivot screen coordinate, measured in platform pixels from top to bottom and from left to right.

  • Calculates target point where camera should move after drag. The method should be called after dragStart and before dragEnd.

    Declaration

    Objective-C

    - (nonnull MBMCameraOptions *)
    getDragCameraOptionsForFromPoint:(nonnull MBMScreenCoordinate *)fromPoint
                             toPoint:(nonnull MBMScreenCoordinate *)toPoint;

    Swift

    func getDragCameraOptionsFor(fromPoint: MBMScreenCoordinate, toPoint: MBMScreenCoordinate) -> MBMCameraOptions

    Parameters

    fromPoint

    The screen coordinate to drag the map from, measured in platform pixels from top to bottom and from left to right.
    toPoint

    The screen coordinate to drag the map to, measured in platform pixels from top to bottom and from left to right.

    Return Value

    The camera options object showing the end point.

  • Ends the ongoing drag gesture. This function should be called always after the user has ended a drag gesture initiated by dragStart.

    Declaration

    Objective-C

    - (void)dragEnd;

    Swift

    func dragEnd()

  • Undocumented

    Declaration

    Objective-C

    - (nonnull MBXExpected<NSNull *, NSString *> *)setBoundsForOptions:(nonnull MBMCameraBoundsOptions *)options __attribute((ns_returns_retained));

    Swift

    func setBoundsFor(_ options: MBMCameraBoundsOptions) -> MBXExpected