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

\section{Methods to Constitute an Image}

\subsubsection{ConstituteImage()}
create an image from pixel data.

\begin{quote}
\hspace*{-0.25in}
Image *ConstituteImage (const unsigned long width,  const unsigned
long height,  const char *map,  const StorageType type,  const void *pixels, 
ExceptionInfo *exception) 
\end{quote}

ConstituteImage() returns an image from the pixel data you supply.
The pixel data must be in scanline order top-to-bottom.
The data can be of type \var{char}, \var{short int}, \var{int}, \var{long},
\var{float}, or \var{double}.  \var{Float} and \var{double} require the
pixels to be normalized [0..1] otherwise [0..MaxRGB].   For example, to
create a 640 x 480 image from unsigned red-green-blue character data, use

{\small
\begin{verbatim}
    image = ConstituteImage(640, 480, "RGB", CharPixel, pixels,
            exception);
\end{verbatim}
}

A description of each parameter follows:

\begin{description}
\item[width] Width in pixels of the image.
\item[height] Height in pixels of the image.
\item[map] This string reflects the expected ordering of the pixel array.  It
can be any combination or order of R = red, G = green, B = blue, A = alpha,
C = cyan, Y = yellow, M = magenta, K = black, or I = intensity (for grayscale).
\item[type] Define the data type of the pixels.  Float and double types are
expected to be normalized [0..1] otherwise [0..MaxRGB].  Choose from these
types:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> CharPixel \> ShortPixel \> IntegerPixel \\
\> LongPixel \> FloatPixel \> DoublePixel 
\end{tabbing}
\item[pixels] This array of values contain the pixel components as defined by
\texttt{map} and \texttt{type}.  The expected length of the array varies
depending on the values of \texttt{width}, \texttt{height}, \texttt{map},
and \texttt{type}.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{DispatchImage()}
extract pixel data from an image.

\begin{quote}
\hspace*{-0.25in}
unsigned int DispatchImage(Image *image, const long x, const long y, 
const unsigned long columns, const unsigned long rows, const char *map, 
const StorageType type, void *pixels, ExceptionInfo *exception) 
\end{quote}

DispatchImage() extracts pixel data from an image and returns it to
you.  The method returns False on success otherwise
True if an error is encountered.  The data is returned as \var{char},
\var{short int}, \var{int},  \var{long}, \var{float}, or \var{double} in the
order specified by \texttt{map}.

Suppose we want want to extract the first scanline of a 640x480 image
as character data in red-green-blue order:

{\small
\begin{verbatim}
    status = DispatchImage(image, 0, 0, 640, 1, "RGB", 0, pixels,
             exception);
\end{verbatim}
}

A description of each parameter follows:

\begin{description}

\item[image] The image.
\item[x, y, columns, rows] These values define the perimeter of a region of
pixels you want to extract.
\item[map] This string reflects the expected ordering of the pixel array.  It
can be any combination or order of R = red, G = green, B = blue, A = alpha,
C = cyan, Y = yellow, M = magenta, K = black, or I = intensity (for grayscale).
\item[type] Define the data type of the pixels.  Float and double types are
normalized to [0..1] otherwise [0..MaxRGB].  Choose from these types:

\begin{tabbing}
0000\=1111111111111111\=2222222222222222\=3333333333333333\kill
\> CharPixel \> ShortPixel \> IntegerPixel \\
\> LongPixel \> FloatPixel \> DoublePixel
\end{tabbing}
\item[pixels] This array of values contain the pixel components as defined by
\texttt{map} and \texttt{type}.  You must preallocate this array where the
expected length varies depending on the values of \texttt{width},
\texttt{height}, \texttt{map}, and \texttt{type}.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *PingImage(const ImageInfo *image\_info, ExceptionInfo *exception)
\end{quote}

PingImage() returns all the attributes of an image or image sequence
except for the pixels.  It is much faster and consumes far less
memory than ReadImage().  On failure, a NULL image is returned and
\texttt{exception} describes the reason for the failure.

A description of each parameter follows:

\begin{description}
\item[image\_info] Ping the image defined by the \texttt{file} or
\texttt{filename} members of this structure.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *ReadImage(const ImageInfo *image\_info, ExceptionInfo *exception) 
\end{quote}

ReadImage() reads an image or image sequence from a file or file handle.
On failure, a NULL image is returned and \texttt{exception} describes
the reason for the failure.

A description of each parameter follows:

\begin{description}
\item[image\_info] Read the image defined by the \texttt{file} or
\texttt{filename} members of this structure.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int WriteImage(const ImageInfo *image\_info, Image *image) 
\end{quote}

Use Write() to write an image or an image sequence to a file or
filehandle.  
If writing to a file on disk, the name is defined by the
filename member of the image structure.
Write() returns 0 is there is a memory shortage or if the
image cannot be written.  Check the \texttt{exception} member of
\texttt{image} to determine the cause for any failure.

A description of each parameter follows:

\begin{description}
\item[image\_info] The image info.
\item[image] The image.
\end{description}

\section{ImageMagick Image Methods}

\subsubsection{AllocateImage()}
allocate an image.

\begin{quote}
\hspace*{-0.25in}
Image *AllocateImage(const ImageInfo *image\_info)
\end{quote}

AllocateImage() returns a pointer to an image structure initialized to
default values. 

A description of each parameter follows:

\begin{description}
\item[image\_info] Many of the image default values are set from this structure.
For example, filename, compression, depth, background color, and others.
\end{description}

\subsubsection{AllocateImageColormap()}
allocate an image colormap.

\begin{quote}
\hspace*{-0.25in}
unsigned int AllocateImageColormap(Image *image, const unsigned long colors) 
\end{quote}

AllocateImageColormap() allocates an image colormap and initializes
it to a linear gray colorspace.  If the image already has a colormap,
it is replaced.  AllocateImageColormap() returns True if successful,
otherwise False if there is not enough memory.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[colors] The number of colors in the image colormap.
\end{description}

\subsubsection{AllocateNextImage()}
allocate the next image in a sequence.

\begin{quote}
\hspace*{-0.25in}
void AllocateNextImage(const ImageInfo *image\_info, Image *image)
\end{quote}

Use AllocateNextImage() to initialize the next image in a sequence to
default values.  The \texttt{next} member of \texttt{image} points to
the newly allocated image.  If there is a memory shortage, \texttt{next}
is assigned NULL.

A description of each parameter follows:

\begin{description}

\item[image\_info] Many of the image default values are set from this
structure.  For example, filename, compression, depth, background color,
and others.
\item[image] The image.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int AnimateImages(const ImageInfo *image\_info, Image *image) 
\end{quote}

AnimateImages() repeatedly displays an image sequence to any X window
screen.  It returns a value other than 0 if successful.  Check the
\texttt{exception} member of \texttt{image} to determine the cause for
any failure.

A description of each parameter follows:

\begin{description}

\item[image\_info] The image info.
\item[image] The image.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *AppendImages (Image *image, const unsigned int stack,
  ExceptionInfo *exception) 
\end{quote}

The Append() method takes a set of images and appends them to each other.
Each image in the set must have the same width or height (or both).
Append() returns a single image where each image in the original set
is side-by-side if all the heights the same or stacked on top of each
other if all widths are the same.  On failure, a NULL image is returned
and \texttt{exception} describes the reason for the failure.

A description of each parameter follows:

\begin{description}
\item[image] The image sequence.
\item[stack] An unsigned value other than stacks rectangular image top-to-bottom
otherwise left-to-right.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *AverageImages (const Image *image,  ExceptionInfo *exception)
\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 height.  Average()
returns a single image with each corresponding pixel component of
each image averaged.   On failure, a NULL image is returned and
\texttt{exception} describes the reason for the failure.

A description of each parameter follows:

\begin{description}

\item[image] The image sequence.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int ChannelImage (Image *image,  const ChannelType channel)
\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:

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[channel] Identify which channel to extract:

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

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

\begin{quote}
\hspace*{-0.25in}
Image *CloneImage(Image *image, const unsigned long columns, const
unsigned long rows, const unsigned int orphan, ExceptionInfo *exception)
\end{quote}

CloneImage() copies an image and returns the copy as a new image object.
If the specified columns and rows is 0, an exact copy of the image is
returned, otherwise the pixel data is undefined and must be initialized
with the SetImagePixels() and SyncImagePixels() methods.  On failure,
a NULL image is returned and \texttt{exception} describes the reason
for the failure.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[columns] The number of columns in the cloned image.
\item[rows] The number of rows in the cloned image.
\item[orphan] With a value other than 0, the cloned image is an orphan.  An
orphan is a stand-alone image that is not assocated with an image list.  In
effect, the \texttt{next} and \texttt{previous} members of the cloned image
is set to NULL.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{CloneImageInfo()}
clone an image info structure.

\begin{quote}
\hspace*{-0.25in}
ImageInfo *CloneImageInfo(const ImageInfo *image\_info)
\end{quote}

CloneImageInfo() makes a copy of the given image info structure.  If
NULL is specified, a new image info structure is created initialized to
default values.

A description of each parameter follows:

\begin{description}
\item[image\_info] The image info.
\end{description}

\subsubsection{CompositeImage()}
composite one image to another.

\begin{quote}
\hspace*{-0.25in}
unsigned int CompositeImage(Image *image, const CompositeOperator compose,
   const Image *composite\_image, const long x\_offset, const long y\_offset) 
\end{quote}

CompositeImage() returns the second image composited onto the
first at the specified offsets.

A description of each parameter follows:

\begin{description}

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

\begin{tabbing}
0000\=111111111111111111\=2222222222222222222222\=333333333333333333333\kill
\> OverCompositeOP \> DifferenceCompositeOP \> XorCompositeOP \\
\> AtopCompositeOP \> DisplaceCompositeOP \> PlusCompositeOP \\
\> MinusCompositeOP \> SubtractCompositeOP \> AddCompositeOP \\
\> InCompositeOP \> BumpmapCompositeOP \> CopyCompositeOP \\
\> OutCompositeOP
\end{tabbing}
\item[composite\_image] The composite image.
\item[x\_offset] The column offset of the composited image.  If the offset
is negative, it is measured between the right edges of the images.
\item[y\_offset] The row offset of the composited image.  If it is
negative, it is measured between the bottom edges of the images.
\end{description}

\subsubsection{CycleColormapImage()}
displace a colormap.

\begin{quote}
\hspace*{-0.25in}
CycleColormapImage(Image *image, const int amount)
\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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[amount] Offset the colormap this much.
\end{description}

\subsubsection{DescribeImage()}
describe an image.

\begin{quote}
\hspace*{-0.25in}
void DescribeImage (Image *image, FILE *file, const unsigned int verbose)
\end{quote}

DescribeImage() describes an image by printing its attributes to the file.
Attributes include the image width, height, size, and others.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[file] The file, typically stdout.
\item[verbose] A value other than zero prints additional detailed information
about the image.
\end{description}

