ilog.views.graphlayout.labellayout.annealing
Class IlvAnnealingLabelDescriptor

java.lang.Object
  ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor

Direct Known Subclasses:

IlvAnnealingPointLabelDescriptor, IlvAnnealingPolylineLabelDescriptor

public abstract class IlvAnnealingLabelDescriptor
extends Object

The class 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 IlvAnnealingLinkLabelDescriptor 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, float). This allows you to use the algorithm with different paths, by subclassing the IlvAnnealingLabelDescriptor and implementing your version of setPosition(double, float).

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, float distFromPath)
   {
     // path radius is 10. Radius for position is 10 + distFromPath,
     // because distFromPath is between 0 and 5
     updatePosition(
           (float)((10 + distFromPath) * Math.cos(pathLocation / 10));
           (float)((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, float 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);
     } 
   }
 }
 

Since:

JViews 5.0

Field Summary

protected float	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 float	maxDistFromPath The maximal distance of the label from the location on the path that is given by the variable actPathLocation.
protected double	maxPathLocation The maximal location on the path for the label.
static int	OBSTACLE This option is used internally by the IlvSDMEngine.

Constructor Summary

IlvAnnealingLabelDescriptor(Object label)
Creates a new instance of a label descriptor.

Method Summary

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.
IlvRect	getBoundingBox()
Object	getLabel() Returns the label of the descriptor.
protected float	getMinDist(Object obstacle, float minDist) Returns the minimal distance value between this label and the input obstacle.
Object	getObject()
float	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.
void	setBoundingBox(IlvRect bbox)
abstract void	setPosition(double pathLocation, float distFromPath) Sets the label conceptually to the specified position.
abstract void	setTowardsPreferredPosition(double pathLocation, float 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(float x, float y) Updates the internal representation of the position of the label.

Methods inherited from class java.lang.Object

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

Field Detail

actPathLocation

protected double actPathLocation

The actual location on the path for the label. This variable must be kept up to date by setPosition(double, float).

maxPathLocation

protected double maxPathLocation

The maximal location on the path for the label. This variable can be initialized by initialize(ilog.views.graphlayout.labellayout.IlvLabelingModel).

actDistFromPath

protected float actDistFromPath

The actual distance of the label from the location on the path that is given by the variable actPathLocation. This variable must be kept up to date by setPosition(double, float).

maxDistFromPath

protected float maxDistFromPath

The maximal distance of the label from the location on the path that is given by the variable actPathLocation. This variable can be initialized by initialize(ilog.views.graphlayout.labellayout.IlvLabelingModel).

LABEL

public static final int LABEL

This option is used internally by the IlvSDMEngine. You should not use this option.

Since:

JViews 6.0

See Also:

Constant Field Values

OBSTACLE

public static final int OBSTACLE

This option is used internally by the IlvSDMEngine. You should not use this option.

Since:

JViews 6.0

See Also:

Constant Field Values

IGNORED

public static final int IGNORED

This option is used internally by the IlvSDMEngine. You should not use this option.

Since:

JViews 6.0

See Also:

Constant Field Values

Constructor Detail

IlvAnnealingLabelDescriptor

public IlvAnnealingLabelDescriptor(Object label)

Creates a new instance of a label descriptor.

Parameters:

label - The label of the descriptor.

Method Detail

getLabel

public final Object getLabel()

Returns the label of the descriptor.

initialize

public abstract void initialize(IlvLabelingModel labelingModel)

Initializes the label descriptor before layout. It is called once at the beginning of layout. Typically, it sets the variables maxPathLocation and maxDistFromPath to the desired values.

setPosition

public abstract void setPosition(double pathLocation,
                                 float distFromPath)

Sets the label conceptually to the specified position. This method updates the variables actPathLocation and actDistFromPath. Furthermore, it calculates the Cartesian coordinates (x, y) that correspond to the given path location and distance, and calls updatePosition(float, float) to update the internal representation of the position of the label.

Parameters:

pathLocation - The location on the path.

distFromPath - The distance from the location on the path.

See Also:

updatePosition(float, float)

setTowardsPreferredPosition

public abstract void setTowardsPreferredPosition(double pathLocation,
                                                 float 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. 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, float) in each step closer to the preferred position.

Parameters:

pathLocation - The current location on the path.

distFromPath - The current distance from the location on the path

i - The number of the iteration step, from 0 to maxI - 1.

maxI - The maximal number of iteration steps.

See Also:

setPosition(double, float), getPreferredPathLocation(), getPreferredDistFromPath()

updatePosition

public final void updatePosition(float x,
                                 float y)

Updates the internal representation of the position of the label. This should be called inside setPosition(double, float).

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(java.lang.Object, float, float, boolean) is delayed until the end of all tests.

Parameters:

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.

See Also:

setPosition(double, float)

getRotation

public 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. 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 getRotation() on the passed labeling model, if the model supports rotation. Otherwise it returns 0.

Parameters:

model - The labeling model.

labelRect - The proposed position of the label.

Returns:

The rotation angle in degree.

Since:

JViews 6.5

See Also:

IlvLabelingModelWithRotation

getPreferredPathLocation

public double getPreferredPathLocation()

Returns the preferred location on the path. The default implementation returns 0.

Subclasses can override this method to give the user the possibility to specify any preferred position for the label.

getPreferredDistFromPath

public float getPreferredDistFromPath()

Returns the preferred distance from the location on the path. The default implementation returns 0.

Subclasses can override this method to give the user the possibility to specify any preferred position for the label.

considerObstacle

public 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. 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.

Parameters:

obstacle - The obstacle to test.

Returns:

true if there is a penalty if the label overlaps the obstacle, and false, if there is no penalty.

getRelatedObstacle

public Object getRelatedObstacle()

Returns the related obstacle of the label descriptor. This is overridden in subclasses.

Since:

JViews 6.0

getMinDist

protected float getMinDist(Object obstacle,
                           float minDist)

Returns the minimal distance value between this label and the input obstacle. The input minimal distance is the global value. Specific labels may want to deviate from the global value and can override this method.

Since:

JViews 6.0

setTreatAs

public void setTreatAs(int mode)

Sets how the label should be treated by the IlvLabelLayoutRenderer of the IlvSDMEngine. This method is internally used. You should not call this method.

Since:

JViews 6.0

getTreatAs

public int getTreatAs()

Returns how the label should be treated by the IlvLabelLayoutRenderer of the IlvSDMEngine. This method is internally used. You should not call this method.

Since:

JViews 6.0

setBoundingBox

public final void setBoundingBox(IlvRect bbox)

getBoundingBox

public final IlvRect getBoundingBox()

getObject

public final Object getObject()