Last update Sun May 11 01:02:33 2014


zlib (See accompanying LICENSE file)

Mike Wey

This module contains functions that operate on a array or list of images.

alias ImageLayerMethod = dmagick.c.layer.ImageLayerMethod;

See Also:

void animationDelay(Image[] images, Duration delay);

Set the animationDelay for all images in the array.

void animationIterations(Image[] images, size_t iterations);

Number of iterations to loop an animation.

Image average(Image[] images);

Averages all the images together. Each image in the image must have the same width and height.

Image[] clone(const(Image)[] images);

Clone every image in the array.

Image[] coalesce(Image[] images);

Merges all the images in the imagelist into a new imagelist. Each image in the new imagelist is formed by flattening all the previous images.

The length of time between images in the new image is specified by the delay attribute of the input image. The position of the image on the merged images is specified by the page attribute of the input image.

Image[] compareLayers(Image[] images, ImageLayerMethod method);

Compares each image with the next in a sequence and returns the minimum bounding region of all the pixel differences (of the ImageLayerMethod specified) it discovers.

Images do NOT have to be the same size, though it is best that all the images are 'coalesced' (images are all the same size, on a flattened canvas, so as to represent exactly how an specific frame should look).

No GIF dispose methods are applied, so GIF animations must be coalesced before applying this image operator to find differences to them.

void compositeLayers(ref Image[] destination, Image[] source, ssize_t xOffset, ssize_t yOffset, CompositeOperator operator = CompositeOperator.OverCompositeOp);

An image from source is composited over an image from destination until one list is finished. Unlike a normal composite operation, the canvas offset is also included to the composite positioning. If one of the image lists only contains one image, that image is applied to all the images in the other image list, regardless of which list it is. In this case it is the image meta-data of the list which preserved.

void display(Image[] images);

Repeatedly displays an image sequence to a X window screen.

void fx(Image[] images, string expression, ChannelType channel = ChannelType.DefaultChannels);

Applies a mathematical expression to the specified images.

See Aso:

FX, The Special Effects Image Operator for a detailed discussion of this option.

Image mergeLayers(Image[] layers, ImageLayerMethod method = ImageLayerMethod.FlattenLayer);

Composes all the image layers from the current given image onward to produce a single image of the merged layers.

The inital canvas's size depends on the given ImageLayerMethod, and is initialized using the first images background color. The images are then compositied onto that image in sequence using the given composition that has been assigned to each individual image.


Image[] layers The images to merge.
ImageLayerMethod method The method of selecting the size of the initial canvas.
  • MergeLayer: Merge all layers onto a canvas just large enough to hold all the actual images. The virtual canvas of the first image is preserved but otherwise ignored.
  • FlattenLayer: Use the virtual canvas size of first image. Images which fall outside this canvas is clipped. This can be used to 'fill out' a given virtual canvas.
  • MosaicLayer: Start with the virtual canvas of the first image enlarging left and right edges to contain all images. Images with negative offsets will be clipped.
  • TrimBoundsLayer: Determine the overall bounds of all the image layers just as in "MergeLayer". Then adjust the the canvas and offsets to be relative to those bounds. Without overlaying the images.

    Warning: a new image is not returned the original image sequence page data is modified instead.

Image[] montage(Image[] images, Montage montageInfo);

Creates a composite image by reducing the size of the input images and arranging them in a grid on the background color or texture of your choice. There are many configuration options. For example, you can specify the number of columns and rows, the distance between images, and include a label with each small image (called a tile).

To add labels to the tiles, assign a "Label" property to each image.

Image[] morph(Image[] images, size_t frames);

Transforms a image into another image by inserting n in-between images. Requires at least two images. If more images are present, the 2nd image is transformed into the 3rd, the 3rd to the 4th, etc.


Image[] images The images to use.
size_t frames The number of frames to inster between the images.

Image[] optimizeLayers(Image[] images);

For each image compares the GIF disposed forms of the previous image in the sequence. From this it attempts to select the smallest cropped image to replace each frame, while preserving the results of the GIF animation.

See Also:
Examples of ImageMagick Usage

Image[] optimizePlusLayers(Image[] images);

Is exactly as optimizeLayers, but may also add or even remove extra frames in the animation, if it improves the total number of pixels in the resulting GIF animation.

