- NAME
- SYNOPSIS
- FUNCTION DESCRIPTIONS
  - AllocateImage
  - AllocateImageColormap
  - AllocateNextImage
  - AnimateImages
  - AppendImages
  - AverageImages
  - ChannelImage
  - ClipImage
  - CloneImage
  - CloneImageInfo
  - CompositeImage
  - CycleColormapImage
  - DescribeImage
  - DestroyImage
  - DestroyImageInfo
  - DisplayImages
  - GetImageDepth
  - GetImageGeometry
  - GetImageInfo
  - GetImageType
  - IsImagesEqual
  - IsTaintImage
  - ModifyImage
  - ReferenceImage
  - SetImage
  - SetImageClipMask
  - SetImageDepth
  - SetImageOpacity
  - SetImageType
  - TextureImage

# NAME

image - ImageMagick Image Methods

# SYNOPSIS

Image * AllocateImage( const ImageInfo *image_info );

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

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

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

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

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

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

unsigned int ClipImage( Image *image );

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

ImageInfo * CloneImageInfo( const ImageInfo *image_info );

unsigned int CompositeImage( Image *image, const CompositeOperator compose, const Image *composite_image, const long x_offset, const long 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 );

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

unsigned long GetImageDepth( const Image *image, ExceptionInfo *exception );

int GetImageGeometry( const Image *image, const char *geometry, const unsigned int size_to_fit, RectangeInfo *region_info );

void GetImageInfo( ImageInfo *image_info );

ImageType GetImageType( const Image *image, ExceptionInfo *exception );

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

unsigned int IsTaintImage( const Image *image );

ModifyImage( Image *image, ExceptionInfo *exception );

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 long depth );

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

SetImageType( Image *image, const ImageType image_type );

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

# FUNCTION DESCRIPTIONS

## AllocateImage

> AllocateImage() returns a pointer to an image structure initialized to default 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 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.

The format of the AllocateImageColormap method is:

> unsigned int AllocateImageColormap ( Image *image, const unsigned long 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 to default values. The next member of image points to the newly allocated image. If there is a memory 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 window screen. It returns a value other than 0 if successful. Check the exception 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 AppendImages() method takes a set of images and appends them to each other top-to-bottom if the stack parameter is true, otherwise left-to-right.

The format of the AppendImage method is:

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

A description of each parameter follows:

  image:
    The image sequence.

  stack:
    A value other than 0 stacks the images top-to-bottom.

  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 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 ( 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:
    Identify which channel to extract: Red, Cyan, Green, Magenta, Blue, Yellow, or Opacity.

## ClipImage

> ClipImage() sets the image clip mask based any clipping path information if it exists.

The format of the ClipImage method is:

> unsigned int ClipImage ( Image *image );

A description of each parameter follows:

  image:
    The image.

## 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 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 exception describes the reason for the failure.

The format of the CloneImage method is:

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

A description of each parameter follows:

  image:
    The image.

  columns:
    The number of columns in the cloned image.

  rows:
    The number of rows in the cloned 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. If NULL is specified, a new image info structure is created initialized to default 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 the specified offsets.

The format of the CompositeImage method is:

> unsigned int CompositeImage ( Image *image, const CompositeOperator compose, const Image *composite_image, const long x_offset, const long 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 the colormap this much.

## DescribeImage

> DescribeImage() describes an image by printing its attributes to the file. 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 with the 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.

## DisplayImages

> DisplayImages() displays an image sequence to any X window screen. It returns a value other than 0 if successful. Check the exception 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. By default, pixels 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.

The format of the GetImageDepth method is:

> unsigned long GetImageDepth ( const Image *image, ExceptionInfo *exception );

A description of each parameter follows:

  image:
    The image.

  exception:
    Return any errors or warnings in this structure.

## GetImageGeometry

> GetImageGeometry() returns a region as defined by the geometry string with respect to the image and its gravity.

The format of the GetImageGeometry method is:

> int GetImageGeometry ( const Image *image, const char *geometry, const unsigned int size_to_fit, RectangeInfo *region_info );

A description of each parameter follows:

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

  geometry:
    The geometry (e.g. 100x100+10+10).

  size_to_fit:
    A value other than 0 means to scale the region so it fits within the specified width and height.

  region_info:
    The region as defined by the geometry string with respect to the image and its gravity.

## GetImageInfo

> GetImageInfo() initializes image_info 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 ( const Image *image, ExceptionInfo *exception );

A description of each parameter follows:

  image:
    The image.

  exception:
    Return any errors or warnings in this structure.

## IsImagesEqual

> 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:

  mean_error_per_pixel:
    The mean error for any single pixel in the image.

  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.

  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.

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.

## IsTaintImage

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

The format of the IsTaintImage method is:

> unsigned int IsTaintImage ( const Image *image );

A description of each parameter follows:

  image:
    The image.

## ModifyImage

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

The format of the ModifyImage method is:

> ModifyImage ( Image *image, ExceptionInfo *exception );

A description of each parameter follows:

  image:
    The image.

  exception:
    Return any errors or warnings in this structure.

## ReferenceImage

> ReferenceImage() increments the reference count associated with an image returning 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 to the image background color and the opacity component to the specified level of transparency. The background color is defined by the background_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 mask must be the same dimensions as the image. Set any pixel component of the clip mask to TransparentOpacity to prevent that corresponding image pixel component from being updated when SyncImagePixels ( ) is applied.

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 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 exception member of image to determine the cause for any failure.

The format of the SetImageDepth method is:

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

A description of each parameter follows:

  image:
    The image.

  depth:
    The image depth.

## SetImageOpacity

> 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 oapcity values are blended with the supplied transparency 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
          OptimizeType

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

The format of the TextureImage method is:

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

A description of each parameter follows:

  image:
    The image.

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