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

LuciadFusionClass TLcdGXYOnPathLabelingAlgorithm

java.lang.Object

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

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

All Implemented Interfaces:

ILcdCloneable, ILcdGXYLabelingAlgorithm, Cloneable

public class TLcdGXYOnPathLabelingAlgorithm
extends ALcdGXYDiscretePlacementsLabelingAlgorithm

Path aware labeling algorithm. This algorithm checks the painted paths that are within the view and tries to add labels to them. It places the labels on the path. To do this it first tries to add a label in the middle of the path. Labels on one path have a minimal distance setMinimumGap(double).

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 ILcdGXYLabelPainter2. If not, the label will be painted at an incorrect location.

The implementation of this labeling algorithm is thread-safe, as long as the set ILcdGXYLabelingPathProvider is thread-safe.

Since:

10.1

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TLcdGXYOnPathLabelingAlgorithm.AlignmentMode Alignment mode that determines if label are placed on, outside or inside the paths.

Constructor Summary

Constructors

Constructor and Description
TLcdGXYOnPathLabelingAlgorithm() Creates a new on path labeling algorithm that can be used to place labels on or along paths.
TLcdGXYOnPathLabelingAlgorithm(ILcdGXYLabelingPathProvider aPathProvider, boolean aPlaceLabelsAlongViewBounds) Creates a new on path labeling algorithm that can be used to place labels on or along paths returned by the given path provider.

Method Summary

Modifier and Type	Method and Description
TLcdGXYOnPathLabelingAlgorithm	clone() Makes Object.clone() public.
TLcdCollectedLabelInfoList	collectLabelInfo(List<TLcdLabelIdentifier> aLabelsToCollect, Graphics aGraphics, ILcdGXYView aGXYView) This method returns a TLcdCollectedLabelInfoList object based on the given list of TLcdLabelIdentifiers.
protected Iterator<TLcdCollectedLabelInfo>	createLabelIterator(TLcdCollectedLabelInfoList aLabelInfoList, ILcdLabelConflictChecker aBoundsConflictChecker, ILcdGXYView aView) Creates a new Iterator that iterates over the TLcdCollectedLabelInfos.
protected ILcdLabelPlacementEvaluator	createLabelPlacementEvaluator(TLcdCollectedLabelInfoList aLabelInfoList, ILcdLabelConflictChecker aBoundsConflictChecker, ILcdGXYView aView) Creates a new ILcdLabelPlacementEvaluator using the given parameters.
protected Iterator<TLcdLabelPlacement>	createLabelPlacementIterator(TLcdCollectedLabelInfo aLabel, TLcdCollectedLabelInfoList aLabelInfoList, ILcdLabelConflictChecker aBoundsConflictChecker, ILcdGXYView aView) Creates a new Iterator that iterates over the TLcdLabelPlacements for the given label.
double	getAdditionalOffset() Returns the additional offset value.
TLcdGXYOnPathLabelingAlgorithm.AlignmentMode	getAlignmentMode() Returns the alignment used for the placed labels.
ILcdGXYMultiLabelPriorityProvider	getLabelPriorityProvider() Returns the label placing priority provider.
int	getMaximumAttemptCount() Returns the maximum number of TLcdLabelPlacements tried to place a label.
double	getMinimumGap() Returns the minimum gap between two labels on the same path.
double	getMinimumPathLength() Returns the minimum length for a clipped path to contain a label.
ILcdGXYLabelingPathProvider	getPathProvider() Returns the path provider used by this path labeling algorithm.
boolean	isAllowLabelsUpsideDown() Returns if it is allowed for this labeling algorithm to place labels upside down.
boolean	isAllowRotation() Returns if it is allowed for this labeling algorithm to rotate labels.
boolean	isReusePreviousLocations() Returns if this algorithm reuses the previous label locations.
void	setAdditionalOffset(double aAdditionalOffset) Sets an additional offset value.
void	setAlignmentMode(TLcdGXYOnPathLabelingAlgorithm.AlignmentMode aAlignmentMode) Sets the alignment for the placed labels.
void	setAllowLabelsUpsideDown(boolean aAllowLabelsUpsideDown) Sets if it is allowed for this labeling algorithm to place labels upside down.
void	setAllowRotation(boolean aAllowRotation) Sets if it is allowed for this labeling algorithm to rotate labels.
void	setLabelPriorityProvider(ILcdGXYMultiLabelPriorityProvider aLabelPriorityProvider) Sets the label placing priority provider, specifying the priority for individual labels.
void	setMaximumAttemptCount(int aMaximumAttemptCount) Sets the maximum number of TLcdLabelPlacements tried to place a label.
void	setMinimumGap(double aMinimumGap) Sets the minimum gap between two labels on the same path.
void	setMinimumPathLength(double aMinimumPathLength) Sets the minimum length for a clipped path to contain a label.
void	setPathProvider(ILcdGXYLabelingPathProvider aPathProvider) Sets the path provider to be used by this path labeling algorithm.
void	setReusePreviousLocations(boolean aReusePreviousLocations) When set to true, this labeling algorithm will try to reuse the previous label locations.

