CameraUpdate

public struct CameraUpdate : Equatable

The CameraUpdate class specifies the map view’s camera position, zoom, tilt, rotation and more.

There are two ways to set a camera update:

  • Call TomTomMap.applyCamera(_:, animationDuration:, completion:) or TomTomMap.moveCamera(_:) which sets the camera update with a corresponding animation for the former or no animation for the latter.

  • Set it directly through the MapView, i.e.: mapView.cameraUpdate = CameraUpdate(position: .AMSTERDAM, zoom: 11).

Each method has its limitations:

  • When calling applyCamera(_:, animationDuration:, completion:) and moveCamera(_:) through the TomTomMap, there are certain CameraUpate properties that can and cannot be used in conjunction with others:

init(position:zoom:tilt:rotation:positionMarkerVerticalOffset:scale:fieldOfView:):

  • zoom - cannot be used together with scale.
  • scale - cannot be used together with zoom.

init(zoomBy:zoomIn:zoomOut:tiltBy:rotateBy:moveBy:fieldOfViewChangeBy:):

  • zoomBy - cannot be used together with zoomIn or zoomOut.
  • zoomIn- cannot be used together with zoomOut or zoomBy.
  • zoomOut- cannot be used together with zoomIn or zoomBy.
  • moveBy - cannot be used together with any of the other properties.

    • When setting directly the cameraUpdate field through the MapView, no animation is applied and only these specific properties can be set:
  • position.

  • zoom - cannot be used together with scale.

  • tilt.

  • rotation.

  • scale - cannot be used together with zoom.

  • fieldOfView.

  • moveBy - cannot be used together with any of the other properties.

  • Creates an instance of CameraUpdate.

    Declaration

    Swift

    public init(
        position: CLLocationCoordinate2D? = nil,
        zoom: Double? = nil,
        tilt: Double? = nil,
        rotation: Double? = nil,
        positionMarkerVerticalOffset: Double? = nil,
        scale: Double? = nil,
        fieldOfView: Double? = nil
    )

    Parameters

    position

    Position of the camera in CLLocationCoordinate2D.

    zoom

    Displays the map from a closer position. Allowed zoom level range: [0, 22]. zoom cannot be used together with scale.

    tilt

    Camera tilt. A value of 0 indicates the camera is looking straight down. 90 means it is looking straight ahead towards the horizon.

    rotation

    Camera heading, measured starting at due north and continuing clockwise around the compass. Thus, north is 0 degrees, east is 90 degrees, south is 180 degrees, and so on. Allowed range: [0, 360].

    positionMarkerVerticalOffset

    Sets the camera position marker vertical offset from the centre of the screen. The offset controls the placement of the position marker in the space between the center of the safe area and its bottom. Offset of 0.0 means the position marker should remain in the center of the safe area. Offset of 1.0 means the position marker should be aligned with the bottom of the safe area. The value may be ignored when the camera’s scale is such that offsetting the map causes the world to rotate oddly. Valid range for the offset is [0.0, 1.0].

    scale

    Ratio of a distance on the screen to the actual distance in the world. scale cannot be less than 1.0, and cannot be used together with zoom.

    fieldOfView

    Camera field of view in degrees. Allowed range [1.0, 150.0].

  • Creates an instance with some optional parameters.

    Level Max Scale
    0 295829357.775591
    1 147914678.887795
    2 73957339.443898
    3 36978669.721949
    4 18489334.860974
    5 9244667.430487
    6 4622333.715244
    7 2311166.857622
    8 1155583.428811
    9 577791.714405
    10 288895.857203
    11 144447.928601
    12 72223.964301
    13 36111.982150
    14 18055.991075
    15 9027.995538
    16 4513.997769
    17 2256.998884
    18 1128.499442
    19 564.249721
    20 282.124861
    21 141.062430
    22 70.531215

    Therefore, if we set a zoomBy of 2 on a zoom level 14, we will get the following: Zoom level 14 scale(18055.991075) * zoomBy(2) =~ 36111.982150 (Zoom level 13). zoomBy cannot be used together with zoomIn or zoomOut.

    • zoomIn: If true, adds an update that reduces the scale by one step. zoomIn cannot be used together with zoomOut or zoomBy.
    • zoomOut: If true, adds an update that increases the scale by one step. zoomOut cannot be used together with zoomIn or zoomBy.
    • tiltBy: Adds an update that adjusts the tilt by the specified angle. The tilt is measured from the nadir, i.e. value of 0 indicates the camera looking straight down, and 90 - straight ahead towards the horizon. The value may be clamped to a maximum value determined based on the camera’s scale, in order to assure map readability.
    • rotateBy: Adds an update that adjusts the heading by the specified angle in degree. Heading is measured starting at due north and continues clockwise around the compass. Thus, north is 0 degrees, east is 90 degrees, south is 180 degrees, and so on.
    • moveBy: Adds an update that adjusts current camera position specified by move vector moveBy. If moveBy is set, all other properties will be ignored.
    • fieldOfViewChangeBy: Adds an update that adjusts the field of view by the specified angle.

    Declaration

    Swift

    public init(
        zoomBy: Double? = nil,
        zoomIn: Bool = false,
        zoomOut: Bool = false,
        tiltBy: Double? = nil,
        rotateBy: Double? = nil,
        moveBy: CGPoint? = nil,
        fieldOfViewChangeBy: Double? = nil
    )

    Parameters

    zoomBy

    Adds an update that adjusts the scale by the specified value, i.e. a scale of 1:100 with a zoomBy of 2 becomes 1:200, a scale of 1:200 with a zoomBy of 0.25 becomes 1:50. If the resulting scale would be less than 1 after the update is applied, the scale is set to 1. The bigger the scale the smaller the zoom level (the further the map appears), the smaller the scale the bigger the zoom level (the closer the map appears). Therefore, if zoomBy is bigger than 1 the map will zoom out, and if zoomBy is smaller than 1 the map will zoom in. The following table demonstrates each zoom level and its corresponding scale:

    zoomIn

    If true, adds an update that reduces the scale by one step. zoomIn cannot be used together with zoomOut or zoomBy.

    zoomOut

    If true, adds an update that increases the scale by one step. zoomOut cannot be used together with zoomIn or zoomBy.

    tiltBy

    Adds an update that adjusts the tilt by the specified angle. The tilt is measured from the nadir, i.e. value of 0 indicates the camera looking straight down, and 90 - straight ahead towards the horizon. The value may be clamped to a maximum value determined based on the camera’s scale, in order to assure map readability.

    rotateBy

    Adds an update that adjusts the heading by the specified angle in degree. Heading is measured starting at due north and continues clockwise around the compass. Thus, north is 0 degrees, east is 90 degrees, south is 180 degrees, and so on.

    moveBy

    Adds an update that adjusts current camera position specified by move vector moveBy. If moveBy is set, all other properties will be ignored.

    fieldOfViewChangeBy

    Adds an update that adjusts the field of view by the specified angle.

  • Creates an instance with FitToCoordinatesOptions.

    Declaration

    Swift

    public init(fitToCoordinatesOptions: FitToCoordinatesOptions)

    Parameters

    fitToCoordinatesOptions

    FitToCoordinatesOptions instance.

  • Returns a CameraUpdate instance that transforms the camera to ensure that all coordinates are visible and padded.

    Declaration

    Swift

    public init(fitToCoordinates coordinates: [CLLocationCoordinate2D], padding: UInt = 0)

    Parameters

    coordinates

    List of coordinates to be taken into account when setting the camera position.

    padding

    Padding between the coordinates and camera borders.

  • Position of the camera in CLLocationCoordinate2D.

    Declaration

    Swift

    @EquatableWrapper
    public var position: CLLocationCoordinate2D? { get set }
  • Displays the map from a closer position. Allowed zoom level range: [0, 22]. Zoom level categories are as follows:

    • 0: The camera is fully zoomed out; the whole globe is visible.
    • 5: Country-level.
    • 10: City-level.
    • 15: Neighborhood-level.
    • 20: Street-level.
    • 22: Maximum zoom in.

    Declaration

    Swift

    public var zoom: Double?
  • A value of 0 indicates the camera is looking straight down. 90 means it is looking straight ahead towards the horizon.

    Declaration

    Swift

    public var tilt: Double?
  • Camera heading, measured starting at due north and continuing clockwise around the compass. Allowed range: [0, 360].

    Declaration

    Swift

    public var rotation: Double?
  • Sets the camera position marker vertical offset from the centre of the screen.

    Declaration

    Swift

    public var positionMarkerVerticalOffset: Double?
  • Sets the camera field of view in degrees. Valid range is [1.0, 150.0]

    Declaration

    Swift

    public var fieldOfView: Double?