MapScene class abstract

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.loadSceneForMapScheme. 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.addListener. Query the bounding box of the camera viewport using MapCamera.boundingBox (it may be extended) and then use the method GeoBox.containsGeoCoordinates in combination with MapCameraState.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.