../index.html
[ImageMagick]
http://www.imagemagick.org/
[sponsor]
../index.html
../index.html
#main
Skip to page contents
[
../index.html
About ImageMagick
../www/command-line-tools.html
Command-line Tools
../www/api.html
Program Interfaces
]
[
../www/install-source.html
Install from Source
../www/binary-releases.html
Binary Releases
../www/resources.html
Resources
]
[
../www/download.html
Downloads
]
[
../www/links.html
Links
]
[
../www/sponsors.html
Sponsors
http://www.georeviews.com
Consumer Reviews
and Ratings
]
[
#installation
Installation
|
#overview
Overview
|
#example
Example Script
|
#read
Read or Write an Image
|
#manipulate
Manipulate an Image
|
#set-attribute
Set an Image Attribute
|
#get-attribute
Get an Image Attribute
|
#montage
Create an Image Montage
|
#blobs
Working with Blobs
|
#miscellaneous
Miscellaneous Methods
|
#exceptions
Handling Exceptions
]
../www/download.html
PerlMagick
is an objected-oriented
http://www.perl.com/perl/
Perl
interface to ImageMagick. Use the module to read, manipulate, or write an image or image sequence from within a Perl script. This makes it very suitable for Web CGI scripts. You must have ImageMagick 6.2.0 or above and Perl version 5.005_02 or greater installed on your system for either of these utilities to work.
There are a number of useful scripts available to show you the value of PerlMagick. You can do Web based image manipulation and conversion with
../www/download.html
MagickStudio
, or use
../www/download.html
L-systems
to create images of plants using mathematical constructs, and finally navigate through collections of thumbnail images and select the image to view with the
../www/download.html
WebMagick Image Navigator
.
You can try PerlMagick from your Web browser at the
http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi
ImageMagick Studio
. Or, you can see
../www/examples.html
examples
of select PerlMagick functions.
Installation
UNIX
The following instructions for Unix apply only to the unbundled PerlMagick as obtained from CPAN. PerlMagick is included as a subdirectory (PerlMagick) of the ImageMagick source distribution, and may be configured and built using the instructions provided in the ImageMagick distribution's README.txt file. It is usually most convenient to install PerlMagick as part of the ImageMagick distribution.
ImageMagick must already be installed on your system. Next, get
the
../www/download.html
PerlMagick
distribution corresponding to the installed ImageMagick distribution (e.g.  PerlMagick 6.22 for ImageMagick 6.2.2) and unpack it as shown below:
gunzip -c PerlMagick-6.22.tar.gz | tar -xvf -
cd PerlMagick
Next, edit
Makefile.PL
and change LIBS and INC to include the appropriate path information to the required
libMagick
library. You will also need paths to JPEG, PNG, TIFF, etc.  delegates if they were included with your installed version of ImageMagick. Build and install it like this:
perl Makefile.PL
make
make install
For Unix, you typically need to be
root
to install the software. There are ways around this. Consult the Perl manual pages for more information.
Windows XP / Windows 2000
ImageMagick must already be installed on your system. Also, the ImageMagick source distribution for
../www/download.html
Windows 2000
is required. You must also have the
nmake
from the Visual C++ or J++ development environment. Copy
\bin\IMagick.dll
and
\bin\X11.dll
to a directory in your dynamic load path such as
c:\perl\site\5.00502
.
Next, type
cd PerlMagick
copy Makefile.nt Makefile.PL
perl Makefile.PL
nmake
nmake install
See the
http://www.dylanbeattie.net/magick/
PerlMagick Windows HowTo
page for further installation instructions.
Running the Regression Tests
To verify a correct installation, type
make test
Use
nmake test
under Windows. There are a few demonstration scripts available to exercise many of the functions PerlMagick can perform. Type
cd demo
make
You are now ready to utilize the PerlMagick methods from within your Perl scripts.
Overview
Any script that wants to use PerlMagick methods must first define the methods within its namespace and instantiate an image object. Do this with:
use Image::Magick;
$image=Image::Magick->new;
The new() method takes the same parameters as
#set-attribute
SetAttribute
. For example,
$image=Image::Magick->new(size=>'384x256');
Next you will want to read an image or image sequence, manipulate it, and then display or write it. The input and output methods for PerlMagick are defined in
#read
Read or Write an Image
. See
#set-attribute
Set an Image Attribute
for methods that affect the way an image is read or written. Refer to
#manipulate
Manipulate an Image
for a list of methods to transform an image.
#get-attribute
Get an Image Attribute
describes how to retrieve an attribute for an image. Refer to
#montage
Create an Image Montage
for details about tiling your images as thumbnails on a background. Finally, some methods do not neatly fit into any of the categories just mentioned. Review
#misc
Miscellaneous Methods
for a list of these methods.
Once you are finished with a PerlMagick object you should consider destroying it. Each image in an image sequence is stored in virtual memory. This can potentially add up to mega-bytes of memory. Upon destroying a PerlMagick object, the memory is returned for use by other Perl methods. The recommended way to destroy an object is with
undef
:
undef $image;
To delete all the images but retain the
Image::Magick
object use
@$image = ();
and finally, to delete a single image from a multi-image sequence, use
undef $image->[x];
The next section illustrates how to use various PerlMagick methods to manipulate an image sequence.
Some of the PerlMagick methods require external programs such as
http://www.cs.wisc.edu/~ghost/
Ghostscript
. This may require an explicit path in your PATH environment variable to work properly. For example,
$ENV{PATH}='/../bin:/usr/bin:/usr/local/bin';
Example Script
Here is an example script to get you started:
#!/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";
The script reads three images, crops them, and writes a single image as a GIF animation sequence. In many cases you may want to access individual images of a sequence. The next example illustrates how this is done:
#!/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');
Suppose you want to start out with a 100 by 100 pixel white canvas with a red pixel in the center. Try
$image = Image::Magick->new;
$image->Set(size=>'100x100');
$image->ReadImage('xc:white');
$image->Set('pixel[49,49]'=>'red');
Or suppose you want to convert your color image to grayscale:
$image->Quantize(colorspace=>'gray');
Here we annotate an image with a Taipai TrueType font:
$text = 'Works like magick!';
$image->Annotate(font=>'kai.ttf', pointsize=>40, fill=>'green', text=>$text);
Other clever things you can do with a PerlMagick objects include
$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
Read or Write an Image
Use the methods listed below to either read, write, or display an image or image sequence:
Read or Write Methods
Method
Parameters
Return Value
Description
Read
one or more filenames
the number of images read
read an image or image sequence
Write
filename
the number of images written
write an image or image sequence
Display
server name
the number of images displayed
display the image or image sequence to an X server
Animate
server name
the number of images animated
animate image sequence to an X server
For convenience, methods Write(), Display(), and Animate() can take any parameter that
#set-attribute
SetAttribute
knows about. For example,
$image->Write(filename=>'image.png', compression=>'None');
Use
-
as the filename to method Read() to read from standard in or to method Write() to write to standard out:
binmode STDOUT;
$image->Write('png:-');
To read an image in the GIF format from a PERL filehandle, use:
$image = Image::Magick->new;
open(IMAGE, 'image.gif');
$image->Read(file=>\*IMAGE);
close(IMAGE);
To write an image in the PNG format to a PERL filehandle, use:
$filename = "image.png";
open(IMAGE, ">$filename");
$image->Write(file=>\*IMAGE, filename=>$filename);
close(IMAGE);
If
%0Nd, %0No, or %0Nx
appears in the filename, it is interpreted as a printf format specification and the specification is replaced with the specified decimal, octal, or hexadecimal encoding of the scene number. For example,
image%03d.miff
converts files image000.miff, image001.miff, etc.
You can optionally add
Image
to any method name. For example, ReadImage() is an alias for method Read().
Manipulate an Image
Once you create an image with, for example, method ReadImage() you may want to operate on it. Below is a list of all the image manipulations methods available to you with PerlMagick.  There are
../www/examples.html
examples
of select PerlMagick methods. Here is an example call to an image manipulation method:
$image->Crop(geometry=>'100x100"+10+20');
$image->[x]->Frame("100x200");
And here is a list of other image manipulation methods you can call:
Image Manipulation Methods
Method
Parameters
Description
AdaptiveThreshold
geometry=>
geometry
, width=>
integer
, height=>
integer
, offset=>
integer
local adaptive thresholding.
AddNoise
noise=>{Uniform, Gaussian, Multiplicative, Impulse, Laplacian, Poisson}
add noise to an image
AffineTransform
affine=>
array of float values
, translate=>
float, float
, scale=>
float, float
, rotate=>
float
, skewX=>
float
, skewY=>
float
affine transform image
Annotate
text=>
string
, font=>
string
, family=>
string
, style=>{Normal, Italic, Oblique, Any}, stretch=>{Normal, UltraCondensed, ExtraCondensed, Condensed, SemiCondensed, SemiExpanded, Expanded, ExtraExpanded, UltraExpanded}, weight=>
integer
, pointsize=>
integer
, density=>
geometry
, stroke=>
../www/color.html
color name
, strokewidth=>
integer
, fill=>
../www/color.html
color name
, undercolor=>
../www/color.html
color name
, geometry=>
geometry
, gravity=>{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}, antialias=>{true, false}, x=>
integer
, y=>
integer
, affine=>
array of float values
, translate=>
float, float
, scale=>
float, float
, rotate=>
float
. skewX=>
float
, skewY=>
float
, align=>{Left, Center, Right}, encoding=>{UTF-8}
annotate an image with text. See
#misc
QueryFontMetrics
to get font metrics without rendering any text.
BlackThreshold
threshold=>
string
force all pixels below the threshold intensity into black
Blur
geometry=>
geometry
, radius=>
double
, sigma=>
double
, channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Alpha, Black, or All}
blur the image with a Gaussian operator of the given radius and standard deviation (sigma).
Border
geometry=>
geometry
, width=>
integer
, height=>
integer
, fill=>
../www/color.html
color name
,  compose=>{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor },
surround the image with a border of color
Charcoal
geometry=>
geometry
, radius=>
double
, sigma=>
double
simulate a charcoal drawing
Chop
geometry=>
geometry
, width=>
integer
, height=>
integer
, x=>
integer
, y=>
integer
chop an image
Clip
id=>
name
, inside=>
{true, false}
,
apply along a named path from the 8BIM profile.
Coalesce
merge a sequence of images
ColorFloodfill
geometry=>
geometry
, x=>
integer
, y=>
integer
, fill=>
../www/color.html
color name
, bordercolor=>
../www/color.html
color name
, fuzz=>
double
changes the color value of any pixel that matches the color of the target pixel and is a neighbor. If you specify a border color, the color value is changed for any neighbor pixel that is not that color.
Colorize
fill=>
../www/color.html
color name
, opacity=>
string
colorize the image with the fill color
Comment
string
add a comment to your image
Compare
image=>
image-handle
compare image to a reference image
Composite
image=>
image-handle
, compose=>{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor }, mask=>
image-handle
, geometry=>
geometry
, x=>
integer
, y=>
integer
, gravity=>{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}, opacity=>
integer
, tile=>{True, False}, rotate=>
double
, color=>
../www/color.html
color name
composite one image onto another
Contrast
sharpen=>{True, False}
enhance or reduce the image contrast
Convolve
coefficients=>
array of float values
, channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Alpha, Black, or All}, bias=>;
double
apply a convolution kernel to the image. Given a kernel
order
, you would supply
order*order
float values (e.g. 3x3 implies 9 values).
Crop
geometry=>
geometry
, width=>
integer
, height=>
integer
, x=>
integer
, y=>
integer
, fuzz=>
double
crop an image
CycleColormap
amount=>
integer
displace image colormap by amount
Deconstruct
break down an image sequence into constituent parts
Describe
file=>
file
describe in detail the attributes of an image
Despeckle
reduce the speckles within an image
Draw
primitive=>{point, line, rectangle, arc, ellipse, circle, path, polyline, polygon, bezier, color, matte, text, @
filename
}, points=>
string
, method=>
{Point, Replace, Floodfill, FillToBorder, Reset}
, stroke=>
../www/color.html
color name
, fill=>
../www/color.html
color name
, tile=>
image-handle
, strokewidth=>
float
, antialias=>{true, false}, bordercolor=>
../www/color.html
color name
, x=>
float
, y=>
float
, affine=>
array of float values
, translate=>
float, float
, scale=>
float, float
, rotate=>
float
.  skewX=>
float
, skewY=>
float
annotate an image with one or more graphic primitives
Edge
radius=>
double
enhance edges within the image with a convolution filter of the given radius.
Emboss
geometry=>
geometry
, radius=>
double
, sigma=>
double
emboss the image with a convolution filter of the given radius and standard deviation (sigma).
Enhance
apply a digital filter to enhance a noisy image
Equalize
perform histogram equalization to the image
Evaluate
value=>
double
, operator=>
;{Add, And, Divide, LeftShift, Max, Min, Multiply, Or, Rightshift, Subtract, Xor}
, channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Alpha, Black, or All}
apply an arithmetic, relational, or logical expression to the image
Flip
create a
mirror image
by reflecting the image scanlines in the vertical direction
Flop
create a
mirror image
by reflecting the image scanlines in the horizontal direction
Frame
geometry=>
geometry
, width=>
integer
, height=>
integer
, inner=>
integer
, outer=>
integer
, fill=>
../www/color.html
color name
,  compose=>{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor },
surround the image with an ornamental border
Gamma
gamma=>
string
, channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Alpha, Black, or All}
gamma correct the image
GaussianBlur
geometry=>
geometry
, radius=>
double
, sigma=>
double
, channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Alpha, Black, or All}
blur the image with a Gaussian operator of the given radius and standard deviation (sigma).
GetPixels
geometry=>
geometry
, width=>
integer
, height=>
integer
, x=>
integer
, y=>
integer
, map=>
string
, normalize=>{ rue, false},
get image pixels as defined by the map (e.g. "RGB", "RGBA", etc.).  By default normalized pixel values are returned.
Implode
amount=>
double
implode image pixels about the center
Label
string
assign a label to an image
Level
level=>
string
, 'black-point'=>
double
, 'gamma'=>
double
, 'white-point'=>
double
, channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}
adjust the level of image contrast
Magnify
double the size of an image
Map
image=>
image-handle
, dither=>{True, False}
choose a particular set of colors from this image
MatteFloodfill
geometry=>
geometry
, x=>
integer
, y=>
integer
, matte=>
integer
, bordercolor=>
../www/color.html
color name
, fuzz=>
double
changes the matte value of any pixel that matches the color of the target pixel and is a neighbor. If you specify a border color, the matte value is changed for any neighbor pixel that is not that color.
MedianFilter
radius=>
double
replace each pixel with the median intensity pixel of a neighborhood.
Minify
half the size of an image
Modulate
brightness=>
double
, saturation=>
double
, hue=>
double
, luminosity=>
double
, whiteness=>
double
, blackness=>
double
vary the brightness, saturation, and hue of an image by the specified percentage
MotionBlur
geometry=>
geometry
, radius=>
double
, sigma=>
double
, angle=>
double
blur the image with a Gaussian operator of the given radius and standard deviation (sigma) at the given angle to simulate the effect of motion
Negate
gray=>{True, False}, channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Alpha, Black, or All}
replace every pixel with its complementary color (white becomes black, yellow becomes blue, etc.)
Normalize
transform image to span the full range of color values
OilPaint
radius=>
integer
simulate an oil painting
Opaque
color=>
../www/color.html
color name
,
fill=>
../www/color.html
color name
change this color to the fill color within the image
Posterize
levels=>
integer
, dither=>{True, False}
reduce the image to a limited number of color level
Profile
name=>
string
, profile=>
blob
add or remove ICC or IPTC image profile; name is formal name (e.g. ICC or filename; set profile to
''
to remove profile
Quantize
colors=>
integer
, colorspace=>{RGB, Gray, Transparent, OHTA, XYZ, YCbCr, YIQ, YPbPr, YUV, CMYK, sRGB, HSL, HSB}, treedepth=>
integer
, dither=>{True, False}, measure_error=>{True, False}, global_colormap=>{True, False}
preferred number of colors in the image
RadialBlur
angle=>
double
radial blur the image.
Raise
geometry=>
geometry
, width=>
integer
, height=>
integer
, x=>
integer
, y=>
integer
, raise=>{True, False}
lighten or darken image edges to create a 3-D effect
ReduceNoise
radius=>
double
reduce noise in the image with a noise peak elimination filter
Resample
density=>
geometry
, x=>
double
, y=>
double
, filter=>{Point, Box, Triangle, Hermite, Hanning, Hamming, Blackman, Gaussian, Quadratic, Cubic, Catrom, Mitchell, Lanczos, Bessel, Sinc}, blur=>
double
resample image to desired resolution. Specify
blur
> 1 for blurry or < 1 for sharp
Resize
geometry=>
geometry
, width=>
integer
, height=>
integer
, filter=>{Point, Box, Triangle, Hermite, Hanning, Hamming, Blackman, Gaussian, Quadratic, Cubic, Catrom, Mitchell, Lanczos, Bessel, Sinc}, blur=>
double
scale image to desired size. Specify
blur
> 1 for blurry or < 1 for sharp
Roll
geometry=>
geometry
, x=>
integer
, y=>
integer
roll an image vertically or horizontally
Rotate
degrees=>
double
, color=>
../www/color.html
color name
rotate an image
Sample
geometry=>
geometry
, width=>
integer
, height=>
integer
scale image with pixel sampling
Scale
geometry=>
geometry
, width=>
integer
, height=>
integer
scale image to desired size
Segment
colorspace=>{RGB, Gray, Transparent, OHTA, XYZ, YCbCr, YCC, YIQ, YPbPr, YUV, CMYK}, verbose={True, False}, cluster=>
double
, smooth=
double
segment an image by analyzing the histograms of the color components and identifying units that are homogeneous
Separate
channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}
separate a channel from the image into a grayscale image
Shade
geometry=>
geometry
, azimuth=>
double
, elevation=>
double
, gray=>{true, false}
shade the image using a distant light source
Shadow
geometry=>
geometry
, opacity=>
double
, sigma=>
double
, x=>
integer
, y=>
integer
simulate an image shadow
Sharpen
geometry=>
geometry
, radius=>
double
, sigma=>
double
, channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Alpha, Black, or All}
sharpen the image with a Gaussian operator of the given radius and standard deviation (sigma).
Shave
geometry=>
geometry
, width=>
integer
, height=>
integer
shave pixels from the image edges
Shear
geometry=>
geometry
, x=>
double
, y=>
double
color=>
../www/color.html
color name
shear the image along the X or Y axis by a positive or negative shear angle
SigmoidalContrast
geometry=>
string
, 'contrast'=>
double
, 'mid-point'=>
double
channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}, sharpen=>{True, False}
sigmoidal non-lineraity contrast control.  Increase the contrast of the image using a sigmoidal transfer function without saturating highlights or shadows.
Contrast
indicates how much to increase the contrast (0 is none; 3 is typical; 20 is a lot);
mid-point
indicates where midtones fall in the resultant image (0 is white; 50% is middle-gray; 100% is black). To decrease contrast, set sharpen to False.
Signature
generate an SHA-256 message digest for the image pixel stream
Solarize
threshold=>
double
negate all pixels above the threshold level
Splice
geometry=>
geometry
, width=>
integer
, height=>
integer
, x=>
integer
, y=>
integer
, fuzz=>
double
splice an image
Spread
amount=>
double
displace image pixels by a random amount
Stegano
image=>
image-handle
, offset=>
integer
hide a digital watermark within the image
Stereo
image=>
image-handle
composites two images and produces a single image that is the composite of a left and right image of a stereo pair
Strip
strip an image of all profiles and comments.
Swirl
degrees=>
double
swirl image pixels about the center
Texture
texture=>
image-handle
name of texture to tile onto the image background
Thumbnail
geometry=>
geometry
, width=>
integer
, height=>
integer
changes the size of an image to the given dimensions and removes any associated profiles.
Threshold
threshold=>
string
, channel=>{Red, Cyan, Green, Magenta, Blue, Yellow, Alpha, Black, or All}
threshold the image
Tint
fill=>
../www/color.html
color name
, opacity=>
string
tint the image with the fill color.
Transparent
color=>
../www/color.html
color name
make this color transparent within the image
Trim
remove edges that are the background color from the image
UnsharpMask
geometry=>
geometry
, radius=>
double
, sigma=>
double
, amount=>
double
, threshold=>
double
sharpen the image with the unsharp mask algorithm.
Wave
geometry=>
geometry
, amplitude=>
double
, wavelength=>
double
alter an image along a sine wave
WhiteThreshold
threshold=>
string
force all pixels above the threshold intensity into white
Note, that the
geometry
parameter is a short cut for the
width
and
height
parameters (e.g.
geometry=>'106x80'
is equivalent to
width=>106, height=>80
).
You can specify
@filename
in both Annotate() and Draw(). This reads the text or graphic primitive instructions from a file on disk. For example,
$image->Draw(fill=>'red', primitive=>'rectangle',
points=>'20,20 100,100  40,40 200,200  60,60 300,300');
Is equivalent to
$image->Draw(fill=>'red', primitive=>'@draw.txt');
Where
draw.txt
is a file on disk that contains this:
rectangle 20, 20 100, 100
rectangle 40, 40 200, 200
rectangle 60, 60 300, 300
The
text
parameter for methods, Annotate(), Comment(), Draw(), and Label() can include the image filename, type, width, height, or other image attribute by embedding these special format characters:
%b   file size
%d   comment
%d   directory
%e   filename extension
%f   filename
%h   height
%m   magick
%p   page number
%s   scene number
%t   top of filename
%w   width
%x   x resolution
%y   y resolution
%z   image depth
\n   newline
\r   carriage return
For example,
text=>"%m:%f %wx%h"
produces an annotation of
MIFF:bird.miff 512x480
for an image titled
bird.miff
and whose width is 512 and height is 480.
You can optionally add
Image
to any method name. For example, TrimImage() is an alias for method Trim().
Most of the attributes listed above have an analog in
../www/convert.html
convert
. See the documentation for a more detailed description of these attributes.
Set an Image Attribute
Use method Set() to set an image attribute. For example,
$image->Set(dither=>'True');
$image->[$x]->Set(delay=>3);
And here is a list of all the image attributes you can set:
Image Attributes
Attribute
Values
Description
adjoin
{True, False}
join images into a single multi-image file
antialias
{True, False}
remove pixel aliasing
area-limit
integer
set pixel area resource limit in megabytes.
authenticate
string
decrypt image with this password.
background
../www/color.html
color name
image background color
blue-primary
x-value
,
y-value
chromaticity blue primary point (e.g. 0.15, 0.06)
bordercolor
../www/color.html
color name
set the image border color
clip-mask
image
Associate a clip mask with the image.
colormap[
i
]
../www/color.html
color name
color name (e.g. red) or hex value (e.g. #ccc) at position
i
colorspace
{RGB, CMYK}
type of colorspace
compression
{None, BZip, Fax, Group4, JPEG, JPEG2000, LosslessJPEG, LZW, RLE, Zip}
type of image compression
debug
{All, Annotate, Blob, Cache, Coder, Configure, Deprecate, Draw, Exception, Locale, None, Resource, Transform, X11}
display copious debugging information
delay
integer
this many 1/100ths of a second must expire before displaying the next image in a sequence
density
geometry
vertical and horizontal resolution in pixels of the image
depth
integer
image depth
disk-limit
integer
set disk resource limit in megabytes
dispose
{Undefined, None, Background, Previous}
GIF disposal method
dither
{True, False}
apply error diffusion to the image
display
string
specifies the X server to contact
extract
geometry
extract area from image
file
filehandle
set the image filehandle
filename
string
set the image filename
fill
color
The fill color paints any areas inside the outline of drawn shape.
font
string
use this font when annotating the image with text
fuzz
integer
colors within this distance are considered equal
gamma
double
gamma level of the image
Gravity
{Forget, NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}
type of image gravity
green-primary
x-value
,
y-value
chromaticity green primary point (e.g. 0.3, 0.6)
index[
x
,
y
]
string
colormap index at position (
x
,
y
)
interlace
{None, Line, Plane, Partition}
the type of interlacing scheme
iterations
integer
add Netscape loop extension to your GIF animation
loop
integer
add Netscape loop extension to your GIF animation
magick
string
set the image format
matte
{True, False}
True if the image has transparency
mattecolor
../www/color.html
color name
set the image matte color
map-limit
integer
set map resource limit in megabytes
memory-limit
integer
set memory resource limit in megabytes
monochrome
{True, False}
transform the image to black and white
option
string
associate an option with an image format (e.g.  option=>'ps:imagemask'
orientation
{top-left, top-right, bottom-right, bottom-left, left-top, right-top, right-bottom, left-bottom}
image orientation
page
{ Letter, Tabloid, Ledger, Legal, Statement, Executive, A3, A4, A5, B4, B5, Folio, Quarto, 10x14} or
geometry
preferred size and location of an image canvas
pixel[
x
,
y
]
string
hex value (e.g. #ccc) at position (
x
,
y
)
pointsize
integer
pointsize of the Postscript or TrueType font
quality
integer
JPEG/MIFF/PNG compression level
red-primary
x-value
,
y-value
chromaticity red primary point (e.g. 0.64, 0.33)
rendering-intent
{Undefined, Saturation, Perceptual, Absolute, Relative}
the type of rendering intent
sampling-factor
geometry
horizontal and vertical sampling factor
scene
integer
image scene number
server
string
specifies the X server to contact
size
string
width and height of a raw image
stroke
color
The stroke color paints along the outline of a shape.
texture
string
name of texture to tile onto the image background
type
{Bilevel, Grayscale, GrayscaleMatte, Palette, PaletteMatte, TrueColor, TrueColorMatte, ColorSeparation, ColorSeparationMatte, Optimize }
image type
units
{ Undefined, PixelsPerInch, PixelsPerCentimeters}
units of image resolution
verbose
{True, False}
print detailed information about the image
virtual-pixel
{Constant, Edge, Mirror, Tile}
the virtual pixel method
white-point
x-value
,
y-value
chromaticity white point (e.g. 0.3127, 0.329)
Note, that the
geometry
parameter is a short cut for the
width
and
height
parameters (e.g.
geometry=>'106x80'
is equivalent to
width=>106, height=>80
).
SetAttribute() is an alias for method Set().
Most of the attributes listed above have an analog in
../www/convert.html
convert
. See the documentation for a more detailed description of these attributes.
Get an Image Attribute
Use method Get() to get an image attribute. For example,
($a, $b, $c) = $image->Get('colorspace', 'magick', 'adjoin');
$width = $image->[3]->Get('columns');
In addition to all the attributes listed in
#set-attribute
Set an Image Attribute
, you can get these additional attributes:
Image Attributes
Attribute
Values
Description
base-columns
integer
base image width (before transformations)
base-filename
string
base image filename (before transformations)
base-rows
integer
base image height (before transformations)
class
{Direct, Pseudo}
image class
colors
integer
number of unique colors in the image
comment
string
get the image comment
columns
integer
image width
directory
string
tile names from within an image montage
elapsed-time
double
elapsed time in seconds since the image was created
error
double
the mean error per pixel computed with methods Compare() or Quantize()
bounding-box
string
image bounding box
filesize
integer
number of bytes of the image on disk
format
string
get the descriptive image format
geometry
string
image geometry
height
integer
the number of rows or height of an image
id
integer
ImageMagick registry id
label
string
image label
mean-error
double
the normalized mean error per pixel computed with methods Compare() or Quantize()
maximum-error
double
the normalized max error per pixel computed with methods Compare() or Quantize()
MIME
string
get the image MIME type
mime
string
MIME of the image format
montage
geometry
tile size and offset within an image montage
rows
integer
the number of rows or height of an image
signature
string
SHA-256 message digest associated with the image pixel stream
taint
{True, False}
True if the image has been modified
user-time
double
user time in seconds since the image was created
width
integer
the number of columns or width of an image
x-resolution
integer
x resolution of the image
y-resolution
integer
y resolution of the image
GetAttribute() is an alias for method Get().
Most of the attributes listed above have an analog in
../www/convert.html
convert
. See the documentation for a more detailed description of these attributes.
Create an Image Montage
Use method Montage() to create a composite image by combining several separate images. The images are tiled on the composite image with the name of the image optionally appearing just below the individual tile. For example,
$image->Montage(geometry=>'160x160', tile=>'2x2', texture=>'granite:');
And here is a list of Montage() parameters you can set:
Montage Parameters
Parameter
Values
Description
background
../www/color.html
color name
background color name
border
integer
image border width
filename
string
name of montage image
fill
../www/color.html
color name
fill color for annotations
font
string
X11 font name
frame
geometry
surround the image with an ornamental border
geometry
geometry
preferred tile and border size of each tile of the composite
image (e.g. 120x120+4+3>)
gravity
{NorthWest, North, NorthEast, West, Center, East, SouthWest,
South, SouthEast}
direction image gravitates to within a tile
label
string
assign a label to an image
mode
{Frame, Unframe, Concatenate}
thumbnail framing options
pointsize
integer
pointsize of the Postscript or TrueType font
shadow
{True, False}
add a shadow beneath a tile to simulate depth
stroke
../www/color.html
color name
stroke color for annotations
texture
string
name of texture to tile onto the image background
tile
geometry
the number of tiles per row and page (e.g. 6x4)
title
string
assign a title to the image montage
transparent
string
make this color transparent within the image
Note, that the
geometry
parameter is a short cut for the
width
and
height
parameters (e.g.
geometry=>'106x80'
is equivalent to
width=>106, height=>80
).
MontageImage() is an alias for method Montage().
Most of the attributes listed above have an analog in
../www/montage.html
montage
. See the documentation for a more detailed description of these attributes.
Working with Blobs
A blob contains data that directly represent a particular image
format in memory instead of on disk. PerlMagick supports
blobs in any of these image
../www/formats.html
formats
and provides methods to convert a blob to or from a particular image format.
Blob Methods
Method
Parameters
Return Value
Description
ImageToBlob
any image
#set-attribute
attribute
an array of image data in the respective image format
convert an image or image sequence to an array of blobs
BlobToImage
one or more blobs
the number of blobs converted to an image
convert one or more blobs to an image
ImageToBlob() returns the image data in their respective formats. You can then print it, save it to an ODBC database, write it to a file, or pipe it to a display program:
@blobs = $image->ImageToBlob();
open(DISPLAY,"| display -") || die;
binmode DISPLAY;
print DISPLAY $blobs[0];
close DISPLAY;
Method BlobToImage() returns an image or image sequence converted from the supplied blob:
@blob=$db->GetImage();
$image=Image::Magick->new(magick=>'jpg');
$image->BlobToImage(@blob);
Miscellaneous Methods
The Append() method append a set of images. For example,
$p = $image->Append(stack=>{true,false});
appends all the images associated with object
$image
. By default, images are stacked left-to-right. Set
stack
to True to stack them top-to-bottom.
The Average() method averages a set of images. For example,
$p = $image->Average();
averages all the images associated with object
$image
.
The Clone() method copies a set of images. For example,
$p = $image->Clone();
copies all the images from object
$q
to
$p
. You can use this method for single or multi-image sequences.
The Flatten() method flattens a set of images. For example,
$p = $images->Flatten();
The sequence of images is replaced by a single image created by composing each image after the first over the first image.
The Fx() method applies a mathematical expression to a set of images. For example,
$p = $image->Fx(expression=>'(g+b)/2.0',channel=>'red');
replaces the red channel with the average of the green and blue channels.
Histogram() returns the unique colors in the image and a count for each one. The returned values are an array of red, green, blue, opacity, and count values.
The Morph() method morphs a set of images. Both the image pixels and size are linearly interpolated to give the appearance of a meta-morphosis from one image to the next:
$p = $image->Morph(frames=>
integer
);
where
frames
is the number of in-between images to generate.  The default is 1.
Mosaic() creates an mosaic from an image sequence.
Method Mogrify() is a single entry point for the image manipulation methods (
#manipulate
Manipulate an Image
). The parameters are the name of a method followed by any parameters the method may require. For example, these calls are equivalent:
$image->Crop('340x256+0+0');
$image->Mogrify('crop', '340x256+0+0');
Method MogrifyRegion() applies a transform to a region of the image. It is similar to Mogrify() but begins with the region geometry. For example, suppose you want to brighten a 100x100 region of your image at location (40, 50):
$image->MogrifyRegion('100x100+40+50', 'modulate', brightness=>50);
Ping() is a convenience method that returns information about an image without having to read the image into memory. It returns the width, height, file size in bytes, and the file format of the image. You can specify more than one filename but only one filehandle:
($width, $height, $size, $format) = $image->Ping('logo.png');
($width, $height, $size, $format) = $image->Ping(file=>\*IMAGE);
($width, $height, $size, $format) = $image->Ping(blob=>$blob);
This is a more efficient and less memory intensive way to query if an image exists and what its characteristics are.
PreviewImage() tiles 9 thumbnails of the specified image with an image processing operation applied at varying strengths. This may be helpful pin-pointing an appropriate parameter for a particular image processing operation. Choose from these operations:
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
. Here is an example:
$preview = $image-&gt;Preview('Gamma');
$preview-&gt;Display();
To have full control over text positioning you need font metric information. Use
($x_ppem, $y_ppem, $ascender, $descender, $width, $height, $max_advance) =
$image->QueryFontMetrics(
parameters
);
Where
parameters
is any parameter of the
#manipulate
Annotate
method. The return values are:
character width
character height
ascender
descender
text width
text height
maximum horizontal advance
Use QueryMultilineFontMetrics() to get the maximum text width and height for multiple lines of text.
Call QueryColor() with no parameters to return a list of known colors names or specify one or more color names to get these attributes: red, green, blue, and opacity value.
@colors = $image->QueryColor();
($red, $green, $blue, $opacity) = $image->QueryColor('cyan');
($red, $green, $blue, $opacity) = $image->QueryColor('#716bae');
QueryColorname() accepts a color value and returns its respective name or hex value;
$name = $image->QueryColorname('rgba(80,60,0,0)');
Call QueryFont() with no parameters to return a list of known fonts or specify one or more font names to get these attributes: font name, description, family, style, stretch, weight, encoding, foundry, format, metrics, and glyphs values.
@fonts = $image->QueryFont();
$weight = ($image->QueryFont('Helvetica'))[5];
Call QueryFormat() with no parameters to return a list of known image formats or specify one or more format names to get these attributes: adjoin, blob support, raw, decoder, encoder, description, and module.
@formats = $image->QueryFormat();
($adjoin, $blob_support, $raw, $decoder, $encoder,
$description, $module) = $image->QueryFormat('gif');
Call MagickToMime() with the image format name to get its MIME type such as
image/tiff
from
tif
.
$mime = $image->MagickToMime('tif');
Use RemoteCommand() to send a command to an already running
../www/display.html
display
or
../www/animate.html
animate
application. The only parameter is the name of the image file to display or animate.
Finally, the Transform() method accepts a fully-qualified geometry specification for cropping or resizing one or more images.  For example,
$p = $image->Transform(crop=>'100x100');
Statistics() returns the image statistics for each channel in the image. The returned values are an array of depth, minima, maxima, mean, and standard deviation values in RGB, CMYK, RGBA, or CMYKA order (depending on the image type).
You can optionally add
Image
to any method name above. For example, PingImage() is an alias for method Ping().
Handling Exceptions
All PerlMagick methods return an undefined string context upon success. If any problems occur, the error is returned as a string with an embedded numeric status code. A status code less than 400 is a warning. This means that the operation did not complete but was recoverable to some degree. A numeric code greater or equal to 400 is an error and indicates the operation failed completely. Here is how exceptions are returned for the different methods:
Methods which return a number (e.g. 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
Methods which operate on an image (e.g. Resize(), Crop()):
$x = $image->Crop(...);
warn "$x" if "$x";      # print the error message
$x =~ /(\d+)/;
print $1;               # print the error number
Methods which return images (Average(), Montage(), Clone()) should be checked for errors this way:
$x = $image->Montage(...);
warn "$x" if !ref($x);  # print the error message
$x =~ /(\d+)/;
print $1;               # print the error number
Here is an example error message:
Error 400: Memory allocation failed
Below is a list of error and warning codes:
Error and Warning Codes
Code
Mnemonic
Description
0
Success
method completed without an error or warning
300
ResourceLimitWarning
a program resource is exhausted (e.g. not enough memory)
305
TypeWarning
A font is unavailable; a substitution may have occurred
310
OptionWarning
a command-line option was malformed
315
DelegateWarning
an ImageMagick
delegate
returned a warning
320
MissingDelegateWarning
the image type can not be read or written because the appropriate
Delegate
is missing
325
CorruptImageWarning
the image file may be corrupt
330
FileOpenWarning
the image file could not be opened
335
BlobWarning
a binary large object could not be allocated
340
StreamWarning
there was a problem reading or writing from a stream
345
CacheWarning
pixels could not be saved to the pixel cache
350
CoderWarning
there was a problem with an image coder
355
ModuleWarning
there was a problem with an image module
360
DrawWarning
a drawing operation failed
365
ImageWarning
the operation could not complete due to an incompatible image
380
XServerWarning
an X resource is unavailable
385
MonitorWarning
there was a problem with prgress monitor
390
RegistryWarning
there was a problem getting or setting the registry
395
ConfigureWarning
there was a problem getting a configuration file
400
ResourceLimitError
a program resource is exhausted (e.g. not enough memory)
405
TypeError
A font is unavailable; a substitution may have occurred
410
OptionError
a command-line option was malformed
415
DelegateError
an ImageMagick
delegate
returned a warning
420
MissingDelegateError
the image type can not be read or written because the appropriate
Delegate
is missing
425
CorruptImageError
the image file may be corrupt
430
FileOpenError
the image file could not be opened
435
BlobError
a binary large object could not be allocated
440
StreamError
there was a problem reading or writing from a stream
445
CacheError
pixels could not be saved to the pixel cache
450
CoderError
there was a problem with an image coder
455
ModuleError
there was a problem with an image module
460
DrawError
a drawing operation failed
465
ImageError
the operation could not complete due to an incompatible image
480
XServerError
an X resource is unavailable
485
MonitorError
there was a progress monitor error
490
RegistryError
there was a problem getting or setting the registry
495
ConfigureError
there was a problem getting a configuration file
The following illustrates how you can use a numeric status code:
$x = $image->Read('rose.png');
$x =~ /(\d+)/;
die "unable to continue" if ($1 == ResourceLimitError);
http://redux.imagemagick.org/discussion-server
Discourse Server
|
../www/mailing-list.html
Mailing Lists
|
http://redux.imagemagick.org/gallery
Image Gallery
|
http://studio.webbyland.com/MagickStudio/scripts/MagickStudio.cgi
ImageMagick Studio
© 1999-2005 ImageMagick Studio LLC
