3.10.8. TextSymbolizer

Table 30. TextSymbolizer specific Attributes
Attribute Type Default Description

Text attributes

size

float

10.0

Font size in pixels

fill

color

black

Text fill color

character-spacing

float

0.0

Additional space between characters in pixels

opacity

float

1.0

Text opacity

comp-op

string

src-over

See Compositing

line-spacing

float

0.0

Extra vertical space for multi line output in pixels

text-transform

string

none

Change the case of the text: one of none, uppercase, lowercase, capitalize (first letter of each word), reverse (swap upper and lower case)

Font attributes

face-name

string

none

Font face to use: family and style name, like DejaVu Sans Book; a fixed name only, expressions are not supported

fontset-name

string

none

FontSet name; a fixed name only, expressions are not supported

lang

string

none

Language of the text as a BCP 47 Language Identifier tag like ja or zh-Hant, selects language specific glyph variants of a font; guessed from the script when not set (since Mapnik v4.0.6)

font-feature-settings

string

none

Comma separated list of OpenType typographic features

Wrap attributes

wrap-width

integer

none

Try to wrap text if it gets longer than this many pixels

wrap-before

boolean

false

Wrap before or after reaching wrap-width

repeat-wrap-character

boolean

false

Keep wrap character and repeat it on new line

wrap-character

string

none

Break text at this character only instead of using general unicode line break algorithm

text-ratio

float

none

When wrapping, keep adding lines until the label’s width to height ratio is at most this value, but don’t make lines shorter than wrap-width; only used together with wrap-width

Halo attributes

halo-fill

color

white

Text halo color

halo-opacity

float

1.0

Text halo opacity

halo-radius

float

0.0

Text halo radius in pixels

halo-rasterizer

full, fast

full

Text halo rasterizing algorithm when using Agg renderer

halo-comp-op

string

src-over

Compositing operator to use for the halo

halo-transform

SVG transformation

none

Transformation applied to the halo only, e.g. scale(1.5); AGG and grid renderers only

Placement attributes

allow-overlap

bool

false

Allow text to overlap with other text or markers

spacing

integer

0

Spacing between text labels on lines if > 0 (in pixels?)

placement

string

point

One of point, line, vertex, interior, grid, alternating-grid

grid-cell-width

float

none

Horizontal spacing between grid cells when using grid or alternating-grid placement

grid-cell-height

float

none

Vertical spacing between grid cells when using grid or alternating-grid placement

placement-type

string

dummy

Algorithm to use to avoid text overlaps, one of dummy, simple, list

placements

string

none

If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is text-placements: "E,NE,SE,W,NW,SW" (TODO: better explanation)

label-position-tolerance

float

spacing/2

Allow displacement by this many pixel with placement=line

max-char-angle-delta

float

22.5

Max. angle change between adjacent characters in degrees, to avoid placing text around sharp corners

avoid-edges

boolean

false

Avoid placing text near image edges

margin

float

none

Minimum distance from other text, shields or markers

repeat-distance

float

none

Minimum distance from other labels with same text content across geometries

minimum-padding

float

none

Minimum placement distance from image edges

minimum-path-length

float

none

Minimum length of lines or polygon boundings to place text on

dx

float

0

horizontal text displacement

dy

float

0

vertical text displacement

offset

float

0

general text displacement

horizontal-alignment

string

auto

Horizontal position of the label relative to its anchor point: left, middle, right, or auto (right for a positive dx, left for a negative one, middle otherwise); adjust with placement="line" stretches the label over the whole line by spreading the characters

vertical-alignment

string

auto

Vertical position of the label relative to its anchor point: top, middle, bottom, or auto (bottom for a positive dy, top for a negative one, middle otherwise)

justify-alignment

string

auto

Alignment of the lines of multi line labels: left, center, right, or auto (left for a positive dx, right for a negative one, center otherwise)

orientation

float

0

Rotate the label counterclockwise by this many degrees

rotate-displacement

boolean

false

Rotate the dx/dy displacement along with orientation

minimum-distance

float

?

?TODO?

largest-bbox-only

boolean

true

Only label the part of a multi polygon with the largest bounding box, instead of each part

upright

string

auto

Text direction on lines: one of auto, auto-down, left, right, left-only, right-only

TODO: explain <Placement>,<Format> and <Layout> sub-tags

