javax.media.jai
Class PixelAccessor

java.lang.Object
  javax.media.jai.PixelAccessor

public final class PixelAccessor

extends Object

This is a utility class that may be used to access the pixel data stored in a RenderedImage's Rasters, as well as performing pixel-to-color data translation based on the image's SampleModel and ColorModel. It also provides several static methods to determine information about the image data.

This class is intended to help classes that need to access the pixel and/or color data of a RenderedImage, such as an OpImage, in an optimized fashion. Most of the variables defined in this class are public so that other classes may use them directly. However, the variables are also declared final so that other classes can not modify their values.

In general, the pixel data of a RenderedImage may be obtained by calling the getPixels() method. By definition, the pixel data of an image are the data described by the image's SampleModel and stored in the image's Rasters. No consideration of any kind is given to the image's ColorModel. If no error is found, the pixel data are returned in the primitive arrays of the type specified by the caller in an unpacked format, along with access information. Therefore, the specified data type must be one of the valid types defined in DataBuffer and large enough (in bit depth) to hold the pixel data of the image.

The pixel data of a binary image may be obtained in a packed format by calling the getPackedPixels() method. It returns the data in a packed byte array, with 8 pixels packed into 1 byte. The format of the data in the array is similar to the format described by the MultiPixelPackedSampleModel, where the end of each scanline is padded to the end of the byte if necessary. Note that this method returns a valid result only if and only if the image is a single-band bit image, that is, each pixel has only 1 sample with a sample size of 1 bit.

Two corresponding "set" methods are also provided for setting the computed pixel data back into the Raster's DataBuffer: setPixels() for unpacked data, and setPackedPixels() for packed data. It is very important that the caller uses the correct "set" method that matches the "get" method used to obtain the data, or errors will occur.

The color/alpha data of the RenderedImage may be obtained by calling the getComponents() method which returns the unnormalized data in the ColorSpace specified in the ColorModel, or the getComponentsRGB() method which returns the data scaled from 0 to 255 in the default sRGB ColorSpace. These methods retrieve the pixel data from the Raster, and perform the pixel-to-color translation. Therefore, in order for these two methods to return a valid result, the image must have a valid ColorModel.

Similarly, two "set" methods may be used to perform the color-to-pixel translation, and set the pixel data back to the Raster's DataBuffer. Again, it is important that the "get" and "set" methods are matched up correctly.

In addition, several static methods are included in this class for the convenience of OpImage developers, who may use them to help determine the appropriate destination SampleModel type.

Since:

JAI 1.1

Field Summary

int	bufferType The type of the DataBuffer's data array used to store the pixel data by the image's SampleModel.
ColorModel	colorModel The image's ColorModel.
int[]	componentSize The size, in number of bits, of all the color/alpha components.
int	componentType The type of the color/alpha components, determined based on the component size.
boolean	hasCompatibleCM Set to true if the image has a non-null ColorModel which is compatible with the image's SampleModel; false otherwise.
boolean	isComponentCM Set to true if the image has a ComponentColorModel; false otherwise.
boolean	isComponentSM true if the image has a ComponentSampleModel; false otherwise.
boolean	isIndexCM Set to true if the image has an IndexColorModel; false otherwise.
boolean	isMultiPixelPackedSM true if the image has a MultiPixelPackedSampleModel; false otherwise.
boolean	isPacked Set to true if the pixel data of this image may be packed into a byte array.
boolean	isPackedCM Set to true if the image has a PackedColorModel; false otherwise.
boolean	isSinglePixelPackedSM true if the image has a SinglePixelPackedSampleModel; false otherwise.
int	numBands The number of bands (samples) per pixel.
int	numComponents The total number of color/alpha components in the image's ColorModel.
SampleModel	sampleModel The image's SampleModel.
int[]	sampleSize The size, in number of bits, of all the pixel samples.
int	sampleType The data type of the pixel samples, determined based on the sample size.
int	transferType The type of the primitive array used to transfer the pixel data by the image's SampleModel.
static int	TYPE_BIT Tag for single-bit data type.

Constructor Summary

PixelAccessor(RenderedImage image)
Constructs a PixelAccessor from a RenderedImage.

PixelAccessor(SampleModel sm, ColorModel cm)
Constructs a PixelAccessor given a valid SampleModel and a (possibly null) ColorModel.

Method Summary

