DiskMemImage (Support and utility classes 1.6.0 API)

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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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)

Class DiskMemImage

Field Summary

Fields inherited from class javax.media.jai.PlanarImage

Constructor Summary

Method Summary

Methods inherited from class javax.media.jai.PlanarImage

Methods inherited from class java.lang.Object

Methods inherited from interface java.awt.image.RenderedImage

Field Detail

DEFAULT_COMMON_CACHE_SIZE

tileCache

tileGrid

numWriters

numTilesInUse

tileMemorySize

tileObservers

Constructor Detail

DiskMemImage

DiskMemImage

DiskMemImage

DiskMemImage

DiskMemImage

Method Detail

getCommonTileCache

setCommonTileCache

getTile

addTileObserver

removeTileObserver

getWritableTile

releaseWritableTile

isTileWritable

getWritableTileIndices

hasTileWriters

getSample

getSampleFloat

getSampleDouble

setSample

setSample

setSample

setData

createGraphics

getMemoryCapacity

getTileMemorySize

setUseCommonCache

getTileCache

isUsingCommonCache