ilog.views.graphlayout.labellayout.annealing
Class IlvAnnealingPointLabelDescriptor

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

All Implemented Interfaces:

IlvPersistentObject

public class IlvAnnealingPointLabelDescriptor
extends IlvAnnealingLabelDescriptor
implements IlvPersistentObject

The class IlvAnnealingPointLabelDescriptor can be used to specify that the label should be placed close to specific point (the point labeling problem). A typical application is to place labels of cities on a map. These labels should be close to the related cities, but they should not overlap each other and should not overlap any city.

Sample drawings produced by the Annealing Label Layout algorithm with point label descriptors:

Click on the image to see it in normal size.

Since:

JViews 5.0

Field Summary

static int	ELLIPTIC Option for the shape of the path.
static int	RECTANGULAR Option for the shape of the path.

Fields inherited from class ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor

actDistFromPath, actPathLocation, IGNORED, LABEL, maxDistFromPath, maxPathLocation, OBSTACLE

Constructor Summary

IlvAnnealingPointLabelDescriptor()
Creates a new empty instance of a point label descriptor.

IlvAnnealingPointLabelDescriptor(IlvInputStream stream)
Creates a new IlvAnnealingPointLabelDescriptor from an IlvInputStream.

IlvAnnealingPointLabelDescriptor(Object label, Object relatedObstacle, IlvPoint referencePoint, float minDist, float maxDist, int preferredDirection)
Creates a new instance of a point label descriptor.

IlvAnnealingPointLabelDescriptor(Object label, Object relatedObstacle, IlvPoint referencePoint, int shape, float halfWidth, float halfHeight, float maxDistFromPath, float preferredDistFromPath, int preferredDirection)
Creates a new instance of a point label descriptor.

IlvAnnealingPointLabelDescriptor(Object label, Object relatedObstacle, int shape, int preferredDirection)
Creates a new instance of a point 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()
float	getHalfHeight() Returns the half height of the path around the reference point.
float	getHalfWidth() Returns the half width of the path around the reference point.
float	getMaxDistFromPath() Returns the maximal distance from the location on the path.
Object	getObject()
int	getPreferredDirection() Returns the preferred direction where the label is placed relative to the reference point or related obstacle.
float	getPreferredDistFromPath() Returns the preferred distance from the location on the path.
double	getPreferredPathLocation() Returns the preferred location on the path.
IlvPoint	getReferencePoint() Returns a copy of the reference point of the label.
Object	getRelatedObstacle() Returns the obstacle that is related to the label.
int	getShape() Returns the shape of the allowed area around the reference point or related obstacle.
void	initialize(IlvLabelingModel labelingModel) Initializes the label descriptor before layout.
void	setBoundingBox(IlvRect bbox)
void	setHalfHeight(float halfHeight) Sets the half height of the path around the reference point.
void	setHalfWidth(float halfWidth) Sets the half width of the path around the reference point.
void	setMaxDistFromPath(float distance) Sets the maximal distance from the location on the path.
void	setPosition(double pathLocation, float distFromPath) Sets the label conceptually to the specified position.
void	setPreferredDirection(int direction) Sets the preferred direction where the label is placed relative to the reference point or related obstacle.
void	setPreferredDistFromPath(float distance) Sets the preferred distance from the location on the path.
void	setReferencePoint(IlvPoint point) Sets the reference point of the label.
void	setRelatedObstacle(Object obstacle) Sets the obstacle that is related to the label.
void	setShape(int shape) Sets the shape of the allowed area around the reference point or related obstacle.
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	write(IlvOutputStream stream) Writes the label descriptor to the output stream.

Methods inherited from class ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor

getLabel, getMinDist, getRotation, getTreatAs, setTreatAs, updatePosition

Methods inherited from class java.lang.Object

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

Field Detail

ELLIPTIC

public static final int ELLIPTIC

Option for the shape of the path. The label can be placed around the reference point on an approximately elliptic path.

See Also:

Constant Field Values

RECTANGULAR

public static final int RECTANGULAR

Option for the shape of the path. The label can be placed around the reference point on an rectangular path.

See Also:

Constant Field Values

Constructor Detail

IlvAnnealingPointLabelDescriptor

