Package com.luciad.view.gxy.labeling.algorithm.discrete

Class TLcdGXYFixedOnPathLabelingAlgorithm

java.lang.Object
com.luciad.view.gxy.labeling.algorithm.discrete.ALcdGXYDiscretePlacementsLabelingAlgorithm
com.luciad.view.gxy.labeling.algorithm.discrete.TLcdGXYFixedOnPathLabelingAlgorithm
All Implemented Interfaces:
ILcdCloneable, ILcdGXYLabelingAlgorithm, Cloneable
public final class TLcdGXYFixedOnPathLabelingAlgorithm extends ALcdGXYDiscretePlacementsLabelingAlgorithm
A path labeling algorithm that places a label at a fixed location along a path. The fixed location is defined by a relative position between the start and end of the path.

Labels can be aligned left, center, or right relative to a specific point on the path, determined by the relative path position property (a value between 0.0 and 1.0). This property specifies the anchor point along the path geometry for label placement.

Vertical alignment modes (TLcdGXYFixedOnPathLabelingAlgorithm.VerticalAlignment.ABOVE, TLcdGXYFixedOnPathLabelingAlgorithm.VerticalAlignment.CENTER, TLcdGXYFixedOnPathLabelingAlgorithm.VerticalAlignment.BELOW) control the label's position perpendicular to the path. Horizontal alignment modes (TLcdGXYFixedOnPathLabelingAlgorithm.HorizontalAlignment.LEFT, TLcdGXYFixedOnPathLabelingAlgorithm.HorizontalAlignment.CENTER, TLcdGXYFixedOnPathLabelingAlgorithm.HorizontalAlignment.RIGHT) control the label's position along the path's tangent.

Customizable horizontal and vertical offsets provide precise control over label placement. The anchor point determines where on the path the label is placed; alignment modes and offsets control the label's position relative to that anchor. Alignment does not affect the anchor’s location.

This class is useful for applications requiring precise label placement along paths, such as cartographic mapping where labels must follow the curvature of roads, rivers, and similar features.

Choosing between TLcdGXYOnPathLabelingAlgorithm and TLcdGXYFixedOnPathLabelingAlgorithm:

  • TLcdGXYOnPathLabelingAlgorithm automatically finds optimal label positions along the path, balancing readability and collision avoidance. Use this for dynamic, automated labeling where label density and overlap are concerns.
  • TLcdGXYFixedOnPathLabelingAlgorithm places labels at a fixed, user-specified relative position along the path, with explicit horizontal/vertical alignment and offset. Use this for precise, repeatable label placement (e.g., cartographic standards).
  • TLcdGXYFixedOnPathLabelingAlgorithm offers separate horizontal and vertical alignment and offset controls, while the TLcdGXYOnPathLabelingAlgorithm provides general alignment modes (center, inside, outside, left, right, above, below).
  • TLcdGXYOnPathLabelingAlgorithm can reuse previous label locations for stability during view changes; TLcdGXYFixedOnPathLabelingAlgorithm always places at the specified position.
