Magick::Image Class

Quick Contents

• BLOBs
• Constructors
• Image Manipulation Methods
• Image Attributes
• Raw Image Pixel Access

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 automatically 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)
{
  // 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
    // (Geometry implicitly initialized by char *)
    image.crop("100x100+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;
}

1. Read master image.
2. Assign master image to second image.
3. Zoom second image to the size 640x480.
4. Assign master image to a third image.
5. Zoom 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)
{
    Image master("horse.jpg");
    Image second = master;
    second.zoom("640x480");
    Image third = master;
    third.zoom("800x600");
    second.write("horse640x480.jpg");
    third.write("horse800x600.jpg");
    return 0;
}

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)
{
    Image image( "100x100", "white" );
    image.pixelColor( 49, 49, "red" );
    image.write( "red_pixel.png" );
    return 0;
}

    image.quantizeColorSpace( GRAYColorspace );
    image.quantizeColors( 256 );
    image.quantize( );

or, more simply:

    image.type( GrayscaleType );

prior to writing the image.

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

#include <Magick++.h>
using namespace std;
using namespace Magick;
int main(int argc,char **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 );

Blob blob( data, length );
Image image;
image.read( blob);

Blob blob( data, length );
Image image;
image.size( "640x480")
image.magick( "RGBA" );
image.read( blob);

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

Image image;
image.read("myImage.tiff");
image.addNoise(GaussianNoise);
image.write("myImage.tiff");

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

Image Image Manipulation Methods

Method	Signature(s)	Description
addNoise	NoiseType noiseType_	Add noise to image with specified noise type.
annotate	const std::string &text_, const Geometry &location_	Annotate using specified text, and placement location
	string text_, const Geometry &boundingArea_, GravityType gravity_	Annotate using specified text, bounding area, and placement gravity. If boundingArea_ is invalid, then bounding area is entire image.
	const std::string &text_, const Geometry &boundingArea_, GravityType gravity_, double degrees_,	Annotate with text using specified text, bounding area, placement gravity, and rotation. If boundingArea_ is invalid, then bounding area is entire image.
	const std::string &text_, GravityType gravity_	Annotate with text (bounding area is entire image) and placement gravity.
blur	const double radius_ = 1, const double sigma_ = 0.5	Blur image. The radius_ parameter specifies the radius of the Gaussian, in pixels, not counting the center pixel.  The sigma_ parameter specifies the standard deviation of the Laplacian, in pixels.
border	const Geometry &geometry_ = "6x6+0+0"	Border image (add border to image).  The color of the border is specified by the borderColor attribute.
channel	ChannelType layer_	Extract channel from image. Use this option to extract a particular channel from  the image.  MatteChannel  for  example, is useful for extracting the opacity values from an image.
charcoal	const double radius_ = 1, const double sigma_ = 0.5	Charcoal effect image (looks like charcoal sketch). The radius_ parameter specifies the radius of the Gaussian, in pixels, not counting the center pixel.  The sigma_ parameter specifies the standard deviation of the Laplacian, in pixels.
chop	const Geometry &geometry_	Chop image (remove vertical or horizontal subregion of image)
colorize	const unsigned int opacityRed_, const unsigned int opacityGreen_, const unsigned int opacityBlue_, const Color &penColor_	Colorize image with pen color, using specified percent opacity for red, green, and blue quantums.
	const unsigned int opacity_, const Color &penColor_	Colorize image with pen color, using specified percent opacity.
comment	const string &comment_	Comment image (add comment string to image).  By default, each image is commented with its file name. Use  this  method to  assign a specific comment to the image.  Optionally you can include the image filename, type, width, height, or other  image  attributes by embedding special format characters.
composite	const Image &compositeImage_, int xOffset_, int yOffset_, CompositeOperator compose_ = InCompositeOp	Compose an image onto the current image at offset specified by xOffset_, yOffset_ using the composition algorithm specified by compose_.
	const Image &compositeImage_, const Geometry &offset_, CompositeOperator compose_ = InCompositeOp	Compose an image onto the current image at offset specified by offset_ using the composition algorithm specified by compose_.
	const Image &compositeImage_, GravityType gravity_, CompositeOperator compose_ = InCompositeOp	Compose an image onto the current image with placement specified by gravity_ using the composition algorithm specified by compose_.
