javax.media.jai
Class RasterAccessor

java.lang.Object
  |
  +--javax.media.jai.RasterAccessor

public class RasterAccessor

extends Object

An adapter class for presenting non-binary image data in a ComponentSampleModel format and binary image data in a zero-offset byte array format even when the original data are not so stored. RasterAccessor is meant to make the common (ComponentSampleModel) case fast and other formats possible without forcing the OpImage writer to cover more than one case per non-binary data type.

When constructing a RasterAccessor with a source(s) that has an IndexColorModel and a destination that has a non-IndexColorModel, RasterAccessor will perform expansion of the source pixels. If the source(s) and the destination have an IndexColorModel, then RasterAccessor will assume that the operation can correctly process an IndexColorModel source and will not expand the source pixels (colormap indices) into color components. Refer to JAI.KEY_REPLACE_INDEX_COLOR_MODEL for a mechanism by which the destination image's ColorModel is set to a non-IndexColorModel to cause RasterAccessor to expand the source's IndexColorModel.

Binary data are handled as a special case. In general image data are considered to be binary when the image has a single-banded MultiPixelPackedSampleModel with one bit per pixel. This may be verified by invoking the isBinary() method. For this case the methods getBinaryDataArray() and copyBinaryDataToRaster() should be used to access and set, respectively, the binary data in packed form. If the binary data are to be accessed in expanded form, i.e., as bytes, then the usual byte methods getByteDataArray(), getByteDataArrays(), and copyDataToRaster() should be used.

Field Summary

protected int[]	bandDataOffsets The bandOffset + subRasterOffset + DataBufferOffset into each of the numBand data arrays
protected int[]	bandOffsets Offset from a pixel's offset to a band of that pixel
protected byte[]	binaryDataArray The image data for the binary case.
protected byte[][]	byteDataArrays The image data in a two-dimensional byte array.
static int	COPIED Flag indicating data is a copy of the raster's data.
static int	COPY_MASK The bits of a FormatTag associated with how dataArrays are obtained.
static int	DATATYPE_MASK The bits of a FormatTagID associated with pixel datatype.
static int	DEFAULTEXPANSION Flag indicating ColorModel data should be used only in copied case
protected double[][]	doubleDataArrays The image data in a two-dimensional double array.
static int	EXPANDED Flag indicating ColorModel data should be interpreted.
static int	EXPANSION_MASK The bits of a FormatTag associated with how ColorModels are used.
protected float[][]	floatDataArrays The image data in a two-dimensional float array.
protected int	formatTagID Tag indicating the data type of the data and whether it's copied
protected int[][]	intDataArrays The image data in a two-dimensional int array.
protected int	numBands The number of bands per pixel in the data array.
protected int	pixelStride The pixel stride of the image data in each data array
protected Raster	raster The raster that is the source of pixel data.
protected int	rectHeight The height of the rectangle this RasterAccessor addresses.
protected int	rectWidth The width of the rectangle this RasterAccessor addresses.
protected int	rectX The x coordinate of upper-left corner of the rectangle this RasterAccessor addresses.
protected int	rectY The y coordinate of upper-left corner of the rectangle this RasterAccessor addresses.
protected int	scanlineStride The scanline stride of the image data in each data array
protected short[][]	shortDataArrays The image data in a two-dimensional short array.
static int	TAG_BYTE_EXPANDED FormatTagID indicating data in byte arrays and expanded.
static int	TAG_BYTE_UNCOPIED FormatTagID indicating data in byte arrays and uncopied.
static int	TAG_DOUBLE_COPIED FormatTagID indicating data in double arrays and copied.
static int	TAG_DOUBLE_UNCOPIED FormatTagID indicating data in double arrays and uncopied.
static int	TAG_FLOAT_COPIED FormatTagID indicating data in float arrays and copied.
static int	TAG_FLOAT_UNCOPIED FormatTagID indicating data in float arrays and uncopied.
static int	TAG_INT_COPIED FormatTagID indicating data in int arrays and copied.
static int	TAG_INT_UNCOPIED FormatTagID indicating data in int arrays and uncopied.
static int	TAG_SHORT_UNCOPIED FormatTagID indicating data in short arrays and uncopied.
static int	TAG_USHORT_UNCOPIED FormatTagID indicating data in unsigned short arrays and uncopied.
static int	UNCOPIED Flag indicating data is raster's data.
static int	UNEXPANDED Flag indicating ColorModel info should be ignored

Constructor Summary

RasterAccessor(Raster raster, Rectangle rect, RasterFormatTag rft, ColorModel theColorModel)
Constructs a RasterAccessor object out of a Raster, Rectangle and formatTagID returned from RasterFormat.findCompatibleTag().

Method Summary

void	clampDataArrays() Clamps data array values to a range that the underlying raster can deal with.
void	copyBinaryDataToRaster() For the case of binary data (isBinary() returns true), copy the binary data back into the Raster of the RasterAccessor.
void	copyDataToRaster() Copies data back into the RasterAccessor's raster.
static int	findCompatibleTag(SampleModel[] srcSampleModels, SampleModel dstSampleModel) Returns the most efficient FormatTagID that is compatible with the destination SampleModel and all source SampleModels.
static RasterFormatTag[]	findCompatibleTags(RenderedImage[] srcs, RenderedImage dst) Finds the appropriate tags for the constructor, based on the SampleModel and ColorModel of all the source and destination.
int	getBandOffset(int b) Returns the offset of a specific band's first sample into the DataBuffer including the DataBuffer's offset.
int[]	getBandOffsets() Returns the bandDataOffsets into the dataArrays.
byte[]	getBinaryDataArray() For the case of binary data (isBinary() returns true), return the binary data as a packed byte array.
byte[]	getByteDataArray(int b) Returns the image data as a byte array for a specific band.
byte[][]	getByteDataArrays() Returns the image data as a byte array.
Object	getDataArray(int b) Returns the image data as an Object for a specific band.
int	getDataType() Returns the data type of the RasterAccessor object.
double[]	getDoubleDataArray(int b) Returns the image data as a double array for a specific band.
double[][]	getDoubleDataArrays() Returns the image data as a double array.
float[]	getFloatDataArray(int b) Returns the image data as a float array for a specific band.
float[][]	getFloatDataArrays() Returns the image data as a float array.
int	getHeight() Returns the height of the RasterAccessor's accessible area.
int[]	getIntDataArray(int b) Returns the image data as an int array for a specific band.
int[][]	getIntDataArrays() Returns the image data as an int array.
int	getNumBands() Returns the numBands of the presented area.
int	getOffsetForBand(int b) Returns the offset of a specified band's sample from any pixel offset.
int[]	getOffsetsForBands() Returns the offset of all band's samples from any pixel offset.
int	getPixelStride() Returns the pixelStride for the image data.
int	getScanlineStride() Returns the scanlineStride for the image data.
short[]	getShortDataArray(int b) Returns the image data as a short array for a specific band.
short[][]	getShortDataArrays() Returns the image data as a short array.
int	getWidth() Returns the width of the RasterAccessor's accessible area.
int	getX() Returns the x coordinate of the upper-left corner of the RasterAccessor's accessible area.
int	getY() Returns the y coordinate of the upper-left corner of the RasterAccessor's accessible area.
boolean	isBinary() Whether the RasterAccessor represents binary data.
boolean	isDataCopy() Returns true if the RasterAccessors's data is copied from it's raster.
boolean	needsClamping() Indicates if the RasterAccessor has a larger dynamic range than the underlying Raster.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COPY_MASK

public static final int COPY_MASK

The bits of a FormatTag associated with how dataArrays are obtained.

UNCOPIED

public static final int UNCOPIED

Flag indicating data is raster's data.

COPIED

public static final int COPIED

Flag indicating data is a copy of the raster's data.

EXPANSION_MASK

public static final int EXPANSION_MASK

The bits of a FormatTag associated with how ColorModels are used.

DEFAULTEXPANSION

public static final int DEFAULTEXPANSION

Flag indicating ColorModel data should be used only in copied case

EXPANDED

public static final int EXPANDED

Flag indicating ColorModel data should be interpreted.

UNEXPANDED

public static final int UNEXPANDED

Flag indicating ColorModel info should be ignored

DATATYPE_MASK

public static final int DATATYPE_MASK

The bits of a FormatTagID associated with pixel datatype.

TAG_BYTE_UNCOPIED

public static final int TAG_BYTE_UNCOPIED

FormatTagID indicating data in byte arrays and uncopied.

TAG_USHORT_UNCOPIED

public static final int TAG_USHORT_UNCOPIED

FormatTagID indicating data in unsigned short arrays and uncopied.

TAG_SHORT_UNCOPIED

public static final int TAG_SHORT_UNCOPIED

FormatTagID indicating data in short arrays and uncopied.

TAG_INT_UNCOPIED

public static final int TAG_INT_UNCOPIED

FormatTagID indicating data in int arrays and uncopied.

TAG_FLOAT_UNCOPIED

public static final int TAG_FLOAT_UNCOPIED

FormatTagID indicating data in float arrays and uncopied.

TAG_DOUBLE_UNCOPIED

public static final int TAG_DOUBLE_UNCOPIED

FormatTagID indicating data in double arrays and uncopied.

TAG_INT_COPIED

public static final int TAG_INT_COPIED

FormatTagID indicating data in int arrays and copied.

TAG_FLOAT_COPIED

public static final int TAG_FLOAT_COPIED

FormatTagID indicating data in float arrays and copied.

TAG_DOUBLE_COPIED

public static final int TAG_DOUBLE_COPIED

FormatTagID indicating data in double arrays and copied.

TAG_BYTE_EXPANDED

public static final int TAG_BYTE_EXPANDED

FormatTagID indicating data in byte arrays and expanded.

raster

protected Raster raster

The raster that is the source of pixel data.

rectWidth

protected int rectWidth

The width of the rectangle this RasterAccessor addresses.

rectHeight

protected int rectHeight

The height of the rectangle this RasterAccessor addresses.

rectX

protected int rectX

The x coordinate of upper-left corner of the rectangle this RasterAccessor addresses.

rectY

protected int rectY

The y coordinate of upper-left corner of the rectangle this RasterAccessor addresses.

formatTagID

protected int formatTagID

Tag indicating the data type of the data and whether it's copied

binaryDataArray

protected byte[] binaryDataArray

The image data for the binary case. The data will be packed as eight bits per byte with no bit offset, i.e., the first bit in each image line will be the left-most bit of the first byte of the line. The line stride in bytes will be (int)((rectWidth+7)/8). The length of the array will be rectHeight multiplied by the line stride.

Since:

JAI 1.1

byteDataArrays

protected byte[][] byteDataArrays

The image data in a two-dimensional byte array. This value will be non-null only if getDataType() returns DataBuffer.TYPE_BYTE. byteDataArrays.length will equal numBands. Note that often the numBands subArrays will all point to the same place in memory.

For the case of binary data this variable will not be initialized until getByteDataArrays() or getByteDataArray(int b) is invoked.

shortDataArrays

protected short[][] shortDataArrays

The image data in a two-dimensional short array. This value will be non-null only if getDataType() returns DataBuffer.TYPE_USHORT or DataBuffer.TYPE_SHORT. shortDataArrays.length will equal numBands. Note that often the numBands subArrays will all point to the same place in memory.

intDataArrays

protected int[][] intDataArrays

The image data in a two-dimensional int array. This value will be non-null only if getDataType() returns DataBuffer.TYPE_INT. intDataArrays.length will equal numBands. Note that often the numBands subArrays will all point to the same place in memory.

floatDataArrays

protected float[][] floatDataArrays

The image data in a two-dimensional float array. This value will be non-null only if getDataType() returns DataBuffer.TYPE_FLOAT. floatDataArrays.length will equal numBands. Note that often the numBand subArrays will all point to the same place in memory.

doubleDataArrays

protected double[][] doubleDataArrays

The image data in a two-dimensional double array. This value will be non-null only if getDataType() returns DataBuffer.TYPE_DOUBLE. doubleDataArrays.length will equal numBands. Note that often the numBand subArrays will all point to the same place in memory.

