A delegate for animation events.

Describes the possible states of an animation.

Assets manager interface. Can be used to make assets available to the SDK.

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

Data attributes collection.

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

Accessor used for manipulating data attributes.

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

Data attributes collection builder.

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

Encapsulates a data attribute value. Supports basic types and arrays of basic types.

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

Represents a dash pattern for map polyline.

Protocol for handling double tap gestures. Double-tap gesture occurs after double-tapping on the screen.

Specifies the type of map item draw order. Map item rendering behavior is chosen based on the draw order type.

Regardless of a draw order type map items with a higher draw order are drawn on top of map items with a lower draw order.

When having map items in a scene with the same draw order, but with different draw order types DrawOrderType.mapSceneAdditionOrderDependent and DrawOrderType.mapSceneAdditionOrderIndependent, DrawOrderType.mapSceneAdditionOrderDependent items will be rendered on top of DrawOrderType.mapSceneAdditionOrderIndependent ones.

Animation easing representing an easing function to be used during animations.

Animation easing functions.

A GeoCoordinatesKeyframe consists of a GeoCoordinates and an animation duration.

A GeoOrientationKeyframe consists of a GeoOrientation (camera orientation) and an animation duration.

Represents the state of the gesture.

Enum that represents the type of a gesture.

Use this class to process touch events from the platform and detect gesture induced actions on the map view. Please note that this class holds strong references to the gesture delegates.

The representation of a dynamic and interactive geographic map. The map manages a collection of layers of objects and spaces, presents them in a stacked layout and offers the means to focus on a certain area. The layers, their relation to the objects and spaces, the layout and the representation style is described through a configuration.

This provider creates icons from a given set of parameters for map content and constraints for icon dimensions for a particular map scheme. The icon creation currently does not rely on map data. Therefore, it works without online connection.

Asset types for loading icons.

A closure of this type can be provided as a callback to be invoked when an icon is received from the IconProvider in the UIImage format. The callback provides information about the loaded icon, or an error if one occurred.

Error which indicates why an icon could not be retrieved.

Image format.

A factory of Style objects from styles defined in JSON format. For more details see Custom Layer Style Reference in the documentation.

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

Specifies type of interpolation performed between keyframes.

Determines the cap (line ending) style.

Line tile data source allows the rendering engine access to user managed data sets of geodetic lines and their attributes through a LineTileSource.

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

A source of geodetic line tiles. Lines provided by an implementation must be clipped to the boundaries of the requested tile. The implementations must be thread-safe.

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

Result handler of a load tile request.

Graphical object to represent the location of the user on the map.

It is either a green dot for pedestrian style or a triangular arrow for vehicle navigation style. This style can be changed by LocationIndicator.locationIndicatorStyle

The location is made available to an instance of this class by calling LocationIndicator.updateLocation(Location) or LocationIndicator.updateLocation(Location, MapCameraUpdate).

Use LocationIndicator.enable(...) to add this object to the map and LocationIndicator.disable(...) to remove it.

Note: The LocationIndicator is always rendered at a fixed altitude near 0. Changing the MapCamera to look at geographic coordinates with an altitude that is higher can cause the following behavior: If the MapCamera angle is tilted and altitude is too high, the LocationIndicator can unexpectedly disappear from the viewport due to the new perspective.

Protocol for handling long-press gestures. Long-press gesture occurs after tapping and holding the finger for a long time on the screen.

A visual representation of an arrow on the map. It consists of a tail - a polyline with an arbitrary number of points - and a head at its end.

The map arrows are only visible on zoom levels >= 13.

Altitude component of GeoPolyline‘s vertices is ignored.

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.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(...).

An animation that can be applied to a MapCamera. Creation is done via MapCameraAnimationFactory.

Factory for creating MapCameraAnimation objects to change map’s camera over time.

Protocol for objects that want to get updates whenever the map is redrawn after camera parameters change.

Stores keyframes for interpolation of a camera property using a specific easing function and interpolation mode. Can only hold keyframes of a single type.

Controls constraints on map camera parameters.

When constraints are set, they are enforced for current camera state and for all future changes to the camera.

When setting, limits are applied on next rendering loop.

An update that can be applied to the map camera. Creation is done via MapCameraUpdateFactory.

Factory for creating MapCameraUpdate to change map’s camera.

