Viewing file:  Image.html (155.77 KB) -rw-r--r--
Select action/file-type:
 (+) | (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
Magick::Image Class
Magick::Image Class
Quick Contents
Image is the primary object in Magick++ and represents a
single image frame (see design
). The STL interface
must be used to operate on image sequences or images (e.g. of
format GIF, TIFF, MIFF, Postscript, & MNG) which are comprized of multiple
image frames. Individual frames of a multi-frame image may be requested
by adding array-style notation to the end of the file name (e.g. "animation.gif[3]"
retrieves the fourth frame of a GIF animation. Various image manipulation
operations may be applied to the image. Attributes may be set on the image
to influence the operation of the manipulation operations. The
Pixels
class provides low-level access to image pixels. As a convenience,
including <Magick++.h> is
sufficient in order to use the complete Magick++ API. The Magick++ API is
enclosed within the Magick namespace so you must either add the prefix
" Magick:: " to each class/enumeration name or add the statement
" using namespace Magick;" after including the Magick++.h
header.
The preferred way to allocate Image objects is via automatic allocation
(on the stack). There is no concern that allocating Image objects on the
stack will excessively enlarge the stack since Magick++ allocates all large
data objects (such as the actual image data) from the heap. Use of automatic
allocation is preferred over explicit allocation (via new) since
it is much less error prone and allows use of C++ scoping rules to avoid
memory leaks. Use of automatic allocation allows Magick++ objects to be
assigned and copied just like the C++ intrinsic data types (e.g. 'int
'), leading to clear and easy to read code. Use of automatic allocation
leads to naturally exception-safe code since if an exception is thrown,
the object is 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
class. The encoded image may be initially placed in memory by reading
it directly from a file, reading the image from a database, memory-mapped
from a disk file, or could be written to memory by Magick++. Once the encoded
image has been placed within a Blob, it may be read into a Magick++ Image
via a constructor
or read()
. Likewise, a Magick++ image may be written to a Blob via
write()
.
An example of using Image to write to a Blob follows:
#include <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 );
or
Blob blob( data, length );
Image image;
image.read( blob);
some images do not contain their size or format so the size and format
must be specified in advance:
Blob blob( data, length
);
Image image;
image.size( "640x480")
image.magick( "RGBA" );
image.read( blob);
Constructors
Image may be constructed in a number of ways. It may be constructed
from a file, a URL, or an encoded image (e.g. JPEG) contained in an in-memory
BLOB
. The available Image constructors are shown in the following table:
Image 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
&color_ |
Construct a blank image canvas of specified size
and color |
|
const Blob
&blob_ |
Construct Image by reading from encoded
image data contained in an in-memory BLOB
. Depending on the constructor arguments, the Blob size
, depth
, magick
(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 (magick
) 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 int 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_ |
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_ |
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. |
|
Image Manipulation Methods
Image supports access to all the single-image (versus image-list)
manipulation operations provided by the ImageMagick library. If you must
process a multi-image file (such as an animation), the
STL interface
, which provides a multi-image abstraction on top of Image, must
be used.
Image manipulation methods are very easy to use. For
example:
Image image;
image.read("myImage.tiff");
image.addNoise(GaussianNoise);
image.write("myImage.tiff");
adds gaussian noise to the image file "myImage.tiff".
The operations supported by Image are shown in the following
table:
Image Image Manipulation Methods
| Method |
Signature(s) |
Description |
|
|
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
|
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.
|
compare
|
const Image
&reference_
|
Compare current
image with another image. Sets meanErrorPerPixel
, normalizedMaxError
, and normalizedMeanError
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
&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
BLOB
stored 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
Image attributes are set and obtained via methods in Image. Except
for methods which accept pointer arguments (e.g. chromaBluePrimary)
all methods return attributes by value.
Image attributes are easily used. For example, to set the
resolution of the TIFF file "file.tiff" to 150 dots-per-inch (DPI) in both
the horizontal and vertical directions, you can use the following example
code:
string filename("file.tiff");
Image image;
image.read(filename);
image.resolutionUnits(PixelsPerInchResolution);
image.density(Geometry(150,150));
// could also use image.density("150x150")
image.write(filename)
The supported image attributes and the method arguments required to
obtain them are shown in the following table:
Image Attributes
|
Attribute
|
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. |
background-
Color
|
Color
|
void |
const Color
&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
|
void |
const Color
&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
|
void |
const Color
&boxColor_ |
Base color that annotation text is rendered on. |
|
cacheThreshold |
const 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. |
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
|
ClassType
|
void |
ClassType
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
|
unsigned int index_ |
unsigned int index_, const
Color
&color_ |
Color at colormap index. |
|
|
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 MaxColormapSize
constant, 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
|
ColorspaceType
colorSpace_ |
void |
ColorspaceType
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 |
compress-
Type
|
CompressionType
|
void |
CompressionType
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. |
|
density
|
Geometry
(default 72x72) |
void |
const Geometry
&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 or 16) |
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
|
EndianType
|
void |
EndianType
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
|
FillRule
|
void |
const Magick::FillRule &fillRule_ |
Rule to use when filling drawn objects. |
|
filterType
|
FilterTypes
|
void |
FilterTypes
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 Lanczos which
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
|
const std::string &text_,
TypeMetric
*metrics |
|
Update metrics with font type metrics using specified
text, and current font
and fontPointSize
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
|
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
|
void |
const Blob
&colorProfile_ |
ICC color profile. Supplied via a
Blob
since Magick++/ and ImageMagick do not currently support formating
this data structure directly. Specifications are available from the
International
Color Consortium
for the format of ICC color profiles. |
interlace-
Type
|
InterlaceType
|
void |
InterlaceType
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. NoInterlace
means 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
|
void |
const Blob
& iptcProfile_ |
IPTC profile. Supplied via a
Blob
since Magick++ and ImageMagick do not currently support formating
this data structure directly. Specifications are available from the
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
|
void |
const Color
&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. |
|
monochrome
|
bool |
void |
bool flag_ |
Transform the image to black and white |
montage-
Geometry
|
Geometry
|
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. |
|
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
|
void |
const
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
.
Page may also be used to position
a GIF image (such as for a scene in an animation)
|
|
pixelColor
|
Color
|
unsigned int x_, unsigned int y_ |
unsigned int x_, unsigned int y_, const
Color
&color_ |
Get/set pixel color at location x & y. |
|
|
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
|
ColorspaceType
|
void |
ColorspaceType
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
|
RenderingIntent
|
void |
RenderingIntent
render_ |
The type of rendering intent |
resolution-
Units
|
ResolutionType
|
void |
ResolutionType
units_ |
Units of image resolution |
|
rows
|
unsigned int |
void |
|
The number of pixel rows in the image |
|
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
|
void |
const Geometry
&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 |
|
|
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
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
|
ImageType
|
void |
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 |
Raw Image Pixel Access
Image pixels (of type PixelPacket
) may be accessed directly via the Image Pixel
Cache . The image pixel cache is a rectangular window into the
actual image pixels (which may be in memory, memory-mapped from a disk file,
or entirely on disk). Two interfaces exist to access the Image Pixel
Cache. The interface described here (part of the Image class)
supports only one view at a time. See the Pixels
class for a more abstract interface which supports
simultaneous pixel views (up to the number of rows). As an analogy, the
interface described here relates to the Pixels
class as stdio's gets() relates to fgets(). The
Pixels
class provides the more general form of the interface.
Obtain existing image pixels via getPixels().
Create a new pixel region using setPixels().
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. |
|