\subsubsection{DestroyImage()}
destroy an image.

\begin{quote}
\hspace*{-0.25in}
void DestroyImage(Image *image)
\end{quote}

DestroyImage() dereferences an image, deallocating memory associated
with the image if the reference count becomes zero.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

\subsubsection{DestroyImageInfo()}
destroy image info.

\begin{quote}
\hspace*{-0.25in}
void DestroyImageInfo(ImageInfo *image\_info)
\end{quote}

DestroyImageInfo() deallocates memory associated with \texttt{image\_Info}.

A description of each parameter follows:

\begin{description}
\item[image\_info] The image info.
\end{description}


\subsubsection{DisplayImages()}
display an image sequence.

\begin{quote}
\hspace*{-0.25in}
unsigned int DisplayImages(const ImageInfo *image\_info, Image *image)
\end{quote}

DisplayImages() displays an image sequence to any X window screen.  It
returns a value other than 0 if successful.  Check the \texttt{exception}
member of \texttt{image} to determine the reason for any failure.

A description of each parameter follows:

\begin{description}
\item[image\_info] The image info.
\item[image] The image.
\end{description}

\subsubsection{GetImageDepth()}
get image depth.

\begin{quote}
\hspace*{-0.25in}
unsigned int GetImageDepth(Image *image)
\end{quote}

GetImageDepth() returns the depth of the image, either 8 or 16 bits.  By
default, pixel components are stored as 16-bit two byte unsigned short
integers that range in value from 0 to 65535.  However, if all the pixels
have lower-order bytes that are identical to their higher-order bytes, the
image depth is 8-bit.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

\subsubsection{GetImageInfo()}
get image info.

\begin{quote}
\hspace*{-0.25in}
void GetImageInfo(ImageInfo *image\_info)
\end{quote}

GetImageInfo() initializes \texttt{image\_info}  to default values.

A description of each parameter follows:

\begin{description}

\item[image\_info] The image info.
\end{description}

\subsubsection{GetImageType()}
get image type.

\begin{quote}
\hspace*{-0.25in}
ImageType GetImageType(const Image *image,ExceptionInfo *exception)
\end{quote}

GetImageType() returns the type of image:

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

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{IsImagesEqual()}
measure the pixel differences between two images.

\begin{quote}
\hspace*{-0.25in}
unsigned int IsImagesEqual(Image *image, Image *reference)
\end{quote}

IsImagesEqual() measures the difference between colors at each pixel
location of two images.  A value other than 0 means the colors match
exactly.  Otherwise an error measure is computed by summing over all
pixels in an image the distance squared in RGB space between each image
pixel and its corresponding pixel in the reference image.  The error
measure is assigned to these image members:

\begin{description}
\item[mean\_error\_per\_pixel] The mean error for any single pixel in
the image.
\item[normalized\_mean\_error] The normalized mean quantization error for
any single pixel in the image.  This distance measure is normalized to
a range between 0 and 1.  It is independent of the range of red, green,
and blue values in the image.
\item[normalized\_maximum\_error] The normalized maximum quantization
error for any single pixel in the image.  This distance measure is
normalized to a range between 0 and 1.  It is independent of the range
of red, green,  and blue values in your image.
\end{description}

Accessed as
\code{image->normalized\_mean\_error},
a small normalized mean square error,
suggests the images are very
similiar in spatial layout and color.

A description of each parameter follows:
\begin{description}

\item[image] The image.
\item[reference] The reference image.
\end{description}

\subsubsection{IsTaintImage()}
tell if an image has been altered.

\begin{quote}
\hspace*{-0.25in}
 unsigned int IsTaintImage(const Image *image)
\end{quote}

IsTaintImage() returns a value other than 0 if any pixel in the image
has been altered since it was first constituted.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

\subsubsection{ProfileImage()}
add or remove a profile.

\begin{quote}
\hspace*{-0.25in}
unsigned int ProfileImage(Image *image, const char *profile\_name, 
  const char *filename)
\end{quote}

ProfileImage() adds or removes a ICM, IPTC, or generic profile from an
image.  If the profile name is defined it is deleted from the image.
If a filename is given, one or more profiles are read and added to the
image.  ProfileImage() returns a value other than 0 if the profile is
successfully added or removed from the image.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[profile\_name] The type of profile to add or remove.
\item[filename] The filename of the ICM, IPTC, or generic profile.
\end{description}

\subsubsection{SetImage()}
set image pixels to the background color.

\begin{quote}
\hspace*{-0.25in}
void SetImage(Image *image, const Quantum opacity)
\end{quote}

SetImage() sets the red, green, and blue components of each pixel to
the image background color and the opacity component to the specified
level of transparency.  The background color is defined by the
\texttt{background\_color} member of the image.

A description of each parameter follows:
\begin{description}

\item[image] The image.
\item[opacity] Set each pixel to this level of transparency.
\end{description}

\subsubsection{SetImageClipMask()}

\begin{quote}
\hspace*{-0.25in}
unsigned int SetImageClipMask(Image *image,Image *clip\_mask)
\end{quote}

SetImageClipMask() associates a clip mask with the image.  The clip mask
must be the same dimensions as the image.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[clip\_mask] The clip mask.
\end{description}

\subsubsection{SetImageDepth()}

\begin{quote}
\hspace*{-0.25in}
unsigned int SetImageDepth(Image *image,const unsigned long depth)
\end{quote}

SetImageDepth() sets the depth of the image, either 8 or 16.  Some image
formats support both 8 and 16-bits per color component (e.g. PNG).  Use
SetImageDepth() to specify your preference.  A value other than 0 is
returned if the depth is set.  Check the \texttt{exception} member of
\texttt{image} to determine the cause for any failure.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[depth] The image depth.
\end{description}

\subsubsection{SetImageOpacity()}
set image pixels transparency level.

\begin{quote}
\hspace*{-0.25in}
void SetImageOpacity(Image *image, const unsigned long opacity)
\end{quote}

SetImageOpacity() attenuates the opacity channel of an image.  If the
image pixels are opaque, they are set to the specified opacity level.
Otherwise, the pixel opacity values are blended with the supplied
transparency value.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[opacity] The level of transparency: 0 is fully opaque and MaxRGB is
fully transparent.
\end{description}

\subsubsection{SetImageType()}
set image type.

\begin{quote}
\hspace*{-0.25in}
void SetImageType(Image *image, const ImageType image\_type)
\end{quote}

SetImageType() sets the type of image.  Choose from these types:

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

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[image\_type] Image type.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
void TextureImage(Image *image, Image *texture)
\end{quote}

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

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[texture] This image is the texture to layer on the background.
\end{description}

\section{Working With Image Lists}

In the ImageMagick API, image lists and sequences are managed by using
the ``next'' and ``previous'' pointers in the Image structure.

Every image is a member of a doubly-linked image list,
as illustrated below:

{\small
\begin{verbatim}
          +-----+      +-----+      +-----+      +-----+
NULL<prev-|image|<prev-|image|<prev-|image|<prev-|image|
          |  0  |-next>|  1  |-next>|  2  |-next>|  3  |-next>NULL
          +-----+      +-----+      +-----+      +-----+

                            +-------+
              NULL<previous-|orphan |
                            |image  |-next>NULL
                            +-------+
\end{verbatim}
}

If the ``previous'' and ``next'' pointers are both are NULL,
the image is called an ``orphan''.  Each ``orphan'' is in effect a
single-image list.  Applications can maintain any number of image lists.
Each image belongs to only one image list.

An {\bf image sequence} is that part of an {\bf image list}
beginning with a specific image, plus the remainder of the {\bf image list}
pointed to by its {\bf next} pointer.  The image pointed to by the specific
image's ``previous'' pointer and other images in the list prior to the specific
image in the {\bf image list} do not form a part of the {\bf image sequence}.

Each image, image sequence, and image list is
referenced by pointing to an image structure of type {\tt Image *}.  In the
illustration above, a reference to the structure for Image 2 refers
to image 2 itself, to the image sequence consisting of images 2 and 3,
and to the image list consisting of all images 0 through 3.
In the C API, functions that operate on an image list contain the words
``ImageList'' as a part of the function name, and are described in this
section.  In general, functions that operate on an image sequence
contain the word ``Images'', although for legacy reasons some, such
as ReadImage(), WriteImage(), and PingImage(), do not.  In general,
functions that contain the word ``Image'' work on a single image.

\subsubsection{CloneImageList()}
duplicate an image list.

\begin{quote}
\hspace*{-0.25in}
Image *CloneImageList(const Image *images, ExceptionInfo *exception) 
\end{quote}

CloneImageList() returns a duplicate of the specified image list.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{DeleteImageFromList()}
delete an image from the list.

\begin{quote}
\hspace*{-0.25in}
unsigned int DeleteImageFromList(Image *images, const long offset)
\end{quote}

DeleteImageFromList() deletes an image at the specified position in the list..

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\item[offset] The position within the list.
\end{description}

\subsubsection{DestroyImageList()}
destroy an image list.

\begin{quote}
\hspace*{-0.25in}
DestroyImageList(Image *images)
\end{quote}

DestroyImageList() destroys an image list.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\end{description}

\subsubsection{GetImageFromList()}
get an image from an image list.

\begin{quote}
\hspace*{-0.25in}
Image *GetImageFromList(const Image *images, const long offset,
  ExceptionInfo *exception) 
\end{quote}

GetImageFromList() returns a clone of the image at the specified position
in the image list.  The clone is an ``orphan'', not linked to the list.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\item[offset] The position in the image list.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{GetImageIndexInList()}
the position in the list of the specified image.

\begin{quote}
\hspace*{-0.25in}
unsigned long *GetImageIndexInList(const Image *images)
\end{quote}

GetImageIndexInList() returns the position of the specified image in the
image list.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\end{description}


\subsubsection{GetImageListLength()}
the number of images in the image list.

\begin{quote}
\hspace*{-0.25in}
unsigned long GetImageListLength(const Image *images)
\end{quote}

GetImageListLength() returns the number of images in the image list.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\end{description}

\subsubsection{GetPreviousImageInList()}
get the previous image in an image list.

\begin{quote}
\hspace*{-0.25in}
Image *GetPreviousImageInList(Image *images)
\end{quote}

GetPreviousImageInList() returns a pointer to the previous image in an
image list after the image pointed to by *images.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\end{description}

\subsubsection{GetNextImageInList()}
get the next image in an image list.

\begin{quote}
\hspace*{-0.25in}
Image *GetNextImageInList(Image *images)
\end{quote}

GetNextImageInList() returns a pointer to the next image in an image list after
the image pointed to by *images.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\end{description}

\subsubsection{ImageListToArray()}
convert an image list to an array.

\begin{quote}
\hspace*{-0.25in}
Image **ImageListToArray(const Image *images, ExceptionInfo *exception) 
\end{quote}

