Perforce JViews Diagrammer Code Example: Link Label Layout

Description

This sample illustrate the Annealing Label Layout provided by the JViews Label Layout module. It shows how to automatically place labels close to polyline links of a grapher.

How to Use the Code Example

• This application shows a manager view that displays a grapher read from a file. You may change the grapher sample using Select Graph list at the top of the application.
• You can see the labels (the text objects) and the obstacles (the links, circles and rectangles). Some of the links own some of the labels. That is, the layout algorithm should place these labels close to the corresponding links.
• The application also has interactor buttons on the top of the application. They are: pan, select, zoom box, zoom in, zoom out, and show all (fit to contents). You can use the select interactor to move obstacles and labels around.
• On the bottom of the window, the Random button places the labels randomly, and the Layout button places the labels near the links that own the labels. It applies the IlvAnnealingLabelLayout to the grapher.
• Notice that after layout, the labels follow the links automatically when you move the links.
• Several spacing parameter and label placement options are provided. For details, see the corresponding section of the User's Manual. You can change the preferred side and the allowed side where the labels should be attached to the links. The preferred side is a hint for the layout algorithm which is evaluated only if there is enough free space. The allowed side is a constraint for the layout algorithm which is always obeyed even if there is not enough space.
• The meaning of the preferred and allowed side specification depends on the side association. If the side association is local, each link has two sides: left and right. The sides can be determined from the flow direction of the link. Consider yourself standing on the link looking in the direction where the link continues towards the target node, and then determine which sides are left and right. Hence, the meaning of left and right in local side association is relative to the link. If the side association is global, the side specification is independent from the links and more like a compass direction: north is top, south is bottom, west is left and east is right. In global association, the sides don't depend on the link direction. Here, more options are possible: top, bottom, left, right and combinations of these.
• The minimal offset is a hint for the algorithm about the distance labels should be placed from unrelated obstacles. If the minimal offset is too small, a person looking at the diagram may be unable to decide whether the label belongs to the link or the obstacle. This is because the algorithm may place the label very close to an obstacle when the offset is too slight.
  The preferred offset is a hint about how far the label should be placed away from the link that owns the label. The overlap offset is the converse: it is the amount the label should overlaps the link that owns the label. The recommended overlap offset is 0 to place labels without overlaps.
• You can enable or disable the quadtree. On large samples, layout is performed faster when the quadtree is enabled. Furthermore it is possible to display:
  • The precise box around the label which is considered during the placement.
  • The red auxiliary lines that show which label belongs to which obstacle.
• After each layout, the status line at the bottom of the application window shows the layout time and the amount of remaining overlap. The remaining overlap value is displayed as absolute value and as a logarithmic scaled percentage value. If there are no overlaps, it shows 0%.

How to Run the Code Example as an Application

This code example can be run as an application. The installation directory contains an executable JAR file, link-label-layout.jar, that allows you to execute the code example with a double click from a file browser. Note that if you are using Internet Explorer, you can open the installation directory and execute the JAR file from the browser. This technique may not work in other Web browsers.

Alternatively, you can run the code example application from the command line. First check that the Ant utility is properly configured. If not, see the instructions on how to configure Ant for Perforce JViews.

Then, go to the installation directory of the code example and type:

ant run

Topics Covered

• Grapher
• Label layout
• Link Label layout
• Link Label layout parameters
• Interactor

Detailed Description

This application illustrates how to automatically place labels close to the polyline links of a grapher. The same mechanism can be used to place labels close to any polylines. That is, it can be used to label the roads of a map: each label is placed close to the polyline object that represents the road. The label layout algorithm used in this sample is based on Simulated Annealing.
It tries to place labels such that the overlaps among labels, and between labels and obstacles are small. Overlaps are avoided in order to keep labels readable.
Simulated annealing is a quality controlled, randomized iterative heuristic. The labels are placed according to a temperature scheme, and the quality of the placement increases when the temperature decreases. The quality is defined by the amount of overlaps between pairs of labels and between labels and obstacles. The fewer overlaps the higher the quality. Simulated annealing, as randomized algorithm, does not guarantee a placement of the labels without overlaps. However, it produces a quality layout with a high probability.

Samples

There are four samples:

• A first small sample. Each link has one label. Notice that the algorithm tries to attach the labels "Start Label", "Center Label" and "End Label" approximately at the start, center and end of the link respectively. The other labels are placed freely.
• Another small sample. There is only one link, but this link has forty labels. This sample can be used to study the effect of the allowed (and preferred) side specification in local or global side association.
• A medium sample. Some links have up to three labels, other links have no labels.
• A large and dense sample. Each link has one label.

Notes about this application

• If you switch the label box on or off, a layout refresh is necessary. Labels with boxes are larger than labels without boxes.
• In these samples, the layout speed is dominated by the drawing speed. When the label box is switched on, label drawing is noticeably slower than when the label box is switched off. To get an impression of the layout speed, switch the label box off.
• The quality of the labeling depends on the available space. The algorithm is not able to move obstacles around to create more space for labels.

Installation Directory

The Link Label Layout code example is installed here.

Classes Involved

• ilog.views.graphlayout.labellayout.annealing.IlvAnnealingLabelLayout

Source Files

• LinkLabelLayoutApp