MapScene Class Reference
- Last UpdatedJun 10, 2025
- 10 minute read
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.
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 = (MapError?) -> Void
Parameters
p0
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 }
-
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(...)
andMapScene.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 JSON file. Any previous map scene config will be replaced.
When loading the same JSON file again, consider to call
reloadScene()
instead.Map features enabled or disabled using
MapScene.enableFeatures(...)
andMapScene.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 JSON file. The style of the HERE watermark matching the map scheme is specified. Any previous map scene config will be replaced.
When loading the same JSON file again, consider to call
reloadScene()
instead.Map features enabled or disabled using
MapScene.enableFeatures(...)
andMapScene.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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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 andMapFeatureModes
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 (seeMapFeatureModes
). -
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()