Perforce JViews Diagrammer Code Example: Point Label Layout
Description
 |
This sample illustrate the Annealing Label Layout provided by the JViews Label Layout module. It shows how labels can be automatically placed close to given points.
How to Use the Code Example
- This application shows a manager view that displays a manager read from a file. You may change the manager sample using the Select Sample list at the top of the application.
- You can see the labels (the text objects) and the obstacles (the lines, circles, ellipses and rectangles). Some of the obstacles own some labels, that is, the layout algorithm should place these labels close to the corresponding obstacles.
- The application also has interactor buttons on the top 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,
and the Layout button places the labels near the
corresponding obstacles that own the labels.
It applies the
IlvAnnealingLabelLayoutto the manager. - Notice that after layout, the labels follow the obstacles automatically when you move the obstacles.
- 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 direction where the labels should be attached to the owner obstacles. 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 obstacle that owns the label. The preferred offset is a hint about how far the label should be placed away from the obstacle that owns the label. It is possible to enable or disable the quadtree. On very large samples, layout is performed faster when the quadtree is enabled. However, most of the sample shown here are too small to notice the speed difference. Furthermore it is possible to show the precise box around the label which is considered during the placement, and the auxiliary lines that show which label belongs to which obstacle.
- 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,
point-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
- Point Label layout
- Point Label layout parameters
- Interactor
Detailed Description
This application illustrates how labels can be automatically placed close
to given points. A typical application is the labeling of cities in
a geographic map. Another application is to label the nodes of a graph.
The label layout algorithm used in this sample is based on
Simulated Annealing.
It tries to place labels such that the overlaps among 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 five samples:
- A first small sample, each obstacle has one label. The labels have different sizes.
- Another small sample with some polyline obstacles. The labels are placed close the the circular obstacles in such a way so that they don't overlap the polyline obstacles.
- A medium sample. Some obstacles have up to three labels.
- A large sample with many additional obstacles. The labels are placed close the the circular obstacles.
- A huge sample. Each obstacle has one label. You may notice the speedup of the quadtree at this sample, if you set the minimal offset to a larger value (for instance, 30).
Notes about this application
- If you select or delsect Label Box checkbox, a relayout 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 noticable 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 Point Label Layout code example is installed here.