Skip to content


Subversion checkout URL

You can clone with
Download ZIP


lucadelu edited this page · 21 revisions
Clone this wiki locally

Configuration Options for ShieldSymbolizer

NEW: Starting from r1793 ShieldSymbolizer supports Scalable Vector Graphics (SVG) as input images, see examples below.

parameter value default
allow_overlap Allow the symbolizer to overlap others false
avoid_edges Attempts to stay away from the edge of the image false
base Base symbol template. See #574 (XML config only)
character_spacing Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement 0
dx Offset the text horizontally. Unit: pixels from the image's center
dy Offset the text vertically. Unit: pixels from the image's center. Also see note at vertical_alignment.
face_name Font name for the shield text
file The file to use for the shield background
fill Color of the shield text, e.g. #FFFFFF
fontset_name Name of the FontSet to use. (XML config only)
halo_fill Color of the colored halo around the text, e.g. #AF2304. white
halo_radius Thickness of the colored halo around the text as an integer value in pixels 0
height The height of the shield file image's height
horizontal_alignment middle
justify_alignment midle
line_spacing Vertical spacing between lines of multi-line labels, in pixels 0
min_distance Minimum distance to the next shield symbol, not necessarily the same shield 0
name This is the query field you want to use for the label text, e.g. "ref"
no_text false
opacity opacity of the image used for the shield 1
text-opacity opacity of the text placed on top of the shield 1
placement "line" or "point"
size Font size of the shield text (a value of zero will prevent text from being written)
spacing The spacing between repeated occurrences of the same shield
text_convert Allows conversion of text to lower or upper case before display. Values are "none", "toupper", and "tolower". "none"
type Type of the shield file, e.g. "png"
unlock_image If "false", the symbol is placed relative to the text box center. If "true", the symbol is placed relative to the point position "false"
vertical_alignment Position of label relative to point position ("top" to label on top of a point, "middle", "bottom") for dy = 0, "bottom" for dy > 0, "top" for dy < 0 "middle"
width The width of the shield file image's width
wrap_before "false"
wrap_character Use this character instead of a space to wrap long names " "
wrap_width Length before wrapping long names 0
transform Development version (trunk) SVG transform
shield_dx offset the shield image horizontally
shield_dy offset the shield image vertically

Good to know

ShieldSymbolizer can be used to label points.BR E.G. If you want to place points on cities and their name above it. If you try to use a TextSymbolizer and a PointSymbolizer separated you will often see points without texts and/or texts without points.BR To draw labeled points configure your shield symbolizer with placement = point and custom value for dx/dy to move the text around the pointBR


BR Image(

Setting up a sample shield symbolizer, from the Cascade Users of OpenSource GeoSpatial (CUGOS) list:



<Style name="My Style">
        <ShieldSymbolizer name="NAME" face_name="DejaVu Sans Bold" size="6" fill="#000000" file="images/ushighway_shield_20.png" type="png" width="20" height="20" spacing="100" min_distance="50"></ShieldSymbolizer>


shield = ShieldSymbolizer('NAME','DejaVu Sans Bold',6,Color('#000000'),'images/ushighway_shield_20.png','png',20,20)
# parameters are: (name, font name, font size, font color, image file, image type, width, height)
shield.min_distance = 50
shield.label_spacing = 100


rule_type rule;
/* Parameters:
      face name
      image type
shield_symbolizer ss("NAME", "DejaVu Sans Bold", 6, color(0, 0, 0), "/path/to/icon.png", "png", 20, 20);
ss.set_label_placement(mapnik::LINE_PLACEMENT); // Place label along the line
ss.set_displacement(dx, dy);

SVG shields


<Style name="My Style">
        <ShieldSymbolizer name="'ABC'" fontset_name="bold-fonts" size="10" fill="green" placement="line" file="/Users/artem/Desktop/svg/shield.svg" transform="scale(2.0,2.0)" min_distance="100" spacing="250"/>

== Resources ==

Something went wrong with that request. Please try again.