javax.media.jai
Class StatisticsOpImage

java.lang.Object
  javax.media.jai.PlanarImage
      javax.media.jai.OpImage
          javax.media.jai.StatisticsOpImage

All Implemented Interfaces:

ImageJAI, PropertyChangeEmitter, PropertySource, RenderedImage, WritablePropertySource

public abstract class StatisticsOpImage

extends OpImage

An abstract base class representing image operators that compute statistics on a given region of an image, and with a given sampling period. Such operators may only have one source image.

The layout of this image is exactly the same as that of the source image. Any user supplied layout values via the RenderingHints are ignored. The StatisticsOpImage simply passes the pixels of the source image through unchanged. However, the desired statistics are computed on demand and made available as a property or set of properties on the image.

All instances of StatisticsOpImage make use of a region of interest, specified as a ROI object. If this argument is null, the entire source image is used. Additionally, they may perform spatial subsampling of the region of interest according to xPeriod and yPeriod parameters that may vary from 1 (sample every pixel of the region of interest) upwards. This allows the speed and quality of statistics gathering to be traded off against one another.

Subclasses should provide implementations of the getStatisticsNames, createStatistics, and accumulateStatistics methods.

See Also:

OpImage

Field Summary

protected ROI	roi The region of interest over which to compute the statistics.
protected int	xPeriod The horizontal sampling rate.
protected int	xStart The X coordinate of the initial sample.
protected int	yPeriod The vertical sampling rate.
protected int	yStart The Y coordinate of the initial sample.

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

StatisticsOpImage(RenderedImage source, ROI roi, int xStart, int yStart, int xPeriod, int yPeriod)
Constructor.

Method Summary

protected abstract void	accumulateStatistics(String name, Raster source, Object stats) Accumulates statistics on the specified region into the previously created statistics object.
boolean	computesUniqueTiles() Returns false as computeTile() invocations are forwarded to the RenderedImage source and are therefore not unique objects in the global sense.
Raster	computeTile(int tileX, int tileY) Computes the image data of a tile.
protected abstract Object	createStatistics(String name) Returns an object that will be used to gather the named statistic.
Object	getProperty(String name) Returns one of the available statistics as a property.
String[]	getPropertyNames() Returns a list of property names that are recognized by this image.
protected abstract String[]	getStatisticsNames() Returns a list of names of statistics understood by this class.
Raster	getTile(int tileX, int tileY) Returns a tile of this image as a Raster.
Raster[]	getTiles(Point[] tileIndices) Returns a list of tiles.
Rectangle	mapDestRect(Rectangle destRect, int sourceIndex) Maps the destination rectangle into source space unchanged.
Rectangle	mapSourceRect(Rectangle sourceRect, int sourceIndex) Maps the source rectangle into destination space unchanged.

Methods inherited from class javax.media.jai.OpImage

addTileToCache, cancelTiles, computeRect, computeRect, createTile, dispose, getExpandedNumBands, getFormatTags, getOperationComputeType, getTileCache, getTileCacheMetric, getTileDependencies, getTileFromCache, getTileRecycler, hasExtender, mapDestPoint, mapSourcePoint, 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, getPropertyClass, 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

roi

protected ROI roi

The region of interest over which to compute the statistics. If it is null, the entire image is used to compute the statistics.

xStart

protected int xStart

The X coordinate of the initial sample.

yStart

protected int yStart

The Y coordinate of the initial sample.

xPeriod

protected int xPeriod

The horizontal sampling rate.

yPeriod

protected int yPeriod

The vertical sampling rate.

Constructor Detail

StatisticsOpImage

public StatisticsOpImage(RenderedImage source,
                         ROI roi,
                         int xStart,
                         int yStart,
                         int xPeriod,
                         int yPeriod)

Constructor.

The layout of this image is exactly the same as that of the source image. Any user supplied layout values via the RenderingHints are ignored.

Parameters:

source - The source image over which the statistics is accumulated.

roi - The region of interest that specifies the region of the source image over which to compute the statistics. If it is null, the entire source image is used.

xStart - The initial X sample coordinate.

yStart - The initial Y sample coordinate.

xPeriod - The horizontal sampling rate.

yPeriod - The vertical sampling rate.

Throws:

IllegalArgumentException - If source is null.

Since:

JAI 1.1

Method Detail

computesUniqueTiles

public boolean computesUniqueTiles()

Returns false as computeTile() invocations are forwarded to the RenderedImage source and are therefore not unique objects in the global sense.

Overrides:

computesUniqueTiles in class OpImage

Since:

JAI 1.1

getTile

public Raster getTile(int tileX,
                      int tileY)

Returns a tile of this image as a Raster. If the requested tile is completely outside of this image's bounds, this method returns null.

Statistics operators do not cache their tiles internally. Rather, the implementation of this method in this class simply forwards the request to the source image.

Specified by:

getTile in interface RenderedImage

Overrides:

getTile in class OpImage

Parameters:

tileX - The X index of the tile.

tileY - The Y index of the tile.

Returns:

The requested tile as a Raster or null.

computeTile

public Raster computeTile(int tileX,
                          int tileY)

Computes the image data of a tile.

The implementation of this method in this class simply forwards the request to the source image.

Overrides:

computeTile in class OpImage

Parameters:

tileX - The X index of the tile.

tileY - The Y index of the tile.

Since:

JAI 1.1

getTiles

public Raster[] getTiles(Point[] tileIndices)

Returns a list of tiles. The request is simply forwarded to the source image.

Overrides:

getTiles in class OpImage

Parameters:

tileIndices - The indices of the tiles requested.

Returns:

An array of Rasters containing the tiles corresponding to the given tile indices.

Throws:

IllegalArgumentException - If tileIndices is null.

mapSourceRect

public Rectangle mapSourceRect(Rectangle sourceRect,
                               int sourceIndex)

Maps the source rectangle into destination space unchanged.

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 valid destination region.

Throws:

IllegalArgumentException - If sourceIndex is not 0.

IllegalArgumentException - If sourceRect is null.

mapDestRect

public Rectangle mapDestRect(Rectangle destRect,
                             int sourceIndex)

Maps the destination rectangle into source space unchanged.

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.

Throws:

IllegalArgumentException - If sourceIndex is not 0.

IllegalArgumentException - If destRect is null.

getProperty

public Object getProperty(String name)

Returns one of the available statistics as a property. If the property name is not recognized, this method returns java.awt.Image.UndefinedProperty.

Specified by:

getProperty in interface PropertySource

Overrides:

getProperty in class PlanarImage

Parameters:

name - the name of the property to get, as a String.

Returns:

A reference to the property Object, or the value java.awt.Image.UndefinedProperty.

Throws:

IllegalArgumentException - If name is null.

getPropertyNames

public String[] getPropertyNames()

Returns a list of property names that are recognized by this image.

Specified by:

getPropertyNames in interface PropertySource

Overrides:

getPropertyNames in class PlanarImage

Returns:

An array of Strings containing valid property names.

getStatisticsNames

protected abstract String[] getStatisticsNames()

Returns a list of names of statistics understood by this class.

createStatistics

protected abstract Object createStatistics(String name)

Returns an object that will be used to gather the named statistic.

Parameters:

name - The name of the statistic to be gathered.

accumulateStatistics

protected abstract void accumulateStatistics(String name,
                                             Raster source,
                                             Object stats)

Accumulates statistics on the specified region into the previously created statistics object. The region of interest and X and Y sampling rate should be respected.

Parameters:

name - The name of the statistic to be gathered.

source - A Raster containing source pixels. The dimensions of the Raster will not exceed maxWidth x maxHeight.

stats - A statistics object generated by a previous call to createStatistics.