public class MapCamera
extension MapCamera: NativeBase
extension MapCamera: Hashable

Represents the camera looking onto the map view.

Each map instance has exactly one camera that is used to manipulate the way the map is displayed.

Any updates to the state of the camera will be applied while drawing the next map view frame and the current state of the camera reflects what is currently drawn inside the map view.

Camera Model

Camera Concepts and Units

By default, HERE SDK uses an idealized Earth globe with a 3D-capable camera model. Being a 3D camera model means that the world position can be freely specified in geodetic 3D space (i.e. Earth centric) and the orientation can be freely changed around two axes - bearing (also known as head) and tilt (also known as pitch).

The camera supports the look-at target with orientation on the ground way of setting up the camera in space. The camera is placed so that it looks at a specific geo-coordinates (placed at the principal point) from a given orientation and distance.

  • the look-at target in geo-coordinates (latitude, longitude) in degrees and an altitude in meters above MSL (mean sea level) at the principal point
  • the orientation at the look-at target
  • the distance of the camera from the look-at target, given as distance in meters or as zoom-level

Getting the current camera state

The current camera state can be obtained by the MapCamera.state call. It contains information about the camera look-at target (geo-coordinates and orientation) in geodetic space. The values are returned for the current principal point. This can lead to surprising or unexpected values in cases where the camera position/orientation was specified for another screen point, e.g. when using MapCameraUpdateFactory.lookAt(GeoBox) with a view rectangle, whose center does not coincide with the principal point. In this case, the geo-coordinates of the look-at target will differ from the center of the geo-box used in the lookAt call.

Geo coordinates

Geo-coordinates are given in degrees and follow the common nomenclature of positive northern latitudes and positive eastern longitudes.

Altitude

When altitude is specified, it is always in meters above mean sea level (MSL). If this value is invalid (not-a-number) or not specified, then the terrain height at the given geo-coordinates will be looked up from the map. This is especially interesting in cases where terrain elevation is used within the map display.

Distance vs zoom-level vs scale

Map camera distance, zoom-level and scale determine how much of the world is visible on the HERE map. Distance, zoom-level and scale are directly connected and changing one will automatically change the others as well (except for distance/scale changes that map to zoom-level values < 0 or > 23).

  • distance: the distance from the camera to the look-at target on the surface of the Earth, in meters
  • zoom-level: the map zoom level, in the range [0, 3]. The relation between the width of the equator in logical pixels w and the zoom level z is: w = 256 * 2^(z)
  • scale: the scale of the map at the look-at target in meters on screen per meters on Earth. So a scale of 0.001 shows 10 meters on Earth within 1 cm on screen.

The following mapping represents the zoom-level values:

Orientation

The camera orientation is composed of two parts:

  • bearing: also known as azimuth, the view direction in clockwise degrees; 0° = north, 90° = east, 180° = south, 270° = west
  • tilt: the angle in degrees from the vertical that the camera is looking down at the Earth; 0° = straight down.

Changing the Camera

All changes to the camera are encapsulated in camera updates that are created using the methods in the MapCameraUpdateFactory class.

These updates can then be applied to the HereMap using MapCamera.applyUpdate(...).

Camera updates are queued and executed when the next frame is rendered. They are executed in the order in which they were applied.

Animating the Camera

Camera updates can be animated by first creating a camera animation using the methods in the MapCameraAnimationFactory class and then applying this animation to the HereMap using MapCamera.startAnimation(MapCameraAnimation, AnimationDelegate).

Only one camera animation for one camera component at a time is supported. Applying a new animation will cancel the active animation before the new one is started. The start position in this case is where ever the active animation happened to be at the time. Different components are camera state (target pose and distance/zoom level/scale) and camera projection (field of view, focal length and principal point).

