\title{Perl API Methods}
\toctitle{Perl API Methods}
\titlerunning{Perl API Methods}
\maketitle

\section{Image::Magick Attributes}
\label{Image::Magick Attributes}

An image has certain attributes associated with it such as width,
height, number of colors in the colormap, page geometry, and others.
Many of the image methods allow you to set relevant attributes directly
in the method call, or you can use Set(), as in:

{\small
\begin{verbatim}
    $image->Set(loop=>100);
    $image->[$x]->Set(dither=>1);
\end{verbatim}
}

To get an imageattribute, use Get():

{\small
\begin{verbatim}
    ($width, $height, $depth) = $image->Get('width', 'height', 'depth');
    $colors = $image->[2]->Get('colors');
\end{verbatim}
}

The methods GetAttribute() and SetAttribute() are aliases for Get() and
Set() and may be used interchangeably.

Following is a list of image attributes acceptable to either Set() or
Get() as noted.

\subsubsection{adjoin}
join images into a single multi-image file.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(adjoin=$>$\var{boolean}) \\
\hspace*{-0.25in}
\$image-$>$Get('adjoin')
\end{quote}

Certain file formats accept multiple images within a single file (e.g.
a GIF animation).  If \texttt{adjoin} is value other than 0 and the image is a
multi-image format, multiple reads to the same image object will join the
images into a single file when you call the Write() method.  Set
\texttt{adjoin} to 0 if you do not want the images output to a single file.

\subsubsection{antialias}
remove pixel aliasing.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(antialias=$>$\var{boolean}) \\
\hspace*{-0.25in}
\$image-$>$Get('antialias')
\end{quote}

The visible effect of antialias is to blend the edges of any text or
graphics with the image background.  This attribute affects how text and
graphics are rendered when certain image formats are read (e.g.
Postscript or SVG) or when certain Image::Magick methods are called
(e.g. Annotate() or Draw()).

\subsubsection{background}
image background color.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(background=$>$\var{color-name}) \\
\hspace*{-0.25in}
\$image-$>$Get('background')
\end{quote}

This attribute sets (or gets) the background color of an image.  Image formats
such as GIF, PICT, PNG, and WMF retain the background color information.

\subsubsection{base-filename}
base image filename (before transformations).

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('base-filename'')
\end{quote}

The original filename is returned as a string.

\subsubsection{base-height}
base image height (before transformations).

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('base-height')
\end{quote}

This attribute returns the original height of image before any
resizing operation.

\subsubsection{base-width}
base image width (before transformations).

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('base-width')
\end{quote}

This attribute returns the original width of image before any
resizing operation.


\subsubsection{blue-primary}
chromaticity blue primary point.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(blue-primary=$>$\var{x-value},\var{y-value}) \\
\hspace*{-0.25in}
\$image-$>$Get('blue-primary')
\end{quote}

This attribute sets or returns the chromaticity blue primary point.  This is
a color management option.

\subsubsection{cache-threshold}
cache threshold.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(cache-threshold=$>$\var{integer}) \\
\hspace*{-0.25in}
\$image-$>$Get('cache-threshold')
\end{quote}

Image pixels are stored in your computer's memory until it has been
consumed or the cache threshold is exceeded.  Subsequent pixel operations
are cached to disk. Operations to memory are significantly faster,
but if your computer does not have a sufficient amount of free memory
to read or transform an image, you may need to set this threshold to a
small megabyte value (e.g. 32).  Use 0 to cache all images to disk.

\subsubsection{class}
image class.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('class')
\end{quote}

A \texttt{Direct} class image is a continuous tone image and is stored
as a sequence of red-green-blue and optional opacity intensity values.
A \texttt{Pseudo} class image is an image with a colormap, where the
image is stored as a map of colors and a sequence of indexes into the map.

\subsubsection{clip-mask}
associate a clip mask with the image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set('clip-mask'=$>$\var{image}) \\
\$image-$>$Get('clip-mask') \\
\end{quote}

\texttt{Clip-mask} associates a clip mask with the image.

\subsubsection{colormap}
color of a particular colormap entry.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set('colormap[\var{\$i}]'=$>$\var{color-name}) \\
\hspace*{-0.25in}
\$image-$>$Get('colormap[\var{\$i}]')
\end{quote}

This attribute returns the red, green, blue, and opacity values
at colormap position \var{\$i}.  You can set the color with a
colorname (e.g. red) or color hex value (e.g. \#ccbdbd).

\subsubsection{colors}
number of distinct colors in the image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('colors')
\end{quote}

This attribute returns the number of distinct colors in the image.

\subsubsection{comment}
image comment.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('comment')
\end{quote}

Return the image comment.

\subsubsection{compression}
type of compression.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(compression=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('compression')
\end{quote}

\texttt{Compression} defaults to the compression type of the image when it was
first read.   The value of \texttt{compression} can be one of the following:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> None \> BZip \> Fax \\
\> Group4 \> JPEG \> LosslessJPEG \\
\> LZW \> RLE \> Zip
\end{tabbing}

If you set a compression type that is incompatible with the output file type,
a compatible compression value is used instead (e.g. a PNG image ignores
a \texttt{compression} value of JPEG and saves with Zip compression).

\subsubsection{delay}
interframe delay.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(delay=$>$\var{integer}) \\
\hspace*{-0.25in}
\$image-$>$Get('delay')
\end{quote}

\texttt{Delay} regulates the playback speed of a sequence of images.  The
value is the number of hundredths of a second that must pass before
displaying the next image.  The default is 0 which means there is no delay
and the animation will play as fast as possible.

\subsubsection{density}
image resolution.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(density=$>$\var{geometry}) \\
\hspace*{-0.25in}
\$image-$>$Get('density')
\end{quote}

This attribute to set the horizontal and vertical resolution of an
image.  Use attribute \texttt{units} to define the units of resolution.
The default is 72 dots-per-inch.

\subsubsection{depth}
color component depth.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('depth')
\end{quote}

Return the color component depth of the image, either 8 or 16.  A depth
of 8 represents color component values from 0 to 255 while a depth of
16 represents values from 0 to 65535.

\subsubsection{directory}
thumbnail names of an image montage.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('directory')
\end{quote}

A montage is one or more image thumbnails regularly spaced across a
color or textured background created by the Montage() method or
\textit{montage} program.  \texttt{Directory} returns the filenames
associated with each thumbnail.

\subsubsection{dispose}
GIF disposal method.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(dispose=$>$\var{0,  1,  2,  3}) \\
\hspace*{-0.25in}
\$image-$>$Get('dispose')
\end{quote}

The \texttt{dispose} attribute sets the GIF disposal method that defines how
an image is refreshed when flipping between scenes in a sequence.  The
disposal methods are defined as:

\begin{tabbing}
0000\=1111111111\=222222222222222\kill
\> 0 \> replace one full-size, non-transparent frame with another\\
\> 1 \> any pixels not covered up by the next frame continue to display\\
\> 2 \> background color or background tile shows through transparent pixels\\
\> 3 \> restore to the state of a previous, undisposed frame
\end{tabbing}

\subsubsection{dither}
apply dithering to the image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(dither=$>$\var{boolean}) \\
\hspace*{-0.25in}
\$image-$>$Get('dither')
\end{quote}

Color reduction is performed implicitly when an image is converted from
a file format that allows many colors to one that allows fewer
(e.g. JPEG to GIF).  Dithering helps smooth out the apparent contours
produced when sharply reducing colors.  The default is to dither an image
during color reduction.

\subsubsection{error}
mean error per pixel.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('error')
\end{quote}

This value reflects the mean error per pixel introduced when reducing the
number of colors in an image either implicitedly or explicitly:

\begin{enumerate}
\item Explicitly, when you use the Quantize() method.
\item Implicitly, when an image is converted from a file format that
allows many colors to one that allows fewer (e.g. JPEG to GIF).
\end{enumerate}

The mean error gives one measure of how well the color reduction
algorithm performed and how similiar the color reduced image is to the
original.

\subsubsection{file}
Perl filehandle.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(file=$>$\var{filehandle}) \\
\hspace*{-0.25in}
\$image-$>$Get('file')
\end{quote}

The Read() and Write() methods accept an already opened Perl filehandle
and the image is read or written directly from or to the specified filehandle.

\subsubsection{filename}
filename of image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(filename=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('filename')
\end{quote}

The default filename is the name of the file from which the image was read.
Write() accepts a filename as a parameter, however, if you do not specify one,
it uses the name defined by the \texttt{filename} attribute.  For example:

{\small
\begin{verbatim}
    $image->Read('logo.gif');
    $image->Write();                   # write image as logo.gif
    $image->Set(filename=>'logo.png');
    $image->Write();                   # write image as logo.png
\end{verbatim}
}

\subsubsection{filesize}
size of file in bytes.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('filesize')
\end{quote}

Returns the number of bytes the image consumes in memory or on disk.

\subsubsection{font}
text font.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(font=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('font')
\end{quote}

Both Annotate() and Draw() require a font to render text to an image.
A font can be Truetype (Arial.ttf), Postscript (Helvetica), or a
fully-qualified X11 font (-*-helvetica-medium-r-*-*-12-*-*-*-*-*-iso8859-*)
name.

\subsubsection{format}
descriptive image format.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('format')
\end{quote}

Attribute \texttt{magick} returns the abbreviated image format (e.g. JPEG)
while \texttt{format} returns more descriptive text about the format
(e.g. Joint Photographic Experts Group JFIF format).

\subsubsection{fuzz}
close colors are treated as equal.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(fuzz=$>$\var{integer}) \\
\hspace*{-0.25in}
\$image-$>$Get('fuzz')
\end{quote}

A number of image methods (e.g. ColorFloodfill()) compare a target color to a
color within the image.  By default these colors must match exactly.  However,
in many cases two colors may differ by a small amount.  \texttt{Fuzz} defines
how much tolerance is acceptable to consider two different colors as the same.
For example, set \texttt{fuzz} to 10 and the color red at intensities of 100
and 102 respectively are now interpreted as the same color.

\subsubsection{gamma}
image gamma.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(gamma=$>$\var{float}) \\
\hspace*{-0.25in}
\$image-$>$Get('gamma')
\end{quote}

Set or return the image gamma value.  Unlike Gamma() that actually
applies the gamma value to the image pixels, here we just set the
value.  This is useful if the correct gamma is already known about a
particular image.

\subsubsection{geometry}
shortcut for specifying width and height.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(geometry=$>$\var{geometry}) \\
\hspace*{-0.25in}
\$image-$>$Get('geometry')
\end{quote}

The \texttt{geometry} attribute is a convenient way to specify the width,
height, and any offset of an image region as a single string.  For example,

{\small
\begin{verbatim}
    geometry=>'640x80'
\end{verbatim}
}

is equivalent to:

{\small
\begin{verbatim}
    width=>640, height=>480
\end{verbatim}
}

To refer to a 20 x 20 region of pixels starting at coordinate (100, 150),
use:

{\small
\begin{verbatim}
    geometry=>'20x20+100+150'
\end{verbatim}
}

\subsubsection{gravity}
type of gravity.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(gravity=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('gravity')
\end{quote}

\texttt{Gravity} defaults to NorthWest.  The value of
\texttt{gravity} can be one of the following:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> NorthWest \> North \> NorthEast \\
\> West \> Center \> East \\
\> SouthWest \> South \> SouthEast
\end{tabbing}

\subsubsection{green-primary}
chromaticity green primary point.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(green-primary=$>$\var{x-value},\var{y-value}) \\
\hspace*{-0.25in}
\$image-$>$Get('green-primary')
\end{quote}

This attribute sets or returns the chromaticity green primary point.  This is
a color management option.

\subsubsection{height}
image height.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('height')
\end{quote}

This attribute returns the height (in pixel rows) of the image.

\subsubsection{index}
colormap index at a particular pixel location.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set('index[\var{\$x, \$y}]'=$>$\var{color-name}) \\
\hspace*{-0.25in}
\$image-$>$Get('index[\var{\$x, \$y}]')
\end{quote}

This attribute sets or returns the colormap index at position
(\var{\$x, \$y}).  The result is undefined if the image does not have a
colormap or the specified location lies outside the the image area.

\subsubsection{ICM}
color information profile.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('ICM')
\end{quote}

This attribute returns the color information profile.

\subsubsection{id}
ImageMagick registry ID.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('id')
\end{quote}

This attribute returns the ImageMagick registry ID.  The registry allows
for persistent images that can later be referenced as a filename (e.g.
\texttt{registry:0xbd}).

\subsubsection{interlace}
type of interlacing scheme.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(interlace=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('interlace')
\end{quote}

The \texttt{interlace} attribute allows you to specify the interlacing
scheme used by certain image formats such as GIF, JPEG, RGB, and CMYK.
The default is \texttt{None} but can be any of the following:

\begin{tabbing}
0000\=1111111111\=222222222222222\kill
\> None \> no interlacing \\
\> Line \> scanline interlacing \\
\> Plane \> plane interlacing \\
\> Partition \> partition interlacing
\end{tabbing}

\subsubsection{IPTC}
newswire information profile.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('IPTC')
\end{quote}

This attribute returns the newswire information profile.

\subsubsection{label}
image label.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(label=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('label')
\end{quote}

Use labels to optionally annotate a Postscript or PDF image or the thumbnail
images of a montage created by the Montage() method or \textit{montage} program.
A label can include any of the special formatting characters described in the
Comment() method description.

\subsubsection{loop}
add loop extension to your image sequence.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(loop=$>$\var{integer}) \\
\hspace*{-0.25in}
\$image-$>$Get('loop')
\end{quote}

The \texttt{loop} attribute adds the Netscape looping extension to an image
sequence.  A value of 0 causes the animation sequence to loop continuously.
Any other value results in the animation being repeated for the specified
number of times.  The default value is 1.


\subsubsection{magick}
image file format.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(magick=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('magick')
\end{quote}

The default image format is whatever format the image was in when it
was read.  Write() accepts an image format as a parameter, however, if you
do not specify one, it uses the format defined by the \texttt{magick}
attribute.  For example:

{\small
\begin{verbatim}
    $image->Read('logo.gif');
    $image->Write();                   # write image as GIF
    $image->Set(magick=>'PNG');
    $image->Write();                   # write image as PNG
\end{verbatim}
}

\subsubsection{matte}
transparency boolean.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(matte=$>$\var{boolean}) \\
\hspace*{-0.25in}
\$image-$>$Get('matte')
\end{quote}

Some images have a transparency mask associated with each pixel ranging
from opaque (pixel obscures background) to fully transparent (background
shows thru).  The transparency mask, if it exists, is ignored if
the \texttt{matte} attribute is 0 and all pixels are treated as opaque.

\subsubsection{maximum-error}
normalized maximum mean error per pixel.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('maximum-error')
\end{quote}

This value reflects the normalized maximum per pixel introduced when reducing
the number of colors in an image either implicitedly or explicitly:

\begin{enumerate}
\item Explicitly, when you use the Quantize() method.
\item Implicitly, when an image is converted from a file format that
allows many colors to one that allows fewer (e.g. JPEG to GIF).
\end{enumerate}

The normalized maximum error gives one measure of how well the color reduction
algorithm performed and how similiar the color reduced image is to the original.

\subsubsection{mean-error}
normalized mean mean error per pixel.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('mean-error')
\end{quote}

This value reflects the normalized mean per pixel introduced when reducing
the number of colors in an image either implicitedly or explicitly:

\begin{enumerate}
\item Explicitly, when you use the Quantize() method.
\item Implicitly, when an image is converted from a file format that
allows many colors to one that allows fewer (e.g. JPEG to GIF).
\end{enumerate}

The normalized mean error gives one measure of how well the color reduction
algorithm performed and how similiar the color reduced image is to the original.

\subsubsection{montage}
tile size and offset within an image montage.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('montage')
\end{quote}

A montage is one or more image thumbnails regularly spaced across a
color or textured background returned by the Montage() method or
\textit{montage} program.  The \texttt{montage} attribute returns the
geometry of the region associated with each image thumbnail
(e.g. 160x120+10+10).  This information is useful for creating image maps
for dynamic web pages.

\subsubsection{page}
perferred size and location of the image canvas.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(page=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('page')
\end{quote}

\texttt{Page} declares the image canvas size and location.  Typically this
is only useful for the Postscript, text, and GIF formats.  The value of
\texttt{string} can be:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Letter \> Tabloid \> Ledger \\
\> Legal \> Statement \> Executive \\
\> A3 \> A4 \> A5 \\
\> B4 \> B5 \> Folio \\
\> Quarto \> 10x14 \>
\end{tabbing}

or a geometry (612x792).  The default value is \texttt{Letter}.

\subsubsection{pointsize}
pointsize of a font.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(pointsize=$>$\var{integer}) \\
\hspace*{-0.25in}
\$image-$>$Get('pointsize')
\end{quote}

The \texttt{pointsize} attribute determines how large to draw a Postscript
or TrueType font with the Annotate() or Draw() methods.  The default is 12.

\subsubsection{preview}
type of image preview.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(preview=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('preview')
\end{quote}

Set or get the type of preview for the Preview image format.

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> 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
\end{tabbing}

Suppose we want to determine an ideal gamma setting for our image:

{\small
\begin{verbatim}
    $image->Write(filename=>'model.png',preview=>'Gamma');
    $image->Display();
\end{verbatim}
}

\subsubsection{quality}
compression level.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(quality=$>$\var{integer}) \\
\hspace*{-0.25in}
\$image-$>$Get('quality')
\end{quote}

The quality attribute sets the JPEG, MIFF, MNG, or PNG compression level.  The
range is 0 (worst) to 100 (best).  The default is 75.

Quality is a trade-off between image size and compression speed for the
MIFF, MNG, and PNG formats.  The higher the quality, the smaller the
resulting image size but with a requisite increase in compute time.
The quality value is used as two decimal digits.  The ``tens'' digit
conveys the zlib compression level and the ``ones'' digit conveys the
PNG filter method.  When the compression level is 0, the Huffman compression
strategy is used, which is fast but does not necessarily obtain the worst
compression.  The MIFF encoder ignores the PNG filter method conveyed
by the ``ones'' digit.

The JPEG trade-off is between image size and image appearance.  A high
quality returns an image nearly free of compression artifacts but with
a larger image size.  If you can accept a lower quality image
appearance, the resulting image size would be considerably less.

\subsubsection{red-primary}
chromaticity red primary point.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(red-primary=$>$\var{x-value},\var{y-value}) \\
\hspace*{-0.25in}
\$image-$>$Get('red-primary')
\end{quote}

This attribute sets or returns the chomaticity red primary point.  This is
a color management option.

\subsubsection{rendering-intent}
intended rendering model.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(rendering-intent=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('rendering-intent')
\end{quote}

This is a color management option.  Choose from these models:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Undefined \> Saturation \> Perceptual \\
\> Absolute \> Relative \>
\end{tabbing}

\subsubsection{sampling-factor}
image sampling factor.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set('sampling-factor'=$>$\var{geometry}) \\
\hspace*{-0.25in}
\$image-$>$Get('sampling-factor')
\end{quote}

Use this attribute to set the horizontal and vertical sampling factor
for use by the JPEG encoder.

\subsubsection{scene}
image scene number.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(scene=$>$\var{integer}) \\
\hspace*{-0.25in}
\$image-$>$Get('scene')
\end{quote}

By default each image in a sequence has a scene number that starts at 0 and
each subsequent image in the sequence increments by 1.  Use \texttt{scene} to
reset this value to whatever is appropriate for your needs.

\subsubsection{signature}
SHA-256 message digest.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('signature')
\end{quote}

Retrieves the SHA-256 message digest associated with the image.
A signature is generated across all the image pixels.  If a single pixel
changes, the signature will change as well.  The signature is mostly useful
for quickly determining if two images are identical or if an image has been
modified.

\subsubsection{size}
width and height of a raw image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(size=$>$\var{geometry}) \\
\hspace*{-0.25in}
\$image-$>$Get('size')
\end{quote}

Set the \texttt{size} attribute before reading an image from a raw data file
format such as RGB, GRAY, TEXT, or CMYK (e.g. 640x480) or identify a desired
resolution for Photo CD images (e.g. 768x512).

{\small
\begin{verbatim}
    $image->Set(size=>'640x480');
    $image->Read('gray:protein');
\end{verbatim}
}

\subsubsection{server}
X server to contact.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(server=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('server')
\end{quote}

Display(), Animate(), or any X11 font use with Annotate() require contact with
an X server.  Use \texttt{server} to specify which X server to contact (e.g.
\texttt{mysever:0}).

\subsubsection{taint}
pixel change boolean.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('taint')
\end{quote}

\texttt{Taint} returns a value other than 0 if any image pixel has modified
since it was first read.

\subsubsection{texture}
name of texture to tile.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(texture=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('texture')
\end{quote}

The \texttt{texture} attribute assigns a filename of a texture to be tiled
onto the image background when any TXT or WMF image formats are read.

\subsubsection{type}
image type.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(type=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('type')
\end{quote}

The image type can be any of the following

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Bilevel \> Grayscale \> GrayscaleMatte \\
\> Palette \> PaletteMatte \> TrueColor\\
\> TrueColorMatte \>  ColorSeparation \>  ColorSeparationMatte \\
\> Optimize
\end{tabbing}

When getting this attribute, the value reflects the type of image pixels.
For example a colormapped GIF image would most likely return Palette as the
image type.  You can also force a particular type with Set().  For example if
you want to force your color image to black and white, use:

{\small
\begin{verbatim}
    $image->Set(type=>'Bilevel');
\end{verbatim}
}

\subsubsection{units}
units of resolution.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(units=$>$\var{string}) \\
\hspace*{-0.25in}
\$image-$>$Get('units')
\end{quote}

Return or set the units in which the image's resolution are defined.
Values may be:

\begin{tabbing}
0000\=111111111111111\kill
\> Undefined \\
\> pixels/inch \\
\> pixels/centimeter
\end{tabbing}

\subsubsection{verbose}
print details.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(verbose=$>$\var{boolean}) \\
\end{quote}

When set, \texttt{verbose} causes some image operations to print details
about the operation as it progresses.

\subsubsection{white-point}
chromaticity white point.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(white-point=$>$\var{x-value},\var{y-value}) \\
\hspace*{-0.25in}
\$image-$>$Get('white-point')
\end{quote}

This attribute sets or returns the chomaticity white point.  This is
a color management option.

\subsubsection{width}
image width.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('width')
\end{quote}

Returns the width (integer number of pixel columns) of the image.

\subsubsection{x-resolution}
horizontal resolution.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('x-resolution')
\end{quote}

Returns the \textit{x} resolution of the image in the units defined
by the \texttt{units} attribute (e.g. 72 pixels/inch).  Use the
\texttt{density} attribute to change this value.

\subsubsection{y-resolution}
vertical resolution.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get('y-resolution')
\end{quote}

Returns the \textit{y} resolution of the image in the units defined
by the \texttt{units} attribute (e.g. 72 pixels/inch). Use the
\texttt{density} attribute to change this value.

\section{Image::Magick Methods}

\subsubsection{AddNoise()}
add noise to an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$AddNoise(noise=$>$\var{string})
\end{quote}

This method adds random noise to the image, where \var{string} specifies one
of the following types:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Uniform \> Gaussian \> Multiplicative \\
\> Impulse \> Laplacian \> Poisson
\end{tabbing}

\subsubsection{AffineTransform}
affine transform the image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$AffineTransform(affine=$>$\var{array of float values},
rotate=$>$\var{rotate-angle}, scale=$>$\var{sx, sy}, skewX=$>$\var{skew-angle},
skewY=$>$\var{skew-angle}, translate=$>$\var{tx, ty})
\end{quote}

AffineTransform()

\begin{description}
\item[rotate] Specifies a rotation of \var{rotate-angle} degrees about a given
point.
\item[scale] Specifies a scale operation by \var{sx} and \var{sy}.
\item[skewX] Specifies a skew transformation along the x-axis.
\item[skewY] Specifies a skew transformation along the y-axis.
\item[translate] Specifies a translation by \var{tx} and \var{ty}.
\end{description}

\subsubsection{Animate()}
animate an image sequence.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Animate()
\end{quote}

Animate() repeatedly displays an image sequence to any X window screen.  This
method accepts the same parameters as Set() as described in section
\ref{Image::Magick Attributes}.

\subsubsection{Annotate()}
annotate an image with text.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Annotate(text=$>$\var{string}, affine=$>$\var{array of float values},
align=$>$\var{string}, antialias=$>$\var{boolean},
density=$>$\var{geometry}, encoding$>$\var{string},
fill=$>$\var{color-name}, family=$>$\var{string}, font=$>$\var{string},
geometry=$>$\var{geometry}, gravity=$>$\var{string}, pointsize=$>$\var{integer},
rotate=$>$\var{rotate-angle}, scale=$>$\var{sx, sy}, skewX=$>$\var{skew-angle},
skewY=$>$\var{skew-angle}, stroke=$>$\var{color-name},
strokewidth=$>$\var{integer}, stretch=$>$\var{string}, style=$>$\var{string},
translate=$>$\var{tx, ty}, undercolor=$>$\var{color-name},
unicode=$>$\var{boolean}, weight=$>$\var{string}, x=$>$\var{integer},
y=$>$\var{integer})
\end{quote}

Annotate() allows you to scribble text across an image.  The text may be
represented as a string or filename.  Precede the filename with an
"at" sign (\texttt{@}) and the contents of the file are drawn on the
image.   You can affect how text is drawn by specifying one or more
of the following parameters:

\begin{description}
\item[align] font alignment.  Choose from these alignments:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Left \> Center \> Right
\end{tabbing}

\item[antialias] The visible effect of antialias is to smooth out the
rounded corners of text characters.  Set to 0 to keep crisp edges.
\item[density] Set the vertical and horizontal resolution of the font.
The default is 72 pixels/inch.
\item[encoding] Font encoding.
\item[family] font family.
\item[fill] The fill color paints any areas inside the outline of the text.
\item[font] A font can be a Truetype (arial.ttf), Postscript (Helvetica), or a
fully-qualified X11 font (-*-helvetica-medium-r-*-*-12-*-*-*-*-*-iso8859-*).
\item[geometry] Geometry defines the baseline position where text is
rendered (e.g. +100+50).
\item[gravity] Gravity affects how the text is rendered relative to the
(\var{x, y}) baseline position.  By default gravity is NorthWest which renders
text above the baseline position.  Choose from these gravities:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> NorthWest \> North \> NorthEast \\
\> West \> Center \> East \\
\> SouthWest \> South \> SouthEast
\end{tabbing}

\item[pointsize] The font pointsize.  The default is 12.
\item[rotate] Specifies a rotation by the specified number of degrees about a
given point.
\item[scale] Specifies a scale operation by \var{sx} and \var{sy}.
\item[skewX] Specifies a skew transformation along the x-axis.
\item[skewY] Specifies a skew transformation along the y-axis.
\item[stretch] font stretch.  Choose from these stretches:
\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Normal \> UltraCondensed \> ExtraCondensed \\
\> Condensed \> SemiCondensed \> SemiExpanded \\
\> Expanded \> ExtraExpanded \> UltraExpanded
\end{tabbing}

\item[stroke] A stroke color paints along the outline of the text.
\item[strokewidth] The width of the stroke on the text.  A zero value
causes no stroke to be painted.
\item[style] font style.  Choose from these styles:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Normal \> Italic \> Oblique \\
\> Any 
\end{tabbing}

\item[translate] Specifies a translation by \var{tx} and \var{ty}.
\item[undercolor] By default text is blended with the image background.
Set the undercolor color to give a uniform background to your text of the
color you choose.
\item[unicode] Set to true if text is Unicode.
\item[weight] Font weight.
\item[x] Specifies the \var{x} baseline position of the text.
\item[y] Specifies the \var{y} baseline position of the text.
\end{description}

\subsubsection{Append()}
append a set of images.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Append(stack=$>$\var{boolean})
\end{quote}

The Append() method takes a set of images and appends them to each other.
Append() returns a single image where each image in the original set
is side-by-side.  If the stack parameter is True, the images
are stacked top-to-bottom.

{\small
\begin{verbatim}
    $append = $image->Append();
\end{verbatim}
}

\subsubsection{Average()}
average a set of images.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Average()
\end{quote}

The Average() method takes a set of images and averages them together.
Each image in the set must have the same width and the same height.
Average() returns a single image with each corresponding pixel component
of each image averaged.

\subsubsection{BlobToImage()}
return an image from a Binary Large OBject.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$BlobToImage(\var{blob})
\end{quote}

Read() returns an image from a file on disk, whereas, BlobToImage() performs
the same function if the image format is stored in memory:

{\small
\begin{verbatim}
    @blob = $db->GetImage();    # get blob from database
    $image = Image::Magick->New(magick=>'jpg');
                                # the blob is a JPEG image
    $image->BlobToImage(@blob); # convert blob to Image::Magick object
\end{verbatim}
}

\subsubsection{Blur()}
blur the image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Blur(geometry=$>$\var{geometry}, radius=$>$\var{float},
  sigma=$>$\var{float})
\end{quote}

Blur() blurs an image.  We convolve the image with a Gaussian operator of the
given radius and standard deviation (sigma).  For reasonable results, the
radius should be larger than sigma.  Use a radius of 0 and Blur()
selects a suitable radius for you.  \texttt{Geometry} represents
radius x sigma as one parameter (e.g. 0x1).

\subsubsection{Border()}
frame the image with a border.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Border(geometry=$>$\var{geometry}, width=$>$\var{integer},
  height=$>$\var{integer}, fill=$>$\var{color-name})
\end{quote}

This method surrounds the image with a border of the specified color.
\texttt{Geometry} represents {\it width x height} as one parameter (e.g. 10x5).

\subsubsection{Channel()}
extract a channel from the image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Channel(channel=$>$\var{string});
\end{quote}

Extract a channel from the image.  A channel is a particular color component
of each pixel in the image.  Choose from these components:

\begin{tabbing}
0000\=111111\kill
\> Red \\
\> Cyan \\
\> Green \\
\> Magenta \\
\> Blue \\
\> Yellow \\
\> Opacity \\
\> Black
\end{tabbing}

\subsubsection{Charcoal()}
special effect filter.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Charcoal(geometry=$>$\var{geometry}, radius=$>$\var{float},
  sigma=$>$\var{float})
\end{quote}

Charcoal() is a special effect filter that simulates a charcoal drawing.
We convolve the image with a Gaussian operator of the given radius and
standard deviation (sigma).  For reasonable results, radius should be larger
than sigma.  Use a radius of 0 and Charcoal() selects a suitable radius for
you.  \texttt{Geometry} represents radius x sigma as one parameter
(e.g. 0x1).

\subsubsection{Chop()}
chop an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Chop(geometry=$>$geometry,  width=$>$integer,  height=$>$integer,
  x=$>$integer,  y=$>$integer)
\end{quote}

Chop() removes a region of an image and collapses the image to occupy the
removed portion.  Columns \texttt{x} through \texttt{x+width} and the rows
\texttt{y} through \texttt{y+height} are chopped.  Use \texttt{Geometry} as a
shortcut for {\it width x height + x + y} (e.g. 100x50+10+20).

\subsubsection{Clone()}
create a new copy of an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Clone()
\end{quote}

The Clone() method copies a set of images and returns the copy as a new
image object.  For example

{\small
\begin{verbatim}
    $clone = $image=>Clone();
\end{verbatim}
}

copies all of the images from \texttt{\$image} to \texttt{\$clone}.

\subsubsection{Coalesce()}
coalesce a set of images.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Coalesce()
\end{quote}

This method composites a set of images while respecting any page
offsets and disposal methods.  GIF, MIFF, and MNG animation sequences
typically start with an image background and each subsequent image
varies in size and offset.  Coalesce() returns a new sequence
where each image in the sequence is the same size as the first and
composited over the previous images in the sequence.

\subsubsection{ColorFloodfill()}
floodfill the designed area with color.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$ColorFloodfill(geometry=$>$\var{geometry},  x=$>$\var{integer},
y=$>$\var{integer},  fill=$>$\var{color-name},  bordercolor=$>$\var{color-name},
fuzz=$>$\var{float})
\end{quote}

ColorFloodfill() changes the color value of any pixel that matches
\texttt{fill} and is an immediate neighbor.  If \texttt{bordercolor} is
specified, the color value is changed for any neighbor pixel that
is not \texttt{bordercolor}.  Use \texttt{Geometry} as a shortcut for
{\it x + y} (e.g. +10+20).

By default \texttt{fill} must match a particular pixel color exactly.
However, in many cases two colors may differ by a small amount.
\texttt{Fuzz} defines how much tolerance is acceptable to consider
two colors as the same.  For example, set fuzz to 10 and the color red
at intensities of 100 and 102 respectively are now interpreted as the
same color for the purposes of the floodfill.

\subsubsection{Colorize()}
colorize an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Colorize(fill=$>$\var{color-name},  opacity=$>$\var{string})
\end{quote}

Colorize() blends the fill color with each pixel in the image.  A
percentage blend is specified with \texttt{opacity}.  Control the
application of different color components by specifying a different
percentage for each component (e.g. 90/100/10 is 90\% red, 100\% green,
and 10\% blue).

\subsubsection{Comment()}
add a comment to an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Comment(comment=$>$\var{string})
\end{quote}

Add a comment to an image.  Optionally you can include any of the following
bits of information about the image by embedding the appropriate special
characters:

\begin{tabbing}
0000\=1111\=222222222222222\kill
\> \%b \>  file size in bytes. \\
\> \%c \>  comment. \\
\> \%d \>  directory in which the image resides. \\
\> \%e \>  extension of the image file. \\
\> \%f \>  original filename of the image. \\
\> \%g \>  page geometry. \\
\> \%h \>  height of image. \\
\> \%i \>  filename of the image. \\
\> \%k \>  number of unique colors. \\
\> \%l \>  image label. \\
\> \%m \>  image file format. \\
\> \%n \>  number of images in the image sequence. \\
\> \%o \>  output image filename. \\
\> \%p \>  page number of the image. \\
\> \%q \>  image depth (8 or 16). \\
\> \%s \>  image scene number. \\
\> \%t \>  image filename without any extension. \\
\> \%u \>  a unique temporary filename. \\
\> \%w \>  image width. \\
\> \%x \>  x resolution of the image. \\
\> \%y \>  y resolution of the image. \\
\> \%z \>  image depth. \\
\> \%\# \>  SHA-256 message digest.
\end{tabbing}

Given an image whose filename is \texttt{logo.gif} and dimensions of
640 pixels in width and 480 pixels in height, this statement:

{\small
\begin{verbatim}
    $image->Comment('%f %m %wx%h')
\end{verbatim}
}

generates a comment that reads: \texttt{logo.gif GIF 640x480}.

\subsubsection{Composite}
composite one image to another.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Composite(image=$>$\var{image-handle}, color=$>$\var{color-name},
compose=$>$\var{string}, geometry=$>$\var{geometry}, mask=$>$\var{image-handle},
gravity=$>$\var{string}, opacity=$>$\var{integer}, rotate=$>$\var{float},
tile=$>$\var{boolean} x=$>$\var{integer}, y=$>$\var{integer},
)
\end{quote}

Composite() allows you to overlay one image to another.  You can affect
how and where the composite is overlaid by specifying one or more of the
following options:

\begin{description}
\item[compose] This operator affects how the composite is applied to
the image.  The default is Over.  Choose from these operators:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Over \> In \> Out \\
\> Atop \> Xor \> Plus \\
\> Minus \> Add \> Subtract \\
\> Difference \> Bumpmap \> Copy \\
\> Displace
\end{tabbing}

\item[geometry] Geometry defines the baseline position where the composite is
placed (e.g. +100+50).
\item[gravity] Gravity affects how the image is placed
relative to the (\var{x, y}) baseline position.  By default
gravity is NorthWest which renders the image just below the baseline position.
Choose from these gravities:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> NorthWest \> North \> NorthEast \\
\> West \> Center \> East \\
\> SouthWest \> South \> SouthEast
\end{tabbing}
\item[image] The image.
\item[mask] The mask image.
\item[opacity] Blend composite with the image background.  \texttt{Opacity}
is expressed as percent transparency.
\item[rotate] Rotate image before it is composited, expressed in degrees.
\item[tile] A value other than 0 tiles the composite repeatedly across
\item[x] Specifies the \var{x} baseline position of the composite.
\item[y] Specifies the \var{y} baseline position of the composite.
and down the image.
\end{description}



\subsubsection{Contrast()}
enhance or reduce the image contrast.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Contrast(sharpen=$>$\var{boolean})
\end{quote}

Contrast() enhances the intensity differences between the lighter and
darker elements of the image.  Set \texttt{sharpen} to a value other than
0 to increase the image contrast otherwise the contrast is reduced.

\subsubsection{Convolve()}
apply a convolution kernel to the image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Convolve(coefficients=$>$\var{array of float values})
\end{quote}

Apply a custom convolution kernel to the image.  Given a particular
kernel \var{order}, you must supply \var{order x order} float values.
For example, a kernel of order 3 implies 9 values (3x3):

{\small
\begin{verbatim}
    $image->Convolve([1, 2, 1, 2, 4, 2, 1, 2, 1]);
\end{verbatim}
}

\subsubsection{Crop}
crop an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Crop(geometry=$>$\var{geometry}, width=$>$\var{integer},
  height=$>$\var{integer},  x=$>$\var{integer},  y=$>$\var{integer})
\end{quote}

Crop() extracts a region of the image starting at the offset defined
by \texttt{x} and \texttt{y} and extending for \texttt{width} and
\texttt{height}.  \texttt{Geometry} is a shorthard method to define
a region.  To crop 100 x 50 region that begins at position (10, 20),
use

{\small
\begin{verbatim}
    $image->Crop('100x50+10+20');
\end{verbatim}
}

\subsubsection{CycleColormap}
displace a colormap.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$CycleColormap(display=$>$\var{integer})
\end{quote}

CycleColormap() displaces an image's colormap by a given number of positions.
If you cycle the colormap a number of times you can produce a psychodelic
effect.

\subsubsection{Deconstruct}
return the constituent parts of an image sequence.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Deconstruct()
\end{quote}

Deconstruct() returns a new sequence that consists of the first image
in the sequence followed by the maximum bounding region of any differences
in subsequent images.  This method can undo a coalesced sequence returned
by Coalesce(), and is useful for removing redundant information
from a GIF or MNG animation.

\subsubsection{Despeckle}
filter speckles.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Despeckle()
\end{quote}

Despeckle() reduces the {\em speckle} noise in an image while perserving
the edges of the original image.

\subsubsection{Display()}
display image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Display(server=$>$\var{server-name})
\end{quote}

Display() displays the image to any X window screen.

\subsubsection{Draw}
annotate an image with a graphic primitive.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Draw(primitive=$>$\var{string},
affine=$>$\var{array of float values}, antialias=$>$\var{boolean},
bordercolor=$>$\var{color-name}, density=$>$\var{geometry},
fill=$>$\var{color-name}, font=$>$\var{string}, geometry=$>$\var{geometry},
method=$>$\var{string}, points=$>$\var{string}, pointsize=$>$\var{integer},
rotate=$>$\var{rotate-angle}, scale=$>$\var{sx, sy}, skewX=$>$\var{skew-angle},
skewY=$>$\var{skew-angle}, stroke=$>$\var{color-name},
strokewidth=$>$\var{integer}, translate=$>$\var{tx, ty}
\end{quote}

Draw() allows you to draw a graphic primitive on your image.  The primitive
may be represented as a string or filename.  Precede the filename with an
"at" sign (\texttt{@}) and the contents of the file are drawn on the
image.   You can affect how text is drawn by specifying one or more
of the following parameters:

\begin{description}
\item[primitive]  The primitive describes the type of graphic to draw.
Choose from these primitives:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Point \> Line  \> Rectangle \\
\> roundRectangle  \> Arc  \> Ellipse \\
\> Circle  \> Polyline  \> Polygon \\
\> Bezier  \> Path  \> Color \\
\> Matte \> Text \> Image
\end{tabbing}
\item[antialias] The visible effect of antialias is to smooth out the
rounded corners of the drawn shape.  Set to 0 to keep crisp edges.
\item[bordercolor] The Color primitive with a method of FloodFill
changes the color value of any pixel that matches \texttt{fill} and is an
immediate neighbor.  If \texttt{bordercolor} is specified, the color
value is changed for any neighbor pixel that is not \texttt{fill}.
\item[density] This parameter sets the vertical and horizontal resolution of
the font.  The default is 72 pixels/inch.
\item[fill] The fill color paints any areas inside the outline of drawn shape.
\item[font] A font can be a Truetype (arial.ttf), Postscript (Helvetica), or a
fully-qualified X11 font (-*-helvetica-medium-r-*-*-12-*-*-*-*-*-iso8859-*).
\item[geometry] Geometry defines the baseline position where the graphic
primitive is rendered (e.g. +100+50).
\item[method] Primitives Matte and Image behavior depends on the painting
method you choose:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Point \> Replace  \> Floodfull \\
\> FillToBorder \> Reset
\end{tabbing}
\item[points] List one or more sets of coordinates as required by
the graphic primitive you selected.
\item[pointsize] The font pointsize.  The default is 12.
\item[rotate] Specifies a rotation of \var{rotate-angle} degrees about a given
point.
\item[scale] Specifies a scale operation by \var{sx} and \var{sy}.
\item[skewX] Specifies a skew transformation along the x-axis.
\item[skewY] Specifies a skew transformation along the y-axis.
\item[stroke] A stroke color paints along the outline of the shape.
\item[strokewidth] The width of the stroke of the shape.  A zero value
means no stroke is painted.
\item[translate] Specifies a translation by \var{tx} and \var{ty}.
\end{description}

\subsubsection{Edge}
detect edges within an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Edge(radius=$>$\var{float})
\end{quote}

Edge() finds edges in an image.  \texttt{Radius} defines the radius of
the convolution filter.  Use a radius of 0 and Edge() selects a suitable
radius for you.

\subsubsection{Emboss}
emboss the image.

\begin{quote}
\hspace*{-0.25in}
\code{\$image-$>$Emboss(geometry=$>$\var{geometry},  radius=$>$\var{float},
  sigma=$>$\var{float})}
\end{quote}

Emboss() returns a grayscale image with a three-dimensional effect.
We convolve the image with a Gaussian operator of the given radius and
standard deviation (sigma).  For reasonable results, radius should be
larger than sigma.  Use a radius of 0 and Emboss() selects a suitable
radius for you.  \texttt{Geometry} represents radius x sigma as one
parameter (e.g. 0x1).

\subsubsection{Enhance}
filter a noisy image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Enhance()
\end{quote}

Enhance() applies a digital filter that improves the quality of a noisy
image.

\subsubsection{Equalize}
equalize an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Equalize()
\end{quote}

Perform a histogram equalization on the image.

\subsubsection{Flatten()}
flatten a sequence of images.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Coalesce()
\end{quote}

This method composites a sequence of images while respecting any page
offsets.  A Photoshop image typically starts with an image background and
each subsequent layer varies in size and offset.  Flatten() returns a single
image with all the layers composited onto the first image in the sequence.

\subsubsection{Flip}
reflect an image vertically.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Flip()
\end{quote}

Flip() creates a vertical mirror image by reflecting the pixels around the
central x-axis.

\subsubsection{Flop}
reflect an image horizontally.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Flop()
\end{quote}

Flop() creates a horizontal mirror image by reflecting the pixels around the
central y-axis.

\subsubsection{Frame}
surround the image with a decorative border.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Frame(geometry=$>$\var{geometry},  width=$>$\var{integer},
  height=$>$\var{integer},  inner=$>$\var{integer},  outer=$>$\var{integer},
  fill=$>$\var{color-name})
\end{quote}

Frame() adds a simulated three-dimensional border around the image.
The color of the border is defined by \texttt{fill}.
\texttt{Width} and \texttt{height} specify the border width of the
vertical and horizontal sides of the frame.  The \texttt{inner} and
\texttt{outer} parameters indicate the width of the inner and outer
{\em shadows} of the frame.  Use \texttt{Geometry} as a shortcut for
\texttt{width}, \texttt{height}, \texttt{inner}, and \texttt{outer}
(e.g. 10x10+3+3).

\subsubsection{Gamma}
gamma-correct the image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Gamma(gamma=$>$\var{string},
  channel=$>$\var{Red, Green, Blue, Opacity, Index, Cyan, Yellow, Magenta, Black, or All})
\end{quote}

Use Gamma() to gamma-correct an image.  The same image viewed on
different devices will have perceptual differences in the way the
image's intensities are represented on the screen.  Specify individual
gamma levels for the red, green, and blue channels, or adjust all three
with the \texttt{gamma} parameter.  Values typically range from 0.8 to
2.3.

You can also reduce the influence of a particular channel with a gamma value
of 0.

\subsubsection{Get()}
get an image attribute.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Get(\var{attribute}, ...)
\end{quote}

Get() accepts one or more image attributes listed in section
\ref{Image::Magick Attributes} and return their value.

\subsubsection{ImageToBlob()}
return image as a Perl variable.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$ImageToBlob()
\end{quote}

ImageToBlob() behaves just like Write() except the image is returned
as a Perl variable rather than written to disk.  This method accepts the
same parameters as Set() as described in section \ref{Image::Magick
Attributes}.

\subsubsection{Implode()}
apply an implosion/explosion filter.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Implode(amount=$>$\var{double})
\end{quote}

Implode() applies a special effects filter to the image where
\texttt{amount} determines the amount of implosion.  Use a negative
amount for an explosive effect.

\subsubsection{Label()}
add a label to an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Label(label=$>$\var{string})
\end{quote}

Use labels to optionally annotate a Postscript or PDF image or the thumbnail
images of a montage created by the Montage() method or \textit{montage} program.
A label can include any of the special formatting characters described in the
Comment() method description.

\subsubsection{Level}
adjust the level of image contrast.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Level(levels=$>$\var{string},
  'black-point'=$>$\var{float}, 'mid-point'=$>$\var{float},
  'white-point'=$>$\var{float})
\end{quote}

The white and black points range from 0 to MaxRGB and mid ranges from 0 to 10.

\subsubsection{Magnify()}
scale the image to twice its size.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Magnify()
\end{quote}

Magnify() is a convenience method that scales an image proportionally
to twice its size.

\subsubsection{Map()}
choose a set of colors from another image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Map(image=$>$\var{image-handle},  dither=$>$\var{boolean})
\end{quote}

Map() changes the colormap of the image to that of the image given by
\texttt{image}.  Use this method to change the colormap in an image or
image sequence to a set of predetermined colors.  Set \texttt{dither}
to a value other than zero to helps smooth out the apparent contours
produced when sharply reducing colors.

One useful example of mapping is to convert an image to the Netscape
216-color web safe palette:

{\small
\begin{verbatim}
    $safe = new Image::Magick;
    $safe->Read('Netscape:');
    $image->Map(image=>$safe, dither=>'True');
\end{verbatim}
}

\subsubsection{MatteFloodfill()}
floodfill an area with transparency.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$MatteFloodfill(geometry=$>$\var{geometry},  x=$>$\var{integer},
y=$>$\var{integer},  opacity=$>$\var{integer},  bordercolor=$>$\var{color-name},
fuzz=$>$\var{float})
\end{quote}

MatteFloodfill() changes the transparency value of any pixel that matches
\texttt{opacity} and is an immediate neighbor.  If \texttt{bordercolor} is
specified, the transparency value is changed for any neighbor pixel that
is not \texttt{bordercolor}.  Use \texttt{Geometry} as a shortcut for
{\it x + y} (e.g. +10+20).

By default \texttt{opacity} must match a particular pixel transparency exactly.
However, in many cases two transparency values may differ by a small
amount.  \texttt{Fuzz} defines how much tolerance is acceptable to consider
two transparency values as the same.  For example, set fuzz to 10 and the
opacity values of 100 and 102 respectively are now interpreted as the
same value for the purposes of the floodfill.

\subsubsection{MedianFilter()}
filter a noisy image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$MedianFilter(radius=$>$\var{float})
\end{quote}

MedianFilter() applies a digital filter that improves the quality of a noisy
image.  Each pixel is replaced by the median in a set of neighboring pixels
as defined by \texttt{radius}.


\subsubsection{Minify()}
scale the image to half its size.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Magnify()
\end{quote}

Minify() is a convenience method that scales an image proportionally
to half its size.

\subsubsection{Modulate}
adjust the brightness, saturation, and hue.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Modulate(factor=$>$\var{string}, brightness=$>$\var{float},
  saturation=$>$\var{float}, hue=$>$\var{float})
\end{quote}

Modulate() lets you control the brightness, saturation, and hue of an image.
Each parameter is in the form of a percentage relative to 100.  For example,
to decrease the brightness by 10% and increase saturation by 50%, use:

{\small
\begin{verbatim}
    $image->Modulate(brightness=$>$90, saturation=$>$150);
\end{verbatim}
}

\texttt{Factor} represents the brightness, saturation, and hue as one
parameter (e.g. 90/150/100).

\subsubsection{Mogrify()}
alternative calling scheme.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Mogrify(method, ...)
\end{quote}

The Mogrify() method is convenience function that allows you to call any
image manipulation method by giving a method name followed by one or
parameters to pass to the method.   The following calls have the same
result:

{\small
\begin{verbatim}
    $image->Crop('340x256+0+0')
    $image->Mogrify('Crop', '340x256+0+0')
\end{verbatim}
}

\subsubsection{MogrifyRegion()}
apply method to a region.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$MogrifyRegion(geometry, method, ...)
\end{quote}

MogrifyRegion() applies an image manipulation method to a region of the
image as defined by \var{geometry}.  For example if you want to sharpen
a 100 x 100 region starting at position (20, 20), use:
result:

{\small
\begin{verbatim}
    $image->MogrifyRegion('100x100+20+20', Sharpen, '0x1')
\end{verbatim}
}

\subsubsection{Montage()}
uniformly tile thumbnails across an image canvas.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Montage(background=$>$\var{color-name},
  bordercolor=$>$\var{color-name}, borderwidth=$>$\var{integer},
  compose=$>$\var{string}, fill=$>$\var{color-name}, font=$>$\var{string},
  frame=$>$\var{geometry},  geometry=$>$\var{geometry}, gravity=$>$\var{string},
  label=$>$\var{string}, mattecolor=$>$\var{color-name}, mode=$>$\var{string},
  pointsize=$>$\var{integer}, shadow=$>$\var{boolean},
  stroke=$>$\var{color-name}, texture=$>$\var{string},
  tile=$>$\var{geometry}, title=$>$\var{string},
  transparent=$>$\var{color-name})
\end{quote}

The Montage() method is a layout manager that lets you tile one or more
thumbnails across an image canvas.  Use these parameters to control how the
layout manager places the thumbnails:

\begin{description}
\item[background] The color name for the montage background.
\item[bordercolor]  The color name for the thumbnail border.
\item[borderwidth] The width of the thumbnail border.
\item[compose] This operator affects how the thumbnail is composited
on the image canvas.  The default is Over.  Choose from these operators:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Over, \> In \> Out \\
\> Atop \> Xor \> Plus \\
\> Minus \> Add \> Subtract \\
\> Difference \> Bumpmap \> Copy \\
\> Displace
\end{tabbing}
\item[fill] The fill color paints any areas inside the outline of the
thumbnail label.
\item[font] A font can be a Truetype (arial.ttf), Postscript (Helvetica), or a
fully-qualified X11 font (-*-helvetica-medium-r-*-*-12-*-*-*-*-*-iso8859-*).
\item[frame]  Adds a simulated three-dimensional border around each thumbnail.
The color of the border is defined by \texttt{mattecolor}.  Specify
the border width of the vertical and horizontal sides of the frame
and the inner and outer {\em shadows} of the frame as a geometry (e.g.
10x10+3+3).
\item[geometry] Geometry defines the baseline position where a thumbnail is
composited (e.g. +100+50).
\item[gravity] Gravity affects how the thumbnail is placed
relative to the (\var{x, y}) baseline position.  By default
gravity is South which positions the thumbnail centered south of the
baseline position.  Choose from these gravities:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> NorthWest \> North \> NorthEast \\
\> West \> Center \> East \\
\> SouthWest \> South \> SouthEast
\end{tabbing}
\item[label] A label optionally appears just below each thumbnail.  Use this
parameter to customize the label.  See Comment() for a list of embedded
formatting options for the thumbnail label.
\item[mode]  Define one of three thumbnail framing options:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Frame \> Unframe \> Concatentate
\end{tabbing}

The default is \texttt{Frame} which adds a simulated three-dimensional border
around each thumbnail.  \texttt{Unframe} tiles thumbnails without any
border or frame, and \texttt{Concatentate} causes each image to be
tightly packed without any border, frame, or space between them.
\item[pointsize] The font pointsize.  The default is 12.
\item[shadow]  Any value other than 0 will add a simulated shadow beneath and
to the right side of each thumbnail.
\item[stroke] The stroke color paints along the outline of any text labels.
\item[texture]  Tile this image across and down the image canvas before
compositing the image thumbnails.
\item[tile] Give the number of thumbnails across and down the canvas
as a geometry string.  The default is 5 x 4.  If the number of thumbnails
exceed this maximum, more then one image canvas is created.
\item[title] Give a title to the montage.  The title is centered near the top
of the montage image.
\item[transparent]  Make this color transparent.
\end{description}

\subsubsection{Mosaic()}
form a single coherent picture.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Mosiac()
\end{quote}

The Mosaic() method takes a set of images and inlays them to form
a single coherent pictiure.  Mosaic() returns a single image with each
image in the sequence inlayed in the image canvas at an offset as defined
in the image.

{\small
\begin{verbatim}
    $mosaic = $image->Mosaic();
\end{verbatim}
}

\subsubsection{MotionBlur()}
simulate motion blur.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$MotionBlur(geometry=$>$\var{geometry}, radius=$>$\var{float},
  sigma=$>$\var{float}, angle=$>$\var{float})
\end{quote}

MotionBlur() simulates motion blur.  We convolve the image with a Gaussian
operator of the given radius and standard deviation (sigma).  For reasonable
results, radius should be larger than sigma.  Use a radius of 0 and MotionBlur()
selects a suitable radius for you.  \texttt{Geometry} represents
radius x sigma as one parameter (e.g. 0x1).  \texttt{Angle} gives the angle
of the blurring motion.

\subsubsection{Morph()}
morph a set of images.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Morph(frames=$>$\var{integer})
\end{quote}

The Morph() method requires a minimum of two images.  The first image is
transformed into the second by a number of intervening images as specified by
\texttt{frames}.  The result is returned as a new image sequence, for example:

{\small
\begin{verbatim}
    $morph = $image->Morph(30);
\end{verbatim}
}

\subsubsection{Negate}
apply color inversion.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Negate(gray=$>$\var{boolean})
\end{quote}


Negate() negates the intensities of each pixel in the image.  If \texttt{gray}
is a value other than 0, only the grayscale pixels are inverted.

\subsubsection{New()}
create an image object.

\begin{quote}
\hspace*{-0.25in}
\$image = new Image::Magick; \\
\$image = Image::Magick->New()
\end{quote}

New() instantiates an image object.  As a convenience, you can set any image
attribute that Set() knows about.  See section \ref{Get or Set an Image
Attribute} for a list of known image attributes.  Here is an example:

{\small
\begin{verbatim}
    $image = Image::Magick->New(size=>'160x120');
    $image->Read('gray:protein');
\end{verbatim}
}

\subsubsection{Normalize()}
enhance image contrast.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Normalize()
\end{quote}

The Normalize() method enhances the contrast of a color image by
adjusting the pixels color to span the entire range of colors available.

\subsubsection{OilPaint()}
simulate an oil painting.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$OilPaint(radius=$>$\var{integer})
\end{quote}

OilPaint() applies a special effect filter that simulates an oil painting.
Each pixel is replaced by the most frequent color occurring in a
circular region defined by \texttt{radius}.

\subsubsection{Opaque()}
globally change a color.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Opaque(color=$>$\var{color-name}, fill=$>$\var{color-name},
  fuzz=$>$\var{float})
\end{quote}

Opaque() changes any pixel that matches \texttt{color} with the color
defined by \texttt{fill}.

By default \texttt{color} must match a particular pixel color exactly.
However, in many cases two colors may differ by a small amount.
\texttt{Fuzz} defines how much tolerance is acceptable to consider
two colors as the same.  For example, set fuzz to 10 and the color red
at intensities of 100 and 102 respectively are now interpreted as the
same color.

\subsubsection{OrderedDither()}
reduce the image to black and white.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$OrderedDither()
\end{quote}

The OrderedDither() method reduces the image to black and white.

\subsubsection{Ping()}
get information about an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Ping(filename=$>$\var{string}, file=$>$\var{file-handle},
  blob=$>$\var{blob})
\end{quote}

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:

{\small
\begin{verbatim}
    ($width, $height, $size, $format) = $image->Ping('logo.gif');
    ($width, $height, $size, $format) = $image->Ping(file=>\*IMAGE);
    ($width, $height, $size, $format) = $image->Ping(blob=>\$blob);
\end{verbatim}
}

\subsubsection{Profile()}
add, remove, or apply an image profile.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Profile(name=$>$\var{variable}, profile=$>$\var{blob})
\end{quote}

The Profile() method adds, removes, or applies an image profile.
The two most common profiles are ICC, a color management option,
IPTC, a newswire profile, and APP1, which is a JPEG marker that
can contain EXIF data.  \texttt{Profile} is a Perl variable representing
the binary profile information.  To remove all profiles from the image, use an
asterick as the profile name:

{\small
\begin{verbatim}
    $image->Profile('*');
\end{verbatim}
}

\subsubsection{Quantize()}
set the maximum number of colors in an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Quantize(colors=$>$\var{integer}, colorspace=$>$\var{string},
  dither=$>$\var{boolean}, global\_colormap=$>$\var{boolean}
  measure\_error=$>$\var{boolean}, tree\_depth=$>$\var{integer})
\end{quote}

The Quantize() method sets the maximum number of colors in an image.  If the
number of colors in the image exceeds \texttt{colors}, a color reduction
algorithm repeatly merges pixels of similar color until the total number
of unique colors is less or equal to the maximum.  Here is a description of
the color reduction parameters:

\begin{description}
\item[colors] Set the maximum number of colors in the image.
\item[colorspace] By default, color merging is performed in the RGB
colorspace.  However, RGB is not perceptually uniform like YCbCr for
example.  You may get better results by trying one of the following
colorspaces:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> CMYK \> Gray \> OHTA \\
\> RGB \> sRGB \> Transparent \\
\> XYZ \> YCbCr \> YCC \\
\> YIQ \> YPbPr \> YUV
\end{tabbing}
\item[dither] Images which suffer from severe contouring when reducing colors
can be improved with this option.
\item[global\_colormap] A value other than 0 creates one global colormap
for a sequence of images.
\item[measure\_error] A value other than 0 returns a measure of how closely
the color reduced image matches the original.  The mean error, normalized mean
error, and normalized maximum mean error per pixel are computed.  Obtain these
values with the Get() method.
\item[tree\_depth] By default, the color reduction uses a Oct-tree algorithm
whose depth ranges from 1-8 which is optimally determined to allow the
best representation of the image with the fastest computational speed and
least amount of memory consumption.  You can override the default with this
parameter.
\end{description}

\subsubsection{QueryColor()}
return numerical values corresponding to a color name.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$QueryColor( ... )
\end{quote}

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.

{\small
\begin{verbatim}
    @colors = $image->QueryColor();
    ($red, $green, $blue, $opacity) = $image->QueryColor('red');
    ($red, $green, $blue, $opacity) = $image->QueryColor('#716bae');
\end{verbatim}
}

\subsubsection{QueryColorname()}
return a color name corresponding to the numerical values.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$QueryColorname( ... )
\end{quote}

QueryColorname() accepts one or more numerical values and returns their
respective color name:

{\small
\begin{verbatim}
    $color = $image->QueryColorname('rgba(65535,0,0,0)');
\end{verbatim}
}

\subsubsection{QueryFont()}
get font attributes.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$QueryFont( ... )
\end{quote}

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.

{\small
\begin{verbatim}
    @fonts = $image->QueryFont();
    $weight = ($image->QueryFont('Helvetica'))[5];
\end{verbatim}
}
\subsubsection{QueryFontMetrics()}
query font metrics.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$QueryFontMetrics(font=>\var{string}, ... )
\end{quote}

QueryFontMetrics() accepts a font name and any parameter acceptable to
Annotate().  The method returns these attributes associated with the given
font:

\begin{itemize}
\item character width
\item character height
\item ascender
\item descender
\item text width
\item text height
\item maximum horizontal advance
\end{itemize}

For example,

{\small
\begin{verbatim}
    @metrics = $image->QueryFontMetrics(font=>'arial.ttf', pointsize=>24);
\end{verbatim}
}

\subsubsection{QueryFormat()}
get image format attributes.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$QueryFormat( ... )
\end{quote}

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, format, decoder, encoder, description, and module.


{\small
\begin{verbatim}
    @formats = $image->QueryFormat();
    ($adjoin, $blob_support, $raw, $decoder, $encoder, $description, $module) = $image->QueryFormat('gif');
\end{verbatim}
}

\subsubsection{Raise()}
lighten or darken edges to create a 3-D effect.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Raise(geometry=$>$\var{geometry}, width=$>$\var{integer},
  height=$>$\var{integer},  raise=$>$\var{boolean})
\end{quote}

Raise() creates a simulated three-dimensional button-like effect by
lightening and darkening the edges of the image.  \texttt{Width} and
\texttt{height} define the width of the vertical and horizontal edge
of the effect.  Use \texttt{Geometry} as a shortcut for
\texttt{width} and \texttt{height} (e.g. 10x10).

A value other than 0 for \texttt{raise} simulates a raised button-like
effect otherwise a sunken button-like effect is applied to the image.

\subsubsection{Read()}
read one or more image files.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Read(filename=$>$\var{float}, file=$>$\var{file-handle})
\end{quote}

\begin{description}
\item[filename] the name of an image file.
\item[file-handle] read the image from an open filehandle.
\end{description}

The Read() method reads an image or image sequence from one or more
filenames or the filehandle you specify.  You can specify more than one
filename but only one filehandle:

{\small
\begin{verbatim}
    $image->Read(filename=>'logo.gif');      # read a single GIF into
                                             # $image object.
    $image->Read('logo.jpg', 'button.gif');  # read two images.
    $image->Read('*.png');                   # read all the PNG files in the
                                             # current directory.
    $image->Read(file=>\*IMAGE);             # read from open Perl filehandle.
\end{verbatim}
}

Read() returns the number of images that were successfully read.

\subsubsection{ReduceNoise()}
smooth an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$ReduceNoise(radius=$>$\var{float})
\end{quote}

The ReduceNoise() method smooths the contours of an image while still
preserving edge information.  The algorithm works by replacing each
pixel with its neighbor closest in value.  A neighbor is defined by
\texttt{radius}.  Use a radius of 0 and ReduceNoise() selects a suitable
radius for you.

\subsubsection{Resize()}
scale an image with a filter.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Resize(geometry=$>$\var{geometry}, width=$>$\var{integer},
  height=$>$\var{integer}, filter=$>$\var{string}, blur=$>$\var{float})
\end{quote}

Resize() scales an image to the desired dimensions with one of these filters:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> Bessel \> Blackman \> Box \\
\> Catrom \> Cubic \> Gaussian \\
\> Hanning \> Hermite \> Lanczos \\
\> Mitchell \> Point \> Quadratic \\
\> Sinc \>  Triangle \>
\end{tabbing}

The default is Lanczos.

Use \texttt{width} and \texttt{height} to specify the image size, or use
\texttt{geometry} as a shortcut (e.g. 640x480).

Set \texttt{Blur} to a value greater than 1 to blur the image as it is scaled.
A value less than 1 sharpens as the image is scaled.

\subsubsection{Roll()}
offset and roll over an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Roll(geometry=$>$\var{geometry},  x=$>$\var{integer},
  y=$>$\var{integer})
\end{quote}

Roll() offsets an image as defined by \texttt{x} and \texttt{y}.
\texttt{Geometry} represents + x + y as one parameter (e.g. +10+20).

\subsubsection{Rotate()}
rotate an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Rotate(degrees=$>$\var{float},  color=$>$\var{color-name})
\end{quote}

Rotate() rotates an image around the x axis by the number of degrees by
\texttt{degrees}.  Any empty spaces are filled with \texttt{color}.

\subsubsection{Sample()}
sample an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Sample(geometry=$>$\var{geometry}, width=$>$\var{integer},
  height=$>$\var{integer})
\end{quote}

Sample() scales an image to the desired dimensions with pixel sampling.
Unlike other scaling methods, this method does not introduce any additional
color into the scaled image.

Use \texttt{width} and \texttt{height} to specify the image size, or use
\texttt{geometry} as a shortcut (e.g. 640x480).

\subsubsection{Scale()}
scale an image to given dimensions.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Scale(geometry=$>$\var{geometry}, width=$>$\var{integer},
  height=$>$\var{integer})
\end{quote}

Scale() changes the size of an image to the given dimensions.
Use \texttt{width} and \texttt{height} to specify the image size, or use
\texttt{geometry} as a shortcut (e.g. 640x480).

\subsubsection{Segment()}
segment an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Segment(geometry=$>$\var{geometry},
  cluster\_threshold=$>$\var{float}, smoothing\_threshold=$>$\var{float},
  colorspace=$>$\var{string}, verbose=$>$\var{boolean})
\end{quote}

Segment() segments an image by  by analyzing the histograms of the color
components and identifying units that are homogeneous.  The default value
for \texttt{cluster\_threshold} is 1.0 and \texttt{smoothing\_threshold} is
1.5. This can be represented with a shortcut geometry of 1.0x1.5.

\subsubsection{Set()}
set an image attribute.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Set(\var{attribute}, ...)
\end{quote}

Set() accepts one or more image attributes listed in section
\ref{Image::Magick Attributes} and sets their value.

\subsubsection{Shade()}
shade the image with light source.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Shade(geometry=$>$\var{geometry},  azimuth=$>$\var{float},
  elevation=$>$\var{float}, color=$>$\var{boolean})
\end{quote}

Shade() shines a distant light on an image to create a three-dimensional
effect. You control the positioning of the light with \var{azimuth} and
\var{elevation}; azimuth is measured in degrees off the x axis and elevation
is measured in pixels above the Z axis.  The geometry parameter is a shortcut
for azimuth x elevation (e.g. 30x30).

\subsubsection{Sharpen()}
sharpen an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Sharpen(geometry=$>$\var{geometry}, radius=$>$\var{float},
  sigma=$>$\var{float})
\end{quote}

Sharpen() sharpens an image.  We convolve the image with a Gaussian operator
of the given radius and standard deviation (sigma).  For reasonable results,
radius should be larger than sigma.  Use a radius of 0 and Sharpen()
selects a suitable radius for you.  \texttt{Geometry} represents
radius x sigma as one parameter (e.g. 0x1).

\subsubsection{Shave()}
shave pixels from the image edges.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Border(geometry=$>$\var{geometry}, width=$>$\var{integer},
  height=$>$\var{integer})
\end{quote}

This method shaves pixels from the image edges.
\texttt{Geometry} represents {\it width x height} as one parameter (e.g. 10x5).

\subsubsection{Shear()}
shear an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Shear(geometry=$>$\var{geometry}, x=$>$\var{float},
  y=$>$\var{float}, color=$>$\var{color-name})
\end{quote}

Shear() transforms an image by shearing it along the x or y axis.
The \texttt{x} and \texttt{y} parameters specify the degree of shear
and ranges from -179.9 to 179.9.  \texttt{Geometry} represents
x x y as one parameter (e.g. 30x60).  Any empty spaces created when shearing
are filled with \texttt{color}.

\subsubsection{Signature()}
generate an SHA-256 message digest.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Signature()
\end{quote}

Signature() generates an SHA-256 message digest across all the image pixels.
The signature can later be used to verify the color integrity of the image.
Two images with the same signature are identical.

\subsubsection{Solarize()}
apply solorization special effect.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Solarize(threshold=$>$\var{float})
\end{quote}

Solarize() applies a special effect to the image, similar to the effect
achieved in a photo darkroom by selectively exposing areas of photo
sensitive paper to light.  \texttt{Threshold} ranges from 0 to MaxRGB
and is a measure of the extent of the solarization.

\subsubsection{Spread()}
randomly displace pixels.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Spread(amount=$>$\var{integer})
\end{quote}

Spead() is a special effects method that randomly displaces each pixel in a
block defined by the \texttt{amount} parameter.

\subsubsection{Stereo()}
create a stereo special effect.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Stereo(image=$>$\var{image-handle})
\end{quote}

Stereo() combines two images and produces a single image that is the
composite of a left and right image of a stereo pair.  Special red-green
stereo glasses are required to view this effect.

\subsubsection{Stegano()}
hide a digital watermark.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Stegano(image=$>$\var{image-handle}, offset=$>$\var{integer})
\end{quote}

Use Stegano() to hide a digital watermark within the image.  Recover the
hidden watermark later to prove that the authenticity of an image.
texttt{Offset} defines the start position within the image to hide the
watermark.

\subsubsection{Swirl()}
swirl pixels about image center.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Swirl(degrees=$>$\var{float})
\end{quote}

The Swirl() method swirls the pixels about the center of the image, where
\texttt{degrees} indicates the sweep of the arc through which each pixel
is moved.  You get a more dramatic effect as the degrees move from
1 to 360.

\subsubsection{Texture()}
tile a texture on image background.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Texture(texture=$>$\var{image-handle})
\end{quote}

Texture() repeatedly tiles the texture image across and down the image
canvas.

\subsubsection{Threshold()}
divide pixels based on intensity values.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Threshold(threshold=$>$\var{integer})
\end{quote}

Threshold() changes the value of individual pixels based on the intensity
of each pixel compared to \texttt{threshold}.  The result is a high-contrast,
two color image.

\subsubsection{Transform()}
resize or crop an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Transform(geometry=$>$\var{string}, crop=$>$\var{string})
\end{quote}

Transform() behaves like Resize() or Crop() but rather than acting on
the image, it returns a new image handle:

{\small
\begin{verbatim}
    $slices = $image->Transform(crop=>'100x100')
\end{verbatim}
}

\subsubsection{Transparent()}
make color transparent.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Transparent(color=$>$\var{color-name}, opacity=$>$\var{integer}
  fuzz=$>$\var{float})
\end{quote}

Transparent() changes the opacity value associated with any pixel that
matches \texttt{color} to the value defined by \texttt{opacity}.

By default \texttt{color} must match a particular pixel color exactly.
However, in many cases two colors may differ by a small amount.
\texttt{Fuzz} defines how much tolerance is acceptable to consider
two colors as the same.  For example, set fuzz to 10 and the color red
at intensities of 100 and 102 respectively are now interpreted as the
same color.

\subsubsection{Trim()}
remove background color from edges of image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Trim(fuzz=$>$\var{float})
\end{quote}

Trim() crops a rectangular box around the image to remove edges that are the
background color.

By default the edge pixels must match in color exactly to be trimmed.
However, in many cases two colors may differ by a small amount.
\texttt{Fuzz} defines how much tolerance is acceptable to consider
two colors as the same.  For example, set fuzz to 10 and the color red
at intensities of 100 and 102 respectively are now interpreted as the
same color.

\subsubsection{UnsharpMask()}
sharpen an image.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$UnsharpMask(geometry=$>$\var{geometry}, radius=$>$\var{float},
  sigma=$>$\var{float}, amount=$>$\var{float},  threshold=$>$\var{float})
\end{quote}

UnsharpMask() sharpens an image.  We convolve the image with a Gaussian operator
of the given radius and standard deviation (sigma).  For reasonable results,
radius should be larger than sigma.  Use a radius of 0 and UnsharpMask()
selects a suitable radius for you.  \texttt{Geometry} represents
radius x sigma as one parameter (e.g. 0x1).

\subsubsection{Wave()}
special effects filter.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Wave(geometry=$>$\var{string},  amplitude=$>$\var{float},
  wavelength=$>$\var{float})
\end{quote}

The Wave() filter creates a "ripple" effect in the image by shifting the
pixels vertically along a sine wave whose amplitude and wavelength is
specified by the given parameters.  \texttt{Geometry} represents
amplitude x wavelength as one parameter (e.g. 30x30).

\subsubsection{Write()}
write one or more image files.

\begin{quote}
\hspace*{-0.25in}
\$image-$>$Write(filename=$>$\var{float}, file=$>$\var{file-handle})
\end{quote}

Write() allows you to write a single or image or a sequence to a file or
filehandle.  You can specify more than one filename but only one filehandle:

{\small
\begin{verbatim}
    $image->Write(filename=>'logo.gif');     # write a single GIF image.
    $image->Write('logo.jpg', 'button.gif'); # write two images.
    $image->Write('gif:-');                  # write to STDOUT.
    $image->[0]->Write('logo.png');          # write only first image
                                             # in a sequence.
    $image->Write(file=>\*IMAGE);            # write to a open Perl filehandle.
\end{verbatim}
}

Write() returns the number of images that were written.

\section{Image::Magick Errors}

Most Image::Magick methods return an undefined value if the operation
was successful.  When an error occurs, a message is returned with an
embedded numeric status code.  Look up the status code in table
\ref{Error and Warning Codes} to determine the reason the operation failed.
The mnemonics are aliases for the the corresponding numeric codes.

\begin{longtable}{p{1cm} | p{4cm} | p{8cm}}
\caption{Error and Warning Codes} \\[0.5in]
\multicolumn{3}{c}{Error and Warning Codes}\\[0.5in]
  \textbf{Code} & \textbf{Mnemonic} & \textbf{Description} \\ \hline
\endfirsthead
\multicolumn{3}{c}{Error and Warning Codes (continued)}\\[0.5in]
  \textbf{Code} & \textbf{Mnemonic} & \textbf{Description} \\ \hline
\endhead
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 occured. \\
310 & OptionWarning & An option parameter was malformed. \\
315 & DelegateWarning & An ImageMagick {\em delegate} returned a warning. \\
320 & MissingDelegateWarning & The image type can not be read or written because the required {\em 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. \\
385 & XServerWarning & An X resource is unavailable. \\
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 occured. \\
410 & OptionError & An option parameter was malformed. \\
415 & DelegateError & An ImageMagick {\em delegate} returned a warning. \\
420 & MissingDelegateError & The image type can not be read or written because the required {\em 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. \\
485 & XServerError & An X resource is unavailable. \\
490 & RegistryError & There was a problem getting or setting the registry. \\
495 & ConfigureError & There was a problem getting a configuration file. \\
\end{longtable}