Method Details

• loadScene

  public void loadScene(@NonNull MapScheme mapScheme, @Nullable MapScene.LoadSceneCallback callback)

  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 enableFeatures(java.util.Map<java.lang.String, java.lang.String>) and disableFeatures(java.util.List<java.lang.String>) will be reset to defaults for the new scene configuration.

  The callback is called on the main thread. When recreating an activity following a device rotation, it is not necessary to call this method a second time. The map scheme that was loaded when the map view was initially created will continue to be used.

  Parameters:

  mapScheme -

  Map scheme.

  callback -

  Optional callback that will receive the result of this operation.

• loadScene

  public void loadScene(@NonNull String configurationFile, @Nullable MapScene.LoadSceneCallback callback)

  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 enableFeatures(java.util.Map<java.lang.String, java.lang.String>) and disableFeatures(java.util.List<java.lang.String>) will be reset to defaults for the new scene configuration.

  The callback is called on the main thread. When recreating an activity following a device rotation, it is not necessary to call this method a second time. The map scheme that was loaded when the map view was initially created will continue to be used.

  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.

  callback -

  Optional callback that will receive the result of this operation.

• loadScene

  public void loadScene(@NonNull String configurationFile, @NonNull WatermarkStyle watermarkStyle, @Nullable MapScene.LoadSceneCallback callback)

  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 enableFeatures(java.util.Map<java.lang.String, java.lang.String>) and disableFeatures(java.util.List<java.lang.String>) will be reset to defaults for the new scene configuration.

  The callback is called on the main thread. When recreating an activity following a device rotation, it is not necessary to call this method a second time. The map scheme that was loaded when the map view was initially created will continue to be used.

  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.

  callback -

  Optional callback that will receive the result of this operation.

• loadScene

  public void loadScene(@NonNull MapSceneLoadOptions options, @Nullable MapScene.LoadSceneCallback callback)

  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.

  When recreating an activity following a device rotation, it is not necessary to call this method a second time. The map scheme that was loaded when the map view was initially created will continue to be used.

  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.

  Parameters:

  options -

  Scene configuration options created using MapSceneLoadOptionsBuilder.

  callback -

  Optional callback that will receive the result of this operation.

• addMapPolyline

  public void addMapPolyline(@NonNull MapPolyline mapPolyline)

  Adds a map polyline to this map scene.

  Parameters:

  mapPolyline -

  The map polyline to be added to this map scene.

• addMapPolylines

  public void addMapPolylines(@NonNull List<MapPolyline> mapPolylines)

  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.

  Parameters:

  mapPolylines -

  The map polylines to be added to this map scene.

• removeMapPolyline

  public void removeMapPolyline(@NonNull MapPolyline mapPolyline)

  Removes a map polyline from this map scene.

  Parameters:

  mapPolyline -

  The map polyline to be removed from this map scene.

• removeMapPolylines

  public void removeMapPolylines(@NonNull List<MapPolyline> mapPolylines)

  Removes map polylines from this map scene.

  Parameters:

  mapPolylines -

  The map polylines to be removed from this map scene.

• removeAllMapPolylines

  public void removeAllMapPolylines()

  Removes all map polylines from this map scene.

• addMapArrow

  public void addMapArrow(@NonNull MapArrow mapArrow)

  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.

  Parameters:

  mapArrow -

  The map arrow to be added to this map scene.

• removeMapArrow

  public void removeMapArrow(@NonNull MapArrow mapArrow)

  Removes a map arrow from this map scene.

  Parameters:

  mapArrow -

  The map arrow to be removed from this map scene.

• addMapMarker

  public void addMapMarker(@NonNull MapMarker marker)

  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.

  Parameters:

  marker -

  The marker to be added to this map scene.

• addMapMarkers

  public void addMapMarkers(@NonNull List<MapMarker> markers)

  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.

  Parameters:

  markers -

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

• removeMapMarker

  public void removeMapMarker(@NonNull MapMarker marker)

  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.

  Parameters:

  marker -

  The marker to be removed from this map scene.