Example 49. TextSymbolizer size
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="DejaVu Sans Book" size="[size]">"size "+[size]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,size
"POINT(0 0)",8
"POINT(1 0)",10
"POINT(2 0)",12
"POINT(3 0)",16
      </Parameter>
    </Datasource>
  </Layer>

</Map>
size
Example 50. TextSymbolizer text color fill
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="DejaVu Sans Book" size="12" fill="[fill]">[fill]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,fill
"POINT(0 0)",black
"POINT(1 0)",red
"POINT(2 0)",green
"POINT(3 0)",blue
      </Parameter>
    </Datasource>
  </Layer>

</Map>
fill
Example 51. TextSymbolizer text opacity
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="DejaVu Sans Bold" size="24" fill="black" opacity="[opacity]">[opacity]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,opacity
"POINT(0 0)",1.0
"POINT(1 0)",0.75
"POINT(2 0)",0.5
"POINT(3 0)",0.25
      </Parameter>
    </Datasource>
  </Layer>

</Map>
opacity
Example 52. TextSymbolizer character spacing
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="DejaVu Sans Book" character-spacing="[spaceing]">"spacing "+[spaceing]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,spaceing
"POINT(0 0)",0
"POINT(1 0)",1
"POINT(2 0)",2
"POINT(3 0)",3
      </Parameter>
    </Datasource>
  </Layer>

</Map>
character spacing
Example 53. TextSymbolizer line spacing
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="DejaVu Sans Book" line-spacing="[spaceing]" wrap-width="10">"line spaceing "+[spaceing]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,spaceing
"POINT(0 0)",0
"POINT(1 0)",5
"POINT(2 0)",10
"POINT(3 0)",15
      </Parameter>
    </Datasource>
  </Layer>

</Map>
line spacing
Example 54. TextSymbolizer face name

face-name takes the full name of a font face, family name and style, like Noto Sans Bold; the family name alone is not enough. Mapnik checks the name when loading the style, an unknown face name is an error in strict mode. mapnik.FontEngine.face_names() in Python lists the available face names.

Unlike most other text attributes face-name and fontset-name do not accept expressions, so the font can’t be taken from a data column. To use different fonts for different features, use a separate rule with a filter for each font.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="Noto Sans Regular"
                      size="16" vertical-alignment="middle" dy="-48">'Noto Sans Regular'</TextSymbolizer>
      <TextSymbolizer face-name="Noto Sans Bold"
                      size="16" vertical-alignment="middle" dy="-24">'Noto Sans Bold'</TextSymbolizer>
      <TextSymbolizer face-name="Noto Sans Italic"
                      size="16" vertical-alignment="middle" dy="0">'Noto Sans Italic'</TextSymbolizer>
      <TextSymbolizer face-name="Noto Serif Regular"
                      size="16" vertical-alignment="middle" dy="24">'Noto Serif Regular'</TextSymbolizer>
      <TextSymbolizer face-name="Noto Serif Bold Italic"
                      size="16" vertical-alignment="middle" dy="48">'Noto Serif Bold Italic'</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt
"POINT(0 0)"
      </Parameter>
    </Datasource>
  </Layer>

</Map>
face name
Example 55. TextSymbolizer lang

Chinese, Japanese and Korean share many Unicode characters whose written forms differ between these languages. Fonts covering all of them, like the Noto Sans CJK fonts used here, contain the different glyph variants, and the text language decides which one is used. Without lang Mapnik guesses the language from the script of the text, which for Han characters is always simplified Chinese.

To a lesser extent Serbian and Macedonian Cyrillic differ from Russian Cyrillic for certain characters, too, and there are some other minor cases, too.

Fonts without language specific variants are not affected by lang at all.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color='white' minimum-version="4.0.6">
  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="Noto Sans CJK SC Regular" size="24"
                      lang="[lang]">'直骨令户'</TextSymbolizer>
      <TextSymbolizer face-name="DejaVu Sans Book" dx="-100">[label]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,lang,label
"POINT(0 0)",,(none)
"POINT(0 -1)",zh-Hans,zh-Hans
"POINT(0 -2)",zh-Hant,zh-Hant
"POINT(0 -3)",ja,ja
"POINT(0 -4)",ko,ko
      </Parameter>
    </Datasource>
  </Layer>

</Map>
lang
Example 56. TextSymbolizer font feature settings

