org.jaitools.tiledimage
Class DiskMemImage

java.lang.Object
  extended by javax.media.jai.PlanarImage
      extended by 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)


Copyright © 2009-2013. All Rights Reserved.