Package ca.cgjennings.graphics.filters

Class ConvolveFilter

java.lang.Object

ca.cgjennings.graphics.filters.AbstractImageFilter

ca.cgjennings.graphics.filters.AbstractImagewiseFilter

ca.cgjennings.graphics.filters.AbstractConvolver

ca.cgjennings.graphics.filters.ConvolveFilter

All Implemented Interfaces:

java.awt.image.BufferedImageOp

public class ConvolveFilter
extends AbstractConvolver

Performs an image convolution on an image. This is similar to ConvolveOp, with two key differences:

1. This class offers more complex options for handling image edges.
2. This class makes use of the acceleration framework provided by the AbstractImageFilter framework. Note that ConvolveOp may also provide acceleration; typically this is GPU-based acceleration for small kernel sizes. (Which implementation is faster will depend on a number of platform-specific factors.)

In-place filtering: Unless otherwise noted, filters based on this class support in-place filtering (the source and destination images can be the same).

Since:

3.0

Author:

Chris Jennings

Constructor Summary

Constructors

Constructor	Description
ConvolveFilter()	Creates a new convolve filter set with a simple blur filter.
ConvolveFilter(boolean normalize, int kernelWidth, int kernelHeight, float... kernelData)	Creates a new convolve filter.
ConvolveFilter(int kernelWidth, int kernelHeight, float... kernelData)	Creates a new convolve filter.
ConvolveFilter(java.awt.image.Kernel kernel)	Creates a new convolve filter with the specified kernel.

Method Summary

Modifier and Type	Method	Description
EdgeHandling	getEdgeHandling()	Returns the current edge handling mode.
java.awt.image.Kernel	getKernel()	Returns the convolution kernel.
protected java.awt.image.Kernel[]	getKernels()	Returns the convolution kernel(s) that should be applied to execute this filter.
void	setEdgeHandling(EdgeHandling edgeHandling)	Sets the edge handling mode.
void	setKernel(boolean normalize, int width, int height, float... kernelData)	Sets the convolution kernel.
void	setKernel(java.awt.image.Kernel kernel)	Sets the convolution kernel.

Methods inherited from class ca.cgjennings.graphics.filters.AbstractConvolver

filter, filterPixels, isAlphaFiltered, isAlphaPremultiplied, workFactor

Methods inherited from class ca.cgjennings.graphics.filters.AbstractImagewiseFilter

filter

Methods inherited from class ca.cgjennings.graphics.filters.AbstractImageFilter

clamp, clamp, clamp, clampBoth, createCompatibleDestImage, fA, fB, fG, fR, getARGB, getARGB, getARGBSynch, getBounds2D, getPoint2D, getRenderingHints, iA, iB, iG, iR, setARGB, setARGB, setARGBSynch

Methods inherited from class java.lang.Object

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

Constructor Detail

ConvolveFilter

public ConvolveFilter()

Creates a new convolve filter set with a simple blur filter.

ConvolveFilter

public ConvolveFilter(int kernelWidth,
                      int kernelHeight,
                      float... kernelData)

Creates a new convolve filter. This is a convenience that creates a new Kernel with the specified width, height, and matrix values. The kernel matrix will not be normalized; if the elements of the kernel do not sum to 1, the brightness of the destination image will be changed by the filter.

Parameters:

kernelWidth - the width of the kernel matrix

kernelHeight - the height of the kernel matrix

kernelData - the matrix data values

ConvolveFilter

public ConvolveFilter(boolean normalize,
                      int kernelWidth,
                      int kernelHeight,
                      float... kernelData)

Creates a new convolve filter. This is a convenience that creates a new Kernel with the specified width, height, and matrix values.

Parameters:

normalize - whether the m

kernelWidth - the width of the kernel matrix

kernelHeight - the height of the kernel matrix

kernelData - the matrix data values

ConvolveFilter

public ConvolveFilter(java.awt.image.Kernel kernel)

Creates a new convolve filter with the specified kernel.

Parameters:

kernel - the convolution kernel

Method Detail

getKernel

public java.awt.image.Kernel getKernel()

Returns the convolution kernel.

Returns:

the current kernel

setKernel

public void setKernel(java.awt.image.Kernel kernel)

Sets the convolution kernel.

Parameters:

kernel - the kernel to use

setKernel

public void setKernel(boolean normalize,
                      int width,
                      int height,
                      float... kernelData)

Sets the convolution kernel. This is a convenience that creates a new Kernel with the specified width, height, and matrix values.

Parameters:

normalize - if true, the matrix will be normalized so that its elements sum to 1; this prevents the overall image brightness from changing

width - the width of the kernel

height - the height of the kernel

kernelData - an array of kernel values, in row-major order

Throws:

java.lang.IllegalArgumentException - if the length of the array is less than with product of the width and height or if normalize is true and the kernel elements sum to zero

setEdgeHandling

public void setEdgeHandling(EdgeHandling edgeHandling)

Sets the edge handling mode. The edge handling mode determines the stand-in pixel values used for pixels at the edge of the image, where part of the kernel would lie outside of the source image.

Parameters:

edgeHandling - the edge handling mode

Throws:

java.lang.NullPointerException - if the edge handling mode is null

getEdgeHandling

public EdgeHandling getEdgeHandling()

Returns the current edge handling mode.

Overrides:

getEdgeHandling in class AbstractConvolver

Returns:

the edge handling mode

getKernels

protected java.awt.image.Kernel[] getKernels()

Description copied from class: AbstractConvolver

Returns the convolution kernel(s) that should be applied to execute this filter. Typically, array is either length one (non-separable) or length two (separable).

Specified by:

getKernels in class AbstractConvolver

Returns:

an array of non-null convolution kernels