font-feature-settings turns optional OpenType font features on or off, like smcp for small capitals, c2sc for turning capitals into small capitals, too, onum for old style numerals or frac for fractions. Each comma separated entry is a feature tag, optionally followed by a value, so smcp, smcp 1 and smcp=1 all enable small caps, while -liga or liga 0 disable a feature.

Features only have an effect if the font provides them; unsupported ones are silently ignored. The example uses Noto Serif, which supports small caps. Tools like otfinfo -f list the features a font file supports.

The attribute can also be set on <Format> to apply features to a part of the text only.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">
  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="Noto Serif Regular" size="24"
                      font-feature-settings="[features]">'Small Caps'</TextSymbolizer>
      <TextSymbolizer face-name="DejaVu Sans Book" dx="-130">[label]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,features,label
"POINT(0 0)",,(none)
"POINT(0 -1)",smcp,smcp
"POINT(0 -2)","c2sc, smcp","c2sc, smcp"
      </Parameter>
    </Datasource>
  </Layer>

</Map>
font feature settings
Example 57. TextSymbolizer spacing
<?xml version="1.0" encoding="utf-8"?>
<Map background-color='white'>
  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="5"/>
      <TextSymbolizer spacing="[spacing]" face-name="DejaVu Sans Book" placement="line">[spacing]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,spacing
"LINESTRING(10 10,50 20,90 10)",30
"LINESTRING(10 20,50 30,90 20)",60
"LINESTRING(10 30,50 40,90 30)",90
      </Parameter>
    </Datasource>
  </Layer>

</Map>
spacing
Example 58. TextSymbolizer placement

placement Controls where the text is actually placed:

point

Places the text just once at the center of the geometry. In case of a polygon that may actually be outside of the polygon surface, depending on its shape

interior

Similar to point, but makes sure that the text is placed inside a polygon even if its center point is actually on its outside

line

When spacing is larger than zero the text is repeatedly printed along a line or a polygons outline with spacing pixels between texts

vertex

Tries to place the text on each vertex point of a line or a polygons outline

grid

When grid-cell-width and grid-cell-height are greater than zero the text is repeatedly printed into a polygons surface, using grid cells of the given width and height. Note that the text is not clipped at the border of the polygon, so some text may be printed slightly outside of the polygon surface.

alternating-grid

Similar to grid, but each second row is horizontally displaced by half of grid-cell-width

<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="5"/>
      <TextSymbolizer face-name="DejaVu Sans Book" placement="[placement]" grid-cell-width="30" grid-cell-height="20" spacing="30">A1</TextSymbolizer>
      <TextSymbolizer face-name="DejaVu Sans Book" allow-overlap="true" dy="50">[placement]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,placement
"POLYGON(( 1 1, 6 1, 6 5, 5 5, 5 2, 2 2, 2 5, 1 5, 1 1))",interior
"POLYGON((11 1,16 1,16 5,                    11 5,11 1))",line
"POLYGON((21 1,26 1,26 5,                    21 5,21 1))",alternating-grid
"POLYGON(( 1 11, 6 11, 6 15, 5 15, 5 12, 2 12, 2 15, 1 15, 1 11))",point
"POLYGON((11 11,16 11,16 15,                        11 15,11 11))",vertex
"POLYGON((21 11,26 11,26 15,                        21 15,21 11))",grid
      </Parameter>
    </Datasource>
  </Layer>

</Map>
placement
Example 59. TextSymbolizer grid width/height
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="5"/>
      <TextSymbolizer face-name="DejaVu Sans Book" placement="[placement]" grid-cell-width="[width]" grid-cell-height="[height]" spacing="30">A1</TextSymbolizer>
      <TextSymbolizer face-name="DejaVu Sans Book" allow-overlap="true" dy="50">[width]+","+[height]+","+[placement]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,width,height,placement
"POLYGON(( 1 1, 6 1, 6 5, 1 5, 1 1))",30,20,alternating-grid
"POLYGON((11 1,16 1,16 5,11 5,11 1))",40,20,alternating-grid
"POLYGON((21 1,26 1,26 5,21 5,21 1))",40,30,alternating-grid
"POLYGON(( 1 11, 6 11, 6 15, 1 15, 1 11))",30,20,grid
"POLYGON((11 11,16 11,16 15,11 15,11 11))",40,20,grid
"POLYGON((21 11,26 11,26 15,21 15,21 11))",40,30,grid
      </Parameter>
    </Datasource>
  </Layer>

