4.3. Polygons¶

4.3.1. Stroke and Fill¶

The polygon symbolizer controls the display of polygon data.

The fill-color property is used to provide the color used to draw the interior of a polygon.

1. Replace the contents of polygon_example with the following fill example:

   symbolizers:
   - polygon:
       fill-color: 'gray'
   

2. The Layer Preview tab can be used preview the change:

   

3. To draw the boundary of the polygon the stroke property is used:

   The stroke property is used to provide the color and size of the polygon boundary. It is effected by the same parameters (and vendor specific parameters) as used for LineStrings.

   symbolizers:
   - polygon:
       fill-color: 'gray'
       stroke-color: 'black'
       stroke-width: 2
   

   Note

   Technically the boundary of a polygon is a specific case of a LineString where the first and last vertex are the same, forming a closed LinearRing.

4. The effect of adding stroke is shown in the map preview:

   

5. An interesting technique when styling polygons in conjunction with background information is to control the fill opacity.

   The fill-opacity property is used to adjust transparency (provided as range from 0.0 to 1.0). Use of fill-opacity to render polygons works well in conjunction with a raster base map. This approach allows details of the base map to shown through.

   The stroke-opacity property is used in a similar fashion, as a range from 0.0 to 1.0.

   symbolizers:
   - polygon:
       fill-color: 'white'
       fill-opacity: 0.5
       stroke-color: 'lightgrey'
       stroke-width: 0.25
       stroke-opacity: 0.5
   

6. As shown in the map preview:

   

7. This effect can be better appreciated using a layer group.

   

   Where the transparent polygons is used lighten the landscape provided by the base map.

   

4.3.2. Pattern¶

The fill-graphic property can be used to provide a pattern.

The fill pattern is defined by repeating one of the built-in symbols, or making use of an external image.

1. We have two options for configuring a fill-graphic with a repeating graphic:

   Using external to reference to an external graphic.

   Use of mark to access a predefined shape. SLD provides several well-known shapes (circle, square, triangle, arrow, cross, star, and x). GeoServer provides additional shapes specifically for use as fill patterns.

   Update polygon_example with the following built-in symbol as a repeating fill pattern:

   symbolizers:
   - polygon:
       fill-graphic:
         symbols:
         - mark:
             shape: square
             fill-color: 'gray'
             stroke-color: 'black'
             stroke-width: 1
   

2. The map preview (and legend) will show the result:

   

3. Add a black stroke:

   symbolizers:
   - polygon:
       stroke-color: 'black'
       stroke-width: 1
       fill-graphic:
         symbols:
         - mark:
             shape: square
             fill-color: 'gray'
             stroke-color: 'black'
             stroke-width: 1
   

4. To outline the individual shapes:

   

5. Additional fill properties allow control over the orientation and size of the symbol.

   The size property is used to adjust the size of the symbol prior to use.

   The rotation property is used to adjust the orientation of the symbol.

   Adjust the size and rotation as shown:

   symbolizers:
   - polygon:
       stroke-color: 'black'
       stroke-width: 1
       fill-graphic:
         size: 22
         rotation: 45.0
         symbols:
         - mark:
             shape: square
             fill-color: 'gray'
             stroke-color: 'black'
             stroke-width: 1
   

6. The size of each symbol is increased, and each symbol rotated by 45 degrees.

   

   Note

   Does the above look correct? There is an open request GEOT-4642 to rotate the entire pattern, rather than each individual symbol.

7. The size and rotation properties just affect the size and placement of the symbol, but do not alter the symbol’s design. In order to control the color we set the fill-color and stroke-color properties of the mark.

8. Replace the contents of polygon_example with the following:

   symbolizers:
   - polygon:
       fill-graphic:
         symbols:
         - mark:
             shape: square
             fill-color: '#008000'
             stroke-color: '#006400'
             stroke-width: 1
   

9. This change adjusts the appearance of our grid of squares.

   

10. The well-known symbols are more suited for marking individual points. Now that we understand how a pattern can be controlled it is time to look at the patterns GeoServer provides.

    shape://horizline	horizontal hatching
    shape://vertline	vertical hatching
    shape://backslash	right hatching pattern
    shape://slash	left hatching pattern
    shape://plus	vertical and horizontal hatching pattern
    shape://times	cross hatch pattern

    Update the example to use shape://slash for a pattern of left hatching.

    symbolizers:
    - polygon:
        stroke-color: 'black'
        stroke-width: 1
        fill-graphic:
          symbols:
          - mark:
              shape: 'shape://slash'
              stroke-color: 'gray'
    

11. This approach is well suited to printed output or low color devices.

    

