  
  
  
  
  
 Magick::Image Class
 Quick Contents
  
 #BLOBsBLOBs    
 #ConstructorsConstructors    
 #Image Manipulation MethodsImage Manipulation
Methods
   
 #Image AttributesImage Attributes    
 #Raw Image Pixel AccessLow-Level Image Pixel
Access
 Image is the primary object in Magick++ and represents
a single image frame (see 
ImageDesign.htmldesign  ). The STL.htmlSTL 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.html 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++.hheader.
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
 (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:
  
 Read master image.  
 Assign master image to second image.  
 Zoom second image to the size 640x480.  
 Assign master image to a third image.  
 Zoom third image to the size 800x600.  
 Write the second image to a file.  
 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;   
}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)   
{   
    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.htmlBlob  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_blobconstructor  or #readread() . Likewise, a Magick++ image may be written to a Blob via 
#write write()  .
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 lengthrepresents 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.html BLOB  . The available Image
constructors are shown in the following table: 
  
 
  
Image Constructors     
      
      
Signature      
      
      
Description      
    
    
      
const std::string &imageSpec_       
Construct Image by reading from file or URL
specified by 
imageSpec_. Use array notation (e.g. filename[9])
to select a  specific scene from a multi-frame image.
    
    
      
const Geometry &size_, const Color.html Color  &color_       
Construct a blank image canvas of specified
size and  color
    
    
      
 const Blob.htmlBlob  &blob_       
Construct Image by reading from
encoded image data contained in an in-memory 
Blob.htmlBLOB . Depending on the constructor arguments, the Blob 
#sizesize , 
#depthdepth  , #magickmagick  (format) may
also be specified. Some image formats require that size  be  specified.
The default ImageMagick uses for depth depends on the compiled-in
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 (
#magickmagick  ) must be specified.     
    
      
const Blob.htmlBlob &blob_, const 
Geometry.htmlGeometry  &size_     
    
      
const Blob.htmlBlob &blob_, const 
Geometry.htmlGeometry  &size,
unsigned int depth
    
    
      
const Blob.htmlBlob &blob_, const 
Geometry.htmlGeometry  &size,
unsigned int depth_, const string &magick_
    
    
      
const Blob.htmlBlob &blob_, const 
Geometry.htmlGeometry  &size, const
string &magick_
    
    
      
const unsigned int width_,        
const unsigned int height_,       
std::string map_,       
const Enumerations.html#StorageTypeStorageType
 type_,       
const void *pixels_       
Construct a new 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 image( 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_             
Enumerations.html#StorageTypePixel
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.
          
        
      
      
      
    
  
  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.html 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 Image Manipulation Methods     
      
Method       
Signature(s)       
Description     
    
      
      
 adaptiveThreshold      
      
      
unsigned int width,  unsigned
int height, unsigned offset = 0
      
      
Apply adaptive thresholding  to
the image. Adaptive thresholding is useful if the ideal threshold level
is not known in advance, or if the illumination gradient is not constant
across the image. Adaptive thresholding works by evaulating the mean
(average) of a pixel region (size specified by 
width and height)
and using the mean as the thresholding value. In order to remove
residual noise from the background, the threshold may be adjusted by
subtracting a constant 
offset (default zero) from the mean to
compute the threshold.
      
    
    
      
      
 addNoise      
      
Enumerations.html#NoiseTypeNoiseType noiseType_
      
Add noise to image with specified noise type.     
    
      
affineTransform      
      
const DrawableAffine
&affine
      
      
Transform image by
specified affine (or free transform) matrix.
      
    
    
      
      
 annotate      
      
const std::string &text_, const Geometry.html Geometry  &location_       
Annotate using specified text, and placement
location
    
    
      
string text_, const Geometry.htmlGeometry &boundingArea_, 
Enumerations.html#GravityTypeGravityType 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.html Geometry  &boundingArea_, Enumerations.html#GravityTypeGravityType  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_, Enumerations.html#GravityType 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.htmlGeometry &geometry_ = "6x6+0+0"
      
Border image (add border to image).  The
color of the border is specified by the 
borderColor attribute.     
    
      
      
 channel      
      
Enumerations.html#ChannelTypeChannelType 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.htmlGeometry &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 
FormatCharacters.htmlspecial format characters.      
    
      
 compare      
      
const Image &reference_      
      
Compare current image  with
another image. Sets 
#meanErrorPerPixelmeanErrorPerPixel  , #normalizedMaxErrornormalizedMaxError  , and #normalizedMeanErrornormalizedMeanError  in the current
image. False is returned if the images are identical. An  ErrorOption
exception is thrown if the reference image columns, rows, colorspace, or
matte differ from the current image.
      
    
    
      
      
 composite      
      
const Image.htmlImage &compositeImage_, int xOffset_, int yOffset_, 
Enumerations.html#CompositeOperator 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.htmlImage &compositeImage_, const 
Geometry.htmlGeometry &offset_, 
Enumerations.html#CompositeOperatorCompositeOperator compose_ = 
InCompositeOp       
Compose an image onto the current image at
offset specified  by 
offset_ using the composition algorithm
specified by 
compose_ .     
    
      
const Image.htmlImage &compositeImage_, 
Enumerations.html#GravityTypeGravityType gravity_, 
Enumerations.html#CompositeOperatorCompositeOperator 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.htmlGeometry &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 compatible   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.htmlDrawable &drawable_
      
Draw shape or text on image.     
    
      
const std::list< Drawable.htmlDrawable > &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.html 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.htmlGeometry &point_, const 
Color.htmlColor  &fillColor_     
    
      
unsigned int x_, unsigned int y_, const Color.html Color  &fillColor_, const Color.htmlColor &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.htmlGeometry &point_, const 
Color.htmlColor  &fillColor_, const Color.htmlColor  &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.htmlGeometry &point_, const Image &texture_
    
    
      
unsigned int x_, unsigned int y_, const Image
&texture_, const 
Color.htmlColor  &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.htmlGeometry &point_, const Image &texture_, const 
Color.html Color &borderColor_
    
    
      
      
 flop      
      
void       
Flop image (reflect each scanline in the
horizontal direction)
    
    
      
      
 frame      
      
const Geometry.htmlGeometry &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  
FormatCharacters.htmlspecial 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.
    
    
      
level      
      
const double black_point,
const double white_point, const double mid_point=1.0
      
      
Level image. Adjust the
levels of the image by scaling the colors falling between specified
white and black points to the full available quantum range. The
parameters provided represent the black, mid (gamma), and white
points.  The black point specifies the darkest color in the image.
Colors darker than the black point are set to zero. Mid point (gamma)
specifies a gamma correction to apply to the image. White point
specifies the lightest color in the image.  Colors brighter than
the white point are set to the maximum quantum value. The black and
white point have the valid range 0 to MaxRGB while mid (gamma) has a
useful range of 0 to ten.
      
    
    
      
levelChannel      
      
const ChannelType
channel, const double black_point, const double white_point, const
double mid_point=1.0
      
      
Level image channel.
Adjust the levels of the image channel by scaling the values falling
between specified white and black points to the full available quantum
range. The parameters provided represent the black, mid (gamma), and
white points. The black point specifies the darkest color in the image.
Colors darker than the black point are set to zero. Mid point (gamma)
specifies a gamma correction to apply to the image. White point
specifies the lightest color in the image. Colors brighter than the
white point are set to the maximum quantum value. The black and white
point have the valid range 0 to MaxRGB while mid (gamma) has a useful
range of 0 to ten.
      
    
    
      
      
 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.htmlColor &target_, const unsigned int  opacity_, const int x_, const int
y_, 
Enumerations.html#PaintMethodPaintMethod  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. Modulation of saturation and brightness is as a
ratio of the current value (1.0 for no change). Modulation of hue is an
absolute rotation of -180 degrees to +180 degrees from the current
position corresponding to an argument range of 0 to 2.0 (1.0 for no
change).
    
    
      
      
 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.htmlColor &opaqueColor_, const 
Color.htmlColor  &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 
#columnscolumns  , #rowsrows  , and #fileSizefileSize attributes are valid after invoking ping.  The image data is not
valid after calling ping.
    
    
      
const Blob &blob_     
    
      
process      
      
std::string name_,
const int argc_, char **argv_
      
      
Execute the named
process module, passing any arguments via an argument vector, with argc_
specifying the number of arguments in the vector, and argv_ passing the
address of an array of null-terminated C strings which constitute the
argument vector. An exception is thrown if the requested process module
does not exist, fails to load, or fails during execution.
      
    
    
      
      
 quantize      
      
bool measureError_ = false       
Quantize image (reduce number of colors). Set
measureError_ to true in order to calculate error attributes.
    
    
      
      
 raise      
      
const Geometry.htmlGeometry &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.htmlGeometry &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.htmlBlob  &blob_       
Read encoded image of specified
size from  an in-memory 
Blob.htmlBLOB  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.htmlBlob &blob_, const 
Geometry.htmlGeometry  &size_     
    
      
const Blob.htmlBlob &blob_, const 
Geometry.htmlGeometry  &size_,
unsigned int depth_
    
    
      
const Blob.htmlBlob &blob_, const 
Geometry.htmlGeometry  &size_,
unsigned short depth_, const string &magick_ 
    
    
      
const Blob.htmlBlob &blob_, const 
Geometry.htmlGeometry  &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.htmlGeometry &geometry_ 
      
Resize image by using pixel sampling algorithm     
    
      
      
 scale      
      
const Geometry.htmlGeometry &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 
quantizeColorSpaceand 
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 c
olorShading_ 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.htmlGeometry &imageGeometry_
      
Transform image based on image
and crop   geometries. Crop geometry is optional.
    
    
      
const Geometry.htmlGeometry &imageGeometry_, const 
Geometry.htmlGeometry &cropGeometry_ 
    
    
      
      
 transparent      
      
const Color.htmlColor &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.htmlBlob  *blob_       
Write image to a in-memory Blob.html BLOB  stored in blob_. The magick_
parameter specifies the image   format to write (defaults to 
#magickmagick  ). The depth_ parameter species the image
depth (defaults to 
#depth 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.htmlBlob  *blob_,
std::string &magick_
    
    
      
Blob.htmlBlob  *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.htmlGeometry &geometry_
      
Zoom image to specified size.     
  
  Image Attributes
Image attributes are set and obtained via methods in Image. Except for
methods which accept pointer arguments (e.g. c
hromaBluePrimary)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: 
 
  
Image Attributes     
      
      
Function      
      
      
Type      
      
      
Get Signature      
      
      
Set Signature      
      
      
Description      
    
    
      
      
 adjoin      
      
bool       
void       
bool flag_       
Join images into a single multi-image file.     
    
      
      
 antiAlias      
      
bool       
void       
bool flag_       
Control antialiasing of rendered Postscript
and Postscript   or TrueType fonts. Enabled by default.
    
    
      
      
 animation-       
Delay      
      
unsigned int (0 to 65535)       
void       
unsigned int delay_       
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.
    
    
      
      
 animation-       
Iterations      
      
unsigned int       
void       
unsigned int iterations_       
Number of iterations to loop an animation
(e.g. Netscape   loop extension) for.
    
    
      
attribute      
      
string      
      
const
std::string name_
      
      
const
std::string name_, const std::string value_
      
An arbitrary named
image attribute. Any number of named attributes may be attached to the
image. For example, the image comment is a named image attribute with
the name "comment". EXIF tags are attached to the image as named
attributes. Use the syntax "[EXIF:<tag>]" to request an EXIF tag
similar to "[EXIF:DateTime]".
      
    
    
      
      
 background-       
Color      
      
Color.htmlColor        
void       
const Color.htmlColor &color_
      
Image background color     
    
      
      
 background-       
Texture      
      
string       
void       
const string &texture_       
Image file name to use as the background
texture. Does  not modify image pixels.
    
    
      
      
 baseColumns      
      
unsigned int       
void       
       
Base image width (before transformations)     
    
      
      
 baseFilename      
      
string       
void       
       
Base image filename (before transformations)     
    
      
      
 baseRows      
      
unsigned int       
void       
       
Base image height (before transformations)     
    
      
      
 borderColor      
      
Color.htmlColor        
void       
 const Color.htmlColor &color_
      
Image border color     
    
      
 boundingBox       
Geometry       
void       
       
Return smallest bounding box enclosing
non-border pixels.  The current fuzz value is used when discriminating
between pixels.   This is the crop bounding box used by
crop(Geometry(0,0)).
    
    
      
      
 boxColor      
      
Color.htmlColor        
void       
const Color.htmlColor &boxColor_
      
Base color that annotation text is rendered
on.
    
    
      
 cacheThreshold       
unsigned int       
       
const int       
Pixel cache threshold in megabytes. Once this
threshold is exceeded, all subsequent pixels cache operations are
to/from disk. This    is a static method and the attribute it sets is
shared by all Image objects.
    
    
      
channelDepth      
      
unsigned
int
      
      
const
ChannelType channel_
      
      
const ChannelType
channel_, const unsigned int depth_
      
      
Channel modulus depth.
The channel modulus depth represents the minimum number of bits required
to support the channel without loss. Setting the channel's modulus depth
modifies the channel (i.e. discards resolution) if the requested modulus
depth is less than the current modulus depth, otherwise the channel is
not altered. There is no attribute associated with the modulus depth so
the current modulus depth is obtained by inspecting the pixels. As a
result, the depth returned may be less than the most recently set
channel depth. Subsequent image processing may result in increasing the
channel depth.
      
    
    
      
      
 chroma-       
BluePrimary      
      
double x & y       
double *x_, double *y_       
double x_, double y_       
Chromaticity blue primary point (e.g. x=0.15,
y=0.06)
    
    
      
      
 chroma-       
GreenPrimary      
      
double x & y       
double *x_, double *y_       
double x_, double y_       
Chromaticity green primary point (e.g. x=0.3,
y=0.6)
    
    
      
      
 chroma-       
RedPrimary      
      
double x & y       
double *x_, double *y_       
double x_, double y_       
Chromaticity red primary point (e.g. x=0.64,
y=0.33)
    
    
      
      
 chroma-       
WhitePoint      
      
double x & y       
double*x_, double *y_       
double x_, double y_       
Chromaticity white point (e.g. x=0.3127,
y=0.329)
    
    
      
      
 classType      
      
Enumerations.html#ClassTypeClassType        
void       
 Enumerations.html#ClassTypeClassType class_
      
Image storage class.  Note that
conversion from   a DirectClass image to a PseudoClass image may result
in a loss of  color  due to the limited size of the palette (256 or
65535 colors).
    
    
      
      
 clipMask      
      
Image       
void       
const Image &clipMask_       
Associate a clip mask image with the current
image. The clip mask image must have the same dimensions as the current
image or   an exception is thrown. Clipping occurs wherever pixels are
transparent in  the clip mask image. Clipping Pass an invalid image to
unset an existing   clip mask.
    
    
      
      
 colorFuzz      
      
double       
void       
double fuzz_       
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.
    
    
      
      
 colorMap      
      
Color.htmlColor        
unsigned int index_       
unsigned int index_, const Color.html Color  &color_       
Color at colormap index.     
    
      
      
 colorMapSize      
      
      
unsigned int      
      
void      
      
unsigned int entries_      
      
Number of entries in the
colormap. Setting the colormap size may extend or truncate the colormap.
The maximum number of supported entries is specified by the 
MaxColormapSizeconstant,
and is dependent on the value of QuantumDepth when ImageMagick is
compiled. An exception is thrown if more entries are requested than may
be supported. Care should be taken when truncating the colormap to
ensure that the image colormap indexes reference valid colormap entries.
      
    
    
      
      
 colorSpace      
      
Enumerations.html#ColorspaceTypeColorspaceType colorSpace_
      
void       
Enumerations.html#ColorspaceTypeColorspaceType colorSpace_
      
The colorspace (e.g. CMYK) used to represent
the image  pixel colors. Image pixels are always stored as RGB(A) except
for the case  of CMY(K).
    
    
      
      
 columns      
      
unsigned int       
void       
       
Image width     
    
      
      
 comment      
      
string       
void       
       
Image comment     
    
      
      
 compose      
      
Enumerations.html#CompositeOperatorCompositeOperator        
void       
Enumerations.html#CompositeOperatorCompositeOperator compose_
      
Composition operator to be used when
composition is implicitly used (such as for image flattening).
    
    
      
      
 compress-       
Type      
      
Enumerations.html#CompressionTypeCompressionType        
void       
Enumerations.html#CompressionTypeCompressionType compressType_
      
Image compresion type. The default is the
compression type of the specified image file.
    
    
      
      
 debug      
      
bool       
void       
bool flag_       
Enable printing of internal debug messages
from ImageMagick   as it executes.
    
    
      
defineValue      
      
string      
      
const std::string
&magick_, const std::string &key_
      
      
const std::string
&magick_, const std::string &key_,  const std::string
&value_
      
      
Set or obtain a
definition string to applied when encoding or decoding the specified
format. The meanings of the definitions are format specific. The format
is designated by the 
magick_argument, the format-specific key is designated by 
key_, and the associated value is
specified by 
value_. See the
defineSet() method if the key must be removed entirely.
      
    
    
      
defineSet      
      
bool      
      
const std::string
&magick_, const std::string &key_
      
      
const std::string
&magick_, const std::string &key_, bool flag_
      
      
Set or obtain a
definition flag to applied when encoding or decoding the specified
format.
. Similar to the defineValue() method except that
passing the 
flag_ value 'true'
creates a value-less define with that format and key. Passing the 
flag_value 'false' removes any existing matching definition. The method
returns 'true' if a matching key exists, and 'false' if no matching key
exists.
      
    
    
      
      
 density      
      
Geometry.htmlGeometry   
(default 72x72)
      
void       
const Geometry.htmlGeometry &density_
      
Vertical and horizontal resolution in pixels
of the  image. This option specifies an image density when decoding a
Postscript or Portable Document page. Often used with 
psPageSize.     
    
      
      
 depth      
      
 unsigned int (8, 16, or 32)       
void       
unsigned int depth_       
Image depth. Used to specify the bit depth
when reading   or writing  raw images or when the output format
supports multiple depths. Defaults to the quantum depth that
ImageMagick is compiled with.
    
    
      
      
 endian      
      
Enumerations.html#EndianTypeEndianType        
void       
Enumerations.html#EndianTypeEndianType endian_
      
Specify (or obtain) endian option for formats
which support it.
    
    
      
      
 directory      
      
string       
void       
       
Tile names from within an image montage     
    
      
      
 fileName      
      
string       
void       
const string &fileName_       
Image file name.     
    
      
      
 fileSize      
      
off_t       
void       
       
Number of bytes of the image on disk     
    
      
      
 fillColor      
      
Color       
void       
const Color &fillColor_       
Color to use when filling drawn objects     
    
      
      
 fillPattern      
      
Image       
void       
const Image &fillPattern_       
Pattern image to use when filling drawn
objects.
    
    
      
      
 fillRule      
      
Enumerations.html#FillRuleFillRule        
void       
const Magick::FillRule &fillRule_       
Rule to use when filling drawn objects.     
    
      
      
 filterType      
      
Enumerations.html#FilterTypesFilterTypes        
void       
Enumerations.html#FilterTypesFilterTypes filterType_
      
Filter to use when resizing image. The
reduction filter  employed has a sigificant effect on the time required
to resize an  image and the resulting quality. The default filter is 
Lanczoswhich has been shown to produce high quality results when reducing most
images.
    
    
      
      
 font      
      
string       
void       
const string &font_       
Text rendering font. If the font is a fully
qualified X server font name, the font is obtained from an X 
server. To use  a TrueType font, precede the TrueType filename with an
@. Otherwise, specify     a  Postscript font name (e.g.
"helvetica").
    
    
      
      
 fontPointsize      
      
unsigned int       
void       
unsigned int pointSize_       
Text rendering font point size     
    
      
      
 fontTypeMetrics      
      
TypeMetric.htmlTypeMetric        
const std::string &text_, TypeMetric.html TypeMetric  *metrics       
       
Update metrics with font type metrics using
specified 
text, and current #fontfont  and #fontPointsizefontPointSize  settings.     
    
      
      
 format      
      
string       
void       
       
Long form image format description.     
    
      
      
 gamma      
      
double (typical range 0.8 to 2.3)       
void       
       
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      
      
Geometry.htmlGeometry        
void       
       
Preferred size of the image when encoding.     
    
      
      
 gifDispose-       
Method      
      
unsigned int       
{ 0 = Disposal not specified,       
1 = Do not dispose of graphic,       
3 = Overwrite graphic with background   color,       
4 = Overwrite graphic with previous   graphic. }       
void       
unsigned int disposeMethod_       
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.
    
    
      
      
 iccColorProfile      
      
Blob.htmlBlob        
void       
const Blob.htmlBlob &colorProfile_
      
ICC color profile. Supplied via a Blob.html Blob  since Magick++/ and ImageMagick do not
currently support formating this   data structure directly. 
Specifications are available from the 
http://www.color.org/International Color Consortium
 for the format of ICC color profiles.     
    
      
      
 interlace-       
Type      
      
Enumerations.html#InterlaceTypeInterlaceType        
void       
Enumerations.html#InterlaceTypeInterlaceType interlace_
      
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. 
NoInterlacemeans 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.     
    
      
      
 iptcProfile      
      
Blob.htmlBlob        
void       
const Blob.htmlBlob  &
iptcProfile_
      
IPTC profile. Supplied via a Blob.html Blob  since Magick++ and ImageMagick do not
currently  support formating   this data structure directly.
Specifications are available from the 
http://www.iptc.org/International Press Telecommunications Council
 for IPTC profiles.     
    
      
      
 label      
      
string       
void       
const string &label_       
Image label     
    
      
      
 magick      
      
string       
void       
 const string &magick_       
Get image format (e.g. "GIF")     
    
      
      
 matte      
      
bool       
void       
bool matteFlag_       
True if the image has transparency. If set
True, store  matte channel if  the image has one otherwise create
an opaque  one.
    
    
      
      
 matteColor      
      
Color.htmlColor        
void       
const Color.htmlColor &matteColor_
      
Image matte (frame) color     
    
      
      
 meanError-       
PerPixel      
      
double       
void       
       
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.
    
    
      
modulusDepth      
      
unsigned
int
      
      
void      
      
unsigned
int depth_
      
      
Image
modulus depth (minimum number of bits required to support
red/green/blue components without loss of accuracy). The pixel modulus
depth may be decreased by supplying a value which is less than the
current value, updating the pixels (reducing accuracy) to the new depth.
The pixel modulus depth can not be increased over the current value
using this method.
      
    
    
      
      
 monochrome      
      
bool       
void       
bool flag_       
Transform the image to black and white     
    
      
      
 montage-       
Geometry      
      
Geometry.htmlGeometry        
void       
       
Tile size and offset within an image montage.
Only valid for montage images.
    
    
      
      
 normalized-       
MaxError      
      
double       
void       
       
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-       
MeanError      
      
double       
void       
       
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.
    
    
      
orientation      
      
Enumerations.html#OrientationTypeOrientationType       
void      
      
www/Magick  /Enumerations.html#OrientationTypeOrientationType orientation_
      
Image orientation.
 Supported by some file formats such as DPX and TIFF. Useful for
turning the right way up.
      
    
    
      
      
 packets      
      
unsigned int       
void       
       
The number of runlength-encoded packets in       
the image     
    
      
      
 packetSize      
      
unsigned int       
void       
       
The number of bytes in each pixel packet     
    
      
      
 page      
      
Geometry.html#PostscriptPageSizeGeometry        
void       
const Geometry.html#PostscriptPageSize Geometry  &pageSize_       
Preferred size and location of an image
canvas.
      
Use this option to specify the   dimensions
and position of the Postscript page in dots per inch or a TEXT   page in
pixels. This option is typically used in concert with 
#density density  . 
      
Page may also be used to position   a GIF
image (such as for a scene in an animation)
      
    
    
      
      
 pixelColor      
      
Color.htmlColor        
unsigned int x_, unsigned int y_       
unsigned int x_, unsigned int y_, const Color.html Color  &color_       
Get/set pixel color at location x & y.     
    
      
      
 profile      
      
      
Blob.html Blob      
       
const std::string name_      
      
const std::string name_,   const Blob
&colorProfile_
      
      
Get/set/remove  a named
profile
. Valid names include "*",
"8BIM", "ICM", "IPTC", or a user/format-defined profile name. 
      
    
    
      
      
 quality      
      
unsigned int (0 to 100)       
void       
unsigned int quality_       
JPEG/MIFF/PNG compression level (default 75).     
    
      
      
 quantize-       
Colors      
      
unsigned int       
void       
unsigned int colors_       
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.
    
    
      
      
 quantize-       
ColorSpace      
      
Enumerations.html#ColorspaceTypeColorspaceType        
void       
Enumerations.html#ColorspaceTypeColorspaceType colorSpace_
      
Colorspace to quantize colors in (default
RGB). 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.
    
    
      
      
 quantize-       
Dither      
      
bool       
void       
bool flag_       
Apply Floyd/Steinberg error diffusion to the
image. 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. The quantizeColors or monochrome option must
be set for this option to take effect.
    
    
      
      
 quantize-       
TreeDepth      
      
unsigned int       
void       
unsigned int treeDepth_       
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.
    
    
      
      
 rendering-       
Intent      
      
Enumerations.html#RenderingIntentRenderingIntent        
void       
Enumerations.html#RenderingIntentRenderingIntent render_
      
The type of rendering intent     
    
      
      
 resolution-       
Units      
      
Enumerations.html#ResolutionTypeResolutionType        
void       
Enumerations.html#ResolutionTypeResolutionType units_
      
Units of image resolution     
    
      
      
 rows      
      
unsigned int       
void       
       
The number of pixel rows in the image     
    
      
      
 samplingFactor      
      
string (e.g. "2x1,1x1,1x1")       
void       
const string &samplingFactor_       
JPEG sampling factors     
    
      
      
 scene      
      
unsigned int       
void       
unsigned int scene_       
Image scene number     
    
      
      
 signature      
      
string       
bool force_ = false       
       
Image MD5 signature. Set force_ to 'true' to
force re-computation of signature.
    
    
      
      
 size      
      
Geometry.htmlGeometry        
void       
const Geometry.htmlGeometry &geometry_
      
Width and height of a raw image (an image
which does   not support width and height information).  Size may
also be used to  affect the image size read from a multi-resolution
format (e.g. Photo CD,  JBIG, or JPEG.
    
    
      
      
 strokeAntiAlias      
      
bool       
void       
bool flag_       
Enable or disable anti-aliasing when drawing
object outlines.
    
    
      
      
 strokeColor      
      
Color       
void       
const Color &strokeColor_       
Color to use when drawing object outlines     
    
      
      
 strokeDashOffset      
      
unsigned int       
void       
double strokeDashOffset_       
While drawing using a dash pattern, specify
distance into the dash pattern to start the dash (default 0).
    
    
      
      
 strokeDashArray      
      
const double*       
void       
const double* strokeDashArray_       
Specify the pattern of dashes and gaps used
to stroke   paths. The strokeDashArray represents a zero-terminated
array of numbers  that specify the lengths (in pixels) of alternating
dashes and gaps in user  units. If an odd number of values is provided,
then the list of values is  repeated to yield an even number of
values.  A typical strokeDashArray_   array might contain the
members 5 3 2 0, where the zero value indicates the  end of the pattern
array.
    
    
      
      
 strokeLineCap      
      
LineCap       
void       
LineCap lineCap_       
Specify the shape to be used at the corners
of paths   (or other vector shapes) when they are stroked. Values of
LineJoin are UndefinedJoin,  MiterJoin, RoundJoin, and BevelJoin.
    
    
      
      
 strokeLineJoin      
      
LineJoin       
void       
LineJoin lineJoin_       
Specify the shape to be used at the corners
of paths   (or other vector shapes) when they are stroked. Values of
LineJoin are UndefinedJoin,  MiterJoin, RoundJoin, and BevelJoin.
    
    
      
      
 strokeMiterLimit      
      
unsigned int       
void       
unsigned int miterLimit_       
Specify miter limit. When two line segments
meet at  a sharp angle and miter joins have been specified for
'lineJoin', it is possible  for the miter to extend far beyond the
thickness of the line stroking the  path. The miterLimit' imposes a
limit on the ratio of the miter length to  the 'lineWidth'. The default
value of this parameter is 4.
    
    
      
      
 strokeWidth      
      
double       
void       
double strokeWidth_       
Stroke width for use when drawing vector
objects (default  one)
    
    
      
      
 strokePattern      
      
Image       
void       
const Image &strokePattern_       
Pattern image to use while drawing object
stroke (outlines).
    
    
      
      
 subImage      
      
unsigned int       
void       
unsigned int subImage_       
Subimage of an image sequence     
    
      
      
 subRange      
      
unsigned int       
void       
unsigned int subRange_       
Number of images relative to the base image     
    
      
      
 textEncoding      
      
      
string      
      
void      
      
const std::string &encoding_      
      
Specify the code set to  use for text
annotations. The only character encoding which may be specified   at
this time is "UTF-8" for representing 
http://www.unicode.org/ Unicode  as a
sequence of bytes. Specify  an  empty string to use the default ASCII
encoding. Successful text annotation   using Unicode may require fonts
designed to support Unicode.
      
    
    
      
      
 tileName      
      
string       
void       
const string &tileName_       
Tile name     
    
      
      
 totalColors      
      
unsigned long       
void       
       
Number of colors in the image     
    
      
      
 type      
      
Enumerations.html#ImageTypeImageType        
void       
Enumerations.html#ImageType ImageType        
Image type.     
    
      
      
 verbose      
      
bool       
void       
bool verboseFlag_       
Print detailed information about the image     
    
      
      
 view      
      
string       
void       
const string &view_       
FlashPix viewing parameters.     
    
      
      
 x11Display      
      
string (e.g. "hostname:0.0")       
void       
const string &display_       
X11 display to display to, obtain fonts from,
or to  capture image from
    
    
      
      
 xResolution      
      
double       
void       
       
x resolution of the image     
    
      
      
 yResolution      
      
double       
void       
       
y resolution of the image     
  
  Low-Level Image Pixel Access
Image pixels (of type 
PixelPacket.htmlPixelPacket  )
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.htmlPixels  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.htmlPixels   class as
stdio's gets() relates to fgets(). The 
Pixels.html 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 
#modifyImagemodifyImage()  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
       
 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+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:  
  
Image Cache Methods     
      
      
Method      
      
      
Returns      
      
      
Signature      
      
      
Description      
    
    
      
      
 getConstPixels      
      
const PixelPacket.htmlPixelPacket *
      
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. 
The returned pointer remains valid until the next getPixel,
getConstPixels, or setPixels call and should never be deallocated by the
user.
    
    
      
      
 getConstIndexes      
      
const IndexPacket*       
void       
Returns a pointer to the Image pixel indexes
corresponding to a previous 
getPixel,
getConstPixels, or setPixels call.  
The
returned pointer remains valid until the next getPixel, getConstPixels,
or setPixels call and should never be deallocated by the user.
 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 
#colorMapcolorMap ) 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 
#getConstPixelsgetConstPixels  , #getPixelsgetPixels , or 
#setPixelssetPixels  call. The
returned pointer remains valid until the next getPixel, getConstPixels,
or setPixels call and should never be deallocated by the user.
 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 
#colorMapcolorMap  )  for that pixel. For CMYKA
images, the indexes are used to contain   the alpha channel.
    
    
      
      
 getPixels      
      
PixelPacket.htmlPixelPacket  *       
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. 
The returned pointer remains valid until the next getPixel,
getConstPixels, or setPixels call and should never be deallocated by the
user.
    
    
      
      
 setPixels      
      
PixelPacket.htmlPixelPacket  *       
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. 
The returned pointer remains
valid until the next getPixel, getConstPixels, or setPixels call and
should never be deallocated by the user.
    
    
      
      
 syncPixels      
      
void       
void       
Transfers the image cache pixels to the image.     
    
      
      
 readPixels      
      
void       
Enumerations.html#QuantumTypesQuantumTypes 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. The region transferred
corresponds to the region set by a preceding setPixels call.
    
    
      
      
 writePixels      
      
void       
Enumerations.html#QuantumTypesQuantumTypes 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. The region transferred corresponds to
the region set by a preceding getPixels or getConstPixels call.
    
  
  
