1 // This may look like C code, but it is really -*- C++ -*-
3 // Copyright Bob Friesenhahn, 1999, 2000, 2001, 2002, 2003
5 // Definition of Image, the representation of a single image in Magick++
8 #if !defined(Magick_Image_header)
9 #define Magick_Image_header
11 #include "Magick++/Include.h"
14 #include "Magick++/Blob.h"
15 #include "Magick++/Color.h"
16 #include "Magick++/Drawable.h"
17 #include "Magick++/Exception.h"
18 #include "Magick++/Geometry.h"
19 #include "Magick++/TypeMetric.h"
23 // Forward declarations
27 extern MagickPPExport const char *borderGeometryDefault;
28 extern MagickPPExport const char *frameGeometryDefault;
29 extern MagickPPExport const char *raiseGeometryDefault;
31 // Compare two Image objects regardless of LHS/RHS
32 // Image sizes and signatures are used as basis of comparison
33 MagickPPExport int operator ==
34 (const Magick::Image &left_,const Magick::Image &right_);
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_);
46 // C library initialization routine
47 MagickPPExport void InitializeMagick(const char *path_);
48 MagickPPExport void TerminateMagick();
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.
55 class MagickPPExport Image
59 // Obtain image statistics. Statistics are normalized to the range
60 // of 0.0 to 1.0 and are output to the specified ImageStatistics
62 typedef struct _ImageChannelStatistics
64 /* Minimum value observed */
66 /* Maximum value observed */
68 /* Average (mean) value observed */
70 /* Standard deviation, sqrt(variance) */
71 double standard_deviation;
78 } ImageChannelStatistics;
80 typedef struct _ImageStatistics
82 ImageChannelStatistics red;
83 ImageChannelStatistics green;
84 ImageChannelStatistics blue;
85 ImageChannelStatistics alpha;
88 // Default constructor
91 // Construct Image from in-memory BLOB
92 Image(const Blob &blob_);
94 // Construct Image of specified size from in-memory BLOB
95 Image(const Blob &blob_,const Geometry &size_);
97 // Construct Image of specified size and depth from in-memory BLOB
98 Image(const Blob &blob_,const Geometry &size,const size_t depth);
100 // Construct Image of specified size, depth, and format from
102 Image(const Blob &blob_,const Geometry &size,const size_t depth_,
103 const std::string &magick_);
105 // Construct Image of specified size, and format from in-memory BLOB
106 Image(const Blob &blob_,const Geometry &size,const std::string &magick_);
108 // Construct a blank image canvas of specified size and color
109 Image(const Geometry &size_,const Color &color_);
112 Image(const Image &image_);
114 // Construct an image based on an array of raw pixels, of
115 // specified type and mapping, in memory
116 Image(const size_t width_,const size_t height_,const std::string &map_,
117 const StorageType type_,const void *pixels_);
119 // Construct from image file or image specification
120 Image(const std::string &imageSpec_);
125 // Assignment operator
126 Image& operator=(const Image &image_);
128 // Join images into a single multi-image file
129 void adjoin(const bool flag_);
130 bool adjoin(void) const;
132 // Image supports transparency (alpha channel)
133 void alpha(const bool alphaFlag_);
134 bool alpha(void) const;
137 void alphaColor(const Color &alphaColor_);
138 Color alphaColor(void) const;
140 // Anti-alias Postscript and TrueType fonts (default true)
141 void antiAlias(const bool flag_);
142 bool antiAlias(void);
144 // Time in 1/100ths of a second which must expire before
145 // displaying the next image in an animated sequence.
146 void animationDelay(const size_t delay_);
147 size_t animationDelay(void) const;
149 // Number of iterations to loop an animation (e.g. Netscape loop
151 void animationIterations(const size_t iterations_);
152 size_t animationIterations(void) const;
154 // Image background color
155 void backgroundColor(const Color &color_);
156 Color backgroundColor(void) const;
158 // Name of texture image to tile onto the image background
159 void backgroundTexture(const std::string &backgroundTexture_);
160 std::string backgroundTexture(void) const;
162 // Base image width (before transformations)
163 size_t baseColumns(void) const;
165 // Base image filename (before transformations)
166 std::string baseFilename(void) const;
168 // Base image height (before transformations)
169 size_t baseRows(void) const;
171 // Image border color
172 void borderColor(const Color &color_);
173 Color borderColor(void) const;
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;
180 // Text bounding-box base color (default none)
181 void boxColor(const Color &boxColor_);
182 Color boxColor(void) const;
184 // Pixel cache threshold in bytes. Once this memory threshold
185 // is exceeded, all subsequent pixels cache operations are to/from
186 // disk. This setting is shared by all Image objects.
187 static void cacheThreshold(const MagickSizeType threshold_);
189 // Set or obtain modulus channel depth
190 void channelDepth(const size_t depth_);
191 size_t channelDepth();
193 // Returns the number of channels in this image.
194 size_t channels() const;
196 // Image class (DirectClass or PseudoClass)
197 // NOTE: setting a DirectClass image to PseudoClass will result in
198 // the loss of color information if the number of colors in the
199 // image is greater than the maximum palette size (either 256 or
200 // 65536 entries depending on the value of MAGICKCORE_QUANTUM_DEPTH when
201 // ImageMagick was built).
202 void classType(const ClassType class_);
203 ClassType classType(void) const;
205 // Associate a clip mask with the image. The clip mask must be the
206 // same dimensions as the image. Pass an invalid image to unset an
207 // existing clip mask.
208 void clipMask(const Image &clipMask_);
209 Image clipMask(void) const;
211 // Colors within this distance are considered equal
212 void colorFuzz(const double fuzz_);
213 double colorFuzz(void) const;
215 // Colormap size (number of colormap entries)
216 void colorMapSize(const size_t entries_);
217 size_t colorMapSize(void) const;
220 void colorSpace(const ColorspaceType colorSpace_);
221 ColorspaceType colorSpace(void) const;
223 void colorSpaceType(const ColorspaceType colorSpace_);
224 ColorspaceType colorSpaceType(void) const;
227 size_t columns(void) const;
229 // Comment image (add comment string to image)
230 void comment(const std::string &comment_);
231 std::string comment(void) const;
233 // Composition operator to be used when composition is implicitly
234 // used (such as for image flattening).
235 void compose(const CompositeOperator compose_);
236 CompositeOperator compose(void) const;
239 void compressType(const CompressionType compressType_);
240 CompressionType compressType(void) const;
242 // Enable printing of debug messages from ImageMagick
243 void debug(const bool flag_);
244 bool debug(void) const;
246 // Vertical and horizontal resolution in pixels of the image
247 void density(const Geometry &geomery_);
248 Geometry density(void) const;
250 // Image depth (bits allocated to red/green/blue components)
251 void depth(const size_t depth_);
252 size_t depth(void) const;
254 // Tile names from within an image montage
255 std::string directory(void) const;
257 // Endianness (little like Intel or big like SPARC) for image
258 // formats which support endian-specific options.
259 void endian(const EndianType endian_);
260 EndianType endian(void) const;
262 // Exif profile (BLOB)
263 void exifProfile(const Blob &exifProfile_);
264 Blob exifProfile(void) const;
267 void fileName(const std::string &fileName_);
268 std::string fileName(void) const;
270 // Number of bytes of the image on disk
271 MagickSizeType fileSize(void) const;
273 // Color to use when filling drawn objects
274 void fillColor(const Color &fillColor_);
275 Color fillColor(void) const;
277 // Rule to use when filling drawn objects
278 void fillRule(const FillRule &fillRule_);
279 FillRule fillRule(void) const;
281 // Pattern to use while filling drawn objects.
282 void fillPattern(const Image &fillPattern_);
283 Image fillPattern(void) const;
285 // Filter to use when resizing image
286 void filterType(const FilterTypes filterType_);
287 FilterTypes filterType(void) const;
289 // Text rendering font
290 void font(const std::string &font_);
291 std::string font(void) const;
294 void fontPointsize(const double pointSize_);
295 double fontPointsize(void) const;
297 // Long image format description
298 std::string format(void) const;
300 // Gamma level of the image
301 double gamma(void) const;
303 // Preferred size of the image when encoding
304 Geometry geometry(void) const;
306 // GIF disposal method
307 void gifDisposeMethod(const DisposeType disposeMethod_);
308 DisposeType gifDisposeMethod(void) const;
310 // ICC color profile (BLOB)
311 void iccColorProfile(const Blob &colorProfile_);
312 Blob iccColorProfile(void) const;
314 // Type of interlacing to use
315 void interlaceType(const InterlaceType interlace_);
316 InterlaceType interlaceType(void) const;
318 // Pixel color interpolation method to use
319 void interpolate(const PixelInterpolateMethod interpolate_);
320 PixelInterpolateMethod interpolate(void) const;
322 // IPTC profile (BLOB)
323 void iptcProfile(const Blob &iptcProfile_);
324 Blob iptcProfile(void) const;
326 // Does object contain valid image?
327 void isValid(const bool isValid_);
328 bool isValid(void) const;
331 void label(const std::string &label_);
332 std::string label(void) const;
334 // File type magick identifier (.e.g "GIF")
335 void magick(const std::string &magick_);
336 std::string magick(void) const;
338 // The mean error per pixel computed when an image is color reduced
339 double meanErrorPerPixel(void) const;
341 // Image modulus depth (minimum number of bits required to support
342 // red/green/blue components without loss of accuracy)
343 void modulusDepth(const size_t modulusDepth_);
344 size_t modulusDepth(void) const;
346 // Transform image to black and white
347 void monochrome(const bool monochromeFlag_);
348 bool monochrome(void) const;
350 // Tile size and offset within an image montage
351 Geometry montageGeometry(void) const;
353 // The normalized max error per pixel computed when an image is
355 double normalizedMaxError(void) const;
357 // The normalized mean error per pixel computed when an image is
359 double normalizedMeanError(void) const;
362 void orientation(const OrientationType orientation_);
363 OrientationType orientation(void) const;
365 // Preferred size and location of an image canvas.
366 void page(const Geometry &pageSize_);
367 Geometry page(void) const;
369 // JPEG/MIFF/PNG compression level (default 75).
370 void quality(const size_t quality_);
371 size_t quality(void) const;
373 // Maximum number of colors to quantize to
374 void quantizeColors(const size_t colors_);
375 size_t quantizeColors(void) const;
377 // Colorspace to quantize in.
378 void quantizeColorSpace(const ColorspaceType colorSpace_);
379 ColorspaceType quantizeColorSpace(void) const;
381 // Dither image during quantization (default true).
382 void quantizeDither(const bool ditherFlag_);
383 bool quantizeDither(void) const;
385 // Quantization tree-depth
386 void quantizeTreeDepth(const size_t treeDepth_);
387 size_t quantizeTreeDepth(void) const;
389 // The type of rendering intent
390 void renderingIntent(const RenderingIntent renderingIntent_);
391 RenderingIntent renderingIntent(void) const;
393 // Units of image resolution
394 void resolutionUnits(const ResolutionType resolutionUnits_);
395 ResolutionType resolutionUnits(void) const;
397 // The number of pixel rows in the image
398 size_t rows(void) const;
400 // Image scene number
401 void scene(const size_t scene_);
402 size_t scene(void) const;
404 // Width and height of a raw image
405 void size(const Geometry &geometry_);
406 Geometry size(void) const;
408 // enabled/disable stroke anti-aliasing
409 void strokeAntiAlias(const bool flag_);
410 bool strokeAntiAlias(void) const;
412 // Color to use when drawing object outlines
413 void strokeColor(const Color &strokeColor_);
414 Color strokeColor(void) const;
416 // Specify the pattern of dashes and gaps used to stroke
417 // paths. The strokeDashArray represents a zero-terminated array
418 // of numbers that specify the lengths of alternating dashes and
419 // gaps in pixels. If an odd number of values is provided, then
420 // the list of values is repeated to yield an even number of
421 // values. A typical strokeDashArray_ array might contain the
422 // members 5 3 2 0, where the zero value indicates the end of the
424 void strokeDashArray(const double *strokeDashArray_);
425 const double *strokeDashArray(void) const;
427 // While drawing using a dash pattern, specify distance into the
428 // dash pattern to start the dash (default 0).
429 void strokeDashOffset(const double strokeDashOffset_);
430 double strokeDashOffset(void) const;
432 // Specify the shape to be used at the end of open subpaths when
433 // they are stroked. Values of LineCap are UndefinedCap, ButtCap,
434 // RoundCap, and SquareCap.
435 void strokeLineCap(const LineCap lineCap_);
436 LineCap strokeLineCap(void) const;
438 // Specify the shape to be used at the corners of paths (or other
439 // vector shapes) when they are stroked. Values of LineJoin are
440 // UndefinedJoin, MiterJoin, RoundJoin, and BevelJoin.
441 void strokeLineJoin(const LineJoin lineJoin_);
442 LineJoin strokeLineJoin(void) const;
444 // Specify miter limit. When two line segments meet at a sharp
445 // angle and miter joins have been specified for 'lineJoin', it is
446 // possible for the miter to extend far beyond the thickness of
447 // the line stroking the path. The miterLimit' imposes a limit on
448 // the ratio of the miter length to the 'lineWidth'. The default
449 // value of this parameter is 4.
450 void strokeMiterLimit(const size_t miterLimit_);
451 size_t strokeMiterLimit(void) const;
453 // Pattern image to use while stroking object outlines.
454 void strokePattern(const Image &strokePattern_);
455 Image strokePattern(void) const;
457 // Stroke width for drawing vector objects (default one)
458 void strokeWidth(const double strokeWidth_);
459 double strokeWidth(void) const;
461 // Subimage of an image sequence
462 void subImage(const size_t subImage_);
463 size_t subImage(void) const;
465 // Number of images relative to the base image
466 void subRange(const size_t subRange_);
467 size_t subRange(void) const;
469 // Annotation text encoding (e.g. "UTF-16")
470 void textEncoding(const std::string &encoding_);
471 std::string textEncoding(void) const;
473 // Number of colors in the image
474 size_t totalColors(void) const;
476 // Rotation to use when annotating with text or drawing
477 void transformRotation(const double angle_);
479 // Skew to use in X axis when annotating with text or drawing
480 void transformSkewX(const double skewx_);
482 // Skew to use in Y axis when annotating with text or drawing
483 void transformSkewY(const double skewy_);
485 // Image representation type (also see type operation)
487 // Bilevel Grayscale GrayscaleMatte
488 // Palette PaletteMatte TrueColor
489 // TrueColorMatte ColorSeparation ColorSeparationMatte
490 void type(const ImageType type_);
491 ImageType type(void) const;
493 // Print detailed information about the image
494 void verbose(const bool verboseFlag_);
495 bool verbose(void) const;
497 // FlashPix viewing parameters
498 void view(const std::string &view_);
499 std::string view(void) const;
501 // Virtual pixel method
502 void virtualPixelMethod(const VirtualPixelMethod virtualPixelMethod_);
503 VirtualPixelMethod virtualPixelMethod(void) const;
505 // X11 display to display to, obtain fonts from, or to capture
507 void x11Display(const std::string &display_);
508 std::string x11Display(void) const;
510 // x resolution of the image
511 double xResolution(void) const;
513 // y resolution of the image
514 double yResolution(void) const;
516 // Adaptive-blur image with specified blur factor
517 // The radius_ parameter specifies the radius of the Gaussian, in
518 // pixels, not counting the center pixel. The sigma_ parameter
519 // specifies the standard deviation of the Laplacian, in pixels.
520 void adaptiveBlur(const double radius_=0.0,const double sigma_=1.0);
522 // This is shortcut function for a fast interpolative resize using mesh
523 // interpolation. It works well for small resizes of less than +/- 50%
524 // of the original image size. For larger resizing on images a full
525 // filtered and slower resize function should be used instead.
526 void adaptiveResize(const Geometry &geometry_);
528 // Adaptively sharpens the image by sharpening more intensely near image
529 // edges and less intensely far from edges. We sharpen the image with a
530 // Gaussian operator of the given radius and standard deviation (sigma).
531 // For reasonable results, radius should be larger than sigma.
532 void adaptiveSharpen(const double radius_=0.0,const double sigma_=1.0);
533 void adaptiveSharpenChannel(const ChannelType channel_,
534 const double radius_=0.0,const double sigma_=1.0);
536 // Local adaptive threshold image
537 // http://www.dai.ed.ac.uk/HIPR2/adpthrsh.htm
538 // Width x height define the size of the pixel neighborhood
539 // offset = constant to subtract from pixel neighborhood mean
540 void adaptiveThreshold(const size_t width,const size_t height,
541 const ::ssize_t offset=0);
543 // Add noise to image with specified noise type
544 void addNoise(const NoiseType noiseType_);
545 void addNoiseChannel(const ChannelType channel_,
546 const NoiseType noiseType_);
548 // Transform image by specified affine (or free transform) matrix.
549 void affineTransform(const DrawableAffine &affine);
551 // Set or attenuate the alpha channel in the image. If the image
552 // pixels are opaque then they are set to the specified alpha
553 // value, otherwise they are blended with the supplied alpha
554 // value. The value of alpha_ ranges from 0 (completely opaque)
555 // to QuantumRange. The defines OpaqueAlpha and TransparentAlpha are
556 // available to specify completely opaque or completely
557 // transparent, respectively.
558 void alpha(const unsigned int alpha_);
560 // AlphaChannel() activates, deactivates, resets, or sets the alpha
562 void alphaChannel(AlphaChannelOption alphaOption_);
564 // Floodfill designated area with replacement alpha value
565 void alphaFloodfill(const Color &target_,const unsigned int alpha_,
566 const ::ssize_t x_, const ::ssize_t y_,const PaintMethod method_);
569 // Annotate image (draw text on image)
571 // Gravity effects text placement in bounding area according to rules:
572 // NorthWestGravity text bottom-left corner placed at top-left
573 // NorthGravity text bottom-center placed at top-center
574 // NorthEastGravity text bottom-right corner placed at top-right
575 // WestGravity text left-center placed at left-center
576 // CenterGravity text center placed at center
577 // EastGravity text right-center placed at right-center
578 // SouthWestGravity text top-left placed at bottom-left
579 // SouthGravity text top-center placed at bottom-center
580 // SouthEastGravity text top-right placed at bottom-right
582 // Annotate using specified text, and placement location
583 void annotate(const std::string &text_,const Geometry &location_);
585 // Annotate using specified text, bounding area, and placement
587 void annotate(const std::string &text_,const Geometry &boundingArea_,
588 const GravityType gravity_);
590 // Annotate with text using specified text, bounding area,
591 // placement gravity, and rotation.
592 void annotate(const std::string &text_,const Geometry &boundingArea_,
593 const GravityType gravity_,const double degrees_);
595 // Annotate with text (bounding area is entire image) and placement
597 void annotate(const std::string &text_,const GravityType gravity_);
599 // Inserts the artifact with the specified name and value into
600 // the artifact tree of the image.
601 void artifact(const std::string &name_,const std::string &value_);
603 // Returns the value of the artifact with the specified name.
604 std::string artifact(const std::string &name_);
606 // Access/Update a named image attribute
607 void attribute(const std::string name_,const std::string value_);
608 std::string attribute(const std::string name_);
610 // Extracts the 'mean' from the image and adjust the image to try
611 // make set its gamma appropriatally.
612 void autoGamma(void);
613 void autoGammaChannel(const ChannelType channel_);
615 // Adjusts the levels of a particular image channel by scaling the
616 // minimum and maximum values to the full quantum range.
617 void autoLevel(void);
618 void autoLevelChannel(const ChannelType channel_);
620 // Adjusts an image so that its orientation is suitable for viewing.
621 void autoOrient(void);
623 // Forces all pixels below the threshold into black while leaving all
624 // pixels at or above the threshold unchanged.
625 void blackThreshold(const std::string &threshold_);
626 void blackThresholdChannel(const ChannelType channel_,
627 const std::string &threshold_);
629 // Simulate a scene at nighttime in the moonlight.
630 void blueShift(const double factor_=1.5);
632 // Blur image with specified blur factor
633 // The radius_ parameter specifies the radius of the Gaussian, in
634 // pixels, not counting the center pixel. The sigma_ parameter
635 // specifies the standard deviation of the Laplacian, in pixels.
636 void blur(const double radius_=0.0,const double sigma_=1.0);
637 void blurChannel(const ChannelType channel_,const double radius_=0.0,
638 const double sigma_=1.0);
640 // Border image (add border to image)
641 void border(const Geometry &geometry_=borderGeometryDefault);
643 // Changes the brightness and/or contrast of an image. It converts the
644 // brightness and contrast parameters into slope and intercept and calls
645 // a polynomical function to apply to the image.
646 void brightnessContrast(const double brightness_=0.0,
647 const double contrast_=0.0);
648 void brightnessContrastChannel(const ChannelType channel_,
649 const double brightness_=0.0,const double contrast_=0.0);
651 // Extract channel from image
652 void channel(const ChannelType channel_);
654 // Charcoal effect image (looks like charcoal sketch)
655 // The radius_ parameter specifies the radius of the Gaussian, in
656 // pixels, not counting the center pixel. The sigma_ parameter
657 // specifies the standard deviation of the Laplacian, in pixels.
658 void charcoal(const double radius_=0.0,const double sigma_=1.0);
660 // Chop image (remove vertical or horizontal subregion of image)
661 // FIXME: describe how geometry argument is used to select either
662 // horizontal or vertical subregion of image.
663 void chop(const Geometry &geometry_);
665 // Chromaticity blue primary point (e.g. x=0.15, y=0.06)
666 void chromaBluePrimary(const double x_,const double y_);
667 void chromaBluePrimary(double *x_,double *y_) const;
669 // Chromaticity green primary point (e.g. x=0.3, y=0.6)
670 void chromaGreenPrimary(const double x_,const double y_);
671 void chromaGreenPrimary(double *x_,double *y_) const;
673 // Chromaticity red primary point (e.g. x=0.64, y=0.33)
674 void chromaRedPrimary(const double x_,const double y_);
675 void chromaRedPrimary(double *x_,double *y_) const;
677 // Chromaticity white point (e.g. x=0.3127, y=0.329)
678 void chromaWhitePoint(const double x_,const double y_);
679 void chromaWhitePoint(double *x_,double *y_) const;
681 // Accepts a lightweight Color Correction Collection
682 // (CCC) file which solely contains one or more color corrections and
683 // applies the correction to the image.
684 void cdl(const std::string &cdl_);
686 // Set each pixel whose value is below zero to zero and any the
687 // pixel whose value is above the quantum range to the quantum range (e.g.
688 // 65535) otherwise the pixel value remains unchanged.
690 void clampChannel(const ChannelType channel_);
692 // Sets the image clip mask based on any clipping path information
695 void clipPath(const std::string pathname_,const bool inside_);
697 // Apply a color lookup table (CLUT) to the image.
698 void clut(const Image &clutImage_,const PixelInterpolateMethod method);
699 void clutChannel(const ChannelType channel_,const Image &clutImage_,
700 const PixelInterpolateMethod method);
702 // Colorize image with pen color, using specified percent alpha.
703 void colorize(const unsigned int alpha_,const Color &penColor_);
705 // Colorize image with pen color, using specified percent alpha
706 // for red, green, and blue quantums
707 void colorize(const unsigned int alphaRed_,const unsigned int alphaGreen_,
708 const unsigned int alphaBlue_,const Color &penColor_);
710 // Color at colormap position index_
711 void colorMap(const size_t index_,const Color &color_);
712 Color colorMap(const size_t index_) const;
714 // Apply a color matrix to the image channels. The user supplied
715 // matrix may be of order 1 to 5 (1x1 through 5x5).
716 void colorMatrix(const size_t order_,const double *color_matrix_);
718 // Compare current image with another image
719 // Sets meanErrorPerPixel, normalizedMaxError, and normalizedMeanError
720 // in the current image. False is returned if the images are identical.
721 bool compare(const Image &reference_);
723 // Compare current image with another image
724 // Returns the distortion based on the specified metric.
725 double compare(const Image &reference_,const MetricType metric_);
726 double compareChannel(const ChannelType channel_,
727 const Image &reference_,
728 const MetricType metric_ );
730 // Compare current image with another image
731 // Sets the distortion and returns the difference image.
732 Image compare(const Image &reference_,const MetricType metric_,
734 Image compareChannel(const ChannelType channel_,const Image &reference_,
735 const MetricType metric_,double *distortion);
737 // Compose an image onto another at specified offset and using
738 // specified algorithm
739 void composite(const Image &compositeImage_,const Geometry &offset_,
740 const CompositeOperator compose_=InCompositeOp);
741 void composite(const Image &compositeImage_,const GravityType gravity_,
742 const CompositeOperator compose_=InCompositeOp);
743 void composite(const Image &compositeImage_,const ::ssize_t xOffset_,
744 const ::ssize_t yOffset_,const CompositeOperator compose_=InCompositeOp);
746 // Contrast image (enhance intensity differences in image)
747 void contrast(const size_t sharpen_);
749 // A simple image enhancement technique that attempts to improve the
750 // contrast in an image by 'stretching' the range of intensity values
751 // it contains to span a desired range of values. It differs from the
752 // more sophisticated histogram equalization in that it can only apply a
753 // linear scaling function to the image pixel values. As a result the
754 // 'enhancement' is less harsh.
755 void contrastStretch(const double blackPoint_,const double whitePoint_);
756 void contrastStretchChannel(const ChannelType channel_,
757 const double blackPoint_,const double whitePoint_);
759 // Convolve image. Applies a user-specified convolution to the image.
760 // order_ represents the number of columns and rows in the filter kernel.
761 // kernel_ is an array of doubles representing the convolution kernel.
762 void convolve(const size_t order_,const double *kernel_);
764 // Crop image (subregion of original image)
765 void crop(const Geometry &geometry_);
767 // Cycle image colormap
768 void cycleColormap(const ::ssize_t amount_);
770 // Converts cipher pixels to plain pixels.
771 void decipher(const std::string &passphrase_);
773 // Tagged image format define. Similar to the defineValue() method
774 // except that passing the flag_ value 'true' creates a value-less
775 // define with that format and key. Passing the flag_ value 'false'
776 // removes any existing matching definition. The method returns 'true'
777 // if a matching key exists, and 'false' if no matching key exists.
778 void defineSet(const std::string &magick_,const std::string &key_,
780 bool defineSet(const std::string &magick_,const std::string &key_) const;
782 // Tagged image format define (set/access coder-specific option) The
783 // magick_ option specifies the coder the define applies to. The key_
784 // option provides the key specific to that coder. The value_ option
785 // provides the value to set (if any). See the defineSet() method if the
786 // key must be removed entirely.
787 void defineValue(const std::string &magick_,const std::string &key_,
788 const std::string &value_);
789 std::string defineValue(const std::string &magick_,
790 const std::string &key_) const;
792 // Removes skew from the image. Skew is an artifact that occurs in scanned
793 // images because of the camera being misaligned, imperfections in the
794 // scanning or surface, or simply because the paper was not placed
795 // completely flat when scanned. The value of threshold_ ranges from 0
797 void deskew(const double threshold_);
799 // Despeckle image (reduce speckle noise)
800 void despeckle(void);
802 // Display image on screen
805 // Distort image. distorts an image using various distortion methods, by
806 // mapping color lookups of the source image to a new destination image
807 // usally of the same size as the source image, unless 'bestfit' is set to
809 void distort(const DistortImageMethod method_,
810 const size_t numberArguments_,const double *arguments_,
811 const bool bestfit_=false);
813 // Draw on image using a single drawable
814 void draw(const Drawable &drawable_);
816 // Draw on image using a drawable list
817 void draw(const std::list<Magick::Drawable> &drawable_);
819 // Edge image (hilight edges in image)
820 void edge(const double radius_=0.0);
822 // Emboss image (hilight edges with 3D effect)
823 // The radius_ parameter specifies the radius of the Gaussian, in
824 // pixels, not counting the center pixel. The sigma_ parameter
825 // specifies the standard deviation of the Laplacian, in pixels.
826 void emboss(const double radius_=0.0,const double sigma_=1.0);
828 // Converts pixels to cipher-pixels.
829 void encipher(const std::string &passphrase_);
831 // Enhance image (minimize noise)
834 // Equalize image (histogram equalization)
837 // Erase image to current "background color"
840 // Extend the image as defined by the geometry.
841 void extent(const Geometry &geometry_);
842 void extent(const Geometry &geometry_,const Color &backgroundColor);
843 void extent(const Geometry &geometry_,const Color &backgroundColor,
844 const GravityType gravity_);
845 void extent(const Geometry &geometry_,const GravityType gravity_);
847 // Flip image (reflect each scanline in the vertical direction)
850 // Floodfill pixels matching color (within fuzz factor) of target
851 // pixel(x,y) with replacement alpha value using method.
852 void floodFillAlpha(const ::ssize_t x_,const ::ssize_t y_,
853 const unsigned int alpha_,const PaintMethod method_);
855 // Flood-fill color across pixels that match the color of the
856 // target pixel and are neighbors of the target pixel.
857 // Uses current fuzz setting when determining color match.
858 void floodFillColor(const Geometry &point_,const Color &fillColor_);
859 void floodFillColor(const ::ssize_t x_,const ::ssize_t y_,
860 const Color &fillColor_ );
862 // Flood-fill color across pixels starting at target-pixel and
863 // stopping at pixels matching specified border color.
864 // Uses current fuzz setting when determining color match.
865 void floodFillColor(const Geometry &point_,const Color &fillColor_,
866 const Color &borderColor_);
867 void floodFillColor(const ::ssize_t x_,const ::ssize_t y_,
868 const Color &fillColor_,const Color &borderColor_);
870 // Flood-fill texture across pixels that match the color of the
871 // target pixel and are neighbors of the target pixel.
872 // Uses current fuzz setting when determining color match.
873 void floodFillTexture(const Geometry &point_,const Image &texture_);
874 void floodFillTexture(const ::ssize_t x_,const ::ssize_t y_,
875 const Image &texture_);
877 // Flood-fill texture across pixels starting at target-pixel and
878 // stopping at pixels matching specified border color.
879 // Uses current fuzz setting when determining color match.
880 void floodFillTexture(const Geometry &point_,const Image &texture_,
881 const Color &borderColor_);
882 void floodFillTexture(const ::ssize_t x_,const ::ssize_t y_,
883 const Image &texture_,const Color &borderColor_);
885 // Flop image (reflect each scanline in the horizontal direction)
888 // Obtain font metrics for text string given current font,
889 // pointsize, and density settings.
890 void fontTypeMetrics(const std::string &text_,TypeMetric *metrics);
893 void frame(const Geometry &geometry_=frameGeometryDefault);
894 void frame(const size_t width_,const size_t height_,
895 const ::ssize_t innerBevel_=6,const ::ssize_t outerBevel_=6);
897 // Applies a mathematical expression to the image.
898 void fx(const std::string expression_);
899 void fx(const std::string expression_,const Magick::ChannelType channel_);
901 // Gamma correct image
902 void gamma(const double gamma_);
903 void gamma(const double gammaRed_,const double gammaGreen_,
904 const double gammaBlue_);
906 // Gaussian blur image
907 // The number of neighbor pixels to be included in the convolution
908 // mask is specified by 'width_'. The standard deviation of the
909 // gaussian bell curve is specified by 'sigma_'.
910 void gaussianBlur(const double width_,const double sigma_);
911 void gaussianBlurChannel(const ChannelType channel_,const double width_,
912 const double sigma_);
914 // Transfers read-only pixels from the image to the pixel cache as
915 // defined by the specified region
916 const Quantum *getConstPixels(const ::ssize_t x_, const ::ssize_t y_,
917 const size_t columns_,const size_t rows_) const;
919 // Obtain immutable image pixel metacontent (valid for PseudoClass images)
920 const void *getConstMetacontent(void) const;
922 // Obtain mutable image pixel metacontent (valid for PseudoClass images)
923 void *getMetacontent(void);
925 // Transfers pixels from the image to the pixel cache as defined
926 // by the specified region. Modified pixels may be subsequently
927 // transferred back to the image via syncPixels. This method is
928 // valid for DirectClass images.
929 Quantum *getPixels(const ::ssize_t x_,const ::ssize_t y_,
930 const size_t columns_,const size_t rows_);
932 // Apply a color lookup table (Hald CLUT) to the image.
933 void haldClut(const Image &clutImage_);
935 // Implode image (special effect)
936 void implode(const double factor_);
938 // Implements the inverse discrete Fourier transform (DFT) of the image
939 // either as a magnitude / phase or real / imaginary image pair.
940 void inverseFourierTransform(const Image &phase_);
941 void inverseFourierTransform(const Image &phase_,const bool magnitude_);
943 // Level image. Adjust the levels of the image by scaling the
944 // colors falling between specified white and black points to the
945 // full available quantum range. The parameters provided represent
946 // the black, mid (gamma), and white points. The black point
947 // specifies the darkest color in the image. Colors darker than
948 // the black point are set to zero. Mid point (gamma) specifies a
949 // gamma correction to apply to the image. White point specifies
950 // the lightest color in the image. Colors brighter than the
951 // white point are set to the maximum quantum value. The black and
952 // white point have the valid range 0 to QuantumRange while mid (gamma)
953 // has a useful range of 0 to ten.
954 void level(const double blackPoint_,const double whitePoint_,
955 const double gamma_=1.0);
956 void levelChannel(const ChannelType channel_,const double blackPoint_,
957 const double whitePoint_,const double gamma_=1.0);
959 // Maps the given color to "black" and "white" values, linearly spreading
960 // out the colors, and level values on a channel by channel bases, as
961 // per level(). The given colors allows you to specify different level
962 // ranges for each of the color channels separately.
963 void levelColors(const Color &blackColor_,const Color &whiteColor_,
964 const bool invert_=true);
965 void levelColorsChannel(const ChannelType channel_,
966 const Color &blackColor_,const Color &whiteColor_,
967 const bool invert_=true);
969 // Discards any pixels below the black point and above the white point and
970 // levels the remaining pixels.
971 void linearStretch(const double blackPoint_,const double whitePoint_);
973 // Rescales image with seam carving.
974 void liquidRescale(const Geometry &geometry_);
976 // Magnify image by integral size
979 // Remap image colors with closest color from reference image
980 void map(const Image &mapImage_,const bool dither_=false);
982 // Filter image by replacing each pixel component with the median
983 // color in a circular neighborhood
984 void medianFilter(const double radius_=0.0);
986 // Reduce image by integral size
989 // Modulate percent hue, saturation, and brightness of an image
990 void modulate(const double brightness_,const double saturation_,
993 // Motion blur image with specified blur factor
994 // The radius_ parameter specifies the radius of the Gaussian, in
995 // pixels, not counting the center pixel. The sigma_ parameter
996 // specifies the standard deviation of the Laplacian, in pixels.
997 // The angle_ parameter specifies the angle the object appears
998 // to be comming from (zero degrees is from the right).
999 void motionBlur(const double radius_,const double sigma_,
1000 const double angle_);
1002 // Negate colors in image. Set grayscale to only negate grayscale
1004 void negate(const bool grayscale_=false);
1005 void negateChannel(const ChannelType channel_,const bool grayscale_=false);
1007 // Normalize image (increase contrast by normalizing the pixel
1008 // values to span the full range of color values)
1009 void normalize(void);
1011 // Oilpaint image (image looks like oil painting)
1012 void oilPaint(const double radius_=0.0,const double sigma=1.0);
1014 // Change color of opaque pixel to specified pen color.
1015 void opaque(const Color &opaqueColor_,const Color &penColor_);
1017 // Set each pixel whose value is less than epsilon to epsilon or
1018 // -epsilon (whichever is closer) otherwise the pixel value remains
1020 void perceptible(const double epsilon_);
1021 void perceptibleChannel(const ChannelType channel_,const double epsilon_);
1023 // Ping is similar to read except only enough of the image is read
1024 // to determine the image columns, rows, and filesize. Access the
1025 // columns(), rows(), and fileSize() attributes after invoking
1026 // ping. The image data is not valid after calling ping.
1027 void ping(const std::string &imageSpec_);
1029 // Ping is similar to read except only enough of the image is read
1030 // to determine the image columns, rows, and filesize. Access the
1031 // columns(), rows(), and fileSize() attributes after invoking
1032 // ping. The image data is not valid after calling ping.
1033 void ping(const Blob &blob_);
1035 // Get/set pixel color at location x & y.
1036 void pixelColor(const ::ssize_t x_,const ::ssize_t y_,const Color &color_);
1037 Color pixelColor(const ::ssize_t x_,const ::ssize_t y_ ) const;
1039 // Simulates a Polaroid picture.
1040 void polaroid(const std::string &caption_,const double angle_,
1041 const PixelInterpolateMethod method_);
1043 // Reduces the image to a limited number of colors for a "poster" effect.
1044 void posterize(const size_t levels_,const DitherMethod method_);
1045 void posterizeChannel(const ChannelType channel_,const size_t levels_,
1046 const DitherMethod method_);
1048 // Execute a named process module using an argc/argv syntax similar to
1049 // that accepted by a C 'main' routine. An exception is thrown if the
1050 // requested process module doesn't exist, fails to load, or fails during
1052 void process(std::string name_,const ::ssize_t argc_,const char **argv_);
1054 // Add or remove a named profile to/from the image. Remove the
1055 // profile by passing an empty Blob (e.g. Blob()). Valid names are
1056 // "*", "8BIM", "ICM", "IPTC", or a user/format-defined profile name.
1057 void profile(const std::string name_,const Blob &colorProfile_);
1059 // Retrieve a named profile from the image. Valid names are:
1060 // "8BIM", "8BIMTEXT", "APP1", "APP1JPEG", "ICC", "ICM", & "IPTC"
1061 // or an existing user/format-defined profile name.
1062 Blob profile(const std::string name_) const;
1064 // Quantize image (reduce number of colors)
1065 void quantize(const bool measureError_=false);
1067 void quantumOperator(const ChannelType channel_,
1068 const MagickEvaluateOperator operator_,double rvalue_);
1070 void quantumOperator(const ::ssize_t x_,const ::ssize_t y_,
1071 const size_t columns_,const size_t rows_,const ChannelType channel_,
1072 const MagickEvaluateOperator operator_,const double rvalue_);
1074 // Raise image (lighten or darken the edges of an image to give a
1075 // 3-D raised or lowered effect)
1076 void raise(const Geometry &geometry_=raiseGeometryDefault,
1077 const bool raisedFlag_=false);
1079 // Random threshold image.
1081 // Changes the value of individual pixels based on the intensity
1082 // of each pixel compared to a random threshold. The result is a
1083 // low-contrast, two color image. The thresholds_ argument is a
1084 // geometry containing LOWxHIGH thresholds. If the string
1085 // contains 2x2, 3x3, or 4x4, then an ordered dither of order 2,
1086 // 3, or 4 will be performed instead. If a channel_ argument is
1087 // specified then only the specified channel is altered. This is
1088 // a very fast alternative to 'quantize' based dithering.
1089 void randomThreshold(const Geometry &thresholds_);
1090 void randomThresholdChannel(const ChannelType channel_,
1091 const Geometry &thresholds_);
1093 // Read single image frame from in-memory BLOB
1094 void read(const Blob &blob_);
1096 // Read single image frame of specified size from in-memory BLOB
1097 void read(const Blob &blob_,const Geometry &size_);
1099 // Read single image frame of specified size and depth from
1101 void read(const Blob &blob_,const Geometry &size_,const size_t depth_);
1103 // Read single image frame of specified size, depth, and format
1104 // from in-memory BLOB
1105 void read(const Blob &blob_,const Geometry &size_,const size_t depth_,
1106 const std::string &magick_);
1108 // Read single image frame of specified size, and format from
1110 void read(const Blob &blob_,const Geometry &size_,
1111 const std::string &magick_);
1113 // Read single image frame of specified size into current object
1114 void read(const Geometry &size_,const std::string &imageSpec_);
1116 // Read single image frame from an array of raw pixels, with
1117 // specified storage type (ConstituteImage), e.g.
1118 // image.read( 640, 480, "RGB", 0, pixels );
1119 void read(const size_t width_,const size_t height_,const std::string &map_,
1120 const StorageType type_,const void *pixels_);
1122 // Read single image frame into current object
1123 void read(const std::string &imageSpec_);
1125 // Transfers one or more pixel components from a buffer or file
1126 // into the image pixel cache of an image.
1127 // Used to support image decoders.
1128 void readPixels(const QuantumType quantum_,const unsigned char *source_);
1130 // Reduce noise in image using a noise peak elimination filter
1131 void reduceNoise(void);
1132 void reduceNoise(const double order_);
1134 // Resize image in terms of its pixel size.
1135 void resample(const Geometry &geometry_);
1137 // Resize image to specified size.
1138 void resize(const Geometry &geometry_);
1140 // Roll image (rolls image vertically and horizontally) by specified
1141 // number of columnms and rows)
1142 void roll(const Geometry &roll_);
1143 void roll(const size_t columns_,const size_t rows_);
1145 // Rotate image counter-clockwise by specified number of degrees.
1146 void rotate(const double degrees_);
1148 // Resize image by using pixel sampling algorithm
1149 void sample(const Geometry &geometry_);
1151 // Allocates a pixel cache region to store image pixels as defined
1152 // by the region rectangle. This area is subsequently transferred
1153 // from the pixel cache to the image via syncPixels.
1154 Quantum *setPixels(const ::ssize_t x_, const ::ssize_t y_,
1155 const size_t columns_,const size_t rows_);
1157 // Resize image by using simple ratio algorithm
1158 void scale(const Geometry &geometry_);
1160 // Segment (coalesce similar image components) by analyzing the
1161 // histograms of the color components and identifying units that
1162 // are homogeneous with the fuzzy c-means technique. Also uses
1163 // QuantizeColorSpace and Verbose image attributes
1164 void segment(const double clusterThreshold_=1.0,
1165 const double smoothingThreshold_=1.5);
1167 // Shade image using distant light source
1168 void shade(const double azimuth_=30,const double elevation_=30,
1169 const bool colorShading_=false);
1171 // Simulate an image shadow
1172 void shadow(const double percentAlpha_=80.0,const double sigma_=0.5,
1173 const ssize_t x_=5,const ssize_t y_=5);
1175 // Sharpen pixels in image
1176 // The radius_ parameter specifies the radius of the Gaussian, in
1177 // pixels, not counting the center pixel. The sigma_ parameter
1178 // specifies the standard deviation of the Laplacian, in pixels.
1179 void sharpen(const double radius_=0.0,const double sigma_=1.0);
1180 void sharpenChannel(const ChannelType channel_,const double radius_=0.0,
1181 const double sigma_=1.0);
1183 // Shave pixels from image edges.
1184 void shave(const Geometry &geometry_);
1186 // Shear image (create parallelogram by sliding image by X or Y axis)
1187 void shear(const double xShearAngle_,const double yShearAngle_);
1189 // adjust the image contrast with a non-linear sigmoidal contrast algorithm
1190 void sigmoidalContrast(const size_t sharpen_,const double contrast,
1191 const double midpoint=QuantumRange/2.0);
1193 // Image signature. Set force_ to true in order to re-calculate
1194 // the signature regardless of whether the image data has been
1196 std::string signature(const bool force_=false) const;
1198 // Solarize image (similar to effect seen when exposing a
1199 // photographic film to light during the development process)
1200 void solarize(const double factor_=50.0);
1202 // Sparse color image, given a set of coordinates, interpolates the colors
1203 // found at those coordinates, across the whole image, using various
1205 void sparseColor(const ChannelType channel_,
1206 const SparseColorMethod method_,const size_t numberArguments_,
1207 const double *arguments_);
1209 // Splice the background color into the image.
1210 void splice(const Geometry &geometry_);
1212 // Spread pixels randomly within image by specified ammount
1213 void spread(const size_t amount_=3);
1215 void statistics(ImageStatistics *statistics);
1217 // Add a digital watermark to the image (based on second image)
1218 void stegano(const Image &watermark_);
1220 // Create an image which appears in stereo when viewed with
1221 // red-blue glasses (Red image on left, blue on right)
1222 void stereo(const Image &rightImage_);
1224 // Strip strips an image of all profiles and comments.
1227 // Swirl image (image pixels are rotated by degrees)
1228 void swirl(const double degrees_);
1230 // Transfers the image cache pixels to the image.
1231 void syncPixels(void);
1233 // Channel a texture on image background
1234 void texture(const Image &texture_);
1237 void threshold(const double threshold_);
1239 // Transform image based on image and crop geometries
1240 // Crop geometry is optional
1241 void transform(const Geometry &imageGeometry_);
1242 void transform(const Geometry &imageGeometry_,
1243 const Geometry &cropGeometry_);
1245 // Origin of coordinate system to use when annotating with text or drawing
1246 void transformOrigin(const double x_,const double y_);
1248 // Reset transformation parameters to default
1249 void transformReset(void);
1251 // Scale to use when annotating with text or drawing
1252 void transformScale(const double sx_,const double sy_);
1254 // Add matte image to image, setting pixels matching color to
1256 void transparent(const Color &color_);
1258 // Add matte image to image, for all the pixels that lies in between
1259 // the given two color
1260 void transparentChroma(const Color &colorLow_,const Color &colorHigh_);
1262 // Trim edges that are the background color from the image
1265 // Replace image with a sharpened version of the original image
1266 // using the unsharp mask algorithm.
1268 // the radius of the Gaussian, in pixels, not counting the
1271 // the standard deviation of the Gaussian, in pixels.
1273 // the percentage of the difference between the original and
1274 // the blur image that is added back into the original.
1276 // the threshold in pixels needed to apply the diffence amount.
1277 void unsharpmask(const double radius_,const double sigma_,
1278 const double amount_,const double threshold_);
1279 void unsharpmaskChannel(const ChannelType channel_,const double radius_,
1280 const double sigma_,const double amount_,const double threshold_);
1282 // Map image pixels to a sine wave
1283 void wave(const double amplitude_=25.0,const double wavelength_=150.0);
1285 // Forces all pixels above the threshold into white while leaving all
1286 // pixels at or below the threshold unchanged.
1287 void whiteThreshold(const std::string &threshold_);
1288 void whiteThresholdChannel(const ChannelType channel_,
1289 const std::string &threshold_);
1291 // Write single image frame to in-memory BLOB, with optional
1292 // format and adjoin parameters.
1293 void write(Blob *blob_);
1294 void write(Blob *blob_,const std::string &magick_);
1295 void write(Blob *blob_,const std::string &magick_,const size_t depth_);
1297 // Write single image frame to an array of pixels with storage
1298 // type specified by user (DispatchImage), e.g.
1299 // image.write( 0, 0, 640, 1, "RGB", 0, pixels );
1300 void write(const ::ssize_t x_,const ::ssize_t y_,const size_t columns_,
1301 const size_t rows_,const std::string &map_,const StorageType type_,
1304 // Write single image frame to a file
1305 void write(const std::string &imageSpec_);
1307 // Transfers one or more pixel components from the image pixel
1308 // cache to a buffer or file.
1309 // Used to support image encoders.
1310 void writePixels(const QuantumType quantum_,unsigned char *destination_);
1312 // Zoom image to specified size.
1313 void zoom(const Geometry &geometry_);
1315 //////////////////////////////////////////////////////////////////////
1317 // No user-serviceable parts beyond this point
1319 //////////////////////////////////////////////////////////////////////
1321 // Construct with MagickCore::Image and default options
1322 Image(MagickCore::Image *image_);
1325 MagickCore::Image *&image(void);
1326 const MagickCore::Image *constImage(void) const;
1328 // Retrieve ImageInfo*
1329 MagickCore::ImageInfo *imageInfo(void);
1330 const MagickCore::ImageInfo *constImageInfo(void) const;
1332 // Retrieve Options*
1333 Options *options(void);
1334 const Options *constOptions(void) const;
1336 // Retrieve QuantizeInfo*
1337 MagickCore::QuantizeInfo *quantizeInfo(void);
1338 const MagickCore::QuantizeInfo *constQuantizeInfo(void) const;
1340 // Prepare to update image (copy if reference > 1)
1341 void modifyImage(void);
1343 // Register image with image registry or obtain registration id
1344 ::ssize_t registerId(void);
1346 // Replace current image (reference counted)
1347 MagickCore::Image *replaceImage(MagickCore::Image *replacement_);
1349 // Unregister image from image registry
1350 void unregisterId(void);
1357 } // end of namespace Magick
1359 #endif // Magick_Image_header