12. To control the size of the symbol produced use the size property of the fill-graphic.

    symbolizers:
    - polygon:
        stroke-color: 'black'
        stroke-width: 1
        fill-graphic:
          size: 8
          symbols:
          - mark:
              shape: 'shape://slash'
              stroke-color: 'gray'
    

13. This results in a tighter pattern shown:

    

14. Multiple fills can be applied by using a separate symbolizer for each fill as part of the same rule.

    symbolizers:
    - polygon:
        stroke-color: 'black'
        stroke-width: 1
        fill-color: '#DDDDFF'
    - polygon:
        fill-graphic:
          size: 8
          symbols:
          - mark:
              shape: shape://slash
              stroke-color: 'black'
              stroke-width: 0.5
    

15. The resulting image has a solid fill, with a pattern drawn overtop.

    

4.3.3. Label¶

Labeling polygons follows the same approach used for LineStrings.

The key properties fill and label are used to enable Polygon label generation.

1. By default labels are drawn starting at the centroid of each polygon.

   

2. Try out label and fill together by replacing our polygon_example with the following:

   symbolizers:
   - polygon:
       stroke-color: 'blue'
       stroke-width: 1
       fill-color: '#7EB5D3'
   - text:
       label: ${name}
       fill-color: 'black'
   

3. Each label is drawn from the lower-left corner as shown in the Layer Preview preview.

   

4. We can adjust how the label is drawn at the polygon centroid.

   

   The property anchor provides two numbers expressing how a label is aligned with respect to the centroid. The first value controls the horizontal alignment, while the second value controls the vertical alignment. Alignment is expressed between 0.0 and 1.0 as shown in the following table.

   	Left	Center	Right
   Top	0.0 1.0	0.5 1.0	1.0 1.0
   Middle	0.0 0.5	0.5 0.5	1.0 0.5
   Bottom	0.0 0.0	0.5 0.0	1.0 0.0

   Adjusting the anchor is the recommended approach to positioning your labels.

5. Using the anchor property we can center our labels with respect to geometry centroid.

   To align the center of our label we select 50% horizontally and 50% vertically, by filling in 0.5 and 0.5 below:

   symbolizers:
   - polygon:
       stroke-color: 'blue'
       stroke-width: 1
       fill-color: '#7EB5D3'
   - text:
       label: ${name}
       fill-color: 'black'
       anchor: [0.5, 0.5]
   

6. The labeling position remains at the polygon centroid. We adjust alignment by controlling which part of the label we are “snapping” into position.

   

7. The property displacement can be used to provide an initial displacement using and x and y offset.

   

8. This offset is used to adjust the label position relative to the geometry centroid resulting in the starting label position.

   symbolizers:
   - polygon:
       stroke-color: 'blue'
       stroke-width: 1
       fill-color: '#7EB5D3'
   - text:
       label: ${name}
       fill-color: 'black'
       displacement: [0, 7]
   

9. Confirm this result in the map preview.

   

10. These two settings can be used together.

    

    The rendering engine starts by determining the label position generated from the geometry centroid and the label-offset displacement. The bounding box of the label is used with the label-anchor setting align the label to this location.

    Step 1: starting label position = centroid + displacement

    Step 2: snap the label anchor to the starting label position

11. To move our labels down (allowing readers to focus on each shape) we can use displacement combined with followed by horizontal alignment.

    symbolizers:
    - polygon:
        stroke-color: 'blue'
        stroke-width: 1
        fill-color: '#7EB5D3'
    - text:
        label: ${name}
        fill-color: 'black'
        anchor: [0.5, 1]
        displacement: [0, -7]
    

12. As shown in the map preview.

    

4.3.4. Legibility¶

When working with labels a map can become busy very quickly, and difficult to read.

1. GeoServer provides extensive vendor parameters directly controlling the labelling process.

   Many of these parameters focus on controlling conflict resolution (when labels would otherwise overlap).

2. Two common properties for controlling labeling are:

   x-maxDisplacement indicates the maximum distance GeoServer should displace a label during conflict resolution.

   x-autoWrap allows any labels extending past the provided width will be wrapped into multiple lines.

3. Using these together we can make a small improvement in our example:

   symbolizers:
   - polygon:
       stroke-color: 'blue'
       stroke-width: 1
       fill-color: '#7EB5D3'
   - text:
       label: ${name}
       fill-color: 'black'
       anchor: [0.5, 0.5]
       x-maxDisplacement: 40
       x-autoWrap: 70
   

4. As shown in the following preview.

   

