Package com.twelvemonkeys.image

Class 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 input 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 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