COMPOSITE¶
Background¶
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.
Performance is affected by advanced blending (all modes except src-over).
Parameters¶
- 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.
- 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.
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.
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