GraphicsMagick
GraphicsMagick
Miscellaneous image methods
Contents
const char *AccessDefinition( const ImageInfo *image_info, const char *magick, const char *key );
AccessDefinition() searches the definitions for an entry matching the specified magick and key. NULL is returned if no matching entry is found.
The format of the AccessDefinition method is:
const char *AccessDefinition( const ImageInfo *image_info, const char *magick, const char *key );
The image info.
Format ID. This is usually the same as the coder name.
Key to search for.
MagickPassFail AddDefinition( ImageInfo *image_info, const char *magick, const char *key, const char *value, ExceptionInfo *exception );
AddDefinition() adds a key/value definition to the current map of definitions in ImageInfo. Definitions may be used by coders/decoders that read and write images.
The format of the AddDefinition method is:
MagickPassFail AddDefinition( ImageInfo *image_info, const char *magick, const char *key, const char *value, ExceptionInfo *exception );
The image info.
format/classification identifier
subidentifier within format/classification
definition value
Errors result in updates to this structure.
MagickPassFail AddDefinitions( ImageInfo *image_info, const char *options );
AddDefinitions() adds definitions from a key/value based string to the current map of definitions in ImageInfo. Definitions may be used by coders/decoders that read and write images.
The format of the AddDefinitions method is:
MagickPassFail AddDefinitions( ImageInfo *image_info, const char *options );
A description of each parameter follows:
The image info.
List of key/value pairs to put in the definitions map. The format of the string is "key1[=[value1]],key2[=[value2]],...". A missing value argument (with or without the equal sign) inserts an empty, zero length string as value for a key.
Errors result in updates to this structure.
AllocateImage() returns a pointer to an image structure initialized to default values. Currently a failure in this function results in a fatal error, resulting in program exit.
The format of the AllocateImage method is:
Image *AllocateImage( const ImageInfo *image_info );
A description of each parameter follows:
Many of the image default values are set from this structure. For example, filename, compression, depth, background color, and others.
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.
It is expected that the image next pointer is null, since otherwise there is likely to be a memory leak. In the future this may be enforced.
The format of the AllocateNextImage method is:
void AllocateNextImage( const ImageInfo *image_info, Image *image );
A description of each parameter follows:
Many of the image default values are set from this structure. For example, filename, compression, depth, background color, and others.
The image.
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:
The image info.
The image.
Image *AppendImages( const Image *image, const unsigned int stack, ExceptionInfo *exception );
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 );
The image sequence.
A value other than 0 stacks the images top-to-bottom.
Return any errors or warnings in this structure.
ExceptionType CatchImageException( Image *image );
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.
The format of the CatchImageException method is:
ExceptionType CatchImageException( Image *image );
A description of each parameter follows:
An image sequence.
unsigned int ClipPathImage( Image *image, const char *pathname, const unsigned int inside );
ClipPathImage() sets the image clip mask based any clipping path information if it exists.
The format of the ClipPathImage method is:
unsigned int ClipPathImage( Image *image, const char *pathname, const unsigned int inside );
The image.
name of clipping path resource. If name is preceded by #, use clipping path numbered by name.
if non-zero, later operations take effect inside clipping path. Otherwise later operations take effect outside clipping path.
unsigned int CompositePathImage( Image *image, const char *pathname, const unsigned int inside );
CompositePathImage() sets the image composite mask based any compositing path information if it exists.
The format of the CompositePathImage method is:
unsigned int CompositePathImage( Image *image, const char *pathname, const unsigned int inside );
The image.
name of compositing path resource. If name is preceded by #, use compositing path numbered by name.
if non-zero, later operations take effect inside compositing path. Otherwise later operations take effect outside compositing path.
Image *CloneImage( const Image *image, const unsigned long columns, const unsigned long rows, const unsigned int orphan, ExceptionInfo *exception );
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 );
The image.
The number of columns in the cloned image.
The number of rows in the cloned image.
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.
Return any errors or warnings in this structure.
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:
The image info.
void DestroyImage( Image *image );
DestroyImage() dereferences an image, deallocating memory associated with the image if the reference count becomes zero. There is no effect if the image pointer is null.
In the interest of avoiding dangling pointers or memory leaks, the image previous and next pointers should be null when this function is called, and no other image should refer to it. In the future this may be enforced.
The format of the DestroyImage method is:
void DestroyImage( Image *image );
A description of each parameter follows:
The image.
void DestroyImageInfo( ImageInfo *image_info );
DestroyImageInfo() deallocates memory associated with a ImageInfo structure.
The format of the DestroyImageInfo method is:
void DestroyImageInfo( ImageInfo *image_info );
A description of each parameter follows:
The image info.
DisplayImages() displays an image sequence to any X window screen. It returns MagickPass if successful or MagickFail if not. Check the exception member of image to determine the reason for any failure.
The format of the DisplayImages method is:
MagickPassFail DisplayImages( const ImageInfo *image_info, Image *image );
A description of each parameter follows:
The image info.
The image.
Image *GetImageClipMask( const Image *image, ExceptionInfo *exception );
GetImageClipMask returns a reference-counted copy of the current image clip mask. This copy must be deallocated using DestroyImage() once it is no longer needed. If the image does not have an associated clip mask, then NULL is returned. Use SetImageClipMask() to add a clip mask to an image, or remove a clip mask.
If a component of the clip mask is set to TransparentOpacity (maximum value) then the corresponding image pixel component will not be updated when SyncImagePixels() is applied. The clip mask may be used to constrain the results of an image processing operation to a region of the image. Regions outside those allowed by the clip mask may be processed, but only pixel quantums allowed by the clip mask will actually be updated.
The clip mask protects the DirectClass pixels and PseudoClass pixel indexes from modification. The clip mask does not protect the image colormap since the image colormap is globally shared by all pixels in a PseudoClass image.
The format of the GetImageClipMask method is
Image *GetImageClipMask( const Image *image, ExceptionInfo *exception );
A descripton of each parameter follows:
The image.
Reason for failure.
Image *GetImageCompositeMask( const Image *image, ExceptionInfo *exception );
GetImageCompositeMask returns a reference-counted copy of the current image composite mask. This copy must be deallocated using DestroyImage() once it is no longer needed. If the image does not have an associated composite mask, then NULL is returned. Use SetImageCompositeMask() to add a composite mask to an image, or remove a composite mask.
If a component of the composite mask is set to TransparentOpacity (maximum value) then the corresponding image pixel component will not be updated when SyncImagePixels() is applied. The composite mask may be used to constrain the results of an image processing operation to a region of the image. Regions outside those allowed by the composite mask may be processed, but only pixel quantums allowed by the composite mask will actually be updated.
The composite mask protects the DirectClass pixels and PseudoClass pixel indexes from modification. The composite mask does not protect the image colormap since the image colormap is globally shared by all pixels in a PseudoClass image.
The format of the GetImageCompositeMask method is
Image *GetImageCompositeMask( const Image *image, ExceptionInfo *exception );
A descripton of each parameter follows:
The image.
Reason for failure.
void GetImageException( Image *image, ExceptionInfo *exception );
GetImageException() traverses an image sequence and returns any error more severe than noted by the exception parameter.
The format of the GetImageException method is:
void GetImageException( Image *image, ExceptionInfo *exception );
A description of each parameter follows:
Specifies a pointer to a list of one or more images.
return the highest severity exception.
int GetImageGeometry( const Image *image, const char *geometry, const unsigned int size_to_fit, RectangleInfo *region_info );
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, RectangleInfo *region_info );
Method GetImageGeometry returns a bitmask that indicates which of the four values were located in the geometry string.
The geometry (e.g. 100x100+10+10).
A value other than 0 means to scale the region so it fits within the specified width and height.
The region as defined by the geometry string with respect to the image and its gravity.
void GetImageInfo( ImageInfo *image_info );
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:
The image info.
unsigned int IsTaintImage( const Image *image );
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:
The image.
ModifyImage( Image *image, ExceptionInfo *exception );
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:
The image.
Return any errors or warnings in this structure.
void RemoveDefinitions( ImageInfo *image_info, const char *options );
RemoveDefinitions() removes definitions from the current map of definitions in ImageInfo. Definitions may be used by coders/decoders that read and write images. RemoveDefinitions() returns true only if the specified keys are present in the map and are actually removed.
The format of the RemoveDefinitions method is:
void RemoveDefinitions( ImageInfo *image_info, const char *options );
A description of each parameter follows:
The image info.
List of keys to remove from the definitions map. The format of the string is "key1,key2,...". A special key, '*', removes all the key/value pairs in the definitions map. This key always succeeds.
Errors result in updates to this structure.
MagickPassFail ResetImagePage( Image *image, const char *page );
ResetImagePage adjusts the current page canvas and position based on a relative page specification.
The format of the ResetImagePage method is:
MagickPassFail ResetImagePage( Image *image, const char *page );
A description of each parameter follows:
The image.
Relative page offset adjustment
void SetImageEx( Image *image, const Quantum opacity, ExceptionInfo *exception );
SetImageEx() 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 SetImageEx method is:
void SetImageEx( Image *image, const Quantum opacity, ExceptionInfo *exception );
The image.
Set each pixel to this level of transparency.
Report any exception here.
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. Any exception is reported to the image.
The format of the SetImage method is:
void SetImage( Image *image, const Quantum opacity );
A description of each parameter follows:
The image.
Set each pixel to this level of transparency.
MagickPassFail SetImageColor( Image *image, const PixelPacket *pixel );
SetImageColor() sets the red, green, blue and opacity components of each pixel to those from a specified pixel value.
The format of the SetImageColor method is:
MagickPassFail SetImageColor( Image *image, const PixelPacket *pixel );
A description of each parameter follows:
The image.
Set each pixel in the image to this pixel's color and transparency.
MagickPassFail SetImageColorRegion( Image *image, long x, long y, unsigned long width, unsigned long height, const PixelPacket *pixel );
SetImageColorRegion() sets the red, green, blue and opacity components of each pixel in the specified region to those from a specified pixel value. Please note that it is assumed that the pixel value is in the same colorspace as the image.
The format of the SetImageColorRegion method is:
MagickPassFail SetImageColorRegion( Image *image, long x, long y, unsigned long width, unsigned long height, const PixelPacket *pixel );
The image.
Set each pixel in the image to this pixel's color and transparency.
SetImageClipMask() associates a clip mask with the image. The clip mask must be the same dimensions as the image.
If a component of the clip mask is set to TransparentOpacity (maximum value) then the corresponding image pixel component will not be updated when SyncImagePixels() is applied. The clip mask may be used to constrain the results of an image processing operation to a region of the image. Regions outside those allowed by the clip mask may be processed, but only pixel quantums allowed by the clip mask will actually be updated.
The clip mask protects the DirectClass pixels and PseudoClass pixel indexes from modification. The clip mask does not protect the image colormap since the image colormap is globally shared by all pixels in a PseudoClass image.
The format of the SetImageClipMask method is:
unsigned int SetImageClipMask( Image *image, const Image *clip_mask );
A description of each parameter follows:
The image.
The image clip mask.
SetImageCompositeMask() associates a composite mask with the image. The mask must be the same dimensions as the image.
If a component of the composite mask is set to TransparentOpacity (maximum value) then the corresponding image pixel component will not be updated when SyncImagePixels() is applied. The composite mask may be used to composite the results of an image processing operation to a region of the image. Regions outside those allowed by the composite mask may be processed, but only pixel quantums covered by the composite mask will actually be updated.
The composite mask protects the DirectClass pixels and PseudoClass pixel indexes from modification. The composite mask does not protect the image colormap since the image colormap is globally shared by all pixels in a PseudoClass image.
The format of the SetImageCompositeMask method is:
unsigned int SetImageCompositeMask( Image *image, const Image *composite_mask );
A description of each parameter follows:
The image.
The image composite mask.
unsigned int SetImageDepth( Image *image, const unsigned long depth );
SetImageDepth() translates the pixel quantums across all of the channels so that if they are later divided to fit within the specified bit depth, that no additional information is lost (i.e. no remainder will result from the division). Note that any subsequent image processing is likely to increase the effective depth of the image channels. A non-zero value is returned if the operation is successful. 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:
The image to update.
Desired image depth (range 1 to QuantumDepth)
void SetImageOpacity( Image *image, const unsigned int opacity );
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.
The format of the SetImageOpacity method is:
void SetImageOpacity( Image *image, const unsigned int opacity );
A description of each parameter follows:
The image.
The level of transparency: 0 is fully opaque and MaxRGB is fully transparent.
(void) SetImageType() sets the type of image. Choose from these types:
BilevelType, GrayscaleType, GrayscaleMatteType, PaletteType, PaletteMatteType, TrueColorType, TrueColorMatteType, ColorSeparationType, ColorSeparationMatteType, OptimizeType
The format of the (void) SetImageType method is:
( void )SetImageType( Image *image, const ImageType image_type );
A description of each parameter follows:
The image.
Image type.
MagickPassFail StripImage( Image *image );
StripImage removes all profiles and text attributes from the image.
The format of the StripImage method is:
MagickPassFail StripImage( Image *image );
A description of each parameter follows:
The image.
MagickPassFail SyncImage( Image *image );
Method SyncImage initializes the red, green, and blue intensities of each pixel as defined by the colormap index and the current image colormap. This is a helper function to update the DirectClass representation of the image pixels after the PseudoClass representation has been updated.
The format of the SyncImage method is:
MagickPassFail SyncImage( Image *image );
A description of each parameter follows:
The image.
Copyright © GraphicsMagick Group 2002 - 2023