</Map>
grid width height
Example 60. TextSymbolizer minimum path length
<?xml version="1.0" encoding="utf-8"?>
<Map background-color='white'>
  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="5"/>
      <TextSymbolizer minimum-path-length="200" face-name="DejaVu Sans Book" placement="line">A1</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt
"LINESTRING(10 10,20 10)"
"LINESTRING(10 20,30 20)"
"LINESTRING(10 30,40 30)"
      </Parameter>
    </Datasource>
  </Layer>

</Map>
minimum path length
Example 61. TextSymbolizer x offset
<?xml version="1.0" encoding="utf-8"?>
<Map background-color='white'>
  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="5"/>
      <TextSymbolizer dx="[offset]" face-name="DejaVu Sans Book" placement="line" horizontal-alignment="middle">"Some long long long long long long long long long amount of text with offset "+[offset]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
offset,wkt
-50,"LINESTRING(10 10,12 10.24,14 10.95,16 12.06,18 13.45,20 15,22 16.55,24 17.94,26 19.05,28 19.76,30 20,32 19.76,34 19.05,36 17.94,38 16.55,40 15,42 13.45,44 12.06,46 10.95,48 10.24,50 10,52 10.24,54 10.95,56 12.06,58 13.45,60 15,62 16.55,64 17.94,66 19.05,68 19.76,70 20)"
0,"LINESTRING(10 20,12 20.24,14 20.95,16 22.06,18 23.45,20 25,22 26.55,24 27.94,26 29.05,28 29.76,30 30,32 29.76,34 29.05,36 27.94,38 26.55,40 25,42 23.45,44 22.06,46 20.95,48 20.24,50 20,52 20.24,54 20.95,56 22.06,58 23.45,60 25,62 26.55,64 27.94,66 29.05,68 29.76,70 30)"
50,"LINESTRING(10 30,12 30.24,14 30.95,16 32.06,18 33.45,20 35,22 36.55,24 37.94,26 39.05,28 39.76,30 40,32 39.76,34 39.05,36 37.94,38 36.55,40 35,42 33.45,44 32.06,46 30.95,48 30.24,50 30,52 30.24,54 30.95,56 32.06,58 33.45,60 35,62 36.55,64 37.94,66 39.05,68 39.76,70 40)"
      </Parameter>
    </Datasource>
  </Layer>

</Map>
dx
Example 62. TextSymbolizer y offset
<?xml version="1.0" encoding="utf-8"?>
<Map background-color='white'>
  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="5"/>
      <TextSymbolizer dy="[offset]" face-name="DejaVu Sans Book" placement="line">"Some long long long long long long long long long amount of text with offset "+[offset]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,offset
"LINESTRING(10 10,12 10.24,14 10.95,16 12.06,18 13.45,20 15,22 16.55,24 17.94,26 19.05,28 19.76,30 20,32 19.76,34 19.05,36 17.94,38 16.55,40 15,42 13.45,44 12.06,46 10.95,48 10.24,50 10,52 10.24,54 10.95,56 12.06,58 13.45,60 15,62 16.55,64 17.94,66 19.05,68 19.76,70 20)",15
"LINESTRING(10 20,12 20.24,14 20.95,16 22.06,18 23.45,20 25,22 26.55,24 27.94,26 29.05,28 29.76,30 30,32 29.76,34 29.05,36 27.94,38 26.55,40 25,42 23.45,44 22.06,46 20.95,48 20.24,50 20,52 20.24,54 20.95,56 22.06,58 23.45,60 25,62 26.55,64 27.94,66 29.05,68 29.76,70 30)",0
"LINESTRING(10 30,12 30.24,14 30.95,16 32.06,18 33.45,20 35,22 36.55,24 37.94,26 39.05,28 39.76,30 40,32 39.76,34 39.05,36 37.94,38 36.55,40 35,42 33.45,44 32.06,46 30.95,48 30.24,50 30,52 30.24,54 30.95,56 32.06,58 33.45,60 35,62 36.55,64 37.94,66 39.05,68 39.76,70 40)",-15
      </Parameter>
    </Datasource>
  </Layer>

</Map>
dy
Example 63. TextSymbolizer offset
<?xml version="1.0" encoding="utf-8"?>
<Map background-color='white'>
  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="5"/>
      <TextSymbolizer offset="[offset]" face-name="DejaVu Sans Book" placement="line">"Some long long long long long long long long long amount of text with offset "+[offset]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,offset
