TwelveMonkeys

About

TwelveMonkeys ImageIO provides extended image file format support for the Java platform, through plugins for the javax.imageio.* package.

The main goal of this project is to provide support for file formats not covered by the JDK. Support for these formats is important, to be able to read data found "in the wild", as well as to maintain access to data in legacy formats. As there is lots of legacy data out there, we see the need for open implementations of readers for popular formats.

File formats supported

Important note on using Batik: Please read The Apache™ XML Graphics Project - Security, and make sure you use an updated and secure version.

Note that GIF, PNG and WBMP formats are already supported through the ImageIO API, using the JDK standard plugins. For BMP, JPEG, and TIFF formats the TwelveMonkeys plugins provides extended format support and additional features.

Basic usage

Most of the time, all you need to do is simply include the plugins in your project and write:

BufferedImage image = ImageIO.read(file);

This will load the first image of the file, entirely into memory.

The basic and simplest form of writing is:

if (!ImageIO.write(image, format, file)) {
   // Handle image not written case
}

This will write the entire image into a single file, using the default settings for the given format.

The plugins are discovered automatically at run time. See the FAQ for more info on how this mechanism works.

Advanced usage

If you need more control of read parameters and the reading process, the common idiom for reading is something like:

…

Query the reader for source image dimensions using reader.getWidth(n) and reader.getHeight(n) without reading the entire image into memory first.

It's also possible to read multiple images from the same file in a loop, using reader.getNumImages().

If you need more control of write parameters and the writing process, the common idiom for writing is something like:

…

For more advanced usage, and information on how to use the ImageIO API, I suggest you read the Java Image I/O API Guide from Oracle.

Adobe Clipping Path support

import com.twelvemonkeys.imageio.path.Paths;

...

try (ImageInputStream stream = ImageIO.createImageInputStream(new File("image_with_path.jpg")) {
    BufferedImage image = Paths.readClipped(stream);

    // Do something with the clipped image...
}

See Adobe Clipping Path support on the Wiki for more details and example code.

Using the ResampleOp

The library comes with a resampling (image resizing) operation, that contains many different algorithms to provide excellent results at reasonable speed.

import com.twelvemonkeys.image.ResampleOp;

...

BufferedImage input = ...; // Image to resample
int width, height = ...; // new width/height

BufferedImageOp resampler = new ResampleOp(width, height, ResampleOp.FILTER_LANCZOS); // A good default filter, see class documentation for more info
BufferedImage output = resampler.filter(input, null);

Using the DiffusionDither

The library comes with a dithering operation, that can be used to convert BufferedImages to IndexColorModel using Floyd-Steinberg error-diffusion dither.

import com.twelvemonkeys.image.DiffusionDither;

...

BufferedImage input = ...; // Image to dither

BufferedImageOp ditherer = new DiffusionDither();
BufferedImage output = ditherer.filter(input, null);

Working with damaged images

When using the normal patterns for loading images, trying to load a damaged image will result in an IOException being thrown.

BufferedImage image = null;
try {
    image = ImageIO.read(file);
} catch (IOException exception) {
    // Handle, log a warning/error etc
}

In this scenario, if the image is damaged, and ImageIO.read throws an exception, image is still null - it's not possible for a function to both return a