UnpackedImageData	getComponents(Raster raster, Rectangle rect, int type) Returns an array of unnormalized color/alpha components in the ColorSpace defined in the image's ColorModel.
UnpackedImageData	getComponentsRGB(Raster raster, Rectangle rect) Returns an array of color/alpha components scaled from 0 to 255 in the default sRGB ColorSpace.
static int	getDestNumBands(Vector sources) Returns the smallest number of bands of all the sources.
static int	getDestPixelType(Vector sources) Returns the largest data type of all the sources.
PackedImageData	getPackedPixels(Raster raster, Rectangle rect, boolean isDest, boolean coerceZeroOffset) Returns a region of the pixel data within a Raster in a packed byte array.
UnpackedImageData	getPixels(Raster raster, Rectangle rect, int type, boolean isDest) Returns a region of the pixel data within a Raster in an unpacked primitive array.
static int	getPixelType(SampleModel sm) Determines the pixel type based on the SampleModel.
static boolean	isPackedOperation(PixelAccessor[] srcs, PixelAccessor dst) Returns true if the destination and/or all the sources are single-bit, single-band images, and their pixel data may be packed into a byte array.
static boolean	isPackedOperation(PixelAccessor src, PixelAccessor dst) Returns true if the destination and the source are both single-bit, single-band images, and their pixel data may be packed into a byte array.
static boolean	isPackedOperation(PixelAccessor src1, PixelAccessor src2, PixelAccessor dst) Returns true if the destination and both sources are all single-bit, single-band images, and their pixel data may be packed into a byte array.
void	setComponents(UnpackedImageData uid) Given an array of unnormalized color/alpha components, this method performs color-to-pixel translation, and sets the translated pixel data back to the Raster within a specific region.
void	setComponentsRGB(UnpackedImageData uid) Given an array of normalized (between 0 and 255) alpha/RGB color components, this method performs color-to-pixel translation, and sets the translated pixel data back to the Raster within a specific region.
void	setPackedPixels(PackedImageData pid) Sets a region of the pixel data within a Raster using a primitive array.
void	setPixels(UnpackedImageData uid) Sets a region of the pixel data within a Raster using a primitive array.
void	setPixels(UnpackedImageData uid, boolean clamp) Sets a region of the pixel data within a Raster using a primitive array.

Methods inherited from class java.lang.Object

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

Field Detail

TYPE_BIT

public static final int TYPE_BIT

Tag for single-bit data type.

See Also:

Constant Field Values

sampleModel

public final SampleModel sampleModel

The image's SampleModel.

colorModel

public final ColorModel colorModel

The image's ColorModel.

isComponentSM

public final boolean isComponentSM

true if the image has a ComponentSampleModel; false otherwise.

isMultiPixelPackedSM

public final boolean isMultiPixelPackedSM

true if the image has a MultiPixelPackedSampleModel; false otherwise.

isSinglePixelPackedSM

public final boolean isSinglePixelPackedSM

true if the image has a SinglePixelPackedSampleModel; false otherwise.

sampleType

public final int sampleType

The data type of the pixel samples, determined based on the sample size.

bufferType

public final int bufferType

The type of the DataBuffer's data array used to store the pixel data by the image's SampleModel. This is the same value as that returned by SampleModel.getDataType().

transferType

public final int transferType

The type of the primitive array used to transfer the pixel data by the image's SampleModel. This is the same value as that returned by SampleModel.getTransferType().

numBands

public final int numBands

The number of bands (samples) per pixel. This is the same value as that returned by SampleModel.getNumBands().

sampleSize

public final int[] sampleSize

The size, in number of bits, of all the pixel samples. This is the same array as that returned by SampleModel.getSampleSize().

isPacked

public final boolean isPacked

Set to true if the pixel data of this image may be packed into a byte array. That is, each pixel has 1 sample (1 band) with a sample size of 1 bit. If this variable is true, getPackedPixels() should return a valid result, with 8 pixels packed into 1 byte.

hasCompatibleCM

public final boolean hasCompatibleCM

Set to true if the image has a non-null ColorModel which is compatible with the image's SampleModel; false otherwise.

isComponentCM

public final boolean isComponentCM

Set to true if the image has a ComponentColorModel; false otherwise.

isIndexCM

public final boolean isIndexCM

Set to true if the image has an IndexColorModel; false otherwise.

