MapCamera Class Reference
- Last UpdatedMay 13, 2025
- 11 minute read
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 theprincipal point
- the
orientation
at the look-at target - the distance of the camera from the look-at target, given as
distance
in meters or aszoom-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 meterszoom-level
: the map zoom level, in the range [0, 3]. The relation between the width of the equator in logical pixelsw
and the zoom levelz
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° = westtilt
: 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 moreDeclaration
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 changesMapCamera.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.