Proposal: support for image filters

[David Faure <faure@kde.org>]

Both ooimpress and kpresenter allow applying "filters" to images,
like desaturate, solarize, etc.

But ooimpress applies them by modifying the stored image itself, so it doesn't
need anything in the file format for this. However this means there's no way to
go back after applying an filter and saving.

In kpresenter the filter is stored in the file, and is applied when reopening the
document, which allows to change the filter's parameters, or to revert to the
initial image. KPresenter currently supports applying only one filter, but let's
make this ready for improvements and model a way to apply multiple filters.

Our proposal is the following:
 <style:image-filters>
   <style:image-filter style:image-filter-name="intensity" style:image-filter-value="10%">
    ...
 </style:image-filters>

The style:image-filters element would be a child of the style:graphic-properties element.

The possible names for style:image-filter-name are:

"fade" Fade an image to a certain background color.
Parameters:
  style:image-filter-color : the color used for fading.
  style:image-filter-value : the strength of the filter in %.

"flatten"   This recolors the image. The most dark color will become color a, 
the most bright one color b, and in between. 
Parameters:
 style:image-filter-color-begin : first color
 style:image-filter-color-end : second color

"intensity"   Either brighten or dim the image by a specified percent.
Parameters:
 style:image-filter-value : the value in %. A negative value dims, a positive value brightens.

"desaturate" Desaturate an image evenly.
Parameters:
 style:image-filter-value : the degree of desaturation, in %

"normalize" Normalises the pixel values to span the full range of color values.

"equalize" Performs histogram equalisation on the reference image.

"threshold" Thresholds the reference image.
Parameters:
 style:image-filter-value : the threshold value, between 0 and 255.

"solarize"  Produces a 'solarization' filter seen when exposing a photographic 
film to light during the development process. 
Parameters:
 style:image-filter-value : the extent of the solarization, in %

"emboss" Embosses the source image. This involves highlighting the edges and 
applying various other enhancements in order to get a metal filter.

"despeckle" Minimizes speckle noise in the source image using the 8 hull 
algorithm.

"blur" Blurs an image by convolving pixel neighborhoods.
Properties:
 style:image-filter-value : the radius of the gaussian

"charcoal"  Produces a neat little "charcoal" filter. 
Properties:
 style:image-filter-value : the radius of the gaussian

"noise-uniform" Adds noise with uniform distribution.
"noise-gaussian" Adds noise with gaussian distribution.
"noise-multiplicative-gaussian" Adds noise with multiplicative gaussian distribution.
"noise-impulse" Adds noise with impulse gaussian distribution.
"noise-laplacian" Adds noise with laplacian distribution.
"noise-poisson" Adds noise with poission distribution.

"edge" Detects edges in an image using pixel neighborhoods and an edge 
detection mask. 
Properties:
 style:image-filter-value : the radius of the gaussian

"implode" Implodes an image by a specified percent. 
Properties:
 style:image-filter-value : the extent of the implosion in %

"oil" Produces an oil painting filter. 
Properties:
 style:image-filter-value : the radius of the gaussian

"sharpen" Sharpens the pixels in the image using pixel neighborhoods. 
Properties:
 style:image-filter-value : the radius of the gaussian

"spread" Randomly displaces pixels. "image-filter-value"
Properties:
 style:image-filter-value : the vicinity for choosing a random pixel to swap

"shade" Shades the image using a distance light source, using color shading.
Properties:
 style:image-filter-value : string containing two values, azimuth and elevation, to determine the light source and direction.

"shade-grayscale" Shades the image using a distance light source, using grayscale shading.
Properties:
 style:image-filter-value : string containing two values, azimuth and elevation, to determine the light source and direction.

"swirl" Swirls the image by a specified amount
Properties:
  style:image-filter-value : the tightness of the swirl, in degrees

"wave" Modifies the pixels along a sine wave.
Properties:
 style:image-filter-value : string containing two values, amplitude and length.
 amplitude is the amplitude of the sine wave, length is the frequency of the sine wave.

--------------

Precise proposal (in RelaxNG format) attached.
The attribute list is rather relaxed, making all attributes available for all filters
instead of forcing that e.g. image-filter-color only exists for "fade" etc.
If preferred I can try changing that, but AFAIK it requires duplicating the 
definition of the element, inside a <choice> tag?

-- 
David Faure, faure@kde.org, sponsored by Trolltech to work on KDE,
Konqueror (http://www.konqueror.org), and KOffice (http://www.koffice.org).
<define name="style-graphic-properties-elements" combine="interleave">
    <ref name="style-image-filters"/>
</define>

<define name="style-image-filters">
    <optional>
        <element name="style:image-filters">
            <zeroOrMore>
                <ref name="style-image-filter"/>
            </zeroOrMore>
        </element>
    </optional>
</define>

<define name="style-image-filter">
    <element name="style:image-filter">
        <ref name="style-image-filter-attlist"/>
    </element>
</define>

<define name="style-image-filter-attlist" combine="interleave">
    <attribute name="style:image-filter-name">
        <choice>
            <value>fade</value>
            <value>flatten</value>
            <value>intensity</value>
            <value>desaturate</value>
            <value>normalize</value>
            <value>equalize</value>
            <value>threshold</value>
            <value>solarize</value>
            <value>emboss</value>
            <value>despeckle</value>
            <value>blur</value>
            <value>charcoal</value>
            <value>noise</value>
            <value>edge</value>
            <value>implode</value>
            <value>oil</value>
            <value>sharpen</value>
            <value>spread</value>
            <value>shade</value>
            <value>shade-grayscale</value>
            <value>swirl</value>
            <value>wave</value>
        </choice>
    </attribute>
</define>

<define name="style-image-filter-attlist" combine="interleave">
    <optional>
        <attribute name="style:image-filter-value">
            <ref name="string"/>
        </attribute>
    </optional>
</define>

<define name="style-image-filter-attlist" combine="interleave">
    <optional>
        <attribute name="style:image-filter-color">
            <ref name="color"/>
        </attribute>
    </optional>
</define>

<define name="style-image-filter-attlist" combine="interleave">
    <optional>
        <attribute name="style:image-filter-color-begin">
            <ref name="color"/>
        </attribute>
        <attribute name="style:image-filter-color-end">
            <ref name="color"/>
        </attribute>
    </optional>
</define>