contrast	unsigned int sharpen_	Contrast image (enhance intensity differences in image)
convolve	unsigned int order_, const double *kernel_	Convolve image.  Applies a user-specfied convolution to the image. The order_ parameter represents the number of columns and rows in the filter kernel, and kernel_ is a two-dimensional array of doubles representing the convolution kernel to apply.
crop	const Geometry &geometry_	Crop image (subregion of original image)
cycleColormap	int amount_	Cycle image colormap
despeckle	void	Despeckle image (reduce speckle noise)
display	void	Display image on screen. 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.
draw	const Drawable &drawable_	Draw shape or text on image.
	const std::list<Drawable> &drawable_	Draw shapes or text on image using a set of Drawable objects contained in an STL list. Use of this method improves drawing performance and allows batching draw objects together in a list for repeated use.
edge	unsigned int radius_ = 0.0	Edge image (hilight edges in image).  The radius is the radius of the pixel neighborhood.. Specify a radius of zero for automatic radius selection.
emboss	const double radius_ = 1, const double sigma_ = 0.5	Emboss image (hilight edges with 3D effect). The radius_ parameter specifies the radius of the Gaussian, in pixels, not counting the center pixel.  The sigma_ parameter specifies the standard deviation of the Laplacian, in pixels.
enhance	void	Enhance image (minimize noise)
equalize	void	Equalize image (histogram equalization)
erase	void	Set all image pixels to the current background color.
flip	void	Flip image (reflect each scanline in the vertical direction)
floodFill- Color	unsigned int x_, unsigned int y_, const Color &fillColor_	Flood-fill color across pixels that match the color of the target pixel and are neighbors of the target pixel. Uses current fuzz setting when determining color match.
	const Geometry &point_, const Color &fillColor_
	unsigned int x_, unsigned int y_, const Color &fillColor_, const Color &borderColor_	Flood-fill color across pixels starting at target-pixel and stopping at pixels matching specified border color. Uses current fuzz setting when determining color match.
	const Geometry &point_, const Color &fillColor_, const Color &borderColor_
floodFillOpacity	const long x_, const long y_, const unsigned int opacity_, const PaintMethod method_	Floodfill pixels matching color (within fuzz factor) of target pixel(x,y) with replacement opacity value using method.
floodFill- Texture	unsigned int x_, unsigned int y_,  const Image &texture_	Flood-fill texture across pixels that match the color of the target pixel and are neighbors of the target pixel. Uses current fuzz setting when determining color match.
	const Geometry &point_, const Image &texture_
	unsigned int x_, unsigned int y_, const Image &texture_, const Color &borderColor_	Flood-fill texture across pixels starting at target-pixel and stopping at pixels matching specified border color. Uses current fuzz setting when determining color match.
	const Geometry &point_, const Image &texture_, const Color &borderColor_
flop	void	Flop image (reflect each scanline in the horizontal direction)
frame	const Geometry &geometry_ = "25x25+6+6"	Add decorative frame around image
	unsigned int width_, unsigned int height_, int x_, int y_, int innerBevel_ = 0, int outerBevel_ = 0
gamma	double gamma_	Gamma correct image (uniform red, green, and blue correction).
	double gammaRed_, double gammaGreen_, double gammaBlue_	Gamma correct red, green, and blue channels of image.
