ImageMagick Image

The Image structure represents an ImageMagick image. It is initially allocated by AllocateImage() and deallocated by DestroyImage(). The functions ReadImage(), ReadImages(), BlobToImage() and CreateImage() return a new image. Use CloneImage() to copy an image. An image consists of a structure containing image attributes as well as the image pixels.

The image pixels are represented by the structure PixelPacket and are cached in-memory, or on disk, depending on the cache threshold setting. This cache is known as the "pixel cache". Pixels in the cache may not be edited directly. They must first be made visible from the cache via a pixel view. A pixel view is a rectangular view of the pixels as defined by a starting coordinate, and a number of rows and columns. When considering the varying abilities of multiple platforms, the most reliably efficient pixel view is comprized of part, or all, of one image row.

There are two means of accessing pixel views. When using the default view, the pixels are made visible and accessable by using the GetImagePixels() method which provides access to a specified region of the image. After the view has been updated, thhe pixels may be saved back to the cache in their original positions via SyncImagePixels(). In order to create an image with new contents, or to blindly overwrite existing contents, the method SetImagePixels() is used to reserve a pixel view corresponding to a region in the pixel cache. Once the pixel view has been updated, it may be written to the cache via SyncImagePixels(). The function GetIndexes() provides access to the image colormap, represented as an array of type IndexPacket.

A more flexible interface to the image pixels is via the CacheView interface. This interface supports multiple pixel cache views (limited by the number of image rows), each of which are identified by a handle (of type ViewInfo*). Use OpenCacheView() to obtain a new cache view, CloseCacheView() to discard a cache view, GetCacheView() to access an existing pixel region, SetCacheView() to define a new pixel region, and SyncCacheView() to save the updated pixel region. The function GetCacheViewIndexes() provides access to the colormap indexes associated with the pixel view.

When writing encoders and decoders for new image formats, it is convenient to have a high-level interface available which supports converting between external pixel representations and ImageMagick's own representation. Pixel components (red, green, blue, opacity, RGB, or RGBA) may be transferred from a user-supplied buffer into the default view by using PushImagePixels(). Pixel components may be transferred from the default view into a user-supplied buffer by using PopImagePixels(). Use of this high-level interface helps protect image coders from changes to ImageMagick's pixel representation and simplifies the implementation.

The members of the Image structure are shown in the following table:

Image Structure Members
Member Type Description

attributes ImageAttribute* Image attribute list. Consists of a doubly-linked-list of ImageAttribute structures, each of which has an associated key and value. Access/update list via SetImageAttribute() and GetImageAttribute(). Key-strings used by ImageMagick include "Comment" (image comment) , "Label" (image label), and "Signature" (image signature).

ImageAttributebackground_color PixelPacket Image background color

blur double Blur factor to apply to the image when zooming

border_color PixelPacket Image border color

chromaticity ChromaticityInfo Red, green, blue, and white-point chromaticity values.

color_profile ProfileInfo ICC color profile. Specifications are available from the International Color Consortium for the format of ICC color profiles.

colormap PixelPacket * PseudoColor palette array.

colors unsigned int The desired number of colors. Used by QuantizeImage().

colorspace ColorspaceType Image pixel interpretation.If the colorspace is RGB the pixels are red, green, blue. If matte is true, then red, green, blue, and index. If it is CMYK, the pixels are cyan, yellow, magenta, black. Otherwise the colorspace is ignored.

columns unsigned int Image width

comments char * Image comments

compression CompressionType Image compresion type. The default is the compression type of the specified image file.

delay unsigned int Time in 1/100ths of a second (0 to 65535) which must expire before displaying the next image in an animated sequence. This option is useful for regulating the animation of a sequence of GIF images within Netscape.

depth unsigned int Image depth (8 or 16). QuantumLeap must be defined before a depth of 16 is valid.

directory char * Tile names from within an image montage. Only valid after calling MontageImages() or reading a MIFF file which contains a directory.

dispose unsigned int GIF disposal method. This option is used to control how successive frames are rendered (how the preceding frame is disposed of) when creating a GIF animation.

exception ExceptionInfo Record of any error which occurred when updating image.

file FILE * Stdio stream to read image from or write image to. If set, ImageMagick will read from or write to the stream rather than opening a file. Used by ReadImage() and WriteImage(). The stream is closed when the operation completes.

filename char[MaxTextExtent] Image file name to read or write.

filesize long int Number of bytes of the encoded file.

filter FilterTypes Filter to use when resizing image. The reduction filter employed has a significant effect on the time required to resize an image and the resulting quality. The default filter is Lanczos which has been shown to produce high quality results when reducing most images.

fuzz int Colors within this distance are considered equal. A number of algorithms search for a target color. By default the color must be exact. Use this option to match colors that are close to the target color in RGB space.

gamma double Gamma level of the image. The same color image displayed on two different workstations may look different due to differences in the display monitor. Use gamma correction to adjust for this color difference.

geometry char * Preferred size of the image when encoding.

interlace InterlaceType The type of interlacing scheme (default NoInterlace). This option is used to specify the type of interlacing scheme for raw image formats such as RGB or YUV. NoInterlace means do not interlace, LineInterlace uses scanline interlacing, and PlaneInterlace uses plane interlacing. PartitionInterlace is like PlaneInterlace except the different planes are saved to individual files (e.g. image.R, image.G, and image.B). Use LineInterlace or PlaneInterlace to create an interlaced GIF or progressive JPEG image.

iptc_profile ProfileInfo IPTC profile. Specifications are available from the International Press Telecommunications Council for IPTC profiles.

iterations unsigned int Number of iterations to loop an animation (e.g. Netscape loop extension) for.

list struct _Image * Undo image list (used only by 'display')

magick char[MaxTextExtent] Image encoding format (e.g. "GIF").

magick_columns unsigned int Base image width (before transformations)

magick_filename char[MaxTextExtent] Base image filename (before transformations)

magick_rows unsigned int Base image height (before transformations)

matte unsigned int If non-zero, then the index member of pixels represents the alpha channel.

matte_color PixelPacket Image matte (transparent) color

mean_error_per_pixel unsigned int The mean error per pixel computed when an image is color reduced. This parameter is only valid if verbose is set to true and the image has just been quantized.

montage char * Tile size and offset within an image montage. Only valid for montage images.

next struct _Image * Next image frame in sequence

normalized_maximum_error double The normalized max error per pixel computed when an image is color reduced. This parameter is only valid if verbose is set to true and the image has just been quantized.

normalized_mean_error double The normalized mean error per pixel computed when an image is color reduced. This parameter is only valid if verbose is set to true and the image has just been quantized.

offset int Number of initial bytes to skip over when reading raw image.

orphan unsigned int When set, CloneImage() clones only the current frame, creating an "orphan" frame.

page RectangleInfo Equivalent size of Postscript page.

pipe int Set to True if image is read/written from/to a POSIX pipe. To read from (or write to) an open pipe, set this member to True, set the file member to a stdio stream representing the pipe (obtained from popen()), and invoke ReadImage()/WriteImage(). The pipe is automatically closed via pclose() when the operation completes.

pixels PixelPacket * Image pixels retrieved via GetPixelCache() or initialized via SetPixelCache().

previous struct _Image * Previous image frame in sequence.

rendering_intent RenderingIntent The type of rendering intent.

rows unsigned int Image height

scene unsigned int Image frame scene number.

storage_type ClassType Image storage class. If DirectClass then the image packets contain valid RGB or CMYK colors. If PseudoClass then the image has a colormap referenced by pixel's index member.

tainted int Set to non-zero (True) if the image pixels have been modified.

tile_info RectangleInfo Describes a tile within an image. For example, if your images is 640x480 you may only want 320x256 with an offset of +128+64. It is used for raw formats such as RGB and CMYK as well as for TIFF.

timer TimerInfo Support for measuring actual (user + system) and elapsed execution time.

total_colors unsigned long The number of colors in the image after QuantizeImage(), or QuantizeImages() if the verbose flag was set before the call. Calculated by GetNumberColors().

units ResolutionType Units of image resolution

x_resolution double Horizontal resolution of the image

y_resolution double Vertical resolution of the image