"LINESTRING(10 10,12 10.24,14 10.95,16 12.06,18 13.45,20 15,22 16.55,24 17.94,26 19.05,28 19.76,30 20,32 19.76,34 19.05,36 17.94,38 16.55,40 15,42 13.45,44 12.06,46 10.95,48 10.24,50 10,52 10.24,54 10.95,56 12.06,58 13.45,60 15,62 16.55,64 17.94,66 19.05,68 19.76,70 20)",15
"LINESTRING(10 20,12 20.24,14 20.95,16 22.06,18 23.45,20 25,22 26.55,24 27.94,26 29.05,28 29.76,30 30,32 29.76,34 29.05,36 27.94,38 26.55,40 25,42 23.45,44 22.06,46 20.95,48 20.24,50 20,52 20.24,54 20.95,56 22.06,58 23.45,60 25,62 26.55,64 27.94,66 29.05,68 29.76,70 30)",0
"LINESTRING(10 30,12 30.24,14 30.95,16 32.06,18 33.45,20 35,22 36.55,24 37.94,26 39.05,28 39.76,30 40,32 39.76,34 39.05,36 37.94,38 36.55,40 35,42 33.45,44 32.06,46 30.95,48 30.24,50 30,52 30.24,54 30.95,56 32.06,58 33.45,60 35,62 36.55,64 37.94,66 39.05,68 39.76,70 40)",-15
      </Parameter>
    </Datasource>
  </Layer>

</Map>
offset
Example 64. TextSymbolizer horizontal alignment

The red dots mark the label positions. horizontal-alignment decides on which side of its position a label is placed. The default auto uses right if dx is positive, left if it is negative, and middle otherwise, so that a displaced label extends away from its point.

With placement="line" the additional value adjust stretches a label over the full length of its line by spreading its characters evenly. As the label then takes up the whole line, spacing is ignored and only one label is placed per line.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">
  <Style name="point-style">
    <Rule>
      <MarkersSymbolizer fill="red" width="6" height="6" stroke-width="0"
                         allow-overlap="true"/>
      <TextSymbolizer face-name="DejaVu Sans Book" size="16" allow-overlap="true"
                      horizontal-alignment="[align]">[align]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="point-layer">
    <StyleName>point-style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
align,wkt
left,"POINT(-10 40)"
middle,"POINT(-10 30)"
right,"POINT(-10 20)"
      </Parameter>
    </Datasource>
  </Layer>

  <Style name="line-style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="20"/>
      <TextSymbolizer face-name="DejaVu Sans Book" size="20" placement="line"
                      horizontal-alignment="[align]">"horizontal-alignment "+[align]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="line-layer">
    <StyleName>line-style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
align,wkt
left,"LINESTRING(10 40,12 40.11,14 40.43,16 40.95,18 41.65,20 42.5,22 43.45,24 44.48,26 45.52,28 46.55,30 47.5,32 48.35,34 49.05,36 49.57,38 49.89,40 50,42 49.89,44 49.57,46 49.05,48 48.35,50 47.5,52 46.55,54 45.52,56 44.48,58 43.45,60 42.5,62 41.65,64 40.95,66 40.43,68 40.11,70 40)"
middle,"LINESTRING(10 30,12 30.11,14 30.43,16 30.95,18 31.65,20 32.5,22 33.45,24 34.48,26 35.52,28 36.55,30 37.5,32 38.35,34 39.05,36 39.57,38 39.89,40 40,42 39.89,44 39.57,46 39.05,48 38.35,50 37.5,52 36.55,54 35.52,56 34.48,58 33.45,60 32.5,62 31.65,64 30.95,66 30.43,68 30.11,70 30)"
right,"LINESTRING(10 20,12 20.11,14 20.43,16 20.95,18 21.65,20 22.5,22 23.45,24 24.48,26 25.52,28 26.55,30 27.5,32 28.35,34 29.05,36 29.57,38 29.89,40 30,42 29.89,44 29.57,46 29.05,48 28.35,50 27.5,52 26.55,54 25.52,56 24.48,58 23.45,60 22.5,62 21.65,64 20.95,66 20.43,68 20.11,70 20)"
adjust,"LINESTRING(10 10,12 10.11,14 10.43,16 10.95,18 11.65,20 12.5,22 13.45,24 14.48,26 15.52,28 16.55,30 17.5,32 18.35,34 19.05,36 19.57,38 19.89,40 20,42 19.89,44 19.57,46 19.05,48 18.35,50 17.5,52 16.55,54 15.52,56 14.48,58 13.45,60 12.5,62 11.65,64 10.95,66 10.43,68 10.11,70 10)"
      </Parameter>
    </Datasource>
  </Layer>

