NAME

image - ImageMagick Image Methods

SYNOPSIS

Image * AllocateImage( const ImageInfo *image_info );

unsigned int AllocateImageColormap( Image *image, const unsigned int colors );

void AllocateNextImage( const ImageInfo *image_info, Image *image );

unsigned int AnimateImages( const ImageInfo *image_info, Image *image );

Image * AppendImages( Image *image, const unsigned int stack, ExceptionInfo *exception );

Image * AverageImages( const Image *image, ExceptionInfo *exception );

unsigned int ChannelImage( Image *image, const ChannelType channel );

Image * CloneImage( Image *image, const unsigned int columns, const unsigned int rows, const unsigned int orphan, ExceptionInfo *exception );

ImageInfo * CloneImageInfo( const ImageInfo *image_info );

unsigned int CompositeImage( Image *image, const CompositeOperator compose, Image *composite_image, const int x_offset, const int y_offset );

CycleColormapImage( image, amount );

void DescribeImage( Image *image, FILE *file, const unsigned int verbose );

void DestroyImage( Image *image );

void DestroyImageInfo( ImageInfo *image_info );

void DestroyImages( Image *image );

unsigned int DisplayImages( const ImageInfo *image_info, Image *image );

RectangleInfo GetImageBoundingBox( Image *image );

unsigned int GetImageDepth( Image *image );

void GetImageInfo( ImageInfo *image_info );

ImageType GetImageType( Image *image );

Image * GetNextImage( Image *image );

unsigned int GetNumberScenes( const Image *image );

void GetPageInfo( RectangleInfo *page );

void GetPixelPacket( PixelPacket *pixel );

unsigned int IsGeometry( const char *geometry );

unsigned int IsImageTainted( const Image *image );

unsigned int IsImagesEqual( Image *image, Image *reference );

unsigned int IsSubimage( const char *geometry, const unsigned int pedantic );

Image ** ListToGroupImage( Image *image, unsigned int *number_images );

unsigned int MogrifyImage( const ImageInfo *image_info, const int argc, char ** argv, Image ** image );

unsigned int MogrifyImages( const ImageInfo *next_info, const int argc, char ** argv, Image ** image );

Image * MosaicImages( const Image *image, ExceptionInfo *exception );

int ParseImageGeometry( const char *geometry, int *x, int *y, unsigned int *width, unsigned int *height );

unsigned int RGBTransformImage( Image *image, const ColorspaceType colorspace );

void SetImage( Image *image, opacity );

unsigned int SetImageDepth( Image *image, const unsigned int );

unsigned int SetImageInfo( ImageInfo *image_info, const unsigned int rectify );

void SetImageOpacity( Image *image, const unsigned int opacity );

SetImageType( Image *image, const ImageType image_type );

void SyncImage( Image *image );

void TextureImage( Image *image, Image *texture );

unsigned int TransformRGBImage( Image *image, const ColorspaceType colorspace );

unsigned int TransmitImage( Image *image, ImageInfo *image_info, const TransmitType sendmode, void *param1, void *param2 );

FUNCTION DESCRIPTIONS

AllocateImage

Method AllocateImage allocates an Image structure and initializes each field to a default value.

The format of the AllocateImage method is:

Image *AllocateImage ( const ImageInfo *image_info );

A description of each parameter follows:

allocate_image:
Method AllocateImage returns a pointer to an image structure initialized to default values. A null image is returned if there is a memory shortage.

image_info:
Specifies a pointer to an ImageInfo structure.

AllocateImageColormap

Method AllocateImageColormap allocates an Image colormap and initializes it. The minimum number of colormap cells allocated is 256.

The format of the AllocateImageColormap method is:

unsigned int AllocateImageColormap ( Image *image, const unsigned int colors );

A description of each parameter follows:

status:
Method AllocateImageColormap returns True if the colormap is successfully allocated and initialized, otherwise False.

image:
The address of a structure of type Image.

colors:
The number of colors in the image colormap.

AllocateNextImage

Method AllocateNextImage allocates an Image structure and initializes each field to a default value.

The format of the AllocateNextImage method is:

void AllocateNextImage ( const ImageInfo *image_info, Image *image );

A description of each parameter follows:

image_info:
Specifies a pointer to an ImageInfo structure.

image:
The address of a structure of type Image.

AnimateImages

Method AnimateImages displays one or more images to an X window.

The format of the AnimateImages method is:

unsigned int AnimateImages ( const ImageInfo *image_info, Image *image );

A description of each parameter follows:

status:
Method AnimateImages returns True if the images are displayed in an X window, otherwise False is returned.

image_info:
Specifies a pointer to an ImageInfo structure.

image:
The address of a structure of type Image.

AppendImages

Method AppendImages appends a sequence of images. All the input images must have the same width or height. Images of the same width are stacked top-to-bottom. Images of the same height are stacked left-to-right. If stack is false, rectangular images are stacked left-to-right otherwise top-to-bottom.

The format of the AppendImage method is:

Image *AppendImages ( Image *image, const unsigned int stack, ExceptionInfo *exception );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

stack:
An unsigned value other than stacks rectangular image top-to-bottom otherwise left-to-right.

exception:
return any errors or warnings in this structure.

AverageImages

Method AverageImages averages a sequence of images. All the input image must be the same size in pixels.

The format of the AverageImage method is:

Image *AverageImages ( const Image *image, ExceptionInfo *exception );

A description of each parameter follows:

average_image:
Method AverageImages returns the mean pixel value for an image sequence.

image:
The address of a structure of type Image; returned from ReadImage.

exception:
return any errors or warnings in this structure.

ChannelImage

Method ChannelImage extracts the specified channel from the referenced image.

The format of the ChannelImage method is:

unsigned int ChannelImage ( Image *image, const ChannelType channel );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

channel:
A value of type ChannelType that identifies which channel to extract.

CloneImage

Method CloneImage clones an image. 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 SetImagePixels() and SyncImagePixels() methods.

The format of the CloneImage method is:

Image *CloneImage ( Image *image, const unsigned int columns, const unsigned int rows, const unsigned int orphan, ExceptionInfo *exception );

A description of each parameter follows:

clone_image:
Method CloneImage returns a pointer to the image after copying. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image.

columns:
An integer that specifies the number of columns in the copied image.

rows:
An integer that specifies the number of rows in the copied image.

orphan:
if true, consider this image an orphan.

exception:
return any errors or warnings in this structure.

CloneImageInfo

Method CloneImageInfo makes a duplicate of the given image info, or if image info is NULL, a new one.

The format of the CloneImageInfo method is:

ImageInfo *CloneImageInfo ( const ImageInfo *image_info );

A description of each parameter follows:

clone_info:
Method CloneImageInfo returns a duplicate of the given image info, or if image info is NULL a new one.

image_info:
Specifies a pointer to an ImageInfo structure.

CompositeImage

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

The format of the CompositeImage method is:

unsigned int CompositeImage ( Image *image, const CompositeOperator compose, Image *composite_image, const int x_offset, const int y_offset );

A description of each parameter follows:

image:
The address of a structure of type Image.

compose:
Specifies an image composite operator.

composite_image:
The address of a structure of type Image.

x_offset:
An integer that specifies the column offset of the composited image.

y_offset:
An integer that specifies the row offset of the composited image.

CycleColormapImage

Method CycleColormapImage cycles the image colormap by a specified amount.

The format of the CycleColormapImage method is:

CycleColormapImage ( image, amount );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

amount:
An unsigned value that specifies the offset of the colormap.

DescribeImage

Method DescribeImage describes an image by printing its attributes to stdout.

The format of the DescribeImage method is:

void DescribeImage ( Image *image, FILE *file, const unsigned int verbose );

A description of each parameter follows:

image:
The address of a structure of type Image.

file:
send the image attributes to this file.

verbose:
an unsigned value other than zero prints detailed information about the image.

DestroyImage

Method DestroyImage deallocates memory associated with an image.

The format of the DestroyImage method is:

void DestroyImage ( Image *image );

A description of each parameter follows:

image:
The address of a structure of type Image.

DestroyImageInfo

Method DestroyImageInfo deallocates memory associated with an ImageInfo structure.

The format of the DestroyImageInfo method is:

void DestroyImageInfo ( ImageInfo *image_info );

A description of each parameter follows:

image_info:
Specifies a pointer to an ImageInfo structure.

DestroyImages

Method DestroyImages deallocates memory associated with a linked list of images.

The format of the DestroyImages method is:

void DestroyImages ( Image *image );

A description of each parameter follows:

image:
The address of a structure of type Image.

DisplayImages

Method DisplayImages displays one or more images to an X window.

The format of the AllocateNextImage method is:

unsigned int DisplayImages ( const ImageInfo *image_info, Image *image );

A description of each parameter follows:

status:
Method DisplayImages returns True if the images are displayed in an X window, otherwise False is returned.

image_info:
Specifies a pointer to an ImageInfo structure.

image:
The address of a structure of type Image.

GetImageBoundingBox

Method GetImageBoundingBox returns the bounding box of an image canvas.

The format of the GetImageBoundingBox method is:

RectangleInfo GetImageBoundingBox ( Image *image );

A description of each parameter follows:

bounds:
Method GetImageBoundingBox returns the bounding box of an image canvas.

image:
The address of a structure of type Image.

GetImageDepth

Method GetImageDepth returns the depth of the image.

The format of the GetImageDepth method is:

unsigned int GetImageDepth ( Image *image );

A description of each parameter follows:

depth:
Method GetImageDepth returns the depth of the image.

image:
The address of a structure of type Image.

GetImageInfo

Method GetImageInfo initializes the ImageInfo structure.

The format of the GetImageInfo method is:

void GetImageInfo ( ImageInfo *image_info );

A description of each parameter follows:

image_info:
Specifies a pointer to an ImageInfo structure.

GetImageType

Method GetImageType returns the type of image (e.g. bilevel, palette, etc).

The format of the GetImageType method is:

ImageType GetImageType ( Image *image );

A description of each parameter follows:

type:
Method GetImageType returns a ImageType enum that specifies the type of the specified image (e.g. bilevel, palette, etc).

image:
The address of a structure of type Image.

GetNextImage

Method GetNextImage returns the next image in an image sequence.

The format of the GetNextImage method is:

Image *GetNextImage ( Image *image );

A description of each parameter follows:

next:
Method GetNextImage returns the next image in an image sequence.

image:
The address of a structure of type Image.

GetNumberScenes

Method GetNumberScenes returns the number of scenes in an image sequence.

The format of the GetNumberScenes method is:

unsigned int GetNumberScenes ( const Image *image );

A description of each parameter follows:

scenes:
Method GetNumberScenes returns the number of scenes in an image sequence.

image:
The address of a structure of type Image.

GetPageInfo

Method GetPageInfo initializes the image page structure.

The format of the GetPageInfo method is:

void GetPageInfo ( RectangleInfo *page );

A description of each parameter follows:

page:
Specifies a pointer to a RectangleInfo structure.

GetPixelPacket

Method GetPixelPacket initializes the PixelPacket structure.

The format of the GetPixelPacket method is:

void GetPixelPacket ( PixelPacket *pixel );

A description of each parameter follows:

pixel:
Specifies a pointer to a PixelPacket structure.

IsGeometry

Method IsGeometry returns True if the geometry specification is valid as determined by ParseGeometry.

The format of the IsGeometry method is:

unsigned int IsGeometry ( const char *geometry );

A description of each parameter follows:

status:
Method IsGeometry returns True if the geometry specification is valid otherwise False is returned.

geometry:
This string is the geometry specification.

IsImagesEqual