public IlvAnnealingPointLabelDescriptor()

Creates a new empty instance of a point label descriptor. You have to fill the label descriptor with data before you can use the descriptor in the label layout. As a minimum, you have to specify either a related obstacle or the reference point.

Since:

JViews 5.5

See Also:

setRelatedObstacle(java.lang.Object), setReferencePoint(ilog.views.IlvPoint), setHalfWidth(float), setHalfHeight(float), setMaxDistFromPath(float), setPreferredDistFromPath(float), setPreferredDirection(int), setShape(int), IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor)

IlvAnnealingPointLabelDescriptor

public IlvAnnealingPointLabelDescriptor(Object label,
                                        Object relatedObstacle,
                                        int shape,
                                        int preferredDirection)

Creates a new instance of a point label descriptor. This can be used to describe that the label can move around the related obstacle. The label layout algorithm tries to place the label close to the related obstacle. For instance, when labeling cities of a geographic map, the related obstacle should be the object that represent the city that has this label.

The label can be placed in an area around the obstacle. The size of the area is determined by the size of the related obstacle. The options for the shape of the area are:

• IlvAnnealingPointLabelDescriptor.ELLIPTIC - The area has an elliptic shape. This should be used if the the related obstacle is a circle or an ellipse.
• IlvAnnealingPointLabelDescriptor.RECTANGULAR - The area has a rectangular shape. This should be used if the related obstacle is a rectangle.

Furthermore, the layout takes as hint the direction where the label should be preferably placed relative to the related obstacle. Valid options for the preferred direction are:

• IlvDirection.Left
• IlvDirection.Right
• IlvDirection.Top
• IlvDirection.Bottom

Parameters:

label - The label.

relatedObstacle - The obstacle that is related to the label.

shape - The shape of the allowed area around the related obstacle.

preferredDirection - The direction from the reference point where the label should preferably be placed.

See Also:

IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor)

IlvAnnealingPointLabelDescriptor

public IlvAnnealingPointLabelDescriptor(Object label,
                                        Object relatedObstacle,
                                        IlvPoint referencePoint,
                                        float minDist,
                                        float maxDist,
                                        int preferredDirection)

Creates a new instance of a point label descriptor. This can be used to describe that the label can move in a circle around the reference point. The label layout algorithm tries to place the label close to the reference point.

The label can be placed in a circular area such that the label is between minDist and maxDist away from the reference point. The distance of the label is measured from the reference point to the closest corner of the label. The layout algorithm strictly observes this range. It does not place the label closer than minDist or farther then maxDist from the reference point.

Furthermore, the layout takes as hint the direction where the label should be preferably placed relative to the reference point. Valid options for the preferred direction are:

• IlvDirection.Left
• IlvDirection.Right
• IlvDirection.Top
• IlvDirection.Bottom

Parameters:

label - The label.

relatedObstacle - The obstacle that is related to the label, e.g. when labeling cities of a geographic map, the related obstacle should be the object that representing the city that has this label. The algorithm does not count overlaps between the label and its related obstacle. If the layout algorithm should count all overlaps to all labels, the related obstacle should be null.

referencePoint - The reference point the label should be close to.

minDist - The minimal distance from the label to the reference point.

maxDist - The maximal distance from the label to the reference point.

preferredDirection - The direction from the reference point where the label should preferably be placed.

See Also:

IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor)

IlvAnnealingPointLabelDescriptor

public IlvAnnealingPointLabelDescriptor(Object label,
                                        Object relatedObstacle,
                                        IlvPoint referencePoint,
                                        int shape,
                                        float halfWidth,
                                        float halfHeight,
                                        float maxDistFromPath,
                                        float preferredDistFromPath,
                                        int preferredDirection)

Creates a new instance of a point label descriptor. This can be used to describe that the label can move around the reference point. The label layout algorithm tries to place the label close to the reference point.

The label can be placed in an area that can be described by a path and and additional offset from the path. The options for the shape of the path are:

• IlvAnnealingPointLabelDescriptor.ELLIPTIC - The path resembles an elliptic shape.
• IlvAnnealingPointLabelDescriptor.RECTANGULAR - The path is a rectangular shape.