5. Even with this improved spacing between labels, it is difficult to read the result against the complicated line work.

   Use of a halo to outline labels allows the text to stand out from an otherwise busy background. In this case we will make use of the fill color, to provide some space around our labels. We will also change the font to Arial.

   symbolizers:
   - polygon:
       stroke-color: 'blue'
       stroke-width: 1
       fill-color: '#7EB5D3'
   - text:
       label: ${name}
       fill-color: 'black'
       anchor: [0.5, 0.5]
       font-family: Arial
       font-size: 14
       font-style: normal
       font-weight: normal
       halo:
         fill-color: '#7EB5D3'
         fill-opacity: 0.8
         radius: 2
       x-maxDisplacement: 40
       x-autoWrap: 70
   

6. By making use of fill-opacity on the halo we still allow stroke information to show through, but prevent the stroke information from making the text hard to read.

   

7. And advanced technique for manually taking control of conflict resolution is the use of the priority.

   This property takes an expression which is used in the event of a conflict. The label with the highest priority “wins.”

8. The Natural Earth dataset we are using includes a labelrank intended to control what labels are displayed based on zoom level.

   The values for labelrank go from 0 (for zoomed out) to 20 (for zoomed in). To use this value for priority we need to swap the values around so a scalerank of 1 is given the highest priority.

   symbolizers:
   - polygon:
       stroke-color: 'blue'
       stroke-width: 1
       fill-color: '#7EB5D3'
   - text:
       label: ${name}
       fill-color: 'black'
       anchor: [0.5, 0.5]
       font-family: Arial
       font-size: 14
       font-style: normal
       font-weight: normal
       halo:
         fill-color: '#7EB5D3'
         fill-opacity: 0.8
         radius: 2
       x-maxDisplacement: 40
       x-autoWrap: 70
       priority: ${'20' - labelrank}
   

9. In the following map East Flanders will take priority over Zeeland when the two labels overlap.

   

4.3.5. Theme¶

A thematic map (rather than focusing on representing the shape of the world) uses elements of style to illustrate differences in the data under study. This section is a little more advanced and we will take the time to look at the generated SLD file.

1. We can use a site like ColorBrewer to explore the use of color theming for polygon symbology. In this approach the fill color of the polygon is determined by the value of the attribute under study.

   

   This presentation of a dataset is known as “theming” by an attribute.

2. For our ne:states_provinces_shp dataset, a mapcolor9 attribute has been provided for this purpose. Theming by mapcolor9 results in a map where neighbouring countries are visually distinct.

   Qualitative 9-class Set3
   #8dd3c7	#fb8072	#b3de69
   #ffffb3	#80b1d3	#fccde5
   #bebada	#fdb462	#d9d9d9

   If you are unfamiliar with theming you may wish to visit http://colorbrewer2.org to learn more. The i icons provide an adequate background on theming approaches for qualitative, sequential and diverging datasets.

3. The first approach we will take is to directly select content based on colormap, providing a color based on the 9-class Set3 palette above:

   define: &stroke
     stroke-color: 'gray'
     stroke-width: 0.5
   rules:
     - filter: ${mapcolor9 = '1'}
       scale: [min, max]
       symbolizers:
       - polygon:
           <<: *stroke
           fill-color: '#8DD3C7'
     - filter: ${mapcolor9 = '2'}
       scale: [min, max]
       symbolizers:
       - polygon:
           <<: *stroke
           fill-color: '#FFFFB3'
     - filter: ${mapcolor9 = '3'}
       scale: [min, max]
       symbolizers:
       - polygon:
           <<: *stroke
           fill-color: '#BEBADA'
     - filter: ${mapcolor9 = '4'}
       scale: [min, max]
       symbolizers:
       - polygon:
           <<: *stroke
           fill-color: '#FB8072'
     - filter: ${mapcolor9 = '5'}
       scale: [min, max]
       symbolizers:
       - polygon:
           <<: *stroke
           fill-color: '#80B1D3'
     - filter: ${mapcolor9 = '6'}
       scale: [min, max]
       symbolizers:
       - polygon:
           <<: *stroke
           fill-color: '#FDB462'
     - filter: ${mapcolor9 = '7'}
       scale: [min, max]
       symbolizers:
       - polygon:
           <<: *stroke
           fill-color: '#B3DE69'
     - filter: ${mapcolor9 = '8'}
       scale: [min, max]
       symbolizers:
       - polygon:
           <<: *stroke
           fill-color: '#FCCDE5'
     - filter: ${mapcolor9 = '9'}
       scale: [min, max]
       symbolizers:
       - polygon:
           <<: *stroke
           fill-color: '#D9D9D9'
     - filter: ${mapcolor9 <> '1' AND mapcolor9 <> '2' AND mapcolor9 <> '3' AND mapcolor9 <> '4' AND mapcolor9 <> '5' AND mapcolor9 <> '6' AND mapcolor9 <> '7' AND mapcolor9 <> '8' AND mapcolor9 <> '9'}
       scale: [min, max]
       symbolizers:
       - line:
           <<: *stroke
   