</Map>
horizontal alignment
Example 65. TextSymbolizer vertical alignment

vertical-alignment does the same vertically. With the default auto a label displaced by a positive dy, i.e. downwards, is aligned at the bottom, one with a negative dy at the top.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">
  <Style name="style">
    <Rule>
      <MarkersSymbolizer fill="red" width="6" height="6" stroke-width="0"
                         allow-overlap="true"/>
      <TextSymbolizer face-name="DejaVu Sans Book" size="16" allow-overlap="true"
                      vertical-alignment="[align]">[align]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,align
"POINT(0 0)",top
"POINT(4 0)",middle
"POINT(8 0)",bottom
      </Parameter>
    </Datasource>
  </Layer>

</Map>
vertical alignment
Example 66. TextSymbolizer justify alignment

justify-alignment aligns the lines of a multi line label with each other, it does not change the position of the label as a whole. With the default auto the lines are aligned towards the label position, left for a positive dx, right for a negative one, and center otherwise.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">
  <Style name="style">
    <Rule>
      <MarkersSymbolizer fill="red" width="6" height="6" stroke-width="0"
                         allow-overlap="true"/>
      <TextSymbolizer face-name="DejaVu Sans Book" size="16" allow-overlap="true"
                      wrap-width="100" justify-alignment="[align]">[align]+" aligned lines of a longer text label"</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,align
"POINT(0 0)",left
"POINT(6 0)",center
"POINT(12 0)",right
      </Parameter>
    </Datasource>
  </Layer>

</Map>
justify alignment
Example 67. TextSymbolizer orientation and rotate-displacement

orientation rotates a label counterclockwise around its position. The dx/dy displacement is not rotated along with it by default, so in the top row the labels stay to the right of their points. With rotate-displacement="true", in the bottom row, the displacement is rotated, too, and a label rotated by 90° ends up above its point, one rotated by 180° to the left of it.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">
  <Style name="style">
    <Rule>
      <MarkersSymbolizer fill="red" width="6" height="6" stroke-width="0"
                         allow-overlap="true"/>
      <TextSymbolizer face-name="DejaVu Sans Book" size="14" allow-overlap="true"
                      dx="15" orientation="[angle]"
                      rotate-displacement="[rotate]">[angle]+"°"</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,angle,rotate
"POINT(0 0)",0,false
"POINT(4 0)",45,false
"POINT(8 0)",90,false
"POINT(12 0)",180,false
"POINT(0 -4)",0,true
"POINT(4 -4)",45,true
"POINT(8 -4)",90,true
"POINT(12 -4)",180,true
      </Parameter>
    </Datasource>
  </Layer>

</Map>
orientation
Example 68. TextSymbolizer largest bbox only

Both features are multi polygons made of one large and two small parts. With largest-bbox-only enabled, the default, only the part with the largest bounding box gets a label; with it disabled, each part is labeled separately. Note that parts are compared by the area of their bounding boxes, not by their actual area, and that this only applies to polygon geometries, not to multi points or multi lines.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color='white'>
  <Style name="style">
    <Rule>
      <PolygonSymbolizer fill="lightblue"/>
    </Rule>
    <Rule>
      <Filter>[mode] = true</Filter>
      <TextSymbolizer largest-bbox-only="true" face-name="DejaVu Sans Book">[mode]</TextSymbolizer>
    </Rule>
    <Rule>
      <Filter>[mode] = false</Filter>
      <TextSymbolizer largest-bbox-only="false" face-name="DejaVu Sans Book">[mode]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,mode
"MULTIPOLYGON(((0 0,4 0,4 4,0 4,0 0)),((5 0,7 0,7 1.5,5 1.5,5 0)),((5 2.5,7 2.5,7 4,5 4,5 2.5)))",true
"MULTIPOLYGON(((10 0,14 0,14 4,10 4,10 0)),((15 0,17 0,17 1.5,15 1.5,15 0)),((15 2.5,17 2.5,17 4,15 4,15 2.5)))",false
      </Parameter>
    </Datasource>
  </Layer>