ImageListToArray() is a convenience method that converts a linked list of
images to a sequential array.  For example,

{\small
\begin{verbatim}
    Image **group;
    group = ImageListToArray(images, exception);
    n = GetImageListLength(images);
    for (i=0; i < n; i++)
      puts(group[i]->filename);
    LiberateMemory((void **) &group);
\end{verbatim}
}

A description of each parameter follows:
\begin{description}
\item[image] The image list.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{NewImageList()}
create an empty image list.

\begin{quote}
\hspace*{-0.25in}
Image *NewImageList(void)
\end{quote}

NewImageList() creates an empty image list.

\subsubsection{RemoveLastImageFromList()}
remove the last image from an image list.

\begin{quote}
\hspace*{-0.25in}
Image *RemoveLastImageFromList(Image **images)
\end{quote}

RemoveLastImageFromList() removes the last image in the list and returns it.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\end{description}

\subsubsection{AppendImageToList()}
adds an image list to the end of an image list.

\begin{quote}
\hspace*{-0.25in}
unsigned int *AppendImageToList(Image **images, const Image *image,
  ExceptionInfo *exception) 
\end{quote}

 AppendImageToList() adds the image list to the end of the image list.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\item[image] The image list to be added.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{ReverseImageList()}
reverse an image list.

\begin{quote}
\hspace*{-0.25in}
Image *ReverseImageList(Image *images, ExceptionInfo *exception) 
\end{quote}

ReverseImageList() returns a new list with the order of images reversed
from those in the specified image list.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{InsertImageInList()}
adds an image to the end of an image list.

\begin{quote}
\hspace*{-0.25in}
unsigned int InsertImageInList(Image **images,const Image *image,
  const long offset,ExceptionInfo *exception)
\end{quote}

InsertImageInList() inserts an image into the list at the specified position.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\item[image] The image.
\item[offset] The position within the list.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{RemoveFirstImageFromList()}
remove and return the first image in the list.

\begin{quote}
\hspace*{-0.25in}
Image *RemoveFirstImageFromList(Image **images) 
\end{quote}

RemoveFirstImageFromList() removes an image from the beginning of the specified image list.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\end{description}

\subsubsection{SpliceImageIntoList()}
splice an image list.

\begin{quote}
\hspace*{-0.25in}
Image *SpliceImageIntoList(Image *images, const long offset,
  const unsigned long length, const Image *splices, ExceptionInfo *exception) 
\end{quote}

SpliceImageIntoList() removes the images designated by offset and length from
the list and replaces them with the specified list.  The "splices" list
is not necessarily of the same length.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\item[offset] The position in the image list.
\item[length] The length of the image list to remove.
\item[splices] Replace the removed image list with this list.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{PrependImageToList()}
add an image list to the beginning of the specified list.

\begin{quote}
\hspace*{-0.25in}
unsigned int *PrependImageToList(Image **images, const Image *image,
ExceptionInfo *exception) 
\end{quote}

PrependImageToList() adds an image list to the beginning of the specified
image list.

A description of each parameter follows:

\begin{description}
\item[images] The image list.
\item[image] The image list to be added.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\section{Methods to Count the Colors in an Image}

\subsubsection{CompressColormap()}
remove duplicate or unused colormap entries.

\begin{quote}
\hspace*{-0.25in}
void CompressColormap(Image *image)
\end{quote}

CompressColormap() compresses an image colormap by removing any duplicate or
unused color entries.

A description of each parameter follows:
\begin{description}
\item[image] The image.
\end{description}

\subsubsection{GetNumberColors()}
count the number of unique colors.

\begin{quote}
\hspace*{-0.25in}
unsigned long GetNumberColors(const Image *image, FILE *file,
  ExceptionInfo *exception)
\end{quote}

GetNumberColors() returns the number of unique colors in an image.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[file] Write a histogram of the color distribution to this file handle.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{IsGrayImage()}
is the image grayscale?

\begin{quote}
\hspace*{-0.25in}
unsigned int IsGrayImage(Image *image, ExceptionInfo *exception)
\end{quote}

IsGrayImage() returns True if all the pixels in the image have the same
red, green, and blue intensities.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{IsMonochromeImage()}
is the image monochrome?

\begin{quote}
\hspace*{-0.25in}
unsigned int IsMonochromeImage(Image *image, ExceptionInfo *exception)
\end{quote}

IsMonochromeImage() returns True if all the pixels in the image have
the same red, green, and blue intensities and the intensity is either
0 or MaxRGB.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{IsOpaqueImage()}
does the image have transparent pixels?

\begin{quote}
\hspace*{-0.25in}
unsigned int IsOpaqueImage(Image *image, ExceptionInfo *exception)
\end{quote}

IsOpaqueImage() returns True if none of the pixels in the image have an
opacity value other than opaque (0).

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{IsPaletteImage()}
does the image have less than 256 unique colors?

\begin{quote}
\hspace*{-0.25in}
unsigned int IsPaletteImage(Image *image, ExceptionInfo *exception)
\end{quote}

IsPaletteImage() returns True if the image is colormapped and has 256
unique colors or less.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{ListColorsInfo}
list color names.

\begin{quote}
\hspace*{-0.25in}
unsigned int ListColorInfo(FILE *file, ExceptionInfo *exception)
\end{quote}

ListColorInfo() lists color names to the specified file.  Color names
are a convenience.  Rather than defining a color by its red, green, and
blue intensities just use a color name such as \texttt{white}, \texttt{blue},
or \texttt{yellow}.

A description of each parameter follows:
\begin{description}
\item[file] List color names to this file handle.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int QueryColorDatabase(const char *name, PixelPacket *color,
ExceptionInfo *exception)
\end{quote}

QueryColorDatabase() returns the red, green, blue, and opacity intensities
for a given color name.

A description of each parameter follows:

\begin{description}
\item[name] The color name (e.g. white, blue, yellow).
\item[color] The red, green, blue, and opacity intensities values of
the named color in this structure.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int QueryColorname(const Image *image, const PixelPacket *color,
  ComplianceType compliance, char *name, ExceptionInfo *exception)
\end{quote}

QueryColorname() returns a named color for the given color intensity.  If
an exact match is not found, a hex value is return instead.  For example
an intensity of rgb:(0,0,0) returns \texttt{black} whereas rgb:(223,223,223)
returns \#dfdfdf.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[color] The color intensities.
\item[compliance] Adhere to this color standard: SVG or X11.
\item[name] Return the color name or hex value.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\section{Methods to Reduce the Number of Unique Colors in an Image}

\subsubsection{CloneQuantizeInfo()}

\begin{quote}
\hspace*{-0.25in}
QuantizeInfo *CloneQuantizeInfo(const QuantizeInfo *quantize\_info)
\end{quote}

Method CloneQuantizeInfo() makes a duplicate of the given quantize info
structure, or if quantize info is NULL,  a new one.
A description of each parameter follows:

\begin{description}
\item[quantize\_info] a structure of type info.
\end{description}

\subsubsection{DestroyQuantizeInfo()}

\begin{quote}
\hspace*{-0.25in}
DestroyQuantizeInfo(QuantizeInfo *quantize\_info)
\end{quote}

Method DestroyQuantizeInfo() deallocates memory associated with an
QuantizeInfo structure.

A description of each parameter follows:

\begin{description}
\item[quantize\_info] Specifies a pointer to an QuantizeInfo structure.
\end{description}

\subsubsection{GetQuantizeInfo()}

\begin{quote}
\hspace*{-0.25in}
GetQuantizeInfo(QuantizeInfo *quantize\_info)
\end{quote}

Method GetQuantizeInfo() initializes the QuantizeInfo structure.

A description of each parameter follows:

\begin{description}
\item[quantize\_info] Specifies a pointer to a QuantizeInfo structure.
\end{description}

\subsubsection{MapImage()}

\begin{quote}
\hspace*{-0.25in}
unsigned int MapImage(Image *image, Image *map\_image,
  const unsigned int dither)
\end{quote}

MapImage replaces the colors of an image with the closest color from a
reference image.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[map\_image] Specifies a pointer to a Image structure.  Reduce image to a
set of colors represented by this image.
\item[dither] Set this integer value to something other than zero to dither the
quantized image.
\end{description}

\subsubsection{MapImages()}

\begin{quote}
\hspace*{-0.25in}
unsigned int MapImages(Image *images, Image *map\_image, 
  const unsigned int dither)
\end{quote}

MapImages replaces the colors of a sequence of images with the closest
color from a reference image.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[map\_image] Specifies a pointer to a Image structure.  Reduce image to a
set of colors represented by this image.
\item[dither] Set this integer value to something other than zero to dither
the quantized image.
\end{description}

\subsubsection{GetImageQuantizeError()}

\begin{quote}
\hspace*{-0.25in}
unsigned int GetImageQuantizeError(Image *image)
\end{quote}

Method GetImageQuantizeError() measures the difference between the original
and quantized images.  This difference is the total quantization error.
The error is computed by summing over all pixels in an image the distance
squared in RGB space between each reference pixel value and its quantized
value.  These values are computed:

A description of each parameter follows:

\begin{description}

\item[mean\_error\_per\_pixel]

This value is the mean error for any single pixel in the image.

\item[normalized\_mean\_square\_error]

This value is the normalized mean quantization error for any single pixel
in the image.  This distance measure is normalized to a range between
0 and 1.  It is independent of the range of red, green,  and blue values
in the image.

\item[normalized\_maximum\_square\_error]

This value is the normalized maximum quantization error for any single
pixel in the image.  This distance measure is normalized to a range
between 0 and 1.  It is independent of the range of red, green,  and blue
values in your image.

\end{description}

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

\subsubsection{QuantizeImage()}

\begin{quote}
\hspace*{-0.25in}
unsigned int QuantizeImage(const QuantizeInfo *quantize\_info, Image *image)
\end{quote}

Method QuantizeImage() analyzes the colors within a reference image and
chooses a fixed number of colors to represent the image.  The goal of
the algorithm is to minimize the difference between the input and output
image while minimizing the processing time.

A description of each parameter follows:

\begin{description}
\item[quantize\_info] Specifies a pointer to an QuantizeInfo structure.
\item[image] Specifies a pointer to a Image structure.
\end{description}

\subsubsection{QuantizeImages()}

\begin{quote}
\hspace*{-0.25in}
unsigned int QuantizeImages(const QuantizeInfo *quantize\_info, Image *images)
\end{quote}

QuantizeImages analyzes the colors within a set of reference images and
chooses a fixed number of colors to represent the set.  The goal of the
algorithm is to minimize the difference between the input and output
images while minimizing the processing time.

A description of each parameter follows:

\begin{description}
\item[quantize\_info] Specifies a pointer to an QuantizeInfo structure.
\item[images] Specifies a pointer to a list of Image structures.
\end{description}

\section{Methods to Segment an Image with Thresholding Fuzzy c-Means}

\subsubsection{SegmentImage()}

\begin{quote}
\hspace*{-0.25in}
unsigned int SegmentImage(Image *image, const ColorspaceType colorspace,
  const unsigned int verbose,  const double cluster\_threshold, 
  const double smoothing\_threshold)
\end{quote}

Method SegmentImage() segments an image by analyzing the histograms of the
color components and identifying units that are homogeneous with the
fuzzy c-means technique.

Specify cluster threshold as the number of pixels in each cluster must
exceed the the cluster threshold to be considered valid.  Smoothing
threshold eliminates noise in the second derivative of the histogram.
As the value is increased, you can expect a smoother second derivative.
The default is 1.5.

A description of each parameter follows:

\begin{description}
\item[image] Specifies a pointer to an Image structure returned from ReadImage.
\item[colorspace] An unsigned integer value that indicates the colorspace.
Empirical evidence suggests that distances in YUV or YIQ correspond to perceptual
color differences more closely than do distances in RGB space.  The image
is then returned to RGB colorspace after color reduction.
\item[verbose] A value greater than zero prints detailed information about the
identified classes.
\end{description}

\section{Methods to Resize an Image}

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

\begin{quote}
\hspace*{-0.25in}
Image *MagnifyImage(image, ExceptionInfo *exception)
\end{quote}

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

\begin{description}

\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *MinifyImage(Image *image, ExceptionInfo *exception)
\end{quote}

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

A description of each parameter follows:
\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *ResizeImage(Image *image, const unsigned long columns,
  const unsigned long rows, const FilterType filter,  const double blur, 
  ExceptionInfo *exception)
\end{quote}

ResizeImage() 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}

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[columns] The number of columns in the scaled image.
\item[rows] The number of rows in the scaled image.
\item[filter] Image filter to use.
\item[blur] The blur factor where > 1 is blurry, < 1 is sharp.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{SampleImage()}

\begin{quote}
\hspace*{-0.25in}
Image *SampleImage(Image *image, const unsigned long columns, 
  const unsigned long rows, ExceptionInfo *exception)
\end{quote}

SampleImage() 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.

A description of each parameter follows:
\begin{description}

\item[image] The image.
\item[columns] The number of columns in the sampled image.
\item[rows] The number of rows in the sampled image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *ScaleImage(Image *image, const unsigned long columns,
   const unsigned long rows, ExceptionInfo *exception)
\end{quote}

ScaleImage() changes the size of an image to the given dimensions.

A description of each parameter follows:
\begin{description}
\item[image] The image.
\item[columns] The number of columns in the scaled image.
\item[rows] The number of rows in the scaled image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\section{Methods to Transform an Image}

\subsubsection{ChopImage()}
chop an image.

\begin{quote}
\hspace*{-0.25in}
Image *ChopImage(Image *image, const RectangleInfo *chop\_info,
  ExceptionInfo *exception)
\end{quote}

Chop() removes a region of an image and collapses the image to occupy the
removed portion.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[chop\_info] Define the region of the image to chop with members
\texttt{x}, \texttt{y}, \texttt{width}, and \texttt{height}.
If the image gravity is \texttt{Northeast}, \texttt{East},
or \texttt{SouthEast}, the offset \texttt{x} specifies the distance from
the right edge of the region to the right edge of the chopping region.
Similarly, if the image gravity is \texttt{SouthEast}, \texttt{South},
or \texttt{SouthWest}, \texttt{y} is the distance between the bottom edges.

\item[exception] Return any errors or warnings in this structure.
\end{description}


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

\begin{quote}
\hspace*{-0.25in}
Image *CoalesceImages(Image *image, ExceptionInfo *exception)
\end{quote}

CoalesceImages() 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.

Offsets are measured from the top left
corner of the composition to the top left corner of each image.  Positive
offsets represent a location of the image to the right and downward from
the corner of the composition.

A description of each parameter follows:

\begin{description}
\item[image] The image sequence.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{CropImage()}
crop an image.

\begin{quote}
\hspace*{-0.25in}
Image *CropImage(Image *image, const RectangleInfo *crop\_info, 
  ExceptionInfo *exception)
\end{quote}

Use CropImage() to extract a region of the image starting at the offset
defined by \texttt{crop\_info}.

A description of each parameter follows:
\begin{description}
\item[image] The image.
\item[crop\_info] Define the region of the image to crop with members
\texttt{x}, \texttt{y}, \texttt{width}, and \texttt{height}.
If the image gravity is \texttt{Northeast}, \texttt{East},
or \texttt{SouthEast}, the offset \texttt{x} specifies the distance from
the right edge of the region to the right edge of the cropping region.
Similarly, if the image gravity is \texttt{SouthEast}, \texttt{South},
or \texttt{SouthWest}, \texttt{y} is the distance between the bottom edges.
If the offset \texttt{x} is negative, it specifies the distance from
the right edge of the region to the right edge of the chopping region.

\item[exception] Return any errors or warnings in this structure.

\end{description}

\subsubsection{DeconstructImages()}
return the constituent parts of an image sequence

\begin{quote}
\hspace*{-0.25in}
Image *DeconstructImages(Image *image, ExceptionInfo *exception)
\end{quote}

DeconstructImages() compares each image with the next in a sequence and
returns the maximum bounding region of any pixel differences it discovers.
This method can undo a coalesced sequence returned by CoalesceImages(),
and is useful for removing redundant information
from a GIF or MNG animation.

A description of each parameter follows:
\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{FlipImage()}
reflect an image vertically.

\begin{quote}
\hspace*{-0.25in}
Image *FlipImage(Image *image, ExceptionInfo *exception)
\end{quote}

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

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{FlopImage()}
reflect an image horizontally.

\begin{quote}
\hspace*{-0.25in}
Image *FlopImage(Image *image, ExceptionInfo *exception)
\end{quote}

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

A description of each parameter follows:
\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{MosaicImages()}
inlay an image sequence to form a single coherent picture.

\begin{quote}
\hspace*{-0.25in}
Image *MosaicImages(const Image *image, ExceptionInfo *exception)
\end{quote}

MosaicImages() inlays an image sequence to form a single coherent picture.
It returns a single image with each image in the sequence composited at
the location defined by the \texttt{page} member of \texttt{image}.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *RollImage(Image *image, const int x\_offset, const int y\_offset,
   ExceptionInfo *exception)
\end{quote}

RollImage() offsets an image as defined by \texttt{x\_offset} and
\texttt{y\_offset}.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[x\_offset] The number of columns to roll in the horizontal direction,
right-to-left (left-to-right if x\_offset is negative).
\item[y\_offset] The number of rows to roll in the vertical direction,
bottom-to-top (top-to-bottom if y\_offset is negative).
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{ShaveImage()}

\begin{quote}
\hspace*{-0.25in}
Image *ShaveImage(const Image *image, const RectangleInfo *shave\_info,
  ExceptionInfo *exception)
\end{quote}

Method ShaveImage() shaves pixels from the image edges.
It allocates the memory necessary for the new Image
structure and returns a pointer to the new image.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[shave\_info] Specifies a pointer to a structure of type Rectangle which
defines the shave region.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
void TransformImage(Image **image, const char *crop\_geometry, 
  const char *image\_geometry)
\end{quote}

TransformImage() is a convenience method that behaves like ResizeImage() or
CropImage() but accepts scaling and/or cropping information as a region
geometry specification.  If the operation fails, the original image handle
is returned.

A description of each parameter follows:

\begin{description}
\item[image] The image.  The transformed image is returned as this parameter.

\item[crop\_geometry] A crop geometry string.  This geometry defines
a subregion of the image to crop.

\item[image\_geometry] An image geometry string.  This geometry defines
the final size of the image.
\end{description}

\section{Methods to Shear or Rotate an Image by an Arbitrary Angle}

\subsubsection{RotateImage}

\begin{quote}
\hspace*{-0.25in}
Image *RotateImage(Image *image, const double degrees,
  ExceptionInfo *exception)
\end{quote}

Method RotateImage() creates a new image that is a rotated copy of an
existing one.  Positive angles rotate counter-clockwise(right-hand rule), 
while negative angles rotate clockwise.  Rotated images are usually
larger than the originals and have 'empty' triangular corners.  X axis.
Empty triangles left over from shearing the image are filled with the
color defined by the pixel at location(0, 0). RotateImage allocates the
memory necessary for the new Image structure and returns a pointer to
the new image.

Method RotateImage() is based on the paper "A Fast Algorithm for General
Raster Rotatation" by Alan W.  Paeth.  RotateImage is adapted from a
similar method based on the Paeth paper written by Michael Halle of the
Spatial Imaging Group, MIT Media Lab.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[degrees] Specifies the number of degrees to rotate the image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{ShearImage()}

\begin{quote}
\hspace*{-0.25in}
Image *ShearImage(Image *image, const double x\_shear,  const double y\_shear,
  ExceptionInfo *exception)
\end{quote}

Method ShearImage() creates a new image that is a shear\_image copy of an
existing one.  Shearing slides one edge of an image along the X or Y axis, 
creating a parallelogram.  An X direction shear slides an edge along
the X axis, while a Y direction shear slides an edge along the Y axis.
The amount of the shear is controlled by a shear angle.  For X direction
shears, x\_shear is measured relative to the Y axis,  and similarly, 
for Y direction shears y\_shear is measured relative to the X axis.
Empty triangles left over from shearing the image are filled with the
color defined by the pixel at location(0, 0). ShearImage allocates the
memory necessary for the new Image structure and returns a pointer to
the new image.

Method ShearImage() is based on the paper "A Fast Algorithm for General
Raster Rotatation" by Alan W.  Paeth.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[x\_shear, y\_shear] Specifies the number of degrees to shear the image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\section{Methods to Enhance an Image}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int ContrastImage(Image *image, const unsigned int sharpen)
\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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[sharpen] Increase or decrease image contrast.
\end{description}

\subsubsection{EqualizeImage()}
equalize an image.

\begin{quote}
\hspace*{-0.25in}
unsigned int EqualizeImage(Image *image)
\end{quote}

EqualizeImage() applies a histogram equalization to the image.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

\subsubsection{GammaImage()}
gamma-correct the image.

\begin{quote}
\hspace*{-0.25in}
unsigned int GammaImage(Image *image, const char *gamma)
\end{quote}

Use GammaImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[gamma] Define the level of gamma correction.
\end{description}

\subsubsection{LevelImage()}
adjust the level of image contrast.

\begin{quote}
\hspace*{-0.25in}
unsigned int LevelImage(Image *image, const char *levels)
\end{quote}

Give three values delineated with commas: black, gamma, and white
(e.g. 10,1.0,65000 or 2,0.5,98%).  The white and black points range from
0 to MaxRGB or from 0 to 100% and gamma is an exponent that ranges
from 0.1 to 10.  If a "%" sign
is present, the black and white points are percentages of MaxRGB.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[levels] Define the image black and white levels and gamma.
\end{description}

\subsubsection{ModulateImage()}
adjust the brightness, saturation, and hue.

\begin{quote}
\hspace*{-0.25in}
unsigned int ModulateImage(Image *image, const char *modulate)
\end{quote}

ModulateImage() lets you control the brightness, saturation, and hue
of an image.  \texttt{Modulate} represents the brightness, saturation,
and hue as one parameter (e.g. 90,150,100).

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[modulate] Define the percent change in brightness, saturation, and hue.
\end{description}

\subsubsection{NormalizeImage()}
enhance image contrast.

\begin{quote}
\hspace*{-0.25in}
unsigned int NormalizeImage(Image *image)
\end{quote}

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

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

\section{ImageMagick Image Effects Methods}

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

\begin{quote}
\hspace*{-0.25in}
Image *AddNoiseImage(const Image *image, const NoiseType noise\_type, 
  ExceptionInfo *exception)
\end{quote}


AddNoiseImage() adds random noise to the image.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[noise\_type] The type of noise: Uniform, Gaussian, Multiplicative,
  Impulse, Laplacian, or Poisson.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{BlurImage()}
blur the image.

\begin{quote}
\hspace*{-0.25in}
Image *BlurImage(const Image *image, const double radius,
  const double sigma, ExceptionInfo *exception)
\end{quote}

BlurImage() 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 BlurImage() selects a suitable radius for you.

A description of each parameter follows:
\begin{description}
\item[radius] The radius of the Gaussian, in pixels,  not counting the center
pixel.
\item[sigma] The standard deviation of the Gaussian, in pixels.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{ColorizeImage()}
colorize an image.

\begin{quote}
\hspace*{-0.25in}
Image *ColorizeImage(const Image *image, const char *opacity,
  const PixelPacket target, ExceptionInfo *exception)
\end{quote}

ColorizeImage() 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).

A description of each parameter follows:

\begin{description}

\item[image] The image.
\item[opacity] A character string indicating the level of opacity as a
percentage.
\item[target] A color value.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *ConvolveImage(const Image *image, const unsigned int order, 
  const double *kernel, ExceptionInfo *exception)
\end{quote}

ConvolveImage() applies a custom convolution kernel to the image.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[order] The number of columns and rows in the filter kernel.
\item[kernel] An array of double representing the convolution kernel.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{DespeckleImage()}
filter speckles.

\begin{quote}
\hspace*{-0.25in}
Image *DespeckleImage(const Image *image, ExceptionInfo *exception)
\end{quote}

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

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{EdgeImage()}
detect edges within an image.

\begin{quote}
\hspace*{-0.25in}
Image *EdgeImage(const Image *image, const double radius,
  ExceptionInfo *exception)
\end{quote}

EdgeImage() 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.

A description of each parameter follows:

\begin{description}
\item[image]  The image.
\item[radius] the radius of the pixel neighborhood.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{EmbossImage}
emboss the image.

\begin{quote}
\hspace*{-0.25in}
Image *EmbossImage(const Image *image, const double radius,
  const double sigma, ExceptionInfo *exception)
\end{quote}

EmbossImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[radius] the radius of the pixel neighborhood.
\item[sigma] The standard deviation of the Gaussian, in pixels.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *EnhanceImage(const Image *image, ExceptionInfo *exception)
\end{quote}

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

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{GaussianBlurImage()}
blur an image.

\begin{quote}
\hspace*{-0.25in}
Image *GaussianBlurImage(const Image *image, const double radius,
  const double sigma, ExceptionInfo *exception)
\end{quote}

GaussianBlurImage() 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 GaussianBlurImage() selects a suitable radius for you.

A description of each parameter follows:
\begin{description}
\item[image] The image.
\item[radius] the radius of the Gaussian, in pixels,  not counting the
  center pixel.
\item[sigma] the standard deviation of the Gaussian, in pixels.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *ImplodeImage(const Image *image, const double amount, 
  ExceptionInfo *exception)
\end{quote}

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


A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[amount] Define the extent of the implosion.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *MedianFilterImage(const Image *image, const double radius, 
  ExceptionInfo *exception)
\end{quote}

MedianFilterImage() 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}.

A description of each parameter follows:

\begin{description}

\item[image]  The image.
\item[radius] The radius of the pixel neighborhood.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *MorphImages(const Image *image, const unsigned long number\_frames,
  ExceptionInfo *exception)
\end{quote}

The MorphImages() 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}.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[number\_frames] Define the number of in-between image to generate.
The more in-between frames, the smoother the morph.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{MotionBlurImage()}
simulate motion blur.

\begin{quote}
\hspace*{-0.25in}
Image *MotionBlurImage(const Image *image, const double radius,
  const double sigma, ExceptionInfo *exception)
\end{quote}

MotionBlurImage() 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 MotionBlurImage()selects a suitable radius for you.  \texttt{Angle}
gives the angle of the blurring motion.

A description of each parameter follows:

\begin{description}
\item[image]  The image.
\item[radius] The radius of the Gaussian, in pixels, not counting the center
pixel. 
\item[sigma] The standard deviation of the Motion, in pixels.
\item[angle] Apply the effect along this angle.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{NegateImage()}

\begin{quote}
\hspace*{-0.25in}
unsigned int NegateImage(Image *image, const unsigned int grayscale)
\end{quote}

Method NegateImage() negates the colors in the reference image.
The Grayscale option means that only grayscale values within the image
are negated.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *OilPaintImage(const Image *image, const double radius, 
  ExceptionInfo *exception)
\end{quote}

OilPaintImage() 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}.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[radius] The radius of the circular neighborhood.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{PlasmaImage()}
initialize an image with plasma fractal values.

\begin{quote}
\hspace*{-0.25in}
unsigned int PlasmaImage(const Image *image, const SegmentInfo *segment, 
  int attenuate, int depth)
\end{quote}

PlasmaImage() initializes an image with plasma fractal values.  The image
must be initialized with a base color and the random number generator
seeded before this method is called.

A description of each parameter follows:

\begin{description}

\item[image] The image.
\item[segment] Define the region to apply plasma fractals values.
\item[attenuate] Define the plasma attenuation factor.
\item[depth] Limit the plasma recursion depth.
\end{description}

\subsubsection{ReduceNoiseImage()}
smooth an image.

\begin{quote}
\hspace*{-0.25in}
Image *ReduceNoiseImage(Image *image, const double radius,  ExceptionInfo
*exception)
\end{quote}

ReduceNoiseImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[radius] The radius of the pixel neighborhood.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{ShadeImage}
shade the image with light source.

\begin{quote}
\hspace*{-0.25in}
Image *ShadeImage(const Image *image, const unsigned int color\_shading, 
  double azimuth, double elevation,  ExceptionInfo *exception)
\end{quote}

ShadeImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[color\_shading] A value other than zero shades the red, green, and blue
components of the image.
\item[azimuth, elevation] Define the light source direction.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{SharpenImage()}
sharpen an image.

\begin{quote}
\hspace*{-0.25in}
Image *SharpenImage(Image *image, const double radius,  const double sigma,
  ExceptionInfo *exception)
\end{quote}

SharpenImage() 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 SharpenImage() selects a suitable radius for you.

A description of each parameter follows:

\begin{description}
\item[radius] The radius of the Gaussian, in pixels,  not counting the center
pixel.
\item[sigma] The standard deviation of the Laplacian, in pixels.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
void SolarizeImage(Image *image, const double threshold)
\end{quote}

SolarizeImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[threshold] Define the extent of the solarization.
\end{description}

\subsubsection{SpreadImage()}
randomly displace pixels.

\begin{quote}
\hspace*{-0.25in}
Image *SpreadImage(const Image *image, const unsigned int amount, 
  ExceptionInfo *exception)
\end{quote}

SpreadImage() is a special effects method that randomly displaces each
pixel in a block defined by the amount parameter.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[radius] An unsigned value constraining the "vicinity" for choosing a
random pixel to swap.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *SteganoImage(const Image *image, Image *watermark,
  ExceptionInfo *exception)
\end{quote}

Use SteganoImage() 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.


A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[watermark] The watermark image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *StereoImage(cosnt Image *image, Image *offset\_image, 
  ExceptionInfo *exception)
\end{quote}

StereoImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The left-hand image.
\item[offset\_image] The right-hand image.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *SwirlImage(const Image *image, double degrees,
  ExceptionInfo *exception)
\end{quote}

SwirlImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[degrees] Define the tightness of the swirling effect.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int ThresholdImage(Image *image, const double threshold)
\end{quote}

ThresholdImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[threshold] Define the threshold value.
\end{description}

\subsubsection{UnsharpMaskImage()}
sharpen an image.

\begin{quote}
\hspace*{-0.25in}
Image *UnsharpMaskImage(const Image *image, const double radius,
  const double sigma, const double amount,  const double threshold, 
  ExceptionInfo *exception)
\end{quote}

UnsharpMaskImage() 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 UnsharpMaskImage() selects a suitable radius for you.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[radius] The radius of the Gaussian, in pixels,  not counting the center
pixel.
\item[sigma] The standard deviation of the Gaussian, in pixels.
\item[amount] The percentage of the difference between the original and the
blur image that is added back into the original.
\item[threshold] The threshold, as a fraction of MaxRGB, needed to apply
the difference amount.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{WaveImage()}
special effects filter.

\begin{quote}
\hspace*{-0.25in}
Image *WaveImage(const Image *image, const double amplitude,
  const double wave\_length, ExceptionInfo *exception)
\end{quote}

The WaveImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[amplitude, frequency] Define the amplitude and wavelength of the sine
wave.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\section{ImageMagick Image Decoration Methods}

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

\begin{quote}
\hspace*{-0.25in}
Image *BorderImage(const Image *image, const RectangleInfo *border\_info,
  ExceptionInfo *exception)
\end{quote}

BorderImage() surrounds the image with a border of the color defined
by the \texttt{border\_color} member of the \texttt{image} structure.
The width and height of the border are defined by the corresponding
members of the \texttt{border\_info} structure.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[border\_info] Define the width and height of the border.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{FrameImage()}
surround the image with a decorative border.

\begin{quote}
\hspace*{-0.25in}
Image *FrameImage(const Image *image, const FrameInfo *frame\_info, 
  ExceptionInfo *exception)
\end{quote}

FrameImage() adds a simulated three-dimensional border around the
image.  The color of the border is defined by the \texttt{matte\_color}
member of \texttt{image}.  Members \texttt{width} and \texttt{height}
of \texttt{frame\_info} specify the border width of the vertical and
horizontal sides of the frame.  Members \texttt{inner} and \texttt{outer}
indicate the width of the inner and outer \texttt{shadows} of the frame.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[frame\_info] Define the width and height of the frame and its bevels.
\item[exception] Return any errors or warnings in this structure.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int RaiseImage(Image *image, const RectangleInfo *raise\_info,
  const int raised)
\end{quote}

RaiseImage() creates a simulated three-dimensional button-like effect by
lightening and darkening the edges of the image.  Members \texttt{width} and
\texttt{height} of \texttt{raise\_info} define the width of the vertical and
horizontal edge of the effect.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[raise\_info] Define the width and height of the raised area.
region.
\item[raised] A value other than zero creates a 3-D raised effect,
otherwise it has a lowered effect.
\end{description}

\section{Methods to Annotate an Image}

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

\begin{quote}
\hspace*{-0.25in}
 unsigned int AnnotateImage(Image *image, DrawInfo *draw\_info)
\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.  Your text can optionally embed any of these 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. \\
\> \%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 a 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.
\end{tabbing}

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[draw\_info] The draw info.
\end{description}

\subsubsection{GetTypeMetrics()}
get font attributes.

\begin{quote}
\hspace*{-0.25in}
unsigned int GetTypeMetrics(Image *image, const DrawInfo *draw\_info,
   TypeMetric *metrics)
\end{quote}

GetTypeMetrics() returns the following information for the supplied font
and text:

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


A description of each parameter follows:

\begin{description}

\item[image] The image.
\item[draw\_info] The draw info.
\item[metrics] Return the font metrics in this structure.
\end{description}

\section{Methods to Draw on an Image}

\subsubsection{CloneDrawInfo}
clone a draw info structure.

\begin{quote}
\hspace*{-0.25in}
DrawInfo *CloneDrawInfo(const ImageInfo *image\_info,
  const DrawInfo *draw\_info)
\end{quote}

CloneDrawInfo() makes a copy of the given draw info structure.  If NULL
is specified, a new image info structure is created initialized to
default values.

A description of each parameter follows:

\begin{description}
\item[image\_info] The image info.
\item[draw\_info] The draw info.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int ColorFloodfillImage(Image *image, const DrawInfo *draw\_info,
  const PixelPacket target,  const long x,  const long y,
  const PaintMethod method)
\end{quote}

ColorFloodfill() changes the color value of any pixel that matches
\texttt{target} and is an immediate neighbor.  If the method
\texttt{FillToBorderMethod} is specified, the color value is changed
for any neighbor pixel that does not match the \texttt{bordercolor}
member of \texttt{image}.

By default \texttt{target} must match a particular pixel color
exactly.  However, in many cases two colors may differ by a small
amount.  The \texttt{fuzz} member of \texttt{image} 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[draw\_info] The draw info.
\item[target] The RGB value of the target color.
\item[x, y] The starting location of the operation.
\item[method] Choose either \texttt{FloodfillMethod} or
   \texttt{FillToBorderMethod}.
\end{description}

\subsubsection{DestroyDrawInfo()}
destroy draw info.

\begin{quote}
\hspace*{-0.25in}
void DestroyDrawInfo(DrawInfo *draw\_info)
\end{quote}

DestroyDrawInfo() deallocates memory associated with \texttt{draw\_info}.

A description of each parameter follows:

\begin{description}
\item[draw\_info] The draw info.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int DrawImage(Image *image, const DrawInfo *draw\_info)
\end{quote}

Use DrawImage() 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 setting
one or more members of the draw info structure:

\begin{description}
\item[primitive]  The primitive describes the type of graphic to draw.
Choose from these primitives:
\begin{tabbing}
0000\=11111111111111111111111\=22222222222222222\=3333333333333333333333\kill
\> PointPrimitive \> LinePrimitive  \> RectanglePrimitive \\
\> roundRectanglePrimitive  \> ArcPrimitive  \> EllipsePrimitive \\
\> CirclePrimitive  \> PolylinePrimitive  \> PolygonPrimitive \\
\> BezierPrimitive  \> PathPrimitive  \> ColorPrimitive \\
\> MattePrimitive \> TextPrimitive \> ImagePrimitive
\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[stroke\_width] 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}


A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[draw\_info] The draw info.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int MatteFloodfillImage(Image *image, const PixelPacket target,
  const unsigned int opacity, const long x, const long y,
  const PaintMethod method)
\end{quote}

MatteFloodfill() changes the transparency value of any pixel that
matches \texttt{target} and is an immediate neighbor.  If the method 
\texttt{FillToBorderMethod} is specified, the transparency value is
changed for any neighbor pixel that does not match the
\texttt{bordercolor} member of \texttt{image}.

By default \texttt{target} must match a particular pixel transparency
exactly.  However, in many cases two transparency values may differ by
a small amount.  The \texttt{fuzz} member of \texttt{image} 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[target] The RGB value of the target color.
\item[opacity] The level of transparency: 0 is fully opaque and MaxRGB is
fully transparent.
\item[x, y] The starting location of the operation.
\item[method] Choose either \texttt{FloodfillMethod} or
   \texttt{FillToBorderMethod}.
\end{description}

\subsubsection{OpaqueImage}
globally change a color.

\begin{quote}
\hspace*{-0.25in}
unsigned int OpaqueImage(Image *image, const PixelPacket target, 
  const PixelPacket fill)
\end{quote}

OpaqueImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[target] The RGB value of the target color.
\item[fill] The replacement color.
\end{description}

\subsubsection{TransparentImage()}
make color transparent.

\begin{quote}
\hspace*{-0.25in}
unsigned int TransparentImage(Image *image, const PixelPacket target,
  const unsigned int opacity)
\end{quote}

TransparentImage() 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.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[target] The RGB value of the target color.
\item[fill] The replacement opacity value.
\end{description}

\section{Methods to Create a Montage}

\subsubsection{CloneMontageInfo()}
clone a montage info structure.

\begin{quote}
\hspace*{-0.25in}
MontageInfo *CloneMontageInfo(const ImageInfo *image\_info, 
  const MontageInfo *montage\_info)
\end{quote}

CloneMontageInfo() makes a copy of the given montage info structure.  If
NULL is specified, a new image info structure is created initialized to
default values.

A description of each parameter follows:

\begin{description}
\item[image\_info] The image info.
\item[montage\_info] The montage info.
\end{description}

\subsubsection{DestroyMontageInfo()}
destroy montage info.

\begin{quote}
\hspace*{-0.25in}
void DestroyMontageInfo(MontageInfo *montage\_info)
\end{quote}

DestroyMontageInfo() deallocates memory associated with \texttt{montage\_info}.

A description of each parameter follows:

\begin{description}
\item[montage\_info] The montage info.
\end{description}

\subsubsection{GetMontageInfo()}
get montage info.

\begin{quote}
\hspace*{-0.25in}
void GetMontageInfo(const ImageInfo *image\_info, MontageInfo *montage\_info)
\end{quote}

GetMontageInfo() initializes \texttt{montage\_info} to default values.

A description of each parameter follows:

\begin{description}
\item[image\_info] The image info.
\item[montage\_info] The montage info.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
Image *MontageImages(const Image *image, const MontageInfo *montage\_info,
  ExceptionInfo *exception)
\end{quote}

Montageimages() is a layout manager that lets you tile one or more
thumbnails across an image canvas.

A description of each parameter follows:

\begin{description}

\item[image] The image.
\item[montage\_info] The montage info.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\section{Image Text Attributes Methods}

\subsubsection{DestroyImageAttributes()}
destroy an image attribute.

\begin{quote}
\hspace*{-0.25in}
DestroyImageAttributes(Image *image)
\end{quote}

DestroyImageAttributes() deallocates memory associated with the
image attribute list.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
ImageAttribute *GetImageAttribute(const Image *image, const char *key)
\end{quote}

GetImageAttribute() searches the list of image attributes and returns
a pointer to attribute if it exists otherwise NULL.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[key] These character strings are the name of an image attribute to return.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
unsigned int SetImageAttribute(Image *image, const char *key,
  const char *value)
\end{quote}

SetImageAttribute searches the list of image attributes and replaces the
attribute value.  If it is not found in the list, the attribute name
and value is added to the list.  If the attribute exists in the list,
the value is concatenated to the attribute.  SetImageAttribute returns
True if the attribute is successfully concatenated or added to the list,
otherwise False.  If the value is NULL,  the matching key is deleted
from the list.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[key, value] These character strings are the name and value of an image
attribute to replace or add to the list.
\end{description}

\section{Methods to Compute a Digital Signature for an Image}

\subsubsection{SignatureImage()}

\begin{quote}
\hspace*{-0.25in}
unsigned int SignatureImage(Image *image)
\end{quote}

SignatureImage() computes a message digest from an image pixel stream
with an implementation of the NIST SHA-256 Message Digest algorithm.  This
signature uniquely identifies the image and is convenient for determining
whether two images are identical.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

\section{Methods to Interactively Animate an Image Sequence}

\subsubsection{XAnimateBackgroundImage}

\begin{quote}
\hspace*{-0.25in}
void XAnimateBackgroundImage(Display *display, XResourceInfo *resource\_info,
  Image *image)
\end{quote}

XAnimateBackgroundImage() animates an image sequence in the background
of a window.

A description of each parameter follows:

\begin{description}
\item[display] Specifies a connection to an X server returned from XOpenDisplay.
\item[resource\_info] Specifies a pointer to a X11 XResourceInfo structure.
\item[image] Specifies a pointer to a Image structure returned from ReadImage.
\end{description}

\subsubsection{XAnimateImage}
animate an image in an X window.

\begin{quote}
\hspace*{-0.25in}
Image *XAnimateImages(Display *display, XResourceInfo *resource\_info, 
  char **argv, const int argc, Image *image)
\end{quote}

XAnimateImages() displays an image via X11.

A description of each parameter follows:
\begin{description}
\item[display] Specifies a connection to an X server returned from XOpenDisplay.
\item[resource\_info] Specifies a pointer to a X11 XResourceInfo structure.
\item[argv] Specifies the application's argument list.
\item[argc] Specifies the number of arguments.
\item[image] Specifies a pointer to a Image structure returned from ReadImage.
\end{description}

\section{Methods to Interactively Display and Edit an Image}

\subsubsection{XDisplayBackgroundImage}
display an image to the background of an X window.

\begin{quote}
\hspace*{-0.25in}
unsigned int XDisplayBackgroundImage(Display *display,
  XResourceInfo *resource\_info, Image *image)
\end{quote}

XDisplayBackgroundImage() displays an image in the background of
a window.

A description of each parameter follows:

\begin{description}
\item[display] Specifies a connection to an X server returned from XOpenDisplay.
\item[resource\_info]
Specifies a pointer to a X11 XResourceInfo structure.
\item[image]
Specifies a pointer to a Image structure returned from ReadImage.
\end{description}

\subsubsection{XDisplayImage}
display an image on an X window.

\begin{quote}
\hspace*{-0.25in}
Image *XDisplayImage(Display *display, XResourceInfo *resource\_info,
  char **argv,  int argc,  Image **image,  unsigned long *state)
\end{quote}

