com.twelvemonkeys.image

Class ResampleOp

java.lang.Object

com.twelvemonkeys.image.ResampleOp

All Implemented Interfaces:

java.awt.image.BufferedImageOp

public class ResampleOp
extends java.lang.Object
implements java.awt.image.BufferedImageOp

Resamples (scales) a BufferedImage to a new width and height, using high performance and high quality algorithms. Several different interpolation algorithms may be specifed in the constructor, either using the filter type constants, or one of the RendereingHints.

For fastest results, use FILTER_POINT or FILTER_BOX. In most cases, FILTER_TRIANGLE will produce acceptable results, while being relatively fast. For higher quality output, use more sophisticated interpolation algorithms, like FILTER_MITCHELL or FILTER_LANCZOS.

Example:

 BufferedImage image;
 

 //...
 

 ResampleOp resampler = new ResampleOp(100, 100, ResampleOp.FILTER_TRIANGLE);
 BufferedImage thumbnail = resampler.filter(image, null);
 

If your imput image is very large, it's possible to first resample using the very fast FILTER_POINT algorithm, then resample to the wanted size, using a higher quality algorithm:

 BufferedImage verylLarge;
 

 //...
 

 int w = 300;
 int h = 200;
 

 BufferedImage temp = new ResampleOp(w * 2, h * 2, FILTER_POINT).filter(verylLarge, null);
 

 BufferedImage scaled = new ResampleOp(w, h).filter(temp, null);
 

For maximum performance, this class will use native code, through JMagick, when available. Otherwise, the class will silently fall back to pure Java mode. Native code may be disabled globally, by setting the system property com.twelvemonkeys.image.accel to false. To allow debug of the native code, set the system property com.twelvemonkeys.image.magick.debug to true.

This BufferedImageOp is based on C example code found in Graphics Gems III, Filtered Image Rescaling, by Dale Schumacher (with additional improvments by Ray Gardener). Additional changes are inspired by ImageMagick and Marco Schmidt's Java Imaging Utilities (which are also adaptions of the same original code from Graphics Gems III).

For a description of the various interpolation algorithms, see General Filtered Image Rescaling in Graphics Gems III, Academic Press, 1994.

Version:

$Id: //depot/branches/personal/haraldk/twelvemonkeys/release-2/twelvemonkeys-core/src/main/java/com/twelvemonkeys/image/ResampleOp.java#1 $

Author:

Harald Kuhr, last modified by $Author: haku $

See Also:

ResampleOp(int,int,int), ResampleOp(int,int,java.awt.RenderingHints), BufferedImage, RenderingHints, AffineTransformOp

Field Summary

Fields

Modifier and Type	Field and Description
static int	FILTER_BLACKMAN Blackman interpolation..
static int	FILTER_BLACKMAN_BESSEL Blackman-Bessel interpolation.
static int	FILTER_BLACKMAN_SINC Blackman-Sinc interpolation.
static int	FILTER_BOX Box interpolation.
static int	FILTER_CATROM Catrom interpolation.
static int	FILTER_CUBIC Cubic interpolation.
static int	FILTER_GAUSSIAN Gaussian interpolation.
static int	FILTER_HAMMING Hamming interpolation.
static int	FILTER_HANNING Hanning interpolation.
static int	FILTER_HERMITE Hermite interpolation.
static int	FILTER_LANCZOS Lanczos interpolation.
static int	FILTER_MITCHELL Mitchell interpolation.
static int	FILTER_POINT Point interpolation (also known as "nearest neighbour").
static int	FILTER_QUADRATIC Quadratic interpolation.
static int	FILTER_TRIANGLE Triangle interpolation (also known as "linear" or "bilinear").
static int	FILTER_UNDEFINED Undefined interpolation, filter method will use default filter.
static java.awt.RenderingHints.Key	KEY_RESAMPLE_INTERPOLATION RenderingHints.Key specifying resampling interpolation algorithm.
static java.lang.Object	VALUE_INTERPOLATION_BLACKMAN
static java.lang.Object	VALUE_INTERPOLATION_BLACKMAN_BESSEL
static java.lang.Object	VALUE_INTERPOLATION_BLACKMAN_SINC
static java.lang.Object	VALUE_INTERPOLATION_BOX
static java.lang.Object	VALUE_INTERPOLATION_CATROM
static java.lang.Object	VALUE_INTERPOLATION_CUBIC
static java.lang.Object	VALUE_INTERPOLATION_GAUSSIAN
static java.lang.Object	VALUE_INTERPOLATION_HAMMING
static java.lang.Object	VALUE_INTERPOLATION_HANNING
static java.lang.Object	VALUE_INTERPOLATION_HERMITE
static java.lang.Object	VALUE_INTERPOLATION_LANCZOS
static java.lang.Object	VALUE_INTERPOLATION_MITCHELL
static java.lang.Object	VALUE_INTERPOLATION_POINT
static java.lang.Object	VALUE_INTERPOLATION_QUADRATIC
static java.lang.Object	VALUE_INTERPOLATION_TRIANGLE

Constructor Summary

Constructors

Constructor and Description
ResampleOp(int width, int height) Creates a ResampleOp that will resample input images to the given width and height, using the default interpolation filter.
ResampleOp(int width, int height, int filterType) Creates a ResampleOp that will resample input images to the given width and height, using the given interpolation filter.
ResampleOp(int width, int height, java.awt.RenderingHints hints) Creates a ResampleOp that will resample input images to the given width and height, using the interpolation filter specified by the given hints.

Method Summary

Methods

Modifier and Type	Method and Description
java.awt.image.BufferedImage	createCompatibleDestImage(java.awt.image.BufferedImage pInput, java.awt.image.ColorModel pModel)
java.awt.image.BufferedImage	filter(java.awt.image.BufferedImage input, java.awt.image.BufferedImage output) Re-samples (scales) the image to the size, and using the algorithm specified in the constructor.
java.awt.geom.Rectangle2D	getBounds2D(java.awt.image.BufferedImage src)
int	getFilterType() Returns the current filter type constant.
java.awt.geom.Point2D	getPoint2D(java.awt.geom.Point2D srcPt, java.awt.geom.Point2D dstPt)
java.awt.RenderingHints	getRenderingHints()

Methods inherited from class java.lang.Object

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

Field Detail

FILTER_UNDEFINED

public static final int FILTER_UNDEFINED

Undefined interpolation, filter method will use default filter.

See Also:

Constant Field Values

FILTER_POINT

public static final int FILTER_POINT

Point interpolation (also known as "nearest neighbour"). Very fast, but low quality (similar to RenderingHints.VALUE_INTERPOLATION_NEAREST_NEIGHBOR and Image.SCALE_REPLICATE).

See Also:

Constant Field Values

FILTER_BOX

public static final int FILTER_BOX

Box interpolation. Fast, but low quality.

See Also:

Constant Field Values

FILTER_TRIANGLE

public static final int FILTER_TRIANGLE

Triangle interpolation (also known as "linear" or "bilinear"). Quite fast, with acceptable quality (similar to RenderingHints.VALUE_INTERPOLATION_BILINEAR and Image.SCALE_AREA_AVERAGING).

See Also:

Constant Field Values

FILTER_HERMITE

public static final int FILTER_HERMITE

Hermite interpolation.

See Also:

Constant Field Values

FILTER_HANNING

public static final int FILTER_HANNING

Hanning interpolation.

See Also:

Constant Field Values

FILTER_HAMMING

public static final int FILTER_HAMMING

Hamming interpolation.

See Also:

Constant Field Values

FILTER_BLACKMAN

public static final int FILTER_BLACKMAN

Blackman interpolation..

See Also:

Constant Field Values

FILTER_GAUSSIAN

public static final int FILTER_GAUSSIAN

Gaussian interpolation.

See Also:

Constant Field Values

FILTER_QUADRATIC

public static final int FILTER_QUADRATIC

Quadratic interpolation.

See Also:

Constant Field Values

FILTER_CUBIC

public static final int FILTER_CUBIC

Cubic interpolation.

See Also:

Constant Field Values

FILTER_CATROM

public static final int FILTER_CATROM

Catrom interpolation.

See Also:

Constant Field Values

FILTER_MITCHELL

public static final int FILTER_MITCHELL

Mitchell interpolation. High quality.

See Also:

Constant Field Values

FILTER_LANCZOS

public static final int FILTER_LANCZOS

Lanczos interpolation. High quality.

See Also:

Constant Field Values

FILTER_BLACKMAN_BESSEL

public static final int FILTER_BLACKMAN_BESSEL

Blackman-Bessel interpolation. High quality.

See Also:

Constant Field Values

FILTER_BLACKMAN_SINC

public static final int FILTER_BLACKMAN_SINC

Blackman-Sinc interpolation. High quality.

See Also:

Constant Field Values

KEY_RESAMPLE_INTERPOLATION

public static final java.awt.RenderingHints.Key KEY_RESAMPLE_INTERPOLATION

RenderingHints.Key specifying resampling interpolation algorithm.

VALUE_INTERPOLATION_POINT

public static final java.lang.Object VALUE_INTERPOLATION_POINT

See Also:

FILTER_POINT

VALUE_INTERPOLATION_BOX

public static final java.lang.Object VALUE_INTERPOLATION_BOX

See Also:

FILTER_BOX

VALUE_INTERPOLATION_TRIANGLE

public static final java.lang.Object VALUE_INTERPOLATION_TRIANGLE

See Also:

FILTER_TRIANGLE

VALUE_INTERPOLATION_HERMITE

public static final java.lang.Object VALUE_INTERPOLATION_HERMITE

See Also:

FILTER_HERMITE

VALUE_INTERPOLATION_HANNING

public static final java.lang.Object VALUE_INTERPOLATION_HANNING

See Also:

FILTER_HANNING

VALUE_INTERPOLATION_HAMMING

public static final java.lang.Object VALUE_INTERPOLATION_HAMMING

See Also:

FILTER_HAMMING

VALUE_INTERPOLATION_BLACKMAN

public static final java.lang.Object VALUE_INTERPOLATION_BLACKMAN

See Also:

FILTER_BLACKMAN

VALUE_INTERPOLATION_GAUSSIAN

public static final java.lang.Object VALUE_INTERPOLATION_GAUSSIAN

See Also:

FILTER_GAUSSIAN

VALUE_INTERPOLATION_QUADRATIC

public static final java.lang.Object VALUE_INTERPOLATION_QUADRATIC

See Also:

FILTER_QUADRATIC

VALUE_INTERPOLATION_CUBIC

public static final java.lang.Object VALUE_INTERPOLATION_CUBIC

See Also:

FILTER_CUBIC

VALUE_INTERPOLATION_CATROM

public static final java.lang.Object VALUE_INTERPOLATION_CATROM

See Also:

FILTER_CATROM

VALUE_INTERPOLATION_MITCHELL

public static final java.lang.Object VALUE_INTERPOLATION_MITCHELL

See Also:

FILTER_MITCHELL

VALUE_INTERPOLATION_LANCZOS

public static final java.lang.Object VALUE_INTERPOLATION_LANCZOS

See Also:

FILTER_LANCZOS

VALUE_INTERPOLATION_BLACKMAN_BESSEL

public static final java.lang.Object VALUE_INTERPOLATION_BLACKMAN_BESSEL

See Also:

FILTER_BLACKMAN_BESSEL

VALUE_INTERPOLATION_BLACKMAN_SINC

public static final java.lang.Object VALUE_INTERPOLATION_BLACKMAN_SINC

See Also:

FILTER_BLACKMAN_SINC

Constructor Detail

ResampleOp

public ResampleOp(int width,
          int height)

Creates a ResampleOp that will resample input images to the given width and height, using the default interpolation filter.

Parameters:

width - width of the re-sampled image

height - height of the re-sampled image

ResampleOp

public ResampleOp(int width,
          int height,
          java.awt.RenderingHints hints)

Creates a ResampleOp that will resample input images to the given width and height, using the interpolation filter specified by the given hints. If using RenderingHints, the hints are mapped as follows:

• KEY_RESAMPLE_INTERPOLATION takes precedence over any standard java.awt hints, and dictates interpolation directly, see RenderingHints constants.
• KEY_INTERPOLATION takes precedence over other hints.
  • RenderingHints.VALUE_INTERPOLATION_NEAREST_NEIGHBOR specifies FILTER_POINT
  • RenderingHints.VALUE_INTERPOLATION_BILINEAR specifies FILTER_TRIANGLE
  • RenderingHints.VALUE_INTERPOLATION_BICUBIC specifies FILTER_QUADRATIC
• KEY_RENDERING or KEY_COLOR_RENDERING
  • RenderingHints.VALUE_RENDER_SPEED specifies FILTER_POINT
  • RenderingHints.VALUE_RENDER_QUALITY specifies FILTER_MITCHELL

Other hints have no effect on this filter.

Parameters:

width - width of the re-sampled image

height - height of the re-sampled image

hints - rendering hints, affecting interpolation algorithm

See Also:

KEY_RESAMPLE_INTERPOLATION, RenderingHints.KEY_INTERPOLATION, RenderingHints.KEY_RENDERING, RenderingHints.KEY_COLOR_RENDERING

ResampleOp

public ResampleOp(int width,
          int height,
          int filterType)

Creates a ResampleOp that will resample input images to the given width and height, using the given interpolation filter.

Parameters:

width - width of the re-sampled image

height - height of the re-sampled image

filterType - interpolation filter algorithm

See Also:

filter type constants

Method Detail

filter

public final java.awt.image.BufferedImage filter(java.awt.image.BufferedImage input,
                                  java.awt.image.BufferedImage output)

Re-samples (scales) the image to the size, and using the algorithm specified in the constructor.

Specified by:

filter in interface java.awt.image.BufferedImageOp

Parameters:

input - The BufferedImage to be filtered

output - The BufferedImage in which to store the resampled image

Returns:

The re-sampled BufferedImage.

Throws:

java.lang.NullPointerException - if input is null

java.lang.IllegalArgumentException - if input == output.

See Also:

ResampleOp(int,int,int)

getFilterType

public int getFilterType()

Returns the current filter type constant.

Returns:

the current filter type constant.

See Also:

filter type constants

createCompatibleDestImage

public final java.awt.image.BufferedImage createCompatibleDestImage(java.awt.image.BufferedImage pInput,
                                                     java.awt.image.ColorModel pModel)

Specified by:

createCompatibleDestImage in interface java.awt.image.BufferedImageOp

getRenderingHints

public java.awt.RenderingHints getRenderingHints()

Specified by:

getRenderingHints in interface java.awt.image.BufferedImageOp

getBounds2D

public java.awt.geom.Rectangle2D getBounds2D(java.awt.image.BufferedImage src)

Specified by:

getBounds2D in interface java.awt.image.BufferedImageOp

getPoint2D

public java.awt.geom.Point2D getPoint2D(java.awt.geom.Point2D srcPt,
                               java.awt.geom.Point2D dstPt)

Specified by:

getPoint2D in interface java.awt.image.BufferedImageOp