</Map>
largest bbox only
Example 69. TextSymbolizer upright

Each row uses one upright value on two horizontal lines, the left one drawn from left to right, the right one from right to left, as the arrow heads show. right always runs the text in the direction the line was drawn, left against it, even if this turns the text upside down. auto, the default, picks whichever of the two directions keeps the text readable, auto-down picks the other one; on horizontal lines this always gives upside down text, so auto-down is mostly useful on near-vertical lines, see the next example. left-only and right-only never flip the text: they place it like left and right, but drop the label instead if more than half of its characters would end up upside down.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="12"/>
      <MarkersSymbolizer file="shape://arrow" placement="vertex-last" fill="steelblue" width="16" height="12" allow-overlap="true" ignore-placement="true"/>
      <TextSymbolizer face-name="DejaVu Sans Book" size="12" placement="line" upright="[upright]" allow-overlap="true">[upright]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,upright
"LINESTRING(0 0,10 0)",auto
"LINESTRING(22 0,12 0)",auto
"LINESTRING(0 -2,10 -2)",auto-down
"LINESTRING(22 -2,12 -2)",auto-down
"LINESTRING(0 -4,10 -4)",left
"LINESTRING(22 -4,12 -4)",left
"LINESTRING(0 -6,10 -6)",right
"LINESTRING(22 -6,12 -6)",right
"LINESTRING(0 -8,10 -8)",left-only
"LINESTRING(22 -8,12 -8)",left-only
"LINESTRING(0 -10,10 -10)",right-only
"LINESTRING(22 -10,12 -10)",right-only
      </Parameter>
    </Datasource>
  </Layer>

</Map>
upright
Example 70. TextSymbolizer upright on steep lines

auto and auto-down only look at the angle of the line on the map, not at the direction it was drawn in: auto runs the text towards the right, auto-down towards the left. On near-vertical lines this decides whether text reads from bottom to top or from top to bottom. With auto, lines leaning to the right, like /, get text reading bottom to top, and lines leaning to the left, like \, get text reading top to bottom; auto-down does the opposite. Either way the reading direction flips when a line crosses the vertical, so labels on almost vertical lines that wobble slightly may change direction from one line to the next.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="12"/>
      <MarkersSymbolizer file="shape://arrow" placement="vertex-last" fill="steelblue" width="16" height="12" allow-overlap="true" ignore-placement="true"/>
      <TextSymbolizer face-name="DejaVu Sans Book" size="12" placement="line" upright="[upright]" allow-overlap="true">[upright]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,upright
"LINESTRING(0 0,1 10)",auto
"LINESTRING(5 10,4 0)",auto
"LINESTRING(9 0,8 10)",auto
"LINESTRING(12 10,13 0)",auto
"LINESTRING(20 0,21 10)",auto-down
"LINESTRING(25 10,24 0)",auto-down
"LINESTRING(29 0,28 10)",auto-down
"LINESTRING(32 10,33 0)",auto-down
      </Parameter>
    </Datasource>
  </Layer>

</Map>
upright steep
Example 71. TextSymbolizer text halo fill
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="DejaVu Sans Bold" size="24" fill="black" halo-fill="[fill]" halo-radius="1">[fill]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,fill
"POINT(0 0)",gray
"POINT(1 0)",red
"POINT(2 0)",green
"POINT(3 0)",blue
      </Parameter>
    </Datasource>
  </Layer>

</Map>
halo fill
Example 72. TextSymbolizer text halo radius
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="DejaVu Sans Bold" size="24" fill="black" halo-fill="red" halo-radius="[radius]">[radius]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,radius
"POINT(0 0)",1
"POINT(1 0)",2
"POINT(2 0)",3
"POINT(3 0)",4
      </Parameter>
    </Datasource>
  </Layer>

</Map>
halo radius
Example 73. TextSymbolizer text halo opacity
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">

  <Style name="style">
    <Rule>
      <TextSymbolizer face-name="DejaVu Sans Bold" size="24" fill="black" halo-fill="red" halo-radius="2" halo-opacity="[opacity]">[opacity]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,opacity
"POINT(0 0)",1.0
"POINT(1 0)",0.75
"POINT(2 0)",0.5
"POINT(3 0)",0.25
      </Parameter>
    </Datasource>
  </Layer>

</Map>
halo opacity