Magick++  6.9.3
Image.h
Go to the documentation of this file.
1 // This may look like C code, but it is really -*- C++ -*-
2 //
3 // Copyright Bob Friesenhahn, 1999, 2000, 2001, 2002, 2003
4 // Copyright Dirk Lemstra 2013-2015
5 //
6 // Definition of Image, the representation of a single image in Magick++
7 //
8 
9 #if !defined(Magick_Image_header)
10 #define Magick_Image_header
11 
12 #include "Magick++/Include.h"
13 #include <string>
14 #include <list>
15 #include "Magick++/Blob.h"
17 #include "Magick++/Color.h"
18 #include "Magick++/Drawable.h"
19 #include "Magick++/Exception.h"
20 #include "Magick++/Geometry.h"
21 #include "Magick++/TypeMetric.h"
22 
23 namespace Magick
24 {
25  // Forward declarations
26  class Options;
27  class ImageRef;
28 
29  extern MagickPPExport const char *borderGeometryDefault;
30  extern MagickPPExport const char *frameGeometryDefault;
31  extern MagickPPExport const char *raiseGeometryDefault;
32 
33  // Compare two Image objects regardless of LHS/RHS
34  // Image sizes and signatures are used as basis of comparison
35  MagickPPExport int operator ==
36  (const Magick::Image &left_,const Magick::Image &right_);
37  MagickPPExport int operator !=
38  (const Magick::Image &left_,const Magick::Image &right_);
39  MagickPPExport int operator >
40  (const Magick::Image &left_,const Magick::Image &right_);
41  MagickPPExport int operator <
42  (const Magick::Image &left_,const Magick::Image &right_);
43  MagickPPExport int operator >=
44  (const Magick::Image &left_,const Magick::Image &right_);
45  MagickPPExport int operator <=
46  (const Magick::Image &left_,const Magick::Image &right_);
47 
48  //
49  // Image is the representation of an image. In reality, it actually
50  // a handle object which contains a pointer to a shared reference
51  // object (ImageRef). As such, this object is extremely space efficient.
52  //
54  {
55  public:
56 
57  // Obtain image statistics. Statistics are normalized to the range
58  // of 0.0 to 1.0 and are output to the specified ImageStatistics
59  // structure.
60  typedef struct _ImageChannelStatistics
61  {
62  /* Minimum value observed */
63  double maximum;
64  /* Maximum value observed */
65  double minimum;
66  /* Average (mean) value observed */
67  double mean;
68  /* Standard deviation, sqrt(variance) */
70  /* Variance */
71  double variance;
72  /* Kurtosis */
73  double kurtosis;
74  /* Skewness */
75  double skewness;
77 
78  typedef struct _ImageStatistics
79  {
85 
86  // Default constructor
87  Image(void);
88 
89  // Construct Image from in-memory BLOB
90  Image(const Blob &blob_);
91 
92  // Construct Image of specified size from in-memory BLOB
93  Image(const Blob &blob_,const Geometry &size_);
94 
95  // Construct Image of specified size and depth from in-memory BLOB
96  Image(const Blob &blob_,const Geometry &size_,const size_t depth_);
97 
98  // Construct Image of specified size, depth, and format from
99  // in-memory BLOB
100  Image(const Blob &blob_,const Geometry &size_,const size_t depth_,
101  const std::string &magick_);
102 
103  // Construct Image of specified size, and format from in-memory BLOB
104  Image(const Blob &blob_,const Geometry &size_,const std::string &magick_);
105 
106  // Construct a blank image canvas of specified size and color
107  Image(const Geometry &size_,const Color &color_);
108 
109  // Copy constructor
110  Image(const Image &image_);
111 
112  // Copy constructor to copy part of the image
113  Image(const Image &image_,const Geometry &geometry_);
114 
115  // Construct an image based on an array of raw pixels, of
116  // specified type and mapping, in memory
117  Image(const size_t width_,const size_t height_,const std::string &map_,
118  const StorageType type_,const void *pixels_);
119 
120  // Construct from image file or image specification
121  Image(const std::string &imageSpec_);
122 
123  // Destructor
124  virtual ~Image();
125 
126  // Assignment operator
127  Image& operator=(const Image &image_);
128 
129  // Join images into a single multi-image file
130  void adjoin(const bool flag_);
131  bool adjoin(void) const;
132 
133  // Anti-alias Postscript and TrueType fonts (default true)
134  void antiAlias(const bool flag_);
135  bool antiAlias(void) const;
136 
137  // Time in 1/100ths of a second which must expire before
138  // displaying the next image in an animated sequence.
139  void animationDelay(const size_t delay_);
140  size_t animationDelay(void) const;
141 
142  // Number of iterations to loop an animation (e.g. Netscape loop
143  // extension) for.
144  void animationIterations(const size_t iterations_);
145  size_t animationIterations(void) const;
146 
147  // Lessen (or intensify) when adding noise to an image.
148  void attenuate(const double attenuate_);
149 
150  // Image background color
151  void backgroundColor(const Color &color_);
152  Color backgroundColor(void) const;
153 
154  // Name of texture image to tile onto the image background
155  void backgroundTexture(const std::string &backgroundTexture_);
156  std::string backgroundTexture(void) const;
157 
158  // Base image width (before transformations)
159  size_t baseColumns(void) const;
160 
161  // Base image filename (before transformations)
162  std::string baseFilename(void) const;
163 
164  // Base image height (before transformations)
165  size_t baseRows(void) const;
166 
167  // Use black point compensation.
168  void blackPointCompensation(const bool flag_);
169  bool blackPointCompensation(void) const;
170 
171  // Image border color
172  void borderColor(const Color &color_);
173  Color borderColor(void) const;
174 
175  // Return smallest bounding box enclosing non-border pixels. The
176  // current fuzz value is used when discriminating between pixels.
177  // This is the crop bounding box used by crop(Geometry(0,0));
178  Geometry boundingBox(void) const;
179 
180  // Text bounding-box base color (default none)
181  void boxColor(const Color &boxColor_);
182  Color boxColor(void) const;
183 
184  // This method is now deprecated. Please use ResourceLimits instead.
185  static void cacheThreshold(const size_t threshold_);
186 
187  // Image class (DirectClass or PseudoClass)
188  // NOTE: setting a DirectClass image to PseudoClass will result in
189  // the loss of color information if the number of colors in the
190  // image is greater than the maximum palette size (either 256 or
191  // 65536 entries depending on the value of MAGICKCORE_QUANTUM_DEPTH when
192  // ImageMagick was built).
193  void classType(const ClassType class_);
194  ClassType classType(void) const;
195 
196  // Associate a clip mask with the image. The clip mask must be the
197  // same dimensions as the image. Pass an invalid image to unset an
198  // existing clip mask.
199  void clipMask(const Image &clipMask_);
200  Image clipMask(void) const;
201 
202  // Colors within this distance are considered equal
203  void colorFuzz(const double fuzz_);
204  double colorFuzz(void) const;
205 
206  // Colormap size (number of colormap entries)
207  void colorMapSize(const size_t entries_);
208  size_t colorMapSize(void) const;
209 
210  // Image Color Space
211  void colorSpace(const ColorspaceType colorSpace_);
212  ColorspaceType colorSpace(void) const;
213 
214  void colorspaceType(const ColorspaceType colorSpace_);
215  ColorspaceType colorspaceType(void) const;
216 
217  // Image width
218  size_t columns(void) const;
219 
220  // Comment image (add comment string to image)
221  void comment(const std::string &comment_);
222  std::string comment(void) const;
223 
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;
228 
229  // Compression type
230  void compressType(const CompressionType compressType_);
231  CompressionType compressType(void) const;
232 
233  // Enable printing of debug messages from ImageMagick
234  void debug(const bool flag_);
235  bool debug(void) const;
236 
237  // Vertical and horizontal resolution in pixels of the image
238  void density(const Geometry &geomery_);
239  Geometry density(void) const;
240 
241  // Image depth (bits allocated to red/green/blue components)
242  void depth(const size_t depth_);
243  size_t depth(void) const;
244 
245  // Tile names from within an image montage
246  std::string directory(void) const;
247 
248  // Endianness (little like Intel or big like SPARC) for image
249  // formats which support endian-specific options.
250  void endian(const EndianType endian_);
251  EndianType endian(void) const;
252 
253  // Exif profile (BLOB)
254  void exifProfile(const Blob &exifProfile_);
255  Blob exifProfile(void) const;
256 
257  // Image file name
258  void fileName(const std::string &fileName_);
259  std::string fileName(void) const;
260 
261  // Number of bytes of the image on disk
262  off_t fileSize(void) const;
263 
264  // Color to use when filling drawn objects
265  void fillColor(const Color &fillColor_);
266  Color fillColor(void) const;
267 
268  // Rule to use when filling drawn objects
269  void fillRule(const FillRule &fillRule_);
270  FillRule fillRule(void) const;
271 
272  // Pattern to use while filling drawn objects.
273  void fillPattern(const Image &fillPattern_);
274  Image fillPattern(void) const;
275 
276  // Filter to use when resizing image
277  void filterType(const FilterTypes filterType_);
278  FilterTypes filterType(void) const;
279 
280  // Text rendering font
281  void font(const std::string &font_);
282  std::string font(void) const;
283 
284  // Font family
285  void fontFamily(const std::string &family_);
286  std::string fontFamily(void) const;
287 
288  // Font point size
289  void fontPointsize(const double pointSize_);
290  double fontPointsize(void) const;
291 
292  // Font style
293  void fontStyle(const StyleType style_);
294  StyleType fontStyle(void) const;
295 
296  // Font weight
297  void fontWeight(const size_t weight_);
298  size_t fontWeight(void) const;
299 
300 
301  // Long image format description
302  std::string format(void) const;
303 
304  // Formats the specified expression
305  // More info here: https://imagemagick.org/script/escape.php
306  std::string formatExpression(const std::string expression);
307 
308  // Gamma level of the image
309  double gamma(void) const;
310 
311  // Preferred size of the image when encoding
312  Geometry geometry(void) const;
313 
314  // GIF disposal method
315  void gifDisposeMethod(const size_t disposeMethod_);
316  size_t gifDisposeMethod(void) const;
317 
318  // When comparing images, emphasize pixel differences with this color.
319  void highlightColor(const Color color_);
320 
321  // ICC color profile (BLOB)
322  void iccColorProfile(const Blob &colorProfile_);
323  Blob iccColorProfile(void) const;
324 
325  // Type of interlacing to use
326  void interlaceType(const InterlaceType interlace_);
327  InterlaceType interlaceType(void) const;
328 
329  // Pixel color interpolation method to use
330  void interpolate(const InterpolatePixelMethod interpolate_);
331  InterpolatePixelMethod interpolate(void) const;
332 
333  // IPTC profile (BLOB)
334  void iptcProfile(const Blob &iptcProfile_);
335  Blob iptcProfile(void) const;
336 
337  // Returns true if none of the pixels in the image have an alpha value
338  // other than OpaqueAlpha (QuantumRange).
339  bool isOpaque(void) const;
340 
341  // Does object contain valid image?
342  void isValid(const bool isValid_);
343  bool isValid(void) const;
344 
345  // Image label
346  void label(const std::string &label_);
347  std::string label(void) const;
348 
349  // Stroke width for drawing vector objects (default one)
350  // This method is now deprecated. Please use strokeWidth instead.
351  void lineWidth(const double lineWidth_);
352  double lineWidth(void) const;
353 
354  // When comparing images, de-emphasize pixel differences with this color.
355  void lowlightColor(const Color color_);
356 
357  // File type magick identifier (.e.g "GIF")
358  void magick(const std::string &magick_);
359  std::string magick(void) const;
360 
361  // Associate a mask with the image. The mask must be the same dimensions
362  // as the image. Pass an invalid image to unset an existing clip mask.
363  void mask(const Image &mask_);
364  Image mask(void) const;
365 
366  // Image supports transparency (matte channel)
367  void matte(const bool matteFlag_);
368  bool matte(void) const;
369 
370  // Transparent color
371  void matteColor(const Color &matteColor_);
372  Color matteColor(void) const;
373 
374  // The mean error per pixel computed when an image is color reduced
375  double meanErrorPerPixel(void) const;
376 
377  // Image modulus depth (minimum number of bits required to support
378  // red/green/blue components without loss of accuracy)
379  void modulusDepth(const size_t modulusDepth_);
380  size_t modulusDepth(void) const;
381 
382  // Transform image to black and white
383  void monochrome(const bool monochromeFlag_);
384  bool monochrome(void) const;
385 
386  // Tile size and offset within an image montage
387  Geometry montageGeometry(void) const;
388 
389  // The normalized max error per pixel computed when an image is
390  // color reduced.
391  double normalizedMaxError(void) const;
392 
393  // The normalized mean error per pixel computed when an image is
394  // color reduced.
395  double normalizedMeanError(void) const;
396 
397  // Image orientation
398  void orientation(const OrientationType orientation_);
399  OrientationType orientation(void) const;
400 
401  // Preferred size and location of an image canvas.
402  void page(const Geometry &pageSize_);
403  Geometry page(void) const;
404 
405  // Pen color (deprecated, don't use any more)
406  void penColor(const Color &penColor_);
407  Color penColor(void) const;
408 
409  // Pen texture image (deprecated, don't use any more)
410  void penTexture(const Image &penTexture_);
411  Image penTexture(void) const;
412 
413  // JPEG/MIFF/PNG compression level (default 75).
414  void quality(const size_t quality_);
415  size_t quality(void) const;
416 
417  // Maximum number of colors to quantize to
418  void quantizeColors(const size_t colors_);
419  size_t quantizeColors(void) const;
420 
421  // Colorspace to quantize in.
422  void quantizeColorSpace(const ColorspaceType colorSpace_);
423  ColorspaceType quantizeColorSpace(void) const;
424 
425  // Dither image during quantization (default true).
426  void quantizeDither(const bool ditherFlag_);
427  bool quantizeDither(void) const;
428 
429  // Dither method
430  void quantizeDitherMethod(const DitherMethod ditherMethod_);
431  DitherMethod quantizeDitherMethod(void) const;
432 
433  // Quantization tree-depth
434  void quantizeTreeDepth(const size_t treeDepth_);
435  size_t quantizeTreeDepth(void) const;
436 
437  // Suppress all warning messages. Error messages are still reported.
438  void quiet(const bool quiet_);
439  bool quiet(void) const;
440 
441  // The type of rendering intent
442  void renderingIntent(const RenderingIntent renderingIntent_);
443  RenderingIntent renderingIntent(void) const;
444 
445  // Units of image resolution
446  void resolutionUnits(const ResolutionType resolutionUnits_);
447  ResolutionType resolutionUnits(void) const;
448 
449  // The number of pixel rows in the image
450  size_t rows(void) const;
451 
452  // Image scene number
453  void scene(const size_t scene_);
454  size_t scene(void) const;
455 
456  // Width and height of a raw image
457  void size(const Geometry &geometry_);
458  Geometry size(void) const;
459 
460  // enabled/disable stroke anti-aliasing
461  void strokeAntiAlias(const bool flag_);
462  bool strokeAntiAlias(void) const;
463 
464  // Color to use when drawing object outlines
465  void strokeColor(const Color &strokeColor_);
466  Color strokeColor(void) const;
467 
468  // Specify the pattern of dashes and gaps used to stroke
469  // paths. The strokeDashArray represents a zero-terminated array
470  // of numbers that specify the lengths of alternating dashes and
471  // gaps in pixels. If an odd number of values is provided, then
472  // the list of values is repeated to yield an even number of
473  // values. A typical strokeDashArray_ array might contain the
474  // members 5 3 2 0, where the zero value indicates the end of the
475  // pattern array.
476  void strokeDashArray(const double *strokeDashArray_);
477  const double *strokeDashArray(void) const;
478 
479  // While drawing using a dash pattern, specify distance into the
480  // dash pattern to start the dash (default 0).
481  void strokeDashOffset(const double strokeDashOffset_);
482  double strokeDashOffset(void) const;
483 
484  // Specify the shape to be used at the end of open subpaths when
485  // they are stroked. Values of LineCap are UndefinedCap, ButtCap,
486  // RoundCap, and SquareCap.
487  void strokeLineCap(const LineCap lineCap_);
488  LineCap strokeLineCap(void) const;
489 
490  // Specify the shape to be used at the corners of paths (or other
491  // vector shapes) when they are stroked. Values of LineJoin are
492  // UndefinedJoin, MiterJoin, RoundJoin, and BevelJoin.
493  void strokeLineJoin(const LineJoin lineJoin_);
494  LineJoin strokeLineJoin(void) const;
495 
496  // Specify miter limit. When two line segments meet at a sharp
497  // angle and miter joins have been specified for 'lineJoin', it is
498  // possible for the miter to extend far beyond the thickness of
499  // the line stroking the path. The miterLimit' imposes a limit on
500  // the ratio of the miter length to the 'lineWidth'. The default
501  // value of this parameter is 4.
502  void strokeMiterLimit(const size_t miterLimit_);
503  size_t strokeMiterLimit(void) const;
504 
505  // Pattern image to use while stroking object outlines.
506  void strokePattern(const Image &strokePattern_);
507  Image strokePattern(void) const;
508 
509  // Stroke width for drawing vector objects (default one)
510  void strokeWidth(const double strokeWidth_);
511  double strokeWidth(void) const;
512 
513  // Subimage of an image sequence
514  void subImage(const size_t subImage_);
515  size_t subImage(void) const;
516 
517  // Number of images relative to the base image
518  void subRange(const size_t subRange_);
519  size_t subRange(void) const;
520 
521  // Render text right-to-left or left-to-right.
522  void textDirection(DirectionType direction_);
523  DirectionType textDirection() const;
524 
525  // Annotation text encoding (e.g. "UTF-16")
526  void textEncoding(const std::string &encoding_);
527  std::string textEncoding(void) const;
528 
529  // Text gravity.
530  void textGravity(GravityType gravity_);
531  GravityType textGravity() const;
532 
533  // Text inter-line spacing
534  void textInterlineSpacing(double spacing_);
535  double textInterlineSpacing(void) const;
536 
537  // Text inter-word spacing
538  void textInterwordSpacing(double spacing_);
539  double textInterwordSpacing(void) const;
540 
541  // Text inter-character kerning
542  void textKerning(double kerning_);
543  double textKerning(void) const;
544 
545  // Text undercolor box
546  void textUnderColor(const Color &underColor_);
547  Color textUnderColor(void) const;
548 
549  // Tile name
550  void tileName(const std::string &tileName_);
551  std::string tileName(void) const;
552 
553  // Number of colors in the image
554  size_t totalColors(void) const;
555 
556  // Rotation to use when annotating with text or drawing
557  void transformRotation(const double angle_);
558 
559  // Skew to use in X axis when annotating with text or drawing
560  void transformSkewX(const double skewx_);
561 
562  // Skew to use in Y axis when annotating with text or drawing
563  void transformSkewY(const double skewy_);
564 
565  // Image representation type (also see type operation)
566  // Available types:
567  // Bilevel Grayscale GrayscaleMatte
568  // Palette PaletteMatte TrueColor
569  // TrueColorMatte ColorSeparation ColorSeparationMatte
570  void type(const ImageType type_);
571  ImageType type(void) const;
572 
573  // Print detailed information about the image
574  void verbose(const bool verboseFlag_);
575  bool verbose(void) const;
576 
577  // FlashPix viewing parameters
578  void view(const std::string &view_);
579  std::string view(void) const;
580 
581  // Virtual pixel method
582  void virtualPixelMethod(const VirtualPixelMethod virtual_pixel_method_);
583  VirtualPixelMethod virtualPixelMethod(void) const;
584 
585  // X11 display to display to, obtain fonts from, or to capture
586  // image from
587  void x11Display(const std::string &display_);
588  std::string x11Display(void) const;
589 
590  // x resolution of the image
591  double xResolution(void) const;
592 
593  // y resolution of the image
594  double yResolution(void) const;
595 
596  // Adaptive-blur image with specified blur factor
597  // The radius_ parameter specifies the radius of the Gaussian, in
598  // pixels, not counting the center pixel. The sigma_ parameter
599  // specifies the standard deviation of the Laplacian, in pixels.
600  void adaptiveBlur(const double radius_=0.0,const double sigma_=1.0);
601 
602  // This is shortcut function for a fast interpolative resize using mesh
603  // interpolation. It works well for small resizes of less than +/- 50%
604  // of the original image size. For larger resizing on images a full
605  // filtered and slower resize function should be used instead.
606  void adaptiveResize(const Geometry &geometry_);
607 
608  // Adaptively sharpens the image by sharpening more intensely near image
609  // edges and less intensely far from edges. We sharpen the image with a
610  // Gaussian operator of the given radius and standard deviation (sigma).
611  // For reasonable results, radius should be larger than sigma.
612  void adaptiveSharpen(const double radius_=0.0,const double sigma_=1.0);
613  void adaptiveSharpenChannel(const ChannelType channel_,
614  const double radius_=0.0,const double sigma_=1.0);
615 
616  // Local adaptive threshold image
617  // http://www.dai.ed.ac.uk/HIPR2/adpthrsh.htm
618  // Width x height define the size of the pixel neighborhood
619  // offset = constant to subtract from pixel neighborhood mean
620  void adaptiveThreshold(const size_t width,const size_t height,
621  const ::ssize_t offset=0);
622 
623  // Add noise to image with specified noise type
624  void addNoise(const NoiseType noiseType_);
625  void addNoiseChannel(const ChannelType channel_,
626  const NoiseType noiseType_);
627 
628  // Transform image by specified affine (or free transform) matrix.
629  void affineTransform(const DrawableAffine &affine);
630 
631  // Activates, deactivates, resets, or sets the alpha channel.
632  void alphaChannel(AlphaChannelType alphaType_);
633 
634  //
635  // Annotate image (draw text on image)
636  //
637  // Gravity effects text placement in bounding area according to rules:
638  // NorthWestGravity text bottom-left corner placed at top-left
639  // NorthGravity text bottom-center placed at top-center
640  // NorthEastGravity text bottom-right corner placed at top-right
641  // WestGravity text left-center placed at left-center
642  // CenterGravity text center placed at center
643  // EastGravity text right-center placed at right-center
644  // SouthWestGravity text top-left placed at bottom-left
645  // SouthGravity text top-center placed at bottom-center
646  // SouthEastGravity text top-right placed at bottom-right
647 
648  // Annotate using specified text, and placement location
649  void annotate(const std::string &text_,const Geometry &location_);
650 
651  // Annotate using specified text, bounding area, and placement
652  // gravity
653  void annotate(const std::string &text_,const Geometry &boundingArea_,
654  const GravityType gravity_);
655 
656  // Annotate with text using specified text, bounding area,
657  // placement gravity, and rotation.
658  void annotate(const std::string &text_,const Geometry &boundingArea_,
659  const GravityType gravity_,const double degrees_);
660 
661  // Annotate with text (bounding area is entire image) and placement
662  // gravity.
663  void annotate(const std::string &text_,const GravityType gravity_);
664 
665  // Inserts the artifact with the specified name and value into
666  // the artifact tree of the image.
667  void artifact(const std::string &name_,const std::string &value_);
668 
669  // Returns the value of the artifact with the specified name.
670  std::string artifact(const std::string &name_) const;
671 
672  // Access/Update a named image attribute
673  void attribute(const std::string name_,const char *value_);
674  void attribute(const std::string name_,const std::string value_);
675  std::string attribute(const std::string name_ ) const;
676 
677  // Extracts the 'mean' from the image and adjust the image to try
678  // make set its gamma appropriatally.
679  void autoGamma(void);
680  void autoGammaChannel(const ChannelType channel_);
681 
682  // Adjusts the levels of a particular image channel by scaling the
683  // minimum and maximum values to the full quantum range.
684  void autoLevel(void);
685  void autoLevelChannel(const ChannelType channel_);
686 
687  // Adjusts an image so that its orientation is suitable for viewing.
688  void autoOrient(void);
689 
690  // Forces all pixels below the threshold into black while leaving all
691  // pixels at or above the threshold unchanged.
692  void blackThreshold(const std::string &threshold_);
693  void blackThresholdChannel(const ChannelType channel_,
694  const std::string &threshold_);
695 
696  // Simulate a scene at nighttime in the moonlight.
697  void blueShift(const double factor_=1.5);
698 
699  // Blur image with specified blur factor
700  // The radius_ parameter specifies the radius of the Gaussian, in
701  // pixels, not counting the center pixel. The sigma_ parameter
702  // specifies the standard deviation of the Laplacian, in pixels.
703  void blur(const double radius_=0.0,const double sigma_=1.0);
704  void blurChannel(const ChannelType channel_,const double radius_=0.0,
705  const double sigma_=1.0);
706 
707  // Border image (add border to image)
708  void border(const Geometry &geometry_=borderGeometryDefault);
709 
710  // Changes the brightness and/or contrast of an image. It converts the
711  // brightness and contrast parameters into slope and intercept and calls
712  // a polynomical function to apply to the image.
713  void brightnessContrast(const double brightness_=0.0,
714  const double contrast_=0.0);
715  void brightnessContrastChannel(const ChannelType channel_,
716  const double brightness_=0.0,const double contrast_=0.0);
717 
718  // Uses a multi-stage algorithm to detect a wide range of edges in images.
719  void cannyEdge(const double radius_=0.0,const double sigma_=1.0,
720  const double lowerPercent_=0.1,const double upperPercent_=0.3);
721 
722  // Accepts a lightweight Color Correction Collection
723  // (CCC) file which solely contains one or more color corrections and
724  // applies the correction to the image.
725  void cdl(const std::string &cdl_);
726 
727  // Extract channel from image
728  void channel(const ChannelType channel_);
729 
730  // Set or obtain modulus channel depth
731  void channelDepth(const ChannelType channel_,const size_t depth_);
732  size_t channelDepth(const ChannelType channel_);
733 
734  // Charcoal effect image (looks like charcoal sketch)
735  // The radius_ parameter specifies the radius of the Gaussian, in
736  // pixels, not counting the center pixel. The sigma_ parameter
737  // specifies the standard deviation of the Laplacian, in pixels.
738  void charcoal(const double radius_=0.0,const double sigma_=1.0);
739 
740  // Chop image (remove vertical or horizontal subregion of image)
741  // FIXME: describe how geometry argument is used to select either
742  // horizontal or vertical subregion of image.
743  void chop(const Geometry &geometry_);
744 
745  // Chromaticity blue primary point (e.g. x=0.15, y=0.06)
746  void chromaBluePrimary(const double x_,const double y_);
747  void chromaBluePrimary(double *x_, double *y_) const;
748 
749  // Chromaticity green primary point (e.g. x=0.3, y=0.6)
750  void chromaGreenPrimary(const double x_,const double y_);
751  void chromaGreenPrimary(double *x_,double *y_) const;
752 
753  // Chromaticity red primary point (e.g. x=0.64, y=0.33)
754  void chromaRedPrimary(const double x_,const double y_);
755  void chromaRedPrimary(double *x_,double *y_) const;
756 
757  // Chromaticity white point (e.g. x=0.3127, y=0.329)
758  void chromaWhitePoint(const double x_,const double y_);
759  void chromaWhitePoint(double *x_,double *y_) const;
760 
761  // Set each pixel whose value is below zero to zero and any the
762  // pixel whose value is above the quantum range to the quantum range (e.g.
763  // 65535) otherwise the pixel value remains unchanged.
764  void clamp(void);
765  void clampChannel(const ChannelType channel_);
766 
767  // Sets the image clip mask based on any clipping path information
768  // if it exists.
769  void clip(void);
770 
771  void clipPath(const std::string pathname_,const bool inside_);
772 
773  // Apply a color lookup table (CLUT) to the image.
774  void clut(const Image &clutImage_);
775  void clutChannel(const ChannelType channel_,const Image &clutImage_);
776 
777  // Colorize image with pen color, using specified percent opacity.
778  void colorize(const unsigned int opacity_,const Color &penColor_);
779 
780  // Colorize image with pen color, using specified percent opacity
781  // for red, green, and blue quantums
782  void colorize(const unsigned int opacityRed_,
783  const unsigned int opacityGreen_,const unsigned int opacityBlue_,
784  const Color &penColor_);
785 
786  // Color at colormap position index_
787  void colorMap(const size_t index_,const Color &color_);
788  Color colorMap(const size_t index_) const;
789 
790  // Apply a color matrix to the image channels. The user supplied
791  // matrix may be of order 1 to 5 (1x1 through 5x5).
792  void colorMatrix(const size_t order_,const double *color_matrix_);
793 
794  // Compare current image with another image
795  // Sets meanErrorPerPixel, normalizedMaxError, and normalizedMeanError
796  // in the current image. False is returned if the images are identical.
797  bool compare(const Image &reference_);
798 
799  // Compare current image with another image
800  // Returns the distortion based on the specified metric.
801  double compare(const Image &reference_,const MetricType metric_);
802  double compareChannel(const ChannelType channel_,const Image &reference_,
803  const MetricType metric_);
804 
805  // Compare current image with another image
806  // Sets the distortion and returns the difference image.
807  Image compare(const Image &reference_,const MetricType metric_,
808  double *distortion);
809  Image compareChannel(const ChannelType channel_,const Image &reference_,
810  const MetricType metric_,double *distortion );
811 
812  // Compose an image onto another at specified offset and using
813  // specified algorithm
814  void composite(const Image &compositeImage_,const Geometry &offset_,
815  const CompositeOperator compose_=InCompositeOp);
816  void composite(const Image &compositeImage_,const GravityType gravity_,
817  const CompositeOperator compose_=InCompositeOp);
818  void composite(const Image &compositeImage_,const ::ssize_t xOffset_,
819  const ::ssize_t yOffset_,const CompositeOperator compose_=InCompositeOp);
820 
821  // Determines the connected-components of the image
822  void connectedComponents(const size_t connectivity_);
823 
824  // Contrast image (enhance intensity differences in image)
825  void contrast(const size_t sharpen_);
826 
827  // A simple image enhancement technique that attempts to improve the
828  // contrast in an image by 'stretching' the range of intensity values
829  // it contains to span a desired range of values. It differs from the
830  // more sophisticated histogram equalization in that it can only apply a
831  // linear scaling function to the image pixel values. As a result the
832  // 'enhancement' is less harsh.
833  void contrastStretch(const double black_point_,const double white_point_);
834  void contrastStretchChannel(const ChannelType channel_,
835  const double black_point_,const double white_point_);
836 
837  // Convolve image. Applies a user-specified convolution to the image.
838  // order_ represents the number of columns and rows in the filter kernel.
839  // kernel_ is an array of doubles representing the convolution kernel.
840  void convolve(const size_t order_,const double *kernel_);
841 
842  // Copies pixels from the source image as defined by the geometry the
843  // destination image at the specified offset.
844  void copyPixels(const Image &source_,const Geometry &geometry_,
845  const Offset &offset_);
846 
847  // Crop image (subregion of original image)
848  void crop(const Geometry &geometry_);
849 
850  // Cycle image colormap
851  void cycleColormap(const ::ssize_t amount_);
852 
853  // Converts cipher pixels to plain pixels.
854  void decipher(const std::string &passphrase_);
855 
856  // Tagged image format define. Similar to the defineValue() method
857  // except that passing the flag_ value 'true' creates a value-less
858  // define with that format and key. Passing the flag_ value 'false'
859  // removes any existing matching definition. The method returns 'true'
860  // if a matching key exists, and 'false' if no matching key exists.
861  void defineSet(const std::string &magick_,const std::string &key_,
862  bool flag_);
863  bool defineSet(const std::string &magick_,const std::string &key_) const;
864 
865  // Tagged image format define (set/access coder-specific option) The
866  // magick_ option specifies the coder the define applies to. The key_
867  // option provides the key specific to that coder. The value_ option
868  // provides the value to set (if any). See the defineSet() method if the
869  // key must be removed entirely.
870  void defineValue(const std::string &magick_,const std::string &key_,
871  const std::string &value_);
872  std::string defineValue(const std::string &magick_,
873  const std::string &key_) const;
874 
875  // Removes skew from the image. Skew is an artifact that occurs in scanned
876  // images because of the camera being misaligned, imperfections in the
877  // scanning or surface, or simply because the paper was not placed
878  // completely flat when scanned. The value of threshold_ ranges from 0
879  // to QuantumRange.
880  void deskew(const double threshold_);
881 
882  // Despeckle image (reduce speckle noise)
883  void despeckle(void);
884 
885  // Determines the color type of the image. This method can be used to
886  // automaticly make the type GrayScale.
887  ImageType determineType(void) const;
888 
889  // Display image on screen
890  void display(void);
891 
892  // Distort image. distorts an image using various distortion methods, by
893  // mapping color lookups of the source image to a new destination image
894  // usally of the same size as the source image, unless 'bestfit' is set to
895  // true.
896  void distort(const DistortImageMethod method_,
897  const size_t number_arguments_,const double *arguments_,
898  const bool bestfit_=false);
899 
900  // Draw on image using a single drawable
901  void draw(const Drawable &drawable_);
902 
903  // Draw on image using a drawable list
904  void draw(const std::list<Magick::Drawable> &drawable_);
905 
906  // Edge image (hilight edges in image)
907  void edge(const double radius_=0.0);
908 
909  // Emboss image (hilight edges with 3D effect)
910  // The radius_ parameter specifies the radius of the Gaussian, in
911  // pixels, not counting the center pixel. The sigma_ parameter
912  // specifies the standard deviation of the Laplacian, in pixels.
913  void emboss(const double radius_=0.0,const double sigma_=1.0);
914 
915  // Converts pixels to cipher-pixels.
916  void encipher(const std::string &passphrase_);
917 
918  // Enhance image (minimize noise)
919  void enhance(void);
920 
921  // Equalize image (histogram equalization)
922  void equalize(void);
923 
924  // Erase image to current "background color"
925  void erase(void);
926 
927  // Extend the image as defined by the geometry.
928  void extent(const Geometry &geometry_);
929  void extent(const Geometry &geometry_,const Color &backgroundColor);
930  void extent(const Geometry &geometry_,const Color &backgroundColor,
931  const GravityType gravity_ );
932  void extent(const Geometry &geometry_,const GravityType gravity_);
933 
934  // Flip image (reflect each scanline in the vertical direction)
935  void flip(void);
936 
937  // Flood-fill color across pixels that match the color of the
938  // target pixel and are neighbors of the target pixel.
939  // Uses current fuzz setting when determining color match.
940  void floodFillColor(const Geometry &point_,const Color &fillColor_);
941  void floodFillColor(const Geometry &point_,const Color &fillColor_,
942  const bool invert_);
943  void floodFillColor(const ::ssize_t x_,const ::ssize_t y_,
944  const Color &fillColor_);
945  void floodFillColor(const ::ssize_t x_,const ::ssize_t y_,
946  const Color &fillColor_,const bool invert_);
947 
948  // Flood-fill color across pixels starting at target-pixel and
949  // stopping at pixels matching specified border color.
950  // Uses current fuzz setting when determining color match.
951  void floodFillColor(const Geometry &point_,const Color &fillColor_,
952  const Color &borderColor_);
953  void floodFillColor(const Geometry &point_,const Color &fillColor_,
954  const Color &borderColor_,const bool invert_);
955  void floodFillColor(const ::ssize_t x_,const ::ssize_t y_,
956  const Color &fillColor_,const Color &borderColor_);
957  void floodFillColor(const ::ssize_t x_,const ::ssize_t y_,
958  const Color &fillColor_,const Color &borderColor_,const bool invert_);
959 
960  // Floodfill pixels matching color (within fuzz factor) of target
961  // pixel(x,y) with replacement opacity value using method.
962  void floodFillOpacity(const ::ssize_t x_,const ::ssize_t y_,
963  const unsigned int opacity_,const bool invert_=false);
964  void floodFillOpacity(const ::ssize_t x_,const ::ssize_t y_,
965  const unsigned int opacity_,const PaintMethod method_);
966  void floodFillOpacity(const ::ssize_t x_,const ::ssize_t y_,
967  const unsigned int opacity_,const Color &target_,
968  const bool invert_=false);
969 
970  // Flood-fill texture across pixels that match the color of the
971  // target pixel and are neighbors of the target pixel.
972  // Uses current fuzz setting when determining color match.
973  void floodFillTexture(const Geometry &point_,const Image &texture_);
974  void floodFillTexture(const Geometry &point_,const Image &texture_,
975  const bool invert_);
976  void floodFillTexture(const ::ssize_t x_,const ::ssize_t y_,
977  const Image &texture_);
978  void floodFillTexture(const ::ssize_t x_,const ::ssize_t y_,
979  const Image &texture_,const bool invert_);
980 
981  // Flood-fill texture across pixels starting at target-pixel and
982  // stopping at pixels matching specified border color.
983  // Uses current fuzz setting when determining color match.
984  void floodFillTexture(const Geometry &point_,const Image &texture_,
985  const Color &borderColor_);
986  void floodFillTexture(const Geometry &point_,const Image &texture_,
987  const Color &borderColor_,const bool invert_);
988  void floodFillTexture(const ::ssize_t x_,const ::ssize_t y_,
989  const Image &texture_,const Color &borderColor_);
990  void floodFillTexture(const ::ssize_t x_,const ::ssize_t y_,
991  const Image &texture_,const Color &borderColor_,const bool invert_);
992 
993  // Flop image (reflect each scanline in the horizontal direction)
994  void flop(void);
995 
996  // Obtain font metrics for text string given current font,
997  // pointsize, and density settings.
998  void fontTypeMetrics(const std::string &text_,TypeMetric *metrics);
999 
1000  // Obtain multi line font metrics for text string given current font,
1001  // pointsize, and density settings.
1002  void fontTypeMetricsMultiline(const std::string &text_,
1003  TypeMetric *metrics);
1004 
1005  // Frame image
1006  void frame(const Geometry &geometry_=frameGeometryDefault);
1007  void frame(const size_t width_,const size_t height_,
1008  const ::ssize_t innerBevel_=6, const ::ssize_t outerBevel_=6);
1009 
1010  // Applies a mathematical expression to the image.
1011  void fx(const std::string expression);
1012  void fx(const std::string expression,const Magick::ChannelType channel);
1013 
1014  // Gamma correct image
1015  void gamma(const double gamma_);
1016  void gamma(const double gammaRed_,const double gammaGreen_,
1017  const double gammaBlue_);
1018 
1019  // Gaussian blur image
1020  // The number of neighbor pixels to be included in the convolution
1021  // mask is specified by 'width_'. The standard deviation of the
1022  // gaussian bell curve is specified by 'sigma_'.
1023  void gaussianBlur(const double width_,const double sigma_);
1024  void gaussianBlurChannel(const ChannelType channel_,const double width_,
1025  const double sigma_);
1026 
1027  // Obtain immutable image pixel indexes (valid for PseudoClass images)
1028  const IndexPacket *getConstIndexes(void) const;
1029 
1030  // Transfers read-only pixels from the image to the pixel cache as
1031  // defined by the specified region
1032  const PixelPacket *getConstPixels(const ::ssize_t x_,const ::ssize_t y_,
1033  const size_t columns_,const size_t rows_) const;
1034 
1035  // Obtain mutable image pixel indexes (valid for PseudoClass images)
1036  IndexPacket *getIndexes(void);
1037 
1038  // Transfers pixels from the image to the pixel cache as defined
1039  // by the specified region. Modified pixels may be subsequently
1040  // transferred back to the image via syncPixels. This method is
1041  // valid for DirectClass images.
1042  PixelPacket *getPixels(const ::ssize_t x_,const ::ssize_t y_,
1043  const size_t columns_,const size_t rows_);
1044 
1045  // Converts the colors in the image to gray.
1046  void grayscale(const PixelIntensityMethod method_);
1047 
1048  // Apply a color lookup table (Hald CLUT) to the image.
1049  void haldClut(const Image &clutImage_);
1050 
1051  // Identifies lines in the image.
1052  void houghLine(const size_t width_,const size_t height_,
1053  const size_t threshold_=40);
1054 
1055  // Implode image (special effect)
1056  void implode(const double factor_);
1057 
1058  // Implements the inverse discrete Fourier transform (DFT) of the image
1059  // either as a magnitude / phase or real / imaginary image pair.
1060  void inverseFourierTransform(const Image &phase_);
1061  void inverseFourierTransform(const Image &phase_,const bool magnitude_);
1062 
1063  // An edge preserving noise reduction filter.
1064  void kuwahara(const double radius_=0.0,const double sigma_=1.0);
1065  void kuwaharaChannel(const ChannelType channel_,const double radius_=0.0,
1066  const double sigma_=1.0);
1067 
1068  // Level image. Adjust the levels of the image by scaling the
1069  // colors falling between specified white and black points to the
1070  // full available quantum range. The parameters provided represent
1071  // the black, mid (gamma), and white points. The black point
1072  // specifies the darkest color in the image. Colors darker than
1073  // the black point are set to zero. Mid point (gamma) specifies a
1074  // gamma correction to apply to the image. White point specifies
1075  // the lightest color in the image. Colors brighter than the
1076  // white point are set to the maximum quantum value. The black and
1077  // white point have the valid range 0 to QuantumRange while mid (gamma)
1078  // has a useful range of 0 to ten.
1079  void level(const double black_point,const double white_point,
1080  const double mid_point=1.0);
1081  void levelChannel(const ChannelType channel,const double black_point,
1082  const double white_point,const double mid_point=1.0);
1083 
1084  // Maps the given color to "black" and "white" values, linearly spreading
1085  // out the colors, and level values on a channel by channel bases, as
1086  // per level(). The given colors allows you to specify different level
1087  // ranges for each of the color channels separately.
1088  void levelColors(const Color &blackColor_,const Color &whiteColor_,
1089  const bool invert_=true);
1090  void levelColorsChannel(const ChannelType channel_,
1091  const Color &blackColor_,const Color &whiteColor_,
1092  const bool invert_=true);
1093 
1094  // Levelize applies the reversed level operation to just the specific
1095  // channels specified.It compresses the full range of color values, so
1096  // that they lie between the given black and white points. Gamma is
1097  // applied before the values are mapped.
1098  void levelize(const double blackPoint_,const double whitePoint_,
1099  const double gamma_=1.0);
1100  void levelizeChannel(const ChannelType channel_,const double blackPoint_,
1101  const double whitePoint_,const double gamma_=1.0);
1102 
1103  // Discards any pixels below the black point and above the white point and
1104  // levels the remaining pixels.
1105  void linearStretch(const double blackPoint_,const double whitePoint_);
1106 
1107  // Rescales image with seam carving.
1108  void liquidRescale(const Geometry &geometry_);
1109 
1110  // Local contrast enhancement
1111  void localContrast(const double radius_,const double strength_);
1112 
1113  // Magnify image by integral size
1114  void magnify(void);
1115 
1116  // Remap image colors with closest color from reference image
1117  void map(const Image &mapImage_,const bool dither_=false);
1118 
1119  // Floodfill designated area with replacement opacity value
1120  void matteFloodfill(const Color &target_,const unsigned int opacity_,
1121  const ::ssize_t x_,const ::ssize_t y_,const PaintMethod method_);
1122 
1123  // Filter image by replacing each pixel component with the median
1124  // color in a circular neighborhood
1125  void medianFilter(const double radius_=0.0);
1126 
1127  // Merge image layers (deprecated, don't use any more)
1128  void mergeLayers(const ImageLayerMethod layerType_);
1129 
1130  // Reduce image by integral size
1131  void minify(void);
1132 
1133  // Modulate percent hue, saturation, and brightness of an image
1134  void modulate(const double brightness_,const double saturation_,
1135  const double hue_);
1136 
1137  // Returns the normalized moments of one or more image channels.
1138  ImageMoments moments(void) const;
1139 
1140  // Applies a kernel to the image according to the given mophology method.
1141  void morphology(const MorphologyMethod method_,const std::string kernel_,
1142  const ssize_t iterations_=1);
1143  void morphology(const MorphologyMethod method_,
1144  const KernelInfoType kernel_,const std::string arguments_,
1145  const ssize_t iterations_=1);
1146  void morphologyChannel(const ChannelType channel_,
1147  const MorphologyMethod method_,const std::string kernel_,
1148  const ssize_t iterations_=1);
1149  void morphologyChannel(const ChannelType channel_,
1150  const MorphologyMethod method_,const KernelInfoType kernel_,
1151  const std::string arguments_,const ssize_t iterations_=1);
1152 
1153  // Motion blur image with specified blur factor
1154  // The radius_ parameter specifies the radius of the Gaussian, in
1155  // pixels, not counting the center pixel. The sigma_ parameter
1156  // specifies the standard deviation of the Laplacian, in pixels.
1157  // The angle_ parameter specifies the angle the object appears
1158  // to be comming from (zero degrees is from the right).
1159  void motionBlur(const double radius_,const double sigma_,
1160  const double angle_);
1161 
1162  // Negate colors in image. Set grayscale to only negate grayscale
1163  // values in image.
1164  void negate(const bool grayscale_=false);
1165  void negateChannel(const ChannelType channel_,const bool grayscale_=false);
1166 
1167  // Normalize image (increase contrast by normalizing the pixel
1168  // values to span the full range of color values)
1169  void normalize(void);
1170 
1171  // Oilpaint image (image looks like oil painting)
1172  void oilPaint(const double radius_=3.0);
1173 
1174  // Set or attenuate the opacity channel in the image. If the image
1175  // pixels are opaque then they are set to the specified opacity
1176  // value, otherwise they are blended with the supplied opacity
1177  // value. The value of opacity_ ranges from 0 (completely opaque)
1178  // to QuantumRange. The defines OpaqueOpacity and TransparentOpacity are
1179  // available to specify completely opaque or completely
1180  // transparent, respectively.
1181  void opacity(const unsigned int opacity_);
1182 
1183  // Change color of opaque pixel to specified pen color.
1184  void opaque(const Color &opaqueColor_,const Color &penColor_,
1185  const bool invert_=MagickFalse);
1186 
1187  // Perform a ordered dither based on a number of pre-defined dithering
1188  // threshold maps, but over multiple intensity levels.
1189  void orderedDither(std::string thresholdMap_);
1190  void orderedDitherChannel(const ChannelType channel_,
1191  std::string thresholdMap_);
1192 
1193  // Set each pixel whose value is less than epsilon to epsilon or
1194  // -epsilon (whichever is closer) otherwise the pixel value remains
1195  // unchanged.
1196  void perceptible(const double epsilon_);
1197  void perceptibleChannel(const ChannelType channel_,const double epsilon_);
1198 
1199  // Ping is similar to read except only enough of the image is read
1200  // to determine the image columns, rows, and filesize. Access the
1201  // columns(), rows(), and fileSize() attributes after invoking
1202  // ping. The image data is not valid after calling ping.
1203  void ping(const Blob &blob_);
1204 
1205  // Ping is similar to read except only enough of the image is read
1206  // to determine the image columns, rows, and filesize. Access the
1207  // columns(), rows(), and fileSize() attributes after invoking
1208  // ping. The image data is not valid after calling ping.
1209  void ping(const std::string &imageSpec_);
1210 
1211  // Get/set pixel color at location x & y.
1212  void pixelColor(const ::ssize_t x_,const ::ssize_t y_,const Color &color_);
1213  Color pixelColor(const ::ssize_t x_,const ::ssize_t y_ ) const;
1214 
1215  // Simulates a Polaroid picture.
1216  void polaroid(const std::string &caption_,const double angle_);
1217 
1218  // Reduces the image to a limited number of colors for a "poster" effect.
1219  void posterize(const size_t levels_,const bool dither_=false);
1220  void posterizeChannel(const ChannelType channel_, const size_t levels_,
1221  const bool dither_=false);
1222 
1223  // Execute a named process module using an argc/argv syntax similar to
1224  // that accepted by a C 'main' routine. An exception is thrown if the
1225  // requested process module doesn't exist, fails to load, or fails during
1226  // execution.
1227  void process(std::string name_,const ::ssize_t argc_,const char **argv_);
1228 
1229  // Add or remove a named profile to/from the image. Remove the
1230  // profile by passing an empty Blob (e.g. Blob()). Valid names are
1231  // "*", "8BIM", "ICM", "IPTC", or a user/format-defined profile name.
1232  void profile(const std::string name_,const Blob &colorProfile_);
1233 
1234  // Retrieve a named profile from the image. Valid names are:
1235  // "8BIM", "8BIMTEXT", "APP1", "APP1JPEG", "ICC", "ICM", & "IPTC"
1236  // or an existing user/format-defined profile name.
1237  Blob profile(const std::string name_) const;
1238 
1239  // Quantize image (reduce number of colors)
1240  void quantize(const bool measureError_=false);
1241 
1242  // Apply a value with an arithmetic, relational, or logical operator.
1243  void quantumOperator(const ChannelType channel_,
1244  const MagickEvaluateOperator operator_,double rvalue_);
1245 
1246  // Apply a value with an arithmetic, relational, or logical operator.
1247  void quantumOperator(const ChannelType channel_,
1248  const MagickFunction function_,const size_t number_parameters_,
1249  const double *parameters_);
1250 
1251  // Apply a value with an arithmetic, relational, or logical operator.
1252  void quantumOperator(const ::ssize_t x_,const ::ssize_t y_,
1253  const size_t columns_,const size_t rows_,const ChannelType channel_,
1254  const MagickEvaluateOperator operator_,const double rvalue_);
1255 
1256  // Raise image (lighten or darken the edges of an image to give a
1257  // 3-D raised or lowered effect)
1258  void raise(const Geometry &geometry_=raiseGeometryDefault,
1259  const bool raisedFlag_=false);
1260 
1261  // Random threshold image.
1262  //
1263  // Changes the value of individual pixels based on the intensity
1264  // of each pixel compared to a random threshold. The result is a
1265  // low-contrast, two color image. The thresholds_ argument is a
1266  // geometry containing LOWxHIGH thresholds. If the string
1267  // contains 2x2, 3x3, or 4x4, then an ordered dither of order 2,
1268  // 3, or 4 will be performed instead. If a channel_ argument is
1269  // specified then only the specified channel is altered. This is
1270  // a very fast alternative to 'quantize' based dithering.
1271  void randomThreshold(const Geometry &thresholds_);
1272  void randomThresholdChannel(const Geometry &thresholds_,
1273  const ChannelType channel_);
1274 
1275  // Read single image frame from in-memory BLOB
1276  void read(const Blob &blob_);
1277 
1278  // Read single image frame of specified size from in-memory BLOB
1279  void read(const Blob &blob_,const Geometry &size_);
1280 
1281  // Read single image frame of specified size and depth from
1282  // in-memory BLOB
1283  void read(const Blob &blob_,const Geometry &size_,const size_t depth_);
1284 
1285  // Read single image frame of specified size, depth, and format
1286  // from in-memory BLOB
1287  void read(const Blob &blob_,const Geometry &size_,const size_t depth_,
1288  const std::string &magick_);
1289 
1290  // Read single image frame of specified size, and format from
1291  // in-memory BLOB
1292  void read(const Blob &blob_,const Geometry &size_,
1293  const std::string &magick_);
1294 
1295  // Read single image frame of specified size into current object
1296  void read(const Geometry &size_,const std::string &imageSpec_);
1297 
1298  // Read single image frame from an array of raw pixels, with
1299  // specified storage type (ConstituteImage), e.g.
1300  // image.read( 640, 480, "RGB", 0, pixels );
1301  void read(const size_t width_,const size_t height_,const std::string &map_,
1302  const StorageType type_,const void *pixels_);
1303 
1304  // Read single image frame into current object
1305  void read(const std::string &imageSpec_);
1306 
1307  // Transfers one or more pixel components from a buffer or file
1308  // into the image pixel cache of an image.
1309  // Used to support image decoders.
1310  void readPixels(const QuantumType quantum_,const unsigned char *source_);
1311 
1312  // Reduce noise in image using a noise peak elimination filter
1313  void reduceNoise(void);
1314  void reduceNoise(const double order_);
1315 
1316  // Resets the image page canvas and position.
1317  void repage();
1318 
1319  // Resize image in terms of its pixel size.
1320  void resample(const Geometry &geometry_);
1321 
1322  // Resize image to specified size.
1323  void resize(const Geometry &geometry_);
1324 
1325  // Roll image (rolls image vertically and horizontally) by specified
1326  // number of columnms and rows)
1327  void roll(const Geometry &roll_);
1328  void roll(const size_t columns_,const size_t rows_);
1329 
1330  // Rotate image clockwise by specified number of degrees. Specify a
1331  // negative number for degrees to rotate counter-clockwise.
1332  void rotate(const double degrees_);
1333 
1334  // Rotational blur image.
1335  void rotationalBlur(const double angle_);
1336  void rotationalBlurChannel(const ChannelType channel_,
1337  const double angle_);
1338 
1339  // Resize image by using pixel sampling algorithm
1340  void sample(const Geometry &geometry_);
1341 
1342  // Resize image by using simple ratio algorithm
1343  void scale(const Geometry &geometry_);
1344 
1345  // Segment (coalesce similar image components) by analyzing the
1346  // histograms of the color components and identifying units that
1347  // are homogeneous with the fuzzy c-means technique. Also uses
1348  // QuantizeColorSpace and Verbose image attributes
1349  void segment(const double clusterThreshold_=1.0,
1350  const double smoothingThreshold_=1.5);
1351 
1352  // Selectively blur pixels within a contrast threshold. It is similar to
1353  // the unsharpen mask that sharpens everything with contrast above a
1354  // certain threshold.
1355  void selectiveBlur(const double radius_,const double sigma_,
1356  const double threshold_);
1357  void selectiveBlurChannel(const ChannelType channel_,const double radius_,
1358  const double sigma_,const double threshold_);
1359 
1360  // Separates a channel from the image and returns it as a grayscale image.
1361  Image separate(const ChannelType channel_) const;
1362 
1363  // Applies a special effect to the image, similar to the effect achieved in
1364  // a photo darkroom by sepia toning. Threshold ranges from 0 to
1365  // QuantumRange and is a measure of the extent of the sepia toning.
1366  // A threshold of 80% is a good starting point for a reasonable tone.
1367  void sepiaTone(const double threshold_);
1368 
1369  // Allocates a pixel cache region to store image pixels as defined
1370  // by the region rectangle. This area is subsequently transferred
1371  // from the pixel cache to the image via syncPixels.
1372  PixelPacket *setPixels(const ::ssize_t x_,const ::ssize_t y_,
1373  const size_t columns_,const size_t rows_);
1374 
1375  // Shade image using distant light source
1376  void shade(const double azimuth_=30,const double elevation_=30,
1377  const bool colorShading_=false);
1378 
1379  // Simulate an image shadow
1380  void shadow(const double percent_opacity_=80.0,const double sigma_=0.5,
1381  const ssize_t x_=5,const ssize_t y_=5);
1382 
1383  // Sharpen pixels in image
1384  // The radius_ parameter specifies the radius of the Gaussian, in
1385  // pixels, not counting the center pixel. The sigma_ parameter
1386  // specifies the standard deviation of the Laplacian, in pixels.
1387  void sharpen(const double radius_=0.0,const double sigma_=1.0);
1388  void sharpenChannel(const ChannelType channel_,const double radius_=0.0,
1389  const double sigma_=1.0);
1390 
1391  // Shave pixels from image edges.
1392  void shave(const Geometry &geometry_);
1393 
1394  // Shear image (create parallelogram by sliding image by X or Y axis)
1395  void shear(const double xShearAngle_,const double yShearAngle_);
1396 
1397  // adjust the image contrast with a non-linear sigmoidal contrast algorithm
1398  void sigmoidalContrast(const size_t sharpen_,const double contrast,
1399  const double midpoint=QuantumRange/2.0);
1400 
1401  // Image signature. Set force_ to true in order to re-calculate
1402  // the signature regardless of whether the image data has been
1403  // modified.
1404  std::string signature(const bool force_=false) const;
1405 
1406  // Simulates a pencil sketch. We convolve the image with a Gaussian
1407  // operator of the given radius and standard deviation (sigma). For
1408  // reasonable results, radius should be larger than sigma. Use a
1409  // radius of 0 and SketchImage() selects a suitable radius for you.
1410  void sketch(const double radius_=0.0,const double sigma_=1.0,
1411  const double angle_=0.0);
1412 
1413  // Solarize image (similar to effect seen when exposing a
1414  // photographic film to light during the development process)
1415  void solarize(const double factor_=50.0);
1416 
1417  // Sparse color image, given a set of coordinates, interpolates the colors
1418  // found at those coordinates, across the whole image, using various
1419  // methods.
1420  void sparseColor(const ChannelType channel,const SparseColorMethod method,
1421  const size_t number_arguments,const double *arguments);
1422 
1423  // Splice the background color into the image.
1424  void splice(const Geometry &geometry_);
1425  void splice(const Geometry &geometry_,const Color &backgroundColor_);
1426  void splice(const Geometry &geometry_,const Color &backgroundColor_,
1427  const GravityType gravity_);
1428 
1429  // Spread pixels randomly within image by specified ammount
1430  void spread(const size_t amount_=3);
1431 
1432  void statistics(ImageStatistics *statistics) const;
1433 
1434  // Add a digital watermark to the image (based on second image)
1435  void stegano(const Image &watermark_);
1436 
1437  // Create an image which appears in stereo when viewed with
1438  // red-blue glasses (Red image on left, blue on right)
1439  void stereo(const Image &rightImage_);
1440 
1441  // Strip strips an image of all profiles and comments.
1442  void strip(void);
1443 
1444  // Search for the specified image at EVERY possible location in this image.
1445  // This is slow! very very slow.. It returns a similarity image such that
1446  // an exact match location is completely white and if none of the pixels
1447  // match, black, otherwise some gray level in-between.
1448  Image subImageSearch(const Image &reference_,const MetricType metric_,
1449  Geometry *offset_,double *similarityMetric_,
1450  const double similarityThreshold=(-1.0));
1451 
1452  // Swirl image (image pixels are rotated by degrees)
1453  void swirl(const double degrees_);
1454 
1455  // Transfers the image cache pixels to the image.
1456  void syncPixels(void);
1457 
1458  // Channel a texture on image background
1459  void texture(const Image &texture_);
1460 
1461  // Threshold image
1462  void threshold(const double threshold_);
1463 
1464  // Resize image to thumbnail size
1465  void thumbnail(const Geometry &geometry_);
1466 
1467  // Applies a color vector to each pixel in the image. The length of the
1468  // vector is 0 for black and white and at its maximum for the midtones.
1469  // The vector weighting function is f(x)=(1-(4.0*((x-0.5)*(x-0.5))))
1470  void tint(const std::string opacity_);
1471 
1472  // Transform image based on image and crop geometries
1473  // Crop geometry is optional
1474  void transform(const Geometry &imageGeometry_);
1475  void transform(const Geometry &imageGeometry_,
1476  const Geometry &cropGeometry_);
1477 
1478  // Origin of coordinate system to use when annotating with text or drawing
1479  void transformOrigin(const double x_,const double y_);
1480 
1481  // Reset transformation parameters to default
1482  void transformReset(void);
1483 
1484  // Scale to use when annotating with text or drawing
1485  void transformScale(const double sx_,const double sy_);
1486 
1487  // Add matte image to image, setting pixels matching color to
1488  // transparent
1489  void transparent(const Color &color_);
1490 
1491  // Add matte image to image, for all the pixels that lies in between
1492  // the given two color
1493  void transparentChroma(const Color &colorLow_,const Color &colorHigh_);
1494 
1495  // Creates a horizontal mirror image by reflecting the pixels around the
1496  // central y-axis while rotating them by 90 degrees.
1497  void transpose(void);
1498 
1499  // Creates a vertical mirror image by reflecting the pixels around the
1500  // central x-axis while rotating them by 270 degrees.
1501  void transverse(void);
1502 
1503  // Trim edges that are the background color from the image
1504  void trim(void);
1505 
1506  // Returns the unique colors of an image.
1507  Image uniqueColors(void) const;
1508 
1509  // Replace image with a sharpened version of the original image
1510  // using the unsharp mask algorithm.
1511  // radius_
1512  // the radius of the Gaussian, in pixels, not counting the
1513  // center pixel.
1514  // sigma_
1515  // the standard deviation of the Gaussian, in pixels.
1516  // amount_
1517  // the percentage of the difference between the original and
1518  // the blur image that is added back into the original.
1519  // threshold_
1520  // the threshold in pixels needed to apply the diffence amount.
1521  void unsharpmask(const double radius_,const double sigma_,
1522  const double amount_,const double threshold_);
1523  void unsharpmaskChannel(const ChannelType channel_,const double radius_,
1524  const double sigma_,const double amount_,const double threshold_);
1525 
1526  // Softens the edges of the image in vignette style.
1527  void vignette(const double radius_=0.0,const double sigma_=1.0,
1528  const ssize_t x_=0,const ssize_t y_=0);
1529 
1530  // Map image pixels to a sine wave
1531  void wave(const double amplitude_=25.0,const double wavelength_=150.0);
1532 
1533  // Removes noise from the image using a wavelet transform.
1534  void waveletDenoise(const double threshold_,const double softness_);
1535 
1536  // Forces all pixels above the threshold into white while leaving all
1537  // pixels at or below the threshold unchanged.
1538  void whiteThreshold(const std::string &threshold_);
1539  void whiteThresholdChannel(const ChannelType channel_,
1540  const std::string &threshold_);
1541 
1542  // Write single image frame to in-memory BLOB, with optional
1543  // format and adjoin parameters.
1544  void write(Blob *blob_);
1545  void write(Blob *blob_,const std::string &magick_);
1546  void write(Blob *blob_,const std::string &magick_,const size_t depth_);
1547 
1548  // Write single image frame to an array of pixels with storage
1549  // type specified by user (DispatchImage), e.g.
1550  // image.write( 0, 0, 640, 1, "RGB", 0, pixels );
1551  void write(const ::ssize_t x_,const ::ssize_t y_,const size_t columns_,
1552  const size_t rows_,const std::string& map_,const StorageType type_,
1553  void *pixels_);
1554 
1555  // Write single image frame to a file
1556  void write(const std::string &imageSpec_);
1557 
1558  // Transfers one or more pixel components from the image pixel
1559  // cache to a buffer or file.
1560  // Used to support image encoders.
1561  void writePixels(const QuantumType quantum_,unsigned char *destination_);
1562 
1563  // Zoom image to specified size.
1564  void zoom(const Geometry &geometry_);
1565 
1567  //
1568  // No user-serviceable parts beyond this point
1569  //
1571 
1572  // Construct with MagickCore::Image and default options
1573  Image(MagickCore::Image *image_);
1574 
1575  // Retrieve Image*
1576  MagickCore::Image *&image(void);
1577  const MagickCore::Image *constImage(void) const;
1578 
1579  // Retrieve ImageInfo*
1580  MagickCore::ImageInfo *imageInfo(void);
1581  const MagickCore::ImageInfo *constImageInfo(void) const;
1582 
1583  // Retrieve Options*
1584  Options *options(void);
1585  const Options *constOptions(void) const;
1586 
1587  // Retrieve QuantizeInfo*
1588  MagickCore::QuantizeInfo *quantizeInfo(void);
1589  const MagickCore::QuantizeInfo *constQuantizeInfo(void) const;
1590 
1591  // Prepare to update image (copy if reference > 1)
1592  void modifyImage(void);
1593 
1594  // Replace current image (reference counted)
1595  MagickCore::Image *replaceImage(MagickCore::Image *replacement_);
1596 
1597  // Test for ImageMagick error and throw exception if error
1598  void throwImageException(void) const;
1599 
1600  private:
1601 
1602  void read(MagickCore::Image *image,
1603  MagickCore::ExceptionInfo *exceptionInfo);
1604 
1605  void floodFill(const ssize_t x_,const ssize_t y_,
1606  const Magick::Image *fillPattern_,const Color &fill_,
1607  const MagickCore::PixelPacket *target,const bool invert_);
1608 
1609  ImageRef *_imgRef;
1610  };
1611 
1612 } // end of namespace Magick
1613 
1614 //
1615 // Inlines
1616 //
1617 
1618 inline Magick::ClassType Magick::Image::classType(void) const
1619 {
1620  return static_cast<Magick::ClassType>(constImage()->storage_class);
1621 }
1622 
1623 inline size_t Magick::Image::columns(void) const
1624 {
1625  return constImage()->columns;
1626 }
1627 
1628 inline void Magick::Image::lineWidth(const double lineWidth_)
1629 {
1630  strokeWidth(lineWidth_);
1631 }
1632 inline double Magick::Image::lineWidth(void) const
1633 {
1634  return strokeWidth();
1635 }
1636 
1638 {
1639  reduceNoise(3.0);
1640 }
1641 
1642 inline size_t Magick::Image::rows(void) const
1643 {
1644  return constImage()->rows;
1645 }
1646 
1647 #endif // Magick_Image_header
ImageChannelStatistics blue
Definition: Image.h:82
MagickPPExport const char * borderGeometryDefault
Definition: Image.cpp:33
ImageChannelStatistics green
Definition: Image.h:81
MagickPPExport const char * raiseGeometryDefault
Definition: Image.cpp:35
ClassType classType(void) const
Definition: Image.h:1618
void reduceNoise(void)
Definition: Image.h:1637
size_t columns(void) const
Definition: Image.h:1623
ImageChannelStatistics red
Definition: Image.h:80
#define MagickPPExport
Definition: Include.h:261
const MagickCore::Image * constImage(void) const
Definition: Image.cpp:5043
MagickPPExport const char * frameGeometryDefault
Definition: Image.cpp:34
double lineWidth(void) const
Definition: Image.h:1632
class MagickPPExport Image
Definition: Drawable.h:642
size_t rows(void) const
Definition: Image.h:1642
ImageChannelStatistics opacity
Definition: Image.h:83