javax.media.jai.operator
Class FilteredSubsampleDescriptor

java.lang.Object
  |
  +--javax.media.jai.OperationDescriptorImpl
        |
        +--javax.media.jai.operator.FilteredSubsampleDescriptor
All Implemented Interfaces:
OperationDescriptor, RegistryElementDescriptor, Serializable

public class FilteredSubsampleDescriptor
extends OperationDescriptorImpl

An OperationDescriptor describing the "FilteredSubsample" operation.

The "FilteredSubsample" operation subsamples an image by integral factors. The furnished scale factors express the ratio of the source dimensions to the destination dimensions. The input filter is symmetric about the center pixel and is specified by values from the center outward. Both filter axes use the same input filter values.

When applying scale factors of scaleX, scaleY to a source image with width of src_width and height of src_height, the resulting image is defined to have the following bounds: dst_minX = round(src_minX / scaleX)
dst_minY = round(src_minY / scaleY)
dst_width = round(src_width / scaleX)
dst_height = round(src_height / scaleY)

The input filter is quadrant symmetric (typically antialias). The filter is product-separable, quadrant symmetric, and is defined by half of its span. For example, if the input filter, qsFilter, was of size 3, it would have width and height 5 and have the symmetric form:
qs[2] qs[1] qs[0] qs[1] qs[2]

A fully expanded 5 by 5 kernel has the following format (25 entries defined by only 3 entries):

qs[2]*qs[2] qs[2]*qs[1] qs[2]*qs[0] qs[2]*qs[1] qs[2]*qs[2]
qs[1]*qs[2] qs[1]*qs[1] qs[1]*qs[0] qs[1]*qs[1] qs[1]*qs[2]
qs[0]*qs[2] qs[0]*qs[1] qs[0]*qs[0] qs[0]*qs[1] qs[0]*qs[2]
qs[1]*qs[2] qs[1]*qs[1] qs[1]*qs[0] qs[1]*qs[1] qs[1]*qs[2]
qs[2]*qs[2] qs[2]*qs[1] qs[2]*qs[0] qs[2]*qs[1] qs[2]*qs[2]

This operator is similar to the image scale operator. Important differences are described here. The coordinate transformation differences between the FilteredDownsampleOpImage and the ScaleOpImage operators can be understood by comparing their mapping equations directly.

For the scale operator, the destination (D) to source (S) mapping equations are given by

xS = (xD - xTrans)/xScale
yS = (yD - yTrans)/yScale

The scale and translation terms are floating point values in D-frame pixel units. For scale this means that one S pixel maps to xScale by yScale D-frame pixels. The translation vector, (xTrans, yTrans), is in D-frame pixel units.

The FilteredSubsample operator mapping equations are given by

xS = xD*scaleX
yS = yD*scaleY

The scale terms for this operation are integral values in the S-Frame; there are no translation terms for this operation.

The downsample terms are restricted to positive integral values. Geometrically, one D-frame pixel maps to scaleX * scaleY S-frame pixels. The combination of downsampling and filtering has performance benefits over sequential operator usage in part due to the symmetry constraints imposed by only allowing integer parameters for scaling and only allowing separable symmetric filters. With odd scale factors, D-frame pixels map directly onto S-frame pixel centers. With even scale factors, D-frame pixels map squarely between S-frame pixel centers. Below are examples of even, odd, and combination cases.

s = S-frame pixel centers
d = D-frame pixel centers mapped to S-frame

 s   s   s   s   s   s           s   s   s   s   s   s  
   d       d       d  
 s   s   s   s   s   s           s   d   s   s   d   s  
  
 s   s   s   s   s   s           s   s   s   s   s   s  
   d       d       d  
 s   s   s   s   s   s           s   s   s   s   s   s  
  
 s   s   s   s   s   s           s   d   s   s   d   s  
   d       d       d  
 s   s   s   s   s   s           s   s   s   s   s   s  
  
 Even scaleX/Y factors            Odd scaleX/Y factors  
   
 s   s   s   s   s   s           s   s   s   s   s   s  
     d           d    
 s   s   s   s   s   s           s d s   s d s   s d s  
   
 s   s   s   s   s   s           s   s   s   s   s   s  
     d           d    
 s   s   s   s   s   s           s   s   s   s   s   s  
   
 s   s   s   s   s   s           s d s   s d s   s d s  
     d           d    
 s   s   s   s   s   s           s   s   s   s   s   s  
   
  Odd/even scaleX/Y factors      Even/odd scaleX/Y factors  

The convolution kernel is restricted to have quadrant symmetry (qs). This type of symmetry is also product separable. The qsFilter is specified by a floating array. If qsFilter[0], qsFilter[1], ... , qsFilter[qsFilter.length - 1] is the filter input, then the entire separable kernel is given by
qsFilter[qsFilter.length - 1], ... , qsFilter[0], ... , qsFilter[qsFilter.length - 1]

The restriction of integer parameter constraints allows full product separablity and symmetry when applying the combined resample and filter convolution operations.

If Bilinear or Bicubic interpolation is specified, the source needs to be extended such that it has the extra pixels needed to compute all the destination pixels. This extension is performed via the BorderExtender class. The type of border extension can be specified as a RenderingHint to the JAI.create method.

If no BorderExtender is specified, the source will not be extended. The output image size is still calculated according to the formula specified above. However since there is not enough source to compute all the destination pixels, only that subset of the destination image's pixels which can be computed, will be written in the destination. The rest of the destination will be set to zeros.

It should be noted that this operation automatically adds a value of Boolean.TRUE for the JAI.KEY_REPLACE_INDEX_COLOR_MODEL to the given configuration so that the operation is performed on the pixel values instead of being performed on the indices into the color map if the source(s) have an IndexColorModel. This addition will take place only if a value for the JAI.KEY_REPLACE_INDEX_COLOR_MODEL has not already been provided by the user. Note that the configuration Map is cloned before the new hint is added to it. The operation can be smart about the value of the JAI.KEY_REPLACE_INDEX_COLOR_MODEL RenderingHints, i.e. while the default value for the JAI.KEY_REPLACE_INDEX_COLOR_MODEL is Boolean.TRUE, in some cases the operator could set the default.

"FilteredSubsample" defines a PropertyGenerator that performs an identical transformation on the "ROI" property of the source image, which can be retrieved by calling the getProperty method with "ROI" as the property name.

One design purpose of this operation is anti-aliasing when downsampling. The technique of anti-aliasing applies a good filter to the area of rendering to generate better results. Generally, this filter is required to be (quadrant) symmetric and separable to obtain good performance. The widely-used Gaussian filter satisfies all these requirements. Thus, the default value for the parameter "qsFilter" is generated from a Gaussian kernel based on the following procedure:

Define the Gaussian function G(x) as

G(x) = e-x2/(2s2)/( (2pi)½s),

where s is the standard deviation, and pi is the ratio of the circumference of a circle to its diameter.

For a one-dimensional Gaussian kernel with a size of 2N+1, the standard deviation of the Gaussian function to generate this kernel is chosen as N/3. The one-dimensional Gaussian kernel KN(1:2N+1) is

(G(-N)/S, G(-N+1)/S, ..., G(0),..., G(N-1)/S, G(N)/S),

where S is the summation of G(-N), G(-N+1), ...,G(0), ..., G(N-1), and G(N). A two-dimensional Gaussian kernel with a size of (2N+1) x (2N+1) is constructed as the outer product of two KNs: the (i, j)th element is KN(i)KN(j). The quadrant symmetric filter corresponding to the (2N+1) x (2N+1) Gaussian kernel is simply

(G(0)/S, G(1)/S, ..., G(N)/S), or

(KN(N+1), ..., KN(2N+1).

Denote the maximum of the X and Y subsample factors as M. If M is even, the default "qsFilter" is the quadrant symmetric filter derived from the two-dimensional (M+1) x (M+1) Gaussian kernel. If M is odd, the default "qsFilter" is the quadrant symmetric filter derived from the two-dimensional M x M Gaussian kernel.

Resource List
Name Value
GlobalName FilteredSubsample
LocalName FilteredSubsample
Vendor com.sun.media.jai
Description Filters and subsamples an image.
DocURL http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/FilteredSubsample.html
Version 1.1
arg0Desc The X subsample factor.
arg1Desc The Y subsample factor.
arg2Desc Symmetric filter coefficients.
arg3Desc The interpolation object for resampling.

Parameter List
Name Class Type Default Value
scaleX java.lang.Integer 2
scaleY java.lang.Integer 2
qsFilter java.lang.Float [] A quadrant symmetric filter generated from a Gaussian kernel as described above.
interpolation javax.media.jai.Interpolation InterpolationNearest

Since:
JAI 1.1
See Also:
Interpolation, BorderExtender, OperationDescriptor, Serialized Form

Fields inherited from class javax.media.jai.OperationDescriptorImpl
resources, sourceNames, supportedModes
 
Fields inherited from interface javax.media.jai.OperationDescriptor
NO_PARAMETER_DEFAULT
 
Constructor Summary
FilteredSubsampleDescriptor()
           Constructor.
 
Method Summary
static RenderedOp create(RenderedImage source0, Integer scaleX, Integer scaleY, float[] qsFilterArray, Interpolation interpolation, RenderingHints hints)
          Filters and subsamples an image.
protected  boolean validateParameters(String modeName, ParameterBlock args, StringBuffer msg)
          Validates the input parameters.
 
Methods inherited from class javax.media.jai.OperationDescriptorImpl
arePropertiesSupported, getDefaultSourceClass, getDestClass, getDestClass, getInvalidRegion, getName, getNumParameters, getNumSources, getParamClasses, getParamDefaults, getParamDefaultValue, getParameterListDescriptor, getParamMaxValue, getParamMinValue, getParamNames, getPropertyGenerators, getPropertyGenerators, getRenderableDestClass, getRenderableSourceClasses, getResourceBundle, getResources, getSourceClasses, getSourceClasses, getSourceNames, getSupportedModes, isImmediate, isModeSupported, isRenderableSupported, isRenderedSupported, makeDefaultSourceClassList, validateArguments, validateArguments, validateParameters, validateRenderableArguments, validateRenderableSources, validateSources, validateSources
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FilteredSubsampleDescriptor

public FilteredSubsampleDescriptor()

Constructor.

Method Detail

validateParameters

protected boolean validateParameters(String modeName,
                                     ParameterBlock args,
                                     StringBuffer msg)
Validates the input parameters.

In addition to the standard checks performed by the superclass method, this method checks that "scaleX" and "scaleY" are both greater than 0 and that the interpolation type is one of 4 standard types:

javax.media.jai.InterpolationNearest
javax.media.jai.InterpolationBilinear
javax.media.jai.InterpolationBicubic
javax.media.jai.InterpolationBicubic2

Overrides:
validateParameters in class OperationDescriptorImpl
Following copied from class: javax.media.jai.OperationDescriptorImpl
Throws:
IllegalArgumentException - if any of the input parameters are null.
See Also:
OperationDescriptorImpl.validateArguments(java.lang.String, java.awt.image.renderable.ParameterBlock, java.lang.StringBuffer), ParameterListDescriptorImpl.isParameterValueValid(java.lang.String, java.lang.Object)

create

public static RenderedOp create(RenderedImage source0,
                                Integer scaleX,
                                Integer scaleY,
                                float[] qsFilterArray,
                                Interpolation interpolation,
                                RenderingHints hints)
Filters and subsamples an image.

Creates a ParameterBlockJAI from all supplied arguments except hints and invokes JAI.create(String,ParameterBlock,RenderingHints).

Parameters:
source0 - RenderedImage source 0.
scaleX - The X subsample factor. May be null.
scaleY - The Y subsample factor. May be null.
qsFilterArray - Symmetric filter coefficients. May be null.
interpolation - Interpolation object. May be null.
hints - The RenderingHints to use. May be null.
Returns:
The RenderedOp destination.
Throws:
IllegalArgumentException - if source0 is null.
See Also:
JAI, ParameterBlockJAI, RenderedOp