1.基于ImageMagic实现图片编辑器

一灰灰blogQuickMediaimagic-plugin约 3200 字大约 11 分钟

基于 ImageMagic 实现图片编辑器

用 Java 做图片的旋转、裁剪、压缩、加水印,是很多业务系统都绕不开的需求。本文介绍 QuickMedia 中的 imagic-plugin,它基于 ImageMagick 对这些常见的图片编辑操作做了链式封装,一行代码即可完成复合编辑。

I. 问题背景

在 Java 中做图片编辑,常见的姿势有两种:

  1. 原生 JDK:BufferedImage + Graphics2D,什么都能画,但什么都得自己算
  2. Thumbnailator 等封装库:基于 AWT 的二次封装,上手简单

但这两条路都有一些老大难问题:

  • jpg 图片变红:ImageIO 解析部分 CMYK 色彩空间的 jpeg 时会出现颜色异常
  • 精度丢失:Java 侧处理的图片质量,和原图相比往往会有肉眼可见的损失
  • 失真:颜色变化、alpha 值变化等问题(jpg 变红的兼容问题可参考兼容ImageIO读取jpeg图片变红open in new window)

而 ImageMagick 是 C++ 实现的专业图片处理工具,命令行一把梭,稳定、支持的操作接口非常丰富、处理质量有保障,很多图片服务底层都是它。缺点也很明显:命令行参数又长又难记,而且需要在服务器上装环境。

imagic-plugin 做的事情,就是把 ImageMagick 的常用编辑操作封装成 Builder 模式的链式调用,对外的使用姿势尽可能简洁,同时支持多种输入输出形态。

II. 环境准备

imagic-plugin 底层通过 im4java 以命令行方式调用 ImageMagick,所以使用前必须在本机(或部署服务器)安装 ImageMagick,这是和 QuickMedia 其他纯 Java 插件最大的区别。

1. linux 安装

# 依赖安装
yum install libjpeg-devel
yum install libpng-devel
yum install libwebp-devel

# 也可以使用源码方式安装依赖
# 安装jpeg:  wget ftp://223.202.54.10/pub/web/php/libjpeg-6b.tar.gz
# 安装webp:  wget http://www.imagemagick.org/download/delegates/libwebp-0.5.1.tar.gz
# 安装png:   wget http://www.imagemagick.org/download/delegates/libpng-1.6.24.tar.gz

# 下载并安装 ImageMagick
wget http://www.imagemagick.org/download/ImageMagick.tar.gz
tar -zxvf ImageMagick.tar.gz
cd ImageMagick-7.0.7-28
./configure; sudo make; sudo make install

2. mac 安装

sudo brew install jpeg
sudo brew install libpng
sudo brew install libwebp
sudo brew install ImageMagick

3. windows 安装

直接到 ImageMagick 官网下载安装包(建议选 ImageMagick-7.x 的 Q16 版本),一路 next 安装时,注意**勾选"将安装目录加入 PATH"**的选项。

4. 验证安装

安装完毕之后,命令行执行:

$ convert --version

Version: ImageMagick 7.0.7-28 Q16 x86_64 2018-04-17 http://www.imagemagick.org
Copyright: © 1999-2018 ImageMagick Studio LLC
License: http://www.imagemagick.org/script/license.php
Features: Cipher DPC HDRI OpenMP
Delegates (built-in): fontconfig freetype jng jpeg lzma png webp x xml zlib

能看到版本号和 Delegates 列表,就说明环境 OK 了。

两个常见的坑:

  • Windows 下 convert 命令冲突:Windows 系统自带一个 C:\Windows\System32\convert.exe(磁盘格式转换工具),和 ImageMagick 的 convert 同名。如果 convert --version 输出的是"FAT 转换"之类的提示,说明 PATH 命中了系统自带的那个,需要调整 PATH 顺序让 ImageMagick 目录排在前面(ImageMagick 7 也可用 magick --version 验证)。由于 java 进程继承的是启动时的 PATH,改完环境变量记得重启 IDE/服务。
  • linux 下提示缺少共享库:把 /usr/local/lib 加入 /etc/ld.so.conf 后执行 ldconfig(或临时 export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH);若 configure 阶段一直找不到 png 依赖,可安装 pkg-config(http://pkgconfig.freedesktop.org/releases/pkg-config-0.28.tar.gzopen in new window )后再试。

安装过程的更详细记录可以参考官方说明:imagemagic安装open in new window

III. 依赖引入

imagic-plugin 依赖 base-plugin,使用时需要一起引入。外部如需使用,请先添加下面的仓库源:

<repositories>
    <repository>
        <id>yihui-maven-repo</id>
        <url>https://raw.githubusercontent.com/liuyueyi/maven-repository/master/repository</url>
    </repository>
</repositories>

jar 包引入,请注意使用最新的版本:

<dependency>
    <groupId>com.github.hui.media</groupId>
    <artifactId>image-plugin</artifactId>
    <version>2.5.2</version>
</dependency>

IV. 快速上手

先来一个最简单的可运行示例:加载一张图片,旋转 90 度,输出为 BufferedImage。

@Test
public void testRotateImg() {
    try {
        InputStream stream = FileReadUtil.getStreamByFileName("blogInfoV2.png");
        BufferedImage img = ImgWrapper.of(stream).rotate(90).asImg();
        System.out.println("----" + img);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

整个使用姿势就是一个链式调用,可以拆成三段理解:

  • ImgWrapper.of(xxx):指定输入源(classpath 资源 / 远程图片 / 输入流),返回一个 Builder 对象
  • 中间一串 xxx():具体的编辑操作,如 rotate、crop、scale、water、board 等,可以链式叠加
  • asXxx():表示输出结果,当前支持文件、InputStream、byte[]、BufferedImage 等多种输出方式

注意中间的编辑操作至少要有一个,否则会抛出 ImgOperateException("operates null!")。

V. 输入源的三种姿势

ImgWrapper.of() 有三个重载,对应三种输入源:

1. of(String):classpath 资源

// blogInfoV2.png 放在 src/main/resources 或 src/test/resources 下
BufferedImage img = ImgWrapper.of("blogInfoV2.png").flip().asImg();

注意:of(String) 内部是通过类加载器 getResource 来定位文件的,所以它找的是 classpath 下的资源(相对路径),而不是磁盘上的任意路径,直接传绝对路径会找不到文件;另外以 http 开头的字符串会被直接拒绝,网络图片请用下面的 URI 方式。

2. of(URI):远程图片

private static final String url = "http://a.hiphotos.baidu.com/image/pic/item/14ce36d3d539b6006a6cc5d0e550352ac65cb733.jpg";

// 远程图片会先下载到临时目录,再做后续编辑
ImgWrapper.of(URI.create(url)).crop(10, 20, 500, 500).toFile();

3. of(InputStream):输入流

处理磁盘上的本地文件时,推荐先转成输入流。QuickMedia 的 base-plugin 提供的 FileReadUtil.getStreamByFileName 同时支持网络地址、绝对路径、~/ 用户目录和 classpath 相对路径,用它来桥接非常方便:

// 绝对路径的本地文件
InputStream stream = FileReadUtil.getStreamByFileName("/Users/yihui/Desktop/12.jpg");
BufferedImage img = ImgWrapper.of(stream).board(10, 10, "red").asImg();

// 当然,直接 new FileInputStream(file) 也是可以的

VI. 输出结果的几种方式

输出方式都是 Builder 上的方法,任选其一调用:

方法说明
toFile()处理结果保存为文件,文件名自动生成为 源文件名_时间戳_out.格式,放在临时目录下,返回完整文件路径
toFile(outputFilename)保存为指定路径的文件,返回该路径
asStream()输出 InputStream
asBytes()输出 byte[]
asImg()输出 BufferedImage
// 直接落盘
ImgWrapper.of(URI.create(url)).crop(0, 0, 1280, 853).toFile("/tmp/quickmedia/scale_3840x5760.jpg");

// 输出流(可用于直接写 http 响应)
InputStream stream = ImgWrapper.of(URI.create(url)).crop(0, 0, 300, 500).asStream();
BufferedImage img = ImageIO.read(stream);

// 输出字节数组
byte[] bytes = ImgWrapper.of(stream).rotate(90).asBytes();

实现层面,asStream/asBytes/asImg 内部都是先把处理结果落成一个临时文件,再读出来封装成对应形态,所以不用担心它们和 toFile 行为不一致。

另外一个有用的配置是 setOutputFormat(String),用于指定输出图片格式(JPEG、PNG、GIF...),默认为 jpg:

// 输出 png 格式,避免 jpg 有损压缩带来的质量损失
ImgWrapper.of(stream).rotate(90).setOutputFormat("png").toFile();

VII. 编辑操作 API 说明

下面逐个过一遍 Builder 支持的编辑操作。

1. crop 裁剪

// 从 (10, 20) 坐标开始,裁出 500x500 的区域
ImgWrapper.of(URI.create(url)).crop(10, 20, 500, 500).toFile();

四个参数分别是:起始坐标 x、y,以及裁剪区域的宽 width、高 height,坐标原点在图片左上角。

2. rotate 旋转

// 旋转 90 度
ImgWrapper.of(stream).rotate(90).asImg();

// 任意角度也可以
ImgWrapper.of(stream).rotate(30).asImg();

参数是角度(double 类型),正数为顺时针。底层对 180 度旋转做了一个小兼容(源码中有注释:180 度旋转后裁图会出现 bug,实际执行时会给角度加上 0.01 度绕过 ImageMagick 的这个问题),使用时无感知。

3. scale 缩放/压缩

scale 有两组重载,覆盖了图片编辑中最常见的几种场景:

// 1) 指定宽高缩放,宽高传 null 表示等比缩放
//    下面表示等比缩放到宽 1125
ImgWrapper.of(URI.create(url)).scale(1125, null, null).toFile("/tmp/quickmedia/scale_out1.jpg");

// 2) quality 指定图片精度 1~100,配合 jpg 输出控制压缩质量
//    同样是缩放到宽 1125,精度 50 的文件会比精度 80 的小很多
ImgWrapper.of(URI.create(url)).scale(1125, null, 50).toFile("/tmp/quickmedia/scale_out2.jpg");
ImgWrapper.of(URI.create(url)).scale(1125, null, 80).toFile("/tmp/quickmedia/scale_out3.jpg");

// 3) 按比例缩放,1.0 表示不缩放,0.5 表示缩放为一半
ImgWrapper.of(URI.create(url)).scale(0.5, null).toFile("/tmp/quickmedia/scale_out4.jpg");
ImgWrapper.of(URI.create(url)).scale(0.5, 80).toFile("/tmp/quickmedia/scale_out12.jpg");

// 4) 强制按照给定的宽高拉伸(不保持宽高比),需要使用四参数重载
ImgWrapper.of(URI.create(url)).scale(200, 200, null, true).toFile("/tmp/quickmedia/force.jpg");

归纳一下:scale(w, h, quality) 指定目标宽高,宽或高传 null 则等比缩放;scale(w, h, quality, forceScale) 在 forceScale = true 时强制按给定宽高拉伸;scale(radio, quality) 按比例缩放,0.5 即缩为原图一半。

对"压缩"这个场景来说,scale + quality 的组合就是传统意义上的图片压缩:既控制了尺寸,又通过精度参数控制了文件体积。

4. flip / flop 翻转与镜像

这两个方法都不带参数:

// flip: 上下翻转(倒影效果)
ImgWrapper.of(localFile).flip().asImg();

// flop: 左右翻转,即镜像
ImgWrapper.of(localFile).flop().asImg();

5. board 添加边框

// 添加 10x10 的红色边框
ImgWrapper.of(localFile).board(10, 10, "red").asImg();

参数:边框宽 width、边框高 height(上下左右各加这么多像素),以及填充色 color。颜色是字符串形式,支持 red、blue 这类颜色名,也支持 #ffffff 这样的 HTML 色值。若不设置,边框宽高默认 3,颜色默认 #ffffff。

6. water 添加水印

// 在 (100, 100) 坐标处叠加水印图,水印图默认按 png 处理
ImgWrapper.of(URI.create(url))
        .board(10, 10, "red")
        .water(localFile, 100, 100)
        .asImg();

// 水印图为输入流时,显式指定图片类型
ImgWrapper.of(URI.create(url)).water(inputStream, "png", 100, 100).asImg();
  • 第一个参数 water 非常灵活,可以是 classpath 资源名、URI、InputStream 中的任意一种
  • 第二组参数 imgType 是水印图片的类型,当传入 InputStream 时需要显式指定(其他情况可以忽略)
  • x、y 是水印在目标图片上的绘制坐标

两个限制需要注意:目前只支持叠加一次水印(链上写多个 water,只有第一个生效);water() 前面如果还有别的操作,水印会叠加在中间结果上。

VIII. 复合操作

前面所有的操作都是链式 API,天然支持叠加,执行顺序就是书写顺序。官方测试中的一个复合 case:

/**
 * 复合操作
 */
@Test
public void testOperate() {
    BufferedImage img;
    try {
        img = ImgWrapper.of(localFile)
                .board(10, 10, "red")   // 先加红色边框
                .flip()                 // 再上下翻转
                .rotate(180)            // 旋转 180 度
                .crop(0, 0, 1200, 500)  // 最后裁剪出 1200x500 的区域
                .asImg();
        System.out.println("--- " + img);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

/**
 * 远程图片 + 复合操作 + 水印
 */
@Test
public void testWater() {
    BufferedImage img;
    try {
        img = ImgWrapper.of(URI.create(url))
                .board(10, 10, "red")
                .water(localFile, 100, 100)
                .asImg();
        System.out.println("--- " + img);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

再来看一个偏业务的例子——典型的"封面图处理"流水线:远程图片 → 裁剪成固定尺寸 → 等比压缩 → 加水印 → 输出 png 字节数组:

public byte[] coverProcess(String imgUrl) throws Exception {
    return ImgWrapper.of(URI.create(imgUrl))
            // 先裁剪成 1200x630 的封面比例
            .crop(0, 0, 1200, 630)
            // 等比压缩到宽 750,精度 80
            .scale(750, null, 80)
            // 右下角叠 logo 水印
            .water("logo.png", 660, 580)
            // 输出 png,规避 jpg 变红等问题
            .setOutputFormat("png")
            .asBytes();
}

复合操作的两个注意点:

  1. 顺序很重要。裁剪的坐标系基于当时的图片状态,先 rotate(90) 再 crop(x, y, w, h),此时的 x、y、w、h 是旋转后图片上的坐标,和原图坐标不是一回事
  2. 每个操作在底层都会校验参数的合法性(如 crop 必须四个参数齐全),不合法的操作会被直接跳过;如果跳过之后一个有效操作都不剩,会抛出异常

IX. 小结

本文介绍了 imagic-plugin 的完整使用姿势:ImageMagick 环境安装与验证、依赖引入、三种输入源、多种输出形态,以及各编辑 API 的逐个说明和复合操作实战。

如果说有什么使用心得,就是两句话:环境装好(注意 Windows 的 convert 命令冲突),输出格式尽量选 png(规避 jpg 的各种老问题)。

项目地址:

相关参考:

Loading...