1 // This may look like C code, but it is really -*- C++ -*-
3 // Copyright Bob Friesenhahn, 1999, 2000, 2001, 2002, 2003
5 // Definition of Image, the representation of a single image in Magick++
8 #if !defined(Magick_Image_header)
9 #define Magick_Image_header
11 #include "Magick++/Include.h"
14 #include "Magick++/Blob.h"
15 #include "Magick++/Color.h"
16 #include "Magick++/Drawable.h"
17 #include "Magick++/Exception.h"
18 #include "Magick++/Geometry.h"
19 #include "Magick++/TypeMetric.h"
23 // Forward declarations
27 extern MagickDLLDecl const char *borderGeometryDefault;
28 extern MagickDLLDecl const char *frameGeometryDefault;
29 extern MagickDLLDecl const char *raiseGeometryDefault;
31 // Compare two Image objects regardless of LHS/RHS
32 // Image sizes and signatures are used as basis of comparison
33 int MagickDLLDecl operator == ( const Magick::Image& left_,
34 const Magick::Image& right_ );
35 int MagickDLLDecl operator != ( const Magick::Image& left_,
36 const Magick::Image& right_ );
37 int MagickDLLDecl operator > ( const Magick::Image& left_,
38 const Magick::Image& right_ );
39 int MagickDLLDecl operator < ( const Magick::Image& left_,
40 const Magick::Image& right_ );
41 int MagickDLLDecl operator >= ( const Magick::Image& left_,
42 const Magick::Image& right_ );
43 int MagickDLLDecl operator <= ( const Magick::Image& left_,
44 const Magick::Image& right_ );
46 // C library initialization routine
47 void MagickDLLDecl InitializeMagick(const char *path_);
50 // Image is the representation of an image. In reality, it actually
51 // a handle object which contains a pointer to a shared reference
52 // object (ImageRef). As such, this object is extremely space efficient.
54 class MagickDLLDecl Image
57 // Construct from image file or image specification
58 Image( const std::string &imageSpec_ );
60 // Construct a blank image canvas of specified size and color
61 Image( const Geometry &size_, const Color &color_ );
63 // Construct Image from in-memory BLOB
64 Image ( const Blob &blob_ );
66 // Construct Image of specified size from in-memory BLOB
67 Image ( const Blob &blob_, const Geometry &size_ );
69 // Construct Image of specified size and depth from in-memory BLOB
70 Image ( const Blob &blob_, const Geometry &size,
73 // Construct Image of specified size, depth, and format from
75 Image ( const Blob &blob_, const Geometry &size,
77 const std::string &magick_ );
78 // Construct Image of specified size, and format from in-memory
80 Image ( const Blob &blob_, const Geometry &size,
81 const std::string &magick_ );
83 // Construct an image based on an array of raw pixels, of
84 // specified type and mapping, in memory
85 Image ( const size_t width_,
87 const std::string &map_,
88 const StorageType type_,
89 const void *pixels_ );
91 // Default constructor
98 Image ( const Image & image_ );
100 // Assignment operator
101 Image& operator= ( const Image &image_ );
103 //////////////////////////////////////////////////////////////////////
107 //////////////////////////////////////////////////////////////////////
109 // Adaptive-blur image with specified blur factor
110 // The radius_ parameter specifies the radius of the Gaussian, in
111 // pixels, not counting the center pixel. The sigma_ parameter
112 // specifies the standard deviation of the Laplacian, in pixels.
113 void adaptiveBlur ( const double radius_ = 0.0,
114 const double sigma_ = 1.0 );
116 // Local adaptive threshold image
117 // http://www.dai.ed.ac.uk/HIPR2/adpthrsh.htm
118 // Width x height define the size of the pixel neighborhood
119 // offset = constant to subtract from pixel neighborhood mean
120 void adaptiveThreshold ( const size_t width,
122 const ssize_t offset = 0 );
124 // Add noise to image with specified noise type
125 void addNoise ( const NoiseType noiseType_ );
126 void addNoiseChannel ( const ChannelType channel_,
127 const NoiseType noiseType_);
129 // Transform image by specified affine (or free transform) matrix.
130 void affineTransform ( const DrawableAffine &affine );
133 // Annotate image (draw text on image)
136 // Gravity effects text placement in bounding area according to rules:
137 // NorthWestGravity text bottom-left corner placed at top-left
138 // NorthGravity text bottom-center placed at top-center
139 // NorthEastGravity text bottom-right corner placed at top-right
140 // WestGravity text left-center placed at left-center
141 // CenterGravity text center placed at center
142 // EastGravity text right-center placed at right-center
143 // SouthWestGravity text top-left placed at bottom-left
144 // SouthGravity text top-center placed at bottom-center
145 // SouthEastGravity text top-right placed at bottom-right
147 // Annotate using specified text, and placement location
148 void annotate ( const std::string &text_,
149 const Geometry &location_ );
150 // Annotate using specified text, bounding area, and placement
152 void annotate ( const std::string &text_,
153 const Geometry &boundingArea_,
154 const GravityType gravity_ );
155 // Annotate with text using specified text, bounding area,
156 // placement gravity, and rotation.
157 void annotate ( const std::string &text_,
158 const Geometry &boundingArea_,
159 const GravityType gravity_,
160 const double degrees_ );
161 // Annotate with text (bounding area is entire image) and placement
163 void annotate ( const std::string &text_,
164 const GravityType gravity_ );
166 // Blur image with specified blur factor
167 // The radius_ parameter specifies the radius of the Gaussian, in
168 // pixels, not counting the center pixel. The sigma_ parameter
169 // specifies the standard deviation of the Laplacian, in pixels.
170 void blur ( const double radius_ = 0.0,
171 const double sigma_ = 1.0 );
172 void blurChannel ( const ChannelType channel_,
173 const double radius_ = 0.0,
174 const double sigma_ = 1.0 );
176 // Border image (add border to image)
177 void border ( const Geometry &geometry_
178 = borderGeometryDefault );
180 // Extract channel from image
181 void channel ( const ChannelType channel_ );
183 // Set or obtain modulus channel depth
184 void channelDepth ( const ChannelType channel_,
185 const size_t depth_ );
186 size_t channelDepth ( const ChannelType channel_ );
188 // Charcoal effect image (looks like charcoal sketch)
189 // The radius_ parameter specifies the radius of the Gaussian, in
190 // pixels, not counting the center pixel. The sigma_ parameter
191 // specifies the standard deviation of the Laplacian, in pixels.
192 void charcoal ( const double radius_ = 0.0,
193 const double sigma_ = 1.0 );
195 // Chop image (remove vertical or horizontal subregion of image)
196 // FIXME: describe how geometry argument is used to select either
197 // horizontal or vertical subregion of image.
199 void chop ( const Geometry &geometry_ );
201 // Accepts a lightweight Color Correction Collection
202 // (CCC) file which solely contains one or more color corrections and
203 // applies the correction to the image.
204 void cdl ( const std::string &cdl_ );
206 // Colorize image with pen color, using specified percent opacity
207 // for red, green, and blue quantums
208 void colorize ( const unsigned int opacityRed_,
209 const unsigned int opacityGreen_,
210 const unsigned int opacityBlue_,
211 const Color &penColor_ );
212 // Colorize image with pen color, using specified percent opacity.
213 void colorize ( const unsigned int opacity_,
214 const Color &penColor_ );
216 // Apply a color matrix to the image channels. The user supplied
217 // matrix may be of order 1 to 5 (1x1 through 5x5).
218 void colorMatrix (const size_t order_,
219 const double *color_matrix_);
221 // Comment image (add comment string to image)
222 void comment ( const std::string &comment_ );
224 // Composition operator to be used when composition is implicitly
225 // used (such as for image flattening).
226 void compose (const CompositeOperator compose_);
227 CompositeOperator compose ( void ) const;
229 // Compare current image with another image
230 // Sets meanErrorPerPixel, normalizedMaxError, and normalizedMeanError
231 // in the current image. False is returned if the images are identical.
232 bool compare ( const Image &reference_ );
234 // Compose an image onto another at specified offset and using
235 // specified algorithm
236 void composite ( const Image &compositeImage_,
237 const ssize_t xOffset_,
238 const ssize_t yOffset_,
239 const CompositeOperator compose_
241 void composite ( const Image &compositeImage_,
242 const Geometry &offset_,
243 const CompositeOperator compose_
245 void composite ( const Image &compositeImage_,
246 const GravityType gravity_,
247 const CompositeOperator compose_
250 // Contrast image (enhance intensity differences in image)
251 void contrast ( const size_t sharpen_ );
253 // Convolve image. Applies a user-specified convolution to the image.
254 // order_ represents the number of columns and rows in the filter kernel.
255 // kernel_ is an array of doubles representing the convolution kernel.
256 void convolve ( const size_t order_,
257 const double *kernel_ );
259 // Crop image (subregion of original image)
260 void crop ( const Geometry &geometry_ );
262 // Cycle image colormap
263 void cycleColormap ( const ssize_t amount_ );
265 // Despeckle image (reduce speckle noise)
266 void despeckle ( void );
268 // Display image on screen
269 void display ( void );
271 // Distort image. distorts an image using various distortion methods, by
272 // mapping color lookups of the source image to a new destination image
273 // usally of the same size as the source image, unless 'bestfit' is set to
275 void distort ( const DistortImageMethod method_,
276 const size_t number_arguments_,
277 const double *arguments_,
278 const bool bestfit_ = false );
280 // Draw on image using a single drawable
281 void draw ( const Drawable &drawable_ );
283 // Draw on image using a drawable list
284 void draw ( const std::list<Magick::Drawable> &drawable_ );
286 // Edge image (hilight edges in image)
287 void edge ( const double radius_ = 0.0 );
289 // Emboss image (hilight edges with 3D effect)
290 // The radius_ parameter specifies the radius of the Gaussian, in
291 // pixels, not counting the center pixel. The sigma_ parameter
292 // specifies the standard deviation of the Laplacian, in pixels.
293 void emboss ( const double radius_ = 0.0,
294 const double sigma_ = 1.0);
296 // Enhance image (minimize noise)
297 void enhance ( void );
299 // Equalize image (histogram equalization)
300 void equalize ( void );
302 // Erase image to current "background color"
305 // Extend the image as defined by the geometry.
306 void extent ( const Geometry &geometry_ );
307 void extent ( const Geometry &geometry_, const Color &backgroundColor );
308 void extent ( const Geometry &geometry_, const GravityType gravity_ );
309 void extent ( const Geometry &geometry_, const Color &backgroundColor, const GravityType gravity_ );
311 // Flip image (reflect each scanline in the vertical direction)
314 // Flood-fill color across pixels that match the color of the
315 // target pixel and are neighbors of the target pixel.
316 // Uses current fuzz setting when determining color match.
317 void floodFillColor( const ssize_t x_,
319 const Color &fillColor_ );
320 void floodFillColor( const Geometry &point_,
321 const Color &fillColor_ );
323 // Flood-fill color across pixels starting at target-pixel and
324 // stopping at pixels matching specified border color.
325 // Uses current fuzz setting when determining color match.
326 void floodFillColor( const ssize_t x_,
328 const Color &fillColor_,
329 const Color &borderColor_ );
330 void floodFillColor( const Geometry &point_,
331 const Color &fillColor_,
332 const Color &borderColor_ );
334 // Floodfill pixels matching color (within fuzz factor) of target
335 // pixel(x,y) with replacement opacity value using method.
336 void floodFillOpacity ( const ssize_t x_,
338 const unsigned int opacity_,
339 const PaintMethod method_ );
341 // Flood-fill texture across pixels that match the color of the
342 // target pixel and are neighbors of the target pixel.
343 // Uses current fuzz setting when determining color match.
344 void floodFillTexture( const ssize_t x_,
346 const Image &texture_ );
347 void floodFillTexture( const Geometry &point_,
348 const Image &texture_ );
350 // Flood-fill texture across pixels starting at target-pixel and
351 // stopping at pixels matching specified border color.
352 // Uses current fuzz setting when determining color match.
353 void floodFillTexture( const ssize_t x_,
355 const Image &texture_,
356 const Color &borderColor_ );
357 void floodFillTexture( const Geometry &point_,
358 const Image &texture_,
359 const Color &borderColor_ );
361 // Flop image (reflect each scanline in the horizontal direction)
364 // Implements the discrete Fourier transform (DFT) of the image either as a
365 // magnitude / phase or real / imaginary image pair.
366 void forwardFourierTransform ( void );
367 void forwardFourierTransform ( const bool magnitude );
370 void frame ( const Geometry &geometry_ = frameGeometryDefault );
371 void frame ( const size_t width_,
372 const size_t height_,
373 const ssize_t innerBevel_ = 6,
374 const ssize_t outerBevel_ = 6 );
376 // Applies a mathematical expression to the image.
377 void fx ( const std::string expression );
378 void fx ( const std::string expression,
379 const Magick::ChannelType channel );
381 // Gamma correct image
382 void gamma ( const double gamma_ );
383 void gamma ( const double gammaRed_,
384 const double gammaGreen_,
385 const double gammaBlue_ );
387 // Gaussian blur image
388 // The number of neighbor pixels to be included in the convolution
389 // mask is specified by 'width_'. The standard deviation of the
390 // gaussian bell curve is specified by 'sigma_'.
391 void gaussianBlur ( const double width_, const double sigma_ );
392 void gaussianBlurChannel ( const ChannelType channel_,
394 const double sigma_ );
396 // Apply a color lookup table (Hald CLUT) to the image.
397 void haldClut ( const Image &clutImage_ );
400 // Implode image (special effect)
401 void implode ( const double factor_ );
403 // implements the inverse discrete Fourier transform (DFT) of the image
404 // either as a magnitude / phase or real / imaginary image pair.
406 void inverseFourierTransform ( const Image &phase_ );
407 void inverseFourierTransform ( const Image &phase_,
408 const bool magnitude_ );
410 void label ( const std::string &label_ );
412 // Level image. Adjust the levels of the image by scaling the
413 // colors falling between specified white and black points to the
414 // full available quantum range. The parameters provided represent
415 // the black, mid (gamma), and white points. The black point
416 // specifies the darkest color in the image. Colors darker than
417 // the black point are set to zero. Mid point (gamma) specifies a
418 // gamma correction to apply to the image. White point specifies
419 // the lightest color in the image. Colors brighter than the
420 // white point are set to the maximum quantum value. The black and
421 // white point have the valid range 0 to QuantumRange while mid (gamma)
422 // has a useful range of 0 to ten.
423 void level ( const double black_point,
424 const double white_point,
425 const double mid_point=1.0 );
427 // Level image channel. Adjust the levels of the image channel by
428 // scaling the values falling between specified white and black
429 // points to the full available quantum range. The parameters
430 // provided represent the black, mid (gamma), and white points.
431 // The black point specifies the darkest color in the
432 // image. Colors darker than the black point are set to zero. Mid
433 // point (gamma) specifies a gamma correction to apply to the
434 // image. White point specifies the lightest color in the image.
435 // Colors brighter than the white point are set to the maximum
436 // quantum value. The black and white point have the valid range 0
437 // to QuantumRange while mid (gamma) has a useful range of 0 to ten.
438 void levelChannel ( const ChannelType channel,
439 const double black_point,
440 const double white_point,
441 const double mid_point=1.0 );
443 // Magnify image by integral size
444 void magnify ( void );
446 // Remap image colors with closest color from reference image
447 void map ( const Image &mapImage_ ,
448 const bool dither_ = false );
450 // Floodfill designated area with replacement opacity value
451 void matteFloodfill ( const Color &target_ ,
452 const unsigned int opacity_,
453 const ssize_t x_, const ssize_t y_,
454 const PaintMethod method_ );
456 // Filter image by replacing each pixel component with the median
457 // color in a circular neighborhood
458 void medianFilter ( const double radius_ = 0.0 );
460 // Reduce image by integral size
461 void minify ( void );
463 // Modulate percent hue, saturation, and brightness of an image
464 void modulate ( const double brightness_,
465 const double saturation_,
468 // Motion blur image with specified blur factor
469 // The radius_ parameter specifies the radius of the Gaussian, in
470 // pixels, not counting the center pixel. The sigma_ parameter
471 // specifies the standard deviation of the Laplacian, in pixels.
472 // The angle_ parameter specifies the angle the object appears
473 // to be comming from (zero degrees is from the right).
474 void motionBlur ( const double radius_,
476 const double angle_ );
478 // Negate colors in image. Set grayscale to only negate grayscale
480 void negate ( const bool grayscale_ = false );
482 // Normalize image (increase contrast by normalizing the pixel
483 // values to span the full range of color values)
484 void normalize ( void );
486 // Oilpaint image (image looks like oil painting)
487 void oilPaint ( const double radius_ = 3.0 );
489 // Set or attenuate the opacity channel in the image. If the image
490 // pixels are opaque then they are set to the specified opacity
491 // value, otherwise they are blended with the supplied opacity
492 // value. The value of opacity_ ranges from 0 (completely opaque)
493 // to QuantumRange. The defines OpaqueOpacity and TransparentOpacity are
494 // available to specify completely opaque or completely
495 // transparent, respectively.
496 void opacity ( const unsigned int opacity_ );
498 // Change color of opaque pixel to specified pen color.
499 void opaque ( const Color &opaqueColor_,
500 const Color &penColor_ );
502 // Ping is similar to read except only enough of the image is read
503 // to determine the image columns, rows, and filesize. Access the
504 // columns(), rows(), and fileSize() attributes after invoking
505 // ping. The image data is not valid after calling ping.
506 void ping ( const std::string &imageSpec_ );
508 // Ping is similar to read except only enough of the image is read
509 // to determine the image columns, rows, and filesize. Access the
510 // columns(), rows(), and fileSize() attributes after invoking
511 // ping. The image data is not valid after calling ping.
512 void ping ( const Blob &blob_ );
514 // Quantize image (reduce number of colors)
515 void quantize ( const bool measureError_ = false );
517 void quantumOperator ( const ChannelType channel_,
518 const MagickEvaluateOperator operator_,
521 void quantumOperator ( const ssize_t x_,const ssize_t y_,
522 const size_t columns_,
524 const ChannelType channel_,
525 const MagickEvaluateOperator operator_,
526 const double rvalue_);
528 // Execute a named process module using an argc/argv syntax similar to
529 // that accepted by a C 'main' routine. An exception is thrown if the
530 // requested process module doesn't exist, fails to load, or fails during
532 void process ( std::string name_,
534 const char **argv_ );
536 // Raise image (lighten or darken the edges of an image to give a
537 // 3-D raised or lowered effect)
538 void raise ( const Geometry &geometry_ = raiseGeometryDefault,
539 const bool raisedFlag_ = false );
541 // Random threshold image.
543 // Changes the value of individual pixels based on the intensity
544 // of each pixel compared to a random threshold. The result is a
545 // low-contrast, two color image. The thresholds_ argument is a
546 // geometry containing LOWxHIGH thresholds. If the string
547 // contains 2x2, 3x3, or 4x4, then an ordered dither of order 2,
548 // 3, or 4 will be performed instead. If a channel_ argument is
549 // specified then only the specified channel is altered. This is
550 // a very fast alternative to 'quantize' based dithering.
551 void randomThreshold( const Geometry &thresholds_ );
552 void randomThresholdChannel( const Geometry &thresholds_,
553 const ChannelType channel_ );
555 // Read single image frame into current object
556 void read ( const std::string &imageSpec_ );
558 // Read single image frame of specified size into current object
559 void read ( const Geometry &size_,
560 const std::string &imageSpec_ );
562 // Read single image frame from in-memory BLOB
563 void read ( const Blob &blob_ );
565 // Read single image frame of specified size from in-memory BLOB
566 void read ( const Blob &blob_,
567 const Geometry &size_ );
569 // Read single image frame of specified size and depth from
571 void read ( const Blob &blob_,
572 const Geometry &size_,
573 const size_t depth_ );
575 // Read single image frame of specified size, depth, and format
576 // from in-memory BLOB
577 void read ( const Blob &blob_,
578 const Geometry &size_,
580 const std::string &magick_ );
582 // Read single image frame of specified size, and format from
584 void read ( const Blob &blob_,
585 const Geometry &size_,
586 const std::string &magick_ );
588 // Read single image frame from an array of raw pixels, with
589 // specified storage type (ConstituteImage), e.g.
590 // image.read( 640, 480, "RGB", 0, pixels );
591 void read ( const size_t width_,
592 const size_t height_,
593 const std::string &map_,
594 const StorageType type_,
595 const void *pixels_ );
597 // Reduce noise in image using a noise peak elimination filter
598 void reduceNoise ( void );
599 void reduceNoise ( const double order_ );
601 // Resize image to specified size.
602 void resize ( const Geometry &geometry_ );
604 // Roll image (rolls image vertically and horizontally) by specified
605 // number of columnms and rows)
606 void roll ( const Geometry &roll_ );
607 void roll ( const size_t columns_,
608 const size_t rows_ );
610 // Rotate image counter-clockwise by specified number of degrees.
611 void rotate ( const double degrees_ );
613 // Resize image by using pixel sampling algorithm
614 void sample ( const Geometry &geometry_ );
616 // Resize image by using simple ratio algorithm
617 void scale ( const Geometry &geometry_ );
619 // Segment (coalesce similar image components) by analyzing the
620 // histograms of the color components and identifying units that
621 // are homogeneous with the fuzzy c-means technique. Also uses
622 // QuantizeColorSpace and Verbose image attributes
623 void segment ( const double clusterThreshold_ = 1.0,
624 const double smoothingThreshold_ = 1.5 );
626 // Shade image using distant light source
627 void shade ( const double azimuth_ = 30,
628 const double elevation_ = 30,
629 const bool colorShading_ = false );
631 // Sharpen pixels in image
632 // The radius_ parameter specifies the radius of the Gaussian, in
633 // pixels, not counting the center pixel. The sigma_ parameter
634 // specifies the standard deviation of the Laplacian, in pixels.
635 void sharpen ( const double radius_ = 0.0,
636 const double sigma_ = 1.0 );
637 void sharpenChannel ( const ChannelType channel_,
638 const double radius_ = 0.0,
639 const double sigma_ = 1.0 );
641 // Shave pixels from image edges.
642 void shave ( const Geometry &geometry_ );
644 // Shear image (create parallelogram by sliding image by X or Y axis)
645 void shear ( const double xShearAngle_,
646 const double yShearAngle_ );
648 // adjust the image contrast with a non-linear sigmoidal contrast algorithm
649 void sigmoidalContrast ( const size_t sharpen_, const double contrast, const double midpoint = QuantumRange / 2.0 );
651 // Solarize image (similar to effect seen when exposing a
652 // photographic film to light during the development process)
653 void solarize ( const double factor_ = 50.0 );
655 // Splice the background color into the image.
656 void splice ( const Geometry &geometry_ );
658 // Spread pixels randomly within image by specified ammount
659 void spread ( const size_t amount_ = 3 );
661 // Sparse color image, given a set of coordinates, interpolates the colors
662 // found at those coordinates, across the whole image, using various
664 void sparseColor ( const ChannelType channel,
665 const SparseColorMethod method,
666 const size_t number_arguments,
667 const double *arguments );
669 // Add a digital watermark to the image (based on second image)
670 void stegano ( const Image &watermark_ );
672 // Create an image which appears in stereo when viewed with
673 // red-blue glasses (Red image on left, blue on right)
674 void stereo ( const Image &rightImage_ );
676 // Swirl image (image pixels are rotated by degrees)
677 void swirl ( const double degrees_ );
679 // Channel a texture on image background
680 void texture ( const Image &texture_ );
683 void threshold ( const double threshold_ );
685 // Transform image based on image and crop geometries
686 // Crop geometry is optional
687 void transform ( const Geometry &imageGeometry_ );
688 void transform ( const Geometry &imageGeometry_,
689 const Geometry &cropGeometry_ );
691 // Add matte image to image, setting pixels matching color to
693 void transparent ( const Color &color_ );
695 // Add matte image to image, for all the pixels that lies in between
696 // the given two color
697 void transparentChroma ( const Color &colorLow_, const Color &colorHigh_);
699 // Trim edges that are the background color from the image
702 // Image representation type (also see type attribute)
704 // Bilevel Grayscale GrayscaleMatte
705 // Palette PaletteMatte TrueColor
706 // TrueColorMatte ColorSeparation ColorSeparationMatte
707 void type ( const ImageType type_ );
709 // Replace image with a sharpened version of the original image
710 // using the unsharp mask algorithm.
712 // the radius of the Gaussian, in pixels, not counting the
715 // the standard deviation of the Gaussian, in pixels.
717 // the percentage of the difference between the original and
718 // the blur image that is added back into the original.
720 // the threshold in pixels needed to apply the diffence amount.
721 void unsharpmask ( const double radius_,
723 const double amount_,
724 const double threshold_ );
725 void unsharpmaskChannel ( const ChannelType channel_,
726 const double radius_,
728 const double amount_,
729 const double threshold_ );
731 // Map image pixels to a sine wave
732 void wave ( const double amplitude_ = 25.0,
733 const double wavelength_ = 150.0 );
735 // Write single image frame to a file
736 void write ( const std::string &imageSpec_ );
738 // Write single image frame to in-memory BLOB, with optional
739 // format and adjoin parameters.
740 void write ( Blob *blob_ );
741 void write ( Blob *blob_,
742 const std::string &magick_ );
743 void write ( Blob *blob_,
744 const std::string &magick_,
745 const size_t depth_ );
747 // Write single image frame to an array of pixels with storage
748 // type specified by user (DispatchImage), e.g.
749 // image.write( 0, 0, 640, 1, "RGB", 0, pixels );
750 void write ( const ssize_t x_,
752 const size_t columns_,
754 const std::string& map_,
755 const StorageType type_,
758 // Zoom image to specified size.
759 void zoom ( const Geometry &geometry_ );
761 //////////////////////////////////////////////////////////////////////
763 // Image Attributes and Options
765 //////////////////////////////////////////////////////////////////////
767 // Join images into a single multi-image file
768 void adjoin ( const bool flag_ );
769 bool adjoin ( void ) const;
771 // Anti-alias Postscript and TrueType fonts (default true)
772 void antiAlias( const bool flag_ );
773 bool antiAlias( void );
775 // Time in 1/100ths of a second which must expire before
776 // displaying the next image in an animated sequence.
777 void animationDelay ( const size_t delay_ );
778 size_t animationDelay ( void ) const;
780 // Number of iterations to loop an animation (e.g. Netscape loop
782 void animationIterations ( const size_t iterations_ );
783 size_t animationIterations ( void ) const;
785 // Access/Update a named image attribute
786 void attribute ( const std::string name_,
787 const std::string value_ );
788 std::string attribute ( const std::string name_ );
790 // Image background color
791 void backgroundColor ( const Color &color_ );
792 Color backgroundColor ( void ) const;
794 // Name of texture image to tile onto the image background
795 void backgroundTexture (const std::string &backgroundTexture_ );
796 std::string backgroundTexture ( void ) const;
798 // Base image width (before transformations)
799 size_t baseColumns ( void ) const;
801 // Base image filename (before transformations)
802 std::string baseFilename ( void ) const;
804 // Base image height (before transformations)
805 size_t baseRows ( void ) const;
807 // Image border color
808 void borderColor ( const Color &color_ );
809 Color borderColor ( void ) const;
811 // Return smallest bounding box enclosing non-border pixels. The
812 // current fuzz value is used when discriminating between pixels.
813 // This is the crop bounding box used by crop(Geometry(0,0));
814 Geometry boundingBox ( void ) const;
816 // Text bounding-box base color (default none)
817 void boxColor ( const Color &boxColor_ );
818 Color boxColor ( void ) const;
820 // Pixel cache threshold in megabytes. Once this memory threshold
821 // is exceeded, all subsequent pixels cache operations are to/from
822 // disk. This setting is shared by all Image objects.
823 static void cacheThreshold ( const size_t threshold_ );
825 // Chromaticity blue primary point (e.g. x=0.15, y=0.06)
826 void chromaBluePrimary ( const double x_, const double y_ );
827 void chromaBluePrimary ( double *x_, double *y_ ) const;
829 // Chromaticity green primary point (e.g. x=0.3, y=0.6)
830 void chromaGreenPrimary ( const double x_, const double y_ );
831 void chromaGreenPrimary ( double *x_, double *y_ ) const;
833 // Chromaticity red primary point (e.g. x=0.64, y=0.33)
834 void chromaRedPrimary ( const double x_, const double y_ );
835 void chromaRedPrimary ( double *x_, double *y_ ) const;
837 // Chromaticity white point (e.g. x=0.3127, y=0.329)
838 void chromaWhitePoint ( const double x_, const double y_ );
839 void chromaWhitePoint ( double *x_, double *y_ ) const;
841 // Image class (DirectClass or PseudoClass)
842 // NOTE: setting a DirectClass image to PseudoClass will result in
843 // the loss of color information if the number of colors in the
844 // image is greater than the maximum palette size (either 256 or
845 // 65536 entries depending on the value of MAGICKCORE_QUANTUM_DEPTH when
846 // ImageMagick was built).
847 void classType ( const ClassType class_ );
848 ClassType classType ( void ) const;
850 // Associate a clip mask with the image. The clip mask must be the
851 // same dimensions as the image. Pass an invalid image to unset an
852 // existing clip mask.
853 void clipMask ( const Image & clipMask_ );
854 Image clipMask ( void ) const;
856 // Colors within this distance are considered equal
857 void colorFuzz ( const double fuzz_ );
858 double colorFuzz ( void ) const;
860 // Color at colormap position index_
861 void colorMap ( const size_t index_,
862 const Color &color_ );
863 Color colorMap ( const size_t index_ ) const;
865 // Colormap size (number of colormap entries)
866 void colorMapSize ( const size_t entries_ );
867 size_t colorMapSize ( void );
870 void colorSpace ( const ColorspaceType colorSpace_ );
871 ColorspaceType colorSpace ( void ) const;
873 void colorspaceType ( const ColorspaceType colorSpace_ );
874 ColorspaceType colorspaceType ( void ) const;
877 size_t columns ( void ) const;
880 std::string comment ( void ) const;
883 void compressType ( const CompressionType compressType_ );
884 CompressionType compressType ( void ) const;
886 // Enable printing of debug messages from ImageMagick
887 void debug ( const bool flag_ );
888 bool debug ( void ) const;
890 // Tagged image format define (set/access coder-specific option) The
891 // magick_ option specifies the coder the define applies to. The key_
892 // option provides the key specific to that coder. The value_ option
893 // provides the value to set (if any). See the defineSet() method if the
894 // key must be removed entirely.
895 void defineValue ( const std::string &magick_,
896 const std::string &key_,
897 const std::string &value_ );
898 std::string defineValue ( const std::string &magick_,
899 const std::string &key_ ) const;
901 // Tagged image format define. Similar to the defineValue() method
902 // except that passing the flag_ value 'true' creates a value-less
903 // define with that format and key. Passing the flag_ value 'false'
904 // removes any existing matching definition. The method returns 'true'
905 // if a matching key exists, and 'false' if no matching key exists.
906 void defineSet ( const std::string &magick_,
907 const std::string &key_,
909 bool defineSet ( const std::string &magick_,
910 const std::string &key_ ) const;
912 // Vertical and horizontal resolution in pixels of the image
913 void density ( const Geometry &geomery_ );
914 Geometry density ( void ) const;
916 // Image depth (bits allocated to red/green/blue components)
917 void depth ( const size_t depth_ );
918 size_t depth ( void ) const;
920 // Tile names from within an image montage
921 std::string directory ( void ) const;
923 // Endianness (little like Intel or big like SPARC) for image
924 // formats which support endian-specific options.
925 void endian ( const EndianType endian_ );
926 EndianType endian ( void ) const;
928 // Exif profile (BLOB)
929 void exifProfile( const Blob& exifProfile_ );
930 Blob exifProfile( void ) const;
933 void fileName ( const std::string &fileName_ );
934 std::string fileName ( void ) const;
936 // Number of bytes of the image on disk
937 off_t fileSize ( void ) const;
939 // Color to use when filling drawn objects
940 void fillColor ( const Color &fillColor_ );
941 Color fillColor ( void ) const;
943 // Rule to use when filling drawn objects
944 void fillRule ( const FillRule &fillRule_ );
945 FillRule fillRule ( void ) const;
947 // Pattern to use while filling drawn objects.
948 void fillPattern ( const Image &fillPattern_ );
949 Image fillPattern ( void ) const;
951 // Filter to use when resizing image
952 void filterType ( const FilterTypes filterType_ );
953 FilterTypes filterType ( void ) const;
955 // Text rendering font
956 void font ( const std::string &font_ );
957 std::string font ( void ) const;
960 void fontPointsize ( const double pointSize_ );
961 double fontPointsize ( void ) const;
963 // Obtain font metrics for text string given current font,
964 // pointsize, and density settings.
965 void fontTypeMetrics( const std::string &text_,
966 TypeMetric *metrics );
968 // Long image format description
969 std::string format ( void ) const;
971 // Gamma level of the image
972 double gamma ( void ) const;
974 // Preferred size of the image when encoding
975 Geometry geometry ( void ) const;
977 // GIF disposal method
978 void gifDisposeMethod ( const size_t disposeMethod_ );
979 size_t gifDisposeMethod ( void ) const;
981 // ICC color profile (BLOB)
982 void iccColorProfile( const Blob &colorProfile_ );
983 Blob iccColorProfile( void ) const;
985 // Type of interlacing to use
986 void interlaceType ( const InterlaceType interlace_ );
987 InterlaceType interlaceType ( void ) const;
989 // IPTC profile (BLOB)
990 void iptcProfile( const Blob& iptcProfile_ );
991 Blob iptcProfile( void ) const;
993 // Does object contain valid image?
994 void isValid ( const bool isValid_ );
995 bool isValid ( void ) const;
998 std::string label ( void ) const;
1000 // Obtain image statistics. Statistics are normalized to the range
1001 // of 0.0 to 1.0 and are output to the specified ImageStatistics
1003 typedef struct _ImageChannelStatistics
1005 /* Minimum value observed */
1007 /* Maximum value observed */
1009 /* Average (mean) value observed */
1011 /* Standard deviation, sqrt(variance) */
1012 double standard_deviation;
1019 } ImageChannelStatistics;
1021 typedef struct _ImageStatistics
1023 ImageChannelStatistics red;
1024 ImageChannelStatistics green;
1025 ImageChannelStatistics blue;
1026 ImageChannelStatistics opacity;
1029 void statistics ( ImageStatistics *statistics ) const;
1031 // Stroke width for drawing vector objects (default one)
1032 // This method is now deprecated. Please use strokeWidth instead.
1033 void lineWidth ( const double lineWidth_ );
1034 double lineWidth ( void ) const;
1036 // File type magick identifier (.e.g "GIF")
1037 void magick ( const std::string &magick_ );
1038 std::string magick ( void ) const;
1040 // Image supports transparency (matte channel)
1041 void matte ( const bool matteFlag_ );
1042 bool matte ( void ) const;
1044 // Transparent color
1045 void matteColor ( const Color &matteColor_ );
1046 Color matteColor ( void ) const;
1048 // The mean error per pixel computed when an image is color reduced
1049 double meanErrorPerPixel ( void ) const;
1051 // Image modulus depth (minimum number of bits required to support
1052 // red/green/blue components without loss of accuracy)
1053 void modulusDepth ( const size_t modulusDepth_ );
1054 size_t modulusDepth ( void ) const;
1056 // Tile size and offset within an image montage
1057 Geometry montageGeometry ( void ) const;
1059 // Transform image to black and white
1060 void monochrome ( const bool monochromeFlag_ );
1061 bool monochrome ( void ) const;
1063 // The normalized max error per pixel computed when an image is
1065 double normalizedMaxError ( void ) const;
1067 // The normalized mean error per pixel computed when an image is
1069 double normalizedMeanError ( void ) const;
1071 // Image orientation
1072 void orientation ( const OrientationType orientation_ );
1073 OrientationType orientation ( void ) const;
1075 // Preferred size and location of an image canvas.
1076 void page ( const Geometry &pageSize_ );
1077 Geometry page ( void ) const;
1079 // Pen color (deprecated, don't use any more)
1080 void penColor ( const Color &penColor_ );
1081 Color penColor ( void ) const;
1083 // Pen texture image (deprecated, don't use any more)
1084 void penTexture ( const Image &penTexture_ );
1085 Image penTexture ( void ) const;
1087 // Get/set pixel color at location x & y.
1088 void pixelColor ( const ssize_t x_,
1090 const Color &color_ );
1091 Color pixelColor ( const ssize_t x_,
1092 const ssize_t y_ ) const;
1094 // Add or remove a named profile to/from the image. Remove the
1095 // profile by passing an empty Blob (e.g. Blob()). Valid names are
1096 // "*", "8BIM", "ICM", "IPTC", or a user/format-defined profile name.
1097 void profile( const std::string name_,
1098 const Blob &colorProfile_ );
1100 // Retrieve a named profile from the image. Valid names are:
1101 // "8BIM", "8BIMTEXT", "APP1", "APP1JPEG", "ICC", "ICM", & "IPTC"
1102 // or an existing user/format-defined profile name.
1103 Blob profile( const std::string name_ ) const;
1105 // JPEG/MIFF/PNG compression level (default 75).
1106 void quality ( const size_t quality_ );
1107 size_t quality ( void ) const;
1109 // Maximum number of colors to quantize to
1110 void quantizeColors ( const size_t colors_ );
1111 size_t quantizeColors ( void ) const;
1113 // Colorspace to quantize in.
1114 void quantizeColorSpace ( const ColorspaceType colorSpace_ );
1115 ColorspaceType quantizeColorSpace ( void ) const;
1117 // Dither image during quantization (default true).
1118 void quantizeDither ( const bool ditherFlag_ );
1119 bool quantizeDither ( void ) const;
1121 // Quantization tree-depth
1122 void quantizeTreeDepth ( const size_t treeDepth_ );
1123 size_t quantizeTreeDepth ( void ) const;
1125 // The type of rendering intent
1126 void renderingIntent ( const RenderingIntent renderingIntent_ );
1127 RenderingIntent renderingIntent ( void ) const;
1129 // Units of image resolution
1130 void resolutionUnits ( const ResolutionType resolutionUnits_ );
1131 ResolutionType resolutionUnits ( void ) const;
1133 // The number of pixel rows in the image
1134 size_t rows ( void ) const;
1136 // Image scene number
1137 void scene ( const size_t scene_ );
1138 size_t scene ( void ) const;
1140 // Image signature. Set force_ to true in order to re-calculate
1141 // the signature regardless of whether the image data has been
1143 std::string signature ( const bool force_ = false ) const;
1145 // Width and height of a raw image
1146 void size ( const Geometry &geometry_ );
1147 Geometry size ( void ) const;
1149 // enabled/disable stroke anti-aliasing
1150 void strokeAntiAlias( const bool flag_ );
1151 bool strokeAntiAlias( void ) const;
1153 // Color to use when drawing object outlines
1154 void strokeColor ( const Color &strokeColor_ );
1155 Color strokeColor ( void ) const;
1157 // Specify the pattern of dashes and gaps used to stroke
1158 // paths. The strokeDashArray represents a zero-terminated array
1159 // of numbers that specify the lengths of alternating dashes and
1160 // gaps in pixels. If an odd number of values is provided, then
1161 // the list of values is repeated to yield an even number of
1162 // values. A typical strokeDashArray_ array might contain the
1163 // members 5 3 2 0, where the zero value indicates the end of the
1165 void strokeDashArray ( const double* strokeDashArray_ );
1166 const double* strokeDashArray ( void ) const;
1168 // While drawing using a dash pattern, specify distance into the
1169 // dash pattern to start the dash (default 0).
1170 void strokeDashOffset ( const double strokeDashOffset_ );
1171 double strokeDashOffset ( void ) const;
1173 // Specify the shape to be used at the end of open subpaths when
1174 // they are stroked. Values of LineCap are UndefinedCap, ButtCap,
1175 // RoundCap, and SquareCap.
1176 void strokeLineCap ( const LineCap lineCap_ );
1177 LineCap strokeLineCap ( void ) const;
1179 // Specify the shape to be used at the corners of paths (or other
1180 // vector shapes) when they are stroked. Values of LineJoin are
1181 // UndefinedJoin, MiterJoin, RoundJoin, and BevelJoin.
1182 void strokeLineJoin ( const LineJoin lineJoin_ );
1183 LineJoin strokeLineJoin ( void ) const;
1185 // Specify miter limit. When two line segments meet at a sharp
1186 // angle and miter joins have been specified for 'lineJoin', it is
1187 // possible for the miter to extend far beyond the thickness of
1188 // the line stroking the path. The miterLimit' imposes a limit on
1189 // the ratio of the miter length to the 'lineWidth'. The default
1190 // value of this parameter is 4.
1191 void strokeMiterLimit ( const size_t miterLimit_ );
1192 size_t strokeMiterLimit ( void ) const;
1194 // Pattern image to use while stroking object outlines.
1195 void strokePattern ( const Image &strokePattern_ );
1196 Image strokePattern ( void ) const;
1198 // Stroke width for drawing vector objects (default one)
1199 void strokeWidth ( const double strokeWidth_ );
1200 double strokeWidth ( void ) const;
1202 // Subimage of an image sequence
1203 void subImage ( const size_t subImage_ );
1204 size_t subImage ( void ) const;
1206 // Number of images relative to the base image
1207 void subRange ( const size_t subRange_ );
1208 size_t subRange ( void ) const;
1210 // Annotation text encoding (e.g. "UTF-16")
1211 void textEncoding ( const std::string &encoding_ );
1212 std::string textEncoding ( void ) const;
1215 void tileName ( const std::string &tileName_ );
1216 std::string tileName ( void ) const;
1218 // Number of colors in the image
1219 size_t totalColors ( void );
1221 // Origin of coordinate system to use when annotating with text or drawing
1222 void transformOrigin ( const double x_,const double y_ );
1224 // Rotation to use when annotating with text or drawing
1225 void transformRotation ( const double angle_ );
1227 // Reset transformation parameters to default
1228 void transformReset ( void );
1230 // Scale to use when annotating with text or drawing
1231 void transformScale ( const double sx_, const double sy_ );
1233 // Skew to use in X axis when annotating with text or drawing
1234 void transformSkewX ( const double skewx_ );
1236 // Skew to use in Y axis when annotating with text or drawing
1237 void transformSkewY ( const double skewy_ );
1239 // Image representation type (also see type operation)
1241 // Bilevel Grayscale GrayscaleMatte
1242 // Palette PaletteMatte TrueColor
1243 // TrueColorMatte ColorSeparation ColorSeparationMatte
1244 ImageType type ( void ) const;
1246 // Print detailed information about the image
1247 void verbose ( const bool verboseFlag_ );
1248 bool verbose ( void ) const;
1250 // FlashPix viewing parameters
1251 void view ( const std::string &view_ );
1252 std::string view ( void ) const;
1254 // Virtual pixel method
1255 void virtualPixelMethod ( const VirtualPixelMethod virtual_pixel_method_ );
1256 VirtualPixelMethod virtualPixelMethod ( void ) const;
1258 // X11 display to display to, obtain fonts from, or to capture
1260 void x11Display ( const std::string &display_ );
1261 std::string x11Display ( void ) const;
1263 // x resolution of the image
1264 double xResolution ( void ) const;
1266 // y resolution of the image
1267 double yResolution ( void ) const;
1269 //////////////////////////////////////////////////////////////////////
1271 // Low-level Pixel Access Routines
1273 // Also see the Pixels class, which provides support for multiple
1276 //////////////////////////////////////////////////////////////////////
1279 // Transfers read-only pixels from the image to the pixel cache as
1280 // defined by the specified region
1281 const PixelPacket* getConstPixels ( const ssize_t x_, const ssize_t y_,
1282 const size_t columns_,
1283 const size_t rows_ ) const;
1285 // Obtain mutable image pixel indexes (valid for PseudoClass images)
1286 IndexPacket* getIndexes ( void );
1288 // Obtain immutable image pixel indexes (valid for PseudoClass images)
1289 const IndexPacket* getConstIndexes ( void ) const;
1291 // Transfers pixels from the image to the pixel cache as defined
1292 // by the specified region. Modified pixels may be subsequently
1293 // transferred back to the image via syncPixels. This method is
1294 // valid for DirectClass images.
1295 PixelPacket* getPixels ( const ssize_t x_, const ssize_t y_,
1296 const size_t columns_,
1297 const size_t rows_ );
1299 // Allocates a pixel cache region to store image pixels as defined
1300 // by the region rectangle. This area is subsequently transferred
1301 // from the pixel cache to the image via syncPixels.
1302 PixelPacket* setPixels ( const ssize_t x_, const ssize_t y_,
1303 const size_t columns_,
1304 const size_t rows_ );
1306 // Transfers the image cache pixels to the image.
1307 void syncPixels ( void );
1309 // Transfers one or more pixel components from a buffer or file
1310 // into the image pixel cache of an image.
1311 // Used to support image decoders.
1312 void readPixels ( const QuantumType quantum_,
1313 const unsigned char *source_ );
1315 // Transfers one or more pixel components from the image pixel
1316 // cache to a buffer or file.
1317 // Used to support image encoders.
1318 void writePixels ( const QuantumType quantum_,
1319 unsigned char *destination_ );
1321 //////////////////////////////////////////////////////////////////////
1323 // No user-serviceable parts beyond this point
1325 //////////////////////////////////////////////////////////////////////
1328 // Construct with MagickCore::Image and default options
1329 Image ( MagickCore::Image* image_ );
1332 MagickCore::Image*& image( void );
1333 const MagickCore::Image* constImage( void ) const;
1335 // Retrieve Options*
1336 Options* options( void );
1337 const Options* constOptions( void ) const;
1339 // Retrieve ImageInfo*
1340 MagickCore::ImageInfo * imageInfo( void );
1341 const MagickCore::ImageInfo * constImageInfo( void ) const;
1343 // Retrieve QuantizeInfo*
1344 MagickCore::QuantizeInfo * quantizeInfo( void );
1345 const MagickCore::QuantizeInfo * constQuantizeInfo( void ) const;
1347 // Replace current image (reference counted)
1348 MagickCore::Image* replaceImage ( MagickCore::Image* replacement_ );
1350 // Prepare to update image (copy if reference > 1)
1351 void modifyImage ( void );
1353 // Test for ImageMagick error and throw exception if error
1354 void throwImageException( void ) const;
1356 // Register image with image registry or obtain registration id
1357 ssize_t registerId( void );
1359 // Unregister image from image registry
1360 void unregisterId( void) ;
1366 } // end of namespace Magick
1378 // Reduce noise in image using a noise peak elimination filter
1379 inline void Magick::Image::reduceNoise ( void )
1384 // Stroke width for drawing vector objects (default one)
1385 inline void Magick::Image::lineWidth ( const double lineWidth_ )
1387 strokeWidth( lineWidth_ );
1389 inline double Magick::Image::lineWidth ( void ) const
1391 return strokeWidth( );
1394 // Get image storage class
1395 inline Magick::ClassType Magick::Image::classType ( void ) const
1397 return static_cast<Magick::ClassType>(constImage()->storage_class);
1400 // Get number of image columns
1401 inline size_t Magick::Image::columns ( void ) const
1403 return constImage()->columns;
1406 // Get number of image rows
1407 inline size_t Magick::Image::rows ( void ) const
1409 return constImage()->rows;
1412 #endif // Magick_Image_header