For some factory methods you can apply an additional padding in pixels by setting a viewRectangle parameter based on the current size of the map view:

let leftPaddingInPixels = 5
let rightPaddingInPixels = 5
let topPaddingInPixels = 5
let bottomPaddingInPixels = 5
let horizontalPaddingInPixels = leftPaddingInPixels + rightPaddingInPixels
let verticalPaddingInPixels = topPaddingInPixels + bottomPaddingInPixels

let origin = Point2D(leftPaddingInPixels, topPaddingInPixels)
let sizeInPixels = Size2D(width: mapView.viewportSize.width - horizontalPaddingInPixels, height: mapView.viewportSize.height - verticalPaddingInPixels)
let paddedViewRectangle = Rectangle2D(origin: origin, size: sizeInPixels)

The origin indicates the top-left corner of the rectangle. An origin of (0, 0) indicates also the top-left corner of the map’s viewport.

Type representing map content categories.

Provides settings regarding map data which are applied globally to all map views. The settings can already be changed before a map view instance is created.

Content types supported by the map.

MapContext is the rendering engine and the context in which virtual geographic maps get rendered.

It runs the render loop or offers the means for the user to run a custom one.

Data sources, assets and virtual maps can be attached to the context. A virtual map can only render data from sources attached to the same context.

The graphics backend to be used by the engine can be choosen by the user or a platform suitable one can be automatically selected internally. Only one graphics backend can be active and once selected it cannot be changed.

Represents various errors that could occur from map related operations.

Holds constants for map features, to be used with MapScene.enableFeatures(...) and MapScene.disableFeatures(...).

See MapFeatureModes for constants representing feature modes.

Holds constants for map feature modes, to be used with MapScene.enableFeatures(...).

Use MapFeatureModes.defaultMode to enable a feature with its default mode.

Note: The default mode is defined by the currently loaded map scene configuration and may vary per MapScheme. The currently active features and modes can be inspected using MapScene.getActiveFeatures(...) after the scene is loaded.

See MapFeatures for constants representing the feature names.

Used to detect when the map becomes idle or busy.

Map is considered busy when its state changes (for example as a result of camera manipulation) and/or when it requires a redraw (for example, as a result of map data being downloaded).

Map is considered idle when current state is fully rendered and no further redraws are necessary.

Represents a drawable resource that can be used by a MapMarker, MapMarker3D or MapImageOverlay to be shown on the map. Supported formats are listed in ImageFormat. SVG format allows custom fonts in text using font-family attribute by prior registration via AssetsManager.registerFont.

It is recommended to associate a resource with a single MapImage instance in order to enable resource sharing and reduce the amount of needed memory.

MapImageOverlay is used to draw images over the map, at a view coordinate inside the map viewport.

The image to be displayed is represented by a MapImage object. By default, the overlay is centered on the given view coordinate.

The resulting viewport area covered by the overlay is computed out of the overlay’s view coordinate, the anchor point and the image size. The overlay subareas that fall outside of the map viewport get clipped.

To display the map overlay, it needs to be added to the scene using MapScene.addMapImageOverlay(...). To stop displaying it, remove it from the scene using MapScene.removeMapImageOverlay(...).

Stores keyframes for interpolation of a map item property using a specific easing function and interpolation mode.

The keyframe track object is used to create animations, see MapMarkerAnimation and MapPolylineAnimation.

Base class to represent visual style of particular map items.

Interface for managing a map layer. A map layer can be created by using the MapLayerBuilder. At creation, the layer gets added to a map. The layer gets removed from the map upon instance destruction.

MapLayerBuilder is used to add layers to a map to visualise a dataset in a programmatic way without defining it upfront in the configuration files.

For example, after loading a scene configuration file, the renderer is setup to draw layers in the following order:

• background
• water
• roads:outline
• roads
• labels

Rendering order of elements in a single map layer can be controlled with categories. Layer names are unique, and category names have to be unique within a layer. The layer’s default, main category is unnamed.

The concept of ‘category’ is tightly linked to styling. The idea behind category is that one should be able to style separately elements in a map layer. Take, for instance, roads. If one wants to style separately the bridges it will create a category ‘bridges’ and style it accordingly in the style file. If the user does not intend to or cannot style elements of the layer differently then it should opt for a layer with only the default category (e.g. for a raster layer, only the default category makes sense, since the layer has no other stylable elements apart from the raster image).

A new layer called ‘zone’ and its category ‘background’ can be added dynamically so that the rendering order gets modified in the following way:

• background
• water
• zone:background
• zone
• roads:outline
• roads
• labels

This could be achieved with the help of the MapLayerPriorityBuilder and the MapLayerBuilder as in the following example:

  let layerPriority = MapLayerPriorityBuilder()
     .renderedAfterLayer(named: "water") // places main category after 'water'
     .withCategory("background")
     .renderedAfterLayer(named: "water") // places 'background' category after 'water' and before the
                                         // layer's main category.
     .build();

  let layer = MapLayerBuilder()
     .withDataSource(named: "DataSourceName", contentType: MapContentType.line)
     .forMap(map)
     .withName("zone")
     .withPriority(layerPriority)
     .build();

In case no layer priority or an empty one is provided, or if a reference layer-category pair is not present in the rendering order, the layer is going to be rendered last with respect to the rendering order at the time of its creation.

Due to current limitations, the MapLayerPriority assignment is not implemented for point map layers. All labels will be rendered within the “labels” layer, defined in the scene configuration file. By default, all labels rendered by a point map layer are rendered last and no overlapping is allowed. The following categories can be used to have a different behaviour:

• ‘custom-labels’ A label should be rendered first, is allowed to overlap with other labels of the same category and block map labels.
• ‘custom-labels-no-self-overlap’ A label should be rendered after ‘custom-labels’, is not allowed to overlap with other labels of the same categoty and block map labels.
• ‘custom-labels-overlap-all’ A label should be rendered last, is allowed to overlap all predefined categories, also map labels. These categories are configured accordingly in the basic map scene configurations. Category assignment to features can be done in the style based on data attributes. The category assignment can be done for all types of content: point, line, polygon.

MapLayerPriority class. Instances are configured and created via a MapLayerPriorityBuilder.

MapLayerPriorityBuilder is an interface used to define the rendering priority of a layer and its categories, relative to other layers or layer-category pairs.

Map layers are rendered in an order according to specified priorities. Rendering order of elements in a single map layer can be controlled with categories. Layer names are unique, and category names have to be unique within a layer. The layer’s default, main category is unnamed.

The concept of ‘category’ is tightly linked to styling. The idea behind category is that one should be able to style separately elements in a map layer. Take, for instance, roads. If one wants to style separately the bridges it will create a category ‘bridges’ and style it accordingly in the style file. If the user does not intend to or cannot style elements of the layer diffenrently then it should opt for a layer with only the default category (e.g. raster layer).

One way to define layers’ priorities is by using a layer priority list in the scene configuration.

For example, a priority list in a scene configuration could define:

• background
• water
• roads:outline
• roads
• labels

This means layer “background” is rendered first. Next up is layer “water”. Then category “outline” of layer “roads”, followed by the main category of layer “roads”. Layer “labels” is then rendered last.

Now let’s consider a newly created layer ‘zone’ and its categories:

• zone
• zone:background
• zone:lines-outline
• zone:lines

The user wants to alter the rendering order so that it looks like:

• background
• water
• zone:background
• zone
• road:outline
• road
• zone:lines-outline
• zone:lines
• labels

This could be achieved with the help of the MapLayerPriorityBuilder and a sequence of calls to its renderedBeforeLayer() and renderedAfterLayer() member functions.

Note that the order of calls matters and one can use a previously defined layer or category as a reference:

  let zoneLayerPriority = MapLayerPriorityBuilder()
      .renderedAfterLayer(named: "water")     // places "zone" after "water"
                                              // in the rendering order
      .withCategory(named: "background")
      .renderedAfterLayer(named: "water")     // places "zone:background" after "water"
                                              // in the rendering order and thus shifts
                                              // "zone" to be rendered later
      .withCategory(named: "lines-outline")
      .renderedAfterLayer(named: "road")      // places "zone:lines-outline" after "road"
                                              // in the rendering order
      .withCategory(named: "lines")
      .renderedAfterLayer(named: "zone", categoryName: "lines-outline") // places "zone:lines" after
                                                                        // "zone:lines-outline" in the rendering order
      .build();

  zoneLayer.setPriority(zoneLayerPriority);  // applies the priority to the zone layer
                                            // and its categories in one single operation.

