Package com.luciad.model.transformation.clustering

Class TLcdClusteringTransformer

java.lang.Object
com.luciad.model.transformation.clustering.TLcdClusteringTransformer
public final class TLcdClusteringTransformer extends Object

Transformer that aims to reduce map clutter caused by showing many icons. If model elements are located close to each other, they are instead replaced by a single cluster element. Whether elements are close to each other or not is defined in view space, so it depends on the current zoom level and camera position.

You use a TLcdClusteringTransformer in combination with a ALcdTransformingModel. Create instances using the newBuilder() method.
Note that it is not allowed to share a single TLcdClusteringTransformer between different ALcdTransformingModel instances. Each ALcdTransformingModel should be constructed using its own, dedicated TLcdClusteringTransformer instance.

The clustering transformer will be triggered automatically by the ALcdTransformingModel whenever the result of the clustering operation might have changed. Examples are view navigation (zooming, panning, ...), model changes, changes to the layer filter, ... .

Clustering has these properties, with respect to the original (=unclustered) model, and the transformed (=clustered) model:

  • All point elements are considered for clustering. All elements that are not points, are added as-is to the transformed model. An element is a point if it implements ILcdPoint, or ILcdPointList or ILcdShapeList with one point. Elements annotated with TLcdHasGeometryAnnotation are considered as well.
  • Points that are considered for clustering may be added to the transformed model as-is, may be added to the transformed model as part of a cluster, or may be omitted. The exact behavior depends on zoom level, camera position, etc.
  • Clusters are essentially groups of point elements, modeled using TLcdCluster.
  • Cluster are by default represented by a point, located at the location of their most suitable containing element. The most suitable containing element is the one that is closest to the center of mass of all containing elements. This avoids weird situations such as positioning a cluster of hospitals on a nearby lake, as the cluster uses one of the locations of an existing hospital. You can adjust this by specifying your own ILcdClusterShapeProvider.
  • If the original model has a ILcdDataModelDescriptor, the transformed model also has one. If the original model does not have one, the transformed model doesn't either. The data model is extended with an extra type for the clusters, see TLcdClusterDataTypes.
  • The model reference of the transformed model is identical to that of the original model.
  • Filtering: if a filter is specified on the layer, it is respected: elements that don't pass the filter do not end up in the transformed model.
Since:
2016.0

  • Field Details

  • Method Details

    • newBuilder

      public static TLcdClusteringTransformer.Builder newBuilder()
      Creates a new builder for TLcdClusteringTransformer. This builder allows you to configure default parameters and parameters for specific classifications using the forClass method.
      Returns:
      the new builder.
      See Also:

    • createScaleDependent

      public static TLcdClusteringTransformer createScaleDependent(double[] aScaleDenominators, TLcdClusteringTransformer[] aClusteringTransformers)
      Deprecated.
      use createMapScaleDependent(double[], TLcdClusteringTransformer[])
      This methods allows to create a TLcdClusteringTransformer which uses different cluster settings for different scales. This is achieved by providing a set of scale denominators, and for each scale a clustering transformer.

      Each of the scale denominators marks the switching point between the settings of the two clustering transformer instances at the corresponding indices in the clustering transformer array.

      Note that the scale denominators need to be ordered from a low value denominator (=zoomed in scale) to a high value denominator (=zoomed out scale). The clustering transformers need to use the same ordering: the transformer corresponding to the most zoomed in scale first, and the transformer corresponding to the most zoomed-out scale last. As the scales indicate the switching point between two transformers, the number of needed transformers is equal to the number of scales + 1.

      A visual example of the relation between the scale switching points and the different transformers is given below. The example uses 3 different switching scales, hence requires 4 transformers. 

        Scale:             1 : 1000          1 : 10 000           1 : 100 000

  (zoomed in) ---------- | ----------------- | ----------------- | ---------- (zoomed out)

       transformer[0]        transformer[1]     transformer[2]      transformer[3]
      Parameters:
      aScaleDenominators - The scale denominators, in world units/toolkit pixels. Should be ordered from small denominators to large denominators, e.g. new int[]{1000, 10000, 100000}.
      aClusteringTransformers - The array of clustering transformers. Should have aScaleDenominators.length + 1 as length.
      Returns:
      a TLcdClusteringTransformer which uses different cluster settings for different scales

    • createMapScaleDependent

      public static TLcdClusteringTransformer createMapScaleDependent(double[] aScales, TLcdClusteringTransformer[] aClusteringTransformers)

      This methods allows to create a TLcdClusteringTransformer which uses different cluster settings for different scales. This is achieved by providing a set of unitless scales, and for each scale a clustering transformer. For example specifying a scale of "1/5000" means that one centimetre on the map equals 5000 centimetres in reality.

      Each scale marks the switching point between the settings of the two clustering transformer instances at the corresponding indices in the clustering transformer array.
      For example, if you want to use different cluster settings when zoomed out compared to zoomed in, and the scale on which the settings must be switched is 1 : 10 000, you would use 

      
   TLcdClusteringTransformer zoomedOutSettings = ...;
   TLcdClusteringTransformer zoomedInSettings = ...;

   double scales = new double[]{1.0/10000.0};
   TLcdClusteringTransformer[] transformers = new TLcdClusteringTransformer[]{
     zoomedInSettings,
     zoomedOutSettings
   };

   TLcdClusteringTransformer transformer =
     TLcdClusteringTransformer.createMapScaleDependent( scales, transformers );

      Note that the scales need to be ordered from a zoomed in scale to a zoomed out scale (high values to low values). The clustering transformers need to use the same ordering: the transformer corresponding to the most zoomed in scale first, and the transformer corresponding to the most zoomed-out scale last. As the scales indicate the switching point between two transformers, the number of needed transformers is equal to the number of scales + 1.

      A visual example of the relation between the scale switching points and the different transformers is given below. The example uses 3 different switching scales, hence requires 4 transformers. 

        Scale:             1 : 1000          1 : 10 000           1 : 100 000

  (zoomed in) ---------- | ----------------- | ----------------- | ---------- (zoomed out)

       transformer[0]        transformer[1]     transformer[2]      transformer[3]
      Parameters:
      aScales - The scales, which are expressed as a unitless scale. Should be ordered from detailed scales to less detailed levels, e.g. new int[]{1.0/1000.0, 1.0/10000.0, 1.0/100000.0}.
      aClusteringTransformers - The array of clustering transformers. Should have aScales.length + 1 as length.
      Returns:
      a TLcdClusteringTransformer which uses different cluster settings for different scales
      Since:
      2018.1