MapScene

public class MapScene
extension MapScene: NativeBase
extension MapScene: Hashable

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.

  • Called on the main thread after loadScene() method finishes loading the scene.

    Declaration

    Swift

    public typealias LoadSceneCompletionHandler = (_ loadSceneError: MapError?) -> Void

    Parameters

    loadSceneError

    The load scene error

  • Controls lights present in the scene. Provides access to a MapSceneLights instance that controls the lights in the scene.

    The behavior of the returned MapSceneLights instance depends on the state of the scene:

    • If the scene is not loaded, the returned MapSceneLights instance will not contain any light settings, as lights are not loaded without a scene.
    • If the scene is loaded, the returned MapSceneLights instance reflects the current light settings of the loaded scene.

    Scene Change Behavior:

    • If the scene changes, the MapSceneLights instance will be updated to reflect the light settings of the new scene.
    • Any user-defined settings to MapSceneLights will be overridden by the new scene’s light settings when the scene changes.

    Error Handling:

    • If the scene is loaded and the loaded scene does not utilize or specify light settings:
      • If the lights are not present, the error callback may return a NO_LIGHTS state.

    Declaration

    Swift

    public var lights: MapSceneLights { get }

  • Filter for the map content to be picked.

    See more

    Declaration

    Swift

    public class MapPickFilter
    extension MapScene.MapPickFilter: NativeBase
    extension MapScene.MapPickFilter: Hashable

  • Asynchronously loads a map scene described by a specified map scheme. Any previous map scene config will be replaced. The loaded scene is cached and so any changes made to the scene files on disk might not get reflected on a successive call to this function. Instead the reloadScene API can handle such use-cases to force-update the scene.

    Map features enabled or disabled using MapScene.enableFeatures(...) and MapScene.disableFeatures(...) will be reset to defaults for the new scene configuration.

    The callback is called on the main thread.

    Declaration

    Swift

    public func loadScene(mapScheme: MapScheme, completion: MapScene.LoadSceneCompletionHandler?)

    Parameters

    mapScheme

    Map scheme.
    completion

    Optional callback that will receive the result of this operation.

  • Asynchronously loads a map scene described by a specified file in one of the supported formats. Any previous map scene config will be replaced.

    When loading the same file again, consider to call reloadScene() instead.

    Map features enabled or disabled using MapScene.enableFeatures(...) and MapScene.disableFeatures(...) will be reset to defaults for the new scene configuration.

    The callback is called on the main thread.

    Declaration

    Swift

    public func loadScene(fromFile configurationFile: String, completion: MapScene.LoadSceneCompletionHandler?)

    Parameters

    configurationFile

    Map scheme configuration file. It must contain the whole scene configuration. In case it contains references to other files, they have to be reachable under the paths specified in the main configuration file.
    completion

    Optional callback that will receive the result of this operation.

  • Asynchronously loads a map scene described by a specified file in one of the supported formats. The style of the HERE watermark matching the map scheme is specified. Any previous map scene config will be replaced.

    When loading the same file again, consider to call reloadScene() instead.

    Map features enabled or disabled using MapScene.enableFeatures(...) and MapScene.disableFeatures(...) will be reset to defaults for the new scene configuration.

    The callback is called on the main thread.

    Declaration

    Swift

    public func loadScene(fromFile configurationFile: String, watermarkStyle: WatermarkStyle, completion: MapScene.LoadSceneCompletionHandler?)

    Parameters

    configurationFile

    Map scheme configuration file. It must contain the whole scene configuration. In case it contains references to other files, they have to be reachable under the paths specified in the main configuration file.
    watermarkStyle

    The style for the HERE watermark, see WatermarkStyle.
    completion

    Optional callback that will receive the result of this operation.

  • Asynchronously loads a map scene using MapSceneLoadOptions.

    This is an unified API that supports loading from either a map scheme or configuration file, with optional feature and watermark configuration. It’s more efficient to load the scene with this function by specifying the list of enabled features and disabled features, compared to loading the scene first and enabling or disabling map features in the scene loading callback function.

    Configuration defaults are used for features that are not part of the enabled features or disabled features parameters. When a feature is in both the enabled and disabled lists, the feature is considered as requested to be enabled. If the same feature is present multiple times in the enabled list with different modes, then the feature is considered as requested to be enabled, but with an unspecified mode (any of the many specified in the enabled list).

    Any previous map scene config will be replaced. The callback is called on the main thread.

    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.

    Declaration

    Swift

    public func loadScene(options: MapSceneLoadOptions, completion: MapScene.LoadSceneCompletionHandler?)

    Parameters

    options

    Scene configuration options created using MapSceneLoadOptionsBuilder.
    completion

    Optional callback that will receive the result of this operation.

  • Adds a map polyline to this map scene.

    Declaration

    Swift

    public func addMapPolyline(_ mapPolyline: MapPolyline)

    Parameters

    mapPolyline

    The map polyline to be added to this map scene.

  • Adds map polylines to this map scene.

    Note: Due to technical limitations using the MapPolyline API to add a very large number of polylines (especially 1000+ also depending on their complexity) is not recommended. Adding this many polylines has a negative impact on the performance leading to stuttering of the app and lower frame rates. To work around this limitation add only map items which are in the current camera viewport. A guide on how to achieve this can be found towards the end of the MapScene class doc.

    Declaration

    Swift

    public func addMapPolylines(_ mapPolylines: [MapPolyline])

    Parameters

    mapPolylines

    The map polylines to be added to this map scene.

  • Removes a map polyline from this map scene.

    Declaration

    Swift

    public func removeMapPolyline(_ mapPolyline: MapPolyline)

    Parameters

    mapPolyline

    The map polyline to be removed from this map scene.

  • Removes map polylines from this map scene.

    Declaration

    Swift

    public func removeMapPolylines(_ mapPolylines: [MapPolyline])

    Parameters

    mapPolylines

    The map polylines to be removed from this map scene.

  • Removes all map polylines from this map scene.

    Declaration

    Swift

    public func removeAllMapPolylines()

  • Adds a map arrow to this map scene.

    Note: Due to technical limitations using the MapArrow API to add a very large number of arrows (especially 1000+ also depending on their complexity) is not recommended. Adding this many arrows has a negative impact on the performance leading to stuttering of the app and lower frame rates. To work around this limitation add only map items which are in the current camera viewport. A guide on how to achieve this can be found towards the end of the MapScene class doc.

    Declaration

    Swift

    public func addMapArrow(_ mapArrow: MapArrow)

    Parameters

    mapArrow

    The map arrow to be added to this map scene.

  • Removes a map arrow from this map scene.

    Declaration

    Swift

    public func removeMapArrow(_ mapArrow: MapArrow)

    Parameters

    mapArrow

    The map arrow to be removed from this map scene.

  • Adds a map marker to this map scene. Adding the same marker instance multiple times has no effect. Adding a marker that is already part of a map marker cluster has no effect.

    Declaration

    Swift

    public func addMapMarker(_ marker: MapMarker)

    Parameters

    marker

    The marker to be added to this map scene.

  • Adds multiple map markers to this map scene. Adding the same marker instances multiple times has no effect. Adding markers that are already part of a map marker cluster has no effect.

    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 add only map items which are in the current camera viewport. A guide on how to achieve this can be found towards the end of the MapScene class doc.

    Declaration

    Swift

    public func addMapMarkers(_ markers: [MapMarker])

    Parameters

    markers

    The list of markers to be added to this map scene.

  • Removes a map marker from this map scene. Removing a marker instance that is not a part of this scene or belongs to a marker cluster has no effect.

    Declaration

    Swift

    public func removeMapMarker(_ marker: MapMarker)

    Parameters

    marker

    The marker to be removed from this map scene.

  • Removes multiple map markers from this map scene. Removing marker instances that are not a part of this scene or belong to a marker cluster has no effect.

    Declaration

    Swift

    public func removeMapMarkers(_ markers: [MapMarker])

    Parameters

    markers

    The list of markers to be removed from this map scene.

  • Removes all map markers from this map scene.

    Declaration

    Swift

    public func removeAllMapMarkers()

  • Adds a map marker cluster to the map. Either the contained individual map markers or the cluster markers will be displayed. Adding the same map marker cluster instance multiple times has no effect.

    Declaration

    Swift

    public func addMapMarkerCluster(_ cluster: MapMarkerCluster)

    Parameters

    cluster

    The marker cluster to be added to this map scene.

  • Removes a map marker cluster from the map. Removing a map marker cluster that is not on this scene has no effect.

    Declaration

    Swift

    public func removeMapMarkerCluster(_ cluster: MapMarkerCluster)

    Parameters

    cluster

    The marker cluster to be removed from this map scene.

  • Adds a 3D map marker to this map scene. Does nothing if the marker instance was already added to the scene.

    Note: Due to technical limitations using the MapMarker3D API to add a very large number of 3D markers (especially 500+ also depending on the complexity of the 3D object) is not recommended. Adding this many 3D markers has a negative impact on the performance leading to stuttering of the app and lower frame rates. To work around this limitation add only map items which are in the current camera viewport. A guide on how to achieve this can be found towards the end of the MapScene class doc.

    Declaration

    Swift

    public func addMapMarker3d(_ marker: MapMarker3D)

    Parameters

    marker

    The marker to be added to this map scene.

  • Adds multiple 3D map markers to this map scene. Adding the same 3D marker instances multiple times has no effect.

    Note: Due to technical limitations, using the MapMarkers3D API to add a very large number of 3D markers (especially 500+) 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 add only map items which are in the current camera viewport. A guide on how to achieve this can be found towards the end of the MapScene class doc.

    Declaration

    Swift

    public func addMapMarkers3d(_ markers: [MapMarker3D])

    Parameters

    markers

    The list of 3D markers to be added to this map scene.

  • Removes a 3D map marker from this map scene. Removing a marker instance that is not on this scene has no effect.

    Declaration

    Swift

    public func removeMapMarker3d(_ marker: MapMarker3D)

    Parameters

    marker

    The marker to be removed from this map scene.

  • Removes multiple 3D map markers from this map scene. Removing marker instances that are not a part of this scene has no effect.

    Declaration

    Swift

    public func removeMapMarkers3d(_ markers: [MapMarker3D])

    Parameters

    markers

    The list of 3D markers to be removed from this map scene.

  • Removes all 3D map markers from this map scene.

    Declaration

    Swift

    public func removeAllMapMarkers3d()

  • Adds a map polygon to this map scene.

    Note: Due to technical limitations using the MapPolygon API to add a very large number of polygons (especially 1000+ also depending on their complexity) is not recommended. Adding this many polygons has a negative impact on the performance leading to stuttering of the app and lower frame rates. To work around this limitation add only map items which are in the current camera viewport. A guide on how to achieve this can be found towards the end of the MapScene class doc.

    Declaration

    Swift

    public func addMapPolygon(_ mapPolygon: MapPolygon)

    Parameters

    mapPolygon

    The map polygon to be added to this map scene.

  • Adds multiple map polygons to this map scene.

    Note: Due to technical limitations using the MapPolygon API to add a very large number of polygons (especially 1000+ also depending on their complexity) is not recommended. Adding this many polygons has a negative impact on the performance leading to stuttering of the app and lower frame rates. To work around this limitation add only map items which are in the current camera viewport. A guide on how to achieve this can be found towards the end of the MapScene class doc.

    Declaration

    Swift

    public func addMapPolygons(_ mapPolygons: [MapPolygon])

    Parameters

    mapPolygons

    The map polygons to be added to this map scene.

  • Removes a map polygon from this map scene.

    Declaration

    Swift

    public func removeMapPolygon(_ mapPolygon: MapPolygon)

    Parameters

    mapPolygon

    The map polygon to be removed from this map scene.

  • Removes multiple map polygon from this map scene.

    Declaration

    Swift

    public func removeMapPolygons(_ mapPolygons: [MapPolygon])

    Parameters

    mapPolygons

    The map polygons to be removed from this map scene.

  • Removes all map polygons from this map scene.

    Declaration

    Swift

    public func removeAllMapPolygons()

  • Adds a map image overlay to this map scene. Adding the same overlay instance multiple times has no effect.

    Declaration

    Swift

    public func addMapImageOverlay(_ overlay: MapImageOverlay)

    Parameters

    overlay

    The overlay to be added to this map scene.

  • Removes a map image overlay from this map scene. Removing an overlay instance that is not part of this scene has no effect.

    Declaration

    Swift

    public func removeMapImageOverlay(_ overlay: MapImageOverlay)

    Parameters

    overlay

    The overlay to be removed from this map scene.

  • Immediately changes the visibility of a specified map layer.

    Declaration

    Swift

    public func setLayerVisibility(layerName: String, visibility: VisibilityState)

    Parameters

    layerName

    The name of the map layer to be changed.
    visibility

    The new visibility state of the layer.

  • Gets map features that are currently active. Active features are features that are either enabled via a call to MapScene.enableFeatures(...) or that are enabled by default in the scene.

    The key to the resulting map is the name of the feature and the value is the active mode.

    Result is empty if scene has not been loaded.

    Declaration

    Swift

    public func getActiveFeatures() -> [String : String]

    Return Value

    The map of active features.

  • Gets features and all of their modes supported by the currently loaded scene configuration.

    The key to the resulting map is the name of the feature and the value is a list of modes for that feature.

    Result is empty if scene has not been loaded.

    Declaration

    Swift

    public func getSupportedFeatures() -> [String : [String]]

    Return Value

    The map of supported features and all their modes.

  • Enables specified map features. Those will become active after next map redraw, meaning that MapScene.getActiveFeatures(...) will return updated list of active features only after the redraw happens.

    Does not affect features that were not specified. Unsupported features are ignored.

    May cause the current map configuration to be reloaded.

    See MapFeatures for feature names and MapFeatureModes for feature mode names.

    Declaration

    Swift

    public func enableFeatures(_ features: [String : String])

    Parameters

    features

    The list of features to enable, key is the name of the feature (see MapFeatures), value specifies its mode (see MapFeatureModes).

  • Disables specified map features. Those will become inactive after next map redraw, meaning that MapScene.getActiveFeatures(...) will return updated list of active features only after the redraw happens.

    Does not affect features that were not specified. Unsupported features are ignored.

    May cause the current map configuration to be reloaded.

    See MapFeatures for feature names.

    Declaration

    Swift

    public func disableFeatures(_ features: [String])

    Parameters

    features

    The names of features to disable (see MapFeatures).

  • Asynchronously reloads the current map scene from file. This skips any cached data used internally and reloads the scene including any changes made to the (custom) map styles in JSON.

    MapFeature settings will be preserved.

    Internal optimization checks will be skipped to ensure all custom style changes are loaded. Therefore, calling this method may take slightly longer than calling one of the loadScene(..) overloads.

    Declaration

    Swift

    public func reloadScene()