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 *image, const int 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 );

unsigned int GetImageDepth( Image *image );

void GetImageInfo( ImageInfo *image_info );

ImageType GetImageType( Image *image );

Image * GetNextImage( Image *image );

unsigned int GetNumberScenes( const Image *image );

unsigned int IsImageTainted( const Image *image );

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

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

Image * ModifyImage( Image *image );

Image * ReferenceImage( Image *image );

void SetImage( Image *image, const Quantum opacity );

unsigned int SetImageClipMask( Image *image, Image *clip_mask );

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

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

SetImageType( Image *image, const ImageType image_type );

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

FUNCTION DESCRIPTIONS

AllocateImage

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

The format of the AllocateImage method is:

Image *AllocateImage ( const ImageInfo *image_info );

A description of each parameter follows:

image_info:
Many of the image default values are set from this structure. For example, filename, compression, depth, background color, and others.

AllocateImageColormap

AllocateImageColormap ( ) allocates an image colormap and initializesit 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.;

The format of the AllocateImageColormap method is:

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

A description of each parameter follows:

image:
The image.

colors:
The number of colors in the image colormap.

AllocateNextImage

Use AllocateNextImage ( ) to initialize the next image in a sequence. Thenext member of image points to the newly allocated image. If there is amemory shortage, next is assigned NULL.;

The format of the AllocateNextImage method is:

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

A description of each parameter follows:

image_info:
Many of the image default values are set from this structure. For example, filename, compression, depth, background color, and others.

image:
The image.

AnimateImages

AnimateImages ( ) repeatedly displays an image sequence to any X windowscreen. It returns a value other than 0 if successful. Check theexception member of image to determine the reason for any failure.;

The format of the AnimateImages method is:

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

A description of each parameter follows:

image_info:
The image info.

image:
The image.

AppendImages

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

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 image sequence.

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

The Average() method takes a set of images and averages them together. Each image in the set must have the same width and the same height. Average() returns a single image with each corresponding pixel component of each image averaged. On failure, a NULL image is returned and exception describes the reason for the failure.

The format of the AverageImage method is:

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

A description of each parameter follows:

image:
The image sequence.

exception:
Return any errors or warnings in this structure.

ChannelImage

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

The format of the ChannelImage method is:

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

A description of each parameter follows:

image:
The image.

channel:
A value of type ChannelType that identifies which channel to extract: Red, Green, Blue, or Opacity.

CloneImage

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 isreturned, otherwise the pixel data is undefined and must be initializedwith the SetImagePixels ( ) and SyncImagePixels ( ) methods. A NULL imageis returned if the image cannot be cloned; check exception for the reasonwhy.;

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:

image:
The image.

columns:
The number of columns in the copied

rows:
The number of rows in the copied image.

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 next and previous members of the cloned image is set to NULL.

exception:
Return any errors or warnings in this structure.

CloneImageInfo

CloneImageInfo ( ) makes a copy of the given image info structure. IfNULL is specified, a new image info structure is created initialized todefault values.;

The format of the CloneImageInfo method is:

ImageInfo *CloneImageInfo ( const ImageInfo *image_info );

A description of each parameter follows:

image_info:
The image info.

CompositeImage

CompositeImage ( ) returns the second image composited onto the first at thespecified 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 image.

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

      OverCompositeOp       InCompositeOp         OutCompositeOP
      AtopCompositeOP       XorCompositeOP        PlusCompositeOP
      MinusCompositeOP      AddCompositeOP        SubtractCompositeOP
      DifferenceCompositeOP BumpmapCompositeOP    CopyCompositeOP
      DisplaceCompositeOP
=over 4

composite_image:
The composite image.

x_offset:
The column offset of the composited image.

y_offset:
The row offset of the composited image.

CycleColormapImage

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.

The format of the CycleColormapImage method is:

CycleColormapImage ( Image *image, const int amount );

A description of each parameter follows:

image:
The image.

amount:
Offset of the colormap this much.

DescribeImage

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

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 image.

file:
The file, typically stdout.

verbose:
A value other than zero prints more detailed information about the image.

DestroyImage

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

The format of the DestroyImage method is:

void DestroyImage ( Image *image );

A description of each parameter follows:

image:
The image.

DestroyImageInfo

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:
The image info.

DestroyImages

DestroyImages ( ) deallocates memory associated with all the images in asequence.;

The format of the DestroyImages method is:

void DestroyImages ( Image *image );

A description of each parameter follows:

image:
The image sequence.

DisplayImages

DisplayImages ( ) displays an image sequence to any X windowscreen. It returns a value other than 0 if successful. Check theexception member of image to determine the reason for any failure.;

