TwelveMonkeys ImageIO

TwelveMonkeys is designed to work as a drop-in replacement for standard Java ImageIO. You do not need to change your existing code to benefit from the improved format support.

Integration via Build Tools

The recommended way to use TwelveMonkeys is to add the specific plugin dependencies to your project using a dependency management tool like Maven or Gradle.

Integration via Classpath

If you are not using a build tool, ensure that all necessary TwelveMonkeys ImageIO JAR files are included in your application's classpath. ImageIO uses a service lookup mechanism to discover these plugins at runtime.

Usage with Standard APIs

For basic usage, you can continue using standard javax.imageio APIs. The plugins are automatically discovered and used by methods such as:

• ImageIO.read(...)
• ImageIO.getImageReaders(...)

Advanced Usage

While most functionality is accessed through standard APIs, some formats offer advanced features that may require using specific APIs. Examples include:

• Setting a base URL for an SVG image consisting of multiple files.
• Controlling the output compression of a TIFF file.

For fine-grained control over reading parameters (like sub-sampling, source regions, or destination buffers), use the ImageReader API instead of the high-level ImageIO.read() method.

Key steps:

1. Create an ImageInputStream.
2. Obtain an ImageReader via ImageIO.getImageReaders(input).
3. Set the input on the reader.
4. Use ImageReadParam to configure settings like setSourceSubsampling, setSourceRegion, or setDestination.
5. Call reader.read(index, param) to perform the read.
6. Crucial: Always call reader.dispose() in a finally block to prevent memory leaks.

You can also query dimensions using reader.getWidth(n) and reader.getHeight(n) without loading the full image into memory, or loop through multiple images in a single file using reader.getNumImages().

// Create input stream (in try-with-resource block to avoid leaks)
try (ImageInputStream input = ImageIO.createImageInputStream(file)) {
    // Get the reader
    Iterator<ImageReader> readers = ImageIO.getImageReaders(input);

    if (!readers.hasNext()) {
        throw new IllegalArgumentException("No reader for: " + file);
    }

    ImageReader reader = readers.next();

    try {
        reader.setInput(input);

        // Optionally, listen for read warnings, progress, etc.
        reader.addIIOReadWarningListener(...);
        reader.addIIOReadProgressListener(...);

        ImageReadParam param = reader.getDefaultReadParam();

        // Optionally, control read settings like sub sampling, source region or destination etc.
        param.setSourceSubsampling(...);
        param.setSourceRegion(...);
        param.setDestination(...);
        // ...

        // Finally read the image, using settings from param
        BufferedImage image = reader.read(0, param);

        // Optionally, read thumbnails, meta data, etc...
        int numThumbs = reader.getNumThumbnails(0);
        // ...
    }
    finally {
        // Dispose reader in finally block to avoid memory leaks
        reader.dispose();
    }
}

Standard ImageIO.read(file) calls return null and throw an IOException if an image is damaged. To attempt to recover usable data from a damaged file, you must manually manage the ImageReader and provide a destination buffer via ImageReadParam.

1. Get the image dimensions and raw image type using reader.getWidth(0) and reader.getRawImageType(0).
2. Create a BufferedImage using the ImageTypeSpecifier.
3. Set this buffer as the destination in ImageReadParam.setDestination(image).
4. Call reader.read(0, param) inside a try-catch block.

Note: Results are plugin-specific; you may still receive a blank or empty image.

int width = reader.getWidth(0);
int height = reader.getHeight(0);
ImageTypeSpecifier imageType = reader.getRawImageType(0);
BufferedImage image = imageType.createBufferedImage(width, height);

ImageReadParam param = reader.getDefaultReadParam();
param.setDestination(image);

try {
    reader.read(0, param);
}
catch (IOException e) {
    // Handle, log a warning/error etc
}

To control write parameters and the writing process, use the ImageWriter API.

Key steps:

1. Obtain an ImageWriter via ImageIO.getImageWritersByFormatName(format).
2. Create an ImageOutputStream.
3. Set the output on the writer.
4. Use ImageWriteParam to configure format-specific settings (often requiring casting) or generic settings like sub-sampling and source regions.
5. Call writer.write(...) providing an IIOImage (which contains metadata, the image, and other data) and the ImageWriteParam.
6. Crucial: Always call writer.dispose() in a finally block to prevent memory leaks.

// Get the writer
Iterator<ImageWriter> writers = ImageIO.getImageWritersByFormatName(format);

if (!writers.hasNext()) {
    throw new IllegalArgumentException("No writer for: " + format);
}

ImageWriter writer = writers.next();

try {
    // Create output stream (in try-with-resource block to avoid leaks)
    try (ImageOutputStream output = ImageIO.createImageOutputStream(file)) {
        writer.setOutput(output);

        // Optionally, listen to progress, warnings, etc.

        ImageWriteParam param = writer.getDefaultWriteParam();

        // Optionally, control format specific settings of param (requires casting), or
        // control generic write settings like sub sampling, source region, output type etc.

        // Optionally, provide thumbnails and image/stream metadata
        writer.write(..., new IIOImage(..., image, ...), param);
    }
} 
finally {
    // Dispose writer in finally block to avoid memory leaks
    writer.dispose();
}

To use TwelveMonkeys plugins in a Maven project, add the specific plugin dependencies to your pom.xml. For example, to include JPEG and TIFF support, add imageio-jpeg and imageio-tiff from the com.twelvemonkeys.imageio group.

If you are deploying as part of a web application, you should also include the com.twelvemonkeys.servlet:servlet dependency. For applications using Jakarta EE (Servlet API 5.0+), use the version with the jakarta classifier.

<dependencies>
    <dependency>
        <groupId>com.twelvemonkeys.imageio</groupId>
        <artifactId>imageio-jpeg</artifactId>
        <version>3.13.1</version>
    </dependency>
    <dependency>
        <groupId>com.twelvemonkeys.imageio</groupId>
        <artifactId>imageio-tiff</artifactId>
        <version>3.13.1</version>
    </dependency>

    <!-- Optional: For web apps (javax.servlet) -->
    <dependency>
        <groupId>com.twelvemonkeys.servlet</groupId>
        <artifactId>servlet</artifactId>
        <version>3.13.1</version>
    </dependency>

    <!-- Optional: For web apps (jakarta.servlet) -->
    <dependency>
        <groupId>com.twelvemonkeys.servlet</groupId>
        <artifactId>servlet</artifactId>
        <version>3.13.1</version>
        <classifier>jakarta</classifier>
    </dependency>
</dependencies>