Extend Contrast Enhancement method handling in SLD and CSS

• Contact: Ian Turton Daniele Romagnoli
• Tracker: GEOT-5180
• TLDR: Add support for specific parameterized contrast enhancement methods in SLD & CSS
• Branch: https://github.com/ianturton/geotools/tree/contrast

Description

The goal is to add some standards remote sensing linear contrast enhancement methods to GeoTools and GeoServer (like this [http://www.r-s-c-c.org/node/240]) with the ability to control the parameters for the stretch which is not possible via the standard SLD:

We need to extend SLD parsing and processing to apply at least linear contrast stretch as per the following elements:

    <ContrastEnhancement>`
      <Normalize>`
       <VendorOption name="algorithm">ClipToMinimumMaximum|StretchToMinimumMaximum|ClipToZero</VendorOption>`
        <VendorOption name=”minValue”>1</VendorOption>`
        <VendorOption name=”maxValue”>1</VendorOption>`
      </Normalize>`
    </ContrastEnhancement>`

With CSS representation following vendor option naming conventions:

    * {
	raster-channels: auto;
	raster-contrast-enhancement: normalize;
	-gt-raster-contrast-enhancement-algorithm: ClipToMinimumMaximum;
	-gt-raster-contrast-enhancement-min-value: 20;
	-gt-raster-contrast-enhancement-max-value: 30;
	raster-gamma : 0.5;
	raster-color-map: color-map-entry(#008000, 70)
		color-map-entry(#663333, 256);
	raster-gamma: 0.5;
   }

The parsers, translators and XSD-SLD will be updated to allow input and output of existing and new forms of ContrastMethod.

The new methods will be implemented in gt-rendering but will continue to work as before on unparameterized methods.

Algorithms

The following Algorithms will be implemented for Normalization (initially):

• StretchToMinimumMaximum
• ClipToMinimumMaximum
• ClipToZero

Parameters

All parameters will be implemented by using the <VendorOption name="NAME">VALUE</VendorOption> style in SLD and a raster-contrast-enhancement-parameter: NAME VALUE [NAME VALUE] in CSS.

For the Normalization algorithms named parameters will be:

• minValue
• maxValue

For Logarithmic & Exponential methods the following will be supported:

• normalizationFactor
• correctionFactor

In all cases any Expression may be used.

References:

• geotools-devel email discussion

Status

Choose one of:

• Under Discussion
• In Progress
• Completed
• Rejected,
• Deferred

Voting:

• Andrea Aime +1
• Ben Caradoc-Davies: +0
• Christian Mueller
• Ian Turton +1
• Justin Deoliveira
• Jody Garnett +1
• Simone Giannecchini +0

Tasks

1. Update implementation
2. Verify with test case
3. Remove deprecated code (including very old deprecations in ContrastEnhancement)
4. Documentation changes
   • API change make a note upgrading page.
   • Update the user guide with code example

API Change

Draft: Two new classes are added Exponential and Logarithmic to allow processing of the new method types, they extend ContrastEnhancmentMethod

Revised: Remove the deprecation on ContrastEnhancement.setType( Expression ) and add getOptions() map for vendor options.

Further Revised: set/getType are no longer needed and have been removed.

public interface ContrastEnhancement extends org.opengis.style.ContrastEnhancement {	

    ...

/**
     * Return vendor options relating to the enhancement method
     * 
     * @return a Map containing expressions with string keys.
     */
    public Map<String, Expression> getOptions();
    /**
     * check if vendor option key is available
     * @param key - the name of the option to check
     * @return true if present
     */
    public boolean hasOption(String key);
    
    /**
     * Store a vendor option
     * @param key - the name of the option
     * @param value an expression that evaluates to it's value
     */
    public void addOption(String key, Expression value);

     /**
     * @param options a Map of VendorOptions 
     */
    public void setOptions(Map<String, Expression> options);

    /**
     * @param string
     * @return An expression for the matching VendorOption
     */
    public Expression getOption(String string);

    /**
     * Convenience method to allow users to pass in a 
     * {@link ContrastEnhancementMethod} to update {@link Method} 
     * and {@link Options} in one go.
     * 
     * @param method the {@link ContrastEnhancementMethod} that underlies this enhancement
     */
    public void setRealMethod(ContrastEnhancementMethod method);
}

With additional method types:

public final class ContrastMethod extends CodeList<ContrastMethod> {
    ...
    public static final ContrastMethod LOGARITHMIC = new ContrastMethod("LOGARITHMIC");
    public static final ContrastMethod EXPONENTIAL = new ContrastMethod("EXPONENTIAL");
    ...
}