public abstract class IlvAnnealingLabelDescriptor extends Object
IlvAnnealingLabelDescriptor
is the abstract
base class of all label descriptors. A label descriptor is used to
describe how a label can move during the Simulated Annealing label
layout. One subclass is for instance the
IlvAnnealingPointLabelDescriptor
that is used to describe
that a label must be placed close to a fixed point, as for instance
needed to label the cities of a map. Another subclass is the
IlvAnnealingPolylineLabelDescriptor
that is used to
describe that a label must be placed near a polyline link of a graph.
Simulated Annealing moves the label basically on a path. It allows the
label to leave the path in a very close area, so the actual position
can be described by a point on the path plus the distance of the label
from this path. For instance, for the
IlvAnnealingPointLabelDescriptor
, the path may be
approximately a circle (in fact, it is an elliptically rounded
rectangle), that is, the label can move along this path around the
reference point of the label. To simplify the implementation of
different paths, the Simulated Annealing does not use Cartesian
coordinates, it only specifies the abstract path location (the
distance you have to go along the path from the start point of the
path to the current path point), and the distance from this path
point. The translation of this abstract location into the
effective Cartesian coordinates of the label is done by the
implementation of the method setPosition(double, double)
.
This allows you to use the algorithm with different paths, by
subclassing the IlvAnnealingLabelDescriptor
and
implementing your version of setPosition(double, double)
.
For instance, assume that the label should move on a circle between radius 10 and 15 around the origin. The following code implements a corresponding label descriptor:
public class MyCircleLabelDescriptor extends IlvAnnealingLabelDescriptor { public MyCircleLabelDescriptor(Object label) { super(label); } public void initialize(IlvLabelingModel labelingModel) { // set the maximum location: // circumference of circle with radius 10 maxPathLocation = 2 * Math.PI * 10; // path is at radius 10, hence max distance from path is (15 - 10) = 5 maxDistFromPath = 5; } public void setPosition(double pathLocation, double distFromPath) { // path radius is 10. Radius for position is 10 + distFromPath, // because distFromPath is between 0 and 5 updatePosition( (double)((10 + distFromPath) * Math.cos(pathLocation / 10)); (double)((10 + distFromPath) * Math.sin(pathLocation / 10)) ); actPathLocation = pathLocation; actDistFromPath = distFromPath; } // assume that the preferred position is the path location 0 and distance // 0 from the path. public void setTowardsPreferredPosition( double pathLocation, double distFromPath, int i, int maxI) { if (pathLocation <= maxPathLocation/2) { // clockwise towards the preferred position setPosition(pathLocation - pathLocation * (i+1) / maxI, distFromPath - distFromPath * (i+1) / maxI); } else { // counter-clockwise towards the preferred position setPosition(pathLocation + pathLocation * (i+1) / maxI, distFromPath + distFromPath * (i+1) / maxI); } } }
Modifier and Type | Field and Description |
---|---|
protected double |
actDistFromPath
The actual distance of the label from the location on the path that is
given by the variable
actPathLocation . |
protected double |
actPathLocation
The actual location on the path for the label.
|
static int |
IGNORED
This option is used internally by the
IlvSDMEngine . |
static int |
LABEL
This option is used internally by the
IlvSDMEngine . |
protected double |
maxDistFromPath
The maximum distance of the label from the location on the path that
is given by the variable
actPathLocation . |
protected double |
maxPathLocation
The maximum location on the path for the label.
|
static int |
OBSTACLE
This option is used internally by the
IlvSDMEngine . |
Constructor and Description |
---|
IlvAnnealingLabelDescriptor(IlvAnnealingLabelDescriptor d)
Creates a copy of a label descriptor.
|
IlvAnnealingLabelDescriptor(Object label)
Creates a new instance of a label descriptor.
|
Modifier and Type | Method and Description |
---|---|
boolean |
considerObstacle(Object obstacle)
Returns
true if the overlap between the label and the
input obstacle should be considered during the quality calculation of
the Simulated Annealing label layout algorithm. |
abstract IlvAnnealingLabelDescriptor |
copy()
Returns a copy of this label descriptor.
|
double |
getActDistFromPath()
Returns the actual distance of the label from the location on the path
that is given by the property
actPathLocation . |
double |
getActPathLocation()
Returns the actual location on the path for the label.
|
Object |
getLabel()
Returns the label of the descriptor.
|
double |
getMaxDistFromPath()
Returns the maximum distance from the location on the path.
|
double |
getMaxPathLocation()
Returns the maximum location on the path for the label.
|
protected double |
getMinDist(Object obstacle,
double min)
Returns the minimum distance value between this label and the input
obstacle.
|
double |
getPreferredDistFromPath()
Returns the preferred distance from the location on the path.
|
double |
getPreferredPathLocation()
Returns the preferred location on the path.
|
Object |
getRelatedObstacle()
Returns the related obstacle of the label descriptor.
|
double |
getRotation(IlvLabelingModel model,
IlvRect labelRect)
Returns the rotation of the label if it were placed at the position
given by the input rectangle
labelRect . |
int |
getTreatAs()
Returns how the label should be treated by the
IlvLabelLayoutRenderer of the IlvSDMEngine . |
abstract void |
initialize(IlvLabelingModel labelingModel)
Initializes the label descriptor before layout.
|
boolean |
isAutoCorrect()
Returns whether an illegal specification is automatically corrected.
|
boolean |
isFixed()
Returns whether the label can be moved or not.
|
void |
setActDistFromPath(double value)
Sets the actual distance of the label from the location on the path
that is given by the property
actPathLocation . |
void |
setActPathLocation(double value)
Sets the actual location on the path for the label.
|
void |
setAutoCorrect(boolean flag)
Sets whether an illegal specification is automatically corrected.
|
void |
setFixed(boolean value)
Sets whether the label can be moved or not.
|
void |
setMaxDistFromPath(double distance)
Sets the maximum distance from the location on the path.
|
void |
setMaxPathLocation(double value)
Sets the maximum location on the path for the label.
|
abstract void |
setPosition(double pathLocation,
double distFromPath)
Sets the label conceptually to the specified position.
|
abstract void |
setTowardsPreferredPosition(double pathLocation,
double distFromPath,
int i,
int maxI)
Sets the label to a position that is closer to the preferred position
than the input position given by
pathLocation and
distFromPath . |
void |
setTreatAs(int mode)
Sets how the label should be treated by the
IlvLabelLayoutRenderer of the IlvSDMEngine . |
void |
updatePosition(double x,
double y)
Updates the internal representation of the position of the label.
|
protected double actPathLocation
setPosition(double, double)
.protected double maxPathLocation
initialize(IlvLabelingModel)
.protected double actDistFromPath
actPathLocation
. This variable
must be kept up to date by setPosition(double, double)
.protected double maxDistFromPath
actPathLocation
. This variable
can be initialized by initialize(IlvLabelingModel)
.public static final int LABEL
IlvSDMEngine
. You
should not use this option.public static final int OBSTACLE
IlvSDMEngine
. You
should not use this option.public static final int IGNORED
IlvSDMEngine
. You
should not use this option.public IlvAnnealingLabelDescriptor(Object label)
label
- The label of the descriptor.public IlvAnnealingLabelDescriptor(IlvAnnealingLabelDescriptor d)
d
- The original label descriptor.public abstract IlvAnnealingLabelDescriptor copy()
public final Object getLabel()
public abstract void initialize(IlvLabelingModel labelingModel)
maxPathLocation
and maxDistFromPath
to the desired values.labelingModel
- The labeling model that provides information about
labels and obstacles.public abstract void setPosition(double pathLocation, double distFromPath)
actPathLocation
and actDistFromPath
. Furthermore, it calculates the Cartesian
coordinates (x, y) that correspond to the given path location and
distance, and calls updatePosition(double, double)
to update
the internal representation of the position of the label.pathLocation
- The location on the path.distFromPath
- The distance from the location on the path.updatePosition(double, double)
public abstract void setTowardsPreferredPosition(double pathLocation, double distFromPath, int i, int maxI)
pathLocation
and
distFromPath
. This method is called iteratively to test
various positions that are closer to the preferred position. One
common strategy is to divide the distance between
pathLocation
and the preferred path location evenly, and
to place the label via setPosition(double, double)
in each
step closer to the preferred position.pathLocation
- The current location on the path.distFromPath
- The current distance from the location on the pathi
- The number of the iteration step, from 0 to maxI -
1
.maxI
- The maximum number of iteration steps.setPosition(double, double)
,
getPreferredPathLocation()
,
getPreferredDistFromPath()
public final void updatePosition(double x, double y)
setPosition(double, double)
.
For experts: This method does not really move the label in the
labeling model, but updates internal data structures that allow to
test easily what would happen if the label would be at the input
position. The real move of the label via IlvLabelingModel.moveLabel(Object, double, double, boolean)
is
delayed until the end of all tests.
x
- The (Cartesian) x coordinate of the upper left corner of the
label.y
- The (Cartesian) y coordinate of the upper left corner of the
label.setPosition(double, double)
public double getRotation(IlvLabelingModel model, IlvRect labelRect)
labelRect
. At this time
point, the label is not yet physically placed at this position. This
allows to check the rotation at a fictive position before the label
is actually moved to this position. The returned rotation angle is
considered to be the rotation around the center of rect
.
The default implementation calls IlvLabelingModelWithRotation.getRotation(Object, IlvRect)
on the
passed labeling model, if the model supports rotation. Otherwise it
returns 0.
model
- The labeling model.labelRect
- The proposed position of the label.IlvLabelingModelWithRotation
public double getPreferredPathLocation()
Subclasses can override this method to give the user the possibility to specify any preferred position for the label.
public double getPreferredDistFromPath()
Subclasses can override this method to give the user the possibility to specify any preferred position for the label.
public boolean considerObstacle(Object obstacle)
true
if the overlap between the label and the
input obstacle should be considered during the quality calculation of
the Simulated Annealing label layout algorithm. If it returns
true
, the algorithm tries to avoid overlaps with this
obstacle. If it returns false
, it indicates that the
label is allowed to overlap the obstacle.
The default implementation always returns true
.
Subclasses can override this method to finetune which label is
allowed to overlap which obstacle.
obstacle
- The obstacle to test.true
if there is a penalty if the label overlaps
the obstacle, and false
, if there is no penalty.public Object getRelatedObstacle()
protected double getMinDist(Object obstacle, double min)
obstacle
- The obstacle.min
- A global value specifying the minimum distance between this
label and the given obstacle.public void setTreatAs(int mode)
IlvLabelLayoutRenderer
of the IlvSDMEngine
.
This method is internally used. You should not call this method.public int getTreatAs()
IlvLabelLayoutRenderer
of the IlvSDMEngine
.
This method is internally used. You should not call this method.public void setAutoCorrect(boolean flag)
maxDistFromPath
. If the
automatic correction is enabled, it automatically corrects the
specification and throws no exception. If the automatic correction is
disabled, it throws an exception for illegal specifications. The
latter is usually better when debugging, while the former is usually
better when you design a GUI for specifying the label descriptor.
The default value is false
.
isAutoCorrect()
public boolean isAutoCorrect()
setAutoCorrect(boolean)
public double getActPathLocation()
The default value is 0
.
setActPathLocation(double)
public void setActPathLocation(double value)
getActPathLocation()
public double getMaxPathLocation()
The default value is 0
.
setMaxPathLocation(double)
public void setMaxPathLocation(double value)
getMaxPathLocation()
public double getActDistFromPath()
actPathLocation
.
The default value is 0
.
setActDistFromPath(double)
public void setActDistFromPath(double value)
actPathLocation
. This is
internally used by the layout algorithm. Do not call this method
yourself.getActDistFromPath()
public void setMaxDistFromPath(double distance)
The default value is 0
.
distance
- The maximum distance from the path.getMaxDistFromPath()
public double getMaxDistFromPath()
setMaxDistFromPath(double)
public boolean isFixed()
The default value is false
.
setFixed(boolean)
public void setFixed(boolean value)
isFixed()
© Copyright Rogue Wave Software, Inc. 1997, 2018. All Rights Reserved.