Currently, you can add labels to points, polylines and polygons:

labeling all types
Figure 1. From left to right: labeling around a point, on a path and in a path.

The drawLabel methods of LabelCanvas allow you to place a label near a point, on a path or in a path. A path can be both a polyline or polygon. As a result, you can paint a label on the edge of a polygon or a label inside the area of a polyline.

Drawing a label around a point

To draw a label around a point, the LabelCanvas provides the drawLabel method.

This method requires a style object to define the possible positions for the label around the point. There are nine positions available. The figure below illustrates the different positions and program Program: Setting label properties using a label style JavaScript object literal demonstrates how to allow multiple positions for a label. When trying to position a label on the map, the application considers each allowed position as a possible candidate for placing the label.

labeling point positions
Figure 2. All available positions for placing a label around a point
Program: Setting label properties using a label style JavaScript object literal (from samples/labeling/CitiesPainter.js)
this.labelStyle = {
  positions: PointLabelPosition.NORTH_EAST |
    PointLabelPosition.NORTH_WEST |
    PointLabelPosition.SOUTH_EAST |
    PointLabelPosition.SOUTH_WEST
};

this.labelStyle.priority = paintState.selected ? -Infinity : -population;

  label = produceLabelContents(template, name, 'hugeCity', populationTable);
  labelcanvas.drawLabel(label, shape, this.labelStyle);

Drawing a label on a path

To draw a label on a line, the LabelCanvas provides the drawLabelOnPath method. The position of the label is defined in a label style object. There are three positions available: above the line, below the line and centered on top of the line.

Alternatively, you can place labels away from the line using the OnPathLabelStyle.perpendicularOffset property:

  • If you set a positive value, labels are placed above the line at the specified perpendicular distance from the center of the line.

  • If you set a negative value, labels are placed below the line.

If both the perpendicularOffset and the position property are defined, the perpendicularOffset value takes precedence.

The label style object also provides a property to modify the rotation of the labels. By default, labels are rotated at the same angle as the path on which the label is currently placed. By using the PathLabelRotation.NO_ROTATION mode, you can simply disable rotation.

Program: Setting label properties on a OnPathLabelStyle. demonstrates how to create label style for drawLabelOnPath.

You can also repeat labels along a path using the OnPathLabelStyle.repeat property. It defines the instructions for drawing labels repeatedly. You can control the distance between labels using OnPathLabelRepeatOptions API. The initialGap describes the distance in pixels between the beginning of the path and the label. The initialGap defines how far away the first label will be drawn relative to the start of the rendering line when you have zoomed in considerably onto the path. The minimumGap defines the minimum gap in pixels between two labels on the same path.

When it is drawing non-repeated labels, the labeling algorithm attempts alternative locations for a label if conflicts with other labels occur.

Note that the shape parameter for the LabelCanvas.drawLabelOnPath method supports both polylines and polygons. In the case of a polygon, the label will be positioned along the edge of the polygon.

Program: Setting label properties on a OnPathLabelStyle. (from samples/labeling/RiverPainter.js)
this.labelStyle = {
  positions: PathLabelPosition.ABOVE,
  rotation: PathLabelRotation.FIXED_LINE_ANGLE,
  repeat: {
    minimumGap: gap,
    initialGap: initialGap
  }
};

var label = template.replace("$name", feature.properties.NAME);
labelcanvas.drawLabelOnPath(label, shape, this.labelStyle);

Drawing a label inside a path

You can draw a label inside a path using the LabelCanvas.drawLabelInPath method. This method requires a label object that defines the basic properties of the label. Currently, LuciadRIA only supports labels at the centroid of the path. As such, no specific in-path properties can be set.

Note that the shape parameter for the LabelCanvas.drawLabelInPath method supports both polylines and polygons. In the case of a polyline, the label is positioned at the centroid of the area defined by the closed polyline. Program: Setting label properties on a OnPathLabelStyle. demonstrates how to create a label style object for drawLabelInPath.

The label style object also provides the restrictToBounds property to guarantee that the label is painted only if it fits within the bounding box of the associated shape. Setting this property to true can increase the readability of the map by showing only labels for shapes that are big enough to accommodate them. This property is not supported on WebGL maps.

Whenever a label location becomes invisible due to panning or zooming actions, the labeling algorithm places the label in a new position in the current view. You can deactivate this behavior by setting the InPathLabelStyle.inView property to false.

Program: Setting label properties on a OnPathLabelStyle. (from samples/labeling/StatePainter.js)
this.labelStyle = {
  priority: 0
};
labelcanvas.drawLabelInPath(label, shape, this.labelStyle);

Dealing with label overlap

The position of a label on the map is defined by label style objects. By default, a LuciadRIA application prevents that labels are visualized on top of each other, making the label text unreadable. This process is called label decluttering.

To determine how LuciadRIA handles the label decluttering for particular labels, you can use properties of the label style objects: priority, group and positions.

Program: Setting label properties using a label style JavaScript object literal demonstrates how to set these properties using a JavaScript object literal.

priority

allows you to indicate how important it is that a label is drawn, in the event of a conflict between multiple labels.

A label conflict occurs when two labels must be rendered on top of each other. In such a case, labels are rendered in order of priority.

Labels with a low priority value take precedence over labels with a higher priority value. If there is a conflict between labels, the label with the lowest priority value will be drawn.

When you are drawing hundreds of cities on a map for example, you could use the city population to determine label priority. This ensures that only the names of big cities are shown when all cities are in view. To assign a higher priority to cities with a larger population, you can set the priority value to the negative value of the population value.

group

allows you to assign a group name to a label object.

You can use label grouping to create a distinction between labels that have a different semantic meaning. Semantically similar labels are grouped together by means of an assigned group name, even if they belong to different layers. Labels that are painted within the same group will be decluttered, while labels across distinct groups will not. This allows you to set up different groups of decluttered labels.

The only exception is the “NON_DECLUTTERED” group name. If you assign this group name to a number of labels, all labels inside this group are painted on top of each other and are not decluttered. This effectively disables label decluttering for all labels inside this group.

positions

describes the different positions at which a label can be placed, relative to the object it is linked to.

If a label cannot be placed at a certain position, due to a label conflict for example, a different position will be tried. When you are painting a label around a point for example, you can choose to position the label at the north or south side of the point. Each position is expressed as a constant integer value. To allow for multiple positions, simply combine these values using a bitwise OR.

Which positions you need to define depends on the type of object you are labeling: points, or lines and polygons.