PerlMagick API

- +

PerlMagick is an objected-oriented 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.5.5 or above and Perl version 5.005_02 or greater installed on your system for PerlMagick to build properly.

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 MagickStudio, or use 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 WebMagick Image Navigator.

@@ -182,7 +212,7 @@

You can try PerlMagick from your Web browser at the ImageMagick Studio. Or, you can see examples of select PerlMagick functions.

Installation

UNIX

@@ -191,10 +221,10 @@

ImageMagick must already be installed on your system. Next, get the PerlMagick distribution corresponding to the installed ImageMagick distribution -(e.g., PerlMagick 6.65 for -ImageMagick 6.6.5) and unpack it as shown below:

+(e.g., PerlMagick 6.70 for +ImageMagick 6.7.0) and unpack it as shown below:

$magick> tar xvfz PerlMagick-6.65.tar.gz $magick> cd PerlMagick

$magick> tar xvfz PerlMagick-6.70.tar.gz $magick> cd PerlMagick

Next, edit Makefile.PL and change LIBS and INC to include the appropriate path information to the required MagickCore library. You may need paths to JPEG, PNG, TIFF, etc. delegates if they were included with your installed version of ImageMagick. Build and install it like this:

$magick> perl Makefile.PL $magick> make $magick> make install

@@ -221,7 +251,7 @@ ImageMagick 6.6.5) and unpack it as shown below:

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:

@@ -264,7 +294,7 @@ ImageMagick 6.6.5) and unpack it as shown below:

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

Example Script

Here is an example script to get you started:

@@ -310,7 +340,7 @@ ImageMagick 6.6.5) and unpack it as shown below:

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

@@ -353,7 +383,7 @@ ImageMagick 6.6.5) and unpack it as shown below:

Read or Write an Image

Use the methods listed below to either read, write, or display an image or image sequence:

@@ -450,7 +480,7 @@ ImageMagick 6.6.5) and unpack it as shown below:

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 examples of select PerlMagick methods. Here is an example call to an image manipulation method:

@@ -707,7 +737,7 @@ ImageMagick 6.6.5) and unpack it as shown below:

Distort - points=>array of float values, method=>{Affine, AffineProjection, Bilinear, Perspective, ScaleRotateTranslate}, virtual-pixel=>{Background Black Constant Dither Edge Gray Mirror Random Tile Transparent White}, best-fit=>{True, False} + points=>array of float values, method=>{Affine, AffineProjection, Bilinear, Perspective, Resize, ScaleRotateTranslate}, virtual-pixel=>{Background Black Constant Dither Edge Gray Mirror Random Tile Transparent White}, best-fit=>{True, False} distort image @@ -905,7 +935,7 @@ ImageMagick 6.6.5) and unpack it as shown below:

MedianFilter - radius=>double + geometry=>geometry, width=>integer, height=>integer, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow} replace each pixel with the median intensity pixel of a neighborhood. @@ -915,6 +945,12 @@ ImageMagick 6.6.5) and unpack it as shown below:

half the size of an image + + Mode + geometry=>geometry, width=>integer, height=>integer, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow} + make each pixel the predominate color of the neighborhood. + + Modulate brightness=>double, saturation=>double, hue=>double, lightness=>double, whiteness=>double, blackness=>double @@ -1002,7 +1038,7 @@ fill=>color name, channel=>{All, De ReduceNoise - radius=>double + geometry=>geometry, width=>integer, height=>integer, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow} reduce noise in the image with a noise peak elimination filter @@ -1143,6 +1179,11 @@ fill=>color name, channel=>{All, De displace image pixels by a random amount + + Statistic + geometry=>geometry, width=>integer, height=>integer, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, type=>{Median, Mode, Mean, Maximum, Minimum, ReduceNoise} + replace each pixel with corresponding statistic from the neighborhood. + Stegano image=>image-handle, offset=>integer @@ -1319,7 +1360,7 @@ fill=>color name, channel=>{All, De

Set an Image Attribute

Use method Set() to set an image attribute. For example,

@@ -1697,7 +1738,7 @@ can use the integers 1 and 0.

type - {Bilevel, Grayscale, GrayscaleMatte, Palette, PaletteMatte, TrueColor, TrueColorMatte, ColorSeparation, ColorSeparationMatte, Optimize } + {Bilevel, Grayscale, GrayscaleMatte, Palette, PaletteMatte, TrueColor, TrueColorMatte, ColorSeparation, ColorSeparationMatte} image type @@ -1736,7 +1777,7 @@ can use the integers 1 and 0.

Get an Image Attribute

Use method Get() to get an image attribute. For example,

@@ -1988,7 +2029,7 @@ can use the integers 1 and 0.

Compare an Image to its Reconstruction

@@ -2046,7 +2087,7 @@ can use the integers 1 and 0.

In addition to the reported root mean squared error of around 0.024, a difference image is displayed so you can visually identify the difference between the images.

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,

@@ -2180,7 +2221,7 @@ South, SouthEast

Working with Blobs

A blob contains data that directly represent a particular image @@ -2233,7 +2274,7 @@ blobs in any of these image formats and provid

Direct-access to Image Pixels

Use these methods to obtain direct access to the image pixels:

@@ -2282,7 +2323,7 @@ blobs in any of these image formats and provid

Miscellaneous Methods

The Append() method append a set of images. For example,

@@ -2445,6 +2486,14 @@ blobs in any of these image formats and provid $image->RemoteCommand('image.jpg'); +

The Smush() method smushes a set of images together. For example,

+ +

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

+ +

smushes together all the images associated with object $image. By default, images are smushed left-to-right. Set stack to True to smushed them top-to-bottom.

Statistics() returns the image statistics for each channel in the image. The returned values are an array of depth, minima, maxima, mean, standard deviation, kurtosis, and skewness values in RGB, CMYK, RGBA, or CMYKA order (depending on the image type).

@@ -2461,7 +2510,7 @@ blobs in any of these image formats and provid

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:

@@ -2512,7 +2561,7 @@ blobs in any of these image formats and provid

Constants

PerlMagick includes these constants:

@@ -2581,7 +2630,7 @@ blobs in any of these image formats and provid