4.2. Lines¶

4.2.1. Line¶

A line symbolizer is represented by a line key. You can make a completely default symbolizer by giving it an empty map

line:

1. Navigate to the Styles page.

2. Click Add a new style and choose the following:

   New style name:	line_example
   Workspace for new layer:	Leave blank
   Format:	YSLD

3. Choose line from the Generate a default style dropdown and click generate.

4. The style editor should look like below:

   title: dark yellow line
   symbolizers:
   - line:
       stroke-width: 1.0
       stroke-color: '#99cc00'
   

1. Click Apply

2. Click Layer Preview to see your new style applied to a layer.

   You can use this tab to follow along as the style is edited, it will refresh each time Apply is pressed.

   

3. You can see the equivalent SLD by requesting http://localhost:8080/geoserver/rest/styles/line_example.sld?pretty=true which will currently show the default line symbolizer we created.

    <?xml version="1.0" encoding="UTF-8"?><sld:StyledLayerDescriptor xmlns="http://www.opengis.net/sld" xmlns:sld="http://www.opengis.net/sld" xmlns:gml="http://www.opengis.net/gml" xmlns:ogc="http://www.opengis.net/ogc" version="1.0.0">
     <sld:NamedLayer>
      <sld:Name>line_example</sld:Name>
      <sld:UserStyle>
        <sld:Name>line_example</sld:Name>
        <sld:Title>dark yellow line</sld:Title>
        <sld:FeatureTypeStyle>
          <sld:Name>name</sld:Name>
          <sld:Rule>
            <sld:LineSymbolizer>
              <sld:Stroke>
                <sld:CssParameter name="stroke">#99CC00</sld:CssParameter>
              </sld:Stroke>
            </sld:LineSymbolizer>
          </sld:Rule>
        </sld:FeatureTypeStyle>
      </sld:UserStyle>
     </sld:NamedLayer>
   </sld:StyledLayerDescriptor>
   

We only specified the line symbolizer, so all of the boilerplate around was generated for us.

1. Additional properties can be used fine-tune appearance. Use stroke-color to specify the colour of the line.

   line:
     stroke-color: blue
   

2. stroke-width lets us make the line wider

   line:
     stroke-color: blue
     stroke-width: 2px
   

3. stroke-dasharray applies a dot dash pattern.

   line:
     stroke-color: blue
     stroke-width: 2px
     stroke-dasharray: 5 2
   

4. Check the Layer Preview tab to preview the result.

   

4.2.2. Multiple Symbolizers¶

Providing two strokes is often used to provide a contrasting edge (called casing) to thick lines. This can be created using two symbolizers.

1. Start by filling in a bit of boilerplate that we’ll be using

   feature-styles:
   - rules:
     - symbolizers:
       - line:
           stroke-color: '#8080E6'
           stroke-width: 3px
   

   The line symbolizer is inside a rule, which is inside a feature style.

2. Add a second symbolizer to the rule

   feature-styles:
   - rules:
     - symbolizers:
       - line:
           stroke-color: black
           stroke-width: 5px
       - line:
           stroke-color: '#8080E6'
           stroke-width: 3px
   

   The wider black line is first so it is drawn first, then the thinner blue line drawn second and so over top of the black line. This is called the painter’s algorithm.

3. If you look carefully you can see a problem with our initial attempt. The junctions of each line show that the casing outlines each line individually, making the lines appear randomly overlapped. Ideally we would like to control this process, only making use of this effect for overpasses.

   

   This is because the black and blue symbolizers are being drawn on a feature by feature basis. For nice line casing, we want all of the black symbols, and then all of the blue symbols.

4. Create a new feature style and move the second symbolizer there.

   feature-styles:
   - rules:
     - symbolizers:
       - line:
           stroke-color: black
           stroke-width: 5px
   - rules:
     - symbolizers:
       - line:
           stroke-color: '#8080E6'
           stroke-width: 3px
   

   Again we are using painter’s algorithm order: the first feature style is drawn first then the second so the second is drawn on top of the first. The difference is that for each feature style, all of the features are drawn before the next feature style is drawn.

5. If you look carefully you can see the difference.

   

6. By using feature styles we have been able to simulate line casing.

   

4.2.3. Label¶

Our next example is significant as it introduces how text labels are generated.

This is also our first example making use of a dynamic style (where a value comes from an attribute from your data).

1. To enable LineString labeling we add a text symbolizer witrh a label.

   Update line_example with the following:

    symbolizers:
    - line:
        stroke-color: blue
        stroke-width: 1px
    - text:
        label: ${name}
   

2. The SLD standard documents the default label position for each kind of Geometry. For LineStrings the initial label is positioned on the midway point of the line.

   

3. We have used an expression to calculate a property value for label. The label is generated dynamically from the name attribute. Expressions are supplied within curly braces preceded with a dollar sign, and use Extended Constraint Query Language (ECQL) syntax.

    symbolizers:
    - line:
        stroke-color: blue
        stroke-width: 1px
    - text:
        label: ${name}
   

4. Additional keys can be supplied to fine-tune label presentation:

    symbolizers:
    - line:
        stroke-color: blue
        stroke-width: 1px
    - text:
        label: ${name}
        fill-color: black
        placement: line
        offset: 7px
   