The format of the AllocateNextImage method is:

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

A description of each parameter follows:

image_info:
The image info.

image:
The image.

GetImageDepth

GetImageDepth ( ) returns the depth of the image, either 8 or 16 bits. Bydefault, pixels components are stored as 16-bit two byte unsigned shortintegers that range in value from 0 to 65535. However, if all the pixelshave lower-order bytes of zero, the image is considered to have a depth of8-bit.;

The format of the GetImageDepth method is:

unsigned int GetImageDepth ( Image *image );

A description of each parameter follows:

image:
The image.

GetImageInfo

GetImageInfo ( ) initializes the ImageInfo structure to default values.;

The format of the GetImageInfo method is:

void GetImageInfo ( ImageInfo *image_info );

A description of each parameter follows:

image_info:
The image info.

GetImageType

GetImageType ( ) returns the type of image:; 
      Bilevel        Grayscale       GrayscaleMatte
      Palette        PaletteMatte    TrueColor
      TrueColorMatte ColorSeparation ColorSeparationMatte

The format of the GetImageType method is:

ImageType GetImageType ( Image *image );

A description of each parameter follows:

image:
The image.

GetNextImage

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:

image:
The image.

GetNumberScenes

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

The format of the GetNumberScenes method is:

unsigned int GetNumberScenes ( const Image *image );

A description of each parameter follows:

image:
The image.

IsImagesEqual

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

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

normalized_mean_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_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.

A small normalized mean square error, accessed as image->normalized_mean_error, suggests the images are very similiar in spatial layout and color.

The format of the IsImagesEqual method is:

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

A description of each parameter follows.

image:
The image.

reference:
The reference image.

IsImageTainted

IsImageTainted ( ) returns a value other than 0 if any pixel in an imagehas been altered since it was first constituted.;

The format of the IsImageTainted method is:

unsigned int IsImageTainted ( const Image *image );

A description of each parameter follows:

image:
The image.

ListToGroupImage

ListToGroupImage ( ) is a convenience method that converts a linked list ofimages to a sequential array. For example, ;
images = ListToGroupImage ( image_list, \&n ); for ( i=0; i < n; i++ ) puts ( images[i]->filename ) ;;

The format of the ListToGroupImage method is:

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

A description of each parameter follows:

image:
The image list.

number_images:
The length of the image array is returned here.

ModifyImage

ModifyImage ( ) ensures that there is only a single reference to the imageto be modified, updating the provided image pointer to point to a clone ofthe original image if necessary.;

The format of the ModifyImage method is:

Image *ModifyImage ( Image *image );

A description of each parameter follows:

image:
The image.

ReferenceImage

ReferenceImage ( ) increments the reference count associated with an imagereturning a pointer to the image.;

The format of the ReferenceImage method is:

Image *ReferenceImage ( Image *image );

A description of each parameter follows:

image:
The image.

SetImage

SetImage ( ) sets the red, green, and blue components of each pixel tothe image background color and the opacity component to the specifiedlevel of transparency. The background color is defined by thebackground_color member of the image.;

The format of the SetImage method is:

void SetImage ( Image *image, const Quantum opacity );

A description of each parameter follows:

image:
The image.

opacity:
Set each pixel to this level of transparency.

SetImageClipMask

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

The format of the SetImageClipMask method is:

unsigned int SetImageClipMask ( Image *image, Image *clip_mask );

A description of each parameter follows:

image:
The image.

clip_mask:
The image clip mask.

SetImageDepth

SetImageDepth ( ) sets the depth of the image, either 8 or 16. Some imageformats support both 8 and 16-bits per color component ( e.g. PNG ) . UseSetImageDepth ( ) to specify your preference. A value other than 0 isreturned if the depth is set.;

The format of the SetImageDepth method is:

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

A description of each parameter follows:

image:
The image.

depth:
The image depth.

SetImageOpacity

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

The format of the SetImageOpacity method is:

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

A description of each parameter follows:

image:
The image.

opacity:
The level of transparency: 0 is fully opaque and MaxRGB is fully transparent.

SetImageType

SetImageType ( ) sets the type of image. Choose from these types:; 
      Bilevel        Grayscale       GrayscaleMatte
      Palette        PaletteMatte    TrueColor
      TrueColorMatte ColorSeparation ColorSeparationMatte

The format of the SetImageType method is:

SetImageType ( Image *image, const ImageType image_type );

A description of each parameter follows:

image:
The image.

image_type:
Image type.

TextureImage

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

The format of the TextureImage method is:

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

A description of each parameter follows:

image:
The image.

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