Labels in style sheets

The <label> section in a <layer> section tells CartoType to draw a label and defines its style, including font attributes.

You can have up to two <label> sections in a <layer>. That enables you to draw both a highway shield with the highway reference, and an ordinary name along the road, for example. Use <labelAttrib> to select the correct name for each label, if using more than one.

The <label> attributes, in alphabetic order, are:

  • abbreviate: allow or forbid the use of abbreviations if the label is too long. Values are 'yes' or 'no'. The default value is 'yes'. Abbreviations are taken from a standard list. For example, if the label 'High Street' is too long to fit its space it will be abbreviated to 'High St'.
  • align: the alignment of lines when the label is broken into more than one line. Values are 'center' (the default), 'standard' (left-alignment for left-to-right text, right-alignment for right-to-left (Arabic, Hebrew, etc.) text), 'reverse' (the opposite of 'standard'), 'left' and 'right'.
  • allowOtherLabels: allow or forbid other labels to overlap the object. Values are 'yes' and 'no'. The default value is 'yes'.
  • baseline: the baseline on which to draw the text of the label. The allowed values are 'ideographic', 'hanging', 'mathematical', 'central', 'middle', 'text-before-edge', 'text-after-edge', and 'central-caps'. All except the last are as in SVG; 'central-caps' is half way between the alphabetic baseline and the top of Latin capital letters. The default values are 'central-caps' for uppercase labels, 'alphabetic' for others.
  • baselineOffset: finer control over the baseline position can be achieved by specifying a baseline offset, which is a distance by which the baseline is moved after the baseline type has been applied. Negative values move the text up and positive values move it down. Example: baselineOffset='-30%,-10pt,-2pt' is used in one style sheet in combination with position='abovePath' to move a label slightly away from the line of a road. The label is moved up by 30% of the road line width, but not by more than 10pt or less than -2pt.
  • case: either 'lower', 'upper', 'title', 'none', 'assume-lower', 'assume-title' and 'assume-upper'. Title case capitalizes the first letter of each word except particles like 'of'. The special value 'none' causes the case to be unchanged, preserving the form of the label stored in the database. The other special values 'assume-lower', 'assume-title' and 'assume-upper' also preserve the form of the label found in the database, but force the label to be positioned according to the rules for the assumed case: for example, upper-case labels drawn on a street use a different baseline to title-case labels.
  • color: the text color
  • condense: allow or forbid the use of a condensed font if the label is too long. Values are 'yes' or 'no'. The default value is 'yes'.
  • copy-fit: this parameter allows labels drawn along a path - that is, labels drawn along roads and other linear features, or drawn in polygons using the 'centralpath' position - to be expanded to fit the path by inserting letter spacing and word spacing. If the value is 'yes' copy-fitting is turned on, with a maximum expansion of four times the normal length of the text. Other values can be used to state a different maximum expansion: for example the value '6' allows the text to expand to six times its normal length.
  • duplicate: if present and greater than zero, this parameter gives a preferred minimum distance between identical labels. You can use units as well as plain pixels, and specify a minimum and maximum. For example, duplicate='500' asks for a minimum spacing of 500 pixels, while duplicate='10cm,1000m' asks for the spacing to be ten centimetres or 1000 projected metres, whichever is greater. This is a relatively expensive feature at run-time and is intended to prevent highway shields or names from being repeated too often.
  • enable: the values 'yes' and 'no' can be used to enable and disable the drawing of labels; this attribute is designed to allow label styles inherited from other styles, such as nested conditional styles , and bridge, tunnel and ramp styles, to turn label drawing off when it is turned on in the parent style, or vice versa. By default, label drawing is turned on by the presence of a
  • font-family: the font family name (e.g., 'DejaVu Serif') or an SVG generic family keyword: 'serif', 'sans-serif', 'cursive', 'fantasy', or 'monospace'.
  • font-size: a dimension giving the font height
  • font-smooth: this parameter controls anti-aliasing, and is one of the values 'auto', 'never', or 'always', or a dimension representing the smallest font size at which anti-aliasing is done.
  • font-stretch: one of the values 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'semi-expanded', 'expanded', 'extra-expanded', or 'ultra-expanded'.
  • font-style: 'italic', 'oblique' or 'normal'. The default is 'normal'.
  • font-weight: only 'bold' and 'normal' are supported. The default is 'normal'.
  • glow: if this attribute is present it specifies a color drawn as an outline around text to give a glowing effect. The standard glow color is white, but any color can be used. Here is a label drawn with a glow effect:

    glowing label

    The 'glow' attribute cancels the 'background' attribute.
  • glowOffsetX and glowOffsetY: the x and y offsets of the glowing background if any. Percentages may be used: 100% = 1em (the font size). The default value is zero. The offsets can be used to create a shadowed text effect.
  • glowWidth: the width of the glowing background if any. The default value is one pixel.
  • labelFormat: You can add label format specifications telling CartoType which attributes to look for when drawing a label, and how to display them. See the section Label formats in detail below.
  • leading: extra space between lines in multi-line labels. If it is not set, the default value of 1/12em, with a minimum of 1 pixel, is used. You can use units as usual when setting the leading. Percentages are relative to the em size: 10% is the same as 0.1em.
  • letter-spacing: extra space inserted between letters. Percentages refer to the em unit (current font size).
  • maxPolygonLabelExtra: for labels on polygon objects, the maximum amount by which a polygon label can project outside a polygon, or outside the polygon's maximum dimension in the case of the default label position, as a multiple of the label's length. For example, if iMaxPolygonLabelExtra is 1/2, a polygon label may project outside the polygon by up to half its length, ensuring that the label's center is in the polygon.
  • maxPolygonLabelLength: for labels on polygon objects, the maximum length of a label drawn in or over a polygon as a multiple of the polygon's maximum dimension. For example, if iMaxPolygonLabelLength is 2, which is the default value, a polygon label is drawn only if it is equal to or less than twice the maximum of the polygon's width and height. Values can be given as ordinary numbers or percentages.
  • maxScale: maximum scale at which labels will be drawn.
  • minPolygonSize: for labels on polygon objects, the minimum polygon size (where size means the maximum of width and height) for which the label is drawn; labels are not drawn for smaller polygons.
  • minScale: minimum scale at which labels will be drawn.
  • once: the value 'yes' causes the label to be drawn only if the center of the object is on the display. This applies only to polygon objects. It is used to ensure that a label appears on one tile only when bitmap tiles are generated. You can also specify a distance between labels using a dimension. If you do that, there may be multiple labels for a polygon, but spaced apart by a distance of at least the specified dimension. The dimension may be in map metres, real-world units, or pixels.
  • opacity: opacity of the text.
  • position: labels are positioned automatically by default, but there are special values that allow you to control label positioning.

    The position 'abovepath' draws the label above a linear feature like a road instead of over it. The baselineOffset attribute is normally used in this situation to move the label a little further away from the edge of the road.

    The position 'centralpath' tells CartoType to find the most attractive central path through a polygon, along which the label is drawn. The central path method should be used for lakes, wide rivers (defined as polygons rather than lines), parks, and other polygons apart from cities, for which it is not usually appropriate. If a label is too long for a central path it is drawn along a straight line centered on the center of gravity of the polygon, and conforming to the polygon's general orientation, and is subject to the 'maxPolygonLabelLength' attribute.

    The position 'centralpath-h' is the same as centralpath except that if the label is too long for the central path, the fallback position is a horizontal line chosen using the 'horizontal' position

    The position 'horizontal' is used for polygons and finds a horizontal line that fits inside the polygon (or extends outside as specified by the 'maxPolygonLabelExtra' and 'maxPolygonLabelLength' attributes). For non-polygon objects it is equivalent to EDefaultLabelPosition.

    The position 'icon' draws the label over an icon, for instance a US highway shield. The icon must be specified in the layer definition in the normal way.

    The position 'normal' positions the label automatically. This is the default value, but you may need to use 'normal' when overriding inherited label specifications in nested conditions, which inherit their attributes from the enclosing condition, or in bridge, ramp and tunnel label specifications, which inherit their attributes from the enclosing style.

    The position 'point' places the label with its hotspot over the central point of the object.

  • priority: the order in which labels are drawn is controlled by the priority. The default priority is 0. Labels are drawn in priority order for each group of layers followed by a <drawLabelLayer> tag. Any whole number, positive, or negative, can be used as a priority. For example, to draw station names before all default-priority names, add the attribute priority='-1' to the <label> tag in the station layer. If priorities are the same, labels are drawn in the order in which their layers appear in the style sheet, and within that (for historical compatibility reasons) in reverse order of the conditional styles in each layer.
  • shaping: controls contextual shaping (for example, the use of Arabic cursive joining forms) and bidirectional reordering. The default settings are for all this to be done automatically, with a default paragraph direction of left to right. This is normally the best thing to do, but you can turn shaping off using shaping='none'. You can also set the paragraph direction to left (default left-to-right), right (default right-to-left), force-left (forced left-to-right) and force-right (forced right-to-left). Do not use these settings unless you understand bidirectional reordering: see the Unicode Bidirectional Algorithm.
  • triangleColor: the color of a triangular pointer attached to the side of a label box for a point object.
  • triangleSize: the size of a triangular pointer attached to the side of a label box. If the object is a point, and triangleColor is not the null color, and triangleSize is greater than zero, the triangle is drawn. The tip of the triangle is the exact location of the point object.

    box label with triangle

    The <label> element used to draw these boxed labels with triangles is:
  • word-spacing: extra space added to the normal size of a word space. Percentages refer to the em unit (current font size).
  • wrap: whether or not it is permissible to wrap the label if there is not enough space for it. Values are 'yes' and 'no'. The default value is 'yes'. The 'align' attribute (see above) controls the alignment of the lines.
  • wrapLines: the maximum number of lines into which the label may be broken. At present any number greater than 2 allows an unlimited number of lines. In practice, map labels do not usually require more than three lines. The 'align' attribute (see above) controls the alignment of the lines.
  • wrapWidth: if wrapWidth is greater than zero, and the label is longer the wrapWidth, the label is split into separate lines no longer than wrapWidth, even if it would fit without splitting. Any units can be used, but the most convenient way to give the wrap width is in ems, which are units equal to the font size.

Label formats in detail

A very simple label format is just the name of a string attribute, which tells CartoType to use that string attribute for the label. The empty string indicates that the ordinary name should be used. But the syntax of a label format is in fact quite complicated and powerful. In semi-formal terms (using a loose version of Extended Backus-Naur Form):

Tokens

  • the character '+'
  • a braced <command-token>: '{' followed by zero or more characters not including '}', and terminated by '}';  example: {font-weight:bold}
  • a quoted <string>: either a single or a double quote, then zero or more characters not including the leading quote, and terminated by a matching single or double quote;  example: "Name: "
  • <attributes>: a sequence of characters not containing any of the characters '+', '{', single or double quote, or whitespace;  example: addr:housenumber
  • sequences of whitespace characters, which are ignored unless they are inside a braced section or a string

Syntax

A label format is a series of one or more sections, separated by plus signs.

<label> ::= <section> { '+' <section> }*

Each section is made up of one or more subsections.

<section> ::= <subsection>*

A subsection may be attributes, a string, or a command.

<subsection> ::= <attributes> | <string> | <command>

An <attributes> token  is a semicolon-separated list of string attribute names, which are looked up in order. An empty name matches the ordinary name ('label') of the object. Examples: ';ref' (ordinary name; ref), 'ref;' (ref, ordinary name).