5. The fill-color property is set to black to provide the colour of the text.

    symbolizers:
    - line:
        stroke-color: blue
        stroke-width: 1px
    - text:
        label: ${name}
        fill-color: black
        placement: line
        offset: 7px
   

6. The placement property is used to set how the label is placed with respect to the line. By default it is point which causes the label to be placed next to the midpoint as it would be for a point feature. When set to line it is placed along the line instead. offset specifies how far from the line the label should be placed.

    symbolizers:
    - line:
        stroke-color: blue
        stroke-width: 1px
    - text:
        label: ${name}
        fill-color: black
        placement: line
        offset: 7px
   

   

7. When using point placement, you can shift the position of the label using displacement instead of offset. This takes an x value and a y value.

    symbolizers:
    - line:
        stroke-color: blue
        stroke-width: 1px
    - text:
        label: ${name}
        fill-color: black
        displacement: [5px, -10px]
   

4.2.4. How Labeling Works¶

The rendering engine collects all the generated labels during the rendering of each layer. Then, during labeling, the engine sorts through the labels performing collision avoidance (to prevent labels overlapping). Finally the rendering engine draws the labels on top of the map. Even with collision avoidance you can spot areas where labels are so closely spaced that the result is hard to read.

The parameters provided by SLD are general purpose and should be compatible with any rendering engine.

To take greater control over the GeoServer rendering engine we can use “vendor specific” parameters. These hints are used specifically for the GeoServer rendering engine and will be ignored by other systems. In YSLD vendor specific parameters start with the prefix x-.

1. The ability to take control of the labeling process is exactly the kind of hint a vendor specific parameter is intended for.

   Update line_example with the following:

    symbolizers:
    - line:
        stroke-color: blue
        stroke-width: 1px
    - text:
        label: ${name}
        fill-color: black
        placement: line
        offset: 7px
        x-label-padding: 10
   

2. The parameter x-label-padding provides additional space around our label for use in collision avoidance.

    symbolizers:
    - line:
        stroke-color: blue
        stroke-width: 1px
    - text:
        label: ${name}
        fill-color: black
        placement: line
        offset: 7px
        x-label-padding: 10
   

3. Each label is now separated from its neighbor, improving legibility.

   

4.2.5. Scale¶

This section explores the use of rules with filters and scale restrictions.

1. Replace the line_example YSLD definition with:

   rules:
   - filter: ${scalerank < 4}
     symbolizers:
     - line:
         stroke-color: black
         stroke-width: 1
   

2. And use the Layer Preview tab to preview the result.

   

3. The scalerank attribute is provided by the Natural Earth dataset to allow control of the level of detail based on scale. Our filter short-listed all content with scalerank 4 or lower, providing a nice quick preview when we are zoomed out.

4. In addition to testing feature attributes, selectors can also be used to check the state of the rendering engine.

   Replace your YSLD with the following:

   rules:
   - scale: [35000000, max]
     symbolizers:
     - line:
         stroke-color: black
         stroke-width: 1
   - scale: [min, 35000000]
     symbolizers:
     - line:
         stroke-color: blue
         stroke-width: 1
   

5. As you adjust the scale in the Layer Preview (using the mouse scroll wheel) the color will change between black and blue. You can read the current scale in the bottom right corner, and the legend will change to reflect the current style.

   

6. Putting these two ideas together allows control of level detail based on scale:

   define: &primaryStyle
     stroke-color: black
   define: &primaryFilter ${scalerank <= 4}
   
   define: &secondaryStyle
     stroke-color: '#000055'
   define: &secondaryFilter ${scalerank = 5}
   
   rules:
   
     - else: true
       scale: [min, 9000000]
       symbolizers:
       - line:
           stroke-color: '#888888'
           stroke-width: 1
   
     - filter: ${scalerank = 7}
       scale: [min, 17000000]
       symbolizers:
       - line:
           stroke-color: '#777777'
           stroke-width: 1
   
     - filter: ${scalerank = 6}
       scale: [min, 35000000]
       symbolizers:
       - line:
           stroke-color: '#444444'
           stroke-width: 1
   
     - filter: *secondaryFilter
       scale: [9000000, 70000000]
       symbolizers:
       - line:
           <<: *secondaryStyle
           stroke-width: 1
     - filter: *secondaryFilter
       scale: [min, 9000000]
       symbolizers:
       - line:
           <<: *secondaryStyle
           stroke-width: 2
   
     - filter: *primaryFilter
       scale: [35000000, max]
       symbolizers:
       - line:
           <<: *primaryStyle
           stroke-width: 1
     - filter: *primaryFilter
       scale: [9000000, 35000000]
       symbolizers:
       - line:
           <<: *primaryStyle
           stroke-width: 2
     - filter: *primaryFilter
       scale: [min, 9000000]
       symbolizers:
       - line:
           <<: *primaryStyle
           stroke-width: 4
   

7. When a rule has both a filter and a scale, it will trigger when both are true.

   The first rule has else: true instead of a filter. This causes it to be applied after all other rules have been checked if none of them worked.

   Since there are some things we need to specify more than once like the colour and filter for primary and secondary roads, even as they change size at different scales, they are given names with define so they can be reused. The filters are inserted inline using *name while the style is inserted as a block with <<: *name

   

4.2.6. Bonus¶

Finished early? Here are some opportunities to explore what we have learned, and extra challenges requiring creativity and research.

In a classroom setting please divide the challenges between teams (this allows us to work through all the material in the time available).