In case an empty MapLayerPriority without any ordering commands is built, it is assumed that the target layer is going to be rendered last.

Due to a current limitation for point map layers, the mentioned APIs to control the rendering order are not implemented. All labels will be rendered within the “labels” layer, defined in the scene configuration file. By default, all labels rendered by a point map layer are rendered last and no overlapping is allowed. The following categories can be used to have a different behaviour:

• ‘custom-labels’ A label should be rendered first, is allowed to overlap with other labels of the same category and block map labels.
• ‘custom-labels-no-self-overlap’ A label should be rendered after ‘custom-labels’, is not allowed to overlap with other labels of the same categoty and block map labels.
• ‘custom-labels-overlap-all’ A label should be rendered last, is allowed to overlap all predefined categories, also map labels. These categories are configured accordingly in the basic map scene configurations. Category assignment to features can be done in the style based on data attributes. The category assignment can be done for all types of data: points, lines, polygons.

Provides a mapping between a MapLayer map measure to datasource storage level.

A layer’s visibility along a zoom level range. The range is half open - [minimumZoomLevel, maximumZoomLevel), the given maximum value is not contained in the range.

Groups map markers and enables their clustering to reduce visual clutter when there are many of them in a small area.

The markers that are close to each other are replaced by a single cluster marker. Cluster groups are generated based on geographical distance between objects, not based on screen space collision. Hence it is possible, that cluster markers can overlap.

The markers can be added to a cluster or to a scene, but not to both. To display the cluster on the map, add it to the scene using MapScene.addMapMarkerCluster(...). The display of a cluster is only guaranteed in case its origin is within the viewport. At the moment, this is a known limitation that mostly affects clusters which are visually large and cover a sizeable part of the viewport.

Markers part of the cluster with opacity set to zero are still on the map and are considered for picking and clustering.

A map measure range.

Interface represents descriptor of a pickable map object.

The map projection used for rendering.

Manage the lights and their attributes in a scene.

Represents the configuration options for loading a map scene. This class combines both the scene source (MapScheme or configuration file) and optional settings like features, watermark style and overriding map style.

It is left empty intentionally. Use MapSceneLoadOptionsBuilder to create instances of this class.

Note: 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.

Builder for creating MapSceneLoadOptions instances. This builder ensures that either a MapScheme or a configuration file is set, but not both.

Note: 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.

MapMarker is used to draw images on the map, for example to mark a specific location. By default, the marker is centered on the given geographic coordinates. Markers keep their size regardless of the current zoom level of the map view.

The image to be displayed is represented by MapImage object. For performance reasons, it is highly recommended to reuse a single instance of the image when creating multiple identical markers.

To display the map marker, it needs to be added to the scene using MapScene.addMapMarker(...). To stop displaying it, remove it from the scene using MapScene.removeMapMarker(...).

The display of a map marker is only guaranteed in case its origin is within the viewport. At the moment, this is a known limitation that mostly affects map markers which are visually large and cover a sizeable part of the viewport.

Note: Due to technical limitations using the MapMarkers API to add a very large number of markers (several thousands, especially 10000+) is not recommended. Adding this many markers will have a negative impact on the performance leading to stuttering of the app and lower frame rates. To work around this limitation the following approach can be used: Register to map camera updates using MapCamera.addDelegate(...). Query the bounding box of the camera viewport using MapCamera.boundingBox (it may be extended) and then use the method GeoBox.contains(GeoCoordinates) in combination with MapCamera.State.distanceToTargetInMeters to determine which MapMarkers are actually visible to the user in the current camera viewport and thus need to be added to the map.

Represents a 3D shape drawn on the map at specified geodetic coordinates.

It can have a solid color or be textured, depending on the data from MapMarker3DModel.

By default, a 3D marker is drawn on top of all map content, including 3D map elements like extruded buildings or 3D landmarks. This can be changed by enabling depth check using MapMarker3D.isDepthCheckEnabled.

The display of a 3D marker is only guaranteed in case its origin is within the viewport. At the moment, this is a known limitation that mostly affects a 3D marker that is visually large and covers a sizeable part of the viewport.

Sizing and scaling

Two aspects determine how big the MapMarker3D will be on the screen and how will it behave when the map is zoomed in and out.