Methods inherited from class com.luciad.view.gxy.labeling.algorithm.discrete.ALcdGXYDiscretePlacementsLabelingAlgorithm

computeLabelPlacements

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TLcdGXYOnPathLabelingAlgorithm

public TLcdGXYOnPathLabelingAlgorithm()

Creates a new on path labeling algorithm that can be used to place labels on or along paths. When using this constructor, TLcdGXYLabelingPathProvider is used as path provider and labels are not placed along the view bounds.

TLcdGXYOnPathLabelingAlgorithm

public TLcdGXYOnPathLabelingAlgorithm(ILcdGXYLabelingPathProvider aPathProvider,
                                      boolean aPlaceLabelsAlongViewBounds)

Creates a new on path labeling algorithm that can be used to place labels on or along paths returned by the given path provider.

Parameters:

aPathProvider - a path provider.

aPlaceLabelsAlongViewBounds - true if labels should also be placed along the view bounds, or false otherwise.

Method Detail

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(double)

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(double)

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.

getMaximumAttemptCount

public int getMaximumAttemptCount()

Returns the maximum number of TLcdLabelPlacements tried to place a label.

Returns:

the maximum number of TLcdLabelPlacements tried to place a label.

See Also:

setMaximumAttemptCount(int)

setMaximumAttemptCount

public void setMaximumAttemptCount(int aMaximumAttemptCount)

Sets the maximum number of TLcdLabelPlacements tried to place a label. This parameter can be adjusted to tweak the performance of this labeling algorithm. A lower value is more efficient while a higher value allows more placements, and increases the chance that a valid label placement is found.

By default this value is 8.

Parameters:

aMaximumAttemptCount - the maximum number of TLcdLabelPlacements tried to place a label.

See Also:

getMaximumAttemptCount()

getAlignmentMode

public TLcdGXYOnPathLabelingAlgorithm.AlignmentMode getAlignmentMode()

Returns the alignment used for the placed labels.

Returns:

the alignment used for the placed labels.

See Also:

setAlignmentMode(AlignmentMode)

setAlignmentMode

public void setAlignmentMode(TLcdGXYOnPathLabelingAlgorithm.AlignmentMode aAlignmentMode)

Sets the alignment for the placed labels. In case this value is INSIDE or 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(double)

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.

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(boolean)

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:

isAllowLabelsUpsideDown()

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(boolean)

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:

isAllowRotation()

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.

getLabelPriorityProvider

public ILcdGXYMultiLabelPriorityProvider getLabelPriorityProvider()

Returns the label placing priority provider.

Returns:

the label placing priority provider.

See Also:

setLabelPriorityProvider(com.luciad.view.gxy.ILcdGXYMultiLabelPriorityProvider)

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, a default label priority provider is used which returns Integer.MAX_VALUE for all labels.

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

Parameters:

aLabelPriorityProvider - The priority provider to set.

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:

isReusePreviousLocations()

setReusePreviousLocations

public void setReusePreviousLocations(boolean aReusePreviousLocations)

When set to true, this labeling algorithm will try to reuse the previous label locations. Reusing previous label locations causes the labels to be some more stable, i.e. labels don't always move when for example the view is panned, or when labeled 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.

Note: For this option to work, the domain objects for which labels are placed should implement ILcdCache. When they do not implement ILcdCache the labels of those domain object behave as if this option is set to false.

The default value is false.

Parameters:

aReusePreviousLocations - true to enable reusing previous label locations, and false to disable it.

See Also:

isReusePreviousLocations()

clone

public TLcdGXYOnPathLabelingAlgorithm 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:

Object.clone()

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 :

• PlacementResult.SUCCESS : the given label placement will be used for its label, it will be added to the list of placed labels, and it will be added to the given ILcdLabelConflictChecker. After that, ILcdLabelPlacementEvaluator.placementApplied will be called and no more placements are tried for the label.
• PlacementResult.FALLBACK : the abstract algorithm will try to find an other placements which returns PlacementResult.SUCCESS. When no such placement is found, this placement will be added to the list of placed labels, and it will be added to the given ILcdLabelConflictChecker. After that, ILcdLabelPlacementEvaluator.placementApplied will be called.
• PlacementResult.TRY_NEW_PLACEMENT : the abstract algorithm will try to find an other placement which returns PlacementResult.SUCCESS or PlacementResult.FALLBACK. When no such placement is found, ILcdLabelPlacementEvaluator.noPlacementApplied is called.
• PlacementResult.FAILED : the abstract algorithm will immediately call ILcdLabelPlacementEvaluator.noPlacementApplied and will not try to find other placements for the label.

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:

ILcdLabelPlacementEvaluator