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, Serializable

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

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
IlvAnnealingPointLabelDescriptor() Creates a new empty instance of a point label descriptor.
IlvAnnealingPointLabelDescriptor(IlvAnnealingPointLabelDescriptor d) Creates a copy of a label descriptor.
IlvAnnealingPointLabelDescriptor(IlvInputStream stream) Creates a new IlvAnnealingPointLabelDescriptor from an IlvInputStream.
IlvAnnealingPointLabelDescriptor(Object label, Object relatedObstacle, IlvPoint referencePoint, double minDist, double maxDist, int preferredDirection) Creates a new instance of a point label descriptor.
IlvAnnealingPointLabelDescriptor(Object label, Object relatedObstacle, IlvPoint referencePoint, int shape, double halfWidth, double halfHeight, double maxDistFromPath, double 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

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.
IlvAnnealingLabelDescriptor	copy() Returns a copy of this label descriptor.
double	getHalfHeight() Returns the half height of the path around the reference point.
double	getHalfWidth() Returns the half width of the path around the reference point.
double	getMaxDistFromPath() Returns the maximum distance from the location on the path.
int	getPreferredDirection() Returns the preferred direction where the label is placed relative to the reference point or related obstacle.
double	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	setHalfHeight(double hheight) Sets the half height of the path around the reference point.
void	setHalfWidth(double halfWidth) Sets the half width of the path around the reference point.
void	setMaxDistFromPath(double distance) Sets the maximum distance from the location on the path.
void	setPosition(double pathLocation, double 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(double 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, 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	write(IlvOutputStream stream) Writes the label descriptor to the output stream.

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

getActDistFromPath, getActPathLocation, getLabel, getMaxPathLocation, getMinDist, getRotation, getTreatAs, isAutoCorrect, isFixed, setActDistFromPath, setActPathLocation, setAutoCorrect, setFixed, setMaxPathLocation, 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(Object), setReferencePoint(IlvPoint), setHalfWidth(double), setHalfHeight(double), setMaxDistFromPath(double), setPreferredDistFromPath(double), setPreferredDirection(int), setShape(int), IlvAnnealingLabelLayout.setLabelDescriptor(Object, 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(Object, IlvAnnealingLabelDescriptor)

IlvAnnealingPointLabelDescriptor

public IlvAnnealingPointLabelDescriptor(Object label,
                                        Object relatedObstacle,
                                        IlvPoint referencePoint,
                                        double minDist,
                                        double 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 minimum distance from the label to the reference point.

maxDist - The maximum 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,
                                        double halfWidth,
                                        double halfHeight,
                                        double maxDistFromPath,
                                        double 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 maximum 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(Object, IlvAnnealingLabelDescriptor)

IlvAnnealingPointLabelDescriptor

public IlvAnnealingPointLabelDescriptor(IlvAnnealingPointLabelDescriptor d)

Creates a copy of a label descriptor.

Parameters:

d - The original label descriptor.

Since:

JViews 8.5

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

copy

public IlvAnnealingLabelDescriptor copy()

Returns a copy of this label descriptor.

Specified by:

copy in class IlvAnnealingLabelDescriptor

Returns:

A copy of this label descriptor.

Since:

JViews 8.5

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,
                        double 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(Object, double, double, 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(double, double)

setTowardsPreferredPosition

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

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 maximum number of iteration steps.

See Also:

setPosition(double, double), 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.

Parameters:

obstacle - The obstacle to set.

Since:

JViews 5.5

See Also:

getRelatedObstacle(), setReferencePoint(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(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 where the label must be placed.

Note that a copy of the input point is stored. The original input point can be reused afterwards.

Parameters:

point - The label reference point.

Since:

JViews 5.5

See Also:

getReferencePoint(), setRelatedObstacle(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(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

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(double 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.

Parameters:

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

Since:

JViews 5.5

See Also:

getHalfWidth()

getHalfWidth

public final double getHalfWidth()

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

See Also:

setHalfWidth(double)

setHalfHeight

public void setHalfHeight(double hheight)

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.

Parameters:

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

Since:

JViews 5.5

See Also:

getHalfHeight()

getHalfHeight

public final double getHalfHeight()

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

See Also:

setHalfHeight(double)

setPreferredDistFromPath

public void setPreferredDistFromPath(double distance)

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

Parameters:

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

Since:

JViews 5.5

See Also:

getPreferredDistFromPath(), setMaxDistFromPath(double)

getPreferredDistFromPath

public final double getPreferredDistFromPath()

Returns the preferred distance from the location on the path.

Overrides:

getPreferredDistFromPath in class IlvAnnealingLabelDescriptor

See Also:

setPreferredDistFromPath(double)

setMaxDistFromPath

public void setMaxDistFromPath(double distance)

Sets the maximum distance from the location on the path.

Overrides:

setMaxDistFromPath in class IlvAnnealingLabelDescriptor

Parameters:

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

Since:

JViews 5.5

See Also:

getMaxDistFromPath()

getMaxDistFromPath

public final double getMaxDistFromPath()

Returns the maximum distance from the location on the path.

Overrides:

getMaxDistFromPath in class IlvAnnealingLabelDescriptor

See Also:

setMaxDistFromPath(double)

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 (the default value)

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.