XDisplayImage() displays an image via X11.  A new image is created and
returned if the user interactively transforms the displayed image.

A description of each parameter follows:

\begin{description}
\item[display] Specifies a connection to an X server returned from XOpenDisplay.
\item[resource\_info] Specifies a pointer to a X11 XResourceInfo structure.
\item[argv] Specifies the application's argument list.
\item[argc] Specifies the number of arguments.
\item[image] The image.
\end{description}

\section{Methods to Get or Set Image Pixels}

\subsubsection{AcquirePixelCache()}
acquire image pixels.

\begin{quote}
\hspace*{-0.25in}
PixelPacket *AcquirePixelCache(Image *image, const int x,  const int y, 
  const unsigned long columns, const unsigned long rows,
  ExceptionInfo *exception) 
\end{quote}

AcquirePixelCache() acquires pixels from the in-memory or disk pixel
cache as defined by the geometry parameters.  A pointer to the pixels
is returned if the pixels are transferred, otherwise a NULL is returned.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[x, y, columns, rows] These values define the perimeter of a region of
\item[exception] Return any errors or warnings in this structure.
pixels.
\end{description}

\subsubsection{GetIndexes()}
get indexes.

\begin{quote}
\hspace*{-0.25in}
IndexPacket *GetIndexes(const Image *image)
\end{quote}

GetIndexes() returns the colormap indexes associated with
the last call to the SetPixelCache() or GetPixelCache() methods.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

\subsubsection{GetOnePixel()}
get one pixel from cache.

\begin{quote}
\hspace*{-0.25in}
PixelPacket *GetOnePixel(const Image image, const int x, const int y)
\end{quote}

GetOnePixelFromCache() returns a single pixel at the specified(x, y)
location.  The image background color is returned if an error occurs.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[x, y] These values define the location of the pixel to return.
\end{description}

\subsubsection{GetPixelCache()}
get pixels from cache.

\begin{quote}
\hspace*{-0.25in}
PixelPacket *GetPixelCache(Image *image, const int x,  const int y, 
  const unsigned long columns, const unsigned long rows)
\end{quote}

GetPixelCache() gets pixels from the in-memory or disk pixel cache as
defined by the geometry parameters.  A pointer to the pixels is returned
if the pixels are transferred, otherwise a NULL is returned.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[x, y, columns, rows]
These values define the perimeter of a region of
pixels.
\end{description}

\subsubsection{SetPixelCache()}
set pixel cache.

\begin{quote}
\hspace*{-0.25in}
PixelPacket *SetPixelCache(Image *image, const int x,  const int y, 
  const unsigned long columns, const unsigned long rows)
\end{quote}

SetPixelCache() allocates an area to store image pixels as defined by
the region rectangle and returns a pointer to the area.  This area is
subsequently transferred from the pixel cache with method SyncPixelCache.
A pointer to the pixels is returned if the pixels are transferred,
otherwise a NULL is returned.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\item[x, y, columns, rows]
These values define the perimeter of a region of
pixels.
\end{description}

\subsubsection{SyncPixelCache()}
synchronize pixel cache.

\begin{quote}
\hspace*{-0.25in}
unsigned int SyncPixelCache(Image *image)
\end{quote}

SyncPixelCache() saves the image pixels to the in-memory or disk cache.
The method returns True if the pixel region is synced, otherwise False.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

\section{ImageMagick Cache Views Methods}

\subsubsection{CloseCacheView}
close cache view.

\begin{quote}
\hspace*{-0.25in}
 void CloseCacheView(ViewInfo *view)
\end{quote}

CloseCacheView() closes the specified view returned by a previous call
to OpenCacheView().

A description of each parameter follows:

\begin{description}
\item[view]
The address of a structure of type ViewInfo.
\end{description}

\subsubsection{GetCacheView}
get cache view.

\begin{quote}
\hspace*{-0.25in}
PixelPacket *GetCacheView(ViewInfo *view, const int x,  const int y,
  const unsigned long columns,  const unsigned long rows)
\end{quote}

GetCacheView() gets pixels from the in-memory or disk pixel cache as
defined by the geometry parameters.  A pointer to the pixels is returned
if the pixels are transferred, otherwise a NULL is returned.

A description of each parameter follows:

\begin{description}
\item[view] The address of a structure of type ViewInfo.
\item[x, y, columns, rows]
These values define the perimeter of a region of pixels.
\end{description}

\subsubsection{GetCacheViewIndexes}
get cache view indexes.

\begin{quote}
\hspace*{-0.25in}
IndexPacket *GetCacheViewIndexes(const ViewInfo *view)
\end{quote}

GetCacheViewIndexes() returns the colormap indexes associated with
the specified view.

A description of each parameter follows:

\begin{description}
\item[view] The address of a structure of type ViewInfo.
\end{description}

\subsubsection{GetCacheViewPixels}
get cache view.

\begin{quote}
\hspace*{-0.25in}
PixelPacket *GetCacheViewPixels(const ViewInfo *view)
\end{quote}

GetCacheViewPixels() returns the pixels associated with the specified
specified view.

A description of each parameter follows:

\begin{description}
\item[view] The address of a structure of type ViewInfo.
\end{description}

\subsubsection{OpenCacheView}
open a cache view.

\begin{quote}
\hspace*{-0.25in}
 ViewInfo *OpenCacheView(Image *image)
\end{quote}

OpenCacheView() opens a view into the pixel cache.

A description of each parameter follows:

\begin{description}
\item[image] The image.
\end{description}

\subsubsection{SetCacheView}
set a cache view.

\begin{quote}
\hspace*{-0.25in}
PixelPacket *SetCacheView(ViewInfo *view, const long x,  const long y,
  const unsigned long columns,  const unsigned long rows)
\end{quote}

SetCacheView() gets pixels from the in-memory or disk pixel cache as
defined by the geometry parameters.  A pointer to the pixels is returned
if the pixels are transferred, otherwise a NULL is returned.

A description of each parameter follows:
\begin{description}

\item[view] The address of a structure of type ViewInfo.
\item[x, y, columns, rows] 
These values define the perimeter of a region of pixels.
\end{description}

\subsubsection{SyncCacheView}
synchronize a cache view.

\begin{quote}
\hspace*{-0.25in}
 unsigned int SyncCacheView(ViewInfo *view)
\end{quote}

SyncCacheView() saves the view pixels to the in-memory or disk cache.
The method returns True if the pixel region is synced, otherwise False.

A description of each parameter follows:
\begin{description}
\item[view] The address of a structure of type ViewInfo.
\end{description}

\section{Image Pixel FIFO}

\subsubsection{ReadStream()}
read a stream.

\begin{quote}
\hspace*{-0.25in}
unsigned int ReadStream(const ImageInfo *image\_info,
  void (*Stream)(const Image *, const void *,  const size\_t),
  ExceptionInfo *exception)
\end{quote}

ReadStream() makes the image pixels available to a user supplied callback
method immediately upon reading a scanline with the ReadImage() method.

A description of each parameter follows:

\begin{description}
\item[image\_info] The image info.
\item[stream] A callback method.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{WriteStream()}
write a stream.

\begin{quote}
\hspace*{-0.25in}
unsigned int WriteStream(const ImageInfo *image\_info,
  Image *, int(*Stream) (const Image *, const void *, const size\_t))
\end{quote}

WriteStream() makes the image pixels available to a user supplied
callback method immediately upon writing pixel data with the WriteImage()
method.

A description of each parameter follows:

\begin{description}
\item[image\_info] The image info.
\item[stream] A callback method.
\end{description}

\section{Methods to Read or Write Binary Large Objects}

\subsubsection{BlobToImage()}
convert a blob to an image.

\begin{quote}
\hspace*{-0.25in}
Image *BlobToImage(const ImageInfo *image\_info, const void
*blob, const size\_t length,  ExceptionInfo *exception)
\end{quote}

BlobToImage() implements direct to memory image formats.  It returns
the blob as an image.

A description of each parameter follows:

\begin{description}
\item[image\_info] The image info.
\item[blob] The address of a character stream in one of the image formats
understood by ImageMagick.
\item[length] This size\_t integer reflects the length in bytes of the blob.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{DestroyBlobInfo()}
destroy a blob.

\begin{quote}
\hspace*{-0.25in}
 void DestroyBlobInfo(BlobInfo *blob)
\end{quote}

DestroyBlobInfo() deallocates memory associated with an BlobInfo structure.

A description of each parameter follows:

\begin{description}
\item[blob] Specifies a pointer to a BlobInfo structure.
\end{description}

\subsubsection{GetBlobInfo()}
initialize a blob.

\begin{quote}
\hspace*{-0.25in}
void GetBlobInfo(BlobInfo *blob)
\end{quote}

GetBlobInfo() initializes the BlobInfo structure.

A description of each parameter follows:

\begin{description}
\item[blob] Specifies a pointer to a BlobInfo structure.
\end{description}

\subsubsection{ImageToBlob()}
convert image to a blob.

\begin{quote}
\hspace*{-0.25in}
void *ImageToBlob(const ImageInfo *image\_info, Image *image,
  size\_t *length, ExceptionInfo *exception)
\end{quote}

ImageToBlob() implements direct to memory image formats.  It returns the
image as a blob and its length.  The magick member of the Image structure
determines the format of the returned blob(GIG, JPEG,  PNG, etc.).

A description of each parameter follows:

\begin{description}
\item[image\_info] Specifies a pointer to an ImageInfo structure.
\item[image] The image.
\item[length] This pointer to a size\_t integer sets the initial length of the
blob.  On return, it reflects the actual length of the blob.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\section{ImageMagick Registry Methods}

\subsubsection{DeleteMagickRegistry}
delete a blob from the registry.


\begin{quote}
\hspace*{-0.25in}
 unsigned int DeleteMagickRegistry(const long id)
\end{quote}

DeleteMagickRegistry() deletes an entry in the registry as defined by the id.
It returns True if the entry is deleted otherwise False if no entry is
found in the registry that matches the id.

A description of each parameter follows:
\begin{description}
\item[id] The registry id.
\end{description}

\subsubsection{GetImageFromMagickRegistry}
get an image from the registry by name.

\begin{quote}
\hspace*{-0.25in}
Image *GetImageFromMagickRegistry(const char *name, ExceptionInfo *exception)
\end{quote}

GetImageFromMagickRegistry() gets an image from the registry as defined by
its name.  If the blob that matches the name is not found, NULL is returned.

A description of each parameter follows:
\begin{description}

\item[name] The image name.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{GetMagickRegistry}
get a blob from the registry.

\begin{quote}
\hspace*{-0.25in}
const void *GetMagickRegistry(const long id,RegistryType *type,
  size\_t *length, ExceptionInfo *exception)
\end{quote}

GetMagickRegistry() gets a blob from the registry as defined by the id.  If
the blob that matches the id is not found, NULL is returned.

A description of each parameter follows:
\begin{description}

