Feature Styles¶

Drawing order¶

The order of feature styles is significant, and also the order of rules inside feature styles is significant.

Rules inside a feature style are all applied to each feature at once. After all of the rules in a feature style have been applied to each feature, the next feature style will start again, applying rules to each feature.

The off-screen buffer for each feature style is merged together during composition. These buffers are merged in the order defined by the feature styles. In this way, using multiple feature styles is a way of specifying z-order.

Consider the same hierarchy as above. Given a layer that contains three features, the rules will be applied as follows:

Feature style 1 will draw an off-screen buffer:

1. Rule 1a is applied to the first feature, followed by rule 1b

2. Rule 1a is applied to the second feature, followed by rule 1b

3. Rule 1a is applied to the third feature, followed by rule 1b

Feature style 1 buffer¶

Feature style 2 will draw an off-screen buffer:

1. Rule 2a is applied to the first feature, followed by rule 2b and then rule 2c

2. Rule 2a is applied to the second feature, followed by rule 2b and then rule 2c

3. Rule 2a is applied to the third feature, followed by rule 2b and then rule 2c

Feature style 2 buffer¶

This final map is produced by composition:

1. The buffer for feature style 1 is drawn

2. The buffer for feature style 2 is drawn

3. Any labeling is drawn on top

Composition of both feature styles¶

If you need a rule to apply on top of other rules, use a second feature style. A useful case for this is for lines representing bridges or overpasses. In order to ensure that the bridge lines always display on “top” of other lines (which in a display that includes, they would need to be applied using a second feature style.)

Syntax¶

The following is the basic syntax of a feature style. Note that the contents of the block are not all expanded here.

feature-styles:
- name: <text>
  title: <text>
  abstract: <text>
  transform:
    ...
  rules:
  - ...
  x-ruleEvaluation: <text>
  x-composite: <text>
  x-composite-base: <boolean>
  x-inclusion: <text>

where:

The following properties are equivalent to SLD “vendor options”.

Compositing and blending¶

By default, multiple feature styles are drawn with one buffer on top of the other. However, using the x-composite and x-composite-base options, one can customize the way that buffers are displayed.

The following two tables show the possible alpha compositing and color blending values for the x-composite option. Note that in the tables below, source refers to the buffer that is drawn on top, while destination refers to the buffer that the source is drawn on top of.

Alpha compositing

Alpha compositing controls how buffers are merged using the transparent areas of each buffer.

Value	Description
copy	Only the source will be present in the output.
destination	Only the destination will be present in the output.
source-over	The source is drawn over the destination, and the destination is visible where the source is transparent. Opposite of destination-over. This is the default value for x-composite.
destination-over	The source is drawn below the destination, and is visible only when the destination is transparent. Opposite of source-over.
source-in	The source is visible only when overlapping some non-transparent pixel of the destination. This allows the background map to act as a mask for the layer/feature being drawn. Opposite of destination-in.
destination-in	The destination is retained only when overlapping some non transparent pixel in the source. This allows the layer/feature to be drawn to act as a mask for the background map. Opposite of source-in.
source-out	The source is retained only in areas where the destination is transparent. This acts as a reverse mask when compared to source-in.
destination-out	The destination is retained only in areas where the source is transparent. This acts as a reverse mask when compared to destination-in.
source-atop	The destination is drawn fully, while the source is drawn only where it intersects the destination.
destination-atop	The source is drawn fully, and the destination is drawn over the source only where it intersects it.
xor	“Exclusive Or” mode. Each pixel is rendered only if either the source or the destination is not blank, but not both.

Color blending

Color blending allows buffers to be mixed during composition.

Value	Description
multiply	The source color is multiplied by the destination color and replaces the destination. The resulting color is always at least as dark as either the source or destination color. Multiplying any color with black results in black. Multiplying any color with white preserves the original color.
screen	Multiplies the complements of the source and destination color values, then complements the result. The end result color is always at least as light as either of the two constituent colors. Screening any color with white produces white; screening with black leaves the original color unchanged.
overlay	Multiplies the colors depending on the destination color value. Source colors overlay the destination while preserving highlights and shadows. The backdrop color is not replaced but is mixed with the source color to reflect the lightness or darkness of the backdrop.
darken	Selects the darker of the destination and source colors. The destination is replaced with the source only where the source is darker.
lighten	Selects the lighter of the destination and source colors. The destination is replaced with the source only where the source is lighter.
color-dodge	Brightens the destination color to reflect the source color. Drawing with black produces no changes.
color-burn	Darkens the destination color to reflect the source color. Drawing with white produces no change.
hard-light	Multiplies the colors, depending on the source color value. The effect is similar to shining a harsh spotlight on the destination.
soft-light	Darkens or lightens the colors, depending on the source color value. The effect is similar to a diffused spotlight on the destination.
difference	Subtracts the darker of the two constituent colors from the lighter color. White inverts the destination color; black produces no change.
exclusion	Produces an effect similar to that of difference but lower in contrast. White inverts the destination color; black produces no change.

