org.jaitools.tiledimage
Class DiskMemImage

java.lang.Object
  javax.media.jai.PlanarImage
      org.jaitools.tiledimage.DiskMemImage

All Implemented Interfaces:

RenderedImage, WritableRenderedImage, javax.media.jai.ImageJAI, javax.media.jai.PropertyChangeEmitter, javax.media.jai.PropertySource, javax.media.jai.WritablePropertySource

public class DiskMemImage
extends javax.media.jai.PlanarImage
implements WritableRenderedImage

A tiled image class similar to JAI's standard TiledImage that uses a DiskMemTileCache to manage its data. Image tiles are cached in memory and, if the volume of image data is greater than available memory, also on disk as temporary files. When a tile is accessed it is swapped into memory if not already resident. Thus, very large images can be handled, albeit at the cost of disk I/O.

By default, each DiskMemImage uses its own tile cache but it is also possible for images to share a common tile cache as shown here:

     DiskMemImage image1 = new DiskMemImage(...);
     image1.useCommonTileCache(true);

     DiskMemImage image2 = new DiskMemImage(...);
     image2.useCommonTileCache(true);

     DiskMemImage image3 = new DiskMemImage(...);
 

In the example above, image1 and image2 will share a common tile cache while image3 will use a separate, exclusive tile cache. You can test whether an image is using the common cache like this:

     boolean usingCommonCache = image.isUsingCommonTileCache();
 

The memory capacity of the common cache can be set like this:

     long memCapacity = 128 * 1024 * 1024; // 128 Mb
     DiskMemImage.getCommonCache().setMemoryCapacity(memCapacity);
 

Since:

1.0

Version:

$Id$

Author:

Michael Bedward

See Also:

DiskMemTileCache

Field Summary

static long	DEFAULT_COMMON_CACHE_SIZE The default memory capacity of the common tile cache in bytes (256 * 1024 * 1024 = 256 Mb)
protected int	numTilesInUse The number of tiles that are currently checked out for writing
protected int[][]	numWriters A 2D array with dimensions corresponding to the tile grid width and height that records, for each tile, the number of writers that have the tile checked out currently
protected DiskMemTileCache	tileCache The tile cache in use by this image.
protected Rectangle	tileGrid Defines the valid range of tile x and y coordinates.
protected long	tileMemorySize The amount of memory (in bytes) required to hold the data for an image tile
protected Set<TileObserver>	tileObservers The set of tile observers currently registered with this image

Fields inherited from class javax.media.jai.PlanarImage

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

Constructor Summary

DiskMemImage(int minX, int minY, int width, int height, int tileGridXOffset, int tileGridYOffset, SampleModel tileSampleModel)
Creates a new image.

DiskMemImage(int minX, int minY, int width, int height, int tileGridXOffset, int tileGridYOffset, SampleModel tileSampleModel, ColorModel colorModel)
Creates a new image.

DiskMemImage(int minX, int minY, int width, int height, SampleModel tileSampleModel)
Creates a new image with default values for tile offsets (0) and ColorModel (null)

DiskMemImage(int width, int height, SampleModel tileSampleModel)
Creates a new image with default values for origin (0, 0), x and y tile offsets (0) and ColorModel (null).

DiskMemImage(int width, int height, SampleModel tileSampleModel, ColorModel colorModel)
Creates a new image with default values for origin (0, 0) and tile offsets (0).

Method Summary

