gunzip -c PerlMagick-0.9.2.tar.gz tar xvf PerlMagick-0.9.2.tar 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. libraries if they were included with your installed version of ImageMagick. Now type
perl Makefile.PL make make install
You typically need to be root to install the software. There are ways around this. Consult the Perl manual pages for more information. You are now ready to utilize the PerlMagick routines from within your Perl scripts.
use Image::Magick;
Next you will want to read an image or image sequence, manipulate it, and then write it. The input and output routines for PerlMagick are defined in Read or Write an Image. See Set an Image Attribute for routines that affect the way an image is read or written. Refer to Manipulate an Image for a list of functions to transform an image. Get an Image Attribute describes how to retrieve an attribute for an image. Refer to Create an Image Montage for details about tiling your images as thumbnails on a background. Finally, some routines do not neatly fit into any of the catagories just mentioned. Review Miscellaneous Routines for a list of these functions.
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 functions. The recommended way to destroy an object is with undef:
undef $q;
To delete all the images but retain the Image::Magick object use
undef @$q;and finally, to delete a single image from a multi-image sequence, use
undef $q->[$x];The next section illustrates how to use various PerlMagick functions to manipulate an image sequence.
#!/usr/local/bin/perl use Image::Magick; my($q, $x); $q = Image::Magick->new; $x = $q->Read('girl.gif','logo.gif','rose.gif'); warn "$x" if "$x"; $x = $q->Crop(geometry=>'100x100+100+100'); warn "$x" if "$x"; $x = $q->Write('x.gif'); 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($q, $r); $q = new Image::Magick; $q->Read('x1.gif'); $q->Read('j*.jpg'); $q->Read('k.miff[1,3,5]'); $q->Contrast; for ($x = 0; $q->[$x]; $x++) { if ($q->[$x]->Get('magick') eq 'GIF') $q->[$x]->Frame('100x200'); if ($q->[$x]->Get('columns') < 100) undef $q->[$x]; } $r = $q->[1]; $r->Draw(pen=>'red',primitive=>'rectangle',points=>'20,20 100,100'); $s = $q->Montage; undef $q; $s->Write('x.miff');
Routine | Parameters | Return Value | Description |
---|---|---|---|
Read | one or more filenames | the number of images read and a list of any warnings | read an image or image sequence |
Write | filename | the number of images written and a list of any warnings | write an image or image sequence |
Display | server name | the number of images displayed and a list of any warnings | display the image or image sequence on an X server |
For convenience, each of these routines can take any parameter that SetAttribute knows. For example,
$x->write(filename=>'image.png',compress=>'false');
You can optionally add Image to any routine name. For example, ReadImage is an alias for function Read.
$q->Crop(geometry=>'100x100+10+20'); $q->[$x]->Frame("100x200");
And here is a list of other image manipulation functions you can call:
Routine | Parameters | Description |
---|---|---|
AddNoise | noise=>{Uniform, Gaussian, Multiplicative, Impulse, Laplacian, Poisson} | add noise to an image |
Annotate | server=>string, font=>string, pointsize=>integer, box=>{true, false}, pen=>colorname, geometry=>string, text=string, primitive={Point, Line, Rectangle, FillRectangle, Ellipse, FillEllipse, Polygon, FillPolygon, Color, Matte, Text, Image}, center=>{true, false}, x=>integer, y=>integer | annotate an image with text |
Border | geometry=>geometry, width=>integer, height=>integer, color=colorname | surround the image with a border of color |
Blur | factor=>percentage | blurs an image |
Charcoal | factor=>percentage | simulate a charcoal drawing |
Chop | geometry=>geometry, width=>integer, height=>integer, x=>integer, y=>integer | chop an image |
Composite | compose=>{Over, In, Out, Atop, Xor, Plus, Minus, Add, Subtract, Difference, Bumpmap, Replace, MatteReplace, Mask, Blend, Displace}, image=>image-handle,x=>integer, y=>integer | blurs an image |
Contrast | sharpen=>{true, false} | enhance or reduce the image contrast |
Copy | make a copy an image | |
Crop | geometry=>geometry, width=>integer, height=>integer, x=>integer, y=>integer | crop an image |
Colorize | color=>colorname, pen=>colorname | colorize the image with the pen color |
Comment | string | annotate an image with a comment |
CycleColormap | amount=>integer | displace image colormap by amount |
Despeckle | reduce the speckles within an image | |
Draw | primitive={Point, Line, Rectangle, FillRectangle, Ellipse, FillEllipse, Polygon, FillPolygon, Color, Matte, Text, Image}, points=>string, method={Point, Replace, Floodfill, Reset}, pen=>colorname, linewidth=>integer, server=>string, | annotate an image with one or more graphic primitives |
Edge | factor=>percentage | detect edges within an image |
Emboss | emboss the image | |
Enhance | apply a digital filter to enhance a noisy image | |
Equalize | perform histogram equalization 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,color=>colorname | surround the image with an ornamental border |
Gamma | gamma=>double, red=>double, green=>double, blue=>double, | gamma correct the image |
Implode | factor=>percentage | implode image pixels about the center |
Label | string | assign a label to an image |
Magnify | double the size of an image | |
Map | image=>image-handle, dither={true, false} | choose a particular set of colors from this image |
Minify | half the size of an image | |
Modulate | brightness=>double, saturation=>double, hue=>double | vary the brightness, saturation, and hue of an image |
Negate | gray=>{true, false} | apply color inversion to image |
Normalize | transform image to span the full range of color values | |
OilPaint | radius=>integer | simulate an oil painting |
Opaque | color=>colorname,pen=>colorname | change this color to the pen color within the image |
Quantize | colors=>integer, treedepth=>integer, dither=>{true, false}, colorspace=>{RGB, Gray, Transparent, OHTA, XYZ, YCbCr, YCC, YIQ, YPbPr, YUV} | preferred number of colors in 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 | add or reduce the noise in an image | |
Roll | x=>integer, y=>integer | roll an image vertically or horizontally |
Rotate | degrees=>double, crop=>{true, false}, sharpen=>{true, false} | roll an image vertically or horizontally |
Sample | width=>integer, height=>integer | scale image with pixel sampling |
Scale | width=>integer, height=>integer | scale image to desired size |
Segment | colorspace=>{RGB, Gray, Transparent, OHTA, XYZ, YCbCr, YCC, YIQ, YPbPr, YUV}, verbose={true, false}, cluster=>double, smooth=double | segment an image by analyzing the histograms of the color components and identifying units that are homogeneous |
Shade | color=>colorname, azimuth=>double, elevation=>double | shade the image using a distant light source |
Sharpen | factor=>percentage | sharpen an image |
Shear | x=>double, y=>double | shear the image along the X or Y axis by a positive or negative shear angle |
Signature | generate an MD5 signature for the image | |
Solarize | factor=>percentage | negate all pixels above the threshold level |
Spread | amount=>integer | displace image pixels by a random amount |
Swirl | degrees=>double | swirl image pixels about the center |
Scale | width=>integer, height=>integer, filter=>{Box, Mitchell, Triangle} | scale image to desired size |
Texture | filename=>string | name of texture to tile onto the image background |
Transparent | color=>colorname | make this color transparent within the image |
Threshold | threshold=>integer | threshold the image |
Trim | remove edges that are the background color from the image |
You can optionally add Image to any routine name. For example, TrimImage is an alias for function Trim.
Most of the attributes listed above have an analog in convert. See the documentation for a more detailed description of these attributes.
$q->Set(dither=>true); $q->[$x]->Set(delay=>3);
And here is a list of all the image attributes you can set:
Attribute | Values | Description |
---|---|---|
adjoin | true, false | join images into a single multi-image file |
compress | No, Runlength, Zip | type of image compression |
colorspace | {RGB, Gray, Transparent, OHTA, XYZ, YCbCr, YCC, YIQ, YPbPr, YUV} | type of colorspace |
colors | integer | preferred number of colors in the image |
density | geometry | vertical and horizontal resolution in pixels of the image |
dispose | geometry | GIF disposal method |
delay | integer | regulate the animation of a sequence of GIF images within Netscape |
dither | {true, false} | apply Floyd/Steinberg error diffusion to the image |
display | string | specifies the X server to contact |
font | string | use this font when annotating the image with text |
format | string | set the image format |
iterations | integer | add Netscape loop extension to your GIF animation |
interlace | {None, Line, Plane, or Partition} | the type of interlacing scheme |
loop | integer | add Netscape loop extension to your GIF animation |
magick | string | set the image format |
monochrome | {true, false} | transform the image to black and white |
number | integer | preferred number of colors in the image |
page | string | preferred size and location of the Postscript page |
pointsize | integer | pointsize of the Postscript font |
quality | integer | JPEG quality setting |
subimage | integer | subimage of an image sequence |
subrange | integer | number of images relative to the base image |
server | string | specifies the X server to contact |
size | string | width and height of a raw image |
tile | string | tile name |
texture | string | name of texture to tile onto the image background |
undercolor | string | control undercolor removal and black generation on CMYK images |
verbose | {true, false} | print detailed information about the image |
SetAttribute is an alias for function Set.
Most of the attributes listed above have an analog in convert. See the documentation for a more detailed description of these attributes.
($a, $b, $c) = $q->Get("colorspace", "magick", "adjoin"); $width = $q->[3]->Get("columns");
In addition to all the attributes list in Set an Image Attribute, you can get these additional attributes:
Attribute | Values | Description |
---|---|---|
background | string | image background color |
border | string | image border color |
class | {DirectClass, PseudoClass} | image class |
comment | string | image comment |
columns | integer | image width |
depth | integer | image depth |
filesize | integer | number of bytes of the image on disk |
filename | string | name of image |
foreground | string | image foreground color |
gamma | double | gamma level of the image |
geometry | string | image geometry |
height | integer | the number of rows or height of an image |
label | string | image label |
matte | {true, false} | true if the image has transparency |
mattecolor | string | image matte color |
mean | double | the mean error per pixel computed when an image is color reduced |
monochrome | {true, false} | true if the image is bi-level |
normalized_max | double | the normalized max error per pixel computed when an image is color reduced |
normalized_mean | double | the normalized mean error per pixel computed when an image is color reduced |
packetsize | integer | the number of bytes in each pixel packet |
packets | integer | the number of runlength-encoded packets in the image |
rows | integer | the number of rows or height of an image |
scene | integer | image scene number |
signature | string | MD5 signature associated with the image |
text | string | any text associated with the image |
units | {Undefined, pixels / inch, pixels / centimeter} | units of resolution |
width | integer | the number of columns or width of an image |
x | integer | x resolution of the image |
y | integer | y resolution of the image |
GetAttribute is an alias for function Get.
Most of the attributes listed above have an analog in convert. See the documentation for a more detailed description of these attributes.
$q->Montage(gometry=>'160x160',tile=>'2x2',texture=>'granite:');
And here is a list of all the image attributes you can set:
Parameter | Values | Description |
---|---|---|
background | string | X11 color name |
borderwidth | integer | image border width |
compose | {Over, In, Out, Atop, Xor, Plus, Minus, Add, Subtract, Difference, Bumpmap, Replace, MatteReplace, Mask, Blend, Displace} | composite operator |
filename | string | name of montage image |
frame | geometry | surround the image with an ornamental border |
geometry | string | preferred tile and border size of each tile of the composite image |
mattecolor | string | color of the image border |
mode | {Frame, Unframe, Concatenate} | thumbnail framing options |
shadow | {true, false} | add a shadow beneath a tile to simulate depth |
texture | string | name of texture to tile onto the image background |
tile | geometry | number of tiles per row and column |
MontageImage is an alias for function montage.
Most of the attributes listed above have an analog in montage. See the documentation for a more detailed description of these attributes.
$x = $q->Average();
Function Mogrify is a single entry point for the image manipulation routines (Manipulate an Image). The parameters are the name of a function followed by any parameters the function may require. For example, these calls are equivalent:
$q->Crop('340x256+0+0'); $q->Mogrify('crop','340x256+0+0');
You can optionally add Image to any routine name. For example, MontageImage is an alias for function Montage.