Package com.luciad.view.lightspeed.layer.shape

Class TLspShapeLayerBuilder

java.lang.Object
com.luciad.view.lightspeed.layer.ALspLayerBuilder
com.luciad.view.lightspeed.layer.shape.TLspShapeLayerBuilder
public final class TLspShapeLayerBuilder extends ALspLayerBuilder
Builder for creating ILspLayer instances that visualize geometric shapes. This builder is the recommended way of creating new layers with a model that contains ILcdShape and/or ILcd3DMesh elements.

This layer builder uses the following default settings to allow for easy layer setup, they can all be overridden using the methods available on this builder:

  • Default styles for points, curves, surfaces and geo-referenced meshes are used if none are specified. The actual styling parameters are taken from TLspIconStyle, TLspLineStyle, TLspFillStyle and TLsp3DMeshStyle.
  • Selection is enabled, selection styling is derived from the regular style.
  • Editing is disabled.
  • Labeling is disabled.
  • The model descriptor display name is used as layer label.
  • Culling is enabled.
  • Snapping is enabled

To enable editing, set bodyEditable(boolean) to true and optionally provide a custom editor through bodyEditor(com.luciad.view.lightspeed.editor.ILspEditor).

To enable labels, set a styler for labels using labelStyler(com.luciad.view.lightspeed.layer.TLspPaintState, com.luciad.view.lightspeed.style.styler.ILspStyler). You can use the default TLspLabelStyler, or create your own. However, the styler must apply at least one style to the domain objects for any labels to be displayed. Alternatively, you can can also just add a TLspTextStyle using labelStyles(com.luciad.view.lightspeed.layer.TLspPaintState, com.luciad.view.lightspeed.style.ALspStyle...).

