Author: Bob Friesenhahn
Description: Description of Image structure members.

# 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_class | 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.
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.
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.