3.10.1. PointSymbolizer

The point symbolizer draws a given image at a point position. When given a line or polygon as input the shape will be put at the middle of the line or center of the polygon.

If no image file is specified a small square is used as the default point image.

For putting symbols along a line or the edge of a polygon the MarkerSymbolizer is usually a better choice.

Table 24. PointSymbolizer Attributes
Attribute Type Default Description

file

file path

none

base

string

none

name of a <FileSource> to find the input file in

allow-overlap

bool

false

allow to paint over previous symbolizers output

opacity

float

1.0

placement

string

centroid

Wehter to place on a polygons centroid, which can actually be outside, or its interior

ignore-placement

bool

false

do not reserve the symbol’s space, so that later symbols and labels may be placed over it

transform

string

See Transformation

comp-op

string

src-over

See Compositing

file attribute

file refers to a SVG or PNG file to include as a symbol at the point position. The file can be given as a constant string, or as an expression, so files to display can be dynamically chosen from layer data.

By default file paths are either absolute or relative to the directory the main style file is in, but different directory paths can be set up using the <FileSource> tag and referenced by its name using the base attribute.

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

  <Style name="style">
    <Rule>
      <PointSymbolizer allow-overlap="true" base="symbols" file="[file]"/>
      <TextSymbolizer face-name="DejaVu Sans Book" allow-overlap="true" dy="20">[file]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,file
"POINT(1 0)","dot.svg"
"POINT(2 0)","bug.svg"
      </Parameter>
    </Datasource>
  </Layer>

</Map>
file
opacity attribute

The opacity attribute defines how opaque or transparent a point symbol should be rendered. The value range is from 0.0 for completely transparent to 1.0 for completely opaque.

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

  <Style name="style">
    <Rule>
      <PointSymbolizer base="symbols" file="dot.svg" opacity="[opacity]"/>
      <TextSymbolizer face-name="DejaVu Sans Book" allow-overlap="true" dy="20">[opacity]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
opacity,wkt
0.0,"POINT(  0 0)"
0.1,"POINT( 1 0)"
0.2,"POINT( 2 0)"
0.3,"POINT( 3 0)"
0.4,"POINT( 4 0)"
0.5,"POINT( 5 0)"
0.6,"POINT( 6 0)"
0.7,"POINT( 7 0)"
0.8,"POINT( 8 0)"
0.9,"POINT( 9 0)"
1.0,"POINT(10 0)"
      </Parameter>
    </Datasource>
  </Layer>

</Map>
opacity
base attribute

The base attribute defines which <FileSource> should be used as the base directory for a file symbol.

Note
The base attribute only accepts constant strings, no expressions. So it can only be chosen dynamically by using <Rule>/<Filter> constructs.
Example 17. PointSymbolizer base
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">
  <FileSource name="default">./symbols</FileSource>
  <FileSource name="red">./symbols/red</FileSource>
  <FileSource name="green">./symbols/green</FileSource>
  <FileSource name="blue">./symbols/blue</FileSource>

  <Style name="style">
    <Rule>
      <Filter>[base] = "red"</Filter>
      <PointSymbolizer allow-overlap="true" file="bug.svg" base="red"/>
    </Rule>
    <Rule>
      <Filter>[base] = "blue"</Filter>
      <PointSymbolizer allow-overlap="true" file="bug.svg" base="blue"/>
    </Rule>
    <Rule>
      <Filter>[base] = "green"</Filter>
      <PointSymbolizer allow-overlap="true" file="bug.svg" base="green"/>
    </Rule>
    <Rule>
      <AlsoFilter />
      <TextSymbolizer face-name="DejaVu Sans Book" allow-overlap="true" dy="20">[base]</TextSymbolizer>
    </Rule>
    <Rule>
      <ElseFilter />
      <PointSymbolizer allow-overlap="true" file="bug.svg" base="default"/>
      <TextSymbolizer face-name="DejaVu Sans Book" allow-overlap="true" dy="20" fill="red">"FileSource for base '"+[base]+"' not found"</TextSymbolizer>
    </Rule>
  </Style>

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

