ilog.views.graphlayout.labellayout.annealing

Class IlvAnnealingLabelLayout

java.lang.Object

ilog.views.graphlayout.labellayout.IlvLabelLayout

ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelLayout

public class IlvAnnealingLabelLayout
extends IlvLabelLayout

The main class for the Simulated Annealing Label Layout algorithm.

This performs a simulated annealing label positioning algorithm. Each label is moved according to its label descriptor, such that the overlaps among labels, and between labels and obstacles is small. The label descriptor defines the area where a label can be placed. For instance, to specify an area close to a given point, use the IlvAnnealingPointLabelDescriptor (see #setLabelDescriptor(Object, IlvAnnealingLabelDescriptor)), or to specify an area along a polyline, use the IlvAnnealingPolylineLabelDescriptor.

In the following sample drawings, the labels were placed by the Annealing Label Layout algorithm. They show point labeling with the IlvAnnealingPointLabelDescriptor to place the labels at nodes of a network or at cities of a map.

Click on the image to see it in normal size.

The following are two sample drawings that show link/line labeling with the IlvAnnealingPolylineLabelDescriptor. Many options are provided to tailor the placement. In the left drawing, the "Start Label", "End Label" and "Center Label" were specified to be at the start, end, center, respectively, of the corresponding link. The right drawing shows a link with multiple labels. It is possible to specify the side of the link where labels are placed.

Click on the image to see it in normal size.

Simulated annealing is a quality controlled, randomized iterative heuristic. The labels are placed according to a temperature scheme, and the quality of the placement increases when the temperature decreases. The quality is defined by the amount of overlaps between pairs of labels and between labels and obstacles. The fewer overlaps the higher the quality. Simulated annealing, as randomized algorithm, does not guarantee a placement of the labels without overlaps. However, it produces a quality layout with a high probability. The more iterations the higher the probability of high quality.

See the corresponding chapter of the User's Manual for details on the algorithm, the features and limitations, code samples, and so on.

Note that the initial position of the labels (at the moment you start the layout) does not affect the resulting layout.

CSS example:

SDM {
LabelLayout : true;
}

LabelLayout {
allowedNumberOfIterations : "2";
allowedTime : "3";
autoUpdate : "false";
coordinatesMode : "MANAGER_COORDINATES";
labelOffset : "3.0";
maxNumberOfFailIterations : "2";
minBusyTime : "3";
minImprovementPercentageToContinue : "3.0";
numberIterationsForMinImprovement : "2";
obstacleOffset : "3.0";
seedValueForRandomGenerator : "3";
useQuadtree : "false";
useSeedValueForRandomGenerator : "false";
}

CSS usage: The CSS example above illustrates the styling of the global parameters of the label layout algorithm. For indications about how to specify the labels and obstacles, see the documentation of the class IlvLabelLayoutRenderer.

Property Summary

Properties

Modifier and Type	Property and Description
int	allowedNumberOfIterations Sets the maximum allowed number of iterations of the layout algorithm.
long	allowedTime Allows you to specify an upper limit for the duration of the layout algorithm.
boolean	autoUpdate Enables the automatic update of labels on geometry changes.
int	coordinatesMode Sets the coordinates mode to be used during layout.
double	labelOffset Sets the minimum offset between the border of neighbored labels.
int	maxNumberOfFailIterations Sets the maximum number of iterations that doesn't improve the layout quality before the layout algorithm stops.
long	minBusyTime Sets the minimal time the layout algorithm can be busy between two calls of layoutStepPerformed when the method callLayoutStepPerformedIfNeeded is used.
double	minImprovementPercentageToContinue Sets the minimum required percentage the layout needs to improve over a couple of rounds before the layout algorithm stops.
int	numberIterationsForMinImprovement Sets the number of iterations performed to reach the minimum required percentage of layout quality improvement specified by #setMinImprovementPercentageToContinue(double).
double	obstacleOffset Sets the global minimum offset between a label and an unrelated obstacle.
long	seedValueForRandomGenerator Allows you to specify a seed value for the random generator.
boolean	useQuadtree Enables the quadtree.
boolean	useSeedValueForRandomGenerator Allows you to specify whether the user-defined seed value should be used for the random generator.

Method Summary

Methods inherited from class java.lang.Object

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

Property Detail

allowedNumberOfIterations

public int allowedNumberOfIterations

Sets the maximum allowed number of iterations of the layout algorithm.

Simulated annealing is a quality controlled, randomized iterative heuristic. It does not guarantee a placement of the labels without overlaps. However, the more iterations, the higher the probability that the heuristic ends up with a high quality layout without overlaps.

CSS example: allowedNumberOfIterations : "2";

allowedTime

public long allowedTime

Allows you to specify an upper limit for the duration of the layout algorithm.

When an iterative layout algorithm is used, the iterations can be stopped when this time is exceeded. Noniterative algorithms can also use this parameter as an upper limit for the computation time. The default value is normally 32000 (32 seconds). Subclasses that support this feature can use a different default value depending on their particular behavior. Layout algorithms that are stopped in this way set the result code of the layout report either to IlvLabelLayoutReport#STOPPED_AND_VALID or to IlvLabelLayoutReport#STOPPED_AND_INVALID.

Note that the method #performLayout(boolean, boolean) does NOT automatically stop the layout when the allowed time is exceeded. It is the sole responsibility of the implementation of the method #layout(boolean) to do this.

A RuntimeException is thrown if the layout does not support this mechanism.

CSS example: allowedTime : "3";

autoUpdate

public boolean autoUpdate

Enables the automatic update of labels on geometry changes. If enabled, a label follows its related obstacle whenever the obstacle is moved or resized. It calls #updateLabelPosition(Object, boolean) for each label that has a point label descriptor or polyline label descriptor with a related obstacle that was moved or resized.

It is disabled by default.

It is designed to automatically update the labels during interactions. Hence, it is optimized for speed: It does not perform a full layout and does not try to avoid overlaps.

If the default labeling model is used, the automatic update is not always performed on zoom level changes. This may lead to undesired results with nonzoomable objects (see IlvGraphic#zoomable). We recommend to use zoomable objects.

CSS example: autoUpdate : "false";

coordinatesMode

public int coordinatesMode

Sets the coordinates mode to be used during layout.

Valid value are:

• #MANAGER_COORDINATES - Labels are placed in the coordinate system of the manager , without applying any transformation.

  This mode should be used if you visualize objects at zoom level 1, or you don't visualize it at all, or the manager contains only fully-zoomable objects. Indeed, in all these cases there's no need to take the transformer into account during the layout.

  Note that in this mode the dimensional parameters of the layout algorithms are considered as being specified in manager's coordinates.

• #VIEW_COORDINATES - Labels are placed in the coordinate system of the manager view. In the default labeling model, all the coordinates are transformed using the current reference transformer.

  This mode should be used if you want the dimensional parameters of the layout algorithms to be considered as being specified in manager view's coordinates.

• #INVERSE_VIEW_COORDINATES - Labels are placed in the coordinate system given by transforming view coordinates back into the coordinate system of the manager . This mode is equivalent to the "manager coordinates" mode if the geometry of the graphic objects strictly obeys to the transformer. (A small difference may exist because of the limited precision of the computations.)

  On the contrary, if some graphic objects are either non-zoomable (see IlvGraphic#zoomable) or semi-zoomable (e.g. links with a maximum line width), this mode gives different results than the manager's coordinates mode. These results are optimal if the manager is visualized using the same transformer as the one taken into account during the layout.

  Note that in this mode the dimensional parameters of the layout algorithms are considered as being specified in manager's coordinates.

This option can be used only if the attached labeling model is an IlvDefaultLabelingModel (or a subclass). Otherwise, it has no effect. Note: the coordinates mode of the layout is only used while layout is running. If layout is not running, operations on the default labeling model use the coordinates mode that was set on the labeling model directly (see IlvDefaultLabelingModel#setCoordinatesMode(int)).

The default value is INVERSE_VIEW_COORDINATES.

CSS example: coordinatesMode : "MANAGER_COORDINATES";

Allowed values:

MANAGER_COORDINATES

VIEW_COORDINATES

INVERSE_VIEW_COORDINATES

labelOffset

public double labelOffset

Sets the minimum offset between the border of neighbored labels. Simulated annealing is a quality controlled iterative heuristic. It will not always satisfy the minimum offset, but it will include the minimum offset in the calculation of the quality after each iteration step, hence, the majority of labels will most likely preserve the minimum offset at the end of layout.

Very large minimum offsets may slow down the layout considerably.

The default value is 0.

CSS example: labelOffset : "3.0";

maxNumberOfFailIterations

public int maxNumberOfFailIterations

Sets the maximum number of iterations that doesn't improve the layout quality before the layout algorithm stops.

Simulated annealing is a quality controlled, randomized iterative heuristic. If after the specified number of iterations, the quality did not improve, the algorithm gives up. Hence, setting the maximum number to a high value avoids that the layout algorithm gives up too early, resulting in a better quality of the layout. Setting the maximum number to a low value speeds up the algorithm.

The default value is 20.

CSS example: maxNumberOfFailIterations : "2";

minBusyTime

public long minBusyTime

Sets the minimal time the layout algorithm can be busy between two calls of layoutStepPerformed when the method callLayoutStepPerformedIfNeeded is used.

The objective is to avoid the overhead of #layoutStepPerformed() becoming too high if the method is called too often. Internal routines of layout algorithms usually call #callLayoutStepPerformedIfNeeded(), which calls #layoutStepPerformed() if the time since the last call was at least the minimal busy time.

The default value is 50 (milliseconds).

CSS example: minBusyTime : "3";

minImprovementPercentageToContinue

public double minImprovementPercentageToContinue

Sets the minimum required percentage the layout needs to improve over a couple of rounds before the layout algorithm stops.

Simulated annealing is a quality controlled, randomized iterative heuristic. If, after the specified number of iterations, the quality did not improve at least by the specified percentage, the algorithm gives up. Hence, setting the percentage to 0 avoids that the layout algorithm gives up too early, resulting in a better quality of the layout. Setting the percentage to a high number speeds up the algorithm. Useful percentage values are between 0 and 5%.

The default value is 0.5%.

By default, the algorithm performs five iterations to reach at least 0.5% improvement of the quality. The number of iterations that are taken to reach the minimum percentage of improvement can be set by #setNumberIterationsForMinImprovement(int).

CSS example: minImprovementPercentageToContinue : "3.0";

numberIterationsForMinImprovement

public int numberIterationsForMinImprovement

Sets the number of iterations performed to reach the minimum required percentage of layout quality improvement specified by #setMinImprovementPercentageToContinue(double).

Simulated annealing is a quality controlled, randomized iterative heuristic. If, after the specified number of iterations, the quality did not improve at least by the specified percentage, the algorithm gives up. Hence, setting the number of iterations to a high value avoids the layout algorithm giving up too early, resulting in a better quality of the layout. Setting the number of iterations to a small number speeds up the algorithm. Useful values are between 1 and 30.

The default value is 5.

CSS example: numberIterationsForMinImprovement : "2";

obstacleOffset

public double obstacleOffset

Sets the global minimum offset between a label and an unrelated obstacle. Typically, a label should not be placed too close to unrelated obstacles. The global obstacle offset is used if no obstacle offset interface is installed. Otherwise, see #setObstacleOffsetInterface(IlvObstacleOffsetInterface). The minimum offset is not used for the related obstacle of the label, if any (see IlvAnnealingPointLabelDescriptor#getRelatedObstacle() and IlvAnnealingLabelDescriptor#considerObstacle(Object)).

Simulated annealing is a quality controlled iterative heuristic. It will not always satisfy the minimum offset, but it will include the minimum offset in the calculation of the quality after each iteration step; hence, the majority of labels will most likely preserve the minimum offset at the end of layout.

Very large minimum offsets may slow down the layout considerably. It is not recommended to set the global obstacle offset to an unreasonably high value such as Double.MAX_VALUE, because this causes computational problems inside quadtree operations (see #setUseQuadtree(boolean)).

The default value is 0.

CSS example: obstacleOffset : "3.0";

seedValueForRandomGenerator

public long seedValueForRandomGenerator

Allows you to specify a seed value for the random generator. The default value is 0. The user-defined seed value is used only if you call setUseSeedValueForRandomGenerator(boolean) with a true argument.

A RuntimeException is thrown if the layout does not support this mechanism.

CSS example: seedValueForRandomGenerator : "3";

See Also:

useSeedValueForRandomGenerator

useQuadtree

public boolean useQuadtree

Enables the quadtree. The quadtree speeds up the layout algorithm if there is a large amount of labels and the underlying labeling model is bounding box dependent.

The quadtree is enabled by default.

CSS example: useQuadtree : "false";

useSeedValueForRandomGenerator

public boolean useSeedValueForRandomGenerator

Allows you to specify whether the user-defined seed value should be used for the random generator.

A RuntimeException is thrown if the layout does not support this mechanism. The default value is false.

CSS example: useSeedValueForRandomGenerator : "false";

See Also:

seedValueForRandomGenerator