0image - ImageMagick Image Methods9/


NAME



!image - ImageMagick Image Methods




(

SYNOPSIS



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

QImage * AppendImages( Image *images, const unsigned int stack );

KImage * AverageImages( const Image *images );

mImage * CloneImage( Image *image, const unsigned int columns, const unsigned int rows, constunsigned int orphan );

XImageInfo * CloneImageInfo( const ImageInfo *image_info );

Wvoid CommentImage( Image *image, const char *comments );

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

kImage * CreateImage( const unsigned int width, const unsigned int height, const char *map,:const StorageType type, const void *pixels );

5CycleColormapImage( image, amount );

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

Avoid DestroyImage( Image *image );

Nvoid DestroyImageInfo( ImageInfo *image_info );

Bvoid DestroyImages( Image *image );

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

Jvoid GetImageInfo( ImageInfo *image_info );

FImageType GetImageType( Image *image );

CImage * GetNextImage( Image *image );

Runsigned int GetNumberScenes( const Image *image );

Lvoid GetPageInfo( RectangleInfo *page_info );

Ivoid GetPixelPacket( PixelPacket *pixel );

kvoid GetPixels( Image *image, const int x, const int y, const unsigned int columns, const@unsigned int rows, const char *map, const StorageType type, void*pixels );

Ounsigned int IsGeometry( const char *geometry );

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

Lunsigned int IsTainted( const Image *image );

Rvoid LabelImage( Image *image, const char *label );

Ivoid LayerImage( Image *image, const LayerType layer );

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

Cvoid MatteImage( Image *image, Quantum opacity );

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

ivoid MogrifyImages( const ImageInfo *image_info, const int argc, char ** argv, Image ** images );

JImage * MosaicImages( const Image *images );

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

OImage * PingImage( const ImageInfo *image_info );

Zvoid RGBTransformImage( Image *image, const ColorspaceType colorspace );

IImage * ReadImage( ImageInfo *image_info );

JImage * ReadImages( ImageInfo *image_info );

=void SetImage( Image *image );

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

>void SyncImage( Image *image );

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

Zvoid TransformRGBImage( Image *image, const ColorspaceType colorspace );

Xvoid TransparentImage( Image *image, const char *color );

dunsigned int WriteImage( const ImageInfo *image_info, Image *image );




B

FUNCTION DESCRIPTIONS






2

AnimateImages



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

8

status:


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






0

AppendImages



KMethod AppendImages appends a set of images. All the input images must have>the same width or height. Images of the same width are stackedFtop-to-bottom. Images of the same height are stacked left-to-right. IfFstack is false, rectangular images are stacked left-to-right otherwisetop-to-bottom.

(The format of the AppendImage method is:

Image *AppendImages ( Image *images, const unsigned int stack );


=A description of each parameter follows:

#

images:


BThe address of a structure of type Image; returned from ReadImage."

stack:


DAn unsigned value other than stacks rectangular images top-to-bottomotherwise left-to-right.






2

AverageImages



KMethod AverageImages averages a set of images. All the input images must bethe same size in pixels.

)The format of the AverageImage method is:

Image *AverageImages ( const Image *images );


=A description of each parameter follows:

+

averaged_image:


HMethod AverageImages returns the mean pixel value for an image sequence.#

images:


BThe address of a structure of type Image; returned from ReadImage.






,

CloneImage



FMethod CloneImage returns a copy of all fields of the input image. TheHimage pixels are copied only if the columns and rows of the cloned imageare the same as the original.

'The format of the CloneImage method is:

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


=A description of each parameter follows:

(

clone_image:


@Method CloneImage returns a pointer to the image after copying. BA null image is returned if there is a memory shortage."

image:


)The address of a structure of type Image.$

columns:


DAn integer that specifies the number of columns in the copied image.!

rows:


AAn integer that specifies the number of rows in the copied image.#

orphan:


'if true, consider this image an orphan.






4

CloneImageInfo



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


WMethod CloneImageInfo returns a duplicate of the given image info, or if image info is $NULL a new one.'

image_info:


a structure of type info.






0

CommentImage



HMethod CommentImage initializes an image comment. Optionally the commentGcan include the image filename, type, width, height, or scene number by$embedding special format characters.

)The format of the CommentImage method is:r

void CommentImage ( Image *image, const char *comments );


=A description of each parameter follows:

"

image:


)The address of a structure of type Image.%

comments:


@The address of a character string containing the comment format.






4

CompositeImage



KMethod CompositeImage returns the second image composited onto the first atthe specified offsets.

+The format of the CompositeImage method is:

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


DAn integer that specifies the column offset of the composited image.%

y_offset:


AAn integer that specifies the row offset of the composited image.






.

CreateImage



JMethod CreateImage is a convenience routine that creates an image from theKpixel data you supply and returns it. It allocates the memory necessary forIthe new Image structure and returns a pointer to the new image. The pixelHdata must be in scanline order top-to-bottom. The data can be character,Ishort int, integer, float, or double. Float and double require the pixelsIto be normalized [0..1]. The other types are [0..MaxRGB]. For example, toGcreate a 640x480 image from unsigned red-green-blue character data, useL

image=CreateImage ( 640, 480, "RGB", 0, pixels );;


(The format of the CreateImage method is:

Image *CreateImage ( const unsigned int width, const unsigned int height, const char *map, const StorageType type, const void *pixels );


=A description of each parameter follows:

"

image:


3Method CreateImage returns a pointer to the image. KA null image is returned if there is a memory shortageor if the image cannot be read."

width:


+Specifies the width in pixels of the image.#

height:


,Specifies the height in pixels of the image.

map:


9This character string can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, !Y = yellow, &M = magenta, and jK = black. The ordering reflects the order of the pixels in the supplied pixel array.!

type:


Jpixel type where 0 = unsigned char, 1 = short int, 2 = int, 3 = float, andG4 = double. Float and double types are expected to be normalized [0..1]otherwise [0..MaxRGB].#

pixels:


KThis array of values contain the pixel components as defined by the map andJtype parameters. The length of the arrays must equal the area specified by0the width and height values and type parameters.






<

CycleColormapImage



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


BThe address of a structure of type Image; returned from ReadImage.#

amount:


<An unsigned value that specifies the offset of the colormap.






2

DescribeImage



EMethod DescribeImage describes an image by printing its attributes tostdout.

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


Gan unsigned value other than zero prints detailed information about theimage.






0

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.






8

DestroyImageInfo



GMethod DestroyImageInfo deallocates memory associated with an ImageInfo structure.

-The format of the DestroyImageInfo method is:m

void DestroyImageInfo ( ImageInfo *image_info );


=A description of each parameter follows:

'

image_info:


.Specifies a pointer to an ImageInfo structure.






2

DestroyImages



HMethod DestroyImages deallocates memory associated with a linked list ofimages.

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






2

DisplayImages



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


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






0

GetImageInfo



8Method GetImageInfo initializes the ImageInfo structure.

)The format of the GetImageInfo method is:i

void GetImageInfo ( ImageInfo *image_info );


=A description of each parameter follows:

'

image_info:


.Specifies a pointer to an ImageInfo structure.






0

GetImageType



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


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






0

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.






6

GetNumberScenes



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

,The format of the GetNumberScenes method is:m

unsigned int GetNumberScenes ( const Image *image );


=A description of each parameter follows:

#

scenes:


IMethod GetNumberScenes returns the number of scenes in an image sequence."

image:


)The address of a structure of type Image.






.

GetPageInfo



8Method GetPageInfo initializes the image page structure.

