MapCamera class abstract

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.

Note: The camera can be configured and positioned even before a map scene is loaded for the first time. This allows for pre-setting the desired camera position, orientation, and zoom level, which will be applied once the map scene becomes available.

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.lookAtArea 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 HereMapControllerCore 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 HereMapControllerCore using MapCamera.startAnimationWithListener.

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.