安装 • 概述 • 示例脚本 • 读取或写入图像 • 操作图像 • 设置图像属性 • 获取图像属性 • 将图像与其重构进行比较 • 创建图像蒙太奇 • 处理 Blob • 直接访问图像像素 • 其他方法 • 异常处理 • 常量

PerlMagick 是 ImageMagick 的面向对象 Perl 接口。使用该模块可以在 Perl 脚本中读取、操作或写入图像或图像序列。这使它非常适合 Web CGI 脚本。要正确构建 PerlMagick，系统上必须安装 ImageMagick 6.5.5 或以上版本以及 Perl 5.005_02 或更高版本。

有许多有用的脚本可以向您展示 PerlMagick 的价值。您可以使用 MagickStudio 进行基于 Web 的图像操作和转换，或使用 L-systems 通过数学构造创建植物图像，最后还可以使用 WebMagick Image Navigator 浏览缩略图集合并选择要查看的图像。

您可以在 Web 浏览器中通过 ImageMagick Studio 试用 PerlMagick。或者，您可以查看精选 PerlMagick 函数的 示例。

安装

UNIX

PerlMagick 可以从您系统的 RPM 仓库中获取吗？例如，在我们的 CentOS 系统上，我们这样安装 PerlMagick：

yum install ImageMagick-perl

如果不能，您必须从 ImageMagick 源代码发行版安装 PerlMagick。下载最新的 源代码 发行版。

使用以下命令解包发行版：

tar xvzf ImageMagick.tar.gz

接下来配置并编译 ImageMagick：

cd ImageMagick-7.1.2-25
./configure -with-perl
make

如果 ImageMagick / PerlMagick 配置和编译都没有报错，您就可以将其安装到系统上了。安装需要管理员权限。要安装，请输入：

sudo make install

您可能需要配置动态链接器的运行时绑定：

sudo ldconfig /usr/local/lib

最后，要验证 PerlMagick 是否正确安装，请输入：

perl -MImage::Magick -le 'print Image::Magick->QuantumDepth'

恭喜，您已拥有可用的 ImageMagick 发行版，并准备好使用 PerlMagick 来 转换、合成或编辑 您的图像。

Windows XP / Windows 2000

系统上必须已经安装 ImageMagick。此外，还需要适用于 Windows 2000 的 ImageMagick 源代码发行版。您还必须拥有 Visual C++ 或 J++ 开发环境中的 nmake。将 \bin\IMagick.dll 和 \bin\X11.dll 复制到动态加载路径中的某个目录，例如 c:\perl\site\5.00502。

接下来，输入：

cd PerlMagick
perl Makefile.nt
nmake
nmake install

运行回归测试

要验证安装是否正确，请输入：

make test

在 Windows 下使用 nmake test。有几个演示脚本可以测试 PerlMagick 能够执行的许多功能。

要从构建文件夹运行测试，请使用 prove 工具：

prove --blib blib -I `pwd` -bv ./t/read.t



cd demo
make

现在您已准备好在 Perl 脚本中使用 PerlMagick 方法了。

概述

任何想要使用 PerlMagick 方法的脚本都必须首先在其命名空间内定义这些方法并实例化一个图像对象。可以这样做：

use Image::Magick;

$image = Image::Magick->new;

PerlMagick 能够感知量子（quantum）。实例化图像对象时，您可以请求特定的量子深度：

use Image::Magick::Q16;

$image = Image::Magick::Q16->new;

new() 方法采用与 SetAttribute 相同的参数。例如，

$image = Image::Magick->new(size=>'384x256');

接下来，您会想要读取一个图像或图像序列，对其进行操作，然后显示或写入它。PerlMagick 的输入和输出方法在“读取或写入图像”中定义。影响图像读取或写入方式的方法请参见“设置图像属性”。变换图像的方法列表请参见“操作图像”。“获取图像属性”说明如何检索图像的某个属性。在背景上将图像平铺为缩略图的细节请参见“创建图像蒙太奇”。最后，有些方法不能很好地归入上述任何类别。这些方法的列表请查看“其他方法”。

一旦您用完某个 PerlMagick 对象，就应该考虑销毁它。图像序列中的每个图像都存储在虚拟内存中。这可能累积到数兆字节（mebibyte）的内存。销毁 PerlMagick 对象后，内存将被释放供其他 Perl 方法使用。销毁对象的推荐方式是使用 undef：

undef $image;

要删除所有图像但保留 Image::Magick 对象，请使用

@$image = ();

最后，要从多图像序列中删除单个图像，请使用

undef $image->[$x];

下一节将说明如何使用各种 PerlMagick 方法来操作图像序列。

某些 PerlMagick 方法需要外部程序，例如 Ghostscript。这可能需要在您的 PATH 环境变量中指定明确的路径才能正常工作。例如（在 Linux 中），

$ENV{PATH}' . "='/../bin:/usr/bin:/usr/local/bin';

示例脚本

这是一个帮助您入门的示例脚本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

#!/usr/local/bin/perl
use Image::Magick;

my($image, $x);

$image = Image::Magick->new;
$x = $image->Read('girl.png', 'logo.png', 'rose.png');
warn "$x" if "$x";

$x = $image->Crop(geometry=>'100x100+100+100');
warn "$x" if "$x";

$x = $image->Write('x.png');
warn "$x" if "$x";

该脚本读取三个图像，将它们裁剪，并写入单个图像作为 GIF 动画序列。在许多情况下，您可能想要访问序列中的单个图像。下一个示例说明如何做到这一点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

#!/usr/local/bin/perl
use Image::Magick;

my($image, $p, $q);

$image = new Image::Magick;
$image->Read('x1.png');
$image->Read('j*.jpg');
$image->Read('k.miff[1, 5, 3]');
$image->Contrast();
for ($x = 0; $image->[$x]; $x++)
{
  $image->[$x]->Frame('100x200') if $image->[$x]->Get('magick') eq 'GIF';
  undef $image->[$x] if $image->[$x]->Get('columns') < 100;
}
$p = $image->[1];
$p->Draw(stroke=>'red', primitive=>'rectangle', points=>20,20 100,100');
$q = $p->Montage();
undef $image;
$q->Write('x.miff');

假设您想从一块 100 x 100 像素的白色画布开始，中心有一个红色像素。尝试

$image = Image::Magick->new;
$image->Set(size=>'100x100');
$image->ReadImage('canvas:white');
$image->Set('pixel[49,49]'=>'red');

这里我们将 (1,1) 处红色分量的强度减半：

@pixels = $image->GetPixel(x=>1,y=>1);
$pixels[0]*=0.5;
$image->SetPixel(x=>1,y=>1,color=>\@pixels);

或者假设您想将彩色图像转换为灰度：

$image->Quantize(colorspace=>'gray');

让我们用台北 TrueType 字体为图像添加注释：

$text = 'Works like magick!';
$image->Annotate(font=>'kai.ttf', pointsize=>40, fill=>'green', text=>$text);

也许您想从图像中提取所有像素强度并将它们写入 STDOUT：

@pixels = $image->GetPixels(map=>'I', height=>$height, width=>$width, normalize=>true);
binmode STDOUT;
print pack('B*',join('',@pixels));

使用 PerlMagick 对象还可以做的其他巧妙的事情包括

$i = $#$p"+1";   # return the number of images associated with object p
push(@$q, @$p);  # push the images from object p onto object q
@$p = ();        # delete the images but not the object p
$p->Convolve([1, 2, 1, 2, 4, 2, 1, 2, 1]);   # 3x3 Gaussian kernel

读取或写入图像

使用下列方法来读取、写入或显示图像或图像序列：

为方便起见，Write()、Display() 和 Animate() 方法可以采用 SetAttribute 知道的任何参数。例如，

$image->Write(filename=>'image.png', compression=>'None');

将 - 用作 Read() 方法的文件名以从标准输入读取，或用作 Write() 方法的文件名以写入标准输出：

binmode STDOUT;
$image->Write('png:-');

要从 PERL 文件句柄读取 GIF 格式的图像，请使用：

$image = Image::Magick->new;
open(IMAGE, 'image.gif');
$image->Read(file=>\*IMAGE);
close(IMAGE);

要将 PNG 格式的图像写入 PERL 文件句柄，请使用：

$filename = "image.png";
open(IMAGE, ">$filename");
$image->Write(file=>\*IMAGE, filename=>$filename);
close(IMAGE);

请注意，如果 ImageMagick 与 ActiveState Perl 发行版之间的 C 运行时库版本不同，或者某个 DLL 是使用 /MT 选项链接的，那么在 Windows 上从 Perl 文件句柄读取或写入可能会失败。说明请参见 Potential Errors Passing CRT Objects Across DLL Boundaries。

如果文件名中出现 %0Nd、%0No 或 %0Nx，它将被解释为 printf 格式说明，并且该说明会被替换为场景编号的指定十进制、八进制或十六进制编码。例如，

image%03d.miff

会转换文件 image000.miff、image001.miff 等等。

您可以选择性地为任何方法名添加 Image。例如，ReadImage() 是 Read() 方法的别名。

操作图像

一旦您（例如用 ReadImage() 方法）创建了图像，您可能想要对其进行操作。下面是 PerlMagick 提供给您的所有图像操作方法的列表。有精选 PerlMagick 方法的 示例。这是一个调用图像操作方法的示例：

$image->Crop(geometry=>'100x100+10+20');
$image->[$x]->Frame("100x200");

下面是您可以调用的其他图像操作方法的列表：

请注意，geometry 参数是 width 和 height 参数的简写（例如 geometry=>'106x80' 等价于 width=>106, height=>80）。

您可以在 Annotate() 和 Draw() 中都指定 @filename。这会从磁盘上的文件读取文本或图形基元指令。例如，

image->Draw(fill=>'red', primitive=>'rectangle',
 points=>'20,20 100,100  40,40 200,200  60,60 300,300');

等价于

$image->Draw(fill=>'red', primitive=>'@draw.txt');

其中 draw.txt 是磁盘上的一个文件，内容如下：

rectangle 20, 20 100, 100
rectangle 40, 40 200, 200
rectangle 60, 60 300, 300

Annotate()、Comment()、Draw() 和 Label() 方法的 text 参数可以通过嵌入以下特殊格式字符来包含图像文件名、类型、宽度、高度或其他图像属性：

%b   文件大小
%c   注释
%d   目录
%e   文件名扩展名
%f   文件名
%g   页面几何
%h   高度
%i   输入文件名
%k   唯一颜色数
%l   标签
%m   magick
%n   场景数
%o   输出文件名
%p   页码
%q   量子深度
%r   图像类与色彩空间
%s   场景编号
%t   去除目录与扩展名的文件名
%u   唯一临时文件名
%w   宽度
%x   x 分辨率
%y   y 分辨率
%z   图像深度
%C   图像压缩类型
%D   图像 dispose 方法
%H   页面高度
%Q   图像压缩质量
%T   图像延迟
%W   页面宽度
%X   页面 x 偏移
%Y   页面 y 偏移
%@   边界框
%#   签名
%%   百分号
\n   换行
\r   回车

例如，

text=>"%m:%f %wx%h"

对于标题为 bird.miff、宽度为 512、高度为 480 的图像，会生成注释 MIFF:bird.miff 512x480。

您可以选择性地为任何方法名添加 Image。例如，TrimImage() 是 Trim() 方法的别名。

上面列出的大多数属性在 magick 中都有对应项。这些属性的更详细说明请参见相关文档。

设置图像属性

使用 Set() 方法设置图像属性。例如，

$image->Set(dither=>'True');
$image->[$x]->Set(delay=>3);

本示例使用 'True'，而本文档写作 '{True, False}' 的地方，您可以使用不区分大小写的字符串 'True'、'False'，也可以使用整数 1 和 0。

当您对布尔属性调用 Get() 时，Image::Magick 返回 1 或 0，而不是字符串。

下面是您可以设置的所有图像属性的列表：

请注意，geometry 参数是 width 和 height 参数的简写（例如 geometry=>'106x80' 等价于 width=>106, height=>80）。

SetAttribute() 是 Set() 方法的别名。

上面列出的大多数属性在 magick 中都有对应项。这些属性的更详细说明请参见相关文档。

获取图像属性

使用 Get() 方法获取图像属性。例如，

($a, $b, $c) = $image->Get('colorspace', 'magick', 'adjoin');
$width = $image->[3]->Get('columns');

除了“设置图像属性”中列出的所有属性外，您还可以获取以下额外属性：

GetAttribute() 是 Get() 方法的别名。

上面列出的大多数属性在 magick 中都有对应项。这些属性的更详细说明请参见相关文档。

将图像与其重构进行比较

使用 Compare() 方法以数学和视觉方式注释图像与其重构之间的差异。该方法支持以下参数：

在此示例中，我们将 ImageMagick 徽标与一个锐化后的重构进行比较：

use Image::Magick;

$logo=Image::Magick->New();
$logo->Read('logo:');
$sharp=Image::Magick->New();
$sharp->Read('logo:');
$sharp->Sharpen('0x1');
$difference=$logo->Compare(image=>$sharp, metric=>'rmse');
print $difference->Get('error'), "\n";
$difference->Display();

除了报告的约 0.024 的均方根误差外，还会显示一幅差异图像，以便您直观地辨别图像之间的差异。

创建图像蒙太奇

使用 Montage() 方法通过组合若干个独立图像来创建一幅合成图像。这些图像在合成图像上平铺排列，图像名称可选地显示在各个小块的正下方。例如，

$image->Montage(geometry=>'160x160', tile=>'2x2', texture=>'granite:');

下面是您可以设置的 Montage() 参数列表：

请注意，geometry 参数是 width 和 height 参数的简写（例如 geometry=>'106x80' 等价于 width=>106, height=>80）。

MontageImage() 是 Montage() 方法的别名。

上面列出的大多数属性在 montage 中都有对应项。这些属性的更详细说明请参见相关文档。

处理 Blob

blob 包含直接在内存中（而非磁盘上）表示某种特定图像格式的数据。PerlMagick 支持任何这些图像 格式 的 blob，并提供将 blob 转换为某种特定图像格式或从中转换的方法。

ImageToBlob() 以各自的格式返回图像数据。然后您可以打印它、将它保存到 ODBC 数据库、写入文件，或管道传输到显示程序：

@blobs = $image->ImageToBlob();
open(DISPLAY,"| display -") || die;
binmode DISPLAY;
print DISPLAY $blobs[0];
close DISPLAY;

BlobToImage() 方法返回从所提供的 blob 转换而来的图像或图像序列：

@blob=$db->GetImage();
$image=Image::Magick->new(magick=>'jpg');
$image->BlobToImage(@blob);

直接访问图像像素

使用以下方法来直接访问图像像素：

其他方法

Append() 方法连接一组图像。例如，

$p = $image->Append(stack=>{true,false});

连接与对象 $image 关联的所有图像。默认情况下，图像从左到右堆叠。将 stack 设为 True 可使它们从上到下堆叠。

Clone() 方法复制一组图像。例如，

$q = $p->Clone();

将对象 $p 的所有图像复制到 $q。您可以将此方法用于单图像或多图像序列。

Coalesce() 在尊重任何页面偏移和处置方法的同时合成一组图像。GIF、MIFF 和 MNG 动画序列通常以一个图像背景开始，后续每个图像在尺寸和偏移上有所不同。返回一个新的图像序列，其中所有图像都与第一个图像的虚拟画布大小相同，并与序列中的下一个图像合成。例如，

$q = $p->Coalesce();

ComplexImages() 方法对图像序列执行复数运算。例如，

$p = $image->ComplexImages('conjugate');

EvaluateImages() 方法对一组图像应用算术、逻辑或关系表达式。例如，

$p = $image->EvaluateImages('mean');

对与对象 $image 关联的所有图像求平均。

Features() 方法返回图像中每个通道在四个方向（水平、垂直、左右对角线）上、针对指定距离的特征。这些特征包括角二阶矩、对比度、相关性、平方和：方差、逆差矩、和均值、和方差、和熵、熵、差方差、差熵、相关性信息度量 1、相关性信息度量 2 以及最大相关系数。值按 RGB、CMYK、RGBA 或 CMYKA 顺序排列（取决于图像类型）。

@features = $image->Features(1);

Flatten() 方法将一组图像平坦化并返回。例如，

$p = $images->Flatten(background=>'none');
$p->Write('flatten.png');

该图像序列被一个单一图像替换，这个图像由将第一个图像之后的每个图像叠加到第一个图像上而创建。

Fx() 方法对一组图像应用数学表达式并返回结果。例如，

$p = $image->Fx(expression=>'(g+b)/2.0',channel=>'red');
$p->Write('fx.miff');

用绿色和蓝色通道的平均值替换红色通道。

有关此方法的详细讨论，请参见 FX，特殊效果图像运算符。

Histogram() 返回图像中的唯一颜色以及每种颜色的计数。返回的值是红、绿、蓝、不透明度和计数值的数组。

Morph() 方法对一组图像进行变形（morph）。图像的像素和尺寸都被线性插值，从而呈现出从一个图像到下一个图像渐变（meta-morphosis）的外观：

$p = $image->Morph(frames=>_integer_);

其中 frames 是要生成的中间图像数量。默认值为 1。

Mosaic() 从图像序列创建马赛克。

Mogrify() 方法是图像操作方法（操作图像）的单一入口点。参数是方法名称，后跟该方法可能需要的任何参数。例如，下面这些调用是等价的：

$image->Crop('340x256+0+0');
$image->Mogrify('crop', '340x256+0+0');

MogrifyRegion() 方法对图像的某个区域应用变换。它类似于 Mogrify()，但以区域几何开头。例如，假设您想提亮图像中位于位置 (40, 50) 的 100x100 区域：

$image->MogrifyRegion('100x100+40+50', 'modulate', brightness=>50);

PerceptualHash() 将视觉上相同的图像映射到相同或相似的哈希值——在图像检索、认证、索引或副本检测以及数字水印中很有用。对于每个通道以及 sRGB 和 HCLp 色彩空间，返回 7 个哈希值。例如，对于一幅 sRGB 图像，预计有 42 个感知哈希值。

@phash = $image->PerceptualHash();

Ping() 是一个便捷方法，无需将图像读入内存即可返回有关图像的信息。它返回图像的宽度、高度、以字节为单位的文件大小以及文件格式。您可以指定多个文件名，但只能指定一个文件句柄：

($width, $height, $size, $format) = $image->Ping('logo.png');
($width, $height, $size, $format) = $image->Ping(file=>\*IMAGE);
($width, $height, $size, $format) = $image->Ping(blob=>$blob);

这是一种更高效、内存消耗更少的方式来查询图像是否存在及其特征是什么。

Poly() 从图像序列和相应的项（系数与次数对）构建一个多项式：

$p = $image->Poly([0.5,1.0,0.25,2.0,1.0,1.0]);

PreviewImage() 平铺指定图像的 9 个缩略图，每个缩略图以不同强度应用某种图像处理操作。这有助于为某个特定的图像处理操作确定合适的参数。从以下操作中选择：Rotate, Shear, Roll, Hue, Saturation, Brightness, Gamma, Spiff, Dull, Grayscale, Quantize, Despeckle, ReduceNoise, AddNoise, Sharpen, Blur, Threshold, EdgeDetect, Spread, Solarize, Shade, Raise, Segment, Swirl, Implode, Wave, OilPaint, CharcoalDrawing, JPEG。这是一个示例：

$preview = $image->Preview('Gamma');
$preview->Display();

要完全控制文本定位，您需要字体度量信息。请使用

($x_ppem, $y_ppem, $ascender, $descender, $width, $height, $max_advance) =
  $image->QueryFontMetrics(_parameters_);

其中 parameters 是 Annotate 方法的任意参数。返回的值如下：

1. 字符宽度
2. 字符高度
3. 上伸部（ascender）
4. 下伸部（descender）
5. 文本宽度
6. 文本高度
7. 最大水平步进（advance）
8. 边界：x1
9. 边界：y1
10. 边界：x2
11. 边界：y2
12. 原点：x
13. 原点：y

使用 QueryMultilineFontMetrics() 获取多行文本的最大文本宽度和高度。

不带参数调用 QueryColor() 以返回已知颜色名称的列表，或指定一个或多个颜色名称以获取这些属性：红、绿、蓝以及不透明度值。

@colors = $image->QueryColor();
($red, $green, $blue) = $image->QueryColor('cyan');
($red, $green, $blue, $alpha) = $image->QueryColor('#716baeff');

QueryColorname() 接受一个颜色值并返回其相应的名称或十六进制值；

$name = $image->QueryColorname('rgba(80,60,0,0)');

不带参数调用 QueryFont() 以返回已知字体的列表，或指定一个或多个字体名称以获取这些属性：字体名称、描述、字族、样式、拉伸、字重、编码、字铸厂（foundry）、格式、度量以及字形值。

@fonts = $image->QueryFont();
$weight = ($image->QueryFont('Helvetica'))[5];

不带参数调用 QueryFormat() 以返回已知图像格式的列表，或指定一个或多个格式名称以获取这些属性：adjoin、blob 支持、raw、解码器、编码器、描述以及模块。

@formats = $image->QueryFormat();
($adjoin, $blob_support, $raw, $decoder, $encoder, $description, $module) =
  $image->QueryFormat('gif');

用图像格式名称调用 MagickToMime() 以获取其 MIME 类型，例如从 tif 得到 image/tiff。

$mime = $image->MagickToMime('tif');

使用 RemoteCommand() 向一个已经运行的 display 或 animate 应用程序发送命令。唯一的参数是要显示或动画播放的图像文件的名称。

$image->RemoteCommand('image.jpg');

Smush() 方法将一组图像紧贴着拼合在一起。例如，

$p = $image->Smush(stack=>{true,false},offset=>integer);

将与对象 $image 关联的所有图像紧贴着拼合。默认情况下，图像从左到右紧贴拼合。将 stack 设为 True 可使它们从上到下紧贴拼合。

Statistics() 返回图像中每个通道的图像统计信息。返回的值是深度、最小值、最大值、平均值、标准差、峰度、偏度和熵值的数组，按 RGB、CMYK、RGBA 或 CMYKA 顺序排列（取决于图像类型）。

@statistics = $image->Statistics();

最后，Transform() 方法接受一个完全限定的几何说明，用于裁剪或调整一个或多个图像的尺寸。例如，

$p = $image->Transform(crop=>'100x100+0+0');

您可以选择性地为上面任何方法名添加 Image。例如，PingImage() 是 Ping() 方法的别名。

异常处理

所有 PerlMagick 方法在成功时返回一个未定义的字符串上下文。如果发生任何问题，错误会作为一个嵌入数值状态码的字符串返回。小于 400 的状态码是警告。这意味着操作未能完成，但在某种程度上是可恢复的。大于或等于 400 的数值码是错误，表示操作完全失败。下面是不同方法返回异常的方式：

返回数字的方法（例如 Read()、Write()）：

$x = $image->Read(...);
warn "$x" if "$x";      # print the error message
$x =~ /(\d+)/;
print $1;               # print the error number
print 0+$x;             # print the number of images read

对图像进行操作的方法（例如 Resize()、Crop()）：

$x = $image->Crop(...);
warn "$x" if "$x";      # print the error message
$x =~ /(\d+)/;
print $1;               # print the error number

返回图像的方法（EvaluateSequence()、Montage()、Clone()）应这样检查错误：

$x = $image->Montage(...);
warn "$x" if !ref($x);  # print the error message
$x =~ /(\d+)/;
print $1;               # print the error number

这是一个错误消息示例：

Error 400: Memory allocation failed

请查看 错误和警告代码 的完整列表。

下面说明如何使用数值状态码：

$x = $image->Read('rose.png');
$x =~ /(\d+)/;
die "unable to continue" if ($1 == ResourceLimitError);

常量

PerlMagick 包含以下常量：

BlobError
BlobWarning
CacheError
CacheWarning
CoderError
CoderWarning
ConfigureError
ConfigureWarning
CorruptImageError
CorruptImageWarning
DelegateError
DelegateWarning
DrawError
DrawWarning
ErrorException
FatalErrorException
FileOpenError
FileOpenWarning
ImageError
ImageWarning
MissingDelegateError
MissingDelegateWarning
ModuleError
ModuleWarning
Opaque
OptionError
OptionWarning
QuantumDepth
QuantumRange
RegistryError
RegistryWarning
ResourceLimitError
ResourceLimitWarning
StreamError
StreamWarning
Success
Transparent
TypeError
TypeWarning
WarningException
XServerError
XServerWarning

您可以这样访问它们：

Image::Magick->QuantumDepth