javax.media.jai
Class GeometricOpImage

java.lang.Object
  |
  +--javax.media.jai.PlanarImage
        |
        +--javax.media.jai.OpImage
              |
              +--javax.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 zero.

Since:

JAI 1.1

See Also:

BorderExtender, Interpolation, InterpolationNearest, OpImage

Field Summary

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 Interpolation	interp The Interpolation object describing the subpixel interpolation method.

Fields inherited from class javax.media.jai.OpImage

cache, cobbleSources, OP_COMPUTE_BOUND, OP_IO_BOUND, OP_NETWORK_BOUND, tileCacheMetric

Fields inherited from class javax.media.jai.PlanarImage

colorModel, eventManager, height, minX, minY, properties, sampleModel, tileGridXOffset, tileGridYOffset, tileHeight, tileWidth, width

Constructor Summary

GeometricOpImage(Vector sources, ImageLayout layout, Map configuration, boolean cobbleSources, BorderExtender extender, Interpolation interp)
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.
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.
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, finalize, getExpandedNumBands, getFormatTags, getOperationComputeType, getTile, getTileCache, getTileCacheMetric, getTileDependencies, getTileFromCache, getTiles, hasExtender, prefetchTiles, queueTiles, setTileCache, vectorize, vectorize, vectorize

Methods inherited from class javax.media.jai.PlanarImage

addPropertyChangeListener, addPropertyChangeListener, addSink, addSink, addSource, addTileComputationListener, copyData, copyData, copyExtendedData, createColorModel, createSnapshot, dispose, getAsBufferedImage, getAsBufferedImage, getBounds, getColorModel, getData, getData, getDefaultColorModel, getExtendedData, getGraphics, getHeight, 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, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileIndices, getTileRect, getTiles, getTileWidth, getWidth, 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.

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.

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.

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().

Overrides:

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.

Overrides:

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.