\item[id] The registry id.
\item[type] The registry type.
\item[length] The blob length in number of bytes.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{SetMagickRegistry}
save a blob to the registry.


\begin{quote}
\hspace*{-0.25in}
long SetMagickRegistry(const void *blob,const size\_t length,
  ExceptionInfo *exception)
\end{quote}

SetMagickRegistry() sets a blob into the registry and returns a unique ID.
If an error occurs, -1 is returned.


A description of each parameter follows:
\begin{description}
\item[type] The registry type.
\item[blob] The address of a Binary Large OBject.
\item[length]
The blob length in number of bytes.

\item[exception]
Return any errors or warnings in this structure.
\end{description}

\section{Methods to Read or List ImageMagick Image formats}

\subsubsection{DestroyMagickInfo()}
destroy magick info.

\begin{quote}
\hspace*{-0.25in}
void DestroyMagickInfo()
\end{quote}

DestroyMagickInfo() deallocates memory associated MagickInfo list.

\subsubsection{GetImageMagick()}
return an image format that matches the magic number.

\begin{quote}
\hspace*{-0.25in}
char *GetImageMagick(const unsigned char *magick, const size\_t length)
\end{quote}

Method GetImageMagick() searches for an image format that matches the
specified magick string.  If one is found the tag is returned otherwise
NULL.

A description of each parameter follows:

\begin{description}
\item[magick] The image format we are searching for.
\item[length] The length of the binary string.
\end{description}

\subsubsection{GetMagickConfigurePath()}
get the path of a configuration file.

\begin{quote}
\hspace*{-0.25in}
char *GetMagickConfigurePath(const char *filename)
\end{quote}

GetMagickConfigurePath() searches a number of pre-defined locations
for the specified ImageMagick configuration file and returns the path.
The search order follows:

\begin{verbatim}
<current directory>/
<client path>/
$MAGICK_HOME/
$HOME/.magick/
MagickLibPath
MagickModulesPath
MagickSharePath
\end{verbatim}

A description of each parameter follows:

\begin{description}
\item[filename] The desired configuration file.
\end{description}

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

\begin{quote}
\hspace*{-0.25in}
MagickInfo *GetMagickInfo(const char *tag)
\end{quote}

GetMagickInfo() returns a pointer MagickInfo structure that matches
the specified tag.  If tag is NULL, the head of the image format list
is returned.

A description of each parameter follows:

\begin{description}
\item[tag] The image format we are looking for.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{GetMagickVersion()}
get the ImageMagick version.

\begin{quote}
\hspace*{-0.25in}
 char *GetMagickVersion(unsigned int *version)
\end{quote}

GetMagickVersion() returns the ImageMagick API version as a string and as a
number.

A description of each parameter follows:

\begin{description}
\item[version] The ImageMagick version is returned as a number.
\end{description}

\subsubsection{InitializeMagick()}
initialize the ImageMagick API.

\begin{quote}
\hspace*{-0.25in}
InitializeMagick(const char *path)
\end{quote}

InitializeMagick() initializes the ImageMagick environment.

A description of each parameter follows:

\begin{description}
\item[path] The execution path of the current ImageMagick client.
\end{description}

\subsubsection{ListMagickInfo()}
list the recognized image formats.

\begin{quote}
\hspace*{-0.25in}
void ListMagickInfo(FILE *file)
\end{quote}

ListMagickInfo() lists the image formats to a file.

A description of each parameter follows:

\begin{description}
\item[file] A file handle.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{RegisterMagickInfo()}
register a new image format.

\begin{quote}
\hspace*{-0.25in}
MagickInfo *RegisterMagickInfo(MagickInfo *entry)
\end{quote}

RegisterMagickInfo() adds attributes for a particular image format to the
list of supported formats.  The attributes include the image format tag,
a method to read and/or write the format,  whether the format supports the
saving of more than one frame to the same file or blob, whether the format
supports native in-memory I/O, and a brief description of the format.

A description of each parameter follows:

\begin{description}
\item[entry] The magick info.
\end{description}

\subsubsection{SetMagickInfo()}

\begin{quote}
\hspace*{-0.25in}
MagickInfo *SetMagickInfo(const char *tag)
\end{quote}

Method SetMagickInfo() allocates a MagickInfo structure and initializes
the members to default values.

A description of each parameter follows:

\begin{description}
\item[tag] a character string that represents the image format associated with the
MagickInfo structure.
\end{description}

\subsubsection{UnregisterMagickInfo()}

\begin{quote}
\hspace*{-0.25in}
unsigned int UnregisterMagickInfo(const char *tag)
\end{quote}

Method UnregisterMagickInfo() removes a tag from the magick info list.
It returns False if the tag does not exist in the list otherwise True.

A description of each parameter follows:

\begin{description}
\item[tag] a character string that represents the image format we are looking for.
\end{description}

\section{ImageMagick Error Methods}

\subsubsection{CatchImageException()}

\begin{quote}
\hspace*{-0.25in}
CatchImageException(Image *image)
\end{quote}

CatchImageException() returns if no exceptions are found in the image
sequence, otherwise it determines the most severe exception and reports
it as a warning or error depending on the severity.

A description of each parameter follows:

\begin{description}
\item[image] An image sequence.
\end{description}

\subsubsection{DestroyExceptionInfo()}
destroy exception info.

\begin{quote}
\hspace*{-0.25in}
void DestroyExceptionInfo(ExceptionInfo *exception)
\end{quote}

DestroyExceptionInfo() deallocates memory associated with \texttt{exception}.

A description of each parameter follows:

\begin{description}
\item[exception] The exception info.
\end{description}

\subsubsection{GetExceptionInfo}
get exception info.

\begin{quote}
\hspace*{-0.25in}
GetExceptionInfo(ExceptionInfo *exception)
\end{quote}

GetExceptionInfo() initializes \texttt{exception}  to default values.

A description of each parameter follows:

\begin{description}
\item[exception] The exception info.
\end{description}

\subsubsection{GetImageException()}
get the severest error.

\begin{quote}
\hspace*{-0.25in}
GetImageException(Image *image, ExceptionInfo *exception)
\end{quote}

GetImageException() traverses an image sequence and returns any error
more severe than noted by the exception parameter.

A description of each parameter follows:

\begin{description}
\item[image] An image sequence.
\item[exception] Return the highest severity exception in the seqeunce.
\end{description}

\subsubsection{MagickError()}
declare an error.

\begin{quote}
\hspace*{-0.25in}
void MagickError(const ExceptionType error, const char *reason, 
  const char *description)
\end{quote}

MagickError() calls the error handler method with an error reason.

A description of each parameter follows:

\begin{description}
\item[exception] The error severity.
\item[reason] Define the reason for the error.
\item[description] Describe the error.
\end{description}

\subsubsection{MagickWarning()}
declare a warning.

\begin{quote}
\hspace*{-0.25in}
void MagickWarning(const ExceptionType warning, const char *reason, 
  const char *description)
\end{quote}

MagickWarning() calls the warning handler method with a warning reason.

A description of each parameter follows:

\begin{description}
\item[warning] The warning severity.
\item[reason] Define the reason for the warning.
\item[description] Describe the warning.
\end{description}

\subsubsection{SetErrorHandler()}
set the warning handler.

\begin{quote}
\hspace*{-0.25in}
ErrorHandler SetErrorHandler(ErrorHandler handler)
\end{quote}

SetErrorHandler() sets the error handler to the specified method
and returns the previous error handler.

A description of each parameter follows:

\begin{description}
\item[handler] The method to handle errors.
\end{description}

\subsubsection{SetWarningHandler()}
set the warning handler.

\begin{quote}
\hspace*{-0.25in}
ErrorHandler SetWarningHandler(ErrorHandler handler)
\end{quote}

SetWarningHandler() sets the warning handler to the specified method
and returns the previous warning handler.

A description of each parameter follows:

\begin{description}
\item[handler] The method to handle warnings.
\end{description}

\subsubsection{ThrowException()}
throw an exception.

\begin{quote}
\hspace*{-0.25in}
void ThrowException(ExceptionInfo *exception, const ExceptionType severity,
  const char *reason,  const char *description)
\end{quote}

ThrowException() throws an exception with the specified severity code,
reason, and optional description.

A description of each parameter follows:

\begin{description}
\item[exception] The exception.
\item[severity] Define the severity of the exception.
\item[reason] Define the reason for the exception.
\item[description] Describe the exception.
\end{description}

\section{ImageMagick Memory Allocation Methods}

\subsubsection{AcquireMemory}
allocate memory.


\begin{quote}
\hspace*{-0.25in}
 void *AcquireMemory(const size\_t size)
\end{quote}

AcquireMemory() returns a pointer to a block of memory at least size
bytes suitably aligned for any use.

A description of each parameter follows:
\begin{description}
\item[size] The size of the memory in bytes to allocate.

\end{description}

\subsubsection{LiberateMemory}
free allocated memory.

\begin{quote}
\hspace*{-0.25in}
void LiberateMemory(void **memory)
\end{quote}

LiberateMemory() frees memory that has already been allocated.

A description of each parameter follows:
\begin{description}
\item[span] A pointer to a block memory to free for reuse.

\end{description}

\subsubsection{ReacquireMemory}
change the size of allocated memory.

\begin{quote}
\hspace*{-0.25in}
void ReacquireMemory(void **memory, const size\_t size)
\end{quote}

ReacquireMemory() changes the size of allocated memory and returns a
pointer to the (possibly moved) block.  The contents will be unchanged
up to the lesser of the new and old sizes.

A description of each parameter follows:

\begin{description}
\item[memory] A pointer to a memory allocation.  On return the pointer
may change but the contents of the original allocation will not.
\item[size] The new size of the allocated memory.
\end{description}

\section{ImageMagick Progress Monitor Methods}

\subsubsection{MagickMonitor}
measure progress toward completion of a task.


\begin{quote}
\hspace*{-0.25in}
MagickExport unsigned int MagickMonitor(const char *text,const off\_t quantum,
  const size\_t span,ExceptionInfo *exception)
\end{quote}

MagickMonitor() calls the monitor handler method with a text string that
describes the task and a measure of completion.
The method returns False on success otherwise
True if an error is encountered, e.g. if there was a user interrupt.

A description of each parameter follows:

\begin{description}
\item[quantum] The position relative to the span parameter which
represents how much progress has been made toward completing a task.
\item[span] The span relative to completing a task.
\item[exception] Return any errors or warnings in this structure.
\end{description}

\subsubsection{SetMonitorHandler}
define a custom progress monitor.

\begin{quote}
\hspace*{-0.25in}
MonitorHandler SetMonitorHandler(MonitorHandler handler)
\end{quote}

SetMonitorHandler() sets the monitor handler to the specified method
and returns the previous monitor handler.

A description of each parameter follows:

\begin{description}
\item[handler] The progress monitor handler method.
\end{description}