The running animations can also be canceled using MapCamera.cancelAnimations(...) or individual ones using MapCamera.cancelAnimation(...).

  • Used to report back results of dry update application to camera.

    Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

    Declaration

    Swift

    public typealias DryCameraUpdateHandler = (MapCamera.State?) -> Void

    Parameters

    p0

    Map camera state after dry application of update

  • Current state of the camera that reflects what is currently drawn by the map view.

    Declaration

    Swift

    public var state: MapCamera.State { get }

  • Determines the pixel point where the target is placed within the map view. Setting a new principal point instantly moves the map to render the current target coordinates at the new principal point. By default, the principal point is located at the center of the map view. It is set in pixels relative to the map view’s origin top-left (0, 0). Values outside the map view’s dimensions (x < 0 || x > width, y < 0 || y > height) will be rejected silently and the current principal point is kept.

    The value of the principal point is adjusted when the dimensions of the map view change, so that it stays in the same point relative to width and height. Meaning that when a principal point it set to bottom middle of the map view, it will stay in the bottom middle regardless of the changes to dimensions and orientation of the view.

    Note: The principal point affects all programmatical map transformations (rotate, orbit, tilt and zoom) and the two-finger-pan gesture to tilt the map. Other gestures, like pinch-rotate, are not affected.

    Declaration

    Swift

    public var principalPoint: Point2D { get set }

  • Currently visible map area encompassed in a GeoBox. Note that this bounding box is always rectangular, and its sides are always parallel to the latitude and longitude. If the camera is rotated, the returned bounding box will be a circumscribed rectangle that is larger than the visible map area. Similarly, when the map is tilted (for example, if the map is tilted by 45 degrees), the visible map area represents a trapezoidal area in the world. Resulting value will then be a larger circumscribed rectangle that contains this trapezoid area. Because on this, corners of the resulting bounding box may be located outside of the currently visible area.

    When the map area does not fully fill the viewport, nil is returned.

    Declaration

    Swift

    public var boundingBox: GeoBox? { get }

  • Controls limits for the camera settings.

    Declaration

    Swift

    public var limits: MapCameraLimits { get }

  • Encapsulates state of the camera.

    See more

    Declaration

    Swift

    public struct State

  • Adds a delegate to this camera that will be notified on the main thread every time the map is redrawn with new camera parameters.

    Adding the same delegate multiple times has no effect.

    Declaration

    Swift

    public func addDelegate(_ delegate: MapCameraDelegate)

    Parameters

    delegate

    The delegate to add.

  • Removes the delegate from the camera.

    Trying to remove a delegate that is not currently registered has no effect.

    Declaration

    Swift

    public func removeDelegate(_ delegate: MapCameraDelegate)

    Parameters

    delegate

    The delegate to remove.

  • Removes all registered delegates.

    Declaration

    Swift

    public func removeDelegates()

  • Applies camera update to the map camera.

    Any ongoing camera animations will be cancelled and the corresponding camera animation delegate will be notified.

    Declaration

    Swift

    public func applyUpdate(_ cameraUpdate: MapCameraUpdate)

    Parameters

    cameraUpdate

    The update that gets applied to camera.

  • Computes result of applying camera update without changing state of the map camera.

    Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

    Declaration

    Swift

    public func dryApplyUpdate(_ cameraUpdate: MapCameraUpdate, completion: @escaping MapCamera.DryCameraUpdateHandler)

    Parameters

    cameraUpdate

    The update that gets dryly applied to camera.
    completion

    Called upon completion with computed map state.

  • Starts a given camera animation.

    Starting an animation can cause the cancelling of an ongoing animation when they both affect the same category of camera properties, like for example any of the look-at properties (target, orientation, map measure) or any of the projection properties (field of view, principal point, focal length). The corresponding delegate of an ongoing animation will be notified about the cancellation in these cases.

    Declaration

    Swift

    public func startAnimation(_ cameraAnimation: MapCameraAnimation)

    Parameters

    cameraAnimation

    The animation to be started.

  • Starts a given camera animation. The state of the animation can be tracked with the provided listener.

    Starting an animation can cause the cancelling of an ongoing animation when they both affect the same category of camera properties, like for example any of the look-at properties (target, orientation, map measure) or any of the projection properties (field of view, principal point, focal length). The corresponding delegate of an ongoing animation will be notified about the cancellation in these cases.

    Declaration

    Swift

    public func startAnimation(_ cameraAnimation: MapCameraAnimation, animationDelegate: AnimationDelegate)

    Parameters

    cameraAnimation

    The animation to be started.
    animationDelegate

    Animation delegate. A strong reference is kept internally up until the animation gets cancelled or completed.

  • Cancels an ongoing camera animation.

    Upon cancellation, the corresponding delegate will be notified.

    Declaration

    Swift

    public func cancelAnimation(_ cameraAnimation: MapCameraAnimation)

    Parameters

    cameraAnimation

    The animation to be cancelled.

  • Cancels any ongoing camera animation.

    Upon cancellation, the corresponding delegate of any cancelled animation will be notified.

    Declaration

    Swift

    public func cancelAnimations()

  • Orbits the camera around a specified view point by increasing tilt and bearing by specified delta values.

    Declaration

    Swift

    public func orbitBy(_ delta: GeoOrientationUpdate, around origin: Point2D)

    Parameters

    delta

    Camera orientation change, containing tilt and bearing angle deltas.
    origin

    Pixel point in view coordinates around which orbiting occurs.

  • Zooms in or out by a specified factor.

    This effectively changes the distance from the camera to the MapCamera.State.targetCoordinates by the specified factor, which changes MapCamera.State.zoomLevel as well.

    Values above 1.0 will zoom in and values below will zoom out.

    The relation with MapCamera.State.distanceToTargetInMeters is inversely linear, meaning that zooming by 4 will decrease distance to target by 4 while zooming by 0.5 will increase distance to target by 2.

    The relation with zoom level is logarithmic. Meaning that zooming by a factor of 4 will increase zoom level by 2 (because log2(4) == 2). So to zoom in by X zoom levels, the zoom factor needs to be 2^X. To zoom out by X zoom levels, zoom factor needs to be 1/(2^X).

    The zooming occurs around the specified origin inside the view.

    Declaration

    Swift

    public func zoomBy(_ factor: Double, around origin: Point2D)

    Parameters

    factor

    The zoom factor. Values above 1.0 will zoom in and values below will zoom out.
    origin

    Pixel point in view coordinates around which zooming occurs.

  • Zooms to the specified zoom level. The supplied value will be clamped to the range of [0, 22], where 0 is a view of whole globe and 22 is street level.

    This effectively changes the distance from the camera to the target. The zooming occurs around the current target point.

    Declaration

    Swift

    public func zoomTo(zoomLevel: Double)

    Parameters

    zoomLevel

    The zoom level to set, clamped to the range of [0, 22].

  • Makes the camera look at a new geodetic target, while preserving the current orientation and distance to the target.

    The altitude of the target point is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

    Declaration

    Swift

    public func lookAt(point target: GeoCoordinates)

    Parameters

    target

    Geodetic coordinates at which the camera will point.

  • Makes the camera look at the geodetic target with the given zoom.

    The altitude of the target point is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

    Declaration

    Swift

    public func lookAt(point target: GeoCoordinates, zoom: MapMeasure)

    Parameters

    target

    Geodetic coordinates at which the camera will point.
    zoom

    The zoom level which can be provided as distance to the target point, scale or zoom level.

  • Makes the camera look at the geodetic target with the given zoom and orientation.

    The supplied orientation is the orientation of the camera looking at the target, so the resulting camera state will have the same orientation as the one supplied to this method.

    The altitude of the target point is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

    Declaration

    Swift

    public func lookAt(point target: GeoCoordinates, orientation: GeoOrientationUpdate, zoom: MapMeasure)

    Parameters

    target

    Geodetic coordinates at which the camera will point.
    orientation

    Desired orientation of the camera.
    zoom

    The zoom level which can be provided as distance to the target point, scale or zoom level.

  • Makes the camera look at the specified geodetic area.

    The supplied orientation is the orientation of the camera looking at the target, so the resulting camera state will have the same orientation as the one supplied to this method.

    The altitude of the target points is ignored.

    Declaration

    Swift

    public func lookAt(area target: GeoBox, orientation: GeoOrientationUpdate)

    Parameters

    target

    Geodetic area at which the camera will point
    orientation

    Desired orientation of the camera

  • Makes the camera look at the specified geodetic area and pass a rectangle which specifies where the area should appear inside of the map view.

    The supplied orientation is the orientation of the camera looking at the target, so the resulting camera state will have the same orientation as the one supplied to this method. Please note that the resulting orientation might deviate from the provided orientation. This is particularly the case if a large geobox on world level and a view rectangle which is relatively small was passed to the method.

    The altitude of the target points is ignored.

    Declaration

    Swift

    public func lookAt(area target: GeoBox, orientation: GeoOrientationUpdate, viewRectangle: Rectangle2D)

    Parameters

    target

    Geodetic area which will be shown in the viewRectangle.
    orientation

    Desired orientation of the camera.
    viewRectangle

    The view rectangle in viewport pixel coordinates inside which the geographical target area is displayed.

  • Makes the camera look at current target from certain distance

    This function neither modifies target coordinates nor target orientation.

    Declaration

    Swift

    public func setDistanceToTarget(distanceInMeters: Double)

    Parameters

    distanceInMeters

    Distance in meters to the target point. Minimal distance value is clamped to 100 meters.

  • Changes camera orientation in relation to target location.

    Declaration

    Swift

    public func setOrientationAtTarget(_ orientation: GeoOrientationUpdate)

    Parameters

    orientation

    Desired orientation of the camera.