gaussianBlur	const double width_, const double sigma_	Gaussian blur image. The number of neighbor pixels to be included in the convolution mask is specified by 'width_'.  For example, a width of one gives a (standard) 3x3 convolution mask. The standard deviation of the gaussian bell curve is specified by 'sigma_'.
implode	const double factor_	Implode image (special effect)
label	const string &label_	Assign a label to an image. Use this option to  assign  a  specific label to the image. Optionally you can include the image filename, type, width, height, or scene number in the label by embedding  special format characters. If the first character of string is @, the image label is read from a file titled by the remaining characters in the string. When converting to Postscript, use this  option to specify a header string to print above the image.
magnify	void	Magnify image by integral size
map	const Image &mapImage_ , bool dither_ = false	Remap image colors with closest color from reference image. Set dither_ to true in to apply Floyd/Steinberg error diffusion to the image. By default, color reduction chooses an optimal  set  of colors that best represent the original image. Alternatively, you can  choose  a  particular  set  of colors  from  an image file with this option.
matteFloodfill	const Color &target_, const unsigned int  opacity_, const int x_, const int y_, PaintMethod method_	Floodfill designated area with a replacement opacity value.
medianFilter	const double radius_ = 0.0	Filter image by replacing each pixel component with the median color in a circular neighborhood
minify	void	Reduce image by integral size
modifyImage	void	Prepare to update image. Ensures that there is only one reference to the underlying image so that the underlying image may be safely modified without effecting previous generations of the image. Copies the underlying image to a new image if necessary.
modulate	double brightness_, double saturation_, double hue_	Modulate percent hue, saturation, and brightness of an image
negate	bool grayscale_ = false	Negate colors in image.  Replace every pixel with its complementary color (white becomes black, yellow becomes blue, etc.).  Set grayscale to only negate grayscale values in image.
normalize	void	Normalize image (increase contrast by normalizing the pixel values to span the full range of color values).
oilPaint	unsigned int radius_ = 3	Oilpaint image (image looks like oil painting)
opacity	unsigned int opacity_	Set or attenuate the opacity channel in the image. If the image pixels are opaque then they are set to the specified opacity value, otherwise they are blended with the supplied opacity value.  The value of opacity_ ranges from 0 (completely opaque) to MaxRGB. The defines OpaqueOpacity and TransparentOpacity are available to specify completely opaque or completely transparent, respectively.
opaque	const Color &opaqueColor_, const Color &penColor_	Change color of pixels matching opaqueColor_ to specified penColor_.
ping	const std::string &imageSpec_	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.
	const Blob &blob_
quantize	bool measureError_ = false	Quantize image (reduce number of colors). Set measureError_ to true in order to calculate error attributes.
raise	const Geometry &geometry_ = "6x6+0+0",  bool raisedFlag_ =  false	Raise image (lighten or darken the edges of an image to give a 3-D raised or lowered effect)
read	const string &imageSpec_	Read image into current object
	const Geometry &size_, const std::string &imageSpec_	Read image of specified size into current object. This form is useful for images that do not specifiy their size or to specify a size hint for decoding an image. For example, when reading a Photo CD, JBIG, or JPEG image, a size request causes the library to return an image which is the next resolution greater or equal to the specified size. This may result in memory and time savings.
	const Blob &blob_	Read encoded image of specified size from an in-memory BLOB into current object. Depending on the method arguments, the Blob size, depth, and format may also be specified. Some image formats require that size be specified. The default ImageMagick uses for depth depends on its Quantum size (8 or 16).  If ImageMagick's Quantum size does not match that of the image, the depth may need to be specified. ImageMagick can usually automatically detect the image's format. When a format can't be automatically detected, the format must be specified.
	const Blob &blob_, const Geometry &size_
	const Blob &blob_, const Geometry &size_, unsigned int depth_
	const Blob &blob_, const Geometry &size_, unsigned short depth_, const string &magick_
	const Blob &blob_, const Geometry &size_, const string &magick_
	const unsigned int width_, const unsigned int height_, std::string map_, const StorageType type_, const void *pixels_	Read image based on an array of image pixels. The pixel data must be in scanline order top-to-bottom. The data can be character, short int, integer, float, or double. Float and double require the pixels to be normalized [0..1]. The other types are [0..MaxRGB].  For example, to create a 640x480 image from unsigned red-green-blue character data, use   image.read( 640, 480, "RGB", 0, pixels ); The parameters are as follows:   width_ Width in pixels of the image. height_ Height in pixels of the image. map_ This character string can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow M = magenta, and K = black. The ordering reflects the order of the pixels in the supplied pixel array. type_ Pixel storage type (CharPixel, ShortPixel, IntegerPixel, FloatPixel, or DoublePixel) pixels_ This array of values contain the pixel components as defined by the map_ and type_ parameters. The length of the arrays must equal the area specified by the width_ and height_ values and type_ parameters.