The first, and most impactful is RenderSize.Unit, which specifies how the vertex coordinates of the 3D model are interpreted. Most importantly, it specifies whether the 3D model is placed in world or screen coordinate space.

RenderSize.Unit.meters will make the 3D model use world coordinate space, meaning that it will change size together with the map when it is zoomed in and out.

RenderSize.Unit.pixels makes the 3D model use screen coordinate space, meaning that it will have constant size on the screen regardless of how the map zoom changes. So a simple 10 by 10 (in model space) rectangle will have a size of 10 by 10 pixels on the screen.

RenderSize.Unit.densityIndependentPixels is similar to pixels, but the resulting size will take into account the pixel density of the display, meaning that physical size on the screen will be approximately the same regardless of the size or resolution of the display.

The second aspect that determines size of MapMarker3D is scale. It can be specified at construction time and can be changed later at any time using MapMarker3D.scale.

Modifying at runtime

A 3D marker can be moved around a map by updating its coordinates using MapMarker3D.coordinates.

Altitude component of the coordinates, if set, controls 3D marker’s elevation above ground. If not set, the 3D marker is placed at ground level.

Its orientation is specified by bearing, pitch and roll and can be changed by using MapMarker3D.bearing, MapMarker3D.pitch and MapMarker3D.roll.

Flat marker

A flat marker is a special case of a 3D marker, where the 3D shape being drawn is a simple textured rectangle. In essence it’s an image drawn “on the ground”. Such 3D marker can be conveniently created using MapMarker3D.init(GeoCoordinates, MapImage, Double, RenderSize.Unit) constructor. Of course, once created, it can be rotated to face any direction.

Represents a 3D model that can be used by a MapMarker3D to be shown on the map. Geometry of 3D marker can be provided in form of a Wavefront OBJ file as specified in http://www.martinreddy.net/gfx/3d/OBJ.spec or as mesh built via MeshBuilder.

1. Creating MapMarker3DModel from OBJ file

For OBJ files, HERE SDK only supports the following set of features of the OBJ specification:

• Triangle Meshes
• Following vertex attributes must be present:
  • Vertex Position
  • Vertex Normal
  • Texture Coordinates
  • Geometry must be indexed (contain an Index Buffer)
  • Face element

HERE SDK does not support:

• Multi Texturing
• Materials (mtllib [external .mtl file name] )
  • Lines
  • Higher Order Surfaces
  • Vendor specific extensions

For supported texture formats, HERE SDK allows the following formats to be specified: JPG, PNG, GPU compressed texture formats: ECT1 (OpenGL only), YUV, ASTC, KTX.

2. Creating MapMarker3DModel programatically

A 3D mesh can be specified programatically using MeshBuilder and passed to MapMarker3DModel constructor. This method supports creating a mesh from quads and triangles. Textured geometry is also supported, the mesh faces need to have texture coordinates and a texture file needs to be passed along with the mesh to MapMarker3DModel constructor.

An animation that can be applied to the MapMarker object.

A map measure. Check MapCamera for more details on each supported measure.

Represents a render size, described as map measure dependent values.

A visual representation of a polygon on the map. Can be used to visualize areas of all shapes and sizes.

The geometry to be visualized is represented by an instance of GeoPolygon. To display circular areas (for example, a position accuracy indicator) use a GeoPolygon created from a GeoCircle using GeoPolygon.init(GeoCircle).

Note:

• The polygon shape should not cover more than half of the globe, otherwise unexpected results may occur.
• Polygons which are self-intersecting are not supported and may lead to render artifacts.
• The inner boundaries (holes) specified in the GeoPolygon are ignored.

A visual representation of a line on the map.

The geometry to be visualized is represented by an instance of GeoPolyline.

Altitude component of GeoPolyline‘s vertices is ignored.

An animation that can be applied to the MapPolyline object.

A class representing a map pick result.

Represents a map scene and exposes the functionality to manipulate its content.

Map schemes

The content of the displayed map and how it looks is specified by a MapScheme which is set when loading a scene with MapScene.loadScene(MapScheme, MapScene.LoadSceneCompletionHandler?). It is also possible to load your own custom map scheme from a file bundled with your application. Supported file formats are:

• JSON (file extension ‘.json’; e.g. ‘my_custom_style.json’)
• ZIP archive (file extension ‘.zip’; e.g. ‘my_custom_style.zip’), with the following archive structure:
  • root folder: any, not empty (e.g. ‘my_custom_style’)
  • JSON configuration: ‘/style.json’
  • custom assets folder: ‘/assets’

Map features

Different map schemes offer different sets of features, for example showing traffic or 3D buildings. Some features have multiple modes of operation, but most have only one. MapScene.getSupportedFeatures(...) can be used to check what features and modes are supported for the current scene. Features can be enabled using MapScene.enableFeatures(...) and disabled with MapScene.disableFeatures(...). Checking which features are currently enabled can be done using MapScene.getActiveFeatures(...). For convenience, MapFeatures and MapFeatureModes hold constants for feature and mode names.

Since version 4.15.0, map features cannot be controlled using MapScene.setLayerVisibility(...), since MapScene.setLayerVisibility(...) controls only visibility of the layers which are corresponding to the features enabled either by MapScene.enableFeatures(...) or enabled by default for the scene.

Map layers

A map scheme is organized in layers, which can be controlled using MapScene.setLayerVisibility(...). It’s possible to change the visibility state of any map layer as long as the name is known.

Layer visibility settings persist between scene reloading.

User content

User generated content can be visualised on the map using MapPolyline, MapPolygon, MapMarker, MapMarkerCluster, MapArrow, MapMarker3D and MapImageOverlay (collectively referred to as “map items”). Those can be added to and removed from the scene by respective add and remove methods. The render order of the map items is according to the list above. The order of objects within the same type can be controlled using the drawOrder property of each object.

Be careful when adding a very large number of map items as this can have a negative impact on the performance of the app. To work around this limitation the following approach can be used: Register to map camera updates using MapCamera.addDelegate(...). Query the bounding box of the camera viewport using MapCamera.boundingBox (it may be extended) and then use the method GeoBox.contains(GeoCoordinates) in combination with MapCamera.State.distanceToTargetInMeters to determine which map items are actually visible to the user in the current camera viewport and thus need to be added to the map.

Represents the preconfigured map schemes bundled with the SDK.

Represents the available public API from MapView.

A view that displays a map. Note: Before using this class, SDKNativeEngine must be already initialized.

Provides a mechanism for observing a lifecycle of a map view and/or implementing components whose lifecycle needs to be linked with that of a map view.

Storing the map view in a strong reference is strongly discouraged, as that will create a reference cycle and prevent map view from being released.

A MapView is using a CAMetalLayer

to render its content.

Options used for initialization of map view

Material reflectivity properties are used to enable per‑pixel lighting for supported map objects (e.g. LocationIndicator markers and their halo).

Lighting OFF vs ON

By default (when no MaterialReflectivity is assigned) objects are rendered “unlit” (emissive): their texture / color appears at a constant brightness, unaffected by scene lights. Assigning a MaterialReflectivity instance to an object that supports it (e.g. LocationIndicator.materialReflectivity) automatically enables lighting for this object and all its internal components. Clearing (setting the property to nil) disables lighting again and restores the unlit appearance.

Factors

Both factors are expected to be within [0.0, 1.0]. Values outside this range are allowed but may produce exaggerated results or be clamped by future implementations. Typical useful ranges:

• ambientFactor: 0.0 – 0.4 (higher values flatten the shading and reduce directional contrast)
• diffuseFactor: 0.5 – 1.0 (lower values dim the object under directional light)

Note: 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.

Represents a mesh in 3D space. Such meshes are built using MeshBuilder.

The class is not offering any methods, as its data is only meant to be consumed internally when being passed to MapMarker3DModel constructor.

Builder for meshes. Such meshes can contain different kinds of primitives, like quads or triangles. Both primitives support adding texture coordinates that are mapped to the corners of the primitives. See TriangleMeshBuilder and QuadMeshBuilder for more details.

Note: Normals cannot be set as they are not necessary when using the MeshBuilder.

Example how to build a cube using QuadMeshBuilder