• removeMapMarkers

  public void removeMapMarkers(@NonNull List<MapMarker> markers)

  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.

  Parameters:

  markers -

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

• removeAllMapMarkers

  public void removeAllMapMarkers()

  Removes all map markers from this map scene.

• addMapMarkerCluster

  public void addMapMarkerCluster(@NonNull MapMarkerCluster cluster)

  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.

  Parameters:

  cluster -

  The marker cluster to be added to this map scene.

• removeMapMarkerCluster

  public void removeMapMarkerCluster(@NonNull MapMarkerCluster cluster)

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

  Parameters:

  cluster -

  The marker cluster to be removed from this map scene.

• addMapMarker3d

  public void addMapMarker3d(@NonNull MapMarker3D marker)

  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.

  Parameters:

  marker -

  The marker to be added to this map scene.

• addMapMarkers3d

  public void addMapMarkers3d(@NonNull List<MapMarker3D> markers)

  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.

  Parameters:

  markers -

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

• removeMapMarker3d

  public void removeMapMarker3d(@NonNull MapMarker3D marker)

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

  Parameters:

  marker -

  The marker to be removed from this map scene.

• removeMapMarkers3d

  public void removeMapMarkers3d(@NonNull List<MapMarker3D> markers)

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

  Parameters:

  markers -

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

• removeAllMapMarkers3d

  public void removeAllMapMarkers3d()

  Removes all 3D map markers from this map scene.

• addMapPolygon

  public void addMapPolygon(@NonNull MapPolygon mapPolygon)

  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.

  Parameters:

  mapPolygon -

  The map polygon to be added to this map scene.

• addMapPolygons

  public void addMapPolygons(@NonNull List<MapPolygon> mapPolygons)

  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.

  Parameters:

  mapPolygons -

  The map polygons to be added to this map scene.

• removeMapPolygon

  public void removeMapPolygon(@NonNull MapPolygon mapPolygon)

  Removes a map polygon from this map scene.

  Parameters:

  mapPolygon -

  The map polygon to be removed from this map scene.

• removeMapPolygons

  public void removeMapPolygons(@NonNull List<MapPolygon> mapPolygons)

  Removes multiple map polygon from this map scene.

  Parameters:

  mapPolygons -

  The map polygons to be removed from this map scene.

• removeAllMapPolygons

  public void removeAllMapPolygons()

  Removes all map polygons from this map scene.

• addMapImageOverlay

  public void addMapImageOverlay(@NonNull MapImageOverlay overlay)

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

  Parameters:

  overlay -

  The overlay to be added to this map scene.

• removeMapImageOverlay

  public void removeMapImageOverlay(@NonNull MapImageOverlay overlay)

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

  Parameters:

  overlay -

  The overlay to be removed from this map scene.

• setLayerVisibility

  public void setLayerVisibility(@NonNull String layerName, @NonNull VisibilityState visibility)

  Immediately changes the visibility of a specified map layer.

  Parameters:

  layerName -

  The name of the map layer to be changed.

  visibility -

  The new visibility state of the layer.

• getActiveFeatures

  @NonNull public Map<String,String> getActiveFeatures()

  Gets map features that are currently active. Active features are features that are either enabled via a call to enableFeatures(java.util.Map<java.lang.String, java.lang.String>) 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.

  Returns:

  The map of active features.

• getSupportedFeatures

  @NonNull public Map<String,List<String>> getSupportedFeatures()

  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.

  Returns:

  The map of supported features and all their modes.

• enableFeatures

  public void enableFeatures(@NonNull Map<String,String> features)

  Enables specified map features. Those will become active after next map redraw, meaning that 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.

  Parameters:

  features -

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

• disableFeatures

  public void disableFeatures(@NonNull List<String> features)

  Disables specified map features. Those will become inactive after next map redraw, meaning that 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.

  Parameters:

  features -

  The names of features to disable (see MapFeatures).

• reloadScene

  public void reloadScene()

  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.

• getLights

  @NonNull public MapSceneLights getLights()

  Gets a MapSceneLights instance that controls lights present in the scene.

  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.

  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.

  Returns:

  Controls lights present in the scene.