IlvAnnealingLabelDescriptor (Perforce JViews 10.0 API)

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 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);
     } 
   }
 }
 
```
Since:

JViews 5.0

Field Summary

Fields
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 Summary

Constructors
Constructor and Description
`IlvAnnealingLabelDescriptor(IlvAnnealingLabelDescriptor d)` Creates a copy of a label descriptor.
`IlvAnnealingLabelDescriptor(Object label)` Creates a new instance of a label descriptor.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
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.

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, double).
  - maxPathLocation
```
protected double maxPathLocation
```
    The maximum location on the path for the label. This variable can be initialized by initialize(IlvLabelingModel).
  - actDistFromPath
```
protected double 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, double).
  - maxDistFromPath
```
protected double maxDistFromPath
```
    The maximum distance of the label from the location on the path that is given by the variable actPathLocation. This variable can be initialized by initialize(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.
  - IlvAnnealingLabelDescriptor
```
public IlvAnnealingLabelDescriptor(IlvAnnealingLabelDescriptor d)
```
    Creates a copy of a label descriptor.
    
    Parameters:
    
    d - The original label descriptor.
    
    Since:
    
    JViews 8.5
- Method Detail
  - copy
```
public abstract IlvAnnealingLabelDescriptor copy()
```
    Returns a copy of this label descriptor.
    
    Returns:
    
    A copy of this label descriptor.
    
    Since:
    
    JViews 8.5
  - 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.
    
    Parameters:
    
    labelingModel - The labeling model that provides information about labels and obstacles.
  - setPosition
```
public abstract void setPosition(double pathLocation,
                                 double 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(double, double) 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(double, double)
  - setTowardsPreferredPosition
```
public 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. 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.
    
    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 maximum number of iteration steps.
    
    See Also:
    
    setPosition(double, double), getPreferredPathLocation(), getPreferredDistFromPath()
  - updatePosition
```
public final void updatePosition(double x,
                                 double y)
```
    Updates the internal representation of the position of the label. This should be called inside 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.
    
    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, double)
  - 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 IlvLabelingModelWithRotation.getRotation(Object, IlvRect) 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 double 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 double getMinDist(Object obstacle,
                            double min)
```
    Returns the minimum distance value between this label and the input obstacle. The input minimum distance is the global value. Specific labels may want to deviate from the global value and can override this method.
    
    Parameters:
    
    obstacle - The obstacle.
    
    min - A global value specifying the minimum distance between this label and the given obstacle.
    
    Returns:
    
    The minimum distance value between this label and the input obstacle.
    
    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
  - setAutoCorrect
```
public void setAutoCorrect(boolean flag)
```
    Sets whether an illegal specification is automatically corrected. For instance, for most label descriptors it is illegal that the preferred distance from path is larger than 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.
    
    Since:
    
    JViews 8.5
    
    See Also:
    
    isAutoCorrect()
  - isAutoCorrect
```
public boolean isAutoCorrect()
```
    Returns whether an illegal specification is automatically corrected.
    
    Since:
    
    JViews 8.5
    
    See Also:
    
    setAutoCorrect(boolean)
  - getActPathLocation
```
public double getActPathLocation()
```
    Returns the actual location on the path for the label.
    The default value is 0.
    
    Since:
    
    JViews 8.6
    
    See Also:
    
    setActPathLocation(double)
  - setActPathLocation
```
public void setActPathLocation(double value)
```
    Sets the actual location on the path for the label. This is internally used by the layout algorithm. Do not call this method yourself.
    
    Since:
    
    JViews 8.6
    
    See Also:
    
    getActPathLocation()
  - getMaxPathLocation
```
public double getMaxPathLocation()
```
    Returns the maximum location on the path for the label.
    The default value is 0.
    
    Since:
    
    JViews 8.6
    
    See Also:
    
    setMaxPathLocation(double)
  - setMaxPathLocation
```
public void setMaxPathLocation(double value)
```
    Sets the maximum location on the path for the label. This is internally used by the layout algorithm. Usually, you do not need to call this method except when you implement the initialize method of your own label descriptor subclass.
    
    Since:
    
    JViews 8.6
    
    See Also:
    
    getMaxPathLocation()
  - getActDistFromPath
```
public double getActDistFromPath()
```
    Returns the actual distance of the label from the location on the path that is given by the property actPathLocation.
    The default value is 0.
    
    Since:
    
    JViews 8.6
    
    See Also:
    
    setActDistFromPath(double)
  - setActDistFromPath
```
public void setActDistFromPath(double value)
```
    Sets the actual distance of the label from the location on the path that is given by the property actPathLocation. This is internally used by the layout algorithm. Do not call this method yourself.
    
    Since:
    
    JViews 8.6
    
    See Also:
    
    getActDistFromPath()
  - setMaxDistFromPath
```
public void setMaxDistFromPath(double distance)
```
    Sets the maximum distance from the location on the path. This is internally used by the layout algorithm. Usually, you do not need to call this method except when you implement the initialize method of your own label descriptor subclass.
    The default value is 0.
    
    Parameters:
    
    distance - The maximum distance from the path.
    
    Since:
    
    JViews 8.6
    
    See Also:
    
    getMaxDistFromPath()
  - getMaxDistFromPath
```
public double getMaxDistFromPath()
```
    Returns the maximum distance from the location on the path.
    
    Since:
    
    JViews 8.6
    
    See Also:
    
    setMaxDistFromPath(double)
  - isFixed
```
public boolean isFixed()
```
    Returns whether the label can be moved or not.
    The default value is false.
    
    Since:
    
    JViews 8.6
    
    See Also:
    
    setFixed(boolean)
  - setFixed
```
public void setFixed(boolean value)
```
    Sets whether the label can be moved or not. This is internally used by the layout algorithm. Do not call this method yourself.
    
    Since:
    
    JViews 8.6
    
    See Also:
    
    isFixed()

Class IlvAnnealingLabelDescriptor

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

actPathLocation

maxPathLocation

actDistFromPath

maxDistFromPath

LABEL

OBSTACLE

IGNORED

Constructor Detail

IlvAnnealingLabelDescriptor

IlvAnnealingLabelDescriptor

Method Detail

copy

getLabel

initialize

setPosition

setTowardsPreferredPosition

updatePosition

getRotation

getPreferredPathLocation

getPreferredDistFromPath

considerObstacle

getRelatedObstacle

getMinDist

setTreatAs

getTreatAs

setAutoCorrect

isAutoCorrect

getActPathLocation

setActPathLocation

getMaxPathLocation

setMaxPathLocation

getActDistFromPath

setActDistFromPath

setMaxDistFromPath

getMaxDistFromPath

isFixed

setFixed