TwelveMonkeys

关于

TwelveMonkeys ImageIO 通过 javax.imageio.* 包的插件为 Java 平台提供扩展的图像文件格式支持。

这个项目的主要目标是为 JRE 本身不支持的格式提供支持。 支持这些格式很重要，因为它能够读取"野外"发现的数据，并保持对遗留格式数据的访问。 由于存在大量遗留数据，我们看到了对流行格式开放实现读取器的需求。

支持的文件格式

使用 Batik 的重要说明： 请阅读 Apache™ XML Graphics 项目 - 安全性，并确保使用更新和安全的版本。

请注意，GIF、PNG 和 WBMP 格式已通过 ImageIO API 使用 JDK 标准插件 得到支持。对于 BMP、JPEG 和 TIFF 格式，TwelveMonkeys 插件提供了扩展的格式支持和其他功能。

基本用法

大多数情况下，您只需在项目中包含插件并编写：

BufferedImage image = ImageIO.read(file);

这将把文件中的第一张图像完全加载到内存中。

最基本和最简单的写入形式是：

if (!ImageIO.write(image, format, file)) {
   // 处理图像未写入的情况
}

这将使用给定格式的默认设置，将整个图像写入单个文件。

插件会在运行时自动发现。有关此机制如何工作的更多信息，请参阅 FAQ。

高级用法

如果您需要更多地控制读取参数和读取过程，常见的读取习惯用法如下：

// 创建输入流（在 try-with-resource 块中以避免泄漏）
try (ImageInputStream input = ImageIO.createImageInputStream(file)) {
    // 获取读取器
    Iterator<ImageReader> readers = ImageIO.getImageReaders(input);

    if (!readers.hasNext()) {
        throw new IllegalArgumentException("无法读取：" + file);
    }

    ImageReader reader = readers.next();

    try {
        reader.setInput(input);

        // 可选：监听读取警告、进度等
        reader.addIIOReadWarningListener(...);
        reader.addIIOReadProgressListener(...);

        ImageReadParam param = reader.getDefaultReadParam();

        // 可选：控制读取设置，如子采样、源区域或目标等
        param.setSourceSubsampling(...);
        param.setSourceRegion(...);
        param.setDestination(...);
        // ...

        // 最后使用 param 中的设置读取图像
        BufferedImage image = reader.read(0, param);
// 可选择性地读取缩略图、元数据等...
int numThumbs = reader.getNumThumbnails(0);
// ...
}
finally {
    // 在finally块中释放reader以避免内存泄漏
    reader.dispose();
}
}

使用reader.getWidth(n)和reader.getHeight(n)查询源图像尺寸,无需先将整个图像读入内存。

还可以使用reader.getNumImages()在循环中从同一文件读取多个图像。

如果需要更多地控制写入参数和写入过程,常见的写入方式如下:

// 获取writer
Iterator<ImageWriter> writers = ImageIO.getImageWritersByFormatName(format);

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

ImageWriter writer = writers.next();

try {
    // 创建输出流(在try-with-resource块中以避免泄漏)
    try (ImageOutputStream output = ImageIO.createImageOutputStream(file)) {
        writer.setOutput(output);

        // 可选择性地监听进度、警告等

        ImageWriteParam param = writer.getDefaultWriteParam();

        // 可选择性地控制param的格式特定设置(需要类型转换),或
        // 控制通用写入设置如子采样、源区域、输出类型等

        // 可选择性地提供缩略图和图像/流元数据
        writer.write(..., new IIOImage(..., image, ...), param);
    }
}
finally {
    // 在finally块中释放writer以避免内存泄漏
    writer.dispose();
}

有关更高级用法和如何使用ImageIO API的信息,我建议您阅读Oracle的Java Image I/O API指南。

Adobe剪切路径支持

import com.twelvemonkeys.imageio.path.Paths;

...

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

    // 对裁剪后的图像进行处理...
}

有关更多详细信息和示例代码,请参阅Wiki上的Adobe剪切路径支持。

使用ResampleOp

该库附带了一个重采样(图像调整大小)操作,包含许多不同的算法,可以以合理的速度提供出色的结果。