let cube = MeshBuilder()
    .quad(a: Point3D(x: 0.5, y: 0.5, z: 0.5),
          b: Point3D(x: -0.5, y: 0.5, z: 0.5),
          c: Point3D(x: 0.5, y: -0.5, z: 0.5),
          d: Point3D(x: -0.5, y: -0.5, z: 0.5))
    .quad(a: Point3D(x: -0.5, y: 0.5, z: -0.5),
          b: Point3D(x: 0.5, y: 0.5, z: -0.5),
          c: Point3D(x: -0.5, y: -0.5, z: -0.5),
          d: Point3D(x: 0.5, y: -0.5, z: -0.5))
    .quad(a: Point3D(x: 0.5, y: 0.5, z: -0.5),
          b: Point3D(x: 0.5, y: 0.5, z: 0.5),
          c: Point3D(x: 0.5, y: -0.5, z: -0.5),
          d: Point3D(x: 0.5, y: -0.5, z: 0.5))
    .quad(a: Point3D(x: -0.5, y: 0.5, z: 0.5),
          b: Point3D(x: -0.5, y: 0.5, z: -0.5),
          c: Point3D(x: -0.5, y: -0.5, z: 0.5),
          d: Point3D(x: -0.5, y: -0.5, z: -0.5))
    .quad(a: Point3D(x: -0.5, y: 0.5, z: 0.5),
          b: Point3D(x: 0.5, y: 0.5, z: 0.5),
          c: Point3D(x: -0.5, y: 0.5, z: -0.5),
          d: Point3D(x: 0.5, y: 0.5, z: -0.5))
    .quad(a: Point3D(x: 0.5, y: -0.5, z: 0.5),
          b: Point3D(x: -0.5, y: -0.5, z: 0.5),
          c: Point3D(x: 0.5, y: -0.5, z: -0.5),
          d: Point3D(x: -0.5, y: -0.5, z: -0.5))
    .build()

Protocol for handling pan gestures. Pan gesture occurs when a finger is moving on the screen.

A class that contains possible results from picking map content on the map scene.

Carries results from the picking of map items on the map scene.

Protocol for handling pinch rotate gestures. Pinch rotate gesture occurs when two fingers are on the screen and at least one of them moves.

Represents a geodetic point with custom attributes. Can be created using a PointDataBuilder.

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

Point data accessor used for manipulating points that are part of a PointDataSource.

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

Builder of PointData instances.

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

Point data source allows the rendering engine access to the user provided geographical locations and their attributes.

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

Builder of points data source.

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

Point tile data source allows the rendering engine access to user managed data sets of geographical locations and their attributes through a PointTileSource.

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

A source of geodetic point tiles. The implementations must be thread-safe.

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

Result handler of a load tile request.

A Point2D keyframe. A keyframe consists of a value and an animation duration.

Represents a geodetic polygon with custom attributes. Can be created using a PolygonDataBuilder.

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

Polygon data accessor used for manipulating polygons that are part of a PolygonDataSource.

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

Builder of PolygonData instances.

The builder can create PolygonData instances for polygons with an outer boundary and optionally one or more inner boundaries (holes).

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

Polygon data source allows the rendering engine access to the user provided polygons geometry and their attributes.

Polygon segments are rendered following the shortest path between their end points.

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

Builder of the polygons data source.

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

Polygon tile data source allows the rendering engine access to user managed data sets of geodetic polygons and their attributes through a PolygonTileSource.

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

A source of geodetic polygon tiles. Polygons provided by an implementation must be clipped to the boundaries of the requested tile. The implementations must be thread-safe.

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

Result handler of a load tile request.

Builder for a single quad.

Data source to load map layers using a raster image format (jpg, png). The example below illustrates how to create a raster data source and how to link it to a newly created map layer.

  let rasterDataSource = RasterDataSource(mapContext, rasterDataSourceConfig)

  let layer = MapLayerBuilder()
     // The name and the type of the data source have to be provided.
     // In our case, the name of the raster data source is in rasterDataSourceConfig.
     .withDataSource(named: rasterDataSourceConfig.name, contentType: MapContentType.rasterImage)
     .forMap(map)
     .withName("rasterLayer")
     .build();

Called on the main thread after fromJsonFile() method finishes loading the configuration.

Configuration update for a RasterDataSource.

Delegate for RasterDataSource events.

Raster data source error codes.

A source of raster tiles. The implementations must be thread-safe. Note: This is a beta release of this feature, so there could be a few bugs and unexpected behavior. Related APIs may change for new releases without a deprecation process.

