ilog.views.graphlayout.labellayout

Interface IlvLabelingModelWithRotation

All Known Implementing Classes:

IltLabelingModel, IlvDefaultLabelingModel

public interface IlvLabelingModelWithRotation

An IlvLabelingModelWithRotation is the extension of a labeling model that supports automatic positioning of rotated labels. If the label layout should position labels that correspond to rotated rectangles, then the labeling model must be a subclass of IlvLabelingModel that implements this interface.

JViews provides a default implementation of the labeling model (IlvDefaultLabelingModel) that can be used to handle labels in an IlvManager. This default model implements this interface and then allows rotated labels.

The Annealing Label layout supports the case that the labels have a rotation that depend on the position of the label (not the case where labels can be rotated freely). For instance, if a label is always rotated so that it is always parallel to the line segment of a polyline link, then this is supported. There are two possibilities to tell the layout what is the rotation formula of a label:

• Either implements a label descriptor and overrides IlvAnnealingLabelDescriptor.getRotation(IlvLabelingModel, IlvRect) in IlvAnnealingLabelDescriptor to return the rotation of a label at a given point. This is the preferred way if many different labels rotate according to different formulas.
• Or overrides IlvDefaultLabelingModel.getRotation(Object, IlvRect) in IlvDefaultLabelingModel (or in the interface IlvLabelingModelWithRotation of your labeling model) to return the rotation of a label at a given point. This is better if all labels rotated according to the same formula. By default the implementation of getRotation in IlvDefaultLabelingModel returns always 0.

Since:

JViews 6.5

See Also:

IlvAnnealingLabelLayout, IlvLabelingModel

Method Summary

Modifier and Type	Method and Description
double	getLabelOverlap(Object label1, IlvRect rect1, double angle1, Object label2, IlvRect rect2, double angle2, double minDist) Returns the overlap between two labels, if the labels would be at the given positions specified by the passed rectangles and the rotation angle.
double	getObstacleOverlap(Object label, IlvRect labelRect, double angle, Object obstacle, IlvRect obstacleBBox, double minDist) Returns the overlap between the label and the obstacle, if the label would be at the given position specified by the passed rectangle and the rotation angle.
double	getPolylineObstacleOverlap(Object label, IlvRect labelRect, double angle, Object polylineObstacle, IlvPoint[] pts, double lineWidth, double minDist) Returns the overlap between the label and the polyline obstacle, if the label would be at the given position specified by the passed rectangle and the rotation angle.
double	getRotation(Object label, IlvRect rect) Returns the rotation of the label if it were placed at the position given by the input rectangle rect.
void	setRotation(Object label, double angle) Rotates the label around the center of its bounding box.

Method Detail

getLabelOverlap

double getLabelOverlap(Object label1,
                       IlvRect rect1,
                       double angle1,
                       Object label2,
                       IlvRect rect2,
                       double angle2,
                       double minDist)

Returns the overlap between two labels, if the labels would be at the given positions specified by the passed rectangles and the rotation angle. This is used as a test before the labels are actually moved to these positions. Therefore, the labels are still at the old positions at the time of the call.

The shape of label1 is considered to be the rectangle rect1 rotated clockwise by angle1 around the center of rect1. The shape of label2 is considered to be the rectangle rect2 rotated clockwise by angle2 around the center of rect2. The angles are given in degree.

A return value of 0 indicates that there is no overlap if the labels are moved to the given positions. For instance, the size of the overlapped area can be used as the overlap value.

The overlap value should be symmetric, that is, the returned value should be the same for label pairs independent of the order in which the labels are passed as arguments.

Parameters:

label1 - The first label.

rect1 - The unrotated bounding box of the first label, translated to the proposed position of the label.

angle1 - The rotation angle of the first label.

label2 - The second label.

rect2 - The unrotated bounding box of the second label, translated to the proposed position of the label.

angle2 - The rotation angle of the second label.

minDist - The desired minimal distance between labels.

Returns:

A value that describes the amount of overlap.

getObstacleOverlap

double getObstacleOverlap(Object label,
                          IlvRect labelRect,
                          double angle,
                          Object obstacle,
                          IlvRect obstacleBBox,
                          double minDist)

Returns the overlap between the label and the obstacle, if the label would be at the given position specified by the passed rectangle and the rotation angle. This is used as a test before the label is actually moved to this position. Therefore, the label is still at the old position at the time of the call.

The shape of label is considered to be the rectangle labelRect rotated clockwise by angle around the center of labelRect. The angle is given in degree.

A return value of 0 indicates that there is no overlap if the label is moved to the given position. For instance, the size of the overlapped area can be used as the overlap value.

Parameters:

label - The label.

labelRect - The unrotated bounding box of the label, translated to the proposed position of the label.

angle - The rotation angle of the label.

obstacle - The obstacle.

obstacleBBox - The bounding box of the obstacle.

minDist - The desired minimal distance between label and obstacle.

Returns:

A value that describes the amount of overlap.

getPolylineObstacleOverlap

double getPolylineObstacleOverlap(Object label,
                                  IlvRect labelRect,
                                  double angle,
                                  Object polylineObstacle,
                                  IlvPoint[] pts,
                                  double lineWidth,
                                  double minDist)

Returns the overlap between the label and the polyline obstacle, if the label would be at the given position specified by the passed rectangle and the rotation angle. This is used as a test before the label is actually moved to this position. Therefore, the label is still at the old position at the time of the call.

The shape of label is considered to be the rectangle labelRect rotated clockwise by angle around the center of labelRect. The angle are given in degree.

A return value of 0 indicates that there is no overlap if the label is moved to the given position.

Label layout algorithms should call this method for polyline obstacles instead of getObstacleOverlap(Object, IlvRect, double, Object, IlvRect, double). to allow the concrete labeling model to optimize the treatment of polyline obstacles.

Parameters:

label - The label.

labelRect - The unrotated bounding box of the label, translated to the proposed position of the label.

angle - The rotation angle of the label.

polylineObstacle - The polyline obstacle.

pts - The points that define the shape of the polyline obstacle.

lineWidth - The line width of the polyline obstacle.

minDist - The desired minimal distance between label and obstacle.

Returns:

A value that describes the amount of overlap.

See Also:

IlvLabelingModel.isPolylineObstacle(Object)

getRotation

double getRotation(Object label,
                   IlvRect rect)

Returns the rotation of the label if it were placed at the position given by the input rectangle rect. 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.

Parameters:

label - The label.

rect - The proposed position of the label.

Returns:

The rotation angle in degree.

setRotation

void setRotation(Object label,
                 double angle)

Rotates the label around the center of its bounding box. This is called by the layout algorithm at the end of layout to rotate the label. At this time point, the label is already moved to its final position.

The method may do nothing if it is not necessary to rotate the label when it is placed at a position. For instance, labels placed at links may get automatically rotated according to their position. Therefore it is not necessary for the layout algorithm to rotate the label explicitly.

Parameters:

label - The label.

angle - The rotation angle in degree.