reduceNoise	void	Reduce noise in image using a noise peak elimination filter.
	unsigned int order_
roll	int columns_, int rows_	Roll image (rolls image vertically and horizontally) by specified number of columnms and rows)
rotate	double degrees_	Rotate image counter-clockwise by specified number of degrees.
sample	const Geometry &geometry_	Resize image by using pixel sampling algorithm
scale	const Geometry &geometry_	Resize image by using simple ratio algorithm
segment	double clusterThreshold_ = 1.0, double smoothingThreshold_ = 1.5	Segment (coalesce similar image components) by analyzing the histograms of the color components and identifying units that are homogeneous with the fuzzy c-means technique. Also uses quantizeColorSpace and verbose image attributes. Specify clusterThreshold_, as the number  of  pixels  each cluster  must exceed the cluster threshold to be considered valid. SmoothingThreshold_ eliminates noise in the  second derivative of the histogram. As the value is  increased, you can  expect  a  smoother second derivative.  The default is 1.5.
shade	double azimuth_ = 30, double elevation_ = 30, bool colorShading_ = false	Shade image using distant light source. Specify azimuth_ and elevation_ as the  position  of  the light source. By default, the shading results as a grayscale image.. Set colorShading_ to true to shade the red, green, and blue components of the image.
sharpen	const double radius_ = 1, const double sigma_ = 0.5	Sharpen pixels in image.  The radius_ parameter specifies the radius of the Gaussian, in pixels, not counting the center pixel.  The sigma_ parameter specifies the standard deviation of the Laplacian, in pixels.
shave	const Geometry &geometry_	Shave pixels from image edges.
shear	double xShearAngle_, double yShearAngle_	Shear image (create parallelogram by sliding image by X or Y axis).  Shearing slides one edge of an image along the X  or  Y axis,  creating  a parallelogram.  An X direction shear slides an edge along the X axis, while  a  Y  direction shear  slides  an edge along the Y axis.  The amount of the shear is controlled by a shear angle.  For X direction  shears,  x  degrees is measured relative to the Y axis, and similarly, for Y direction shears  y  degrees is measured relative to the X axis. Empty triangles left over from shearing the  image  are filled  with  the  color  defined as borderColor.
solarize	double factor_ = 50.0	Solarize image (similar to effect seen when exposing a photographic film to light during the development process)
spread	unsigned int amount_ = 3	Spread pixels randomly within image by specified amount
stegano	const Image &watermark_	Add a digital watermark to the image (based on second image)
stereo	const Image &rightImage_	Create an image which appears in stereo when viewed with red-blue glasses (Red image on left, blue on right)
swirl	double degrees_	Swirl image (image pixels are rotated by degrees)
texture	const Image &texture_	Layer a texture on pixels matching image background color.
threshold	double threshold_	Threshold image
transform	const Geometry &imageGeometry_	Transform image based on image and crop geometries. Crop geometry is optional.
	const Geometry &imageGeometry_, const Geometry &cropGeometry_