**Image Structure Members**
Member	Type	Description
attributes	ImageAttribute*	Image attribute list. Consists of a doubly-linked-list of ImageAttribute structures, each of which has an associated key and value. Access/update list via SetImageAttribute() and GetImageAttribute(). Key-strings used by ImageMagick include "Comment" (image comment) , "Label" (image label), and "Signature" (image signature).
ImageAttributebackground_color	PixelPacket	Image background color
blur	double	Blur factor to apply to the image when zooming
border_color	PixelPacket	Image border color
chromaticity	ChromaticityInfo	Red, green, blue, and white-point chromaticity values.
color_profile	ProfileInfo	ICC color profile. Specifications are available from the International Color Consortium for the format of ICC color profiles.
colormap	PixelPacket *	PseudoColor palette array.
colors	unsigned int	The desired number of colors. Used by QuantizeImage().
colorspace	ColorspaceType	Image pixel interpretation.If the colorspace is RGB the pixels are red, green, blue. If matte is true, then red, green, blue, and index. If it is CMYK, the pixels are cyan, yellow, magenta, black. Otherwise the colorspace is ignored.
columns	unsigned int	Image width
comments	char *	Image comments
compression	CompressionType	Image compresion type. The default is the compression type of the specified image file.
delay	unsigned int	Time in 1/100ths of a second (0 to 65535) which must expire before displaying the next image in an animated sequence. This option is useful for regulating the animation of a sequence of GIF images within Netscape.
depth	unsigned int	Image depth (8 or 16). QuantumLeap must be defined before a depth of 16 is valid.
directory	char *	Tile names from within an image montage. Only valid after calling MontageImages() or reading a MIFF file which contains a directory.
dispose	unsigned int	GIF disposal method. This option is used to control how successive frames are rendered (how the preceding frame is disposed of) when creating a GIF animation.
exception	ExceptionInfo	Record of any error which occurred when updating image.
file	FILE *	Stdio stream to read image from or write image to. If set, ImageMagick will read from or write to the stream rather than opening a file. Used by ReadImage() and WriteImage(). The stream is closed when the operation completes.
filename	char[MaxTextExtent]	Image file name to read or write.
filesize	long int	Number of bytes of the encoded file.
filter	FilterTypes	Filter to use when resizing image. The reduction filter employed has a significant effect on the time required to resize an image and the resulting quality. The default filter is Lanczos which has been shown to produce high quality results when reducing most images.
fuzz	int	Colors within this distance are considered equal. A number of algorithms search for a target color. By default the color must be exact. Use this option to match colors that are close to the target color in RGB space.
gamma	double	Gamma level of the image. The same color image displayed on two different workstations may look different due to differences in the display monitor. Use gamma correction to adjust for this color difference.
geometry	char *	Preferred size of the image when encoding.
interlace	InterlaceType	The type of interlacing scheme (default NoInterlace). This option is used to specify the type of interlacing scheme for raw image formats such as RGB or YUV. NoInterlace means do not interlace, LineInterlace uses scanline interlacing, and PlaneInterlace uses plane interlacing. PartitionInterlace is like PlaneInterlace except the different planes are saved to individual files (e.g. image.R, image.G, and image.B). Use LineInterlace or PlaneInterlace to create an interlaced GIF or progressive JPEG image.
iptc_profile	ProfileInfo	IPTC profile. Specifications are available from the International Press Telecommunications Council for IPTC profiles.
iterations	unsigned int	Number of iterations to loop an animation (e.g. Netscape loop extension) for.
list	struct _Image *	Undo image list (used only by 'display')
magick	char[MaxTextExtent]	Image encoding format (e.g. "GIF").
magick_columns	unsigned int	Base image width (before transformations)
magick_filename	char[MaxTextExtent]	Base image filename (before transformations)
magick_rows	unsigned int	Base image height (before transformations)
matte	unsigned int	If non-zero, then the index member of pixels represents the alpha channel.
matte_color	PixelPacket	Image matte (transparent) color
mean_error_per_pixel	unsigned int	The mean error per pixel computed when an image is color reduced. This parameter is only valid if verbose is set to true and the image has just been quantized.
montage	char *	Tile size and offset within an image montage. Only valid for montage images.
next	struct _Image *	Next image frame in sequence
normalized_maximum_error	double	The normalized max error per pixel computed when an image is color reduced. This parameter is only valid if verbose is set to true and the image has just been quantized.
normalized_mean_error	double	The normalized mean error per pixel computed when an image is color reduced. This parameter is only valid if verbose is set to true and the image has just been quantized.
offset	int	Number of initial bytes to skip over when reading raw image.
orphan	unsigned int	When set, CloneImage() clones only the current frame, creating an "orphan" frame.
page	RectangleInfo	Equivalent size of Postscript page.
pipe	int	Set to True if image is read/written from/to a POSIX pipe. To read from (or write to) an open pipe, set this member to True, set the file member to a stdio stream representing the pipe (obtained from popen()), and invoke ReadImage()/WriteImage(). The pipe is automatically closed via pclose() when the operation completes.
pixels	PixelPacket *	Image pixels retrieved via GetPixelCache() or initialized via SetPixelCache().
previous	struct _Image *	Previous image frame in sequence.
rendering_intent	RenderingIntent	The type of rendering intent.
rows	unsigned int	Image height
scene	unsigned int	Image frame scene number.
storage_type	ClassType	Image storage class. If DirectClass then the image packets contain valid RGB or CMYK colors. If PseudoClass then the image has a colormap referenced by pixel's index member.
tainted	int	Set to non-zero (True) if the image pixels have been modified.
tile_info	RectangleInfo	Describes a tile within an image. For example, if your images is 640x480 you may only want 320x256 with an offset of +128+64. It is used for raw formats such as RGB and CMYK as well as for TIFF.
timer	TimerInfo	Support for measuring actual (user + system) and elapsed execution time.
total_colors	unsigned long	The number of colors in the image after QuantizeImage(), or QuantizeImages() if the verbose flag was set before the call. Calculated by GetNumberColors().
units	ResolutionType	Units of image resolution
x_resolution	double	Horizontal resolution of the image
y_resolution	double	Vertical resolution of the image

Image manipulation software that works like magic.