java.awt.image
Class ConvolveOp

java.lang.Object
  extended by java.awt.image.ConvolveOp
All Implemented Interfaces:
BufferedImageOp, RasterOp

public class ConvolveOp
extends Object
implements BufferedImageOp, RasterOp

Convolution filter. ConvolveOp convolves the source image with a Kernel to generate a destination image. This involves multiplying each pixel and its neighbors with elements in the kernel to compute a new pixel. Each band in a Raster is convolved and copied to the destination Raster. For BufferedImages, convolution is applied to all components. Color conversion will be applied if needed. Note that this filter ignores whether the source or destination is alpha premultiplied. The reference spec states that data will be premultiplied prior to convolving and divided back out afterwards (if needed), but testing has shown that this is not the case with their implementation.


Field Summary
static int EDGE_NO_OP
          Edge pixels are copied from the source.
static int EDGE_ZERO_FILL
          Edge pixels are set to 0.
 
Constructor Summary
ConvolveOp(Kernel kernel)
          Construct a ConvolveOp.
ConvolveOp(Kernel kernel, int edgeCondition, RenderingHints hints)
          Construct a ConvolveOp.
 
Method Summary
 BufferedImage createCompatibleDestImage(BufferedImage src, ColorModel dstCM)
          Creates an empty BufferedImage with the size equal to the source and the correct number of bands.
 WritableRaster createCompatibleDestRaster(Raster src)
          Returns a raster that can be used by this RasterOp as the destination raster when operating on the specified source raster.
 BufferedImage filter(BufferedImage src, BufferedImage dst)
          Converts the source image using the kernel specified in the constructor.
 WritableRaster filter(Raster src, WritableRaster dest)
          Converts the source raster using the kernel specified in the constructor.
 Rectangle2D getBounds2D(BufferedImage src)
          Returns the bounds of the destination image on the basis of this BufferedImageOp being applied to the specified source image.
 Rectangle2D getBounds2D(Raster src)
          Returns the bounds of the destination raster on the basis of this RasterOp being applied to the specified source raster.
 int getEdgeCondition()
          Get the edge condition for this Op.
 Kernel getKernel()
          Returns (a clone of) the convolution kernel.
 Point2D getPoint2D(Point2D src, Point2D dst)
          Returns the corresponding destination point for a source point.
 RenderingHints getRenderingHints()
          Returns the rendering hints for this operation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EDGE_ZERO_FILL

public static final int EDGE_ZERO_FILL
Edge pixels are set to 0.

See Also:
Constant Field Values

EDGE_NO_OP

public static final int EDGE_NO_OP
Edge pixels are copied from the source.

See Also:
Constant Field Values
Constructor Detail

ConvolveOp

public ConvolveOp(Kernel kernel,
                  int edgeCondition,
                  RenderingHints hints)
Construct a ConvolveOp. The edge condition specifies that pixels outside the area that can be filtered are either set to 0 or copied from the source image.

Parameters:
kernel - The kernel to convolve with.
edgeCondition - Either EDGE_ZERO_FILL or EDGE_NO_OP.
hints - Rendering hints for color conversion, or null.

ConvolveOp

public ConvolveOp(Kernel kernel)
Construct a ConvolveOp. The edge condition defaults to EDGE_ZERO_FILL.

Parameters:
kernel - The kernel to convolve with.
Method Detail

filter

public final BufferedImage filter(BufferedImage src,
                                  BufferedImage dst)
Converts the source image using the kernel specified in the constructor. The resulting image is stored in the destination image if one is provided; otherwise a new BufferedImage is created and returned. The source and destination BufferedImage (if one is supplied) must have the same dimensions.

Specified by:
filter in interface BufferedImageOp
Parameters:
src - The source image.
dst - The destination image.
Returns:
The convolved image.
Throws:
IllegalArgumentException - if the rasters and/or color spaces are incompatible.

createCompatibleDestImage

public BufferedImage createCompatibleDestImage(BufferedImage src,
                                               ColorModel dstCM)
Creates an empty BufferedImage with the size equal to the source and the correct number of bands. The new image is created with the specified ColorModel, or if no ColorModel is supplied, an appropriate one is chosen.

Specified by:
createCompatibleDestImage in interface BufferedImageOp
Parameters:
src - The source image.
dstCM - A color model for the destination image (may be null).
Returns:
The new compatible destination image.

getRenderingHints

public final RenderingHints getRenderingHints()
Description copied from interface: BufferedImageOp
Returns the rendering hints for this operation.

Specified by:
getRenderingHints in interface BufferedImageOp
Specified by:
getRenderingHints in interface RasterOp
Returns:
The rendering hints.

getEdgeCondition

public int getEdgeCondition()
Get the edge condition for this Op.

Returns:
The edge condition.

getKernel

public final Kernel getKernel()
Returns (a clone of) the convolution kernel.

Returns:
The convolution kernel.

filter

public final WritableRaster filter(Raster src,
                                   WritableRaster dest)
Converts the source raster using the kernel specified in the constructor. The resulting raster is stored in the destination raster if one is provided; otherwise a new WritableRaster is created and returned. If the convolved value for a sample is outside the range of [0-255], it will be clipped. The source and destination raster (if one is supplied) cannot be the same, and must also have the same dimensions.

Specified by:
filter in interface RasterOp
Parameters:
src - The source raster.
dest - The destination raster.
Returns:
The transformed raster.
Throws:
IllegalArgumentException - if the rasters identical.
ImagingOpException - if the convolution is not possible.

createCompatibleDestRaster

public WritableRaster createCompatibleDestRaster(Raster src)
Description copied from interface: RasterOp
Returns a raster that can be used by this RasterOp as the destination raster when operating on the specified source raster.

Specified by:
createCompatibleDestRaster in interface RasterOp
Parameters:
src - the source raster.
Returns:
A new writable raster that can be used as the destination raster.

getBounds2D

public final Rectangle2D getBounds2D(BufferedImage src)
Description copied from interface: BufferedImageOp
Returns the bounds of the destination image on the basis of this BufferedImageOp being applied to the specified source image.

Specified by:
getBounds2D in interface BufferedImageOp
Parameters:
src - the source image.
Returns:
The destination bounds.

getBounds2D

public final Rectangle2D getBounds2D(Raster src)
Description copied from interface: RasterOp
Returns the bounds of the destination raster on the basis of this RasterOp being applied to the specified source raster.

Specified by:
getBounds2D in interface RasterOp
Parameters:
src - the source raster.
Returns:
The destination bounds.

getPoint2D

public final Point2D getPoint2D(Point2D src,
                                Point2D dst)
Returns the corresponding destination point for a source point. Because this is not a geometric operation, the destination and source points will be identical.

Specified by:
getPoint2D in interface BufferedImageOp
Specified by:
getPoint2D in interface RasterOp
Parameters:
src - The source point.
dst - The transformed destination point.
Returns:
The transformed destination point.