bandDataOffsets

protected int[] bandDataOffsets

The bandOffset + subRasterOffset + DataBufferOffset into each of the numBand data arrays

bandOffsets

protected int[] bandOffsets

Offset from a pixel's offset to a band of that pixel

numBands

protected int numBands

The number of bands per pixel in the data array.

scanlineStride

protected int scanlineStride

The scanline stride of the image data in each data array

pixelStride

protected int pixelStride

The pixel stride of the image data in each data array

Constructor Detail

RasterAccessor

public RasterAccessor(Raster raster,
                      Rectangle rect,
                      RasterFormatTag rft,
                      ColorModel theColorModel)

Constructs a RasterAccessor object out of a Raster, Rectangle and formatTagID returned from RasterFormat.findCompatibleTag().

The RasterFormatTag must agree with the raster's SampleModel and ColorModel. It is best to obtain the correct tag using the findCompatibleTags static method.

Parameters:

raster - The raster to be accessed

rect - A Rectangle from the raster to be accessed

rft - The RasterFormatTag associated with the Raster

theColorModel - The ColorModel for color components

Throws:

ClassCastException - if the data type of RasterFormatTag does not agree with the actual data type of the Raster.

IllegalArgumentException - if raster, rect, or rft is null.

IllegalArgumentException - if the Rectangle is not contained within Raster's bounds.

Method Detail

findCompatibleTags

public static RasterFormatTag[] findCompatibleTags(RenderedImage[] srcs,
                                                   RenderedImage dst)

Finds the appropriate tags for the constructor, based on the SampleModel and ColorModel of all the source and destination.

Parameters:

srcs - The operations sources; may be null which is taken to be equivalent to zero sources.

dst - The operation destination.

Returns:

An array containing RasterFormatTags for the sources in the first src.length elements and a RasterFormatTag for the destination in the last element.

Throws:

NullPointerException - if dst is null.

findCompatibleTag

public static int findCompatibleTag(SampleModel[] srcSampleModels,
                                    SampleModel dstSampleModel)

Returns the most efficient FormatTagID that is compatible with the destination SampleModel and all source SampleModels. Since there is no ColorModel associated with a SampleModel, this method does not expand the data buffer as it has no access to the Raster's ColorModel.

getX

public int getX()

Returns the x coordinate of the upper-left corner of the RasterAccessor's accessible area.

getY

public int getY()

Returns the y coordinate of the upper-left corner of the RasterAccessor's accessible area.

getWidth

public int getWidth()

Returns the width of the RasterAccessor's accessible area.

getHeight

public int getHeight()

Returns the height of the RasterAccessor's accessible area.

getNumBands

public int getNumBands()

Returns the numBands of the presented area.

isBinary

public boolean isBinary()

Whether the RasterAccessor represents binary data. This occurs when the Raster has a MultiPixelPackedSampleModel with a single band and one bit per pixel.

Since:

JAI 1.1

getBinaryDataArray

public byte[] getBinaryDataArray()

For the case of binary data (isBinary() returns true), return the binary data as a packed byte array. The data will be packed as eight bits per byte with no bit offset, i.e., the first bit in each image line will be the left-most of the first byte of the line. The line stride in bytes will be (int)((getWidth()+7)/8). The length of the returned array will be the line stride multiplied by getHeight()

Returns:

the binary data as a packed array of bytes with zero offset of null if the data are not binary.

Since:

JAI 1.1

getByteDataArrays

public byte[][] getByteDataArrays()

Returns the image data as a byte array. Non-null only if getDataType = DataBuffer.TYPE_BYTE.

For the case of binary data the corresponding instance variable byteDataArrays will not be initialized until this method or getByteDataArray(int b) is invoked. The binary data will be returned as bytes with value 0 or 1.

getByteDataArray

public byte[] getByteDataArray(int b)

Returns the image data as a byte array for a specific band. Non-null only if getDataType = DataBuffer.TYPE_BYTE.

getShortDataArrays

public short[][] getShortDataArrays()

