


  

  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  



  

    

      

        
../index.html[ImageMagick] 
        

        
http://www.imagemagick.org/[sponsor] 
        

        
../index.html 
        
../index.html 
      

    

  


  

  


    

      

      
#mainSkip to page contents 

      
[
      
../index.htmlAbout ImageMagick       
../www/command-line-tools.htmlCommand-line Tools       
../www/api.htmlProgram Interfaces   
][
      
../www/install-source.htmlInstall from Source       
../www/binary-releases.htmlBinary Releases       
../www/resources.htmlResources   
][
      
../www/download.htmlDownload   
][
      
../www/links.htmlLinks   
][
      
../www/sponsors.htmlSponsors   
http://www.thebest3d.com/dogwaffleProject Dogwaffle digital image paint andanimation software       
]
      


      

[ #installationInstallation  | #overviewOverview  | #exampleExample Script  | #readRead or Write an Image  | #manipulateManipulate an Image  |
#set-attributeSet an Image Attribute  | #get-attributeGet an Image Attribute  | #montageCreate an Image Montage  | #blobsWorking with Blobs  | #miscellaneousMiscellaneous Methods  | #exceptionsHandling Exceptions  ]
../www/download.htmlPerlMagick  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 http://www.imagemagick.org/download/perlMagickStudio , or use https://subversion.imagemagick.org/subversion/ImageMagick/trunk/PerlMagick/demo/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 http://webmagick.sourceforge.net/WebMagick Image Navigator .
You can try PerlMagick from your Web browser at the http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgiImageMagick Studio . Or, you can see ../www/examples.htmlexamples  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.htmlPerlMagick  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.htmlWindows 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-attributeSetAttribute  . 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 #readRead or Write an Image . See #set-attributeSet an Image Attribute  for methods that affect the way an image is read or written. Refer to #manipulateManipulate an Image  for a list of methods to transform an image. #get-attributeGet an Image Attribute  describes how to retrieve an attribute for an image. Refer to #montageCreate 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 #miscMiscellaneous 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-attributeSetAttribute  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.htmlexamples  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}, channel=>{All, alpha, Black, Blue, Cyan, Gray, Green, Index, Magenta, Opacity, Red, Yellow}     
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.htmlcolor name , strokewidth=>integer, fill=> ../www/color.htmlcolor name , undercolor=> ../www/color.htmlcolor 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 #miscQueryFontMetrics  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=>{All, alpha, Black, Blue, Cyan, Gray, Green, Index, Magenta, Opacity, Red, Yellow}     
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.htmlcolor 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.htmlcolor name , bordercolor=> ../www/color.htmlcolor 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.htmlcolor 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.htmlcolor name     
composite one image onto another   
  
    
Contrast     
sharpen=>{True, False}     
enhance or reduce the image contrast   
  
    
Convolve     
coefficients=>array of float values, channel=>{All, alpha, Black, Blue, Cyan, Gray, Green, Index, Magenta, Opacity, Red, Yellow}, 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   
  
    
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.htmlcolor name , fill=> ../www/color.htmlcolor name , tile=>image-handle, strokewidth=>float, antialias=>{true, false}, bordercolor=> ../www/color.htmlcolor 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   
  
    
Extent     
geometry=>geometry, width=>integer, height=>integer     
set the image size   
  
    
Evaluate     
value=>double, operator=>;{Add, And, Divide, LeftShift, Max, Min, Multiply, Or, Rightshift, Subtract, Xor}, channel=>{All, alpha, Black, Blue, Cyan, Gray, Green, Index, Magenta, Opacity, Red, Yellow}     
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.htmlcolor 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=>{All, alpha, Black, Blue, Cyan, Gray, Green, Index, Magenta, Opacity, Red, Yellow}     
gamma correct the image   
  
    
GaussianBlur     
geometry=>geometry, radius=>double, sigma=>double, channel=>{All, alpha, Black, Blue, Cyan, Gray, Green, Index, Magenta, Opacity, Red, Yellow}     
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=>{true, false},     
get image pixels as defined by the map (e.g. "RGB", "RGBA", etc.).  By default non-normalized pixel values are returned.   
  
    
Identify     
file=>file     
identify the attributes of an image   
  
    
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.htmlcolor 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=>{All, alpha, Black, Blue, Cyan, Gray, Green, Index, Magenta, Opacity, Red, Yellow}     
replace every pixel with its complementary color (white becomes black, yellow becomes blue, etc.)   
  
    
Normalize     
channel=>{All, alpha, Black, Blue, Cyan, Gray, Green, Index, Magenta, Opacity, Red, Yellow}     
transform image to span the full range of color values   
  
    
OilPaint     
radius=>integer     
simulate an oil painting   
  
    
Opaque     
color=> ../www/color.htmlcolor name ,
fill=>
../www/color.htmlcolor 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}, support=>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}, support=>double     
scale image to desired size. Specify support > 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.htmlcolor 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=>{All, alpha, Black, Blue, Cyan, Gray, Green, Index, Magenta, Opacity, Red, Yellow}     
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.htmlcolor 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=>{All, alpha, Black, Blue, Cyan, Gray, Green, Index, Magenta, Opacity, Red, Yellow}     
threshold the image   
  
    
Tint     
fill=> ../www/color.htmlcolor name , opacity=>string     
tint the image with the fill color.   
  
    
Transparent     
color=> ../www/color.htmlcolor 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.htmlconvert . 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.htmlcolor name     
image background color   
  
    
blue-primary     
x-value, y-value     
chromaticity blue primary point (e.g. 0.15, 0.06)   
  
    
bordercolor     
../www/color.htmlcolor name     
set the image border color   
  
    
clip-mask     
image     
Associate a clip mask with the image.   
  
    
colormap[i]     
../www/color.htmlcolor 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.htmlcolor 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     
{Background, Edge, Mirror, Tile, Transparent}     
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.htmlconvert . 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-attributeSet an Image Attribute  , you can get these additional attributes:
  
