Magick::Image Class

Quick Contents

Image is the primary object in Magick++ and represents a single image frame (see design ). The STL interface must be used to operate on image sequences or images (e.g. of format GIF, TIFF, MIFF, Postscript, & MNG) which are comprized of multiple image frames. Individual frames of a multi-frame image may be requested by adding array-style notation to the end of the file name (e.g. "animation.gif[3]" retrieves the fourth frame of a GIF animation.  Various image manipulation operations may be applied to the image. Attributes may be set on the image to influence the operation of the manipulation operations. The Pixels class provides low-level access to image pixels. As a convenience, including <Magick++.h> is sufficient in order to use the complete Magick++ API. The Magick++ API is enclosed within the Magick namespace so you must either add the prefix " Magick:: " to each class/enumeration name or add the statement " using namespace Magick;" after including the Magick++.h header.

The preferred way to allocate Image objects is via automatic allocation (on the stack). There is no concern that allocating Image objects on the stack will excessively enlarge the stack since Magick++ allocates all large data objects (such as the actual image data) from the heap. Use of automatic allocation is preferred over explicit allocation (via new) since it is much less error prone and allows use of C++ scoping rules to avoid memory leaks. Use of automatic allocation allows Magick++ objects to be assigned and copied just like the C++ intrinsic data types (e.g. 'int '), leading to clear and easy to read code. Use of automatic allocation leads to naturally exception-safe code since if an exception is thrown, the object is automagically deallocated once the stack unwinds past the scope of the allocation (not the case for objects allocated via new ).

Image is very easy to use. For example, here is a the source to a program which reads an image, crops it, and writes it to a new file (the exception handling is optional but strongly recommended):

#include <Magick++.h> 
#include <iostream> 
using namespace std; 
using namespace Magick; 
int main(int argc,char **argv) 
{ 
  InitializeMagick(*argv);

  // Construct the image object. Seperating image construction from the 
  // the read operation ensures that a failure to read the image file 
  // doesn't render the image object useless. 
  Image image;
  try { 
    // Read a file into image object 
    image.read( "girl.gif" );

    // Crop the image to specified size (width, height, xOffset, yOffset)
    image.crop( Geometry(100,100, 100, 100) );

    // Write the image to a file 
    image.write( "x.gif" ); 
  } 
  catch( Exception &error_ ) 
    { 
      cout << "Caught exception: " << error_.what() << endl; 
      return 1; 
    } 
  return 0; 
}
The following is the source to a program which illustrates the use of Magick++'s efficient reference-counted assignment and copy-constructor operations which minimize use of memory and eliminate unncessary copy operations (allowing Image objects to be efficiently assigned, and copied into containers).  The program accomplishes the following:
  1. Read master image.
  2. Assign master image to second image.
  3. Resize second image to the size 640x480.
  4. Assign master image to a third image.
  5. Resize third image to the size 800x600.
  6. Write the second image to a file.
  7. Write the third image to a file.
#include <Magick++.h> 
#include <iostream> 
using namespace std; 
using namespace Magick; 
int main(int argc,char **argv) 
{ 
  InitializeMagick(*argv);

  Image master("horse.jpg"); 
  Image second = master; 
  second.resize("640x480"); 
  Image third = master; 
  third.resize("800x600"); 
  second.write("horse640x480.jpg"); 
  third.write("horse800x600.jpg"); 
  return 0; 
}
During the entire operation, a maximum of three images exist in memory and the image data is never copied.

The following is the source for another simple program which creates a 100 by 100 pixel white image with a red pixel in the center and writes it to a file:

#include <Magick++.h> 
using namespace std; 
using namespace Magick; 
int main(int argc,char **argv) 
{ 
  InitializeMagick(*argv);
  Image image( "100x100", "white" ); 
  image.pixelColor( 49, 49, "red" ); 
  image.write( "red_pixel.png" ); 
  return 0; 
}
If you wanted to change the color image to grayscale, you could add the lines:
image.quantizeColorSpace( GRAYColorspace ); 
image.quantizeColors( 256 ); 
image.quantize( );

or, more simply:

 image.type( GrayscaleType );

prior to writing the image.

BLOBs

While encoded images (e.g. JPEG) are most often written-to and read-from a disk file, encoded images may also reside in memory. Encoded images in memory are known as BLOBs (Binary Large OBjects) and may be represented using the Blob class. The encoded image may be initially placed in memory by reading it directly from a file, reading the image from a database, memory-mapped from a disk file, or could be written to memory by Magick++. Once the encoded image has been placed within a Blob, it may be read into a Magick++ Image via a constructor or read() . Likewise, a Magick++ image may be written to a Blob via write() .

An example of using Image to write to a Blob follows:
 

#include  
using namespace std; 
using namespace Magick; 
int main(int argc,char **argv) 
{ 
  InitializeMagick(*argv);

  // Read GIF file from disk 
  Image image( "giraffe.gif" );
  // Write to BLOB in JPEG format 
  Blob blob; 
  image.magick( "JPEG" ) // Set JPEG output format 
  image.write( &blob );

  [ Use BLOB data (in JPEG format) here ]

  return 0; 
}


likewise, to read an image from a Blob, you could use one of the following examples:

[ Entry condition for the following examples is that data is pointer to encoded image data and length represents the size of the data ]

Blob blob( data, length ); 
Image image( blob );
or
Blob blob( data, length ); 
Image image; 
image.read( blob);
some images do not contain their size or format so the size and format must be specified in advance:
Blob blob( data, length ); 
Image image; 
image.size( "640x480") 
image.magick( "RGBA" ); 
image.read( blob);

Constructors

Image may be constructed in a number of ways. It may be constructed from a file, a URL, or an encoded image (e.g. JPEG) contained in an in-memory BLOB . The available Image constructors are shown in the following table:
 
 

Image Manipulation Methods

Image supports access to all the single-image (versus image-list) manipulation operations provided by the ImageMagick library. If you must process a multi-image file (such as an animation), the STL interface , which provides a multi-image abstraction on top of Image, must be used.

Image manipulation methods are very easy to use.  For example:

Image image; 
image.read("myImage.tiff"); 
image.addNoise(GaussianNoise); 
image.write("myImage.tiff");
adds gaussian noise to the image file "myImage.tiff".

The operations supported by Image are shown in the following table:
 

Image Attributes

Image attributes are set and obtained via methods in Image. Except for methods which accept pointer arguments (e.g. chromaBluePrimary) all methods return attributes by value.

Image attributes are easily used. For example, to set the resolution of the TIFF file "file.tiff" to 150 dots-per-inch (DPI) in both the horizontal and vertical directions, you can use the following example code:

string filename("file.tiff"); 
Image image; 
image.read(filename); 
image.resolutionUnits(PixelsPerInchResolution); 
image.density(Geometry(150,150));   // could also use image.density("150x150") 
image.write(filename)
The supported image attributes and the method arguments required to obtain them are shown in the following table:
 

Low-Level Image Pixel Access

Image pixels (of type PixelPacket ) may be accessed directly via the Image Pixel Cache .  The image pixel cache is a rectangular window into the actual image pixels (which may be in memory, memory-mapped from a disk file, or entirely on disk). Two interfaces exist to access the Image Pixel Cache. The interface described here (part of the Image class) supports only one view at a time. See the Pixels class for a more abstract interface which supports simultaneous pixel views (up to the number of rows). As an analogy, the interface described here relates to the Pixels class as stdio's gets() relates to fgets(). The Pixels class provides the more general form of the interface.

Obtain existing image pixels via getPixels(). Create a new pixel region using setPixels().

In order to ensure that only the current generation of the image is modified, the Image's modifyImage() method should be invoked to reduce the reference count on the underlying image to one. If this is not done, then it is possible for a previous generation of the image to be modified due to the use of reference counting when copying or constructing an Image.

Depending on the capabilities of the operating system, and the relationship of the window to the image, the pixel cache may be a copy of the pixels in the selected window, or it may be the actual image pixels. In any case calling syncPixels() insures that the base image is updated with the contents of the modified pixel cache. The method readPixels() supports copying foreign pixel data formats into the pixel cache according to the QuantumTypes. The method writePixels() supports copying the pixels in the cache to a foreign pixel representation according to the format specified by QuantumTypes.

The pixel region is effectively a small image in which the pixels may be accessed, addressed, and updated, as shown in the following example:

Image image("cow.png"); // Ensure that there are no other references to this image. image.modifyImage(); // Set the image type to TrueColor DirectClass representation. image.type(TrueColorType); // Request pixel region with size 60x40, and top origin at 20x30 ssize_t columns = 60; PixelPacket *pixel_cache = image.getPixels(20,30,columns,40); // Set pixel at column 5, and row 10 in the pixel cache to red. ssize_t column = 5; ssize_t row = 10; PixelPacket *pixel = pixel_cache+row*columns+column; *pixel = Color("red"); // Save changes to underlying image . image.syncPixels(); // Save updated image to file. image.write("horse.png");

The image cache supports the following methods: