Magick++ STL Support

Magick++ uses a limited set of template argument types. The current template argument types are:

Container

A container having the properties of a Back Insertion Sequence . Sequences support forward iterators and Back Insertion Sequences support the additional abilty to append an element via push_back(). Common compatable container types are the STL < vector > and <list > template containers. This template argument is usually used to represent an output container in which one or more image frames may be appended. Containers like STL <vector > which have a given default capacity may need to have their capacity adjusted via reserve() to a larger capacity in order to support the expected final size . Since Magick++ images are very small, it is likely that the default capacity of STL < vector > is sufficient for most situations.

InputIterator

An input iterator used to express a position in a container. These template arguments are typically used to represent a range of elements with first_ representing the first element to be processed and last_ representing the element to stop at. When processing the entire contents of a container, it is handy to know that STL containers usually provide the begin() and end() methods to return input interators which correspond with the first and last elements, respectively.

#include <list>
#include <Magick++.h>
using namespace std;
using namespace Magick;

int main(int /*argc*/,char **/*argv*/)
{
   list<Image> imageList;
   readImages( &imageList, "test_image_anim.gif" );

   Image appended;
   appendImages( &appended, imageList.begin(), imageList.end() );
   appended.write( "appended_image.miff" );
   return 0;
}

The available Magick++ specific STL algorithms for operating on sequences of image frames are shown in the following table:
 

Magick++ STL Algorithms For Image Sequences

Algorithm	Signature	Description
animateImages	InputIterator first_, InputIterator last_	Animate a sequence of image frames. Image frames are displayed in succession, creating an animated effect. The animation options are taken from the first image frame. This feature is only supported under X11 at the moment.
appendImages	Image *appendedImage_, InputIterator first_, InputIterator last_, bool stack_ = false	Append a sequence of image frames, writing the result to appendedImage_. All the input image frames must have the same width or height. Image frames of the same width are stacked top-to-bottom. Image frames of the same height are stacked left-to-right. If the stack_ parameter is false, rectangular image frames are stacked left-to-right otherwise top-to-bottom.
averageImages	Image *averagedImage_, InputIterator first_, InputIterator last_	Average a sequence of image frames, writing the result to averagedImage_. All the input image frames must be the same size in pixels.
coalesceImages	Container *coalescedImages_, InputIterator first_, InputIterator last_	Create a coalesced image sequence obtained by "playing" the image sequence (observing page offsets and disposal methods) to create a new image sequence in which all frames are full size and completely rendered. Note that if the original image sequence relied on page offsets and disposal methods that the resulting sequence will be larger (perhaps much larger) then the original. This is useful for GIF animation sequences that have page offsets and disposal methods. The resuting image sequence is returned via coalescedImages_.
deconstructImages	Container *deconstructedImages_, InputIterator first_, InputIterator last_	Break down an image sequence into constituent parts.  This is useful for creating GIF or MNG animation sequences. The input sequence is specified by first_ and last_, and the deconstruted images are returned via deconstructedImages_.
displayImages	InputIterator first_, InputIterator last_	Display a sequence of image frames. Through use of a pop-up menu, image frames may be selected in succession. This feature is fully supported under X11 but may have only limited support in other environments. Caution: if an image format is is not compatable with the display visual (e.g. JPEG on a colormapped display) then the original image will be altered. Use a copy of the original if this is a problem.
flattenImages	Image *flattendImage_, InputIterator first_, InputIterator last_	Merge a sequence of image frames which represent image layers into a single composited representation. The flattendImage_ parameter points to an existing Image to update with the flattened image. This function is useful for combining Photoshop layers into a single image.
mapImages	InputIterator first_, InputIterator last_, const Image & mapImage_, bool dither_,  bool measureError_ = false	Replace the colors of a sequence of images with the closest color from a reference image. Set dither_ to true to enable dithering.  Set measureError_ to true in order to evaluate quantization error.
montageImages	Container *montageImages_, InputIterator first_, InputIterator last_, const Montage &montageOpts_	Create a composite image by combining several separate image frames. Multiple frames may be generated in the output container montageImages_ depending on the tile setting and the number of image frames montaged. Montage options are provided via the parameter montageOpts_ . Options set in the first image frame ( backgroundColor, borderColor , matteColor , fillColor, strokeColor, font, and fontPointsize ) are also used as options by montageImages().
morphImages	Container *morphedImages_, InputIterator first_, InputIterator last_, unsigned int frames_	Morph a seqence of image frames. This algorithm  expands the number of image frames (output to the container morphedImages_) by adding the number of intervening frames specified by frames_ such that the original frames morph (blend) into each other when played as an animation.
mosaicImages	Image *mosaicImage_, InputIterator first_, InputIterator last_	Inlay a number of images to form a single coherent picture. The mosicImage_ argument is updated with a mosaic constructed from the image sequence represented by first_ through last_ .
readImages	Container *sequence_, const std::string &imageSpec_	Read a sequence of image frames into existing container (appending to container sequence_) with image names specified in the string imageSpec_.
	Container *sequence_, const Blob &blob_	Read a sequence of image frames into existing container (appending to container sequence_) from Blob blob_.