Method IsImagesEqual measures the difference between two images. The error 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. These values are computed:

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

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.

normalized_maximum_square_error:
Thsi 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.

The format of the IsImagesEqual method is:

unsigned int IsImagesEqual ( Image *image, Image *reference );

A description of each parameter follows.

image:
Specifies a pointer to an Image structure.

reference:
Specifies a pointer to an Image structure.

IsImageTainted

Method IsImageTainted returns True if the image has been altered since it was first read or if any image in the sequence has a difference magic or filename.

The format of the IsImageTainted method is:

unsigned int IsImageTainted ( const Image *image );

A description of each parameter follows:

status:
Method IsImageTainted returns True if the image has been altered since it was first read.

image:
The address of a structure of type Image.

IsSubimage

Method IsSubimage returns True if the geometry is a valid subimage specification (e.g. [1], [1-9], [1,7,4]).

The format of the IsSubimage method is:

unsigned int IsSubimage ( const char *geometry, const unsigned int pedantic );

A description of each parameter follows:

status:
Method IsSubimage returns True if the geometry is a valid subimage specification otherwise False is returned.

geometry:
This string is the geometry specification.

pedantic:
A value other than 0 invokes a more restriction set of conditions for a valid specification (e.g. [1], [1-4], [4-1]).

ListToGroupImage

Method ListToGroupImage converts a linked list of images to a sequential array.

The format of the ListToGroupImage method is:

Image **ListToGroupImage ( Image *image, unsigned int *number_images );

A description of each parameter follows:

images:
Method ListToGroupImage converts a linked list of images to a sequential array and returns the array..

images:
The address of a structure of type Image; returned from ReadImage.

number_images:
A pointer to an unsigned integer. The number of images in the image array is returned here.

MogrifyImage

Method MogrifyImage applies image processing options to an image as prescribed by command line options.

The format of the MogrifyImage method is:

unsigned int MogrifyImage ( const ImageInfo *image_info, const int argc, char **argv, Image **image );

A description of each parameter follows:

image_info:
Specifies a pointer to an ImageInfo structure.

argc:
Specifies a pointer to an integer describing the number of elements in the argument vector.

argv:
Specifies a pointer to a text array containing the command line arguments.

image:
The address of a structure of type Image; returned from ReadImage.

MogrifyImages

Method MogrifyImages applies next processing options to a sequence of images as prescribed by command line options.

The format of the MogrifyImage method is:

unsigned int MogrifyImages ( const ImageInfo *next_info, const int argc, char **argv, Image **image );

A description of each parameter follows:

next_info:
Specifies a pointer to an ImageInfo structure.

argc:
Specifies a pointer to an integer describing the number of elements in the argument vector.

argv:
Specifies a pointer to a text array containing the command line arguments.

image:
The address of a structure of type Image; returned from ReadImage.

MosaicImages

Method MosaicImages inlays a number of image to form a single coherent picture.

The format of the MosaicImage method is:

Image *MosaicImages ( const Image *image, ExceptionInfo *exception );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

exception:
return any errors or warnings in this structure.

ParseImageGeometry

Method ParseImageGeometry parses a geometry specification and returns the width, height, x, and y values. It also returns flags that indicates which of the four values (width, height, xoffset, yoffset) were located in the string, and whether the x and y values are negative. In addition,

The format of the ParseImageGeometry method is:

int ParseImageGeometry ( const char *geometry, int *x, int *y, unsigned int *width, unsigned int *height );

A description of each parameter follows:

flags:
Method ParseImageGeometry returns a bitmask that indicates which of the four values were located in the geometry string.

image_geometry:
Specifies a character string representing the geometry specification.

x,y:
A pointer to an integer. The x and y offset as determined by the geometry specification is returned here.

width,height:
A pointer to an unsigned integer. The width and height as determined by the geometry specification is returned here.

RGBTransformImage

Method RGBTransformImage converts the reference image from RGB to an alternate colorspace. The transformation matrices are not the standard ones: the weights are rescaled to normalized the range of the transformed values to be [0..MaxRGB].

The format of the RGBTransformImage method is:

unsigned int RGBTransformImage ( Image *image, const ColorspaceType colorspace );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

colorspace:
An unsigned integer value that indicates which colorspace to transform the image.

SetImage

Method SetImage initializes the reference image to the background color.

The format of the SetImage method is:

void SetImage ( Image *image, opacity );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

opacity:
The transparency of the background color.

SetImageDepth

Method SetImageDepth sets the depth of the image.

The format of the SetImageDepth method is:

unsigned int SetImageDepth ( Image *image, const unsigned int );

A description of each parameter follows:

status:
Method SetImageDepth returns True if the image depth is set.

image:
The address of a structure of type Image.

depth:
specified the image depth.

SetImageInfo

Method SetImageInfo initializes the `magick' field of the ImageInfo structure. It is set to a type of image format based on the prefix or suffix of the filename. For example, `ps:image' returns PS indicating a Postscript image. JPEG is returned for this filename: `image.jpg'. The filename prefix has precendence over the suffix. Use an optional index enclosed in brackets after a file name to specify a desired subimage of a multi-resolution image format like Photo CD (e.g. img0001.pcd[4]).

The format of the SetImageInfo method is:

unsigned int SetImageInfo ( ImageInfo *image_info, const unsigned int rectify );

A description of each parameter follows:

image_info:
Specifies a pointer to an ImageInfo structure.

rectify:
an unsigned value other than zero rectifies the attribute for multi-frame support (user may want multi-frame but image format may not support it).

SetImageOpacity

Method SetImageOpacity initializes the opacity channel of the reference image to the specified value. If the image already has a matte channel it is attenuated with the opacity value.

The format of the SetImageOpacity method is:

void SetImageOpacity ( Image *image, const unsigned int opacity );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

opacity:
The level of transparency.

SetImageType

Method SetImageType sets the type of the image.

The format of the SetImageType method is:

SetImageType ( Image *image, const ImageType image_type );

A description of each parameter follows:

status:
Method SetImageDepth returns True if the image depth is set.

image:
The address of a structure of type Image.

image_type:
specified the image type.

SortColormapByIntentsity

Method SortColormapByIntensity sorts the colormap of a PseudoClass image by decreasing color intensity.

The format of the SortColormapByIntensity method is:

    unsigned int SortColormapByIntensity(Image *image)

A description of each parameter follows:

image:
A pointer to a Image structure.

SyncImage

Method SyncImage initializes the red, green, and blue intensities of each pixel as defined by the colormap index.

The format of the SyncImage method is:

void SyncImage ( Image *image );

A description of each parameter follows:

image:
The address of a structure of type Image.

TextureImage

Method TextureImage layers a texture onto the background of an image.

The format of the TextureImage method is:

void TextureImage ( Image *image, Image *texture );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

texture:
This image contains the texture to layer on the background.

TransformRGBImage

Method TransformRGBImage converts the reference image from an alternate colorspace. The transformation matrices are not the standard ones: the weights are rescaled to normalize the range of the transformed values to be [0..MaxRGB].

The format of the TransformRGBImage method is:

unsigned int TransformRGBImage ( Image *image, const ColorspaceType colorspace );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

colorspace:
An unsigned integer value defines which colorspace to transform the image to.

TransmitImage

Method TransmitImage transmit an image to a variety of destinations. It is used primarily in CGI and ISAPI programs to send an image to a client using either disk, blobs, streaming, or via the normal in memory image structure.

The format of the TransmitImage method is:

unsigned int TransmitImage ( Image *image, ImageInfo *image_info, const TransmitType sendmode, void *param1, void *param2 );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

image_info:
Specifies a pointer to an ImageInfo structure.

sendmode:
An unsigned integer value defines which transmit mode to send the image with.

param1:
An void pointer whose meaning depends on the transmit mode.

param2:
An void pointer whose meaning depends on the transmit mode.