GeoTools : Color blending and compositing

Contact:

Andrea Aime

Tracker:

http://jira.codehaus.org/browse/GEOT-4958

Tagline:

Compositing and blending

Children:

Description

This technical proposal discusses the addition of color compositing and color blending in GeoTools/GeoServer map rendering capabilities to get results similar to Mapnik own color compositing, in other words, to support the well known SVG color compositing and blending abilities. References:

We will use the SVG nomenclature to name the operations. 

The compositing operations that will be supported are the following (within parenthesis, the equivalent Mapnik name):

  • copy (src)

  • destination (dst)

  • source-over (src-over)

  • destination-over (dst-over)

  • source-in (src-in)

  • destination-in (dst-in)

  • source-out (src-out)

  • destination-out (dst-out)

  • source-atop (src-atop)

  • destination-atop (dst-atop)

  • xor (xor)

All of the above operations are also known as Porter-Duff composites and are already available in Java2D by the AlphaComposite class, but they need to exposed in SLD and properly applied by the rendering engine.


The blending operations that will be supported are the following:
  • multiply

  • screen

  • overlay

  • darken

  • lighten

  • color-dodge

  • color-burn

  • hard-light

  • soft-light

  • difference

  • exclusion

  • hue

  • saturation

  • color

  • luminosity 

None of the above operators is available in Java2D, so they need to be first implemented as new Java2D Composite objects, and then exposed in SLD and properly applied by the rendering engine. Since this implementations will be pure java it is expected to be slower than the color compositing operations.

 

The two lists above leave out some Mapnik operators that are not maching the SVG specification, and will not be implemented at the moment: plus, minus, contrast, invert, invert-rgb, grain-merge, grain-extract, value

Exposing blending and compositing in SLD 

At the SLD level the compositing operation will be exposed either as a symbolizer level operation, or as a FeatureTypeStyle level operation, the first one will act only while painting specific symbolizers, the second one while merging inner featuer type styles with the already painted image.

At the single symbolizer level it is somehow tempting to play against the existing CSS properties and add a "fill-composite" or "stroke-composite", however, this would be limiting, as it could not apply to external graphics and rasters. Instead, we propose to add compositing/blending as a single vendor option:

<FeatureTypeStyle>
    <Rule>
      ...
      <PolygonSymbolizer>
         ....
         <VendorParameter name=”composite”>multiply</CssParameter>
     </PolygonSymbolizer>  
  </Rule>
<FeatureTypeStyle>

 

For the sake of simplicity and to align to other software practictes, a single "composite" tag will be used for both compositing and blending.

In order to specify how to composite/blend full layers instead a new <VendorOption> tag at the end of the FeatureTypeStyle, with the same usage and semantic as the symbolizer specific one.

<FeatureTypeStyle>
    <Rule>
    ...
    </Rule>
    <VendorParameter name=”composite”>multiply</CssParameter>
</FeatureTypeStyle>  

Exposing blending and compositing in CSS

The gt-css CSS syntax will be extended to support compositing at the symbolizer level by matching the corresponding symbolizer activation property (with the exception of the raster case):

  • mark-composite
  • fill-composite
  • stroke-composite
  • label-composite
  • raster-composite
To apply a composite at the feature type style level instead a global "composite" property will be used instead.

Implementing the new blending Composite objects

The color blending Composite already have an incomplete open source implementation as original provided by Roman Guy on his blog, under the BSD license:
http://www.curious-creature.com/2006/09/20/new-blendings-modes-for-java2d/comment-page-1/

This code has then been taken over by the SwingX project, embedded in the swingx-graphics module, improved and released under a dual licence, LGPL and BSD:
http://grepcode.com/file/repo1.maven.org/maven2/org.bidib.jbidib.swinglabs.swingx/swingx-graphics/1.6.5-1/org/jdesktop/swingx/graphics/BlendComposite.java#BlendComposite
The project is unfortunately dead, and the functionality provided is still insufficient, as it only supports INT RGB(A) images, while GeoTools often paints also against BYTE (A)BGR. 
The SwingX project is dead, so the most likely outcome is that the class will be merged into GeoTools. It is not clean if from an IP management point of view we need to rewrite it from scratch as a consequence, or not

Status

This proposal is under construction.

Voting has not started yet:

Tasks

This section is used to make sure your proposal is complete (did you remember documentation?) and has enough paid or volunteer time lined up to be a success

 

no progress

(tick)

done

(error)

impeded

(warning)

lack mandate/funds/time

(question)

volunteer needed

  1. API changed based on BEFORE / AFTER
  2. Update default implementation
  3. Update wiki (both module matrix and upgrade to to 2.5 pages) |
  4. Remove deprecated code from GeoTools project
  5. Update the user guide
  6. Update or provided sample code in demo
  7. review user documentation

API Changes

Filter

BEFORE:

package org.geotools.styling;


public interface FeatureTypeStyle extends org.opengis.style.FeatureTypeStyle {
    
    ...    
}

AFTER:

package org.geotools.styling;
public interface FeatureTypeStyle extends org.opengis.style.FeatureTypeStyle {
    
    ...    
 
    /**
     * Determines if a vendor option with the specific key has been set on this FeatureTypeStyle. 
     */
    boolean hasOption(String key);
    /**
     * Map of vendor options for the FeatureTypeStyle.
     * <p>
     * Client code looking for the existence of a single option should use {@link #hasOption(String)}
     * </p>
     */
    Map<String,String> getOptions();
}

Documentation Changes

I cannot find documentation pages talking about styling? There is just a very basic tutorial