Mapnik - The Missing Manual

3.10.9. ShieldSymbolizer

A shield symbolizer is basically a combination of a point and a text symbolizer, making sure that both image and text are always shown at the same position, and that collision rules apply to both together instead of individually. The name stems from the original use case to show highway shields.

ShieldSymbolizer inherits almost all attributes from the TextSymbolizer, with a small number of additions and modifications.

Table 31. ShieldSymbolizer specific Attributes
Attribute	Type	Default	Description
`file`	file path	none	Shield image to use
`base`	string	none	name of a <FileSource> to find the input file in
`opacity`	float	1.0	Opacity to use for the shield image
`text-opacity`	float	1.0	Opacity to use for the shield text
`unlock-image`	boolean	false	`dx`,`dy` move image and text when `true`, text only when `false`
`dx`	float	0.0	Move text, and image if `unlock-image=false`, horizontallly
`dy`	float	0.0	Move text, and image if `unlock-image=false`, vertically
`shield-dx`	float	0.0	Move image horizontally only
`shield-dy`	float	0.0	Move image vertically only
`transform`	SVG transformation	none	Transform image

/* name file face-name unlock-image size fill placement avoid-edges allow-overlap margin repeat-distance min-distance spacing min-padding label-position-tolerance wrap-width wrap-before wrap-character halo-fill halo-radius halo-rasterizer halo-transform halo-comp-op halo-opacity character-spacing line-spacing text-dx text-dy dx dy opacity horizontal-alignment vertical-alignment placement-type text-transform justify-alignment transform clip simplify simplify-algorithm smooth comp-op grid-cell-width grid-cell-height offset */

Example 60. ShieldSymolizer spacing

spacing controls the distance between shields on a single line feature. When no spacing is given only a single shield will be attemted to be placed.

See also repeat-distance, which controls how far shields with the same text should be set apart in general, even when placed on different geometries.

<?xml version="1.0" encoding="utf-8"?>
<Map background-color='white'>
  <FileSource name="symbols">./symbols/</FileSource>

  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="blue" stroke-width="5"/>
      <ShieldSymbolizer spacing="[spacing]" base="symbols" file="motorway_2x1.svg" face-name="DejaVu Sans Book" placement="line">[spacing]</ShieldSymbolizer>
    </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 61. ShieldSymolizer placement

placement Controls where the shield is actually placed:

point: Places the shield 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 shield is placed inside a polygon even if its center point is actually on its outside
line: When spacing is larger than zero the shield is repeatedly drawn along a line or a polygons outline with spacing pixels between shields
vertex: Tries to place the shield 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 shield is repeatedly drawn into a polygons surface, using grid cells of the given width and height. Note that the shield is not clipped at the border of the polygon, so some shield parts may be drawn 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">
  <FileSource name="symbols">./symbols</FileSource>

  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="blue" stroke-width="5"/>
      <ShieldSymbolizer base="symbols" file="motorway_2x1.svg" face-name="DejaVu Sans Book" placement="[placement]" grid-cell-width="30" grid-cell-height="20" spacing="30">A1</ShieldSymbolizer>
      <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 62. ShieldSymbolizer grid width/height

<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">
  <FileSource name="symbols">./symbols</FileSource>

  <Style name="style">
    <Rule>
      <LineSymbolizer stroke="lightblue" stroke-width="5"/>
      <ShieldSymbolizer base="symbols" file="motorway_2x1.svg" face-name="DejaVu Sans Book" placement="[placement]" grid-cell-width="[width]" grid-cell-height="[height]" spacing="30">A1</ShieldSymbolizer>
      <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>