Polyline label descriptor

> > > > >

If you want to place labels at straight lines, polylines, or links, you should use the class IlvAnnealingPolylineLabelDescriptor. The allowed area for labels at a polyline is different from the rectangular or elliptic area considered for placing labels at a reference point (see Positioning at a point). A polyline has two sides where the label can be placed along a path. This is known as the polyline labeling problem.

This section first explains how to code a polyline label descriptor in Java™ , then gives a CSS sample.

Note

The polyline label descriptor is not suitable for placing labels at splines or spline links. Because splines have a complex geometric shape, the automatic placement of labels at splines is currently not supported.

Simple positioning at a link

This specification can be used if the label must be placed at a straight or polyline link. Here is an example:

 layout.setLabelDescriptor(label,new IlvAnnealingPolylineLabelDescriptor(label, 
link,IlvAnnealingPolylineLabelDescriptor.CENTER));

The label is placed near the center of the link such that one border of the label just touches the link. If the link is moved or reshaped, the next label layout call will update the position of the label automatically to follow the link.

The example uses the following IlvAnnealingPolylineLabelDescriptor constructor:

IlvAnnealingPolylineLabelDescriptor (Object label,
                                     IlvLinkImage link,
                                     int anchor)

The options for the anchor parameter are:

IlvAnnealingPolylineLabelDescriptor.CENTER : places the label near the center of the link (that is, in the middle third of the link path).
IlvAnnealingPolylineLabelDescriptor.START : places the label near the source node of the link (that is, in the first third of the link path).
IlvAnnealingPolylineLabelDescriptor.END : places the label near the target node of the link (that is, in the last third of the link path).
IlvAnnealingPolylineLabelDescriptor.FREE : places the label anywhere on the link.

Diagram
illustrating the anchors of the link label descriptor

Anchors for label positions at a link

Simple positioning at a polyline obstacle

Use this specification if the label must be placed at a polyline obstacle (an instance of IlvLine or IlvPolyline in the default labeling model). The polyline obstacle does not need to be a link of a grapher.

Here is an example:

layout.setLabelDescriptor(label,
    new IlvAnnealingPolylineLabelDescriptor(label, polyline,
          IlvAnnealingPolylineLabelDescriptor.FREE,
          IlvDirection.Left, IlvDirection.TopLeft,
          IlvAnnealingPolylineLabelDescriptor.GLOBAL));

The label is placed anywhere at the left or top side of the polyline obstacle, with preference given to the left side.

The example uses the following constructor:

IlvAnnealingPolylineLabelDescriptor
                                 (Object label, 
                                  Object relatedPolylineObstacle,
                                  int anchor,
                                  int preferredSide, 
                                  int allowedSide, 
                                  int sideAssociation)

Even though a polyline does not have a source node or a target node, the anchor parameter can be used in the same way as for links ( CENTER , START , END , and FREE ). The first control point of the polyline is the start point. Labels with anchor START are placed closer to the first control point, and labels with anchor END are placed closer to the last control point of the polyline.

The value of the preferredSide parameter is a suggestion of where the label layout algorithm should preferably place the label. If the area at the preferred side is occupied, the label is placed elsewhere.

In contrast, the allowedSide parameter is a strict constraint: it is always obeyed, even if the entire area at the allowed side is occupied and the label must overlap the obstacles in that area.

Side association

The orientation of the preferred and allowed sides depend on the sideAssociation parameter. This parameter can take the following values (see the following figure):

IlvAnnealingPolylineLabelDescriptor.LOCAL
IlvAnnealingPolylineLabelDescriptor.GLOBAL

Side associations

Local side association

If the side association is local, each polyline has two sides: left and right. The sides can be determined from the flow direction of the polyline from start point to end point. Consider yourself standing on the polyline looking in the direction where the polyline continues towards the end point, and then determine which is the left and which is the right side. Hence, the meaning of left and right in local side association is relative to the polyline. The options for the preferredSide and allowedSide parameters are in this case:

IlvDirection.Left
IlvDirection.Right

You can also specify the value 0 for the allowed side, which indicates that you do not want to restrict the side: both sides are allowed.

Global side association

If the side association is global, the side specification is independent of the flow direction of the polyline and more like a compass direction: north is top, south is bottom, west is left, and east is right. Here more options are possible: in addition to the basic top, bottom, left, right, all meaningful combinations of these are allowed. You specify the sides in the following way:

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

You can also use combinations of these, such as:

IlvDirection.Left | IlvDirection.Right (left or right but not top or bottom).
IlvDirection.Left | IlvDirection.Top (which is the same as IlvDirection.TopLeft , meaning the left or the top side).

You can specify the value 0 for the allowed side if all sides should be allowed.

Full positioning at a link

The most powerful constructor of a descriptor for a label that should be placed at a link is the following IlvAnnealingPolylineLabelDescriptor one:

IlvAnnealingPolylineLabelDescriptor
                                 (Object label, 
                                  Object link, 
                                  Object source, 
                                  Object target,
                                  int anchor,
                                  float maxDistFromLink, 
                                  float preferredDistFromLink,
                                  int preferredSide, 
                                  int allowedSide, 
                                  int sideAssociation,
                                  float topOverlap, 
                                  float bottomOverlap,
                                  float leftOverlap, 
                                  float rightOverlap)

It combines all the possibilities described in Simple positioning at a link: in addition to the anchor, the side association, and the allowed and preferred sides, you can specify overlap options.

You must pass the link as well as the source node and the target node of the link. The label does not need to touch the link. If you want to allow the label to be placed at a short distance from the link, then specify the maximum distance by maxDistFromLink and the preferred distance by preferredDistFromLink . Conversely, you may want to allow the link to partially overlap the label. You specify this by setting topOverlap , bottomOverlap , leftOverlap , or rightOverlap to a value larger than 0. This is illustrated in the following figure.

Picture
illustrating the distance from link and the overlap parameters of
the label descriptor

Distance and overlap at link

Full positioning at a polyline obstacle

If the label should be placed at a polyline that is not a link, then the most powerful IlvAnnealingPolylineLabelDescriptor constructor is the following one:

IlvAnnealingPolylineLabelDescriptor
                               (Object label,
                                Object relatedObstacle,
                                IlvPoint[] referencePoints, 
                                float lineWidth, 
                                float minPercentageFromStart,
                                float maxPercentageFromStart,
                                float prefPercentageFromStart,
                                float maxDistFromPath, 
                                float preferredDistFromPath, 
                                int preferredSide, 
                                int allowedSide, 
                                int sideAssociation, 
                                float topOverlap, 
                                float bottomOverlap, 
                                float leftOverlap, 
                                float rightOverlap)

It combines all previously mentioned possibilities. If the label should be placed at a polyline obstacle, then pass this object as the related obstacle. If the label should be placed at an imaginary polyline, then pass the polyline with the points parameter and the width of the polyline with the lineWidth parameter. Instead of an anchor, you can pass the area where the label is placed by the minimum, maximum, and preferred percentage values relative to the polyline length. The minimum and maximum percentages are strictly obeyed, while the preferred percentage is only a recommendation for the layout.

For example, if you want to specify that the label can be placed anywhere but you prefer the center of the polyline, specify 0 and 100 for the minimum and maximum percentages and 50 for the preferred percentage. If there is not enough free space at the center, the label will be placed elsewhere.
If you want to specify that the label must be placed close to the center even if there is not enough space, then specify, for example, 40 and 60 for the minimum and maximum percentages instead.

Starting from an empty descriptor (polyline)

An alternative way to create a polyline label descriptor is to start with the empty descriptor:

descriptor = new IlvAnnealingPolylineLabelDescriptor();

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 reference points and line width. For instance:

descriptor.setRelatedObstacle(polyline);
descriptor.setMinPercentageFromStart(10f);
descriptor.setMaxPercentageFromStart(90f);
descriptor.setPreferredPercentageFromStart(50f);

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.

Example of specifying polyline label descriptor

Example of an IlvGeneralLink instance with a label:

In CSS

You can specify all multiple criteria of the polyline labeling descriptor except the related obstacles. In CSS, the related obstacle is always the link that owns the label. The related source and target object of the link label descriptor are calculated from the source and target of the link. The reference points and line width are automatically derived from the link that owns the label, but can be overridden in the CSS specification.

link {
    class : "ilog.views.sdm.graphic.IlvGeneralLink";
    lineWidth : "2";
    label : "@name";
    decorationPositions[0]: "0.8";  // prefPercentageFromStart
}

In this example, the lineWidth value of the link automatically specifies the line width for the label descriptor, and the decorationPositions[0] affects where the label is anchored at the link. These parameters can be overridden by specifying the details of the polyline label descriptor in the following way:

link:labelLayout {
    lineWidth: "3";
    minPercentageFromStart: "30";
    maxPercentageFromStart: "70";
    preferredPercentageFromStart: "50";
    maxDistFromPath: "4";
    preferredDistFromPath: "2";
    preferredSide: "Left";
    allowedSide: "Left";
    sideAssociation: "GLOBAL";
    topOverlap: "1";
    bottomOverlap: "1";
    leftOverlap: "1";
    rightOverlap: "1";
}

If the link is an instance of IlvSDMCompositeLink and its fourth child is a label, the details of the descriptor for this label can be specified in the following way:

link:labelLayout_4 {
    lineWidth: "3";
    minPercentageFromStart: "30";
    maxPercentageFromStart: "70";
    preferredPercentageFromStart: "50";
    maxDistFromPath: "4";
    preferredDistFromPath: "2";
    preferredSide: "Left";
    allowedSide: "Left";
    sideAssociation: "GLOBAL"”;
    topOverlap: "1";
    bottomOverlap: "1";
    leftOverlap: "1";
    rightOverlap: "1";
}

The meaning of these parameters is already explained in Full positioning at a link and Full positioning at a polyline obstacle.

Current section

Annealing label layout