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