Chapter 18. The java.awt.image Package

AffineTransformOp	Java 1.2
java.awt.image

This class is a BufferedImageOp and a RasterOp that performs an arbitrary java.awt.geom.AffineTransform on a BufferedImage or Raster. To create an AffineTransformOp, you must specify the desired AffineTransform and the interpolation mode to use when interpolation is necessary to determine the pixel or color values of the destination. TYPE_NEAREST_NEIGHBOR is the quicker form of interpolation, but TYPE_BILINEAR produces better results. You may also specify the type of interpolation to use by specifying a java.awt.RenderingHints object that contains an interpolation hint.

To use an AffineTransformOp, simply pass a BufferedImage or Raster to the filter() method. Note that for this operation the destination image or raster cannot be the same as the source image or raster. See BufferedImageOp for further details.

Hierarchy: Object-->AffineTransformOp(BufferedImageOp,RasterOp)

AreaAveragingScaleFilter	Java 1.1
java.awt.image	cloneable PJ1.1

This class implements an ImageFilter that scales an image to a specified pixel size. It uses a scaling algorithm that averages adjacent pixel values when shrinking an image, which produces relatively smooth scaled images. Its superclass, ReplicateScaleFilter, implements a faster, less smooth scaling algorithm. The easiest way to use this filter is to call the getScaledInstance() method of java.awt.Image, specifying an appropriate hint constant.

The methods of this class are ImageConsumer methods intended for communication between the image filter and the FilteredImageSource that uses it. Applications do not usually call these methods directly.

Hierarchy: Object-->ImageFilter(Cloneable,ImageConsumer)-->ReplicateScaleFilter-->AreaAveragingScaleFilter

BandCombineOp	Java 1.2
java.awt.image

This RasterOp allows the bands of image data in a Raster to be arbitrarily combined using a matrix. For example, you can use a BandCombineOp to convert three bands of color image data to a single band of grayscale image data. The number of columns of the matrix should be equal to the number of bands in the source raster or the number of bands plus one, if you are adding constant values as part of the combination. The number of rows in the matrix should be equal to the number of bands in the destination Raster.

As an example, consider the following matrix with four columns and three rows, used to convert a Raster with three bands to another three-banded raster: This matrix is used to convert the source bands s1, s2, and s3 into destination bands d1, d2, and d3, using the following formulas:

d1 = s1*m11 + s2*m21 + s3*m31 + c1;
d2 = s1*m12 + s2*m22 + s3*m32 + c2;
d3 = s1*m13 + s2*m23 + s3*m33 + c3;

If the constants c1, c2, and c3 are all 0, they can be omitted from the vector.

After creating a BandCombineOp for a specified vector, you perform the operation by passing a source and optional destination Raster to the filter() method. Because this operation processes each pixel independently, you can specify the same Raster object as both source and destination. BandCombineOp does not implement BufferedImageOp and cannot be used to process BufferedImage objects. See RasterOp for further details.

Hierarchy: Object-->BandCombineOp(RasterOp)

BandedSampleModel	Java 1.2
java.awt.image

This SampleModel represents image data stored so that each color component is in a separate data element of a DataBuffer and each band of color components is in a separate bank of the DataBuffer. For example, it can be used to represent RGB colors stored in three separate banks of short values. Most applications never need to use this class. See SampleModel for further information.

Hierarchy: Object-->SampleModel-->ComponentSampleModel-->BandedSampleModel

BufferedImage	Java 1.2
java.awt.image

This is the central class in the simplified, immediate-mode imaging API introduced in Java 1.2 as part of Java 2D. A BufferedImage represents an image as a rectangular array of pixels in a Raster object and a ColorModel object that is capable of interpreting the pixel values of the Raster. BufferedImage extends java.awt.Image and can therefore be used anywhere that an Image can. However, a BufferedImage always holds its image data in memory, so there is no need for the complicated ImageObserver interface to handle asynchronous notifications as image data loads over a network.

If you know the data format of the image you need, you can create a BufferedImage by calling the BufferedImage() constructor. For example, to create an off-screen image with an alpha channel for use in complex color compositing operations, you can call BufferedImage() with the desired image size and an image type of TYPE_INT_ARGB. If you want to create an off-screen image and you do not need an alpha channel, it is easier to simply call the createImage() method of a java.awt.Component. Although this method is declared to return an Image, in Java 1.2 it is guaranteed to return a BufferedImage. The advantage to using this method is that it creates a BufferedImage with a type that is the same as (or can be efficiently converted to) the type used on your screen. If you do not have a Component handy, you can achieve the same effect by calling the createCompatibleImage() method of the java.awt.GraphicsConfiguration object that represents your screen configuration.

Once you have created a BufferedImage, you can call createGraphics() to obtain a Graphics2D object that you can use to draw into the image. You can draw a BufferedImage onto the screen or into any other image, using any of the drawImage() methods of Graphics or Graphics2D. You can perform image processing on a BufferedImage by passing it to the filter() method of any BufferedImageOp object. Finally, you can query and set individual pixels (or blocks of pixels) in a BufferedImage with getRGB() and setRGB(). These methods use the default ARGB color model: each pixel contains 8 bits of alpha, red, green, and blue data.

BufferedImage implements WritableRenderedImage, which in turn implements RenderedImage. These interfaces are used primarily by the forthcoming Java Advanced Imaging (JAI) API (javax.jai.*). Their methods allow an image to be divided up into multiple rectangular tiles. The BufferedImage class defines each image as a single tile, so most of these methods have trivial implementations. Most applications can simply ignore the RenderedImage and WritableRenderedImage methods of this class.

Hierarchy: Object-->Image-->BufferedImage(WritableRenderedImage(RenderedImage))

Passed To: Too many methods to list.

Returned By: Too many methods to list.

BufferedImageFilter	Java 1.2
java.awt.image	cloneable

This class allows a Java 1.2 BufferedImageOp image-processing operation to be used as an ImageFilter in the Java 1.0 and Java 1.1 image processing model. Create a BufferedImageFilter by passing a BufferedImageOp to the constructor. Then use the resulting BufferedImageFilter with a FilteredImageSource exactly as you would use RGBImageFilter, CropImageFilter, or any other Java 1.0 or Java 1.1 image filter.

Hierarchy: Object-->ImageFilter(Cloneable,ImageConsumer)-->BufferedImageFilter(Cloneable)

BufferedImageOp	Java 1.2
java.awt.image

This interface describes an image-processing operation that can be performed on any BufferedImage. Java 2D includes a number of versatile implementations of this interface that most applications can rely for all their image-processing needs.

To use a BufferedImageOp, call its filter() method. This method processes a specified source image and stores the results in a specified destination image. If no destination image is specified, the method creates and returns an appropriate one. You can pass a source image to getBounds2D() to get the bounding box of the destination image that would be produced if that source image were to be passed to filter(). Given a point in a (hypothetical) source image, getPoint2D() returns the corresponding point in the destination image. If a destination Point2D object is provided, it is used to return the destination point; otherwise a Point2D object is allocated for this purpose. getRenderingHints() returns the rendering hints associated with this implementation of BufferedImageOp, or null if it has no rendering hints. Finally, createCompatibleDestImage() is an internal method that implementations must define but that applications never need to call.

Implementations: AffineTransformOp, ColorConvertOp, ConvolveOp, LookupOp, RescaleOp

Passed To: Graphics2D.drawImage(), BufferedImageFilter.BufferedImageFilter()

Returned By: BufferedImageFilter.getBufferedImageOp()

ByteLookupTable	Java 1.2
java.awt.image

This concrete subclass of LookupTable contains one or more byte arrays that serve as lookup tables for a LookupOp image-processing operation. Applications never need to use a ByteLookupTable directly; they need to create one only to pass to the LookupOp() constructor. Create a ByteLookupTable by passing the byte array or arrays to the ByteLookupTable() constructor, along with an offset that is subtracted from each source color component before the lookup is performed. See also LookupTable.

Hierarchy: Object-->LookupTable-->ByteLookupTable

ColorConvertOp	Java 1.2
java.awt.image

This class is a BufferedImageOp and a RasterOp that converts the colors of a BufferedImage or a Raster from one color space to another color space. If the filter() method is called with two distinct source and destination BufferedImage objects specified, it converts the colors from the java.awt.color.ColorSpace of the source image to the ColorSpace of the destination image. If no destination image is passed to filter(), the destination ColorSpace must have been specified when the ColorConvertOp() constructor was called. Finally, if this ColorConvertOp is to be used to filter Raster object, both the source and destination color spaces must be specified, either in the form of ColorSpace objects or as an array of two java.awt.color.ICC_PROFILE objects.

In addition to optionally specifying the source and destination color spaces when you invoke the ColorConvertOp() constructor, you may also specify a RenderingHints object. If the hints object is non-null, the ColorConvertOp may use the color rendering and dithering hints it contains.

To use a ColorConvertOp, simply pass a source and optional destination image or raster to the filter() method. Because the ColorConvertOp works on each pixel of the image or raster independently, you may specify the same object for both source and destination. In this case, the image or raster is modified in place. See BufferedImageOp for further details.

Hierarchy: Object-->ColorConvertOp(BufferedImageOp,RasterOp)

ColorModel	Java 1.0
java.awt.image	PJ1.1

This abstract class defines a scheme for representing colors as pixels. The primary job of a ColorModel object is to extract individual color components from pixel values. Most applications do not need to work with ColorModel objects directly; those that do usually need only to instantiate an appropriate ColorModel subclass for use by some other method or constructor.

In Java 1.0 and 1.1, this is a fairly simple class: pixel values are supplied as int values, and the getRed(), getGreen(), getBlue(), and getAlpha() methods return the red, green, blue, and alpha components of the pixel. The getRGB() method converts a pixel to the pixel format used by the default ARGB color model. This color model is returned by the static getRGBDefault() method; it packs 8-bit color and alpha components into a 32-bit int in 0xAARRGGBB format.

With the introduction of Java 2D in Java 1.2, this class has become more complicated. Now the ColorModel is not tied to the default RGB java.awt.color.ColorSpace and provides methods for extracting color components from any color space. The getComponents() method and its variants return an array of color components for a given pixel value. If the ColorModel is defined in terms of the CMYK color space, for example, these components are not red, green, and blue, but cyan, magenta, yellow, and black. Note, however, that because every ColorSpace can convert colors to the default RGB color space, the getRed(), getGreen(), getBlue(), and getRGB() methods still work, regardless of color space.

Another generalization to the ColorModel class in Java 1.2 is that pixel values are no longer assumed to fit in int values. Each method that extracts color components from pixels comes in two forms. In the first, the pixel value is specified as an int. In the second form, it is specified as a Object. This object is an array of primitive values. The type of these values is known as the transfer type of the color model and is specified by one of the constants DataBuffer.TYPE_BYTE, Databuffer.TYPE_USHORT, or DataBuffer.TYPE_INT. In simple cases, the elements of the transfer type arrays contain color components, and the ColorModel object provides a trivial mapping between pixel values and color component values.

Other ColorModel additions in Java 1.2 include the implementation of the Transparency interface and its getTransparency() method. This method returns a Transparency constant that specifies the level of transparency supported by the ColorModel. For ColorModel objects that support transparency, the isAlphaPremultiplied() method specifies whether the color components have been premultiplied by the alpha component. (Premultiplication makes alpha compositing operations more efficient.) Also, the getNormalizedComponents() and getUnnormalizedComponents() convert back and forth between normalized and unnormalized color component values. A normalized component is a float value between 0.0 and 1.0 that has not been premultiplied by an alpha value. An unnormalized component is an integral value with a range that depends on the number of bits used by the color model, possibly premultiplied by the alpha value.

There are a number of ColorModel subclasses, suitable for distinctly different types of color models. See also ComponentColorModel, DirectColorModel, IndexColorModel, and PackedColorModel.

Hierarchy: Object-->ColorModel(Transparency)

Subclasses: ComponentColorModel, IndexColorModel, PackedColorModel

Passed To: Too many methods to list.

Returned By: Component.getColorModel(), GraphicsConfiguration.getColorModel(), PaintContext.getColorModel(), Toolkit.getColorModel(), BufferedImage.getColorModel(), ColorModel.{coerceData(), getRGBdefault()}, ComponentColorModel.coerceData(), DirectColorModel.coerceData(), PixelGrabber.getColorModel(), RenderedImage.getColorModel(), java.awt.peer.ComponentPeer.getColorModel()

Type Of: RGBImageFilter.{newmodel, origmodel}

ComponentColorModel	Java 1.2
java.awt.image

This ColorModel is used with image data in which the color and transparency components of pixels are stored separately, instead of being combined together into a single int value. This class works only with pixel values specified as an array of primitive values of the specified transfer type. The number of elements in these pixel arrays must match the number of color and transparency components in the specified color space. This class performs the trivial mapping between the array elements of the pixel value and the color components of the color it represents. The methods of this class that are passed int pixel values can throw IllegalArgumentException. Only applications that are doing custom image processing need to use this, or any, ColorModel.

Hierarchy: Object-->ColorModel(Transparency)-->ComponentColorModel

ComponentSampleModel	Java 1.2
java.awt.image

This SampleModel represents image data stored so that each component of each pixel is stored in a separate element of the DataBuffer. The arguments to the ComponentSampleModel allow great flexibility in this model. For example, it can represent RGB values interleaved into a single bank of bytes or ARGB values stored in four separate banks of bytes. Additionally, it can handle offsets at the end of scanlines and an offset at the beginning of each bank.

Java 2D defines two subclasses of ComponentSampleModel that are more efficient for particular types of image data. When each band of pixel components is stored in a separate bank of the DataBuffer, it is easier and more efficient to use the BandedSampleModel subclass. When the components of a pixel are stored in adjacent data elements of a single bank of the DataBuffer, it is easier and more efficient to use PixelInterleavedSampleModel.

Most applications never need to use this class or its subclasses. See SampleModel for further information.

Hierarchy: Object-->SampleModel-->ComponentSampleModel

Subclasses: BandedSampleModel, PixelInterleavedSampleModel

ConvolveOp	Java 1.2
java.awt.image

This class is a BufferedImageOp and a RasterOp that performs an arbitrary convolution on an image. Convolution is a versatile image-processing operation that can be used, for example, to blur or sharpen an image or perform edge detection on an image. The convolution to be performed is specified by a matrix of floating-point numbers, in the form of a Kernel object. Because convolution looks at the neighbors of each pixel in an image, special care must be taken when operating on the pixels at the edges of the image. By default, a ConvolveOp uses imaginary color components of all zeros when it reaches the edges of an image. You can pass EDGE_NO_OP to the constructor to specify that the edges of the image should simply be left unprocessed. Finally, you can pass a RenderingHints object to the ConvolveOp() constructor. If this argument is not null, the ConvolveOp may use its color and dithering hints.

To use a ConvolveOp, simply pass a source and optional destination image or raster to its filter() method. Note that you cannot specify the same object as both source and destination. See BufferedImageOp for further details.

Hierarchy: Object-->ConvolveOp(BufferedImageOp,RasterOp)

CropImageFilter	Java 1.0
java.awt.image	cloneable PJ1.1

This class implements an ImageFilter that crops an image to a specified rectangle. The methods defined by this class are used for communication between the filter and its FilteredImageSource and should never be called directly.

Hierarchy: Object-->ImageFilter(Cloneable,ImageConsumer)-->CropImageFilter

DataBuffer	Java 1.2
java.awt.image

This abstract class stores image data at the lowest level. A DataBuffer stores one or more arrays, or banks, of data of a specified size and a given type. The Raster class uses a DataBuffer to store image data and a SampleModel to interpret the storage format of that data. Most applications never need to use DataBuffer objects directly.

Specific concrete subclasses of DataBuffer are implemented for specific types of data. See also DataBufferByte, DataBufferShort, DataBufferUShort, and DataBufferInt.

Subclasses: DataBufferByte, DataBufferInt, DataBufferShort, DataBufferUShort

Passed To: Too many methods to list.

Returned By: BandedSampleModel.createDataBuffer(), ComponentSampleModel.createDataBuffer(), MultiPixelPackedSampleModel.createDataBuffer(), Raster.getDataBuffer(), SampleModel.createDataBuffer(), SinglePixelPackedSampleModel.createDataBuffer()

Type Of: Raster.dataBuffer

DataBufferByte	Java 1.2
java.awt.image

This class stores image data in one or more byte arrays. The arrays, or banks, of data can be passed directly to the DataBufferByte() constructor, or they can be created by the constructor. You may specify an offset into each array at which the data begins. getElem() and setElem() allow you to get and set the values of a particular element of a particular bank. Most applications never use this class directly.

Hierarchy: Object-->DataBuffer-->DataBufferByte

DataBufferInt	Java 1.2
java.awt.image

This class stores image data in one or more int arrays. The arrays, or banks, of data can be passed directly to the DataBufferInt() constructor, or they can be created by the constructor. You may specify an offset into each array at which the data begins. getElem() and setElem() allow you to get and set the values of a particular element of a particular bank. Most applications never use this class directly.

Hierarchy: Object-->DataBuffer-->DataBufferInt

DataBufferShort	Java 1.2
java.awt.image

This class stores image data in one or more short arrays. The arrays, or banks, of data can be passed directly to the DataBufferShort() constructor, or they can be created by the constructor. You may specify an offset into each array at which the data begins. getElem() and setElem() allow you to get and set the values of a particular element of a particular bank. Most applications never use this class directly.