Image Attributes  
  
    
Attribute    
Values    
Description  
  
    
area     
integer     
current area resource consumed   
  
    
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   
  
    
copyright     
string     
get PerlMagick's copyright   
  
    
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   
  
    
disk     
integer     
current disk resource consumed   
  
    
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()   
  
    
map     
integer     
current memory-mapped resource consumed   
  
    
maximum-error     
double     
the normalized max error per pixel computed with methods Compare() or Quantize()   
  
    
memory     
integer     
current memory resource consumed   
  
    
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   
  
    
version     
string     
get PerlMagick's version   
  
    
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.htmlconvert . 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.htmlcolor name     
background color name   
  
    
border     
integer     
image border width   
  
    
filename     
string     
name of montage image   
  
    
fill     
../www/color.htmlcolor 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.htmlcolor 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.htmlmontage . 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.htmlformats  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-attributeattribute     
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 ( #manipulateManipulate 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->Preview('Gamma');
  $preview->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 #manipulateAnnotate  method. The return values are:
  
character width  
character height  
ascender  
descender  
text width  
text height  
maximum horizontal advanceUse 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.htmldisplay  or ../www/animate.htmlanimate  application. The only parameter is the name of the image file to display or animate.
  $image->RemoteCommand('image.jpg');
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).
  @statistics = $image->Statistics();
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');
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     
ConfigureWarning     
there was a problem getting a configuration file   
  
    
395     
RegistryWarning     
there was a problem getting or setting the registry   
  
    
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     
ConfigureError     
there was a problem getting a configuration file   
  
    
495     
RegistryError     
there was a problem getting or setting the registry   
  
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-serverDiscourse Server  |
    
../www/mailing-list.htmlMailing Lists  |
    
http://redux.imagemagick.org/galleryImage Gallery  |
    
http://redux.imagemagick.org/MagickStudio/scripts/MagickStudio.cgiImageMagick Studio 
  

  

    
© 1999-2005 ImageMagick Studio LLC
  

  