transparent	const Color &color_	Add matte image to image, setting pixels matching color to transparent.
trim	void	Trim edges that are the background color from the image.
unsharpmask	double radius_, double sigma_, double amount_, double threshold_	Replace image with a sharpened version of the original image using the unsharp mask algorithm. The radius_ parameter specifies the radius of the Gaussian, in pixels, not counting the center pixel. The sigma_ parameter specifies the standard deviation of the Gaussian, in pixels. The amount_ parameter specifies the percentage of the difference between the original and the blur image that is added back into the original. The threshold_ parameter specifies the threshold in pixels needed to apply the diffence amount.
wave	double amplitude_ = 25.0, double wavelength_ = 150.0	Alter an image along a sine wave.
write	const string &imageSpec_	Write image to a file using filename imageSpec_. Caution: 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.
	Blob *blob_	Write image to a in-memory BLOBstored in blob_. The magick_ parameter specifies the image format to write (defaults to magick ). The depth_ parameter species the image depth (defaults to depth). Caution: 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.
	Blob *blob_, std::string &magick_
	Blob *blob_, std::string &magick_, unsigned int depth_
	const int x_, const int y_, const unsigned int columns_, const unsigned int rows_, const std::string &map_, const StorageType type_, void *pixels_	Write pixel data into a buffer you supply. The data is saved either as char, short int, integer, float or double format in the order specified by the type_ parameter. For example, we want to extract scanline 1 of a 640x480 image as character data in red-green-blue order:   image.write(0,0,640,1,"RGB",0,pixels); The parameters are as follows:   x_ Horizontal ordinate of left-most coordinate of region to extract. y_ Vertical ordinate of top-most coordinate of region to extract. columns_ Width in pixels of the region to extract. rows_ Height in pixels of the region to extract. map_ This character string can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, and K = black. The ordering reflects the order of the pixels in the supplied pixel array. type_ Pixel storage type (CharPixel, ShortPixel, IntegerPixel, FloatPixel, or DoublePixel) pixels_ This array of values contain the pixel components as defined by the map_ and type_ parameters. The length of the arrays must equal the area specified by the width_ and height_ values and type_ parameters.
zoom	const Geometry &geometry_	Zoom image to specified size.

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)

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

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"); // Obtain pixel region with size 60x40, and top origin at 20x30 int 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. int column = 5; int row = 10; PixelPacket *pixel = pixel_cache+row*columns*sizeof(PixelPacket)+column; pixel = Color("red"); // Save updated pixel cache back to underlying image image.syncPixels(); image.write("horse.png");

The image cache supports the following methods:
 

Image Cache Methods

Method	Returns	Signature	Description
getConstPixels	const PixelPacket*	const int x_, const int y_, const unsigned int columns_, const unsigned int rows_	Transfers pixels from the image to the pixel cache as defined by the specified rectangular region.
getConstIndexes	const IndexPacket*	void	Returns a pointer to the Image pixel indexes. Only valid for PseudoClass images or CMYKA images. The pixel indexes represent an array of type IndexPacket, with each entry corresponding to an x,y pixel position. For PseudoClass images, the entry's value is the offset into the colormap (see colorMap) for that pixel. For CMYKA images, the indexes are used to contain the alpha channel.
getIndexes	IndexPacket*	void	Returns a pointer to the Image pixel indexes corresponding to the pixel region requested by the last getConstPixels, getPixels, or setPixels call. Only valid for PseudoClass images or CMYKA images. The pixel indexes represent an array of type IndexPacket, with each entry corresponding to a pixel x,y position. For PseudoClass images, the entry's value is the offset into the colormap (see colorMap)  for that pixel. For CMYKA images, the indexes are used to contain the alpha channel.
getPixels	PixelPacket*	const int x_, const int y_, const unsigned int columns_, const unsigned int rows_	Transfers pixels from the image to the pixel cache as defined by the specified rectangular region. Modified pixels may be subsequently transferred back to the image via syncPixels.
setPixels	PixelPacket*	const int x_, const int y_, const unsigned int columns_, const unsigned int rows_	Allocates a pixel cache region to store image pixels as defined by the region rectangle.  This area is subsequently transferred from the pixel cache to the image via syncPixels.
syncPixels	void	void	Transfers the image cache pixels to the image.
readPixels	void	QuantumTypes quantum_, unsigned char *source_,	Transfers one or more pixel components from a buffer or file into the image pixel cache of an image. ReadPixels is typically used to support image decoders.
writePixels	void	QuantumTypes quantum_, unsigned char *destination_	Transfers one or more pixel components from the image pixel cache to a buffer or file. WritePixels is typically used to support image encoders.