Returns the image data as a short array. Non-null only if getDataType = DataBuffer.TYPE_USHORT or DataBuffer.TYPE_SHORT.

getShortDataArray

public short[] getShortDataArray(int b)

Returns the image data as a short array for a specific band. Non-null only if getDataType = DataBuffer.TYPE_USHORT or DataBuffer.TYPE_SHORT.

getIntDataArrays

public int[][] getIntDataArrays()

Returns the image data as an int array. Non-null only if getDataType = DataBuffer.TYPE_INT.

getIntDataArray

public int[] getIntDataArray(int b)

Returns the image data as an int array for a specific band. Non-null only if getDataType = DataBuffer.TYPE_INT.

getFloatDataArrays

public float[][] getFloatDataArrays()

Returns the image data as a float array. Non-null only if getDataType = DataBuffer.TYPE_FLOAT.

getFloatDataArray

public float[] getFloatDataArray(int b)

Returns the image data as a float array for a specific band. Non-null only if getDataType = DataBuffer.TYPE_FLOAT.

getDoubleDataArrays

public double[][] getDoubleDataArrays()

Returns the image data as a double array. Non-null only if getDataType = DataBuffer.TYPE_DOUBLE

getDoubleDataArray

public double[] getDoubleDataArray(int b)

Returns the image data as a double array for a specific band. Non-null only if getDataType = DataBuffer.TYPE_DOUBLE

getDataArray

public Object getDataArray(int b)

Returns the image data as an Object for a specific band.

Parameters:

b - The index of the image band of interest.

getBandOffsets

public int[] getBandOffsets()

Returns the bandDataOffsets into the dataArrays.

getOffsetsForBands

public int[] getOffsetsForBands()

Returns the offset of all band's samples from any pixel offset.

getBandOffset

public int getBandOffset(int b)

Returns the offset of a specific band's first sample into the DataBuffer including the DataBuffer's offset.

getOffsetForBand

public int getOffsetForBand(int b)

Returns the offset of a specified band's sample from any pixel offset.

getScanlineStride

public int getScanlineStride()

Returns the scanlineStride for the image data.

For binary data this stride is applies to the arrays returned by getByteDataArray() and getByteDataArrays() if the data are accessed as bytes; it does not apply to the array returned by getBinaryDataArray() when the data are accessed as bits packed into bytes.

getPixelStride

public int getPixelStride()

Returns the pixelStride for the image data.

getDataType

public int getDataType()

Returns the data type of the RasterAccessor object. Note that this datatype is not necessarily the same data type as the underlying raster.

isDataCopy

public boolean isDataCopy()

Returns true if the RasterAccessors's data is copied from it's raster.

copyBinaryDataToRaster

public void copyBinaryDataToRaster()

For the case of binary data (isBinary() returns true), copy the binary data back into the Raster of the RasterAccessor. If this method is invoked in the non-binary case it does nothing. Any bit offset in the original SampleModel will be accounted for.

Since:

JAI 1.1

copyDataToRaster

public void copyDataToRaster()

Copies data back into the RasterAccessor's raster. Note that the data is cast from the intermediate data format to the raster's format. If clamping is needed, the call clampDataArrays() method needs to be called before calling the copyDataToRaster() method. Note: the raster is expected to be writable - typically a destination raster - otherwise, a run-time exception will occur.

If the data are binary, then the target bit will be set if and only if the corresponding byte is non-zero.

needsClamping

public boolean needsClamping()

Indicates if the RasterAccessor has a larger dynamic range than the underlying Raster. Except in special cases, where the op knows something special, this call will determine whether or not clampDataArrays() needs to be called.

clampDataArrays

public void clampDataArrays()

Clamps data array values to a range that the underlying raster can deal with. For example, if the underlying raster stores data as bytes, but the samples are unpacked into integer arrays by the RasterAccessor for an operation, the operation will need to call clampDataArrays() so that the data in the int arrays is restricted to the range 0..255 before a setPixels() call is made on the underlying raster. Note that some operations (for example, lookup) can guarantee that their results don't need clamping so they can call RasterAccessor.copyDataToRaster() without first calling this function.