isPackedCM

public final boolean isPackedCM

Set to true if the image has a PackedColorModel; false otherwise.

componentType

public final int componentType

The type of the color/alpha components, determined based on the component size.

numComponents

public final int numComponents

The total number of color/alpha components in the image's ColorModel. This is the same value as that returned by ColorModel.getNumComponents().

componentSize

public final int[] componentSize

The size, in number of bits, of all the color/alpha components. This is the same array as that returned by ColorModel.getComponentSize().

Constructor Detail

PixelAccessor

public PixelAccessor(RenderedImage image)

Constructs a PixelAccessor from a RenderedImage. The RenderedImage must have a valid SampleModel, but may or may not have a valid ColorModel.

Parameters:

image - The image whose data are to be accessed.

Throws:

IllegalArgumentException - If image is null, or if the image does not have a valid SampleModel.

PixelAccessor

public PixelAccessor(SampleModel sm,
                     ColorModel cm)

Constructs a PixelAccessor given a valid SampleModel and a (possibly null) ColorModel.

Parameters:

sm - The SampleModel for the image to be accessed. Must be valid.

cm - The ColorModel for the image to be accessed. May be null.

Throws:

IllegalArgumentException - If sm is null.

Method Detail

getPixelType

public static int getPixelType(SampleModel sm)

Determines the pixel type based on the SampleModel. The pixel type signifies the data type for a PixelAccessor. For ComponentSampleModel, the pixel type is the same as the type of the DataBuffer used to store the pixel data. For all other types of SampleModel, the pixel type is determined based on the sample sizes.

Parameters:

sm - The SampleModel of the image.

Returns:

The pixel type for this sample model.

getDestPixelType

public static int getDestPixelType(Vector sources)

Returns the largest data type of all the sources. This method may be used to determine the pixel sample type of a destination in the default situation. It guarantees that the destination can store the resulting pixel values without losing any precision. The pixel type signifies the data type for a PixelAccessor.

If all the sources are single-bit images, this method returns TYPE_BIT (defined in this class) so that the destination does not use unnecessary memory for some operations. This includes all images whose SampleModel is single-banded and whose sample size is 1, regardless of the type of ColorModel the image may have. If an operation does not wish to deal with packed data, it should use TYPE_BYTE for pixel computation.

If there is no object in the source Vector, this method returns TYPE_UNDEFINED. All the objects in the source Vector must be RenderedImages.

When determining the result, only information from each image's SampleModel is used. No consideration is given to the image's ColorModel.

Parameters:

sources - A Vector of RenderedImage sources.

Returns:

The largest data type which can accomodate all sources.

Throws:

IllegalArgumentException - If sources is null.

ClassCastException - If any object in sources is not a RenderedImage.

getDestNumBands

public static int getDestNumBands(Vector sources)

Returns the smallest number of bands of all the sources. This method may be used to determine the number of bands a destination should have in the default situation. It guarantees that every destination band has a corresponding source band.

In general, if an operation has multiple sources, and some sources have 1 band and others have multiple bands, the single band may be applied to the multiple bands one at a time. (An example of this would be the MultiplyOpImage). Therefore, in such a case, this method returns the smallest band count among the multi-band sources.

If there is no object in the source Vector, this method returns 0. All the objects in the source Vector must be RenderedImages.

When determining the result, only information from each image's SampleModel are used. No consideration is given to the image's ColorModel.

Parameters:

sources - A Vector of RenderedImage sources.

Returns:

The minimum number of destination bands.

Throws:

IllegalArgumentException - If sources is null.

ClassCastException - If any object in sources is not a RenderedImage.

isPackedOperation

public static boolean isPackedOperation(PixelAccessor[] srcs,
                                        PixelAccessor dst)

Returns true if the destination and/or all the sources are single-bit, single-band images, and their pixel data may be packed into a byte array. If so, then the operations may be done in the packed format.

Parameters:

srcs - The array of source PixelAccesors.

dst - The destination PixelAccesor.

Returns:

true if a packed operation is possible.

isPackedOperation

public static boolean isPackedOperation(PixelAccessor src,
                                        PixelAccessor dst)

Returns true if the destination and the source are both single-bit, single-band images, and their pixel data may be packed into a byte array. If so, then the operations may be done in the packed format.

Parameters:

dst - The destination PixelAccesor.

Returns:

true if a packed operation is possible.

isPackedOperation

public static boolean isPackedOperation(PixelAccessor src1,
                                        PixelAccessor src2,
                                        PixelAccessor dst)

Returns true if the destination and both sources are all single-bit, single-band images, and their pixel data may be packed into a byte array. If so, then the operations may be done in the packed format.

Parameters:

src1 - The first source PixelAccesor.

src2 - The second source PixelAccesor.

dst - The destination PixelAccesor.

Returns:

true if a packed operation is possible.

getPixels

public UnpackedImageData getPixels(Raster raster,
                                   Rectangle rect,
                                   int type,
                                   boolean isDest)

Returns a region of the pixel data within a Raster in an unpacked primitive array. The returned data are retrieved from the Raster's DataBuffer; no pixel-to-color translation is performed.

The primitive array is of the type specified by the type argument. It must be one of the valid data types defined in DataBuffer and large (in bit depth) enough to hold the pixel samples, or an exception will be thrown. This means type should be greater than or equal to sampleType.

The Rectangle specifies the region of interest within which the pixel data are to be retrieved. It must be completely inside the Raster's boundary, or else this method throws an exception.

This method tries to avoid copying data as much as possible. If it is unable to reformat the pixel data in the way requested, or if the pixels do not have enough data to satisfy the request, this method throws an exception.

Parameters:

raster - The Raster that contains the pixel data.

rect - The region of interest within the Raster where the pixels are accessed.

type - The type of the primitive array used to return the pixel samples.

isDest - Indicates whether this Raster is a destination Raster. That is, its pixels have not been computed.

Returns:

The pixel data in an UnpackedImageData object.

Throws:

IllegalArgumentException - If type is not a valid data type defined in DataBuffer, or is not large enough to hold the pixel samples from the specified Raster.

IllegalArgumentException - If rect is not contained by the bounds of the specified Raster.

setPixels

public void setPixels(UnpackedImageData uid)

Sets a region of the pixel data within a Raster using a primitive array. This method copies data only if the set flag in UnpackedImageData is true. Performs clamping by default.

The UnpackedImageData should be obtained by calling the getPixels() method.

Parameters:

uid - The UnpackedImageData object to set.

Throws:

IllegalArgumentException - If the uid is null.

setPixels

public void setPixels(UnpackedImageData uid,
                      boolean clamp)

Sets a region of the pixel data within a Raster using a primitive array. This method only copies data only if the set flag in UnpackedImageData is true.

The UnpackedImageData should be obtained by calling the getPixels() method.

Parameters:

uid - The UnpackedImageData object to set.

clamp - A boolean set to true if clamping is to be performed.

Throws:

IllegalArgumentException - If the uid is null.

getPackedPixels

public PackedImageData getPackedPixels(Raster raster,
                                       Rectangle rect,
                                       boolean isDest,
                                       boolean coerceZeroOffset)

Returns a region of the pixel data within a Raster in a packed byte array. The returned data are retrieved from the Raster's DataBuffer; no pixel-to-color translation is performed.

This method only returns a valid result when the pixels are single-band and single-bit. All other types of data result in an exception. The data are packed in such a format that eight pixels are packed into one byte, and the end of each scanline is padded with zeros to the end of the byte.

In general, this method is called when operations are to be performed on the bit data in a packed format directly, to save memory usage. The static method isPackedOperation should be used to determine whether the destination and/or its sources are suitable for performing operations to a packed array.

The Rectangle specifies the region of interest within which the pixel data are to be retrieved. It must be completely inside the Raster's boundary, or this method will throw an exception.

Parameters:

raster - The Raster that contains the pixel data.

rect - The region of interest within the Raster where the pixels are accessed.

isDest - Indicates whether this Raster is a destination Raster. That is, its pixels have not been computed.

coerceZeroOffset - If true the returned PackedImageData will be forced to have a bitOffset and offset of zero and a lineStride of (rect.width+7)/8. The coercedZeroOffset field of the returned PackedImageData will be set to true.

Returns:

The PackedImageData with its data filled in.

Throws:

IllegalArgumentException - If data described by the Raster's SampleModel are not single-band and single-bit.

IllegalArgumentException - If rect is not within the bounds of the specified Raster.

setPackedPixels

public void setPackedPixels(PackedImageData pid)

Sets a region of the pixel data within a Raster using a primitive array. This method copies data only if the set flag in PackedImageData is true.

The PackedImageData should be obtained by calling the getPackedPixels() method.

Parameters:

pid - The PackedImageData object whose pixels are to be written.

Throws:

IllegalArgumentException - If the pid is null.

getComponents

public UnpackedImageData getComponents(Raster raster,
                                       Rectangle rect,
                                       int type)

Returns an array of unnormalized color/alpha components in the ColorSpace defined in the image's ColorModel. This method retrieves the pixel data within the specified rectangular region from the Raster, performs the pixel-to-color translation based on the image's ColorModel, and returns the components in the order specified by the ColorSpace.

In order for this method to return a valid result, the image must have a valid ColorModel that is compatible with the image's SampleModel. Further, the SampleModel and ColorModel must have the same transferType.

The component data are stored in a primitive array of the type specified by the type argument. It must be one of the valid data types defined in DataBuffer and large (in bit depth) enough to hold the color/alpha components, or an exception is thrown. This means type should be greater than or equal to componentType. To avoid extra array copy, it is best to use DataBuffer.TYPE_INT for this argument.

The Rectangle specifies the region of interest within which the pixel data are to be retrieved. It must be completely inside the Raster's boundary, or else this method throws an exception.

Parameters:

raster - The Raster that contains the pixel data.

rect - The region of interest within the Raster where the pixels are accessed.

type - The type of the primitive array used to return the color/alpha components with.

Returns:

The UnpackedImageData with its data filled in.

Throws:

IllegalArgumentException - If the image does not have a valid ColorModel that is compatible with its SampleModel.

IllegalArgumentException - If type is not a valid data type defined in DataBuffer, or is not large enough to hold the translated color/alpha components.

IllegalArgumentException - If rect is not contained by the bounds of the specified Raster.

setComponents

public void setComponents(UnpackedImageData uid)

Given an array of unnormalized color/alpha components, this method performs color-to-pixel translation, and sets the translated pixel data back to the Raster within a specific region. It is very important that the components array along with access information are obtained by calling the getComponents() method, or errors will occur.

In order for this method to return a valid result, the image must have a valid ColorModel that is compatible with the image's SampleModel. Further, the SampleModel and ColorModel must have the same transferType.

This method sets data only if the set flag in UnpackedImageData is true.

Parameters:

uid - The UnpackedImageData whose data is to be set.

Throws:

IllegalArgumentException - If the uid is null.

getComponentsRGB

public UnpackedImageData getComponentsRGB(Raster raster,
                                          Rectangle rect)

Returns an array of color/alpha components scaled from 0 to 255 in the default sRGB ColorSpace. This method retrieves the pixel data within the specified rectangular region from the Raster, performs the pixel-to-color translation based on the image's ColorModel, and returns the components in the order specified by the ColorSpace.

In order for this method to return a valid result, the image must have a valid ColorModel that is compatible with the image's SampleModel. Further, the SampleModel and ColorModel must have the same transferType.

The component data are stored in a two-dimensional, band-interleaved, byte array, because the components are always scaled from 0 to 255. Red is band 0, green is band 1, blue is band 2, and alpha is band 3.

The Rectangle specifies the region of interest within which the pixel data are to be retrieved. It must be completely inside the Raster's boundary, or this method will throw an exception.

Parameters:

raster - The Raster that contains the pixel data.

rect - The region of interest within the Raster where the pixels are accessed.

Returns:

The UnpackedImageData with its data filled in.

Throws:

IllegalArgumentException - If the image does not have a valid ColorModel that is compatible with its SampleModel.

IllegalArgumentException - If rect is not contained by the bounds of the specified Raster.

setComponentsRGB

public void setComponentsRGB(UnpackedImageData uid)

Given an array of normalized (between 0 and 255) alpha/RGB color components, this method performs color-to-pixel translation, and sets the translated pixel data back to the Raster within a specific region. It is very important that the components array along with access information are obtained by calling the getComponentsRGB() method, or errors will occur.

In order for this method to return a valid result, the image must have a valid ColorModel that is compatible with the image's SampleModel. Furthermore, the SampleModel and ColorModel must have the same transferType.

This method sets data only if the set flag in UnpackedImageData is true.

Parameters:

uid - The UnpackedImageData to set.

Throws:

IllegalArgumentException - If the uid is null.