Short syntax¶

When a style has a single feature style, it is possible to omit the syntax for the feature style and start at the first parameter inside.

So the following complete styles are both equivalent:

feature-styles:
- rules:
  - name: rule1
    scale: [min,50000]
    symbolizers:
    - line:
        stroke-color: '#000000'
        stroke-width: 2
  - name: rule2
    scale: [50000,max]
    symbolizers:
    - line:
        stroke-color: '#000000'
        stroke-width: 1

rules:
- name: rule1
  scale: [min,50000]
  symbolizers:
  - line:
      stroke-color: '#000000'
      stroke-width: 2
- name: rule2
  scale: [50000,max]
  symbolizers:
  - line:
      stroke-color: '#000000'
      stroke-width: 1

Examples¶

Road casing¶

This example shows how a smaller line can be drawn on top of a larger line, creating the effect of lines being drawn with a border or “casing”:

feature-styles:
- name: outer
  title: Outer line
  rules:
  - name: outer_rule
    symbolizers:
    - line:
        stroke-color: '#808080'
        stroke-width: 8
- name: inner
  title: Inner line
  rules:
  - name: inner_rule
    symbolizers:
    - line:
        stroke-color: '#44FF88'
        stroke-width: 6

To draw the inner lines always on top of the outer lines we need to control the z-order. The outer_rule is encased in its own feature style and drawn into a distinct “Outer line” buffer. Next the inner_rule is encased in its own feature style and drawn into a distinct “Inner line” buffer.

Feature style buffers¶

During composition these two off-screen buffers are combined into the the final map.

Final map composition¶

When drawn, the outer line has a width of 8 pixels and the inner line has a width of 6 pixels, so the line “border” is 1 pixel (on each side).

Example showing road casing¶

 1 feature-styles:
 2 - name: without_first_match
 3   rules:
 4   - name: fishing_town
 5     filter: ${type = 'town' AND industry = 'fishing'}
 6     symbolizers:
 7     - point:
 8         <<: *fishingtown
 9   - name: fishing_city
10     filter: ${type = 'city' AND industry = 'fishing'}
11     symbolizers:
12     - point:
13         <<: *fishingcity
14   - name: other_towns_cities
15     filter: ${type IN ('town', 'city') AND industry <> 'fishing'}
16     symbolizers:
17     - point:
18         <<: *othertownscities
19   - name: other
20     else: true
21     symbolizers:
22     - point:
23         <<: *allotherplaces

 1 feature-styles:
 2 - name: with_first_match
 3   x-ruleEvaluation: first
 4   rules:
 5   - name: fishing_town
 6     filter: ${type = 'town' AND industry = 'fishing'}
 7     symbolizers:
 8     - point:
 9         <<: *fishingtown
10   - name: fishing_city
11     filter: ${type = 'city' AND industry = 'fishing'}
12     symbolizers:
13     - point:
14         <<: *fishingcity
15   - name: other_towns_cities
16     filter: ${type IN ('town', 'city')}
17     symbolizers:
18     - point:
19         <<: *othertownscities
20   - name: other
21     else: true
22     symbolizers:
23     - point:
24         <<: *allotherplaces

Layer mask¶

Given two layers (in this case, two three-band rasters), one can mask or “knock out” the other, making visible what’s beneath.

Top/source layer¶

Bottom/destination layer¶

Note

Screenshots show data provided by Natural Earth.

Layer 1 (top/source):

1 feature-styles:
2 - rules:
3   - title: Top/source
4     symbolizers:
5     - raster:
6         opacity: 1.0
7   x-composite: xor

Layer 2 (bottom/destination):

1 feature-styles:
2 - rules:
3   - title: Bottom/destination
4     symbolizers:
5     - raster:
6         opacity: 1.0

Layer as mask¶

Color inversion¶

Given the same two layers as the previous example, one can display the difference of the colors of layers, which can have the effect of a color “inversion”.

Layer 1 (top/source):

1 feature-styles:
2 - rules:
3   - title: Top/source
4     symbolizers:
5     - raster:
6         opacity: 1.0
7   x-composite: difference

Layer 2 (bottom/destination):

1 feature-styles:
2 - rules:
3   - title: Bottom/destination
4     symbolizers:
5     - raster:
6         opacity: 1.0

Layer as color inversion¶