(The format of the GetPageInfo method is:o

void GetPageInfo ( RectangleInfo *page_info );


=A description of each parameter follows:

&

page_info:


1Specifies a pointer to a RectangleInfo structure.






*

GetPixels



GMethod GetPixels is a convenience routine. Use it to extract pixel dataKfrom an image and place it in a buffer you supply. The data is saved eitherJas char, short int, integer, float or double format in the order specifiedFby the type parameter. For example, we want to extract scanline 1 of a8640x480 image as character data in red-green-blue order:O

GetPixels ( image, 0, 0, 640, 1, "RGB", 0, pixels );;


&The format of the GetPixels method is:

void GetPixels ( Image *image, const int x, const int y, const unsigned int columns, const unsigned int rows, const char *map, const StorageType type, void *pixels );


=A description of each parameter follows:

"

image:


BSpecifies a pointer to a Image structure; returned from ReadImage.-

x,y,columns,rows:


CThese values define the perimeter of a region of pixels you want toextract.

map:


9This character string can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, !Y = yellow, &M = magenta, and jK = black. The ordering reflects the order of the pixels in the supplied pixel array.!

type:


Jpixel type where 0 = unsigned char, 1 = short int, 2 = int, 3 = float, andG4 = double. Float and double types are expected to be normalized [0..1]otherwise [0..MaxRGB].#

pixels:


KThis array of values contain the pixel components as defined by the map andJtype parameters. The length of the arrays must equal the area specified by0the width and height values and type parameters.






4

GetPixelPacket



<Method GetPixelPacket initializes the PixelPacket structure.

+The format of the GetPixelPacket method is:j

void GetPixelPacket ( PixelPacket *pixel );


=A description of each parameter follows:

"

pixel:


/Specifies a pointer to a PixelPacket structure.






,

IsGeometry



HMethod IsGeometry returns True if the geometry specification is valid asdetermined by ParseGeometry.

'The format of the IsGeometry method is:K

unsigned int IsGeometry ( const char *geometry );


=A description of each parameter follows:

#

status:


EMethod IsGeometry returns True if the geometry specification is validotherwise False is returned.%

geometry:


*This string is the geometry specification.






,

IsSubimage



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

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


=A description of each parameter follows:

#

status:


BMethod IsSubimage returns True if the geometry is a valid subimage*specification otherwise False is returned.%

geometry:


*This string is the geometry specification.%

pedantic:


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






*

IsTainted



HMethod IsTainted returns True if the image has been altered since it wasDfirst read or if any image in the sequence has a difference magic or filename.

&The format of the IsTainted method is:g

unsigned int IsTainted ( const Image *image );


=A description of each parameter follows:

#

status:


HMethod IsTainted returns True if the image has been altered since it was first read."

image:


)The address of a structure of type Image.






,

LabelImage



FMethod LabelImage initializes an image label. Optionally the label canCinclude the image filename, type, width, height, or scene number by$embedding special format characters.

'The format of the LabelImage method is:m

void LabelImage ( Image *image, const char *label );


=A description of each parameter follows:

"

image:


)The address of a structure of type Image."

label:


>The address of a character string containing the label format.






,

LayerImage



IMethod LayerImage extracts the specified layer from the references image.

'The format of the LayerImage method is:

void LayerImage ( Image *image, const LayerType layer );


=A description of each parameter follows:

"

image:


BThe address of a structure of type Image; returned from ReadImage."

layer:


JA value of type LayerType that identifies which layer to extract.






8

ListToGroupImage



HMethod ListToGroupImage converts a linked list of images to a sequentialarray.

-The format of the ListToGroupImage method is:

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


=A description of each parameter follows:

#

images:


HMethod ListToGroupImage converts a linked list of images to a sequentialarray and returns the array..#

images:


BThe address of a structure of type Image; returned from ReadImage.*

number_images:


KA pointer to an unsigned integer. The number of images$in the image array is returned here.






,

MatteImage



IMethod MatteImage initializes the matte channel of the reference image toopaque.

'The format of the MatteImage method is:k

void MatteImage ( Image *image, Quantum opacity );


=A description of each parameter follows:

"

image:


BThe address of a structure of type Image; returned from ReadImage.$

opacity:


The level of transparency.






0

MogrifyImage



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

)The format of the MogrifyImage method is:

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


JSpecifies a pointer to an integer describing the number of elements in theargument vector.!

argv:


JSpecifies a pointer to a text array containing the command line arguments."

image:


BThe address of a structure of type Image; returned from ReadImage.






2

MogrifyImages



FMethod MogrifyImages applies image processing options to a sequence of-images as prescribed by command line options.

)The format of the MogrifyImage method is:

void MogrifyImages ( const ImageInfo *image_info, const int argc, char **argv, Image **images );


=A description of each parameter follows:

'

image_info:


.Specifies a pointer to an ImageInfo structure.!

argc:


JSpecifies a pointer to an integer describing the number of elements in theargument vector.!

argv:


JSpecifies a pointer to a text array containing the command line arguments.#

images:


BThe address of a structure of type Image; returned from ReadImage.






0

MosaicImages



GMethod MosaicImages inlays a number of images to form a single coherentpicture.