<attributes> ::= <attribname> { ";" <attribname> }
<attribname> ::= <attribchar>+
<attribchar> ::= any character except '+', '{', single or double quote, or whitespace

A command is either a single command token, or a box.

<command> ::= <command-token> | <box>

A box is a box-start command, followed by a nested label, followed by a box-end command.

<box> ::= <box-start> <label> <box-end>

Box starts and ends are special commands:

<box-start> := "{[" <command-body> "}"
<box-end> ::= "{]}"

Another special command is the baseline command:

<baseline-command> ::= "{-" <command-body> "}"

All other commands are of the form

<other-command> ::= "{" <command-body> "}"

And the body of a command is:

<command-body> ::= "" | <command-start-char> <command-continuation-char>+
<command-start-char> ::= any character except {, [ or -
<command-continuation-char> ::= any character except '{'

Meaning

The label is created by concatenating all the sections together, but discarding any section not containing any text derived from a map object attribute. That allows you to write

labelFormat=';ref + " "{font-style:italic}"("name:en")"'

which is made from two sections. The first one uses the local name, or the 'ref' attribute if there's no name. The second section changes the font to italic and appends a space followed by the English name in parentheses, but only if there is an English name (and if it's different from the local name). Thus we get the labels Roma (Rome) and Edinburgh.

Literal text can be inserted using quoted strings like "(" in the previous example.

Commands contain CSS-like style commands: the empty style command {} selects the standard font.

The style command {[ ...box styles... } starts a box and the style command {]} ends a box. The box style is specified using the CSS-like commands width, padding, border, margin, border-style, border-color, border-radius and background-color. If border-radius is positive a curved box is drawn (available from CartoType 3.0 onwards). Boxes can be nested.

Newlines (use the entity reference &#10; in literal text) force a new line.

The style command {-} sets the baseline of the containing box to the baseline of the line containing the command.

Here is an example of the use of the label specification above:

complex label1

And here is another example, showing that the change to italics works correctly even if the label has to be reordered for a right-to-left script:

complex label2

And here is a more complicated example, creating a boxed label containing several different attributes, each on a separate line. The newline character is inserted using the entity reference &#10;. 

labelFormat='{[padding:20%,1pt;background-color:#EEEEAA50;border-color:slategrey;border-width:15%,0.7;border-radius:30%}
{font-weight:bold}"Name: "{font-weight:normal};+
{font-weight:bold}"&#10;Housename: "{font-weight:normal}addr:housename+
{font-weight:bold}"&#10;Street: "{font-weight:normal}addr:street+
{font-weight:bold}"&#10;City: "{font-weight:normal}addr:city+
{font-weight:bold}"&#10;Postcode: "{font-weight:normal}addr:postcode+
{font-weight:bold}"&#10;Website: "{font-weight:normal}_website+
{font-weight:bold}"&#10;Phone: "{font-weight:normal}_phone+
{font-style:italic}"&#10;Building: "{font-style:normal}_building+
{font-style:italic}"&#10;Levels: "{font-style:normal}_building:levels+
{font-style:italic}"&#10;Roof height: "{font-style:normal}_roof:height
{]}'

boxlabel3 

Style Sheets Directory