Since:
2026.0
See Also:

  • Constructor Details

    • TLcdGXYFixedOnPathLabelingAlgorithm

      public TLcdGXYFixedOnPathLabelingAlgorithm(double aRelativeLocation, TLcdGXYFixedOnPathLabelingAlgorithm.VerticalAlignment aVerticalAlignment, TLcdGXYFixedOnPathLabelingAlgorithm.HorizontalAlignment aHorizontalAlignment, double aVerticalOffset, double aHorizontalOffset)
      Creates a new path labeling algorithm with the specified parameters. The labels are not placed along view bounds.The default path provider TLcdGXYLabelingPathProvider is used. The relative location must be between 0.0 and 1.0 where 0.0 represents the start of the path and 1.0 the end of the path.
      Parameters:
      aRelativeLocation - The relative location along the path (0.0 to 1.0).
      aVerticalAlignment - The vertical alignment of the label relative to the path.
      aHorizontalAlignment - The horizontal alignment of the label relative to the path point.
      aVerticalOffset - The vertical offset in pixels from the aligned position.
      aHorizontalOffset - The horizontal offset in pixels from the aligned position.

    • TLcdGXYFixedOnPathLabelingAlgorithm

      public TLcdGXYFixedOnPathLabelingAlgorithm(double aRelativeLocation, TLcdGXYFixedOnPathLabelingAlgorithm.VerticalAlignment aVerticalAlignment, TLcdGXYFixedOnPathLabelingAlgorithm.HorizontalAlignment aHorizontalAlignment, double aVerticalOffset, double aHorizontalOffset, ILcdGXYLabelingPathProvider aPathProvider)
      Creates a new path labeling algorithm with the specified parameters. The relative location must be between 0.0 and 1.0 where 0.0 represents the start of the path and 1.0 the end of the path.
      Parameters:
      aRelativeLocation - The relative location along the path (0.0 to 1.0).
      aVerticalAlignment - The vertical alignment of the label relative to the path.
      aHorizontalAlignment - The horizontal alignment of the label relative to the path point.
      aVerticalOffset - The vertical offset in pixels from the aligned position.
      aHorizontalOffset - The horizontal offset in pixels from the aligned position.
      aPathProvider - The path provider to use for labeling.

  • Method Details

    • getHorizontalAlignment

      public TLcdGXYFixedOnPathLabelingAlgorithm.HorizontalAlignment getHorizontalAlignment()
      Gets the horizontal alignment of the label relative to the point on the path.
      Returns:
      The horizontal alignment.

    • setHorizontalAlignment

      public void setHorizontalAlignment(TLcdGXYFixedOnPathLabelingAlgorithm.HorizontalAlignment aHorizontalAlignment)
      Sets the horizontal alignment of the label relative to the point on the path.
      Parameters:
      aHorizontalAlignment - The desired horizontal alignment.

    • getHorizontalOffset

      public double getHorizontalOffset()
      Gets the horizontal offset in pixels from the aligned position.
      Returns:
      The horizontal offset.

    • setHorizontalOffset

      public void setHorizontalOffset(double aHorizontalOffset)
      Sets the horizontal offset in pixels from the aligned position. The offset is applied along the tangent of the path at the label position.
      Parameters:
      aHorizontalOffset - The desired horizontal offset.

    • getVerticalAlignment

      public TLcdGXYFixedOnPathLabelingAlgorithm.VerticalAlignment getVerticalAlignment()
      Gets the vertical alignment of the label relative to the path.
      Returns:
      The vertical alignment.

    • setVerticalAlignment

      public void setVerticalAlignment(TLcdGXYFixedOnPathLabelingAlgorithm.VerticalAlignment aVerticalAlignment)
      Sets the vertical alignment of the label relative to the path.
      Parameters:
      aVerticalAlignment - The desired vertical alignment.

    • getVerticalOffset

      public double getVerticalOffset()
      Gets the vertical offset in pixels from the aligned position.
      Returns:
      The vertical offset.

    • setVerticalOffset

      public void setVerticalOffset(double aVerticalOffset)
      Sets the vertical offset in pixels from the aligned position. The offset is applied perpendicular to the path at the label position.
      Parameters:
      aVerticalOffset - The desired vertical offset.

    • getRelativePathPosition

      public double getRelativePathPosition()
      Gets the relative position along the path where the label is placed.
      Returns:
      The relative path position (between 0.0 and 1.0).

    • setRelativePathPosition

      public void setRelativePathPosition(double aRelativePathPosition)
      Sets the relative position along the path where the label is anchored. The value must be between 0.0 (start of the path) and 1.0 (end of the path), inclusive. This property determines the anchor point for label placement along the path geometry, independent of alignment or offset settings.
      Parameters:
      aRelativePathPosition - the desired relative path position, between 0.0 and 1.0 inclusive
      Throws:
      IllegalArgumentException - if the value is outside the range [0.0, 1.0]

    • 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, it will not be labeled.

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

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

    • isAllowLabelsUpsideDown

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

    • setAllowLabelsUpsideDown

      public void setAllowLabelsUpsideDown(boolean aAllowLabelsUpsideDown)
      Sets if it is allowed for this labeling 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:
      aAllowLabelsUpsideDown - true to allow labels being painted upside done, and false otherwise.
      See Also:

    • isAllowRotation

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

    • setAllowRotation

      public void setAllowRotation(boolean aAllowRotation)
      Sets if it is allowed for this labeling 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:

    • getPathProvider

      public ILcdGXYLabelingPathProvider getPathProvider()
      Returns the path provider used by this path labeling algorithm.
      Returns:
      the path provider used by this path labeling algorithm.

    • setPathProvider

      public void setPathProvider(ILcdGXYLabelingPathProvider aPathProvider)
      Sets the path provider to be used by this path labeling algorithm.
      Parameters:
      aPathProvider - the path provider to be used by this path labeling algorithm.

    • clone

      public TLcdGXYFixedOnPathLabelingAlgorithm 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
      See Also:

    • collectLabelInfo

      public TLcdCollectedLabelInfoList collectLabelInfo(List<TLcdLabelIdentifier> aLabelsToCollect, Graphics aGraphics, ILcdGXYView aGXYView)
      Description copied from interface: ILcdGXYLabelingAlgorithm
      This method returns a TLcdCollectedLabelInfoList object based on the given list of TLcdLabelIdentifiers. The returned TLcdCollectedLabelInfoList should contain a TLcdCollectedLabelInfo object for each label that should be placed.

      Each TLcdCollectedLabelInfo should also contain all information needed by computeLabelPlacements to place the labels. In order to enable correct asynchronous label placing, all calls to the layer and the (label) painters should be done in this method. The results should then be stored in the info objects.

      It is possible that the returned TLcdCollectedLabelInfoList doesn't contain a TLcdCollectedLabelInfo object for every given TLcdLabelIdentifier. In that case the missing labels are not placed.

      Specified by:
      collectLabelInfo in interface ILcdGXYLabelingAlgorithm
      Parameters:
      aLabelsToCollect - the labels for which a TLcdCollectedLabelInfoList should be created.
      aGraphics - the graphics.
      aGXYView - the view.
      Returns:
      a TLcdCollectedLabelInfoList which contains all the information needed to place the labels.

    • createLabelIterator

      protected Iterator<TLcdCollectedLabelInfo> createLabelIterator(TLcdCollectedLabelInfoList aLabelInfoList, ILcdLabelConflictChecker aBoundsConflictChecker, ILcdGXYView aView)
      Description copied from class: ALcdGXYDiscretePlacementsLabelingAlgorithm
      Creates a new Iterator that iterates over the TLcdCollectedLabelInfos. The abstract labeling algorithm will continue iterating over TLcdCollectedLabelInfos as long as Iterator.hasNext() returns true. When it returns false, no more labels will be tried, and computeLabelPlacements 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.

      The returned TLcdCollectedLabelInfo should be correctly initialized, i.e. it should contain all information needed to create valid TLcdLabelPlacements using createLabelPlacementIterator. It should also always point to its corresponding TLcdCollectedLabeledObjectInfo.

      Override this method to provide a custom implementation.

      Specified by:
      createLabelIterator in class ALcdGXYDiscretePlacementsLabelingAlgorithm
      Parameters:
      aLabelInfoList - the label infos object that contains all information needed to place the labels.
      aBoundsConflictChecker - the bounds conflict checker to be used when evaluating label placements.
      aView - the view.
      Returns:
      a new Iterator that iterates over TLcdCollectedLabelInfos.

    • createLabelPlacementIterator

      protected Iterator<TLcdLabelPlacement> createLabelPlacementIterator(TLcdCollectedLabelInfo aLabel, TLcdCollectedLabelInfoList aLabelInfoList, ILcdLabelConflictChecker aBoundsConflictChecker, ILcdGXYView aView)
      Description copied from class: ALcdGXYDiscretePlacementsLabelingAlgorithm
      Creates a new Iterator that iterates over the TLcdLabelPlacements for the given label. The abstract labeling algorithm will continue iterating over TLcdLabelPlacements 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 TLcdLabelPlacement should be correctly initialized, i.e. it should at least be able to return a valid label location, bounds rectangle and bounds rotation. It should also reference its corresponding TLcdCollectedLabelInfo.

      Override this method to provide a custom implementation.

      Specified by:
      createLabelPlacementIterator in class ALcdGXYDiscretePlacementsLabelingAlgorithm
      Parameters:
      aLabel - the label for which an iterator should be created.
      aLabelInfoList - the info object that contains all information needed to place the labels.
      aBoundsConflictChecker - the bounds conflict checker to be used when evaluating label placements.
      aView - the view.
      Returns:
      a new Iterator that iterates over TLcdLabelPlacements.

    • createLabelPlacementEvaluator

      protected ILcdLabelPlacementEvaluator createLabelPlacementEvaluator(TLcdCollectedLabelInfoList aLabelInfoList, ILcdLabelConflictChecker aBoundsConflictChecker, ILcdGXYView aView)
      Description copied from class: ALcdGXYDiscretePlacementsLabelingAlgorithm
      Creates a new ILcdLabelPlacementEvaluator 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 ALcdGXYDiscretePlacementsLabelingAlgorithm
      Parameters:
      aLabelInfoList - the info object that contains all information needed to place the labels.
      aBoundsConflictChecker - the bounds conflict checker to be used when evaluating label placements.
      aView - the view
      Returns:
      a new LabelPlacementEvaluator
      See Also:

    • getLabelPriorityProvider

      public ILcdGXYMultiLabelPriorityProvider getLabelPriorityProvider()
      Returns the label placing priority provider.
      Returns:
      the label placing priority provider.
      See Also:

    • setLabelPriorityProvider

      public void setLabelPriorityProvider(ILcdGXYMultiLabelPriorityProvider aLabelPriorityProvider)
      Sets the label placing priority provider, specifying the priority for individual labels. This priority provider specifies the order in which labels are placed. In the event labels overlap, those with higher priority are painted on top of labels with lower priority. So lower priority labels are the first candidates if labels need to be obscured.

      When no label priority provider is set, no label priorities are set.

      The priority provider is used to sort the list of labels before their placements are computed.

      Parameters:
      aLabelPriorityProvider - The priority provider to set.