import com.twelvemonkeys.image.ResampleOp;

...

BufferedImage input = ...; // 要重采样的图像
int width, height = ...; // 新的宽度/高度

BufferedImageOp resampler = new ResampleOp(width, height, ResampleOp.FILTER_LANCZOS); // 一个不错的默认滤波器,更多信息请参阅类文档
BufferedImage output = resampler.filter(input, null);

使用DiffusionDither

该库附带了一个抖动操作,可用于使用Floyd-Steinberg误差扩散抖动将BufferedImage转换为IndexColorModel。

import com.twelvemonkeys.image.DiffusionDither;

...

BufferedImage input = ...; // 要抖动的图像

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

构建

下载项目(使用Git):

$ git clone git@github.com:haraldk/TwelveMonkeys.git

这应该会在当前目录中创建一个名为TwelveMonkeys的文件夹。切换到TwelveMonkeys文件夹,并执行以下命令进行构建。

构建项目(使用Maven):

$ mvn package

目前,推荐用于构建的JDK是Oracle JDK 8.x。

使用OpenJDK也可以构建,但由于色彩管理系统的一些微小差异,某些测试可能会失败。您需要禁用相关测试,或完全跳过测试进行构建。

由于单元测试需要相当多的内存来运行,您可能需要设置环境变量MAVEN_OPTS以为运行Maven的Java进程提供更多内存。我建议设置类似-Xmx512m -XX:MaxPermSize=256m的值。

可选地,您可以使用以下命令将项目安装到本地Maven仓库:

$ mvn install

安装

要安装插件, 可以使用Maven并将必要的依赖项添加到项目中, 或手动将所需的JAR包及其依赖项添加到类路径中。

ImageIO注册表和服务查找机制将确保插件可用。

要在运行时验证JPEG插件是否已安装并使用,可以使用以下代码:

Iterator<ImageReader> readers = ImageIO.getImageReadersByFormatName("JPEG");
while (readers.hasNext()) {
    System.out.println("reader: " + readers.next());
}

第一行应打印:

reader: com.twelvemonkeys.imageio.plugins.jpeg.JPEGImageReader@somehash

Maven依赖示例

要使用Maven依赖JPEG和TIFF插件,请在POM中添加以下内容:

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

    <!--
    可选依赖。仅在将ImageIO插件部署为Web应用程序的一部分时才需要。
    确保将IIOProviderContextListener添加到web.xml中,请参见上文。
    -->
    <dependency>
        <groupId>com.twelvemonkeys.servlet</groupId>
        <artifactId>servlet</artifactId>
        <version>3.10.1</version>
    </dependency>

    <!--
    或Jakarta版本,适用于Servlet API 5.0
    -->
    <dependency>
        <groupId>com.twelvemonkeys.servlet</groupId>
        <artifactId>servlet</artifactId>
        <version>3.10.1</version>
        <classifier>jakarta</classifier>
    </dependency>
</dependencies>

手动依赖示例

要在IDE或程序中依赖JPEG和TIFF插件,请将以下所有JAR添加到类路径中:

twelvemonkeys-common-lang-3.10.1.jar
twelvemonkeys-common-io-3.10.1.jar
twelvemonkeys-common-image-3.10.1.jar
twelvemonkeys-imageio-core-3.10.1.jar
twelvemonkeys-imageio-metadata-3.10.1.jar
twelvemonkeys-imageio-jpeg-3.10.1.jar
twelvemonkeys-imageio-tiff-3.10.1.jar

在Web应用程序中部署插件

由于ImageIO插件注册表(IIORegistry)是"VM全局"的,因此它与servlet上下文不能很好地配合使用。如果从WEB-INF/lib或classes文件夹加载插件,这一点尤其明显。除非在代码中的某处添加ImageIO.scanForPlugins(),否则插件可能根本无法使用。

此外,servlet上下文动态加载和卸载类(每个上下文使用新的类加载器)。如果重新启动应用程序,旧类默认情况下将永远保留在内存中(因为下次调用scanForPlugins时,是另一个ClassLoader扫描/加载类,因此它们在注册表中将是新实例)。如果尝试使用其中一个剩余的"旧"读取器进行读取,可能会发生奇怪的异常(例如在访问static final初始化字段时出现NullPointerException,或未初始化内部类的NoClassDefFoundError)。

为了解决发现问题和资源泄漏问题,强烈建议使用IIOProviderContextListener,它为Web应用程序实现了ImageIO插件的动态加载和卸载。

<web-app ...>

...

    <listener>
        <display-name>ImageIO service provider loader/unloader</display-name>
        <listener-class>com.twelvemonkeys.servlet.image.IIOProviderContextListener</listener-class>
    </listener>

...

</web-app>

不安装上下文监听器而从WEB-INF/lib加载插件是不受支持的,且无法正常工作。

上下文监听器不依赖于TwelveMonkeys ImageIO插件,也可以与JAI ImageIO或其他ImageIO插件一起使用。

另一个安全的选择是将JAR文件放在应用程序服务器的共享或公共lib文件夹中。

Jakarta Servlet支持

对于那些从旧的javax.servlet过渡到新的jakarta.servlet包的人,有一个单独的依赖项可用。它包含与上面提到的完全相同的servlet类,但是是针对新的Jakarta EE包构建的。该依赖项具有与以前相同的组名和标识符,但附加了jakarta分类器,以区别于非Jakarta包。

有关如何使用Maven启用它的信息,请参见Maven依赖示例。 Gradle或其他构建工具将有类似的选项。

将插件包含在"fat" JAR中

使用插件的推荐方式是通过Maven依赖或类似方式将JAR按原样包含在项目中。 重新打包对使用库不是必需的,也不推荐。

但是,如果您想创建一个"fat" JAR,或者出于某种原因想重新打包JAR,请记住ImageIO对插件的自动发现依赖于服务提供者接口(SPI)机制。 简而言之,每个JAR都包含一个名为META-INF/services的特殊文件夹,其中包含一个或多个文件, 通常是javax.imageio.spi.ImageReaderSpi和javax.imageio.spi.ImageWriterSpi。 这些文件在每个JAR中都以相同的名称存在, 因此,如果您只是将所有内容解压到一个文件夹或创建一个JAR,文件将被覆盖,行为将是未定义的(很可能最终只会安装一个插件)。 解决方案是确保所有同名文件都合并为一个单独的文件，包含每种类型的所有SPI信息。如果使用Maven Shade插件，你应该使用ServicesResourceTransformer来正确合并这些文件。你可能还想使用ManifestResourceTransformer来获取正确的供应商名称、版本信息等。其他"fat" JAR打包工具可能也有类似的机制来合并同名条目。

预构建二进制文件链接

最新版本（3.10.1）

可在Java 7上运行的最新版本是3.9.4。更高版本将需要Java 8或更高版本。

常用依赖项

• common-lang-3.10.1.jar
• common-io-3.10.1.jar
• common-image-3.10.1.jar

ImageIO依赖项

• imageio-core-3.10.1.jar
• imageio-metadata-3.10.1.jar

ImageIO插件

• imageio-bmp-3.10.1.jar
• imageio-hdr-3.10.1.jar
• imageio-icns-3.10.1.jar
• imageio-iff-3.10.1.jar
• imageio-jpeg-3.10.1.jar
• imageio-pcx-3.10.1.jar
• imageio-pict-3.10.1.jar
• imageio-pnm-3.10.1.jar
• imageio-psd-3.10.1.jar
• imageio-sgi-3.10.1.jar
• imageio-tga-3.10.1.jar
• imageio-thumbsdb-3.10.1.jar
• imageio-tiff-3.10.1.jar
• imageio-webp-3.10.1.jar
• imageio-xwd-3.10.1.jar

需要第三方库的ImageIO插件

• imageio-batik-3.10.1.jar

ImageIO的Photoshop路径支持

• imageio-clippath-3.10.1.jar

Servlet支持

• servlet-3.10.1.jar

许可证

本项目基于OSI批准的BSD许可证提供：

版权所有 (c) 2008-2022，Harald Kuhr
保留所有权利。

在源代码和二进制形式下重新分发和使用，无论是否修改，
都允许，前提是满足以下条件：

o 源代码的重新分发必须保留上述版权声明、本条件列表和以下免责声明。

o 以二进制形式重新分发必须在文档和/或随分发提供的其他材料中复制
  上述版权声明、本条件列表和以下免责声明。

o 未经特定事先书面许可，版权持有人和贡献者的名称
  不得用于认可或推广从本软件衍生的产品。

本软件由版权持有人和贡献者"按原样"提供，
不提供任何明示或暗示的保证，包括但不限于
对适销性和特定用途适用性的暗示保证。在任何情况下，
版权持有人或贡献者均不对任何直接、间接、偶然、
特殊、惩戒性或后果性损害（包括但不限于替代商品或
服务的采购；使用、数据或利润的损失；或业务中断）承担责任，
无论是基于合同、严格责任还是侵权行为（包括疏忽或其他原因），
即使已被告知可能发生此类损害的可能性。

常见问题

问：如何使用它？

答：最简单的方法是使用Maven、Gradle或其他具有依赖管理功能的构建工具来构建你自己的项目，只需添加你需要的特定插件的依赖项即可。如果你不使用这样的构建工具，请确保在类路径中包含所有必要的JAR包。请参阅上面的安装部分。

问：为了使用这些插件，我需要对代码做出哪些更改？

答：简短的回答是：不需要更改。对于基本用法，如ImageIO.read(...)或ImageIO.getImageReaders(...)，无需更改代码。大多数功能都可以通过标准的ImageIO API使用，我们非常注意不在不必要的地方引入额外的API。

如果你想使用某些格式的非常具体/高级功能，你可能需要使用特定的API，比如为由多个文件组成的SVG图像设置基本URL，或控制TIFF文件的输出压缩。

问：它是如何工作的？

答：TwelveMonkeys ImageIO项目包含ImageIO的插件。ImageIO使用服务查找机制在运行时发现插件。

你只需要确保在类路径中包含TwelveMonkeys ImageIO JAR包即可。

你可以在IIORegistry API文档中阅读更多关于注册表和查找机制的信息。

细节说明：TwelveMonkeys的JPEG、BMP和TIFF服务提供者重写了onRegistration方法，并利用IIOServiceRegistry的成对部分排序机制，确保它在Sun/Oracle提供的JPEGImageReader、BMPImageReader、TIFFImageReader以及OS X上Apple提供的TIFFImageReader之前安装。使用成对排序不会删除这些实现的任何功能，但在大多数情况下，你最终会使用TwelveMonkeys插件。

问：为什么不支持常见格式如GIF或PNG？

答：简单的回答是，ImageIO内置的对这些格式的支持已经足够好了。如果你在Java 7和8上寻求更好的PNG写入性能，请参见JDK9 PNG Writer Backport。

问：下一个版本什么时候发布？当前的发布计划是什么？

答：目标是每月发布一次，包含bug修复和小型新功能。每季度发布一次包含更多"主要"功能的版本。

问：我喜欢这个项目！我怎样才能提供帮助？ a：看看开放的问题，看看是否有你可以帮忙解决的问题，或者提供样本文件或创建测试用例。 你或你的组织也可以通过GitHub Sponsors成为赞助商。 提供资金将使我们能够花更多时间修复错误和实现新功能。

q：JAI呢？有几种格式已经被JAI支持了。

a：虽然JAI（特别是jai-imageio）支持一些相同的格式，但JAI存在一些主要问题。 最明显的是：

• 它没有积极开发。多年来没有修复任何问题。
• 要获得完整的格式支持，你需要本地库。 许多流行的平台/架构并不存在本地库，而且本地库并不开源。 某些环境可能还会阻止部署本地库，这使我们回到了原点。

q：JMagick或IM4Java呢？你不能直接使用现有的吗？

a：虽然这些是支持广泛格式的优秀库，但与ImageIO相比，基于ImageMagick的库有一些缺点：

• 没有真正的流支持，这些库只能处理文件。
• 无法通过标准Java2D/BufferedImage API轻松访问像素数据。
• 不是纯Java解决方案，需要特定系统的本地库。

我们做到了