void	addTileObserver(TileObserver to)
Graphics2D	createGraphics() Creates a Graphics2D object for drawing operations with this image.
static DiskMemTileCache	getCommonTileCache() Get the common tile cache.
long	getMemoryCapacity() Gets the maximum amount of memory, in bytes, that this image will use for in-memory storage of its data.
int	getSample(int x, int y, int b) Gets the image value for the given image position as an integer.
double	getSampleDouble(int x, int y, int b) Gets the image value for the given image position as a double.
float	getSampleFloat(int x, int y, int b) Gets the image value for the given image position as a float.
Raster	getTile(int tileX, int tileY) Gets a tile for reading.
DiskMemTileCache	getTileCache() Gets a reference to the DiskMemTileCache instance used by this image.
long	getTileMemorySize() Gets the amount of memory (bytes) required to store a single tile's data.
WritableRaster	getWritableTile(int tileX, int tileY) Checks out a tile for writing.
Point[]	getWritableTileIndices() Gets the indices (tile grid col,row) of tiles that are currently checked out for writing.
boolean	hasTileWriters() Tests if any tiles are currently checked out for writing.
boolean	isTileWritable(int tileX, int tileY) Tests if a tile is currently checked-out for writing (via a call to getWritableTile(int, int).
boolean	isUsingCommonCache() Tests if this image is using the common tile cache.
void	releaseWritableTile(int tileX, int tileY) Releases a tile that was checked out for writing.
void	removeTileObserver(TileObserver to)
static void	setCommonTileCache(DiskMemTileCache newCache) Sets a new common cache.
void	setData(Raster data) Copies data from the given Raster object into this image.
void	setSample(int x, int y, int b, double value) Sets the image value for the given image position as a double.
void	setSample(int x, int y, int b, float value) Sets the image value for the given image position as a float.
void	setSample(int x, int y, int b, int value) Sets the image value for the given image position as an integer.
void	setUseCommonCache(boolean useCommon) Sets whether this image will use the common tile cache.

Methods inherited from class javax.media.jai.PlanarImage

addPropertyChangeListener, addPropertyChangeListener, addSink, addSink, addSource, addTileComputationListener, cancelTiles, copyData, copyData, copyExtendedData, createColorModel, createSnapshot, createWritableRaster, dispose, 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, getTiles, getTileWidth, getWidth, overlapsMultipleTiles, prefetchTiles, queueTiles, 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

Methods inherited from interface java.awt.image.RenderedImage

copyData, getColorModel, getData, getData, getHeight, getMinTileX, getMinTileY, getMinX, getMinY, getNumXTiles, getNumYTiles, getProperty, getPropertyNames, getSampleModel, getSources, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileWidth, getWidth

Field Detail

DEFAULT_COMMON_CACHE_SIZE

public static final long DEFAULT_COMMON_CACHE_SIZE

The default memory capacity of the common tile cache in bytes (256 * 1024 * 1024 = 256 Mb)

See Also:

Constant Field Values

tileCache

protected DiskMemTileCache tileCache

The tile cache in use by this image. It may or may not be the common tile cache. Ahthough this is a protected field, it is recommended that sub-classes use getTileCache() for general purposes.

tileGrid

protected Rectangle tileGrid

Defines the valid range of tile x and y coordinates.

numWriters

protected int[][] numWriters

A 2D array with dimensions corresponding to the tile grid width and height that records, for each tile, the number of writers that have the tile checked out currently

numTilesInUse

protected int numTilesInUse

The number of tiles that are currently checked out for writing

See Also:

getWritableTileIndices()

tileMemorySize

protected long tileMemorySize

The amount of memory (in bytes) required to hold the data for an image tile

tileObservers

protected Set<TileObserver> tileObservers

The set of tile observers currently registered with this image

Constructor Detail

DiskMemImage

public DiskMemImage(int width,
                    int height,
                    SampleModel tileSampleModel)

Creates a new image with default values for origin (0, 0), x and y tile offsets (0) and ColorModel (null).

Parameters:

width - image width

height - image height

tileSampleModel - a SampleModel specifying the dimensions data type etc. for image tiles

DiskMemImage

public DiskMemImage(int width,
                    int height,
                    SampleModel tileSampleModel,
                    ColorModel colorModel)

Creates a new image with default values for origin (0, 0) and tile offsets (0).

Parameters:

width - image width

height - image height

tileSampleModel - the SampleModel

colorModel - the ColorModel

DiskMemImage

public DiskMemImage(int minX,
                    int minY,
                    int width,
                    int height,
                    SampleModel tileSampleModel)

Creates a new image with default values for tile offsets (0) and ColorModel (null)

Parameters:

minX - x coordinate of the upper-left image pixel

minY - y coordinate of the upper-left image pixel

width - image width

height - image height

tileSampleModel - the SampleModel

DiskMemImage

public DiskMemImage(int minX,
                    int minY,
                    int width,
                    int height,
                    int tileGridXOffset,
                    int tileGridYOffset,
                    SampleModel tileSampleModel)

Creates a new image. Sets the ColorModel to null

Parameters:

minX - x coordinate of the upper-left image pixel

minY - y coordinate of the upper-left image pixel

width - image width

height - image height data type etc. for image tiles

tileGridXOffset - x coordinate of the upper-left pixel of the upper-left tile

tileGridYOffset - y coordinate of the upper-left pixel of the upper-left tile

tileSampleModel - the SampleModel

DiskMemImage

public DiskMemImage(int minX,
                    int minY,
                    int width,
                    int height,
                    int tileGridXOffset,
                    int tileGridYOffset,
                    SampleModel tileSampleModel,
                    ColorModel colorModel)

Creates a new image.

Parameters:

minX - x coordinate of the upper-left image pixel

minY - y coordinate of the upper-left image pixel

width - image width

height - image height data type etc. for image tiles

tileGridXOffset - x coordinate of the upper-left pixel of the upper-left tile

tileGridYOffset - y coordinate of the upper-left pixel of the upper-left tile

tileSampleModel - the SampleModel

colorModel - the ColorModel

Method Detail

getCommonTileCache

public static DiskMemTileCache getCommonTileCache()

Get the common tile cache. This method has the side effect of creating the common cache if it does not already exist (ie. it never returns null).

Returns:

the common tile cache

See Also:

isUsingCommonCache(), setUseCommonCache(boolean)

setCommonTileCache

public static void setCommonTileCache(DiskMemTileCache newCache)

Sets a new common cache. If a common cache has already been initialized (either with this method or via setUseCommonCache(boolean)) this method does nothing.

Parameters:

newCache - the cache instance to use as the common tile cache for DiskMemImage objects (null arguments are ignored)

getTile

public Raster getTile(int tileX,
                      int tileY)

Gets a tile for reading. Any changes to the tile's data will not be preserved by the cache.

Specified by:

getTile in interface RenderedImage

Specified by:

getTile in class javax.media.jai.PlanarImage

Parameters:

tileX - the tile's column in the tile grid

tileY - the tile's row in the tile grid

Returns:

the tile data for reading

addTileObserver

public void addTileObserver(TileObserver to)

Specified by:

addTileObserver in interface WritableRenderedImage

removeTileObserver

public void removeTileObserver(TileObserver to)

Specified by:

removeTileObserver in interface WritableRenderedImage

getWritableTile

public WritableRaster getWritableTile(int tileX,
                                      int tileY)

Checks out a tile for writing. The tile will be unavailable to other callers through this method until it is released via releaseWritableTile(int, int). If this method is called for the same time prior to the tile being released it returns null and a warning message is logged.

Specified by:

getWritableTile in interface WritableRenderedImage

Parameters:

tileX - tile X ordinate

tileY - tile Y ordinate

Returns:

the tile data for writing, or null if the tile is already checked-out

releaseWritableTile

public void releaseWritableTile(int tileX,
                                int tileY)

Releases a tile that was checked out for writing. The cache's disk copy of the tile's data will be refreshed.

If the cache no longer has the tile in its memory storage, e.g. because of memory swapping for other tile accesses, the cache will be unable to refresh the tile's data on disk. In this case a warning message is logged.

If the tile was not previously checked-out via getWritableTile(int, int) a warning message is logged.

Specified by:

releaseWritableTile in interface WritableRenderedImage

Parameters:

tileX - tile X ordinate

tileY - tile Y ordinate

isTileWritable

public boolean isTileWritable(int tileX,
                              int tileY)

Tests if a tile is currently checked-out for writing (via a call to getWritableTile(int, int).

Specified by:

isTileWritable in interface WritableRenderedImage

Parameters:

tileX - tile X ordinate

tileY - tile Y ordinate

Returns:

true if the tile is currently checked-out for writing; false otherwise.

getWritableTileIndices

public Point[] getWritableTileIndices()

Gets the indices (tile grid col,row) of tiles that are currently checked out for writing.

Specified by:

getWritableTileIndices in interface WritableRenderedImage

Returns:

tile indices

hasTileWriters

public boolean hasTileWriters()

Tests if any tiles are currently checked out for writing.

Specified by:

hasTileWriters in interface WritableRenderedImage

Returns:

true if any tiles are currently checked out; false otherwise

getSample

public int getSample(int x,
                     int y,
                     int b)
              throws PixelOutsideImageException

Gets the image value for the given image position as an integer.

Parameters:

x - X ordinate

y - Y ordinate

b - band index

Returns:

image value

Throws:

PixelOutsideImageException

getSampleFloat

public float getSampleFloat(int x,
                            int y,
                            int b)
                     throws PixelOutsideImageException

Gets the image value for the given image position as a float.

Parameters:

x - X ordinate

y - Y ordinate

b - band index

Returns:

image value

Throws:

PixelOutsideImageException

getSampleDouble

public double getSampleDouble(int x,
                              int y,
                              int b)
                       throws PixelOutsideImageException

Gets the image value for the given image position as a double.

Parameters:

x - X ordinate

y - Y ordinate

b - band index

Returns:

image value

Throws:

PixelOutsideImageException

setSample

public void setSample(int x,
                      int y,
                      int b,
                      int value)
               throws PixelOutsideImageException

Sets the image value for the given image position as an integer.

Parameters:

x - X ordinate

y - Y ordinate

b - band index

value - the new value

Throws:

PixelOutsideImageException

setSample

public void setSample(int x,
                      int y,
                      int b,
                      float value)
               throws PixelOutsideImageException

Sets the image value for the given image position as a float.

Parameters:

x - X ordinate

y - Y ordinate

b - band index

value - the new value

Throws:

PixelOutsideImageException

setSample

public void setSample(int x,
                      int y,
                      int b,
                      double value)
               throws PixelOutsideImageException

Sets the image value for the given image position as a double.

Parameters:

x - X ordinate

y - Y ordinate

b - band index

value - the new value

Throws:

PixelOutsideImageException

setData

public void setData(Raster data)

Copies data from the given Raster object into this image. The bounds of data will be used to place the data and only that portion of data within this image's bounds will be copied.

Specified by:

setData in interface WritableRenderedImage

Parameters:

data - the data to copy

Throws:

IllegalArgumentException - if data is null

createGraphics

public Graphics2D createGraphics()

Creates a Graphics2D object for drawing operations with this image. The graphics object will be an instance of DiskMemImageGraphics.

Note that only images of integral data type support graphics operations.

Returns:

a new Graphics2D object

Throws:

UnsupportedOperationException - if the image is not of integral data type

See Also:

DiskMemImageGraphics

getMemoryCapacity

public long getMemoryCapacity()

Gets the maximum amount of memory, in bytes, that this image will use for in-memory storage of its data. Since this class uses a DiskMemTileCache this is not the limit of image size.

Returns:

max memory usage

getTileMemorySize

public long getTileMemorySize()

Gets the amount of memory (bytes) required to store a single tile's data.

Returns:

tile memory size in bytes

setUseCommonCache

public void setUseCommonCache(boolean useCommon)

Sets whether this image will use the common tile cache. Any tiles belonging to this image that are already cached will be transferred from the image's current tile cache to the common cache (if useCommon is true) or to a new exclusive tile cache ((if useCommon is false).

By default, the image will use an exclusive cache.

Parameters:

useCommon - true to set this image to use the common tile cache; false for the image to use its own exclusive cache.

See Also:

getCommonTileCache(), isUsingCommonCache()

getTileCache

public DiskMemTileCache getTileCache()

Gets a reference to the DiskMemTileCache instance used by this image. This method is intended for client code that wishes to query cache state or receive cache diagnostic messages (via the Observer interface). It is probably not a good idea to manipulate the cache state directly.

Returns:

a live reference to the cache being used by this image

See Also:

isUsingCommonCache(), DiskMemTileCache

isUsingCommonCache

public boolean isUsingCommonCache()

Tests if this image is using the common tile cache.

Returns:

true if using the common tile cache; false otherwise

See Also:

setUseCommonCache(boolean)