Image[] ping(string filename);
Image[] ping(void[] blob);
Image[] ping(void[] blob, Geometry size);
Image[] ping(void[] blob, Geometry size, size_t depth);
Image[] ping(void[] blob, Geometry size, size_t depth, string magick);
Image[] ping(void[] blob, Geometry size, string magick);

Ping is similar to read except only enough of the image is read to determine the image columns, rows, and filesize. The columns, rows, and fileSize attributes are valid after invoking ping. The image data is not valid after calling ping.

void quantize(Image[] images, bool measureError = false);

Analyzes the colors within a set of reference images and chooses a fixed number of colors to represent the set. The goal of the algorithm is to minimize the difference between the input and output images while minimizing the processing time.


Image[] images The images to quantize.
bool measureError Set to true to calculate quantization errors when quantizing the image. These can be accessed


normalizedMeanError, normalizedMaxError and meanErrorPerPixel.

void quantizeColors(Image[] images, size_t colors);
size_t quantizeColors(const(Image)[] images);

Preferred number of colors in the image. The actual number of colors in the image may be less than your request, but never more. Images with less unique colors than specified with this option will have any duplicate or unused colors removed.

void quantizeColorSpace(Image[] images, ColorspaceType type);
ColorspaceType quantizeColorSpace(const(Image)[] images);

Colorspace to quantize colors in. Empirical evidence suggests that distances in color spaces such as YUV or YIQ correspond to perceptual color differences more closely than do distances in RGB space. These color spaces may give better results when color reducing an image. The default is RGB

void quantizeDitherMethod(Image[] images, DitherMethod method);
DitherMethod quantizeDitherMethod(const(Image)[] images);

The basic strategy of dithering is to trade intensity resolution for spatial resolution by averaging the intensities of several neighboring pixels. Images which suffer from severe contouring when reducing colors can be improved with this option.

void quantizeTreeDepth(Image[] images, size_t depth);
size_t quantizeTreeDepth(const(Image)[] images);

Depth of the quantization color classification tree. Values of 0 or 1 allow selection of the optimal tree depth for the color reduction algorithm. Values between 2 and 8 may be used to manually adjust the tree depth.

Image[] readImages(string filename);
Image[] readImages(string filename, Geometry size);

Read a multi frame Image by reading from the file or URL specified by filename.

Image[] readImages(void[] blob);
Image[] readImages(void[] blob, Geometry size);
Image[] readImages(void[] blob, Geometry size, size_t depth);
Image[] readImages(void[] blob, Geometry size, size_t depth, string magick);
Image[] readImages(void[] blob, Geometry size, string magick);

Reads a multi frame Image from an in-memory blob. The Blob size, depth and magick format may also be specified.

Some image formats require size to be specified, the default depth Imagemagick uses is the Quantum size it's compiled with. If it doesn't match the depth of the image it may need to be specified.

Imagemagick can usualy detect the image format, when the format can't be detected a magick format must be specified.

void remap(Image[] images, Image referenceImage);

Reduce the colors used in the imagelist to the set of colors in reference image.

void[] toBlob(Image[] images, string magick = null, size_t depth = 0, bool adjoin = true);

Creates a Binary Large OBject, a direct-to-memory version of the image.

if an image format is selected which is capable of supporting fewer colors than the original image or quantization has been requested, the original image will be quantized to fewer colors. Use a copy of the original if this is a problem.

Note, some image formats do not permit multiple images to the same image stream (e.g. JPEG). in this instance, just the first image of the sequence is returned as a blob.


Image[] images Images to write.
string magick Specifies the image format to write.
size_t depth Specifies the image depth.
bool adjoin Join images into a single multi-image file.

void writeImages(Image[] images, string filename, bool adjoin = true);

Writes the image to the specified file. ImageMagick determines image format from the prefix or extension.

WriteImages generates multiple output files if necessary (or when requested). When adjoin is set to false, the filename is expected to include a printf-style formatting string for the frame number (e.g. "image%02d.png").

If an image format is selected which is capable of supporting fewer colors than the original image or quantization has been requested, the original image will be quantized to fewer colors. Use a copy of the original if this is a problem.


Image[] images Images to write.
string filename The file name to write to.
bool adjoin Join images into a single multi-image file.