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
.
Modifier and Type | Class and Description |
---|---|
static class |
TLspOnPathLabelingAlgorithm.Alignment
Alignment mode that determines if labels are placed on, outside or inside
the paths.
|
ILspLabelingAlgorithm.LabelContext
CONSECUTIVE_LABEL_CONFLICT_FAIL_COUNT_KEY, CONSECUTIVE_LABEL_FAIL_COUNT_KEY, LABEL_ATTEMPT_COUNT_KEY, LABEL_CONFLICT_FAIL_COUNT_KEY, LABEL_FAIL_COUNT_KEY, LABEL_PLACED_COUNT_KEY, TOTAL_LABEL_COUNT_KEY
Constructor and Description |
---|
TLspOnPathLabelingAlgorithm()
Create a new on path algorithm that can be used to place labels
on or along paths.
|
Modifier and Type | Method and Description |
---|---|
TLspOnPathLabelingAlgorithm |
clone()
Makes
Object.clone() public. |
protected Iterator<TLspLabelID> |
createLabelIterator(List<TLspLabelID> aLabels,
ILspLabelingAlgorithm.LabelContext aLabelContext,
ILspLabelConflictChecker aConflictChecker,
ILspView aView)
Creates a new
Iterator that iterates over the TLspLabelID s. |
protected ILspLabelPlacementEvaluator |
createLabelPlacementEvaluator(List<TLspLabelID> aLabels,
ILspLabelingAlgorithm.LabelContext aLabelContext,
ILspLabelConflictChecker aConflictChecker,
ILspView aView)
Creates a new
ILspLabelPlacementEvaluator using the given parameters. |
protected Iterator<TLspLabelPlacement> |
createLabelPlacementIterator(TLspLabelID aLabel,
ALspLabelLocations aCurrentLabelLocations,
ILspLabelingAlgorithm.LabelContext aLabelContext,
ILspLabelConflictChecker aConflictChecker,
ILspView aView)
Creates a new
Iterator that iterates over the TLspLabelPlacement s for
the given label. |
double |
getAdditionalOffset()
Returns the additional offset value.
|
TLspOnPathLabelingAlgorithm.Alignment |
getAlignmentMode()
Returns the alignment used for the placed labels.
|
int |
getMaximumAttemptCount()
Returns the maximum number of
TLspLabelPlacement s 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.
|
double |
getQuality()
Returns the quality setting.
|
boolean |
isAllowRotation()
Returns if it is allowed for this algorithm to rotate labels.
|
boolean |
isAllowUpsideDown()
Returns if it is allowed for this algorithm to place labels upside down.
|
boolean |
isReusePreviousLocations()
Returns if this algorithm reuses the previous label locations.
|
void |
setAdditionalOffset(double aAdditionalOffset)
Sets an additional offset value.
|
void |
setAlignmentMode(TLspOnPathLabelingAlgorithm.Alignment aAlignmentMode)
Sets the alignment for the placed labels.
|
void |
setAllowRotation(boolean aAllowRotation)
Sets if it is allowed for this algorithm to rotate labels.
|
void |
setAllowUpsideDown(boolean aAllowUpsideDown)
Sets if it is allowed for this algorithm to place labels upside down.
|
void |
setMaximumAttemptCount(int aMaximumAttemptCount)
Sets the maximum number of
TLspLabelPlacement s 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 |
setQuality(double aQuality)
Sets the quality.
|
void |
setReusePreviousLocations(boolean aReusePreviousLocations)
When set to
true , this algorithm will try to reuse the previous label locations. |
placeLabels
public TLspOnPathLabelingAlgorithm()
ILspLabelPainter.getAnchorObject
) or the domain object if no anchor is defined explicitly.public void setQuality(double aQuality)
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.
setQuality
in class ALspDiscreteLabelingAlgorithm
aQuality
- the new quality. This is a number in [0, 1].ALspDiscreteLabelingAlgorithm.getQuality()
public double getQuality()
ALspDiscreteLabelingAlgorithm
getQuality
in class ALspDiscreteLabelingAlgorithm
ALspDiscreteLabelingAlgorithm.setQuality(double)
public boolean isReusePreviousLocations()
true
if this algorithm reuses the previous label locations.isReusePreviousLocations()
public void setReusePreviousLocations(boolean aReusePreviousLocations)
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
.
aReusePreviousLocations
- true
to enable reusing previous label locations,
and false
to disable it.isReusePreviousLocations()
public double getMinimumGap()
setMinimumGap(double)
public void setMinimumGap(double aMinimumGap)
The default value is 100 pixels.
aMinimumGap
- the minimal gap between two labels on the same path.public double getMinimumPathLength()
setMinimumPathLength(double)
public void setMinimumPathLength(double aMinimumPathLength)
The default value is 0 pixels, i.e. no path will be excluded from being placed.
aMinimumPathLength
- the minimal length for a clipped path to contain a label.public int getMaximumAttemptCount()
TLspLabelPlacement
s tried to place a label.TLspLabelPlacement
s tried to place a label.setMaximumAttemptCount(int)
public void setMaximumAttemptCount(int aMaximumAttemptCount)
TLspLabelPlacement
s 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
.
aMaximumAttemptCount
- the maximum number of TLspLabelPlacement
s tried to
place a label.getMaximumAttemptCount()
public TLspOnPathLabelingAlgorithm.Alignment getAlignmentMode()
setAlignmentMode(com.luciad.view.lightspeed.label.algorithm.discrete.TLspOnPathLabelingAlgorithm.Alignment)
public void setAlignmentMode(TLspOnPathLabelingAlgorithm.Alignment aAlignmentMode)
getAdditionalOffset()
).
By default, this value is CENTER
aAlignmentMode
- the alignment for the placed labels.public double getAdditionalOffset()
setAdditionalOffset(double)
public void setAdditionalOffset(double aAdditionalOffset)
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
.
aAdditionalOffset
- an additional offset value.public boolean isAllowUpsideDown()
setAllowUpsideDown(boolean)
public void setAllowUpsideDown(boolean aAllowUpsideDown)
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
.
aAllowUpsideDown
- true
to allow labels being painted upside
done, and false
otherwise.isAllowUpsideDown()
public boolean isAllowRotation()
setAllowRotation(boolean)
public void setAllowRotation(boolean aAllowRotation)
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
.
aAllowRotation
- true
to allow labels to be rotated, and
false
otherwise.isAllowRotation()
public TLspOnPathLabelingAlgorithm clone()
ILcdCloneable
Makes Object.clone()
public.
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 );
}
}
clone
in interface ILcdCloneable
clone
in class ALspDiscreteLabelingAlgorithm
Object.clone()
protected Iterator<TLspLabelID> createLabelIterator(List<TLspLabelID> aLabels, ILspLabelingAlgorithm.LabelContext aLabelContext, ILspLabelConflictChecker aConflictChecker, ILspView aView)
ALspDiscreteLabelingAlgorithm
Iterator
that iterates over the TLspLabelID
s. The abstract algorithm will continue
iterating over TLspLabelID
s 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.
createLabelIterator
in class ALspDiscreteLabelingAlgorithm
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.Iterator
that iterates over TLspLabelID
s.protected Iterator<TLspLabelPlacement> createLabelPlacementIterator(TLspLabelID aLabel, ALspLabelLocations aCurrentLabelLocations, ILspLabelingAlgorithm.LabelContext aLabelContext, ILspLabelConflictChecker aConflictChecker, ILspView aView)
ALspDiscreteLabelingAlgorithm
Iterator
that iterates over the TLspLabelPlacement
s for
the given label. The abstract algorithm will continue iterating over
TLspLabelPlacement
s 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.
createLabelPlacementIterator
in class ALspDiscreteLabelingAlgorithm
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.Iterator
that iterates over TLspLabelPlacement
s.protected ILspLabelPlacementEvaluator createLabelPlacementEvaluator(List<TLspLabelID> aLabels, ILspLabelingAlgorithm.LabelContext aLabelContext, ILspLabelConflictChecker aConflictChecker, ILspView aView)
ALspDiscreteLabelingAlgorithm
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 :
PlacementResult.SUCCESS
:
the given placement will be used for its label, it will be added to the list of placed
representations, and it will be added to the given ILspLabelConflictChecker
. After
that, ILspLabelPlacementEvaluator.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 ILspLabelConflictChecker
. After that, ILspLabelPlacementEvaluator.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, ILspLabelPlacementEvaluator.noPlacementApplied
is called.PlacementResult.FAILED
: the abstract algorithm will immediately call ILspLabelPlacementEvaluator.noPlacementApplied
and will not try to find other placements for the label.Override this method to provide a custom implementation.
createLabelPlacementEvaluator
in class ALspDiscreteLabelingAlgorithm
aLabels
- a list of labels.aLabelContext
- the label info object.aConflictChecker
- the conflict checker to be used when evaluating placements.aView
- the viewILspLabelPlacementEvaluator
.ILspLabelPlacementEvaluator