Package com.luciad.view.lightspeed.label.algorithm.discrete

Class TLspOnPathLabelingAlgorithm

java.lang.Object
com.luciad.view.lightspeed.label.algorithm.discrete.ALspDiscreteLabelingAlgorithm
com.luciad.view.lightspeed.label.algorithm.discrete.TLspOnPathLabelingAlgorithm
All Implemented Interfaces:
ILcdCloneable, ILspLabelingAlgorithm, Cloneable
public class TLspOnPathLabelingAlgorithm extends ALspDiscreteLabelingAlgorithm

Labeling algorithm that tries to place labels on path. This algorithm checks the painted paths that are within the view and tries to add label placements to them. It places them on the path. To do this it first tries to add a label in the middle of the path. Labels on one path can have a minimal distance, see setMinimumGap.

There are a few ways to determine on which side of the path the label lies, see setAlignmentMode.

The used label painter must be an ILspStampLocationLabelPainter. If not, the label will not be placed. The placed label location will be a TLspStampLabelLocation.

Since:
2012.0

  • Constructor Details

    • TLspOnPathLabelingAlgorithm

      public TLspOnPathLabelingAlgorithm()
      Create a new on path algorithm that can be used to place labels on or along paths. These paths are created by a default path provider that discretizes the anchor of a label (see ILspLabelPainter.getAnchorObject) or the domain object if no anchor is defined explicitly.

  • Method Details

    • setQuality

      public void setQuality(double aQuality)
      Description copied from class: ALspDiscreteLabelingAlgorithm

      Sets the quality. If the quality setting is high, the algorithm will try to place more labels. If it is low, the algorithm will only try to place a small portion of the labels, making label placement faster. Setting the quality to e.g. 0.5 can dramatically improve the label placement performance in some cases.

      E.g. it is possible that due to the quality setting, this algorithm will only try to place 10% of the labels. This may still result in high quality results, but this depends on the used data. In general, using a lower quality setting will still work well when the data (and its labels) are distributed uniformly over the screen.

      By default, the quality is set to 1.0.

      Specified by:
      setQuality in class ALspDiscreteLabelingAlgorithm
      Parameters:
      aQuality - the new quality. This is a number in [0, 1].
      See Also:

    • getQuality

      public double getQuality()
      Description copied from class: ALspDiscreteLabelingAlgorithm
      Returns the quality setting.
      Specified by:
      getQuality in class ALspDiscreteLabelingAlgorithm
      Returns:
      the quality setting.
      See Also:

    • isReusePreviousLocations

      public boolean isReusePreviousLocations()
      Returns if this algorithm reuses the previous label locations.
      Returns:
      true if this algorithm reuses the previous label locations.
      See Also:

    • setReusePreviousLocations

      public void setReusePreviousLocations(boolean aReusePreviousLocations)
      When set to true, this algorithm will try to reuse the previous label locations. Reusing previous label locations causes the labels to be more stable, i.e. labels don't always move when for example the view is panned, or when objects are selected. This is because label positions are only recalculated when the previous label location has become invalid.

      When using this option, getMinimumGap() will still be respected. Because of this the previous label location will not be reused in some cases.

      Trying to place a label at the previous label location will count as one attempt out of getMaximumAttemptCount(). The previous label location will always be attempted first.

      The default value is true.

      Parameters:
      aReusePreviousLocations - true to enable reusing previous label locations, and false to disable it.
      See Also:

    • getMinimumGap

      public double getMinimumGap()
      Returns the minimum gap between two labels on the same path.
      Returns:
      the minimum gap between two labels on the same path.
      See Also:

    • setMinimumGap

      public void setMinimumGap(double aMinimumGap)
      Sets the minimum gap between two labels on the same path. This distance is expressed in pixels and should be positive.

      The default value is 100 pixels.

      Parameters:
      aMinimumGap - the minimal gap between two labels on the same path.

    • getMinimumPathLength

      public double getMinimumPathLength()
      Returns the minimum length for a clipped path to contain a label.
      Returns:
      the minimum length for a clipped path to contain a label.
      See Also:

    • setMinimumPathLength

      public void setMinimumPathLength(double aMinimumPathLength)
      Sets the minimum length for a clipped path to contain a label. This length is expressed in pixels and should be positive. When a clipped path has a length smaller than the given length, no label will be placed on it.

      The default value is 0 pixels, i.e. no path will be excluded from being placed.

      Parameters:
      aMinimumPathLength - the minimal length for a clipped path to contain a label.

    • getMaximumAttemptCount

      public int getMaximumAttemptCount()
      Returns the maximum number of TLspLabelPlacements tried to place a label.
      Returns:
      the maximum number of TLspLabelPlacements tried to place a label.
      See Also:

    • setMaximumAttemptCount

      public void setMaximumAttemptCount(int aMaximumAttemptCount)
      Sets the maximum number of TLspLabelPlacements tried to place a label. This parameter can be adjusted to tweak the performance of this algorithm. A lower value is more efficient while a higher value allows more placements, and increases the chance that a valid placement is found.

      By default this value is 8.

      Parameters:
      aMaximumAttemptCount - the maximum number of TLspLabelPlacements tried to place a label.
      See Also:

    • getAlignmentMode

      public TLspOnPathLabelingAlgorithm.Alignment getAlignmentMode()
      Returns the alignment used for the placed labels.
      Returns:
      the alignment used for the placed labels.
      See Also:

    • setAlignmentMode

      public void setAlignmentMode(TLspOnPathLabelingAlgorithm.Alignment aAlignmentMode)
      Sets the alignment for the placed labels. In case this value is INSIDE, OUTSIDE, LEFT, RIGHT, ABOVE or BELOW, the label is offset in the direction perpendicular to the path by half of its height and an additional offset ( see getAdditionalOffset()).

      By default, this value is CENTER

      Parameters:
      aAlignmentMode - the alignment for the placed labels.

    • getAdditionalOffset

      public double getAdditionalOffset()
      Returns the additional offset value.
      Returns:
      the additional offset value.
      See Also:

    • setAdditionalOffset

      public void setAdditionalOffset(double aAdditionalOffset)
      Sets an additional offset value. This offset is only used when the alignment mode (getAlignmentMode()) is either OUTSIDE, INSIDE, LEFT, RIGHT, ABOVE or BELOW. The offset determines the distance in pixels of the label from the path. The given distance should be a positive value.

      The default value is 1.0.

      Parameters:
      aAdditionalOffset - an additional offset value.

    • isAllowUpsideDown

      public boolean isAllowUpsideDown()
      Returns if it is allowed for this algorithm to place labels upside down.
      Returns:
      if it is allowed for this algorithm to place labels upside down.
      See Also:

    • setAllowUpsideDown

      public void setAllowUpsideDown(boolean aAllowUpsideDown)
      Sets if it is allowed for this algorithm to place labels upside down. If set to true, there is no restriction on the rotation of the labels. If set to false, labels that are rotated upside down are rotated 180 degrees around their center. In this context, upside down means that the rotation of the label lies between 90 and 270 degrees, assuming that 0 degrees lies at 3 'o clock.

      The default value is false.

      Parameters:
      aAllowUpsideDown - true to allow labels being painted upside done, and false otherwise.
      See Also:

    • isAllowRotation

      public boolean isAllowRotation()
      Returns if it is allowed for this algorithm to rotate labels.
      Returns:
      if it is allowed for this algorithm to rotate labels.
      See Also:

    • setAllowRotation

      public void setAllowRotation(boolean aAllowRotation)
      Sets if it is allowed for this algorithm to rotate labels. If set to true, labels will be rotated in order to follow the path. If set to false, labels will not be rotated, and will be placed on the path.

      The default value is true.

      Parameters:
      aAllowRotation - true to allow labels to be rotated, and false otherwise.
      See Also:

    • clone

      public TLspOnPathLabelingAlgorithm clone()
      Description copied from interface: ILcdCloneable

      Makes Object.clone() public.

      When for example extending from java.lang.Object, it can be implemented like this: 
      
 public Object clone() {
   try {
     return super.clone();
   } catch ( CloneNotSupportedException e ) {
     // Cannot happen: extends from Object and implements Cloneable (see also Object.clone)
     throw new RuntimeException( e );
   }
 }
      Specified by:
      clone in interface ILcdCloneable
      Overrides:
      clone in class ALspDiscreteLabelingAlgorithm
      See Also:

    • createLabelIterator

      protected Iterator<TLspLabelID> createLabelIterator(List<TLspLabelID> aLabels, ILspLabelingAlgorithm.LabelContext aLabelContext, ILspLabelConflictChecker aConflictChecker, ILspView aView)
      Description copied from class: ALspDiscreteLabelingAlgorithm
      Creates a new Iterator that iterates over the TLspLabelIDs. The abstract algorithm will continue iterating over TLspLabelIDs as long as Iterator.hasNext() returns true. When it returns false, no more label placements will be tried, and placeLabels returns. Iterator.hasNext() should always be called before calling Iterator.next(), and if it returns true, Iterator.next() should never return null.

      The implementation of this method should be as independent as possible. It should not rely on createLabelPlacementIterator or createLabelPlacementEvaluator. Not respecting this might result in unexpected behaviour when wrapping or extending this class.

      Override this method to provide a custom implementation.

      Specified by:
      createLabelIterator in class ALspDiscreteLabelingAlgorithm
      Parameters:
      aLabels - a list of labels that need to be placed.
      aLabelContext - the label info object.
      aConflictChecker - the conflict checker to be used when evaluating placements.
      aView - the view.
      Returns:
      a new Iterator that iterates over TLspLabelIDs.

    • createLabelPlacementIterator

      protected Iterator<TLspLabelPlacement> createLabelPlacementIterator(TLspLabelID aLabel, ALspLabelLocations aCurrentLabelLocations, ILspLabelingAlgorithm.LabelContext aLabelContext, ILspLabelConflictChecker aConflictChecker, ILspView aView)
      Description copied from class: ALspDiscreteLabelingAlgorithm
      Creates a new Iterator that iterates over the TLspLabelPlacements for the given label. The abstract algorithm will continue iterating over TLspLabelPlacements as long as Iterator.hasNext() returns true. When it returns false, a new label will be tried. Iterator.hasNext() should always be called before calling Iterator.next(), and if it returns true, Iterator.next() should never return null.

      The implementation of this method should be as independent as possible. It should not rely on createLabelIterator or createLabelPlacementEvaluator. Not respecting this might result in unexpected behaviour when wrapping or extending this class.

      The returned TLspLabelPlacement should be correctly initialized, that is it should at least be able to return a valid label location, bounds rectangle and bounds rotation. It should also reference its corresponding TLspLabelID.

      Override this method to provide a custom implementation.

      Specified by:
      createLabelPlacementIterator in class ALspDiscreteLabelingAlgorithm
      Parameters:
      aLabel - the identifier for which an iterator should be created.
      aCurrentLabelLocations - an ALspLabelLocations object containing locations for the currently placed labels.
      aLabelContext - the label info object.
      aConflictChecker - the conflict checker to be used when evaluating placements.
      aView - the view.
      Returns:
      a new Iterator that iterates over TLspLabelPlacements.

    • createLabelPlacementEvaluator

      protected ILspLabelPlacementEvaluator createLabelPlacementEvaluator(List<TLspLabelID> aLabels, ILspLabelingAlgorithm.LabelContext aLabelContext, ILspLabelConflictChecker aConflictChecker, ILspView aView)
      Description copied from class: ALspDiscreteLabelingAlgorithm
      Creates a new ILspLabelPlacementEvaluator using the given parameters. It evaluates the placements returned by createLabelPlacementIterator, and returns a PlacementResult to denote if the placement should be used for its label or not.

      The following actions are undertaken for the following placement results :

      Override this method to provide a custom implementation.

      Specified by:
      createLabelPlacementEvaluator in class ALspDiscreteLabelingAlgorithm
      Parameters:
      aLabels - a list of labels.
      aLabelContext - the label info object.
      aConflictChecker - the conflict checker to be used when evaluating placements.
      aView - the view
      Returns:
      a new ILspLabelPlacementEvaluator.
      See Also: