javax.media.jai
Class GeometricOpImage

java.lang.Object
  extended byjavax.media.jai.PlanarImage
      extended byjavax.media.jai.OpImage
          extended byjavax.media.jai.GeometricOpImage
All Implemented Interfaces:
ImageJAI, PropertyChangeEmitter, PropertySource, RenderedImage, WritablePropertySource
Direct Known Subclasses:
ScaleOpImage, WarpOpImage

public abstract class GeometricOpImage
extends OpImage

An abstract base class for image operators that perform a geometric transformation of the source image.

The geometric relationship between the source and destination images will be determined by the specific behavior of the methods backwardMapRect() and forwardMapRect() the implementations of which must be provided by a subclass.

The location of the source pixel corresponding to a given destination pixel is determined by the aforementioned backward mapping transformation. The value of the destination pixel is then calculated by interpolating the values of a set of source pixels at locations in the vicinity of the backward mapped destination pixel location according to the requirements of a specified interpolation algorithm. In particular, a given destination pixel value may be interpolated from the neighborhood of source pixels beginning at (sx - leftPadding, sy - topPadding) and extending to (sx + rightPadding, sy + bottomPadding), inclusive, where (sx, sy) is the truncated backward mapped location of the destination pixel. The actual amount of padding required is determined by a supplied Interpolation object.

Since this operator might need a region around each source pixel in order to compute the destination pixel value, the border destination pixels might not be able to be computed without any source extension mechanism. The source extension method can be specified by supplying a BorderExtender object that will define the pixel values of the source outside the actual source area as a function of the actual source pixel values. If no extension is specified, the destination samples that cannot be computed will be written in the destination as the user-specified background values.

Since:
JAI 1.1
See Also:
BorderExtender, Interpolation, InterpolationNearest, OpImage

Field Summary
protected  double[] backgroundValues
          The user-specified background values.
protected  Rectangle computableBounds
          The computable bounds of this image within which the pixels of the image may be computed and set.
protected  BorderExtender extender
          The BorderExtender describing the method by which source data are extended to provide sufficient context for calculation of the pixel values of backward mapped coordinates according to the interpolation method specified.
protected  int[] intBackgroundValues
          The user-specified background values in integer.
protected  Interpolation interp
          The Interpolation object describing the subpixel interpolation method.
protected  boolean setBackground
          Indicates whether the background values are provided.
 
Fields inherited from class javax.media.jai.OpImage
cache, cobbleSources, OP_COMPUTE_BOUND, OP_IO_BOUND, OP_NETWORK_BOUND, tileCacheMetric, tileRecycler
 
Fields inherited from class javax.media.jai.PlanarImage
colorModel, eventManager, height, minX, minY, properties, sampleModel, tileFactory, tileGridXOffset, tileGridYOffset, tileHeight, tileWidth, width
 
Constructor Summary
GeometricOpImage(Vector sources, ImageLayout layout, Map configuration, boolean cobbleSources, BorderExtender extender, Interpolation interp)
          Constructs a GeometricOpImage.
GeometricOpImage(Vector sources, ImageLayout layout, Map configuration, boolean cobbleSources, BorderExtender extender, Interpolation interp, double[] backgroundValues)
          Constructs a GeometricOpImage.
 
Method Summary
protected abstract  Rectangle backwardMapRect(Rectangle destRect, int sourceIndex)
          Returns the minimum bounding box of the region of the specified source to which a particular Rectangle of the destination will be mapped.
 Raster computeTile(int tileX, int tileY)
          Computes a tile.
protected abstract  Rectangle forwardMapRect(Rectangle sourceRect, int sourceIndex)
          Returns the minimum bounding box of the region of the destination to which a particular Rectangle of the specified source will be mapped.
 BorderExtender getBorderExtender()
          Retrieve the BorderExtender object associated with this class instance.
 Interpolation getInterpolation()
          Retrieve the Interpolation object associated with this class instance.
 Point2D mapDestPoint(Point2D destPt, int sourceIndex)
          Computes the position in the specified source that best matches the supplied destination image position.
 Rectangle mapDestRect(Rectangle destRect, int sourceIndex)
          Returns a conservative estimate of the region of a specified source that is required in order to compute the pixels of a given destination rectangle.
 Point2D mapSourcePoint(Point2D sourcePt, int sourceIndex)
          Computes the position in the destination that best matches the supplied source image position.
 Rectangle mapSourceRect(Rectangle sourceRect, int sourceIndex)
          Returns a conservative estimate of the destination region that can potentially be affected by the pixels of a rectangle of a given source.
 
Methods inherited from class javax.media.jai.OpImage
addTileToCache, cancelTiles, computeRect, computeRect, computesUniqueTiles, createTile, dispose, getExpandedNumBands, getFormatTags, getOperationComputeType, getTile, getTileCache, getTileCacheMetric, getTileDependencies, getTileFromCache, getTileRecycler, getTiles, hasExtender, prefetchTiles, queueTiles, recycleTile, setTileCache, vectorize, vectorize, vectorize
 
Methods inherited from class javax.media.jai.PlanarImage
addPropertyChangeListener, addPropertyChangeListener, addSink, addSink, addSource, addTileComputationListener, copyData, copyData, copyExtendedData, createColorModel, createSnapshot, createWritableRaster, finalize, getAsBufferedImage, getAsBufferedImage, getBounds, getColorModel, getData, getData, getDefaultColorModel, getExtendedData, getGraphics, getHeight, getImageID, getMaxTileX, getMaxTileY, getMaxX, getMaxY, getMinTileX, getMinTileY, getMinX, getMinY, getNumBands, getNumSources, getNumXTiles, getNumYTiles, getProperties, getProperty, getPropertyClass, getPropertyNames, getPropertyNames, getSampleModel, getSinks, getSource, getSourceImage, getSourceObject, getSources, getSplits, getTileComputationListeners, getTileFactory, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileIndices, getTileRect, getTiles, getTileWidth, getWidth, overlapsMultipleTiles, removeProperty, removePropertyChangeListener, removePropertyChangeListener, removeSink, removeSink, removeSinks, removeSource, removeSources, removeTileComputationListener, setImageLayout, setProperties, setProperty, setSource, setSources, tileXToX, tileXToX, tileYToY, tileYToY, toString, wrapRenderedImage, XToTileX, XToTileX, YToTileY, YToTileY
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

interp

protected Interpolation interp
The Interpolation object describing the subpixel interpolation method. This variable should not be null.


extender

protected BorderExtender extender
The BorderExtender describing the method by which source data are extended to provide sufficient context for calculation of the pixel values of backward mapped coordinates according to the interpolation method specified. If this variable is null no extension will be performed.


computableBounds

protected Rectangle computableBounds
The computable bounds of this image within which the pixels of the image may be computed and set. This is equal to the bounding box of the set of pixels the locations of which backward map to within the source image bounds contracted by the padding values required for interpolation.

The GeometricOpImage constructor sets the computable bounds to the image bounds. Subclasses should set this value to values reasonable for the operation in question.


setBackground

protected boolean setBackground
Indicates whether the background values are provided.


backgroundValues

protected double[] backgroundValues
The user-specified background values.


intBackgroundValues

protected int[] intBackgroundValues
The user-specified background values in integer.

Constructor Detail

GeometricOpImage

public GeometricOpImage(Vector sources,
                        ImageLayout layout,
                        Map configuration,
                        boolean cobbleSources,
                        BorderExtender extender,
                        Interpolation interp)
Constructs a GeometricOpImage. The image layout (image bounds, tile grid layout, SampleModel and ColorModel) of the output are set in the standard way by the OpImage constructor.

Additional control over the image bounds, tile grid layout, SampleModel, and ColorModel may be obtained by specifying an ImageLayout parameter. This parameter will be passed to the superclass constructor unchanged.

Parameters:
layout - An ImageLayout containing the source bounds before padding, and optionally containing the tile grid layout, SampleModel, and ColorModel.
sources - The immediate sources of this image.
configuration - Configurable attributes of the image including configuration variables indexed by RenderingHints.Keys and image properties indexed by Strings or CaselessStringKeys. This is simply forwarded to the superclass constructor.
cobbleSources - A boolean indicating whether computeRect() expects contiguous sources.
extender - A BorderExtender, or null.
interp - an Interpolation object to use for interpolation of the backward mapped pixel values at fractional positions. If the supplied parameter is null the corresponding instance variable will be initialized to an instance of InterpolationNearest.
Throws:
IllegalArgumentException - if sources is null.
IllegalArgumentException - If sources is non-null and any object in sources is null.
IllegalArgumentException - if combining the intersected source bounds with the layout parameter results in negative output width or height.

GeometricOpImage

public GeometricOpImage(Vector sources,
                        ImageLayout layout,
                        Map configuration,
                        boolean cobbleSources,
                        BorderExtender extender,
                        Interpolation interp,
                        double[] backgroundValues)
Constructs a GeometricOpImage. The image layout (image bounds, tile grid layout, SampleModel and ColorModel) of the output are set in the standard way by the OpImage constructor.

Additional control over the image bounds, tile grid layout, SampleModel, and ColorModel may be obtained by specifying an ImageLayout parameter. This parameter will be passed to the superclass constructor unchanged.

A RenderingHints for JAI.KEY_REPLACE_INDEX_COLOR_MODEL with the value of Boolean.TRUE is automatically added to the given configuration and passed up to the superclass constructor so that geometric operations are performed on the pixel values instead of being performed on the indices into the color map for those operations whose 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. Regarding the value for the JAI.KEY_REPLACE_INDEX_COLOR_MODEL RenderingHints, the operator itself can be smart based on the parameters, i.e. while the default value for the JAI.KEY_REPLACE_INDEX_COLOR_MODEL is Boolean.TRUE for operations that extend this class, in some cases the operator could set the default.

Parameters:
layout - An ImageLayout containing the source bounds before padding, and optionally containing the tile grid layout, SampleModel, and ColorModel.
sources - The immediate sources of this image.
configuration - Configurable attributes of the image including configuration variables indexed by RenderingHints.Keys and image properties indexed by Strings or CaselessStringKeys. This is simply forwarded to the superclass constructor.
cobbleSources - A boolean indicating whether computeRect() expects contiguous sources.
extender - A BorderExtender, or null.
interp - an Interpolation object to use for interpolation of the backward mapped pixel values at fractional positions. If the supplied parameter is null the corresponding instance variable will be initialized to an instance of InterpolationNearest.
backgroundValues - The user-specified background values. If the provided array length is smaller than the number of bands, all the bands will be filled with the first element of the array. If the provided array is null, set it to new double[]{0.0} .
Throws:
IllegalArgumentException - if sources is null.
IllegalArgumentException - If sources is non-null and any object in sources is null.
IllegalArgumentException - if combining the intersected source bounds with the layout parameter results in negative output width or height.
Since:
JAI 1.1.2
Method Detail

getInterpolation

public Interpolation getInterpolation()
Retrieve the Interpolation object associated with this class instance. The object is returned by reference.

Returns:
The associated Interpolation object.

getBorderExtender

public BorderExtender getBorderExtender()
Retrieve the BorderExtender object associated with this class instance. The object is returned by reference.

Returns:
The associated BorderExtender object or null.

mapDestPoint

public Point2D mapDestPoint(Point2D destPt,
                            int sourceIndex)
Computes the position in the specified source that best matches the supplied destination image position. If it is not possible to compute the requested position, null will be returned.

The implementation in this class returns the value of pt in the following code snippet:

 Rectangle destRect = new Rectangle((int)destPt.getX(),
                                    (int)destPt.getY(),
                                    1, 1);
 Rectangle sourceRect = backwardMapRect(destRect, sourceIndex);
 Point2D pt = (Point2D)destPt.clone();
 pt.setLocation(sourceRect.x + (sourceRect.width - 1.0)/2.0,
                sourceRect.y + (sourceRect.height - 1.0)/2.0);
 
Subclasses requiring different behavior should override this method.

Overrides:
mapDestPoint in class OpImage
Parameters:
destPt - the position in destination image coordinates to map to source image coordinates.
sourceIndex - the index of the source image.
Returns:
a Point2D of the same class as destPt or null.
Throws:
IllegalArgumentException - if destPt is null.
IndexOutOfBoundsException - if sourceIndex is negative or greater than or equal to the number of sources.
Since:
JAI 1.1.2

mapSourcePoint

public Point2D mapSourcePoint(Point2D sourcePt,
                              int sourceIndex)
Computes the position in the destination that best matches the supplied source image position. If it is not possible to compute the requested position, null will be returned.

The implementation in this class returns the value of pt in the following code snippet:

 Rectangle sourceRect = new Rectangle((int)sourcePt.getX(),
                                      (int)sourcePt.getY(),
                                      1, 1);
 Rectangle destRect = forwardMapRect(sourceRect, sourceIndex);
 Point2D pt = (Point2D)sourcePt.clone();
 pt.setLocation(destRect.x + (destRect.width - 1.0)/2.0,
                destRect.y + (destRect.height - 1.0)/2.0);
 
Subclasses requiring different behavior should override this method.

Overrides:
mapSourcePoint in class OpImage
Parameters:
sourcePt - the position in source image coordinates to map to destination image coordinates.
sourceIndex - the index of the source image.
Returns:
a Point2D of the same class as sourcePt or null.
Throws:
IllegalArgumentException - if sourcePt is null.
IndexOutOfBoundsException - if sourceIndex is negative or greater than or equal to the number of sources.
Since:
JAI 1.1.2

forwardMapRect

protected abstract Rectangle forwardMapRect(Rectangle sourceRect,
                                            int sourceIndex)
Returns the minimum bounding box of the region of the destination to which a particular Rectangle of the specified source will be mapped.

The integral source rectangle coordinates should be considered pixel indices. The "energy" of each pixel is defined to be concentrated in the continuous plane of pixels at an offset of (0.5, 0.5) from the index of the pixel. Forward mappings must take this (0.5, 0.5) pixel center into account. Thus given integral source pixel indices as input, the fractional destination location, as calculated by functions Xf(xSrc, ySrc), Yf(xSrc, ySrc), is given by:


     xDst = Xf(xSrc+0.5, ySrc+0.5) - 0.5
     yDst = Yf(xSrc+0.5, ySrc+0.5) - 0.5

 

Parameters:
sourceRect - the Rectangle in source coordinates.
sourceIndex - the index of the source image.
Returns:
a Rectangle indicating the destination bounding box, or null if the bounding box is unknown.
Throws:
IllegalArgumentException - if sourceIndex is negative or greater than the index of the last source.
IllegalArgumentException - if sourceRect is null.

backwardMapRect

protected abstract Rectangle backwardMapRect(Rectangle destRect,
                                             int sourceIndex)
Returns the minimum bounding box of the region of the specified source to which a particular Rectangle of the destination will be mapped.

The integral destination rectangle coordinates should be considered pixel indices. The "energy" of each pixel is defined to be concentrated in the continuous plane of pixels at an offset of (0.5, 0.5) from the index of the pixel. Backward mappings must take this (0.5, 0.5) pixel center into account. Thus given integral destination pixel indices as input, the fractional source location, as calculated by functions Xb(xDst, yDst), Yb(xDst, yDst), is given by:


     xSrc = Xb(xDst+0.5, yDst+0.5) - 0.5
     ySrc = Yb(xDst+0.5, yDst+0.5) - 0.5

 

Parameters:
destRect - the Rectangle in destination coordinates.
sourceIndex - the index of the source image.
Returns:
a Rectangle indicating the source bounding box, or null if the bounding box is unknown.
Throws:
IllegalArgumentException - if sourceIndex is negative or greater than the index of the last source.
IllegalArgumentException - if destRect is null.

mapSourceRect

public Rectangle mapSourceRect(Rectangle sourceRect,
                               int sourceIndex)
Returns a conservative estimate of the destination region that can potentially be affected by the pixels of a rectangle of a given source. The supplied Rectangle will first be contracted according to the Interpolation object characteristics and then forward mapped into destination coordinate space using forwardMapRect(). The resulting Rectangle is not clipped to the destination image bounds.

Specified by:
mapSourceRect in class OpImage
Parameters:
sourceRect - the Rectangle in source coordinates.
sourceIndex - the index of the source image.
Returns:
a Rectangle indicating the potentially affected destination region. This will equal the destination bounds if forwardMapRect() returns null.
Throws:
IllegalArgumentException - if sourceIndex is negative or greater than the index of the last source.
IllegalArgumentException - if sourceRect is null.

mapDestRect

public Rectangle mapDestRect(Rectangle destRect,
                             int sourceIndex)
Returns a conservative estimate of the region of a specified source that is required in order to compute the pixels of a given destination rectangle. The supplied Rectangle will first be backward mapped into source coordinate space using backwardMapRect() and then the resulting context will be modified according to the Interpolation object characteristics. The resulting Rectangle is not clipped to the source image bounds.

Specified by:
mapDestRect in class OpImage
Parameters:
destRect - the Rectangle in destination coordinates.
sourceIndex - the index of the source image.
Returns:
a Rectangle indicating the required source region. This will equal the bounds of the respective source if backwardMapRect() returns null.
Throws:
IllegalArgumentException - if sourceIndex is negative or greater than the index of the last source.
IllegalArgumentException - if destRect is null.

computeTile

public Raster computeTile(int tileX,
                          int tileY)
Computes a tile. A new WritableRaster is created to represent the requested tile. Its width and height are equal to this image's tile width and tile height respectively. If the requested tile lies outside of the image's boundary, or if the backward mapped and padded tile region does not intersect all sources, the created raster is returned with all of its pixels set to 0.

Whether or not this method performs source cobbling is determined by the cobbleSources variable set at construction time. If cobbleSources is true, cobbling is performed on the source for areas that intersect multiple tiles, and computeRect(Raster[], WritableRaster, Rectangle) is called to perform the actual computation. Otherwise, computeRect(PlanarImage[], WritableRaster, Rectangle) is called to perform the actual computation.

Overrides:
computeTile in class OpImage
Parameters:
tileX - The X index of the tile.
tileY - The Y index of the tile.
Returns:
The tile as a Raster.