Result handler of a load tile request.

Contains the information required to create a road shield image.

Represents size of visual elements drawn on the map.

A ScalarKeyframe consists of a scalar value (e.g,: distance in meters) and an animation duration.

Do not use this. This class is used to initialize internals of the SDK.

The shadow quality. Controls the quality of the shadow cascade (i.e. the size of the shadow maps and the cascade count), which is shared by all views.

A style that defines the visual appearance of map rendered features. A Style can be created using a JsonStyleFactory.

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

Protocol for handling tap gestures. Tap gesture occurs after tapping on the screen.

A calculator of geodetic bounds for tiles identified by keys generated in a particular tiling scheme (TilingScheme).

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

A source of tiles. The implementations must be thread-safe.

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

Tile data version.

Delegate for TileSource events.

Handle of a load request.

Tile metadata.

Key of a data source tile. Note: This is a beta release of this feature, so there could be a few bugs and unexpected behavior. Related APIs may change for new releases without a deprecation process.

Factory for generating a TileUrlRequestHandler utilized in creating a tile URL.

Provides the URL as String for the given tile coordinates and storage level.

The first and second parameters correspond to the X and Y coordinates of the tile, respectively, and have values ranging from 0 to 2^level − 1. The third parameter indicates the level of the tile.

List of available data tiling schemes. X axis has the origin at -180 longitude and is increasing in east direction. Y axis has the origin at max latitude and is increasing in south direction. For half quad tree schemes, only the uppper half of the tree is used.

A translucent layer group that can be the target for MapLayerPriorityBuilder.inGroup(...). Currently, only custom line layers can be added to a translucent layer group. Custom line layers in a translucent layer group are rendered in an offscreen translucent pass so that overlapping translucent line geometry is not alpha blended with itself. At creation, the layer group gets added to a map. The layer group gets removed from the map upon instance destruction and any layer (categories) still in the group are not rendered anymore, therefore it is recommended to keep a group alive as long as layers using the group are alive and in use.

Conceptual example to place line layers into a translucent group:

 // Create a translucent group with a unique name and a render priority
 let groupPriority = MapLayerPriorityBuilder().renderedLast().build()
 let group = TranslucentMapLayerGroup(name: "TranslucentGroupName", map, groupPriority)

 // Create a line layer to be rendered as part of the translucent group
 let lineLayerPriority = MapLayerPriorityBuilder()
     .inGroup("TranslucentGroupName") // places the line layer into the group
     .renderedFirst()                 // to be rendered first when the group is rendered
     .withCategory("SomeCategory")    // places the line layer category 'SomeCategory'
     .inGroup("TranslucentGroupName") // into the group
     .renderedLast()                  // to be rendered last when the group is rendered
     .build()

 let lineLayer = MapLayerBuilder()
     .withDataSource(named: "DataSourceName", contentType: MapContentType.line)
     .forMap(map)
     .withName("LineLayerName")
     .withPriority(lineLayerPriority)
     .withStyle(translucentLineStyle) // E.g. "technique": "line" ... "color": "#FFFFFF80"
     .build()

 // Create a second line layer to be rendered as part of the translucent group
 let secondLineLayerPriority = MapLayerPriorityBuilder()
     .inGroup("TranslucentGroupName")      // places the second line layer into the group
     .renderedBeforeLayer("LineLayerName") // to be rendered before first layer
                                           // when the group is rendered
     .build()

 let secondLineLayer = MapLayerBuilder()
     .withDataSource(named: "SecondDataSourceName", contentType: MapContentType.line)
     .forMap(map)
     .withName("SecondLineLayerName")
     .withPriority(secondLineLayerPriority)
     .withStyle(secondTranslucentLineStyle) // E.g. "technique": "line" ... "color": "#FFFFFF80"
     .build()

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

Builder for a single triangle.

Protocol for handling two finger pan gestures. Two finger pan gesture occurs when two fingers are on the screen and both of them are moving vertically.

Protocol for handling two finger tap gestures. Two finger tap gesture occurs after tapping on the screen with two fingers.

Represents the visibility state of an SDK map view’s object.

Defines the style of the HERE watermark logo. The dark watermark should be used for custom schemes that are brighter (like daytime) and the light watermark for darker custom schemes (like night or satellite based).