Class MapScene

Method Detail

• 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
                        java.lang.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
                        java.lang.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
                              java.util.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
                                 java.util.List<MapPolyline> mapPolylines)

  Removes map polylines from this map scene.

  Parameters:

  mapPolylines -

  The map polylines to be removed 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
                            java.util.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
                               java.util.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.

• 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.

• 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.

• 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.

• 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.

• 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
                                 java.lang.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 java.util.Map<java.lang.String,​java.lang.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 java.util.Map<java.lang.String,​java.util.List<java.lang.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
                             java.util.Map<java.lang.String,​java.lang.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
                              java.util.List<java.lang.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.