Perforce JViews Diagrammer Code Example: Rotated Label Layout

Description

This sample illustrates 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. It also shows how annealing label layout handles rotated labels.

How to Use the Code Example

This application shows a manager view that displays a grapher.
You can see the labels (the text objects) and the obstacles (the links and rectangles). Some of the links own some labels, that is, the layout algorithm should place these labels close to the corresponding links.
The application also has interactor buttons on the top side of the application window. 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 application window, the Random button places the labels randomly. The Layout button places the labels near the links that own the labels. It applies the IlvAnnealingLabelLayout to the grapher.
Notice that the labels follow the links automatically when you move the links.
The minimal offset is a hint for the algorithm about how far the labels should be placed away from unrelated obstacles such that these obstacles are not confused with the links that owns the label.
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.
After each layout, the status line at the bottom 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, then 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, rotated-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 polyline links of a grapher. The same mechanism can be used to place labels close to any polylines, e.g., 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.

Notes about this application

If you select and deselect Label Box, 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 Label Box is selected, label drawing is noticably 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.