The halfWidth and halfHeight specify the dimensions of the path. For instance, if the path should be a circle, specify the radius of the circle as halfWidth and halfHeight. The label is placed no farther than maxDistFromPath away from the path.

Furthermore, the layout takes as hint the distance and direction where the label should be preferably placed relative to the reference point. Valid options for the preferred direction are:

• IlvDirection.Left
• IlvDirection.Right
• IlvDirection.Top
• IlvDirection.Bottom

Parameters:

label - The label.

relatedObstacle - The obstacle that is related to the label, e.g. when labeling cities of a geographic map, the related obstacle should be the object that representing the city that has this label. The algorithm does not count overlaps between the label and its related obstacle. If the layout algorithm should count all overlaps to all labels, the related obstacle should be null.

referencePoint - The reference point the label should be close to. If the reference point is null, the center of the related obstacle is taken as reference point.

shape - The shape of the allowed area around the reference point.

halfWidth - The half width of the path around the reference point.

halfHeight - The half height of the path around the reference point.

maxDistFromPath - The maximal distance the label is allowed to be placed away from the path (towards the outside).

preferredDistFromPath - The preferred distance the label is placed away from the path (towards the outside).

preferredDirection - The direction from the reference point where the label should preferably be placed.

See Also:

IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor)

IlvAnnealingPointLabelDescriptor

public IlvAnnealingPointLabelDescriptor(IlvInputStream stream)
                                 throws IOException,
                                        IlvReadFileException

Creates a new IlvAnnealingPointLabelDescriptor from an IlvInputStream.

Parameters:

stream - The input stream from which the descriptor must be read.

Throws:

IlvReadFileException - if an error occurs while reading.

IOException

Method Detail

initialize

public void initialize(IlvLabelingModel labelingModel)

Initializes the label descriptor before layout. You should not call this directly. It is called once at the beginning of layout.

Specified by:

initialize in class IlvAnnealingLabelDescriptor

Parameters:

labelingModel - The labeling model attached to the layout algorithm.

setPosition

public void setPosition(double pathLocation,
                        float distFromPath)

Sets the label conceptually to the specified position. You should not call this directly.

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.

Specified by:

setPosition in class IlvAnnealingLabelDescriptor

Parameters:

pathLocation - The location on the path.

distFromPath - The distance from the location on the path.

See Also:

IlvAnnealingLabelDescriptor.updatePosition(float, float)

setTowardsPreferredPosition

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

You should not call this directly. The layout algorithm calls this method iteratively to test various positions that are closer to the preferred position.

Specified by:

setTowardsPreferredPosition in class IlvAnnealingLabelDescriptor

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()

getPreferredPathLocation

public double getPreferredPathLocation()

Returns the preferred location on the path.

Overrides:

getPreferredPathLocation in class IlvAnnealingLabelDescriptor

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. In fact, it returns false if the input obstacle is the related obstacle.

Overrides:

considerObstacle in class IlvAnnealingLabelDescriptor

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.

setRelatedObstacle

public void setRelatedObstacle(Object obstacle)

Sets the obstacle that is related to the label.

If you use this method to change a descriptor that is currently installed for a label, you should reinstall it by calling IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor) again to make the change active.

Parameters:

obstacle - The obstacle to set.

Since:

JViews 5.5

See Also:

getRelatedObstacle(), setReferencePoint(ilog.views.IlvPoint)

getRelatedObstacle

public final Object getRelatedObstacle()

Returns the obstacle that is related to the label. It may return null if only an array of reference points was specified.

Overrides:

getRelatedObstacle in class IlvAnnealingLabelDescriptor

See Also:

setRelatedObstacle(java.lang.Object)

setReferencePoint

public void setReferencePoint(IlvPoint point)

Sets the reference point of the label. This must be used if there is no related obstacle, or if the position of the related obstacle does not define the desired position of the label. If you set the reference point to null, the position of the related obstacle defines the where the label must be placed.

Note that a copy of the input point is stored. The original input point can be reused afterwards. If you use this method to change a descriptor that is currently installed for a label, you should reinstall it by calling IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor) again to make the change active.

Parameters:

point - The label reference point.

Since:

JViews 5.5

See Also:

getReferencePoint(), setRelatedObstacle(java.lang.Object)

getReferencePoint

public final IlvPoint getReferencePoint()

Returns a copy of the reference point of the label. It returns null if no reference point was specified.

See Also:

setReferencePoint(ilog.views.IlvPoint)

setShape

public void setShape(int shape)

Sets the shape of the allowed area around the reference point or related obstacle. Possible shapes are:

• ELLIPTIC
• RECTANGULAR

If you use this method to change a descriptor that is currently installed for a label, you should reinstall it by calling IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor) again to make the change active.

Parameters:

shape - The shape of the area.

Since:

JViews 5.5

See Also:

getShape()

getShape

public final int getShape()

Returns the shape of the allowed area around the reference point or related obstacle.

See Also:

setShape(int)

setHalfWidth

public void setHalfWidth(float halfWidth)

Sets the half width of the path around the reference point. The value is only taken into account if the reference point is not null.

If you use this method to change a descriptor that is currently installed for a label, you should reinstall it by calling IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor) again to make the change active.

Parameters:

halfWidth - The half width of the path around the reference point.

Since:

JViews 5.5

See Also:

getHalfWidth()

getHalfWidth

public final float getHalfWidth()

Returns the half width of the path around the reference point.

See Also:

setHalfWidth(float)

setHalfHeight

public void setHalfHeight(float halfHeight)

Sets the half height of the path around the reference point. The value is only taken into account if the reference point is not null.

If you use this method to change a descriptor that is currently installed for a label, you should reinstall it by calling IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor) again to make the change active.

Parameters:

halfHeight - The half height of the path around the reference point.

Since:

JViews 5.5

See Also:

getHalfHeight()

getHalfHeight

public final float getHalfHeight()

Returns the half height of the path around the reference point.

See Also:

setHalfHeight(float)

setPreferredDistFromPath

public void setPreferredDistFromPath(float distance)

Sets the preferred distance from the location on the path. It must be smaller than the maximal distance from path.

If you use this method to change a descriptor that is currently installed for a label, you should reinstall it by calling IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor) again to make the change active.

Parameters:

distance - The preferred distance from the location on the path.

Since:

JViews 5.5

See Also:

getPreferredDistFromPath(), setMaxDistFromPath(float)

getPreferredDistFromPath

public final float getPreferredDistFromPath()

Returns the preferred distance from the location on the path.

Overrides:

getPreferredDistFromPath in class IlvAnnealingLabelDescriptor

See Also:

setPreferredDistFromPath(float)

setMaxDistFromPath

public void setMaxDistFromPath(float distance)

Sets the maximal distance from the location on the path.

If you use this method to change a descriptor that is currently installed for a label, you should reinstall it by calling IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor) again to make the change active.

Parameters:

distance - The maximal distance from the location on the path.

Since:

JViews 5.5

See Also:

getMaxDistFromPath()

getMaxDistFromPath

public final float getMaxDistFromPath()

Returns the maximal distance from the location on the path.

See Also:

setMaxDistFromPath(float)

setPreferredDirection

public void setPreferredDirection(int direction)

Sets the preferred direction where the label is placed relative to the reference point or related obstacle. Possible directions are:

• IlvDirection.Left
• IlvDirection.Right
• IlvDirection.Top
• IlvDirection.Bottom

If you use this method to change a descriptor that is currently installed for a label, you should reinstall it by calling IlvAnnealingLabelLayout.setLabelDescriptor(java.lang.Object, ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelDescriptor) again to make the change active.

Parameters:

direction - The preferred direction to set.

Since:

JViews 5.5

See Also:

getPreferredDirection()

getPreferredDirection

public final int getPreferredDirection()

Returns the preferred direction where the label is placed relative to the reference point or related obstacle.

See Also:

setPreferredDirection(int)

write

public void write(IlvOutputStream stream)
           throws IOException

Writes the label descriptor to the output stream. It writes the related obstacle only if it is of type IlvGraphic.

Specified by:

write in interface IlvPersistentObject

Parameters:

stream - The output stream.

Throws:

IOException - standard IO error.

setBoundingBox

public final void setBoundingBox(IlvRect bbox)

getBoundingBox

public final IlvRect getBoundingBox()

getObject

public final Object getObject()