Point label descriptor

Positioning at an obstacle

The following example shows how to position a label at a specific obstacle in Java™ .

layout.setLabelDescriptor(label,
    new IlvAnnealingPointLabelDescriptor(label, node,
          IlvAnnealingPointLabelDescriptor.ELLIPTIC, IlvDirection.Right));

This specification can be used if the label must be placed at a node that has an elliptical or circular shape. The label is placed in the free area around the node so that the border of the label just touches the border of the node (see the following figure). The preferred position is the right side of the node, but this preferred position is used only if it does not create overlaps. If the node is moved or reshaped, the next call of label layout will update the position of the label automatically so that it follows the node.

Diagram
illustrating the potential positions of a label around a node

Potential label positions around a node

The example uses the following constructor:

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

This constructor takes the following parameters:

The relatedObstacle parameter is the obstacle that gets the label. The label is placed outside but close to this obstacle. The related obstacle can be a node of a graph, a city of a geographic map, a station of a railroad, and so on, whatever needs to have a label. The shape of the related obstacle should be either an ellipse, a circle, or a rectangle.
The shape argument can take the following values:
- IlvAnnealingPointLabelDescriptor.ELLIPTIC for ellipses or circles,
- IlvAnnealingPointLabelDescriptor.RECTANGULAR for rectangles.
  
  If the real shape of the related obstacle is neither of these, pass the shape that is the best approximation. For instance, if the obstacle is an IlvRoundRectangle, it can be considered as a rectangular shape and the RECTANGULAR option is then the best approximation.
The preferredDirection parameter is a suggestion of where the label layout algorithm should preferably place the label. If the area at the preferred position is occupied, the label will be placed elsewhere. Options for the preferred position are:
- IlvDirection.Left
- IlvDirection.Right
- IlvDirection.Top
- IlvDirection.Bottom

Positioning at a point

The following example shows how to position a label at a specific point in Java:

layout.setLabelDescriptor(label,
    new IlvAnnealingPointLabelDescriptor(label, null, new IlvPoint(25, 75),
          5f, 15f, IlvDirection.Right));

Use this specification if the label must be placed close to specific coordinates, like (in this example 25, 75) regardless of any obstacle. The label must be at least 5 coordinate units and at most 15 coordinate units away from the point (see the following figure). The preferred position is at the right side of the point.

Diagram
illustrating the potential positions of a label between 5 and 15 coordinate
units away from a point

Potential label positions between 5 and 15 units away from a point

The example uses the following constructor:

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

This IlvAnnealingPointLabelDescriptor constructor takes the following parameters:

relatedObstacle and referencePoint: The label is placed close to the reference point. It does not take the position of the related obstacle into account. If the related obstacle is moved, the label does not follow the obstacle on the next call of layout, but stays at the reference point.

If a related obstacle is specified, the label is not pushed away from the related obstacle. Rather, it is pushed away from all other obstacles to avoid overlaps. You can set the relatedObstacle parameter to null if the label is independent of all obstacles.
minDist and maxDist: These are the minimum and maximum distances from the reference point, measured from the border of the label. If you set the minimum and maximum distance to 0, the label will just touch the reference point. To keep the circular area around the reference point free, set the minimum distance accordingly. Most of the time you probably want to keep the label close to the reference point; hence, set the minimum and maximum distances to the same value.
preferredDirection: This parameter indicates whether the label should be placed to the left, right, top, or bottom of the reference point. This is a suggestion for the labeling algorithm, as described for Positioning at an obstacle.

Positioning on multiple criteria

The most powerful constructor combines all the possibilities described in Positioning at an obstacle and Positioning at a point:

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

This IlvAnnealingPointLabelDescriptor constructor takes the following parameters:

relatedObstacle and referencePoint: If a related obstacle is specified and the reference point is null , the label is placed close to the related obstacle. If a reference point is not null, the label is placed close to the reference point independently of the related obstacle position.
shape: The shape of the free area around the point can be rectangular or elliptic.
halfWidth and halfHeight: The parameter halfWidth is the minimum distance of the label to the reference point in the horizontal direction. The parameter halfHeight is the minimum distance of the label to the reference point in the vertical direction. If the reference point is null , the parameters halfWidth and halfHeight are calculated from the bounding box of the related obstacle.
maxDistFromPath: This parameter specifies the maximum additional distance allowed for the label (shown in Potential label positions with rectangular shape at a point).
preferredDistFromPath: This parameter specifies the preferred additional distance for the label. Its value should be between 0 and maxDistFromPath.
preferredDirection: This parameter indicates whether the label should be placed to the left, right, top, or bottom of the reference point or related obstacle. This is a suggestion for the labeling algorithm, as described in Positioning at an obstacle

Starting from an empty descriptor (point)

An alternative way to create a point label descriptor is to start from the empty descriptor:

descriptor = new IlvAnnealingPointLabelDescriptor();

Before using the empty descriptor, you must fill it with information on how the label should be placed. As a minimum, you need to specify a related obstacle or a reference point. For example:

descriptor.setRelatedObstacle(obstacle);
descriptor.setShape(IlvAnnealingPointLabelDescriptor.ELLIPTIC);
descriptor.setPreferredDirection(IlvDirection.Left);

At the end of all changes, the descriptor must be passed to the layout instance:

layout.setLabelDescriptor(label, descriptor);

Once the descriptor is passed to the layout instance, it should normally not be changed. If you need to change it later, you must pass it to the layout instance again.

Diagram
illustrating the potential positions of a label at a rectangular shape

Potential label positions with rectangular shape at a point

Example of specifying point label descriptor

Example of an IlvGeneralNode specification with label:

In CSS

You can specify all multiple criteria of the point labeling descriptor except the related obstacle. In CSS, the related obstacle is always the node that owns the label. The reference point and the shape ( ELLIPTIC or RECTANGULAR ) are automatically derived from the node that owns the label, but can be overridden in the CSS specification.

Example of an IlvGeneralNode specification with label:

node {
    class: "ilog.views.sdm.graphic.IlvGeneralNode";
     label: "@name";
    shapeType: "Rectangle"; // shape of path for label descriptor
    shapeWidth: "30";       // twice the halfWidth
    shapeHeight: "30";      // twice the HalfHeight
    labelPosition: "Left";  // preferredDirection
    labelSpacing: "2.0";    // preferredDistFromPath
}

In this example, shapeType , shapeWidth and shapeHeight specify the basic shape of the node and are taken into account by the label layout, the labelPosition specifies the preferred direction of the label for the label layout, and the labelSpacing specifies the preferred distance of the label from the path around the border of the basic shape of the node.

These parameters can be overridden by specifying the details of the point label descriptor in the following way:

node:labelLayout {
    shape: "ELLIPTIC";
    halfWidth: "16";
    halfHeight: "16";
    maxDistFromPath: "5";
    preferredDistFromPath: "3";
    preferredDirection: "Top";
}

If the node is an instance of IlvSDMCompositeNode and its fourth child is a label, the details of the label descriptor for that label can be specified in the following way:

node:labelLayout_4 {
    shape: "ELLIPTIC";
    halfWidth: "16";
    halfHeight: "16";
    maxDistFromPath: "5";
    preferredDistFromPath: "3";
    preferredDirection: "Top";
}

The meaning of these parameters is explained in Positioning on multiple criteria.