COMPOSITE

Background

Available since MapServer 7.0, the COMPOSITE block is used to achieve blending effects with MapServer.

Some cartographic renderings benefit from the addition of advanced blending modes, as explained in detail in Blend Modes. This functionality is essential for more pleasant renderings of raster hillshadings over vector surfaces. It is also useful for simulating different kinds of overprinting effects.

Voir aussi

MS RFC 113: Layer Compositing Pipeline

Performance is affected by advanced blending (all modes except src-over).

Parameters

COMPFILTER [string]

Ajouté dans la version 7.2.

Name of the compositing filter. The primary purpose is to enable soft shadow and blurring effects, although other usages can exist or could be added in the future. Several compfilters can be placed after another to create a combined effect. For example a blur and translate effect can be combined to make a soft shadow effect behind a feature.

The currently available filters are:

  • blur(integer)

  • translate(integer,integer)

  • grayscale()

  • blacken()

  • whiten()

COMPOP [string]

Name of the compositing operator to use when blending the temporary image onto the main map image. See http://en.wikipedia.org/wiki/Blend_modes. The default compositing operator is « src-over ».

Available operators are:

  • clear

    Both the color and the alpha of the destination are cleared. Neither the source nor the destination are used. This is an unusual compose method that essentially ignores the overlay image completely, and just clears the background image.

  • color-burn

    Divides the inverted bottom layer by the top layer, and then inverts the result. This darkens the top layer increasing the contrast to reflect the color of the bottom layer. The darker the bottom layer, the more its color is used.

  • color-dodge

    Divides the bottom layer by the inverted top layer. This lightens the bottom layer depending on the value of the top layer: the brighter the top layer, the more its color affects the bottom layer. Blending any color with white gives white. Blending with black does not change the image.

  • contrast*

  • darken

    Creates a image that retains the smallest components of the foreground and background pixels. If the foreground pixel has the components r1, g1, and b1, and the background has r2, g2, b2, the resultant pixel is [min(r1,r2), min(g1,g2), min(b1,b2)]

  • difference

    Subtracts the bottom layer from the top layer or the other way round, to always get a positive value. Blending with black produces no change, as values for all colors are 0. (The RGB value for black is 0,0,0.) Blending with white inverts the picture.

  • dst

    This operator does nothing. The source, or overlay image, is completely ignored and the destination, or background image, is left unchanged. The method’s real use is as a means of “turning off” an alpha composition operation in other image operators.

  • dst-atop

    The part of the source lying inside of the destination is composited onto the destination.

  • dst-in

    The part of the destination lying inside of the source replaces the destination. Areas not overlaid are cleared. Will remove the overlay image’s shape from the background image like a cookie cutter which cuts out a cookie’s shape from cookie dough (result is the cookie).

  • dst-out

    The part of the destination lying outside of the source replaces the destination. Using the “cookie dough” metaphor of “dst-in” the result of the “dst-out” method is the dough that was left behind once a cookie has been cut out. It can be used to cut holes, or take bites out of the background image, using the shape of the overlay. Any color in the overlay is again completely ignored.

  • dst-over

    The destination is composited over the source and the result replaces the destination. Equivalent to placing the source overlay image “under” the destination. The result is that only the parts of our source or overlay image not hidden by the destination or background image will be visible as they peek out from underneath.

  • exclusion

    This is sort of an averaged difference. White on white will produce black (no difference), the same with black on black. However grey on grey will produce a grey result. White and black naturally still produce white (maximum difference).

  • hard-light

    Hard Light is a combination of Multiply and Screen, each at half strength. Hard Light effects the blend layer’s relationship to the base layer in the same way Overlay effects the base layer’s relationship to the blend layer.

  • hsl-color (added in 8.4)

    Creates a color with the hue and saturation of the source and the luminosity of the target. This preserves the gray levels of the target and is useful for coloring monochrome images or tinting color images.

  • hsl-hue (added in 8.4)

    Creates a color with the hue of the source and the saturation and luminosity of the target.

  • hsl-luminosity (added in 8.4)

    Creates a color with the luminosity of the source and the hue and saturation of the target. This produces an inverse effect to hsl-color

  • hsl-saturation (added in 8.4)

    Creates a color with the saturation of the source and the hue and luminosity of the target. Painting with this mode onto a gray area produces no change.

  • invert*

  • invert-rgb*

  • lighten

    Lighten has the opposite action of Darken. It selects the maximum of each component from the foreground and background pixels. If the foreground pixel has the components r1, g1, and b1, and the background has r2, g2, b2, the resultant pixel is [max(r1,r2), max(g1,g2), max(b1,b2)]

  • minus*

    Subtract the colors in the source image from the destination image. When transparency is involved, opaque areas is subtracted from any destination opaque areas.

  • multiply

    A simple multiply of the two images. Its formula is: [Src * Dest]. This means that if one of the images is pure white, the result will be the other image. On the other hand if one image is black the result will be black. Between these extremes one image will darken the destination image by the amount given. Note that “Multiply” will only darken an image, it will never brighten it. That is, it “attenuates” an image toward black, which makes this compose method a “Burn” style of composition.

  • overlay

    Overlay combines Multiply and Screen blend modes, at half strength. The parts of the top layer where the base layer is light become lighter, the parts where the base layer is dark become darker. Areas where the top layer are mid grey are unaffected.

  • plus

    The source is added to the destination and replaces the destination. This operator is useful for averaging or a controlled merger of two images, rather than a direct overlay.

  • screen

    The source and destination are complemented and then multiplied and then replace the destination. The resultant color is always at least as light as either of the two constituent colors. Screening any color with white produces white. Screening any color with black leaves the original color unchanged.

  • soft-light

    Soft light is most closely related to Overlay and is only similar to Hard Light by name. Will add highlights and shadows to an existing color image. However, the colors of the destination image are modified to produce a softer contrast, and smoother gradient in lighting effects.

  • src

    The source is copied to the destination. The destination is not used as input, though it is cleared. This operator completely replaces the background image with the overlay image. The colors and transparency in the background are completely junked leaving a blank image the same size as the original destination over which is applied the source image.

  • src-atop

    The part of the source lying inside of the destination is composited onto the destination. Like “src-over” but limits the result to the original shape of the background image. In other words, the alpha channel on the destination is unchanged but the image colors are overlaid by any non-transparent parts of the source image. If the background image is fully opaque (no transparency), this operation will act exactly like the normal “src-over” composition. It only differs when the background contains transparency which also clips the overlay. What makes this useful is for overlaying lighting and shading effects that are limited to the object (shape) of the destination.

  • src-in

    The part of the source lying inside of the destination replaces the destination.

  • src-out

    The part of the source lying outside of the destination replaces the destination.

  • src-over

    The source is composited over the destination. This is the default composite option if no other is specified.

  • xor

    The part of the source that lies outside of the destination is combined with the part of the destination that lies outside of the source. Source or Destination, but not both.

Operators marked with a star (*) will only be supported when using an AGG backends and when pixman support is not enabled, and will fall back to « src-over » when this is not the case.

OPACITY [integer]

Sets the opacity level (or the inability to see through the layer) of all classed pixels for a given layer. Must be between 0 to 100. A value of 100 is opaque and 0 is fully transparent.

Usage

Simple transparency / opacity is achieved by only specifying the OPACITY parameter (this achieves the same effect as the legacy LAYER OPACITY parameter):

LAYER
  COMPOSITE
    OPACITY 70
  END # COMPOSITE
...
END # LAYER

The darkening effect is achieved by adding the COMPOP parameter with the value darken:

LAYER
  COMPOSITE
    OPACITY 100
    COMPOP "darken"
  END # COMPOSITE
...
END # LAYER