Package com.here.sdk.mapview

Class MapLayerBuilder

java.lang.Object
com.here.NativeBase
com.here.sdk.mapview.MapLayerBuilder
public final class MapLayerBuilder extends NativeBase

MapLayerBuilder is used to add layers to a map to visualise a dataset in a programmatic way without defining it upfront in the configuration files.

For example, after loading a scene configuration file, the renderer is setup to draw layers in the following order:

  • background
  • water
  • roads:outline
  • roads
  • labels

Rendering order of elements in a single map layer can be controlled with categories. Layer names are unique, and category names have to be unique within a layer. The layer's default, main category is unnamed.

The concept of 'category' is tightly linked to styling. The idea behind category is that one should be able to style separately elements in a map layer. Take, for instance, roads. If one wants to style separately the bridges it will create a category 'bridges' and style it accordingly in the style file. If the user does not intend to or cannot style elements of the layer differently then it should opt for a layer with only the default category (e.g. for a raster layer, only the default category makes sense, since the layer has no other stylable elements apart from the raster image).

A new layer called 'zone' and its category 'background' can be added dynamically so that the rendering order gets modified in the following way:

  • background
  • water
  • zone:background
  • zone
  • roads:outline
  • roads
  • labels

This could be achieved with the help of the MapLayerPriorityBuilder and the MapLayerBuilder as in the following example: 

 MapLayerPriority layerPriority = new MapLayerPriorityBuilder()
        .renderedAfterLayer("water") // places main category after 'water'
        .withCategory("background")
        .renderedAfterLayer("water") // places 'background' category after 'water' and before the
                                     // layer's main category.
        .build();

     MapLayer layer = new MapLayerBuilder()
        .withDataSource("DataSourceName", MapContentType.LINE)
        .forMap(map)
        .withName("zone")
        .withPriority(layerPriority)
        .build();

In case no layer priority or an empty one is provided, or if a reference layer-category pair is not present in the rendering order, the layer is going to be rendered last with respect to the rendering order at the time of its creation.

Due to current limitations, the MapLayerPriority assignment is not implemented for point map layers. All labels will be rendered within the "labels" layer, defined in the scene configuration file. By default, all labels rendered by a point map layer are rendered last and no overlapping is allowed. The following categories can be used to have a different behaviour:

  • 'custom-labels' A label should be rendered first, is allowed to overlap with other labels of the same category and block map labels.
  • 'custom-labels-no-self-overlap' A label should be rendered after 'custom-labels', is not allowed to overlap with other labels of the same categoty and block map labels.
  • 'custom-labels-overlap-all' A label should be rendered last, is allowed to overlap all predefined categories, also map labels. These categories are configured accordingly in the basic map scene configurations. Category assignment to features can be done in the style based on data attributes. The category assignment can be done for all types of content: point, line, polygon.

  • Constructor Details

    • MapLayerBuilder

      public MapLayerBuilder()

      Creates an instance of the layer builder interface.

  • Method Details

    • withName

      @NonNull public MapLayerBuilder withName(@NonNull String name)

      Configures builder to use the given name as a layer name. The name is a mandatory layer creation parameter.

      Parameters:
      name -

      Name of the layer. Must be unique.

      Returns:

      This class instance.

    • withDataSource

      @NonNull public MapLayerBuilder withDataSource(@NonNull String dataSourceName, @NonNull MapContentType contentType)

      Configures the builder to use a data source with the given name as the source of data for the layer. The datasource name and content type are mandatory layer creation parameters.

      Parameters:
      dataSourceName -

      Name of the data source.

      contentType -

      The renderable content type supplied by the data source.

      Returns:

      This class instance.

    • withStyle

      @NonNull public MapLayerBuilder withStyle(@NonNull Style style)

      Configures the builder to use a style. Providing a style during layer creation is not mandatory. The style can also be set/updated after the layer creation. For more details see Custom Layer Style Reference in the documentation. Note: This is a beta release of this feature, so there could be a few bugs and unexpected behavior. Related APIs may change for new releases without a deprecation process.

      Parameters:
      style -

      Style for the layer.

      Returns:

      This class instance.

    • forMap

      @NonNull public MapLayerBuilder forMap(@NonNull HereMap targetMap)

      Configures the builder to display a layer in the given map. The map is a mandatory layer creation parameter.

      Parameters:
      targetMap -

      The map.

      Returns:

      This class instance.

    • withPriority

      @NonNull public MapLayerBuilder withPriority(@NonNull MapLayerPriority priority)

      Configures the builder to set the MapLayerPriority to be used by the layer.

      Parameters:
      priority -

      MapLayerPriority which should be applied to the layer.

      Returns:

      This class instance.

    • withVisibilityRange

      @NonNull public MapLayerBuilder withVisibilityRange(@NonNull MapLayerVisibilityRange visibilityRange)

      Configures the builder to set the layer visible in the given zoom levels range. Values outside the map zoom level range (0, 24) will be ignored. Providing the visibility range is optional. If not provided, the layer will be visible on all zoom levels.

      Parameters:
      visibilityRange -

      Visibility range which should be applied to the layer.

      Returns:

      This class instance.

    • withMapMeasureDependentStorageLevels

      @NonNull public MapLayerBuilder withMapMeasureDependentStorageLevels(@NonNull MapLayerMapMeasureDependentStorageLevels mapLayerMapMeasureDependentStorageLevels)

      Applies a mapping from the map measure to the storage level. This mapping is used by the layer to request data for the specified storage level corresponding to the map measure from the datasource. This can be used for example to fine-tune the resolution of raster layers. Note: When the map camera is significantly tilted, the storage level is further reduced for data towards the horizon. Note: Mappings that request higher storage levels will lead to an increased number of requests to the raster tile service. Providing the map measure to storage level mapping is optional. If not provided, the default mapping will use a storage level that is for raster layers one and for others three levels lower than the zoom level, corresponding to an offset of -1 and -3.

      Parameters:
      mapLayerMapMeasureDependentStorageLevels -

      The map measure to storage level mapping that should be applied for the layer.

      Returns:

      This class instance.

    • withLoadPriority

      @NonNull public MapLayerBuilder withLoadPriority(double loadPriority)

      Configures the builder to set the layer load priority. Higher load priority values lead to layer being scheduled for loading before layers with lesser values.

      Parameters:
      loadPriority -

      Load priority for layer.

      Returns:

      This class instance.

    • build

      @NonNull public MapLayer build() throws MapLayerBuilder.InstantiationException

      Constructs, registers and configures a new map layer showing specified content type according to the configured parameters. After this call this instance is reset to the initial state. It could be used to build another map layer, but will not keep any previously configured properties.

      Returns:

      A new MapLayer instance.

      Throws:
      MapLayerBuilder.InstantiationException -

      Indicates an instantiation issue.