Mapnik - The Missing Manual

3.10.8. TextSymbolizer

Table 30. TextSymbolizer specific Attributes
Attribute	Type	Default	Description
Text attributes
`face-name`	string	none	Face name to use
`fontset-name`	string	none	FontSet name
`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
Wrap attributes
`line-spacing`	float	0.0	Extra vertical space for multi line output in pixels
`font-feature-settings`	string	none	Comma separated list of OpenType typographic features
`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
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
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
`force-odd-labels`	boolean	false	Force an odd number of labels to be generated
`displacement`	2xfloat	(0.0,0.0)	Displace label by this many pixel horizontally/vertically
`minimum-distance`	float	?	?TODO?
`largest-bbox-only`	bool	?	?TODO?
`upright`	string	?	?TODO? one of auto, auto-down, left, left-only, right, right-only, up, down

Example 47. 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>

Example 48. 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>

Example 49. 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>

Example 50. 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>

Example 51. 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>

Example 52. 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>

Example 53. 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>

Example 54. 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>

Example 55. 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>

Example 56. 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>

Example 57. 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>

Example 58. 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>