</Map>
base
allow-overlap attribute

The allow-overlap defines whether a point symbolizer may be drawn over previous output.

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

  <Style name="style">
    <Rule>
      <PolygonSymbolizer/>
      <TextSymbolizer face-name="DejaVu Sans Book">[caption]</TextSymbolizer>
      <PointSymbolizer allow-overlap="[allow-overlap]" base="symbols" opacity="0.3" file="bug.svg"/>
      <TextSymbolizer face-name="DejaVu Sans Book" allow-overlap="true" dy="20">[allow-overlap]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,allow-overlap,caption
"POINT(0 0)",true,overlap
"POINT(1 0)",false,overlap
"POINT(3 0.2)",true,
"POINT(3.1 0)",true,
"POINT(4 0.2)",true,
"POINT(4.1 0)",false,
      </Parameter>
    </Datasource>
  </Layer>

</Map>
allow overlap
ignore-placement attribute

Each symbol that has been drawn normally reserves its space, so that symbols and labels placed later that would collide with it are skipped, unless they have allow-overlap set. With ignore-placement set, the symbol is still drawn, but its space is not reserved, so it does not block anything placed later.

allow-overlap and ignore-placement are complementary: allow-overlap controls whether a symbol is drawn even if its space is already taken, while ignore-placement controls whether a symbol takes up space for later ones. To have a symbol that neither is blocked by nor blocks anything else, set both.

In the example the first symbol of each pair is drawn first, and the second symbol, which does not have allow-overlap set, is only drawn when the first one has ignore-placement set. The captions are drawn by a separate style after all symbols, so that they do not block any of the symbols.

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

  <Style name="style">
    <Rule>
      <PointSymbolizer ignore-placement="[ignore-placement]" base="symbols" opacity="0.5" file="bug.svg"/>
    </Rule>
  </Style>

  <Style name="captions">
    <Rule>
      <TextSymbolizer face-name="DejaVu Sans Book" allow-overlap="true" dy="30">[caption]</TextSymbolizer>
    </Rule>
  </Style>

  <Layer name="layer">
    <StyleName>style</StyleName>
    <StyleName>captions</StyleName>
    <Datasource>
      <Parameter name="type">csv</Parameter>
      <Parameter name="inline">
wkt,ignore-placement,caption
"POINT(0 0.1)",true,true
"POINT(0.1 0)",false,
"POINT(1 0.1)",false,false
"POINT(1.1 0)",false,
      </Parameter>
    </Datasource>
  </Layer>

</Map>
ignore placement
placement attribute

The placement attribute specifies where the point symbol should be placed on a polygon object. By default it is placed on the centroid of the polygons, but for a non-convex polygon this can actually place the symbol outside of the polygon itself. interior makes sure that the symbol is placed within the polygon in all cases.

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

  <Style name="style">
    <Rule>
      <PolygonSymbolizer/>
      <PointSymbolizer allow-overlap="true" placement="[placement]" base="symbols" file="bug.svg"/>
      <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,15 5,15 2,12 2,12 5,11 5,11 1))",centroid
      </Parameter>
    </Datasource>
  </Layer>

</Map>
placement
transform attribute

TODO: move transformation examples to Transformation section

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

  <Style name="style">
    <Rule>
      <PointSymbolizer base="symbols" file="bug.svg" transform="scale([scale])"/>
      <TextSymbolizer face-name="DejaVu Sans Book" allow-overlap="true" dy="40">[scale]+"x"</TextSymbolizer>
    </Rule>
  </Style>

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

</Map>
transform scale
Example 22. PointSymbolizer rotation
<?xml version="1.0" encoding="utf-8"?>
<Map background-color="white">
  <FileSource name="symbols">./symbols</FileSource>

  <Style name="style">
    <Rule>
      <PointSymbolizer base="symbols" file="bug.svg" transform="rotate([rotate])"/>
      <TextSymbolizer face-name="DejaVu Sans Book" allow-overlap="true" dy="20">[rotate]+"°"</TextSymbolizer>
    </Rule>
  </Style>

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

</Map>
transform rotate