4. The Layer Preview tab can be used to preview this result.

   

5. This YSLD makes use of a define to avoid repeating the stroke-color and stroke-width information multiple times.

   As an example the ${mapcolor9 = '2'} rule, combined with the define: results in the following collection of properties:

   - filter: ${mapcolor9 = '2'}
       scale: [min, max]
       symbolizers:
       - polygon:
           stroke-color: 'gray'
           stroke-width: 0.5
           fill-color: '#FFFFB3'
   

6. Reviewing the generated SLD shows us this representation:

   <sld:Rule>
      <ogc:Filter>
         <ogc:PropertyIsEqualTo>
            <ogc:PropertyName>mapcolor9</ogc:PropertyName>
            <ogc:Literal>2</ogc:Literal>
         </ogc:PropertyIsEqualTo>
      </ogc:Filter>
      <sld:PolygonSymbolizer>
         <sld:Fill>
            <sld:CssParameter name="fill">#ffffb3</sld:CssParameter>
         </sld:Fill>
      </sld:PolygonSymbolizer>
      <sld:LineSymbolizer>
         <sld:Stroke>
            <sld:CssParameter name="stroke">#808080</sld:CssParameter>
            <sld:CssParameter name="stroke-width">0.5</sld:CssParameter>
         </sld:Stroke>
      </sld:LineSymbolizer>
   </sld:Rule>
   

7. There are three important functions, defined by the Symbology Encoding specification, that are often easier to use for theming than using rules.

   • Recode: Used the theme qualitative data. Attribute values are directly mapped to styling property such as fill or stroke-width.

   • Categorize: Used the theme quantitative data. Categories are defined using min and max ranges, and values are sorted into the appropriate category.

   • Interpolate: Used to smoothly theme quantitative data by calculating a styling property based on an attribute value.

   Theming is an activity, producing a visual result allow map readers to learn more about how an attribute is distributed spatially. We are free to produce this visual in the most efficient way possible.

8. Swap out mapcolor9 theme to use the Recode function:

   symbolizers:
   - polygon:
       stroke-color: 'gray'
       stroke-width: 0.5
       fill-color: ${Recode(mapcolor9,
         '1','#8dd3c7',
         '2','#ffffb3',
         '3','#bebada',
         '4','#fb8072',
         '5','#80b1d3',
         '6','#fdb462',
         '7','#b3de69',
         '8','#fccde5',
         '9','#d9d9d9')}
   

9. The Layer Preview tab provides the same preview.

   

10. The Generated SLD tab shows where things get interesting. Our generated style now consists of a single Rule:

    <sld:Rule>
       <sld:PolygonSymbolizer>
          <sld:Fill>
             <sld:CssParameter name="fill">
                <ogc:Function name="Recode">
                   <ogc:PropertyName>mapcolor9</ogc:PropertyName>
                   <ogc:Literal>1</ogc:Literal>
                      <ogc:Literal>#8dd3c7</ogc:Literal>
                   <ogc:Literal>2</ogc:Literal>
                      <ogc:Literal>#ffffb3</ogc:Literal>
                   <ogc:Literal>3</ogc:Literal>
                      <ogc:Literal>#bebada</ogc:Literal>
                   <ogc:Literal>4</ogc:Literal>
                      <ogc:Literal>#fb8072</ogc:Literal>
                   <ogc:Literal>5</ogc:Literal>
                      <ogc:Literal>#80b1d3</ogc:Literal>
                   <ogc:Literal>6</ogc:Literal>
                      <ogc:Literal>#fdb462</ogc:Literal>
                   <ogc:Literal>7</ogc:Literal>
                      <ogc:Literal>#b3de69</ogc:Literal>
                   <ogc:Literal>8</ogc:Literal>
                      <ogc:Literal>#fccde5</ogc:Literal>
                   <ogc:Literal>9</ogc:Literal>
                      <ogc:Literal>#d9d9d9</ogc:Literal>
             </ogc:Function>
             </sld:CssParameter>
          </sld:Fill>
       </sld:PolygonSymbolizer>
       <sld:LineSymbolizer>
          <sld:Stroke>
             <sld:CssParameter name="stroke">#808080</sld:CssParameter>
             <sld:CssParameter name="stroke-width">0.5</sld:CssParameter>
          </sld:Stroke>
       </sld:LineSymbolizer>
    </sld:Rule>
    

4.3.6. Bonus¶

The following optional explore and challenge activities offer a chance to review and apply the ideas introduced here. The challenge activities require a bit of creativity and research to complete.

In a classroom setting you are encouraged to team up into groups, with each group taking on a different challenge.