Quality Image Resizing with JAI

ThumbMaster Documentation

There are two different ways that ThumbMaster can be used to resize images. The first is by calling one of the static methods of the net.devella.thumbs.ThumbMaster class. This is the simpler of the two methods, and allows image resizing to be performed in a single line of code.

For users familiar with JAI who require more control — for example, custom RenderingHints — a net.devella.thumbs.ThumbMasterInterpolation can be passed directly as the final parameter to a ’scale’ operation.

Each of these two modes of operation are detailed below. Javadoc is also available for all public ThumbMaster classes.

Using ThumbMaster’s Static Helper Methods

The ThumbMaster API provides a number of static helper methods in the net.devella.thumbs.ThumbMaster class. These methods allow an image to be resized in several different ways without the need to manually create and use JAI operations. The provided functions are:

resizeImageToFit
: Resizes an image so that it will fit inside a box with specified dimensions. The original image’s aspect ratio will be preserved, so that the new image will not be distorted.
resizeImageToWidth
: Resizes an image so that the result has the specified width. The height will be variable, and depends on the aspect ratio of the initial image.
resizeImageToHeight
: Resizes an image so that the result has the specified height. The width will be variable, and depends on the aspect ratio of the initial image.
resizeImage
: Resizes an image by the specified scale factor, which is applied to both the X and Y dimensions.

Using ThumbMasterInterpolation and JAI Operations

The following documentation assumes you are already familiar with using JAI operators in general, and the ’scale’ operator in specific. If this is not the case, you may want to consider using ThumbMaster’s static helper methods instead — or read the JAI Programmer’s Guide section on scaling transformations.

In order to use ThumbMaster as part of a normal JAI scale operation, the 5th parameter (’interpolation’) must be set to an instance of net.devella.thumbs.ThumbMasterInterpolation. This class provides a single constructor, which is detailed below.

ThumbMasterInterpolation’s Constructor

public ThumbMasterInterpolation(float scaleFactor) { ... }

Parameters

scaleFactor: The scale factor for the resize operation being performed. This should be the smaller of the first two values in the JAI scale ParameterBlock (’xScale’ and ‘yScale’). Note that different values for scaleFactor produce different interpolation tables, and so it is important that the same ThumbMasterInterpolation not be reused for operations with different scale factors.

Example Usage

Following is a complete example of how to use JAI with ThumbMaster to write an image resize method:

/**
 * Resizes a RenderedImage by a given scale factor, and returns
 * the result. If the source image is null, null is returned.
 *
 * @param image the source image to resize
 * @param ratio the scale factor to resize the image by
 * @return the resized image, or null
 */
public static RenderedImage
  resizeImage(RenderedImage image, float ratio) {
    if (image == null) {
        return null;
    }

    ParameterBlock pb = new ParameterBlock();
    pb.addSource(image);
    pb.add(ratio);
    pb.add(ratio);
    pb.add(0F);
    pb.add(0F);

    // Here we create the ThumbMaster interpolation, and pass
    // it to JAI as parameter five. Note that the ratio is
    // the same scale factor as parameters 1 and 2
    pb.add(new ThumbMasterInterpolation(ratio));

    RenderingHints rh = new RenderingHints(
        JAI.KEY_BORDER_EXTENDER,
        BorderExtender.createInstance(
            BorderExtender.BORDER_COPY
        )
    );
    return JAI.create("scale", pb, rh);
}

Example 1: Resizing images using ThumbMasterInterpolation and JAI