(The format of the MosaicImage method is:

Image *MosaicImages ( const Image *images );


=A description of each parameter follows:

#

images:


BThe address of a structure of type Image; returned from ReadImage.






<

ParseImageGeometry



IMethod ParseImageGeometry parses a geometry specification and returns theJwidth, height, x, and y values. It also returns flags that indicates whichHof the four values (width, height, xoffset, yoffset) were located in theAstring, 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:


GMethod ParseImageGeometry returns a bitmask that indicates which of the0four values were located in the geometry string.+

image_geometry:


ESpecifies a character string representing the geometry specification.

x,y:


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

width,height:


KA pointer to an unsigned integer. The width and height=as determined by the geometry specification is returned here.






*

PingImage



HMethod PingImage returns the image size in bytes if it exists and can beJthe image is returned as well. Note, only the first image in a multi-frameimage file is pinged.

&The format of the PingImage method is:

Image *PingImage ( const ImageInfo *image_info );


=A description of each parameter follows:

"

Image:


IMethod PingImage returns the image size in bytes if the image file exists*and it size can be determined otherwise 0.'

image_info:


.Specifies a pointer to an ImageInfo structure.






*

ReadImage



GMethod ReadImage reads an image and returns it. It allocates the memoryFnecessary for the new Image structure and returns a pointer to the newIimage. By default, the image format is determined by its magic number. ToHspecify a particular image format, precede the filename with an explicitGimage format name and a colon (i.e. ps:image) or as the filename suffix(i.e. image.ps).

&The format of the ReadImage method is:

Image *ReadImage ( ImageInfo *image_info );


=A description of each parameter follows:

"

image:


?Method ReadImage returns a pointer to the image after reading. KA null image is returned if there is a memory shortageor if the image cannot be read.'

image_info:


.Specifies a pointer to an ImageInfo structure.






,

ReadImages



JMethod ReadImages reads a list of image names from a file and then returnsthe images as a linked list.

&The format of the ReadImage method is:

Image *ReadImages ( ImageInfo *image_info );


=A description of each parameter follows:

"

image:


?Method ReadImage returns a pointer to the image after reading. KA null image is returned if there is a memory shortageor if the image cannot be read.'

image_info:


.Specifies a pointer to an ImageInfo structure.






:

RGBTransformImage



;Method RGBTransformImage converts the reference image from GRGB to an alternate colorspace. The transformationJmatrices are not the standard ones: the weights are rescaled to normalized6the range of the transformed values to be [0..MaxRGB].

.The format of the RGBTransformImage method is:

void RGBTransformImage ( Image *image, const ColorspaceType colorspace );


=A description of each parameter follows:

"

image:


BThe address of a structure of type Image; returned from ReadImage.'

colorspace:


JAn unsigned integer value that indicates which colorspace to transform theimage.






(

SetImage



HMethod SetImage initializes the reference image to the background color.

%The format of the SetImage method is:X

void SetImage ( Image *image );


=A description of each parameter follows:

"

image:


BThe address of a structure of type Image; returned from ReadImage.






0

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

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


=A description of each parameter follows:

'

image_info:


.Specifies a pointer to an ImageInfo structure.$

rectify:


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






H

SortColormapByIntentsity



KMethod SortColormapByIntensity sorts the colormap of a PseudoClass image bydecreasing color intensity.

4The format of the SortColormapByIntensity method is:

3

    void SortColormapByIntensity(Image *image)


=A description of each parameter follows:

"

image:


4A pointer to a Image structure.






*

SyncImage



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

&The format of the SyncImage method is:Y

void SyncImage ( Image *image );


=A description of each parameter follows:

"

image:


)The address of a structure of type Image.






0

TextureImage



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


BThe address of a structure of type Image; returned from ReadImage.$

texture:


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






:

TransformRGBImage



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

.The format of the TransformRGBImage method is:

void TransformRGBImage ( Image *image, const ColorspaceType colorspace );


=A description of each parameter follows:

"

image:


BThe address of a structure of type Image; returned from ReadImage.'

colorspace:


IAn unsigned integer value defines which colorspace to transform the imageto.






8

TransparentImage



HMethod TransparentImage creates a matte image associated with the image.KAll pixel locations are initially set to opaque. Any pixel that matches the'specified color are set to transparent.

-The format of the TransparentImage method is:s

void TransparentImage ( Image *image, const char *color );


=A description of each parameter follows:

"

image:


BThe address of a structure of type Image; returned from ReadImage."

color:


8A character string that contain an &X11 color string.






,

WriteImage



Method WriteImage writes an image to a file as defined by image->filename. You can specify a particular image format by prefixing the file with the image type and a colon (i.e. ps:image) or specify the image type as the filename suffix (i.e. image.ps). The image may be modified to adapt it to the requirements of the image format. For example, DirectClass images must be color-reduced to PseudoClass if the format is GIF.

'The format of the WriteImage method is:

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


=A description of each parameter follows:

#

status:


KMethod WriteImage return True if the image is written. False is returned is?there is a memory shortage or if the image file fails to write.'

image_info:


.Specifies a pointer to an ImageInfo structure."

image:


4A pointer to a Image structure.