Since:
2012.0

  • Method Details

    • newBuilder

      public static TLspShapeLayerBuilder newBuilder()
      Returns:
      a new layer builder with the default settings.

    • newBuilder

      public static TLspShapeLayerBuilder newBuilder(ILspLayer.LayerType aLayerType)
      Creates a TLspShapeLayerBuilder.newBuilder with the given layer type.

      When creating a layer for use with dynamic data, it is highly recommended to use the ILspLayer.LayerType.REALTIME layer type, since it provides various performance enhancements for dynamic data. Failing to do so may result in a non-negligible performance cost.

      Parameters:
      aLayerType - the layer type for the layer built by this builder
      Returns:
      a new layer builder with the given layer type

    • build

      public TLspLayer build()
      Description copied from class: ALspLayerBuilder

      Creates a new layer instance.

      Specified by:
      build in class ALspLayerBuilder
      Returns:
      the new layer instance

    • selectable

      public TLspShapeLayerBuilder selectable(boolean aSelectable)
      Sets whether the layer should be selectable, by default, non-background layers are selectable.
      Parameters:
      aSelectable - whether the layer should be selectable
      Returns:
      this

    • selectableSupported

      public TLspShapeLayerBuilder selectableSupported(boolean aSelectableSupported)
      Sets whether the layer should support selection. By default, layers support selection.
      Parameters:
      aSelectableSupported - whether the layer should support selection
      Returns:
      this

    • editableSupported

      public TLspShapeLayerBuilder editableSupported(boolean aEditableSupported)
      Sets whether the layer should support editing. By default, layers support editing if any editors are set.
      Parameters:
      aEditableSupported - whether the layer should support selection
      Returns:
      this

    • bodyEditable

      public TLspShapeLayerBuilder bodyEditable(boolean aEditable)
      Sets whether the body of the layer should be editable. A default body editor will be used if no body editor is provided.
      Parameters:
      aEditable - whether the body of the layer should be editable
      Returns:
      this
      See Also:

    • labelEditable

      public TLspShapeLayerBuilder labelEditable(boolean aEditable)
      Sets whether the labels of the layer should be editable. A default label editor will be used if no label editor is provided.
      Parameters:
      aEditable - whether the labels of the layer should be editable
      Returns:
      this
      See Also:

    • bodyStyler

      public TLspShapeLayerBuilder bodyStyler(TLspPaintState aPaintState, ILspStyler aBodyStyler)
      Sets the given body styler for the given paint state.

      The following styles are supported:

      Use either bodyStyler(com.luciad.view.lightspeed.layer.TLspPaintState, com.luciad.view.lightspeed.style.styler.ILspStyler) or bodyStyles(com.luciad.view.lightspeed.layer.TLspPaintState, com.luciad.view.lightspeed.style.ALspStyle...), not both.

      Parameters:
      aPaintState - the paint state for which to set the body styler
      aBodyStyler - the new body styler for the layer
      Returns:
      this

    • bodyStyles

      public TLspShapeLayerBuilder bodyStyles(TLspPaintState aPaintState, ALspStyle... aBodyStyles)
      Sets the given body styles for the given paint state.

      The following styles are supported:

      Use either bodyStyler(com.luciad.view.lightspeed.layer.TLspPaintState, com.luciad.view.lightspeed.style.styler.ILspStyler) or bodyStyles(com.luciad.view.lightspeed.layer.TLspPaintState, com.luciad.view.lightspeed.style.ALspStyle...), not both.

      Parameters:
      aPaintState - the paint state for which to set the body styler
      aBodyStyles - the new body styles for the layer
      Returns:
      this

    • labelStyler

      public TLspShapeLayerBuilder labelStyler(TLspPaintState aPaintState, ILspStyler aLabelStyler)
      Sets the given label styler for the given paint state.

      If you need control over other labeling aspects such as positioning or priorities, use an ALspLabelStyler.

      The following styles are supported:

      Use either labelStyler(com.luciad.view.lightspeed.layer.TLspPaintState, com.luciad.view.lightspeed.style.styler.ILspStyler) or labelStyles(com.luciad.view.lightspeed.layer.TLspPaintState, com.luciad.view.lightspeed.style.ALspStyle...), not both.

      Parameters:
      aPaintState - the paint state for which to set the label styler
      aLabelStyler - the new label styler for the layer
      Returns:
      this

    • labelStyles

      public TLspShapeLayerBuilder labelStyles(TLspPaintState aPaintState, ALspStyle... aLabelStyles)
      Sets the given label styles for the given paint state.

      The following styles are supported:

      Use either labelStyler(com.luciad.view.lightspeed.layer.TLspPaintState, com.luciad.view.lightspeed.style.styler.ILspStyler) or labelStyles(com.luciad.view.lightspeed.layer.TLspPaintState, com.luciad.view.lightspeed.style.ALspStyle...), not both.

      Parameters:
      aPaintState - the paint state for which to set the label styles
      aLabelStyles - the new label styles for the layer
      Returns:
      this

    • bodyPainter

      public TLspShapeLayerBuilder bodyPainter(ILspPainter aPainter)
      Allows setting a custom body painter on the layer. In almost any case, it is better to configure the default painter using the bodyStyler(TLspPaintState, ILspStyler) or bodyStyles(TLspPaintState, ALspStyle...) methods instead.

      One example of using a custom painter is the TLspDensityPainter to create a density plot layer.

      Parameters:
      aPainter - the body painter for the layer
      Returns:
      this

    • labelPainter

      public TLspShapeLayerBuilder labelPainter(ILspPainter aPainter)
      Allows setting a custom label painter on the layer. In almost any case, it is better to configure the default label painter using the labelStyler(TLspPaintState, ILspStyler) or labelStyles(TLspPaintState, ALspStyle...) methods instead.
      Parameters:
      aPainter - the label painter for the layer
      Returns:
      this
      See Also:

    • bodyEditor

      public TLspShapeLayerBuilder bodyEditor(ILspEditor aEditor)
      Sets the body editor for the layer, alternatively you can use bodyEditable(boolean) to enable a default editor.
      Parameters:
      aEditor - the body editor for the layer
      Returns:
      this
      See Also:

    • labelEditor

      public TLspShapeLayerBuilder labelEditor(ILspEditor aEditor)
      Sets a custom label editor for the layer, alternatively you can use labelEditable(boolean) to enable a default label editor.
      Parameters:
      aEditor - the label editor for the layer
      Returns:
      this
      See Also:

    • bodyScaleRange

      public TLspShapeLayerBuilder bodyScaleRange(ILcdInterval aBodyScaleRange)
      Sets the scale range for the body of the layer in toolkit pixels/meter. This property defines a range of scales in which the bodies of the layer are visible. By default, no scale range is used, meaning that all bodies are visible.
      Parameters:
      aBodyScaleRange - the scale range for the body of the layer, in toolkit pixels/meter
      Returns:
      this

    • bodyMapScaleRange

      public TLspShapeLayerBuilder bodyMapScaleRange(TLcdDimensionInterval<TLcdMapScale> aBodyScaleRange)
      Sets the scale range for the body of the layer in unitless map scale ratios. This property defines a range of scales in which the bodies of the layer are visible. By default, no scale range is used, meaning that all bodies are visible.
      Parameters:
      aBodyScaleRange - the scale range for the body of the layer
      Returns:
      this
      Since:
      2021.0

    • labelScaleRange

      public TLspShapeLayerBuilder labelScaleRange(ILcdInterval aLabelScaleRange)
      Sets the scale range for the labels of the layer in toolkit pixels/meter. This property defines a range of scales in which the labels of the layer are visible. By default, no scale range is used, meaning that all labels are visible.
      Parameters:
      aLabelScaleRange - the scale range for the labels of the layer, in toolkit pixels/meter
      Returns:
      this

    • labelMapScaleRange

      public TLspShapeLayerBuilder labelMapScaleRange(TLcdDimensionInterval<TLcdMapScale> aLabelScaleRange)
      Sets the scale range for the labels of the layer in unitless map scale ratios. This property defines a range of scales in which the labels of the layer are visible. By default, no scale range is used, meaning that all labels are visible.
      Parameters:
      aLabelScaleRange - the scale range for the labels of the layer
      Returns:
      this
      Since:
      2021.0

    • culling

      public TLspShapeLayerBuilder culling(boolean aUseCulling)
      Sets whether the layer should use culling or not, enabled by default.

      Enabling culling restricts the objects that are painted to those that (approximately) overlap with the view. This typically reduces the memory usage and increases the frame rate. However because culling also introduces an additional overhead, you may get better performance by disabling it for either very dynamic layers or layers with only a small amount of objects.

      The cost of culling is typically higher if the model does not implement ILcd2DBoundsIndexedModel.

      The culling of objects is based on their model bounds. These bounds may be (slightly) different from the painted representation's bounds. This can occur due to styling (for example painting a point as a circle or as a view-sized icon). To ensure that objects all objects are correctly painted in these cases you can configure a margin in both pixels and meters.

      Parameters:
      aUseCulling - whether the layer should use culling or not
      Returns:
      this

    • filter

      public TLspShapeLayerBuilder filter(ILcdDynamicFilter aFilter)

      Sets a filter that will be used to filter objects to prevent them from being painted by the layer. No filter is set by default.

      Consult the class javadoc of TLspLayer for more information about data filtering.

      Parameters:
      aFilter - the filter
      Returns:
      this

    • modelQueryConfiguration

      public TLspShapeLayerBuilder modelQueryConfiguration(TLcdModelQueryConfiguration aModelQueryConfiguration)

      Sets the model query configuration which defines the filters that the layer will use when querying the model during the paint operation.

      Consult the class javadoc of TLspLayer for more information about data filtering.

      Parameters:
      aModelQueryConfiguration - The model query configuration
      Returns:
      this
      Since:
      2017.0

    • sldStyle

      public TLspShapeLayerBuilder sldStyle(TLcdSLDFeatureTypeStyle aFeatureTypeStyle)

      Use the styling defined in aFeatureTypeStyle to style the layer under creation. All relevant settings on the layer will be adjusted to match the info contained in the SLD style.

      Calling this method is the equivalent of calling (in pseudo-code): 

      
   //Create a model query configuration based on the SLD
   TLcdModelQueryConfiguration config = calculateFromSLD(aFeatureTypeStyle);
   //Create an SLD styler
   TLspSLDStyler styler = new TLspSLDStyler(aFeatureTypeStyle);

   //Configure those instances on the builder
   builder.modelQueryConfiguration(config)
          .bodyStyler(TLspPaintState.REGULAR, styler)
          .labelStyler(TLspPaintState.REGULAR, styler);

      If you need to override certain settings, while wanting to retain the rest, you can call this method and override some settings afterwards. For example, if you want to use a specific SLD context for the styler, you can use: 

      

   //Create a SLD styler which uses a custom context
   TLcdSLDContext context = createCustomSLDContext();
   TLspSLDStyler customSLDStyler = new TLspSLDStyler(aFeatureTypeStyle, context);

   //Override the styler, while retaining the SLD-based model query configuration
   builder.sldStyle(aFeatureTypeStyle)
          .bodyStyler(TLspPaintState.REGULAR, customSLDStyler)
          .labelStyler(TLspPaintState.REGULAR, customSLDStyler);

      Note that in future versions of the product it is possible that this method will overwrite more settings.

      Parameters:
      aFeatureTypeStyle - The feature type style
      Returns:
      this builder
      Since:
      2017.0

    • minimumObjectSizeForPainting

      public TLspShapeLayerBuilder minimumObjectSizeForPainting(double aMinimumObjectSizeForPainting)
      Sets the minimum size of an object in the view for it to be painted and handled otherwise. So objects that are smaller as this minimum size are ignored during painting and during applyOnInteract (which is for example used during selection). A value of 0 will always paint all objects, no matter how small they appear. Larger values can discard more objects. This typically improves the painting speed, although it might leave undesirable gaps in models containing many small objects. The default value is 1 pixel.

      See TLspLayer.setMinimumObjectSizeForPainting(double) for more information.

      Parameters:
      aMinimumObjectSizeForPainting - The minimal size, expressed in pixels.
      Returns:
      this

    • objectViewMargin

      public TLspShapeLayerBuilder objectViewMargin(double aObjectViewMargin)
      Sets the largest possible difference (in pixels) between an object's model bounds and its painted representation's bounds that should be taken into account.

      This value is used when determining what objects are visible (if culling is enabled). It ensures, for example, that a model element is still painted if its visual representation falls inside the view, but its model bounds do not.

      If for example view-sized icons are used to represent points on the map, the icon could be 16 by 16 pixels, whereas the object itself is a point, having a zero size. Depending on where the point is located in the icon, the required margin for this example can be up to 16 pixels.

      The drawback of setting a too large value is a performance loss. The drawback of setting a too small value is that objects (e.g. icons) disappear when they are located partly outside the view.

      You can also configure a maximum distance in meters.

      The default value is 32.

      Parameters:
      aObjectViewMargin - the maximum difference (in pixels)
      Returns:
      this

    • objectWorldMargin

      public TLspShapeLayerBuilder objectWorldMargin(double aObjectWorldMargin)
      Sets the largest possible difference (in meters) between an object's model bounds and its painted representation's bounds that should be taken into account.

      This value is used when determining what objects are visible (if culling is enabled). It ensures, for example, that a model element is still painted if its visual representation falls inside the view, but its model bounds do not.

      If for example circles are used to represent points on the map, the circle could have a radius of 1km, whereas the object itself is a point, having a zero size. The required margin for this example is 1000 meters.

      The drawback of setting a too large value is a performance loss. The drawback of setting a too small value is that objects (e.g. icons) disappear when they are located partly outside the view.

      You can also configure a maximum distance in pixels.

      The default value is 0.

      Parameters:
      aObjectWorldMargin - the maximum difference in meters
      Returns:
      this

    • synchronizePainters

      public TLspShapeLayerBuilder synchronizePainters(boolean aSynchronizePainters)
      Sets whether the painters should be synchronized or not.

      If the synchronization is enabled then all painters will be updated at the same time. For example the body and label of the objects in the view will be consistent. However enabling synchronization typically also increases the memory usage and latency of the layer.

      The default value is true.

      Parameters:
      aSynchronizePainters - true if the painters should be synchronized
      Returns:
      this

    • paintingHints

      public TLspShapeLayerBuilder paintingHints(TLspShapePaintingHints aPaintingHints)
      Sets the painting hints to be used by created layers. The hints are only respected when no custom painter is set (i.e. when bodyPainter(ILspPainter) is not called).

      The default value is TLspShapePaintingHints.newBuilder().build(). The hints must not be null.

      Parameters:
      aPaintingHints - the painting hints to be used
      Returns:
      this

    • synchronous

      public TLspShapeLayerBuilder synchronous(boolean aIsSynchronous)
      Specifies whether created layers should paint synchronously. The default is false and allows layers to perform shape discretization and other expensive processing using the view's ILspTaskExecutor. When synchronous mode is on, all such tasks are performed on the EDT.

      It is strongly recommended to leave this setting off, to ensure that the application remains responsive. Applications that need to change the view's world reference on a regular basis, however, may want to consider synchronous mode to avoid flickering.

      Parameters:
      aIsSynchronous - true if the layer should paint synchronously
      Returns:
      this

    • snapTarget

      public TLspShapeLayerBuilder snapTarget(boolean aIsSnapTarget)
      Sets whether the created layer should be regarded as a source for snapping points.
      Parameters:
      aIsSnapTarget - if true, the created layer should be regarded as a source for snapping points, i.e. it should be possible to snap to objects in the layer; if false, the layer should not produce snapping candidates.
      Since:
      2018.0

    • model

      public TLspShapeLayerBuilder model(ILcdModel aModel)
      Description copied from class: ALspLayerBuilder
      Sets the model of the layer.

      The default value is null.

      Overrides:
      model in class ALspLayerBuilder
      Parameters:
      aModel - a model
      Returns:
      this builder
      See Also:

    • label

      public TLspShapeLayerBuilder label(String aLabel)
      Description copied from class: ALspLayerBuilder
      Sets the label of the layer. This is a short textual representation for it, often used to represent the layer to end-users.

      The default value is null.

      Overrides:
      label in class ALspLayerBuilder
      Parameters:
      aLabel - the label
      Returns:
      this builder
      See Also:

    • layerType

      public TLspShapeLayerBuilder layerType(ILspLayer.LayerType aLayerType)
      Description copied from class: ALspLayerBuilder
      Sets the layer type of the layer.

      The default value is ILspLayer.LayerType.EDITABLE.

      Overrides:
      layerType in class ALspLayerBuilder
      Parameters:
      aLayerType - the layer type
      Returns:
      this builder
      See Also:

    • icon

      public TLspShapeLayerBuilder icon(ILcdIcon aIcon)
      Description copied from class: ALspLayerBuilder
      Sets the icon of the layer.

      The default value is null.

      Overrides:
      icon in class ALspLayerBuilder
      Parameters:
      aIcon - the icon
      Returns:
      this builder
      See Also:

    • layerStyle

      public TLspShapeLayerBuilder layerStyle(TLspLayerStyle aLayerStyle)
      Description copied from class: ALspLayerBuilder
      Set a layer style to be used during the rendering of the layer. TLspLayerStyle is used to style the layer as a whole. Layer style can for example modify the transparency of a layer. Also, layer style can be modified after building the layer by calling ILspLayer.setLayerStyle(TLspLayerStyle).
      Overrides:
      layerStyle in class ALspLayerBuilder
      Parameters:
      aLayerStyle - the layer style. Must not be null. If you want to set the default layer style, set TLspLayerStyle.newBuilder().build()
      Returns:
      this
      See Also: