""":mod:`wand.image` --- Image objects ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Opens and manipulates images. Image objects can be used in :keyword:`with` statement, and these resources will be automatically managed (even if any error happened):: with Image(filename='pikachu.png') as i: print('width =', i.width) print('height =', i.height) """ import ctypes import functools import numbers import weakref from . import assertions from .api import libc, libmagick, library from .cdefs.structures import (CCObjectInfo, CCObjectInfo70A, CCObjectInfo710, ChannelFeature, GeometryInfo, PixelInfo, RectangleInfo) from .color import Color from .compat import (abc, binary, binary_type, encode_filename, file_types, string_type, text, to_bytes, xrange) from .exceptions import (MissingDelegateError, WandException, WandLibraryVersionError, WandRuntimeError) from .font import Font from .resource import DestroyedResourceError, Resource, genesis from .version import MAGICK_HDRI, MAGICK_VERSION_NUMBER __all__ = ('ALPHA_CHANNEL_TYPES', 'AUTO_THRESHOLD_METHODS', 'CHANNELS', 'COLORSPACE_TYPES', 'COMPARE_METRICS', 'COMPOSITE_OPERATORS', 'COMPRESSION_TYPES', 'DISPOSE_TYPES', 'DISTORTION_METHODS', 'DITHER_METHODS', 'EVALUATE_OPS', 'FILTER_TYPES', 'FUNCTION_TYPES', 'GRAVITY_TYPES', 'IMAGE_LAYER_METHOD', 'IMAGE_TYPES', 'INTERLACE_TYPES', 'KERNEL_INFO_TYPES', 'MORPHOLOGY_METHODS', 'NOISE_TYPES', 'ORIENTATION_TYPES', 'PAPERSIZE_MAP', 'PIXEL_INTERPOLATE_METHODS', 'RENDERING_INTENT_TYPES', 'SPARSE_COLOR_METHODS', 'STATISTIC_TYPES', 'STORAGE_TYPES', 'VIRTUAL_PIXEL_METHOD', 'UNIT_TYPES', 'BaseImage', 'ChannelDepthDict', 'ChannelImageDict', 'ClosedImageError', 'HistogramDict', 'Image', 'ImageProperty', 'Iterator', 'Metadata', 'OptionDict', 'manipulative', 'ArtifactTree', 'ProfileDict', 'ConnectedComponentObject') #: (:class:`tuple`) The list of :attr:`~wand.image.BaseImage.alpha_channel` #: types. #: #: - ``'undefined'`` #: - ``'activate'`` #: - ``'background'`` #: - ``'copy'`` #: - ``'deactivate'`` #: - ``'discrete'`` - Only available in ImageMagick-7 #: - ``'extract'`` #: - ``'off'`` - Only available in ImageMagick-7 #: - ``'on'`` - Only available in ImageMagick-7 #: - ``'opaque'`` #: - ``'reset'`` - Only available in ImageMagick-6 #: - ``'set'`` #: - ``'shape'`` #: - ``'transparent'`` #: - ``'flatten'`` - Only available in ImageMagick-6 #: - ``'remove'`` #: #: .. seealso:: #: `ImageMagick Image Channel`__ #: Describes the SetImageAlphaChannel method which can be used #: to modify alpha channel. Also describes AlphaChannelType #: #: __ http://www.imagemagick.org/api/channel.php#SetImageAlphaChannel ALPHA_CHANNEL_TYPES = ('undefined', 'activate', 'background', 'copy', 'deactivate', 'extract', 'opaque', 'reset', 'set', 'shape', 'transparent', 'flatten', 'remove', 'associate', 'disassociate') if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover ALPHA_CHANNEL_TYPES = ('undefined', 'activate', 'associate', 'background', 'copy', 'deactivate', 'discrete', 'disassociate', 'extract', 'off', 'on', 'opaque', 'remove', 'set', 'shape', 'transparent') #: (:class:`tuple`) The list of methods used by #: :meth:`Image.auto_threshold() ` #: #: - ``'undefined'`` #: - ``'kapur'`` #: - ``'otsu'`` #: - ``'triangle'`` #: #: .. versionadded:: 0.5.5 AUTO_THRESHOLD_METHODS = ('undefined', 'kapur', 'otsu', 'triangle') #: (:class:`dict`) The dictionary of channel types. #: #: - ``'undefined'`` #: - ``'red'`` #: - ``'gray'`` #: - ``'cyan'`` #: - ``'green'`` #: - ``'magenta'`` #: - ``'blue'`` #: - ``'yellow'`` #: - ``'alpha'`` #: - ``'opacity'`` #: - ``'black'`` #: - ``'index'`` #: - ``'composite_channels'`` #: - ``'all_channels'`` #: - ``'sync_channels'`` #: - ``'default_channels'`` #: #: .. seealso:: #: #: `ImageMagick Color Channels`__ #: Lists the various channel types with descriptions of each #: #: __ http://www.imagemagick.org/Magick++/Enumerations.html#ChannelType #: #: .. versionchanged:: 0.5.5 #: Deprecated ``true_alpha``, ``rgb_channels``, and ``gray_channels`` #: values in favor of MagickCore channel parser. #: CHANNELS = dict(undefined=0, red=1, gray=1, cyan=1, green=2, magenta=2, blue=4, yellow=4, alpha=8, opacity=8, black=32, index=32, composite_channels=47, all_channels=134217727, true_alpha=64, rgb=7, rgb_channels=7, gray_channels=1, sync_channels=256, default_channels=134217719) if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover CHANNELS = dict(undefined=0, red=1, gray=1, cyan=1, green=2, magenta=2, blue=4, yellow=4, black=8, alpha=16, opacity=16, index=32, readmask=0x0040, write_mask=128, meta=256, composite_channels=31, all_channels=134217727, true_alpha=256, rgb=7, rgb_channels=7, gray_channels=1, sync_channels=131072, default_channels=134217727) #: (:class:`tuple`) The list of colorspaces. #: #: - ``'undefined'`` #: - ``'rgb'`` #: - ``'gray'`` #: - ``'transparent'`` #: - ``'ohta'`` #: - ``'lab'`` #: - ``'xyz'`` #: - ``'ycbcr'`` #: - ``'ycc'`` #: - ``'yiq'`` #: - ``'ypbpr'`` #: - ``'yuv'`` #: - ``'cmyk'`` #: - ``'srgb'`` #: - ``'hsb'`` #: - ``'hsl'`` #: - ``'hwb'`` #: - ``'rec601luma'`` - Only available with ImageMagick-6 #: - ``'rec601ycbcr'`` #: - ``'rec709luma'`` - Only available with ImageMagick-6 #: - ``'rec709ycbcr'`` #: - ``'log'`` #: - ``'cmy'`` #: - ``'luv'`` #: - ``'hcl'`` #: - ``'lch'`` #: - ``'lms'`` #: - ``'lchab'`` #: - ``'lchuv'`` #: - ``'scrgb'`` #: - ``'hsi'`` #: - ``'hsv'`` #: - ``'hclp'`` #: - ``'xyy'`` - Only available with ImageMagick-7 #: - ``'ydbdr'`` #: #: .. seealso:: #: #: `ImageMagick Color Management`__ #: Describes the ImageMagick color management operations #: #: __ http://www.imagemagick.org/script/color-management.php #: #: .. versionadded:: 0.3.4 COLORSPACE_TYPES = ('undefined', 'rgb', 'gray', 'transparent', 'ohta', 'lab', 'xyz', 'ycbcr', 'ycc', 'yiq', 'ypbpr', 'yuv', 'cmyk', 'srgb', 'hsb', 'hsl', 'hwb', 'rec601luma', 'rec601ycbcr', 'rec709luma', 'rec709ycbcr', 'log', 'cmy', 'luv', 'hcl', 'lch', 'lms', 'lchab', 'lchuv', 'scrgb', 'hsi', 'hsv', 'hclp', 'ydbdr') if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover COLORSPACE_TYPES = ('undefined', 'cmy', 'cmyk', 'gray', 'hcl', 'hclp', 'hsb', 'hsi', 'hsl', 'hsv', 'hwb', 'lab', 'lch', 'lchab', 'lchuv', 'log', 'lms', 'luv', 'ohta', 'rec601ycbcr', 'rec709ycbcr', 'rgb', 'scrgb', 'srgb', 'transparent', 'xyy', 'xyz', 'ycbcr', 'ycc', 'ydbdr', 'yiq', 'ypbpr', 'yuv') #: (:class:`tuple`) The list of compare metric types used by #: :meth:`Image.compare() ` and #: :meth:`Image.similarity() ` methods. #: #: - ``'undefined'`` #: - ``'absolute'`` #: - ``'fuzz'`` #: - ``'mean_absolute'`` #: - ``'mean_error_per_pixel'`` #: - ``'mean_squared'`` #: - ``'normalized_cross_correlation'`` #: - ``'peak_absolute'`` #: - ``'peak_signal_to_noise_ratio'`` #: - ``'perceptual_hash'`` - Available with ImageMagick-7 #: - ``'root_mean_square'`` #: - ``'structural_similarity'`` - Available with ImageMagick-7 #: - ``'structural_dissimilarity'`` - Available with ImageMagick-7 #: #: .. seealso:: #: #: `ImageMagick Compare Operations`__ #: #: __ http://www.imagemagick.org/Usage/compare/ #: #: .. versionadded:: 0.4.3 #: #: .. versionchanged:: 0.5.4 - Remapped :c:data:`MetricType` enum. COMPARE_METRICS = ('undefined', 'absolute', 'mean_absolute', 'mean_error_per_pixel', 'mean_squared', 'peak_absolute', 'peak_signal_to_noise_ratio', 'root_mean_square', 'normalized_cross_correlation', 'fuzz') if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover COMPARE_METRICS = ('undefined', 'absolute', 'fuzz', 'mean_absolute', 'mean_error_per_pixel', 'mean_squared', 'normalized_cross_correlation', 'peak_absolute', 'peak_signal_to_noise_ratio', 'perceptual_hash', 'root_mean_square', 'structural_similarity', 'structural_dissimilarity') #: (:class:`tuple`) The list of complex operators used by #: :meth:`Image.complex() `. #: #: - ``'undefined'`` #: - ``'add'`` #: - ``'conjugate'`` #: - ``'divide'`` #: - ``'magnitude',`` #: - ``'multiply'`` #: - ``'real_imaginary'`` #: - ``'subtract'`` #: #: .. versionadded:: 0.5.5 COMPLEX_OPERATORS = ('undefined', 'add', 'conjugate', 'divide', 'magnitude', 'multiply', 'real_imaginary', 'subtract') #: (:class:`tuple`) The list of composition operators #: #: - ``'undefined'`` #: - ``'alpha'`` - Only available with ImageMagick-7 #: - ``'atop'`` #: - ``'blend'`` #: - ``'blur'`` #: - ``'bumpmap'`` #: - ``'change_mask'`` #: - ``'clear'`` #: - ``'color_burn'`` #: - ``'color_dodge'`` #: - ``'colorize'`` #: - ``'copy_black'`` #: - ``'copy_blue'`` #: - ``'copy'`` #: - ``'copy_alpha'`` - Only available with ImageMagick-7 #: - ``'copy_cyan'`` #: - ``'copy_green'`` #: - ``'copy_magenta'`` #: - ``'copy_opacity'`` - Only available with ImageMagick-6 #: - ``'copy_red'`` #: - ``'copy_yellow'`` #: - ``'darken'`` #: - ``'darken_intensity'`` #: - ``'difference'`` #: - ``'displace'`` #: - ``'dissolve'`` #: - ``'distort'`` #: - ``'divide_dst'`` #: - ``'divide_src'`` #: - ``'dst_atop'`` #: - ``'dst'`` #: - ``'dst_in'`` #: - ``'dst_out'`` #: - ``'dst_over'`` #: - ``'exclusion'`` #: - ``'freeze'`` - Added with ImageMagick-7.0.10 #: - ``'hard_light'`` #: - ``'hard_mix'`` #: - ``'hue'`` #: - ``'in'`` #: - ``'intensity'`` - Only available with ImageMagick-7 #: - ``'interpolate'`` - Added with ImageMagick-7.0.10 #: - ``'lighten'`` #: - ``'lighten_intensity'`` #: - ``'linear_burn'`` #: - ``'linear_dodge'`` #: - ``'linear_light'`` #: - ``'luminize'`` #: - ``'mathematics'`` #: - ``'minus_dst'`` #: - ``'minus_src'`` #: - ``'modulate'`` #: - ``'modulus_add'`` #: - ``'modulus_subtract'`` #: - ``'multiply'`` #: - ``'negate'`` - Added with ImageMagick-7.0.10 #: - ``'no'`` #: - ``'out'`` #: - ``'over'`` #: - ``'overlay'`` #: - ``'pegtop_light'`` #: - ``'pin_light'`` #: - ``'plus'`` #: - ``'reflect'`` - Added with ImageMagick-7.0.10 #: - ``'replace'`` #: - ``'rmse'`` - Added with ImageMagick-7.1.0 #: - ``'saliency_blend'`` - Added with ImageMagick-7.1.1 #: - ``'saturate'`` #: - ``'screen'`` #: - ``'seamless_blend'`` - Added with ImageMagick-7.1.1 #: - ``'soft_burn'`` - Added with ImageMagick-7.0.10 #: - ``'soft_dudge'`` - Added with ImageMagick-7.0.10 #: - ``'soft_light'`` #: - ``'src_atop'`` #: - ``'src'`` #: - ``'src_in'`` #: - ``'src_out'`` #: - ``'src_over'`` #: - ``'stamp'`` - Added with ImageMagick-7.0.10 #: - ``'stereo'`` #: - ``'threshold'`` #: - ``'vivid_light'`` #: - ``'xor'`` #: #: .. versionchanged:: 0.3.0 #: Renamed from :const:`COMPOSITE_OPS` to :const:`COMPOSITE_OPERATORS`. #: #: .. versionchanged:: 0.5.6 #: Operators have been updated to reflect latest changes in C-API. #: For ImageMagick-6, ``'add'`` has been renamed to ``'modulus_add'``, #: ``'subtract'`` has been renamed to ``'modulus_subtract'``, #: ``'divide'`` has been split into ``'divide_dst'`` & ``'divide_src'``, and #: ``'minus'`` has been split into ``'minus_dst'`` & ``'minus_src'``. #: #: .. seealso:: #: #: `Compositing Images`__ ImageMagick v6 Examples #: Image composition is the technique of combining images that have, #: or do not have, transparency or an alpha channel. #: This is usually performed using the IM :program:`composite` command. #: It may also be performed as either part of a larger sequence of #: operations or internally by other image operators. #: #: `ImageMagick Composition Operators`__ #: Demonstrates the results of applying the various composition #: composition operators. #: #: __ http://www.imagemagick.org/Usage/compose/ #: __ http://www.rubblewebs.co.uk/imagemagick/operators/compose.php COMPOSITE_OPERATORS = ( 'undefined', 'no', 'modulus_add', 'atop', 'blend', 'bumpmap', 'change_mask', 'clear', 'color_burn', 'color_dodge', 'colorize', 'copy_black', 'copy_blue', 'copy', 'copy_cyan', 'copy_green', 'copy_magenta', 'copy_opacity', 'copy_red', 'copy_yellow', 'darken', 'dst_atop', 'dst', 'dst_in', 'dst_out', 'dst_over', 'difference', 'displace', 'dissolve', 'exclusion', 'hard_light', 'hue', 'in', 'lighten', 'linear_light', 'luminize', 'minus_dst', 'modulate', 'multiply', 'out', 'over', 'overlay', 'plus', 'replace', 'saturate', 'screen', 'soft_light', 'src_atop', 'src', 'src_in', 'src_out', 'src_over', 'modulus_subtract', 'threshold', 'xor', 'divide_dst', 'distort', 'blur', 'pegtop_light', 'vivid_light', 'pin_light', 'linear_dodge', 'linear_burn', 'mathematics', 'divide_src', 'minus_src', 'darken_intensity', 'lighten_intensity', 'hard_mix', 'stereo' ) if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover COMPOSITE_OPERATORS = ( 'undefined', 'alpha', 'atop', 'blend', 'blur', 'bumpmap', 'change_mask', 'clear', 'color_burn', 'color_dodge', 'colorize', 'copy_black', 'copy_blue', 'copy', 'copy_cyan', 'copy_green', 'copy_magenta', 'copy_alpha', 'copy_red', 'copy_yellow', 'darken', 'darken_intensity', 'difference', 'displace', 'dissolve', 'distort', 'divide_dst', 'divide_src', 'dst_atop', 'dst', 'dst_in', 'dst_out', 'dst_over', 'exclusion', 'hard_light', 'hard_mix', 'hue', 'in', 'intensity', 'lighten', 'lighten_intensity', 'linear_burn', 'linear_dodge', 'linear_light', 'luminize', 'mathematics', 'minus_dst', 'minus_src', 'modulate', 'modulus_add', 'modulus_subtract', 'multiply', 'no', 'out', 'over', 'overlay', 'pegtop_light', 'pin_light', 'plus', 'replace', 'saturate', 'screen', 'soft_light', 'src_atop', 'src', 'src_in', 'src_out', 'src_over', 'threshold', 'vivid_light', 'xor', 'stereo', 'freeze', 'interpolate', 'negate', 'reflect', 'soft_burn', 'soft_dodge', 'stamp', 'rmse', 'saliency_blend', 'seamless_blend' ) #: (:class:`tuple`) The list of :attr:`Image.compression` types. #: #: - ``'undefined'`` #: - ``'b44a'`` #: - ``'b44'`` #: - ``'bzip'`` #: - ``'dxt1'`` #: - ``'dxt3'`` #: - ``'dxt5'`` #: - ``'fax'`` #: - ``'group4'`` #: - ``'jbig1'`` #: - ``'jbig2'`` #: - ``'jpeg2000'`` #: - ``'jpeg'`` #: - ``'losslessjpeg'`` #: - ``'lzma'`` #: - ``'lzw'`` #: - ``'no'`` #: - ``'piz'`` #: - ``'pxr24'`` #: - ``'rle'`` #: - ``'zip'`` #: - ``'zips'`` #: #: .. versionadded:: 0.3.6 #: .. versionchanged:: 0.5.0 #: Support for ImageMagick-6 & ImageMagick-7 COMPRESSION_TYPES = ( 'undefined', 'no', 'bzip', 'dxt1', 'dxt3', 'dxt5', 'fax', 'group4', 'jpeg', 'jpeg2000', 'losslessjpeg', 'lzw', 'rle', 'zip', 'zips', 'piz', 'pxr24', 'b44', 'b44a', 'lzma', 'jbig1', 'jbig2' ) if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover COMPRESSION_TYPES = ( 'undefined', 'b44a', 'b44', 'bzip', 'dxt1', 'dxt3', 'dxt5', 'fax', 'group4', 'jbig1', 'jbig2', 'jpeg2000', 'jpeg', 'losslessjpeg', 'lzma', 'lzw', 'no', 'piz', 'pxr24', 'rle', 'zip', 'zips' ) #: (:class:`tuple`) The list of :attr:`BaseImage.dispose` types. #: #: - ``'undefined'`` #: - ``'none'`` #: - ``'background'`` #: - ``'previous'`` #: #: .. versionadded:: 0.5.0 DISPOSE_TYPES = ( 'undefined', 'none', 'background', 'previous' ) #: (:class:`tuple`) The list of :meth:`BaseImage.distort` methods. #: #: - ``'undefined'`` #: - ``'affine'`` #: - ``'affine_projection'`` #: - ``'scale_rotate_translate'`` #: - ``'perspective'`` #: - ``'perspective_projection'`` #: - ``'bilinear_forward'`` #: - ``'bilinear_reverse'`` #: - ``'polynomial'`` #: - ``'arc'`` #: - ``'polar'`` #: - ``'depolar'`` #: - ``'cylinder_2_plane'`` #: - ``'plane_2_cylinder'`` #: - ``'barrel'`` #: - ``'barrel_inverse'`` #: - ``'shepards'`` #: - ``'resize'`` #: - ``'sentinel'`` #: - ``'rigidaffine'`` - Only available with ImageMagick-7.0.10, or later. #: #: .. versionadded:: 0.4.1 DISTORTION_METHODS = ( 'undefined', 'affine', 'affine_projection', 'scale_rotate_translate', 'perspective', 'perspective_projection', 'bilinear_forward', 'bilinear_reverse', 'polynomial', 'arc', 'polar', 'depolar', 'cylinder_2_plane', 'plane_2_cylinder', 'barrel', 'barrel_inverse', 'shepards', 'resize', 'sentinel', 'rigidaffine' ) #: (:class:`tuple`) The list of Dither methods. Used by #: :meth:`Image.posterize() ` and #: :meth:`Image.remap() ` methods. #: #: - ``'undefined'`` #: - ``'no'`` #: - ``'riemersma'`` #: - ``'floyd_steinberg'`` #: #: .. versionadded:: 0.5.0 DITHER_METHODS = ('undefined', 'no', 'riemersma', 'floyd_steinberg') #: (:class:`tuple`) The list of evaluation operators. Used by #: :meth:`Image.evaluate() ` method. #: #: - ``'undefined'`` #: - ``'abs'`` #: - ``'add'`` #: - ``'addmodulus'`` #: - ``'and'`` #: - ``'cosine'`` #: - ``'divide'`` #: - ``'exponential'`` #: - ``'gaussiannoise'`` #: - ``'impulsenoise'`` #: - ``'inverse_log'`` - Added with ImageMagick-7.0.10-24 #: - ``'laplaciannoise'`` #: - ``'leftshift'`` #: - ``'log'`` #: - ``'max'`` #: - ``'mean'`` #: - ``'median'`` #: - ``'min'`` #: - ``'multiplicativenoise'`` #: - ``'multiply'`` #: - ``'or'`` #: - ``'poissonnoise'`` #: - ``'pow'`` #: - ``'rightshift'`` #: - ``'set'`` #: - ``'sine'`` #: - ``'subtract'`` #: - ``'sum'`` #: - ``'threshold'`` #: - ``'thresholdblack'`` #: - ``'thresholdwhite'`` #: - ``'uniformnoise'`` #: - ``'xor'`` #: #: .. seealso:: #: #: `ImageMagick Image Evaluation Operators`__ #: Describes the MagickEvaluateImageChannel method and lists the #: various evaluations operators #: #: __ http://www.magickwand.org/MagickEvaluateImage.html EVALUATE_OPS = ('undefined', 'add', 'and', 'divide', 'leftshift', 'max', 'min', 'multiply', 'or', 'rightshift', 'set', 'subtract', 'xor', 'pow', 'log', 'threshold', 'thresholdblack', 'thresholdwhite', 'gaussiannoise', 'impulsenoise', 'laplaciannoise', 'multiplicativenoise', 'poissonnoise', 'uniformnoise', 'cosine', 'sine', 'addmodulus', 'mean', 'abs', 'exponential', 'median', 'sum', 'rootmeansquare') if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover EVALUATE_OPS = ('undefined', 'abs', 'add', 'addmodulus', 'and', 'cosine', 'divide', 'exponential', 'gaussiannoise', 'impulsenoise', 'laplaciannoise', 'leftshift', 'log', 'max', 'mean', 'median', 'min', 'multiplicativenoise', 'multiply', 'or', 'poissonnoise', 'pow', 'rightshift', 'rootmeansquare', 'set', 'sine', 'subtract', 'sum', 'thresholdblack', 'threshold', 'thresholdwhite', 'uniformnoise', 'xor', 'inverse_log') #: (:class:`tuple`) The list of filter types. Used by #: :meth:`Image.resample() ` and #: :meth:`Image.resize() ` methods. #: #: - ``'undefined'`` #: - ``'point'`` #: - ``'box'`` #: - ``'triangle'`` #: - ``'hermite'`` #: - ``'hanning'`` #: - ``'hamming'`` #: - ``'blackman'`` #: - ``'gaussian'`` #: - ``'quadratic'`` #: - ``'cubic'`` #: - ``'catrom'`` #: - ``'mitchell'`` #: - ``'jinc'`` #: - ``'sinc'`` #: - ``'sincfast'`` #: - ``'kaiser'`` #: - ``'welsh'`` #: - ``'parzen'`` #: - ``'bohman'`` #: - ``'bartlett'`` #: - ``'lagrange'`` #: - ``'lanczos'`` #: - ``'lanczossharp'`` #: - ``'lanczos2'`` #: - ``'lanczos2sharp'`` #: - ``'robidoux'`` #: - ``'robidouxsharp'`` #: - ``'cosine'`` #: - ``'spline'`` #: - ``'sentinel'`` #: #: .. seealso:: #: #: `ImageMagick Resize Filters`__ #: Demonstrates the results of resampling images using the various #: resize filters and blur settings available in ImageMagick. #: #: __ http://www.imagemagick.org/Usage/resize/ FILTER_TYPES = ('undefined', 'point', 'box', 'triangle', 'hermite', 'hanning', 'hamming', 'blackman', 'gaussian', 'quadratic', 'cubic', 'catrom', 'mitchell', 'jinc', 'sinc', 'sincfast', 'kaiser', 'welsh', 'parzen', 'bohman', 'bartlett', 'lagrange', 'lanczos', 'lanczossharp', 'lanczos2', 'lanczos2sharp', 'robidoux', 'robidouxsharp', 'cosine', 'spline', 'sentinel') #: (:class:`tuple`) The list of :attr:`Image.function ` #: types. #: #: - ``'undefined'`` #: - ``'arcsin'`` #: - ``'arctan'`` #: - ``'polynomial'`` #: - ``'sinusoid'`` FUNCTION_TYPES = ('undefined', 'polynomial', 'sinusoid', 'arcsin', 'arctan') if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover FUNCTION_TYPES = ('undefined', 'arcsin', 'arctan', 'polynomial', 'sinusoid') #: (:class:`tuple`) The list of :attr:`~BaseImage.gravity` types. #: #: - ``'forget'`` #: - ``'north_west'`` #: - ``'north'`` #: - ``'north_east'`` #: - ``'west'`` #: - ``'center'`` #: - ``'east'`` #: - ``'south_west'`` #: - ``'south'`` #: - ``'south_east'`` #: #: .. versionadded:: 0.3.0 GRAVITY_TYPES = ('forget', 'north_west', 'north', 'north_east', 'west', 'center', 'east', 'south_west', 'south', 'south_east', 'static') #: (:class:`tuple`) The list of methods for :meth:`~BaseImage.merge_layers` #: and :meth:`~Image.compare_layers`. #: #: - ``'undefined'`` #: - ``'coalesce'`` #: - ``'compareany'`` - Only used for :meth:`~Image.compare_layers`. #: - ``'compareclear'`` - Only used for :meth:`~Image.compare_layers`. #: - ``'compareoverlay'`` - Only used for :meth:`~Image.compare_layers`. #: - ``'dispose'`` #: - ``'optimize'`` #: - ``'optimizeimage'`` #: - ``'optimizeplus'`` #: - ``'optimizetrans'`` #: - ``'removedups'`` #: - ``'removezero'`` #: - ``'composite'`` #: - ``'merge'`` - Only used for :meth:`~BaseImage.merge_layers`. #: - ``'flatten'`` - Only used for :meth:`~BaseImage.merge_layers`. #: - ``'mosaic'`` - Only used for :meth:`~BaseImage.merge_layers`. #: - ``'trimbounds'`` - Only used for :meth:`~BaseImage.merge_layers`. #: #: .. versionadded:: 0.4.3 IMAGE_LAYER_METHOD = ('undefined', 'coalesce', 'compareany', 'compareclear', 'compareoverlay', 'dispose', 'optimize', 'optimizeimage', 'optimizeplus', 'optimizetrans', 'removedups', 'removezero', 'composite', 'merge', 'flatten', 'mosaic', 'trimbounds') #: (:class:`tuple`) The list of image types #: #: - ``'undefined'`` #: - ``'bilevel'`` #: - ``'grayscale'`` #: - ``'grayscalealpha'`` - Only available with ImageMagick-7 #: - ``'grayscalematte'`` - Only available with ImageMagick-6 #: - ``'palette'`` #: - ``'palettealpha'`` - Only available with ImageMagick-7 #: - ``'palettematte'`` - Only available with ImageMagick-6 #: - ``'truecolor'`` #: - ``'truecoloralpha'`` - Only available with ImageMagick-7 #: - ``'truecolormatte'`` - Only available with ImageMagick-6 #: - ``'colorseparation'`` #: - ``'colorseparationalpha'`` - Only available with ImageMagick-7 #: - ``'colorseparationmatte'`` - Only available with ImageMagick-6 #: - ``'optimize'`` #: - ``'palettebilevelalpha'`` - Only available with ImageMagick-7 #: - ``'palettebilevelmatte'`` - Only available with ImageMagick-6 #: #: .. seealso:: #: #: `ImageMagick Image Types`__ #: Describes the MagickSetImageType method which can be used #: to set the type of an image #: #: __ http://www.imagemagick.org/api/magick-image.php#MagickSetImageType IMAGE_TYPES = ('undefined', 'bilevel', 'grayscale', 'grayscalematte', 'palette', 'palettematte', 'truecolor', 'truecolormatte', 'colorseparation', 'colorseparationmatte', 'optimize', 'palettebilevelmatte') if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover IMAGE_TYPES = ('undefined', 'bilevel', 'grayscale', 'grayscalealpha', 'palette', 'palettealpha', 'truecolor', 'truecoloralpha', 'colorseparation', 'colorseparationalpha', 'optimize', 'palettebilevelalpha') #: (:class:`tuple`) The list of interlace schemes. #: #: - ``'undefined'`` #: - ``'no'`` #: - ``'line'`` #: - ``'plane'`` #: - ``'partition'`` #: - ``'gif'`` #: - ``'jpeg'`` #: - ``'png'`` #: #: .. versionadded:: 0.5.2 INTERLACE_TYPES = ('undefined', 'no', 'line', 'plane', 'partition', 'gif', 'jpeg', 'png') #: (:class:`tuple`) The list of builtin kernels. #: #: - ``'undefined'`` #: - ``'unity'`` #: - ``'gaussian'`` #: - ``'dog'`` #: - ``'log'`` #: - ``'blur'`` #: - ``'comet'`` #: - ``'laplacian'`` #: - ``'sobel'`` #: - ``'frei_chen'`` #: - ``'roberts'`` #: - ``'prewitt'`` #: - ``'compass'`` #: - ``'kirsch'`` #: - ``'diamond'`` #: - ``'square'`` #: - ``'rectangle'`` #: - ``'octagon'`` #: - ``'disk'`` #: - ``'plus'`` #: - ``'cross'`` #: - ``'ring'`` #: - ``'peaks'`` #: - ``'edges'`` #: - ``'corners'`` #: - ``'diagonals'`` #: - ``'line_ends'`` #: - ``'line_junctions'`` #: - ``'ridges'`` #: - ``'convex_hull'`` #: - ``'thin_se'`` #: - ``'skeleton'`` #: - ``'chebyshev'`` #: - ``'manhattan'`` #: - ``'octagonal'`` #: - ``'euclidean'`` #: - ``'user_defined'`` #: - ``'binomial'`` #: KERNEL_INFO_TYPES = ('undefined', 'unity', 'gaussian', 'dog', 'log', 'blur', 'comet', 'laplacian', 'sobel', 'frei_chen', 'roberts', 'prewitt', 'compass', 'kirsch', 'diamond', 'square', 'rectangle', 'octagon', 'disk', 'plus', 'cross', 'ring', 'peaks', 'edges', 'corners', 'diagonals', 'line_ends', 'line_junctions', 'ridges', 'convex_hull', 'thin_se', 'skeleton', 'chebyshev', 'manhattan', 'octagonal', 'euclidean', 'user_defined', 'binomial') if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover KERNEL_INFO_TYPES = ('undefined', 'unity', 'gaussian', 'dog', 'log', 'blur', 'comet', 'binomial', 'laplacian', 'sobel', 'frei_chen', 'roberts', 'prewitt', 'compass', 'kirsch', 'diamond', 'square', 'rectangle', 'octagon', 'disk', 'plus', 'cross', 'ring', 'peaks', 'edges', 'corners', 'diagonals', 'line_ends', 'line_junctions', 'ridges', 'convex_hull', 'thin_se', 'skeleton', 'chebyshev', 'manhattan', 'octagonal', 'euclidean', 'user_defined') #: (:class:`tuple`) The list of morphology methods. #: #: - ``'undefined'`` #: - ``'convolve'`` #: - ``'correlate'`` #: - ``'erode'`` #: - ``'dilate'`` #: - ``'erode_intensity'`` #: - ``'dilate_intensity'`` #: - ``'distance'`` #: - ``'open'`` #: - ``'close'`` #: - ``'open_intensity'`` #: - ``'close_intensity'`` #: - ``'smooth'`` #: - ``'edgein'`` #: - ``'edgeout'`` #: - ``'edge'`` #: - ``'tophat'`` #: - ``'bottom_hat'`` #: - ``'hit_and_miss'`` #: - ``'thinning'`` #: - ``'thicken'`` #: - ``'voronoi'`` #: - ``'iterative_distance'`` #: MORPHOLOGY_METHODS = ('undefined', 'convolve', 'correlate', 'erode', 'dilate', 'erode_intensity', 'dilate_intensity', 'distance', 'open', 'close', 'open_intensity', 'close_intensity', 'smooth', 'edgein', 'edgeout', 'edge', 'tophat', 'bottom_hat', 'hit_and_miss', 'thinning', 'thicken', 'voronoi', 'iterative_distance') if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover MORPHOLOGY_METHODS = ('undefined', 'convolve', 'correlate', 'erode', 'dilate', 'erode_intensity', 'dilate_intensity', 'iterative_distance', 'open', 'close', 'open_intensity', 'close_intensity', 'smooth', 'edgein', 'edgeout', 'edge', 'tophat', 'bottom_hat', 'hit_and_miss', 'thinning', 'thicken', 'distance', 'voronoi') #: (:class:`tuple`) The list of montage behaviors used by #: :meth:`Image.montage()` method. #: #: - ``'undefined'`` #: - ``'frame'`` #: - ``'unframe'`` #: - ``'concatenate'`` #: #: .. versionadded:: 0.6.8 MONTAGE_MODES = ('undefined', 'frame', 'unframe', 'concatenate') #: (:class:`tuple`) The list of noise types used by #: :meth:`Image.noise() ` method. #: #: - ``'undefined'`` #: - ``'uniform'`` #: - ``'gaussian'`` #: - ``'multiplicative_gaussian'`` #: - ``'impulse'`` #: - ``'laplacian'`` #: - ``'poisson'`` #: - ``'random'`` #: #: .. versionadded:: 0.5.3 NOISE_TYPES = ('undefined', 'uniform', 'gaussian', 'multiplicative_gaussian', 'impulse', 'laplacian', 'poisson', 'random') #: (:class:`collections.abc.Set`) The set of available #: :attr:`~BaseImage.options`. #: #: .. versionadded:: 0.3.0 #: #: .. versionchanged:: 0.3.4 #: Added ``'jpeg:sampling-factor'`` option. #: #: .. versionchanged:: 0.3.9 #: Added ``'pdf:use-cropbox'`` option. Ensure you set this option *before* #: reading the PDF document. #: #: .. deprecated:: 0.5.0 #: Any arbitrary key can be set to the option table. Key-Value pairs set #: on the MagickWand stack allowing for various coders, kernels, morphology #: (&tc) to pick and choose additional user-supplied properties/artifacts. OPTIONS = frozenset([ 'caption', 'comment', 'date:create', 'date:modify', 'exif:ColorSpace', 'exif:InteroperabilityIndex', 'fill', 'film-gamma', 'gamma', 'hdr:exposure', 'jpeg:colorspace', 'jpeg:sampling-factor', 'label', 'pdf:use-cropbox', 'png:bit-depth-written', 'png:IHDR.bit-depth-orig', 'png:IHDR.color-type-orig', 'png:tIME', 'reference-black', 'reference-white', 'signature', 'tiff:Orientation', 'tiff:photometric', 'tiff:ResolutionUnit', 'type:hinting', 'vips:metadata' ]) #: (:class:`tuple`) The list of :attr:`~BaseImage.orientation` types. #: #: .. versionadded:: 0.3.0 ORIENTATION_TYPES = ('undefined', 'top_left', 'top_right', 'bottom_right', 'bottom_left', 'left_top', 'right_top', 'right_bottom', 'left_bottom') #: (:class:`dict`) Map of papersize names to page sizes. Each page size #: is a width & height :class:`tuple` at a 72dpi resolution. #: #: .. code:: #: #: from wand.image import Image, PAPERSIZE_MAP #: #: w, h = PAPERSIZE_MAP["a4"] #: with Image(width=w, height=h, background="white") as img: #: img.save(filename="a4_page.png") #: #: .. versionadded:: 0.6.4 PAPERSIZE_MAP = { '4x6': (288, 432), '5x7': (360, 504), '7x9': (504, 648), '8x10': (576, 720), '9x11': (648, 792), '9x12': (648, 864), '10x13': (720, 936), '10x14': (720, 1008), '11x17': (792, 1224), '4A0': (4768, 6741), '2A0': (3370, 4768), 'a0': (2384, 3370), 'a1': (1684, 2384), 'a2': (1191, 1684), 'a3': (842, 1191), 'a4': (595, 842), 'a4small': (595, 842), 'a5': (420, 595), 'a6': (298, 420), 'a7': (210, 298), 'a8': (147, 210), 'a9': (105, 147), 'a10': (74, 105), 'archa': (648, 864), 'archb': (864, 1296), 'archC': (1296, 1728), 'archd': (1728, 2592), 'arche': (2592, 3456), 'b0': (2920, 4127), 'b1': (2064, 2920), 'b10': (91, 127), 'b2': (1460, 2064), 'b3': (1032, 1460), 'b4': (729, 1032), 'b5': (516, 729), 'b6': (363, 516), 'b7': (258, 363), 'b8': (181, 258), 'b9': (127, 181), 'c0': (2599, 3676), 'c1': (1837, 2599), 'c2': (1298, 1837), 'c3': (918, 1296), 'c4': (649, 918), 'c5': (459, 649), 'c6': (323, 459), 'c7': (230, 323), 'csheet': (1224, 1584), 'dsheet': (1584, 2448), 'esheet': (2448, 3168), 'executive': (540, 720), 'flsa': (612, 936), 'flse': (612, 936), 'folio': (612, 936), 'halfletter': (396, 612), 'isob0': (2835, 4008), 'isob1': (2004, 2835), 'isob10': (88, 125), 'isob2': (1417, 2004), 'isob3': (1001, 1417), 'isob4': (709, 1001), 'isob5': (499, 709), 'isob6': (354, 499), 'isob7': (249, 354), 'isob8': (176, 249), 'isob9': (125, 176), 'jisb0': (1030, 1456), 'jisb1': (728, 1030), 'jisb2': (515, 728), 'jisb3': (364, 515), 'jisb4': (257, 364), 'jisb5': (182, 257), 'jisb6': (128, 182), 'ledger': (1224, 792), 'legal': (612, 1008), 'letter': (612, 792), 'lettersmall': (612, 792), 'monarch': (279, 540), 'quarto': (610, 780), 'statement': (396, 612), 'tabloid': (792, 1224) } #: (:class:`tuple`) List of interpolate pixel methods (ImageMagick-7 only.) #: #: - ``'undefined'`` #: - ``'average'`` #: - ``'average9'`` #: - ``'average16'`` #: - ``'background'`` #: - ``'bilinear'`` #: - ``'blend'`` #: - ``'catrom'`` #: - ``'integer'`` #: - ``'mesh'`` #: - ``'nearest'`` #: - ``'spline'`` #: #: .. versionadded:: 0.5.0 PIXEL_INTERPOLATE_METHODS = ('undefined', 'average', 'average9', 'average16', 'background', 'bilinear', 'blend', 'catrom', 'integer', 'mesh', 'nearest', 'spline') #: (:class:`tuple`) List of rendering intent types used for #: :attr:`Image.rendering_intent ` #: property. #: #: - ``'undefined'`` #: - ``'saturation'`` #: - ``'perceptual'`` #: - ``'absolute'`` #: - ``'relative'`` #: #: .. versionadded:: 0.5.4 RENDERING_INTENT_TYPES = ('undefined', 'saturation', 'perceptual', 'absolute', 'relative') #: (:class:`tuple`) List of sparse color methods used by #: :class:`Image.sparse_color() ` #: #: - ``'undefined'`` #: - ``'barycentric'`` #: - ``'bilinear'`` #: - ``'shepards'`` #: - ``'voronoi'`` #: - ``'inverse'`` #: - ``'manhattan'`` #: #: .. versionadded:: 0.5.3 SPARSE_COLOR_METHODS = dict(undefined=0, barycentric=1, bilinear=7, shepards=16, voronoi=18, inverse=19, manhattan=20) #: (:class:`tuple`) The list of statistic types used by #: :meth:`Image.statistic() `. #: #: - ``'undefined'`` #: - ``'gradient'`` #: - ``'maximum'`` #: - ``'mean'`` #: - ``'median'`` #: - ``'minimum'`` #: - ``'mode'`` #: - ``'nonpeak'`` #: - ``'root_mean_square'`` #: - ``'standard_deviation'`` #: #: .. versionadded:: 0.5.3 STATISTIC_TYPES = ('undefined', 'gradient', 'maximum', 'mean', 'median', 'minimum', 'mode', 'nonpeak', 'standard_deviation', 'root_mean_square') if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover STATISTIC_TYPES = ('undefined', 'gradient', 'maximum', 'mean', 'median', 'minimum', 'mode', 'nonpeak', 'root_mean_square', 'standard_deviation') #: (:class:`tuple`) The list of pixel storage types. #: #: - ``'undefined'`` #: - ``'char'`` #: - ``'double'`` #: - ``'float'`` #: - ``'integer'`` #: - ``'long'`` #: - ``'quantum'`` #: - ``'short'`` #: #: .. versionadded:: 0.5.0 STORAGE_TYPES = ('undefined', 'char', 'double', 'float', 'integer', 'long', 'quantum', 'short') #: (:class:`tuple`) The list of resolution unit types. #: #: - ``'undefined'`` #: - ``'pixelsperinch'`` #: - ``'pixelspercentimeter'`` #: #: .. seealso:: #: #: `ImageMagick Image Units`__ #: Describes the MagickSetImageUnits method which can be used #: to set image units of resolution #: #: __ http://www.imagemagick.org/api/magick-image.php#MagickSetImageUnits UNIT_TYPES = ('undefined', 'pixelsperinch', 'pixelspercentimeter') #: (:class:`tuple`) The list of :attr:`~BaseImage.virtual_pixel` types. #: #: - ``'undefined'`` #: - ``'background'`` #: - ``'constant'`` - Only available with ImageMagick-6 #: - ``'dither'`` #: - ``'edge'`` #: - ``'mirror'`` #: - ``'random'`` #: - ``'tile'`` #: - ``'transparent'`` #: - ``'mask'`` #: - ``'black'`` #: - ``'gray'`` #: - ``'white'`` #: - ``'horizontal_tile'`` #: - ``'vertical_tile'`` #: - ``'horizontal_tile_edge'`` #: - ``'vertical_tile_edge'`` #: - ``'checker_tile'`` #: #: .. versionadded:: 0.4.1 VIRTUAL_PIXEL_METHOD = ('undefined', 'background', 'constant', 'dither', 'edge', 'mirror', 'random', 'tile', 'transparent', 'mask', 'black', 'gray', 'white', 'horizontal_tile', 'vertical_tile', 'horizontal_tile_edge', 'vertical_tile_edge', 'checker_tile') if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover VIRTUAL_PIXEL_METHOD = ('undefined', 'background', 'dither', 'edge', 'mirror', 'random', 'tile', 'transparent', 'mask', 'black', 'gray', 'white', 'horizontal_tile', 'vertical_tile', 'horizontal_tile_edge', 'vertical_tile_edge', 'checker_tile') def manipulative(function): """Mark the operation manipulating itself instead of returning new one.""" @functools.wraps(function) def wrapped(self, *args, **kwargs): result = function(self, *args, **kwargs) self.dirty = True return result return wrapped def trap_exception(function): @functools.wraps(function) def wrapped(self, *args, **kwargs): result = function(self, *args, **kwargs) if not bool(result): self.raise_exception() return result return wrapped class BaseImage(Resource): """The abstract base of :class:`Image` (container) and :class:`~wand.sequence.SingleImage`. That means the most of operations, defined in this abstract class, are possible for both :class:`Image` and :class:`~wand.sequence.SingleImage`. .. versionadded:: 0.3.0 """ #: (:class:`OptionDict`) The mapping of internal option settings. #: #: .. versionadded:: 0.3.0 #: #: .. versionchanged:: 0.3.4 #: Added ``'jpeg:sampling-factor'`` option. #: #: .. versionchanged:: 0.3.9 #: Added ``'pdf:use-cropbox'`` option. options = None #: (:class:`collections.abc.Sequence`) The list of #: :class:`~wand.sequence.SingleImage`\ s that the image contains. #: #: .. versionadded:: 0.3.0 sequence = None #: (:class:`bool`) Whether the image is changed or not. dirty = None #: (:class:`numbers.Integral`) Internal placeholder for #: :attr:`seed` property. #: #: .. versionadded:: 0.5.5 _seed = None c_is_resource = library.IsMagickWand c_destroy_resource = library.DestroyMagickWand c_get_exception = library.MagickGetException c_clear_exception = library.MagickClearException __slots__ = '_wand', def __init__(self, wand): self.wand = wand self.channel_images = ChannelImageDict(self) self.channel_depths = ChannelDepthDict(self) self.options = OptionDict(self) self.dirty = False def __eq__(self, other): if isinstance(other, type(self)): return self.signature == other.signature return False def __getitem__(self, idx): if (not isinstance(idx, string_type) and isinstance(idx, abc.Iterable)): idx = tuple(idx) d = len(idx) if not (1 <= d <= 2): raise ValueError('index cannot be {0}-dimensional'.format(d)) elif d == 2: x, y = idx x_slice = isinstance(x, slice) y_slice = isinstance(y, slice) if x_slice and not y_slice: y = slice(y, y + 1) elif not x_slice and y_slice: x = slice(x, x + 1) elif not (x_slice or y_slice): if not (isinstance(x, numbers.Integral) and isinstance(y, numbers.Integral)): raise TypeError('x and y must be integral, not ' + repr((x, y))) if x < 0: x += self.width if y < 0: y += self.height if x >= self.width: raise IndexError('x must be less than width') elif y >= self.height: raise IndexError('y must be less than height') elif x < 0: raise IndexError('x cannot be less than 0') elif y < 0: raise IndexError('y cannot be less than 0') with iter(self) as iterator: iterator.seek(y) return iterator.next(x) if not (x.step is None and y.step is None): raise ValueError('slicing with step is unsupported') elif (x.start is None and x.stop is None and y.start is None and y.stop is None): return self.clone() cloned = self.clone() try: cloned.crop(x.start, y.start, x.stop, y.stop) except ValueError as e: raise IndexError(str(e)) return cloned else: return self[idx[0]] elif isinstance(idx, numbers.Integral): if idx < 0: idx += self.height elif idx >= self.height: raise IndexError('index must be less than height, but got ' + repr(idx)) elif idx < 0: raise IndexError('index cannot be less than zero, but got ' + repr(idx)) with iter(self) as iterator: iterator.seek(idx) return iterator.next() elif isinstance(idx, slice): return self[:, idx] raise TypeError('unsupported index type: ' + repr(idx)) def __setitem__(self, idx, color): if isinstance(color, string_type): color = Color(color) assertions.assert_color(color=color) if not isinstance(idx, abc.Iterable): raise TypeError('Expecting list of x,y coordinates, not ' + repr(idx)) idx = tuple(idx) if len(idx) != 2: msg = 'pixel index can not be {0}-dimensional'.format(len(idx)) raise ValueError(msg) colorspace = self.colorspace s_index = STORAGE_TYPES.index("double") width, height = self.size x1, y1 = idx x2, y2 = 1, 1 if not (isinstance(x1, numbers.Integral) and isinstance(y1, numbers.Integral)): raise TypeError('Expecting x & y to be integers') if x1 < 0: x1 += width if y1 < 0: y1 += height if x1 >= width: raise ValueError('x must be less than image width') elif y1 >= height: raise ValueError('y must be less than image height') if colorspace == 'gray': channel_map = b'I' pixel = (ctypes.c_double * 1)() pixel[0] = color.red elif colorspace == 'cmyk': channel_map = b'CMYK' pixel = (ctypes.c_double * 5)() pixel[0] = color.red pixel[1] = color.green pixel[2] = color.blue pixel[3] = color.black if self.alpha_channel: channel_map += b'A' pixel[4] = color.alpha else: channel_map = b'RGB' pixel = (ctypes.c_double * 4)() pixel[0] = color.red pixel[1] = color.green pixel[2] = color.blue if self.alpha_channel: channel_map += b'A' pixel[3] = color.alpha r = library.MagickImportImagePixels(self.wand, x1, y1, x2, y2, channel_map, s_index, ctypes.byref(pixel)) if not r: self.raise_exception() def __hash__(self): return hash(self.signature) def __iter__(self): return Iterator(image=self) def __len__(self): return self.height def __ne__(self, other): return not (self == other) def __repr__(self, extra_format=' ({self.width}x{self.height})'): cls = type(self) typename = '{0}.{1}'.format( cls.__module__, getattr(cls, '__qualname__', cls.__name__) ) if getattr(self, 'c_resource', None) is None: return '<{0}: (closed)>'.format(typename) sig = self.signature if not sig: return '<{0}: (empty)>'.format(typename) return '<{0}: {1}{2}>'.format( typename, sig[:7], extra_format.format(self=self) ) @property def __array_interface__(self): """Allows image-data from :class:`Image ` instances to be loaded into numpy's array. .. code:: import numpy from wand.image import Image with Image(filename='rose:') as img: img_data = numpy.asarray(img) :raises ValueError: if image has no data. .. versionadded:: 0.5.0 .. versionchanged:: 0.6.0 The :attr:`shape` property is now ordered by ``height``, ``width``, and ``channel``. .. versionchanged:: 0.6.2 Color spaces ``gray`` & ``cmyk`` are now supported. """ if not self.signature: raise ValueError("No image data to interface with.") width, height = self.size storage_type = 1 # CharPixel cs = self.colorspace if cs in ('gray',): channel_format = binary('R') elif cs in ('cmyk',): channel_format = binary('CMYK') else: channel_format = binary('RGB') if self.alpha_channel: channel_format += binary('A') channel_number = len(channel_format) self._c_buffer = (width * height * channel_number * ctypes.c_char)() # FIXME: Move to pixel-data import/export methods. r = library.MagickExportImagePixels(self.wand, 0, 0, width, height, channel_format, storage_type, ctypes.byref(self._c_buffer)) if not r: self.raise_exception() return dict(data=(ctypes.addressof(self._c_buffer), True), shape=(height, width, channel_number), typestr='|u1', version=3) @property def alpha_channel(self): """(:class:`bool`) Get state of image alpha channel. It can also be used to enable/disable alpha channel, but with different behavior such as new, copied, or existing. Behavior of setting :attr:`alpha_channel` is defined with the following values: - ``'activate'``, ``'on'``, or :const:`True` will enable an images alpha channel. Existing alpha data is preserved. - ``'deactivate'``, ``'off'``, or :const:`False` will disable an images alpha channel. Any data on the alpha will be preserved. - ``'associate'`` & ``'disassociate'`` toggle alpha channel flag in certain image-file specifications. - ``'set'`` enables and resets any data in an images alpha channel. - ``'opaque'`` enables alpha/matte channel, and forces full opaque image. - ``'transparent'`` enables alpha/matte channel, and forces full transparent image. - ``'extract'`` copies data in alpha channel across all other channels, and disables alpha channel. - ``'copy'`` calculates the gray-scale of RGB channels, and applies it to alpha channel. - ``'shape'`` is identical to ``'copy'``, but will color the resulting image with the value defined with :attr:`background_color`. - ``'remove'`` will composite :attr:`background_color` value. - ``'background'`` replaces full-transparent color with background color. .. note:: The :attr:`alpha_channel` attribute will always return ``True`` if alpha channel is enabled, and ``False`` otherwise. Setting this property with a string value from :const:`ALPHA_CHANNEL_TYPES` will resolve to a :class:`bool` after applying channel operations listed above. With ImageMagick-6, values ``'on'`` & ``'off'`` are aliased to ``'activate'`` & ``'deactivate'``. However in ImageMagick-7, both ``'on'`` & ``'off'`` have their own behavior. .. versionadded:: 0.2.1 .. versionchanged:: 0.4.1 Support for additional setting values. However :attr:`Image.alpha_channel` will continue to return :class:`bool` if the current alpha/matte state is enabled. .. versionchanged:: 0.6.0 Setting the alpha channel will apply the change to all frames in the image stack. """ return bool(library.MagickGetImageAlphaChannel(self.wand)) @alpha_channel.setter @manipulative def alpha_channel(self, alpha_type): is_im6 = MAGICK_VERSION_NUMBER < 0x700 # Map common aliases for ``'deactivate'`` if alpha_type is False or (alpha_type == 'off' and is_im6): alpha_type = 'deactivate' # Map common aliases for ``'activate'`` elif alpha_type is True or (alpha_type == 'on' and is_im6): alpha_type = 'activate' assertions.string_in_list(ALPHA_CHANNEL_TYPES, 'wand.image.ALPHA_CHANNEL_TYPES', alpha_channel=alpha_type) alpha_index = ALPHA_CHANNEL_TYPES.index(alpha_type) library.MagickSetLastIterator(self.wand) n = library.MagickGetIteratorIndex(self.wand) library.MagickResetIterator(self.wand) for i in xrange(0, n + 1): library.MagickSetIteratorIndex(self.wand, i) library.MagickSetImageAlphaChannel(self.wand, alpha_index) @property def animation(self): """(:class:`bool`) Whether the image is animation or not. It doesn't only mean that the image has two or more images (frames), but all frames are even the same size. It's about image format, not content. It's :const:`False` even if :mimetype:`image/ico` consists of two or more images of the same size. For example, it's :const:`False` for :mimetype:`image/jpeg`, :mimetype:`image/gif`, :mimetype:`image/ico`. If :mimetype:`image/gif` has two or more frames, it's :const:`True`. If :mimetype:`image/gif` has only one frame, it's :const:`False`. .. versionadded:: 0.3.0 .. versionchanged:: 0.3.8 Became to accept :mimetype:`image/x-gif` as well. """ return False @property def antialias(self): """(:class:`bool`) If vectors & fonts will use anti-aliasing. .. versionchanged:: 0.5.0 Previously named :attr:`font_antialias`. """ return bool(library.MagickGetAntialias(self.wand)) @antialias.setter @manipulative def antialias(self, antialias): assertions.assert_bool(antialias=antialias) library.MagickSetAntialias(self.wand, antialias) @property def background_color(self): """(:class:`wand.color.Color`) The image background color. It can also be set to change the background color. .. versionadded:: 0.1.9 .. versionchanged:: 0.6.7 Allow property to be set before image read. """ pixel = library.NewPixelWand() if library.MagickGetNumberImages(self.wand): result = library.MagickGetImageBackgroundColor(self.wand, pixel) else: pixel = library.MagickGetBackgroundColor(self.wand) result = True if not result: # pragma: no cover self.raise_exception() else: color = Color.from_pixelwand(pixel) pixel = library.DestroyPixelWand(pixel) return color @background_color.setter @manipulative def background_color(self, color): if isinstance(color, string_type): color = Color(color) assertions.assert_color(color=color) with color: # Only set the image background if an image was loaded. if library.MagickGetNumberImages(self.wand): result = library.MagickSetImageBackgroundColor(self.wand, color.resource) if not result: # pragma: no cover self.raise_exception() # Also set the image stack. result = library.MagickSetBackgroundColor(self.wand, color.resource) if not result: self.raise_exception() @property def blue_primary(self): """(:class:`tuple`) The chromatic blue primary point for the image. With ImageMagick-6 the primary value is ``(x, y)`` coordinates; however, ImageMagick-7 has ``(x, y, z)``. .. versionadded:: 0.5.2 """ x = ctypes.c_double(0.0) y = ctypes.c_double(0.0) r = None p = None if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickGetImageBluePrimary(self.wand, x, y) p = (x.value, y.value) else: # pragma: no cover z = ctypes.c_double(0.0) r = library.MagickGetImageBluePrimary(self.wand, x, y, z) p = (x.value, y.value, z.value) if not r: # pragma: no cover self.raise_exception() return p @blue_primary.setter def blue_primary(self, coordinates): r = None if not isinstance(coordinates, abc.Sequence): raise TypeError('Primary must be a tuple') if MAGICK_VERSION_NUMBER < 0x700: x, y = coordinates r = library.MagickSetImageBluePrimary(self.wand, x, y) else: # pragma: no cover x, y, z = coordinates r = library.MagickSetImageBluePrimary(self.wand, x, y, z) if not r: # pragma: no cover self.raise_exception() @property def border_color(self): """(:class:`wand.color.Color`) The image border color. Used for special effects like :meth:`polaroid()`. .. versionadded:: 0.5.4 """ pixel = library.NewPixelWand() result = library.MagickGetImageBorderColor(self.wand, pixel) if not result: # pragma: no cover self.raise_exception() else: color = Color.from_pixelwand(pixel) pixel = library.DestroyPixelWand(pixel) return color @border_color.setter def border_color(self, color): if isinstance(color, string_type): color = Color(color) assertions.assert_color(border_color=color) with color: r = library.MagickSetImageBorderColor(self.wand, color.resource) if not r: # pragma: no cover self.raise_exception() @property def colors(self): """(:class:`numbers.Integral`) Count of unique colors used within the image. This is READ ONLY property. .. versionadded:: 0.5.3 """ return library.MagickGetImageColors(self.wand) @property def colorspace(self): """(:class:`basestring`) The image colorspace. Defines image colorspace as in :const:`COLORSPACE_TYPES` enumeration. It may raise :exc:`ValueError` when the colorspace is unknown. .. versionadded:: 0.3.4 """ colorspace_type_index = library.MagickGetImageColorspace(self.wand) if not colorspace_type_index: # pragma: no cover self.raise_exception() return COLORSPACE_TYPES[text(colorspace_type_index)] @colorspace.setter @manipulative def colorspace(self, colorspace_type): assertions.string_in_list(COLORSPACE_TYPES, 'wand.image.COLORSPACE_TYPES', colorspace=colorspace_type) r = library.MagickSetImageColorspace( self.wand, COLORSPACE_TYPES.index(colorspace_type) ) if not r: # pragma: no cover self.raise_exception() @property def compose(self): """(:class:`basestring`) The type of image compose. It's a string from :const:`COMPOSITE_OPERATORS` list. It also can be set. .. versionadded:: 0.5.1 """ compose_index = library.MagickGetImageCompose(self.wand) return COMPOSITE_OPERATORS[compose_index] @compose.setter def compose(self, operator): assertions.string_in_list(COMPOSITE_OPERATORS, 'wand.image.COMPOSITE_OPERATORS', compose=operator) library.MagickSetImageCompose(self.wand, COMPOSITE_OPERATORS.index(operator)) @property def compression(self): """(:class:`basestring`) The type of image compression. It's a string from :const:`COMPRESSION_TYPES` list. It also can be set. .. versionadded:: 0.3.6 .. versionchanged:: 0.5.2 Setting :attr:`compression` now sets both `image_info` and `images` in the internal image stack. """ compression_index = library.MagickGetImageCompression(self.wand) return COMPRESSION_TYPES[compression_index] @compression.setter def compression(self, value): assertions.string_in_list(COMPRESSION_TYPES, 'wand.image.COMPRESSION_TYPES', compression=value) library.MagickSetCompression( self.wand, COMPRESSION_TYPES.index(value) ) library.MagickSetImageCompression( self.wand, COMPRESSION_TYPES.index(value) ) @property def compression_quality(self): """(:class:`numbers.Integral`) Compression quality of this image. .. versionadded:: 0.2.0 .. versionchanged:: 0.5.2 Setting :attr:`compression_quality` now sets both `image_info` and `images` in the internal image stack. """ return library.MagickGetImageCompressionQuality(self.wand) @compression_quality.setter @manipulative def compression_quality(self, quality): """Set compression quality for the image. :param quality: new compression quality setting :type quality: :class:`numbers.Integral` """ assertions.assert_integer(compression_quality=quality) library.MagickSetCompressionQuality(self.wand, quality) r = library.MagickSetImageCompressionQuality(self.wand, quality) if not r: # pragma: no cover raise ValueError('Unable to set compression quality to ' + repr(quality)) @property def delay(self): """(:class:`numbers.Integral`) The number of ticks between frames. .. versionadded:: 0.5.9 """ return library.MagickGetImageDelay(self.wand) @delay.setter def delay(self, value): assertions.assert_integer(delay=value) library.MagickSetImageDelay(self.wand, value) @property def depth(self): """(:class:`numbers.Integral`) The depth of this image. .. versionadded:: 0.2.1 """ return library.MagickGetImageDepth(self.wand) @depth.setter @manipulative def depth(self, depth): r = library.MagickSetImageDepth(self.wand, depth) if not r: # pragma: no cover raise self.raise_exception() @property def dispose(self): """(:class:`basestring`) Controls how the image data is handled during animations. Values are from :const:`DISPOSE_TYPES` list, and can also be set. .. seealso:: `Dispose Images`__ section in ``Animation Basics`` article. __ https://www.imagemagick.org/Usage/anim_basics/#dispose_images .. versionadded:: 0.5.0 """ dispose_idx = library.MagickGetImageDispose(self.wand) try: return DISPOSE_TYPES[dispose_idx] except IndexError: # pragma: no cover return DISPOSE_TYPES[0] @dispose.setter def dispose(self, value): assertions.string_in_list(DISPOSE_TYPES, 'wand.image.DISPOSE_TYPES', dispose=value) library.MagickSetImageDispose(self.wand, DISPOSE_TYPES.index(value)) @property def font(self): """(:class:`wand.font.Font`) The current font options.""" if not self.font_path: return None return Font( path=text(self.font_path), size=self.font_size, color=self.font_color, antialias=self.antialias, stroke_color=self.stroke_color, stroke_width=self.stroke_width ) @font.setter @manipulative def font(self, font): if not isinstance(font, Font): raise TypeError('font must be a wand.font.Font, not ' + repr(font)) self.font_path = font.path self.font_size = font.size self.font_color = font.color self.antialias = font.antialias if font.stroke_color: self.stroke_color = font.stroke_color if font.stroke_width is not None: self.stroke_width = font.stroke_width @property def font_antialias(self): """ .. deprecated:: 0.5.0 Use :attr:`antialias` instead. """ return self.antialias @font_antialias.setter def font_antialias(self, antialias): self.antialias = antialias @property def font_color(self): return Color(self.options['fill']) @font_color.setter @manipulative def font_color(self, color): if isinstance(color, string_type): color = Color(color) assertions.assert_color(font_color=color) self.options['fill'] = color.string @property def font_path(self): """(:class:`basestring`) The path of the current font. It also can be set. """ font_str = None font_p = library.MagickGetFont(self.wand) if font_p: font_str = text(ctypes.string_at(font_p)) font_p = library.MagickRelinquishMemory(font_p) return font_str @font_path.setter @manipulative def font_path(self, font): font = binary(font) r = library.MagickSetFont(self.wand, font) if not r: # pragma: no cover self.raise_exception() @property def font_size(self): """(:class:`numbers.Real`) The font size. It also can be set.""" return library.MagickGetPointsize(self.wand) @font_size.setter @manipulative def font_size(self, size): assertions.assert_real(font_size=size) if size < 0.0: raise ValueError('cannot be less than 0.0, but got ' + repr(size)) r = library.MagickSetPointsize(self.wand, size) if not r: # pragma: no cover self.raise_exception() @property def format(self): """(:class:`basestring`) The image format. If you want to convert the image format, just reset this property:: assert isinstance(img, wand.image.Image) img.format = 'png' It may raise :exc:`ValueError` when the format is unsupported. .. seealso:: `ImageMagick Image Formats`__ ImageMagick uses an ASCII string known as *magick* (e.g. ``GIF``) to identify file formats, algorithms acting as formats, built-in patterns, and embedded profile types. __ http://www.imagemagick.org/script/formats.php .. versionadded:: 0.1.6 """ fmt_str = None fmt_p = library.MagickGetImageFormat(self.wand) if fmt_p: fmt_str = text(ctypes.string_at(fmt_p)) fmt_p = library.MagickRelinquishMemory(fmt_p) return fmt_str @format.setter def format(self, fmt): assertions.assert_string(format=fmt) fmt = fmt.strip() r = library.MagickSetImageFormat(self.wand, binary(fmt.upper())) if not r: raise ValueError(repr(fmt) + ' is unsupported format') r = library.MagickSetFilename(self.wand, b'buffer.' + binary(fmt.lower())) if not r: # pragma: no cover self.raise_exception() @property def fuzz(self): """(:class:`numbers.Real`) The normalized real number between ``0.0`` and :attr:`quantum_range`. This property influences the accuracy of :meth:`compare()`. .. versionadded:: 0.5.3 """ return library.MagickGetImageFuzz(self.wand) @fuzz.setter def fuzz(self, value): assertions.assert_real(fuzz=value) library.MagickSetImageFuzz(self.wand, value) @property def gravity(self): """(:class:`basestring`) The text placement gravity used when annotating with text. It's a string from :const:`GRAVITY_TYPES` list. It also can be set. """ gravity_index = library.MagickGetGravity(self.wand) if not gravity_index: # pragma: no cover self.raise_exception() return GRAVITY_TYPES[gravity_index] @gravity.setter @manipulative def gravity(self, value): assertions.string_in_list(GRAVITY_TYPES, 'wand.image.GRAVITY_TYPES', gravity=value) library.MagickSetGravity(self.wand, GRAVITY_TYPES.index(value)) @property def green_primary(self): """(:class:`tuple`) The chromatic green primary point for the image. With ImageMagick-6 the primary value is ``(x, y)`` coordinates; however, ImageMagick-7 has ``(x, y, z)``. .. versionadded:: 0.5.2 """ x = ctypes.c_double(0.0) y = ctypes.c_double(0.0) r = None p = None if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickGetImageGreenPrimary(self.wand, x, y) p = (x.value, y.value) else: # pragma: no cover z = ctypes.c_double(0.0) r = library.MagickGetImageGreenPrimary(self.wand, x, y, z) p = (x.value, y.value, z.value) if not r: # pragma: no cover self.raise_exception() return p @green_primary.setter def green_primary(self, coordinates): r = None if not isinstance(coordinates, abc.Sequence): raise TypeError('Primary must be a tuple') if MAGICK_VERSION_NUMBER < 0x700: x, y = coordinates r = library.MagickSetImageGreenPrimary(self.wand, x, y) else: # pragma: no cover x, y, z = coordinates r = library.MagickSetImageGreenPrimary(self.wand, x, y, z) if not r: # pragma: no cover self.raise_exception() @property def height(self): """(:class:`numbers.Integral`) The height of this image.""" return library.MagickGetImageHeight(self.wand) @height.setter @manipulative def height(self, height): assertions.assert_unsigned_integer(height=height) library.MagickSetSize(self.wand, self.width, height) @property def histogram(self): """(:class:`HistogramDict`) The mapping that represents the histogram. Keys are :class:`~wand.color.Color` objects, and values are the number of pixels. .. tip:: True-color photos can have millions of color values. If performance is more valuable than accuracy, remember to :meth:`quantize` the image before generating a :class:`HistogramDict`. with Image(filename='hd_photo.jpg') as img: img.quantize(255, 'RGB', 0, False, False) hist = img.histogram .. versionadded:: 0.3.0 """ return HistogramDict(self) @property def interlace_scheme(self): """(:class:`basestring`) The interlace used by the image. See :const:`INTERLACE_TYPES`. .. versionadded:: 0.5.2 .. versionchanged:: 0.6.2 The :attr:`interlace_scheme` property now points to the image. Previously was pointing to the :c:struct:`MagickWand`. """ scheme_idx = library.MagickGetImageInterlaceScheme(self.wand) return INTERLACE_TYPES[scheme_idx] @interlace_scheme.setter def interlace_scheme(self, scheme): assertions.string_in_list(INTERLACE_TYPES, 'wand.image.INTERLACE_TYPES', interlace_scheme=scheme) scheme_idx = INTERLACE_TYPES.index(scheme) library.MagickSetImageInterlaceScheme(self.wand, scheme_idx) @property def interpolate_method(self): """(:class:`basestring`) The interpolation method of the image. See :const:`PIXEL_INTERPOLATE_METHODS`. .. versionadded:: 0.5.2 """ method_idx = library.MagickGetImageInterpolateMethod(self.wand) return PIXEL_INTERPOLATE_METHODS[method_idx] @interpolate_method.setter def interpolate_method(self, method): assertions.string_in_list(PIXEL_INTERPOLATE_METHODS, 'wand.image.PIXEL_INTERPOLATE_METHODS', interpolate_method=method) method_idx = PIXEL_INTERPOLATE_METHODS.index(method) library.MagickSetImageInterpolateMethod(self.wand, method_idx) @property def kurtosis(self): """(:class:`numbers.Real`) The kurtosis of the image. .. tip:: If you want both :attr:`kurtosis` & :attr:`skewness`, it would be faster to call :meth:`kurtosis_channel()` directly. .. versionadded:: 0.5.3 """ k, _ = self.kurtosis_channel() return k @property def length_of_bytes(self): """(:class:`numbers.Integral`) The original size, in bytes, of the image read. This will return `0` if the image was modified in a way that would invalidate the original length value. .. versionadded:: 0.5.4 """ size_ptr = ctypes.c_size_t(0) library.MagickGetImageLength(self.wand, ctypes.byref(size_ptr)) return size_ptr.value @property def loop(self): """(:class:`numbers.Integral`) Number of frame iterations. A value of ``0`` will loop forever.""" return library.MagickGetImageIterations(self.wand) @loop.setter def loop(self, iterations): assertions.assert_unsigned_integer(loop=iterations) library.MagickSetImageIterations(self.wand, iterations) @property def matte_color(self): """(:class:`wand.color.Color`) The color value of the matte channel. This can also be set. .. versionadded:: 0.4.1 """ pixel = library.NewPixelWand() result = library.MagickGetImageMatteColor(self.wand, pixel) if result: color = Color.from_pixelwand(pixel) pixel = library.DestroyPixelWand(pixel) return color else: # pragma: no cover self.raise_exception() @matte_color.setter @manipulative def matte_color(self, color): if isinstance(color, string_type): color = Color(color) assertions.assert_color(matte_color=color) with color: result = library.MagickSetImageMatteColor(self.wand, color.resource) if not result: # pragma: no cover self.raise_exception() @property def maxima(self): """(:class:`numbers.Real`) The maximum quantum value within the image. Value between 0.0 and :attr:`quantum_range` .. tip:: If you want both :attr:`maxima` & :attr:`minima`, it would be faster to call :meth:`range_channel()` directly. .. versionadded:: 0.5.3 """ _, max_q = self.range_channel() return max_q @property def mean(self): """(:class:`numbers.Real`) The mean of the image, and have a value between 0.0 and :attr:`quantum_range` .. tip:: If you want both :attr:`mean` & :attr:`standard_deviation`, it would be faster to call :meth:`mean_channel()` directly. .. versionadded:: 0.5.3 """ m, _ = self.mean_channel() return m @property def minima(self): """(:class:`numbers.Real`) The minimum quantum value within the image. Value between 0.0 and :attr:`quantum_range` .. tip:: If you want both :attr:`maxima` & :attr:`minima`, it would be faster to call :meth:`range_channel()` directly. .. versionadded:: 0.5.3 """ min_q, _ = self.range_channel() return min_q @property def orientation(self): """(:class:`basestring`) The image orientation. It's a string from :const:`ORIENTATION_TYPES` list. It also can be set. .. versionadded:: 0.3.0 """ orientation_index = library.MagickGetImageOrientation(self.wand) try: return ORIENTATION_TYPES[orientation_index] except IndexError: # pragma: no cover return ORIENTATION_TYPES[0] @orientation.setter @manipulative def orientation(self, value): assertions.string_in_list(ORIENTATION_TYPES, 'wand.image.ORIENTATION_TYPES', orientation=value) index = ORIENTATION_TYPES.index(value) library.MagickSetImageOrientation(self.wand, index) @property def page(self): """The dimensions and offset of this Wand's page as a 4-tuple: ``(width, height, x, y)``. .. code:: with Image(filename='wizard:') as img: img.page = (595, 842, 0, 0) Note that since it is based on the virtual canvas, it may not equal the dimensions of an image. See the ImageMagick documentation on the virtual canvas for more information. This attribute can also be set by using a named papersize. For example:: with Image(filename='wizard:') as img: img.page = 'a4' .. versionadded:: 0.4.3 .. versionchanged:: 0.6.4 Added support for setting by papersize. """ w = ctypes.c_size_t() h = ctypes.c_size_t() x = ctypes.c_ssize_t() y = ctypes.c_ssize_t() r = library.MagickGetImagePage(self.wand, w, h, x, y) if not r: # pragma: no cover self.raise_exception() return int(w.value), int(h.value), int(x.value), int(y.value) @page.setter @manipulative def page(self, newpage): if isinstance(newpage, string_type): c_ptr = libmagick.GetPageGeometry(newpage.encode()) ri = RectangleInfo() c_ptr = ctypes.cast(c_ptr, ctypes.c_char_p) libmagick.ParseAbsoluteGeometry(c_ptr, ctypes.byref(ri)) newpage = (ri.width, ri.height, ri.x, ri.y) libmagick.DestroyString(c_ptr) del ri if isinstance(newpage, abc.Sequence): w, h, x, y = newpage else: raise TypeError("page layout must be 4-tuple") r = library.MagickSetImagePage(self.wand, w, h, x, y) if not r: # pragma: no cover self.raise_exception() @property def page_height(self): """(:class:`numbers.Integral`) The height of the page for this wand. .. versionadded:: 0.4.3 """ return self.page[1] @page_height.setter @manipulative def page_height(self, height): newpage = list(self.page) newpage[1] = height self.page = newpage @property def page_width(self): """(:class:`numbers.Integral`) The width of the page for this wand. .. versionadded:: 0.4.3 """ return self.page[0] @page_width.setter @manipulative def page_width(self, width): newpage = list(self.page) newpage[0] = width self.page = newpage @property def page_x(self): """(:class:`numbers.Integral`) The X-offset of the page for this wand. .. versionadded:: 0.4.3 """ return self.page[2] @page_x.setter @manipulative def page_x(self, x): newpage = list(self.page) newpage[2] = x self.page = newpage @property def page_y(self): """(:class:`numbers.Integral`) The Y-offset of the page for this wand. .. versionadded:: 0.4.3 """ return self.page[3] @page_y.setter @manipulative def page_y(self, y): newpage = list(self.page) newpage[3] = y self.page = newpage @property def quantum_range(self): """(`:class:`numbers.Integral`) The maximum value of a color channel that is supported by the imagemagick library. .. versionadded:: 0.2.0 """ result = ctypes.c_size_t() library.MagickGetQuantumRange(ctypes.byref(result)) return result.value @property def red_primary(self): """(:class:`tuple`) The chromatic red primary point for the image. With ImageMagick-6 the primary value is ``(x, y)`` coordinates; however, ImageMagick-7 has ``(x, y, z)``. .. versionadded:: 0.5.2 """ x = ctypes.c_double(0.0) y = ctypes.c_double(0.0) r = None p = None if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickGetImageRedPrimary(self.wand, x, y) p = (x.value, y.value) else: # pragma: no cover z = ctypes.c_double(0.0) r = library.MagickGetImageRedPrimary(self.wand, x, y, z) p = (x.value, y.value, z.value) if not r: # pragma: no cover self.raise_exception() return p @red_primary.setter def red_primary(self, coordinates): r = None if not isinstance(coordinates, abc.Sequence): raise TypeError('Primary must be a tuple') if MAGICK_VERSION_NUMBER < 0x700: x, y = coordinates r = library.MagickSetImageRedPrimary(self.wand, x, y) else: # pragma: no cover x, y, z = coordinates r = library.MagickSetImageRedPrimary(self.wand, x, y, z) if not r: # pragma: no cover self.raise_exception() @property def rendering_intent(self): """(:class:`basestring`) PNG rendering intent. See :const:`RENDERING_INTENT_TYPES` for valid options. .. versionadded:: 0.5.4 """ ri_index = library.MagickGetImageRenderingIntent(self.wand) return RENDERING_INTENT_TYPES[ri_index] @rendering_intent.setter def rendering_intent(self, value): assertions.string_in_list(RENDERING_INTENT_TYPES, 'wand.image.RENDERING_INTENT_TYPES', rendering_intent=value) ri_index = RENDERING_INTENT_TYPES.index(value) library.MagickSetImageRenderingIntent(self.wand, ri_index) @property def resolution(self): """(:class:`tuple`) Resolution of this image. .. versionadded:: 0.3.0 .. versionchanged:: 0.5.8 Resolution returns a tuple of float values to match ImageMagick's behavior. """ x = ctypes.c_double(0.0) y = ctypes.c_double(0.0) r = library.MagickGetImageResolution(self.wand, x, y) if not r: # pragma: no cover self.raise_exception() return x.value, y.value @resolution.setter @manipulative def resolution(self, geometry): if isinstance(geometry, abc.Sequence): x, y = geometry elif isinstance(geometry, numbers.Real): x, y = geometry, geometry else: raise TypeError('resolution must be a (x, y) pair or a float ' 'of the same x/y') if self.size == (0, 0): r = library.MagickSetResolution(self.wand, x, y) else: r = library.MagickSetImageResolution(self.wand, x, y) if not r: # pragma: no cover self.raise_exception() @property def sampling_factors(self): """(:class:`tuple`) Factors used in sampling data streams. This can be set by given it a string ``"4:2:2"``, or tuple of numbers ``(2, 1, 1)``. However the given string value will be parsed to aspect ratio (i.e. ``"4:2:2"`` internally becomes ``"2,1"``). .. note:: This property is only used by YUV, DPX, & EXR encoders. For JPEG & TIFF set ``"jpeg:sampling-factor"`` on :attr:`Image.options` dictionary:: with Image(filename='input.jpg') as img: img.options['jpeg:sampling-factor'] = '2x1' .. versionadded:: 0.6.3 """ factors_len = ctypes.c_size_t(0) factors = library.MagickGetSamplingFactors(self.wand, ctypes.byref(factors_len)) factors_tuple = tuple(factors[x] for x in xrange(factors_len.value)) factors = library.MagickRelinquishMemory(factors) return factors_tuple @sampling_factors.setter def sampling_factors(self, factors): if isinstance(factors, string_type): geometry_info = GeometryInfo() flags = libmagick.ParseGeometry(binary(factors), ctypes.byref(geometry_info)) if (flags & geometry_info.SigmaValue) == 0: factors = (geometry_info.rho, geometry_info.rho) else: factors = (geometry_info.rho, geometry_info.sigma) elif not isinstance(factors, abc.Sequence): raise TypeError('sampling_factors must be a sequence of real ' 'numbers, not ' + repr(factors)) factors_len = len(factors) factors_ptr = (ctypes.c_double * factors_len)(*factors) library.MagickSetSamplingFactors(self.wand, factors_len, factors_ptr) @property def scene(self): """(:class:`numbers.Integral`) The scene number of the current frame within an animated image. .. versionadded:: 0.5.4 """ return library.MagickGetImageScene(self.wand) @scene.setter def scene(self, value): assertions.assert_unsigned_integer(scene=value) library.MagickSetImageScene(self.wand, value) @property def seed(self): """(:class:`numbers.Integral`) The seed for random number generator. .. warning:: This property is only available with ImageMagick 7.0.8-41, or greater. .. versionadded:: 0.5.5 """ return self._seed @seed.setter def seed(self, value): if library.MagickSetSeed is None: msg = 'Property requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) assertions.assert_unsigned_integer(seed=value) self._seed = value library.MagickSetSeed(self.wand, value) @property def signature(self): """(:class:`str`) The SHA-256 message digest for the image pixel stream. .. versionadded:: 0.1.9 """ sig_str = None sig_p = library.MagickGetImageSignature(self.wand) if sig_p: sig_str = text(ctypes.string_at(sig_p)) sig_p = library.MagickRelinquishMemory(sig_p) return sig_str @property def size(self): """(:class:`tuple`) The pair of (:attr:`width`, :attr:`height`). .. note:: When working with animations, or other layer-based image formats, the :attr:`width` & :attr:`height` properties are referencing the last frame read into the image stack. To get the :attr:`size` of the entire animated images, call :meth:`Image.coalesce() ` method immediately after reading the image. """ return self.width, self.height @property def skewness(self): """(:class:`numbers.Real`) The skewness of the image. .. tip:: If you want both :attr:`kurtosis` & :attr:`skewness`, it would be faster to call :meth:`kurtosis_channel()` directly. .. versionadded:: 0.5.3 """ _, s = self.kurtosis_channel() return s @property def standard_deviation(self): """(:class:`numbers.Real`) The standard deviation of the image. .. tip:: If you want both :attr:`mean` & :attr:`standard_deviation`, it would be faster to call :meth:`mean_channel()` directly. .. versionadded:: 0.5.3 """ _, s = self.mean_channel() return s @property def stroke_color(self): stroke = self.options['stroke'] return Color(stroke) if stroke else None @stroke_color.setter def stroke_color(self, color): if isinstance(color, string_type): color = Color(color) if isinstance(color, Color): self.options['stroke'] = color.string elif color is None: del self.options['stroke'] else: raise TypeError('stroke_color must be a wand.color.Color, not ' + repr(color)) @property def stroke_width(self): strokewidth = self.options['strokewidth'] return float(strokewidth) if strokewidth else None @stroke_width.setter def stroke_width(self, width): assertions.assert_real(stroke_width=width) self.options['strokewidth'] = str(width) @property def ticks_per_second(self): """(:class:`numbers.Integral`) Internal clock for animated images. .. versionadded:: 0.5.4 """ return library.MagickGetImageTicksPerSecond(self.wand) @ticks_per_second.setter def ticks_per_second(self, value): assertions.assert_unsigned_integer(ticks_per_second=value) r = library.MagickSetImageTicksPerSecond(self.wand, value) if not r: # pragma: no cover self.raise_exception() @property def type(self): """(:class:`basestring`) The image type. Defines image type as in :const:`IMAGE_TYPES` enumeration. It may raise :exc:`ValueError` when the type is unknown. .. versionadded:: 0.2.2 """ image_type_index = library.MagickGetImageType(self.wand) if not image_type_index: # pragma: no cover self.raise_exception() return IMAGE_TYPES[text(image_type_index)] @type.setter @manipulative def type(self, image_type): assertions.string_in_list(IMAGE_TYPES, 'wand.image.IMAGE_TYPES', type=image_type) r = library.MagickSetImageType(self.wand, IMAGE_TYPES.index(image_type)) if not r: # pragma: no cover self.raise_exception() @property def units(self): """(:class:`basestring`) The resolution units of this image.""" r = library.MagickGetImageUnits(self.wand) return UNIT_TYPES[text(r)] @units.setter @manipulative def units(self, units): assertions.string_in_list(UNIT_TYPES, 'wand.image.UNIT_TYPES', units=units) r = library.MagickSetImageUnits(self.wand, UNIT_TYPES.index(units)) if not r: # pragma: no cover self.raise_exception() @property def virtual_pixel(self): """(:class:`basestring`) The virtual pixel of image. This can also be set with a value from :const:`VIRTUAL_PIXEL_METHOD` ... versionadded:: 0.4.1 """ method_index = library.MagickGetImageVirtualPixelMethod(self.wand) return VIRTUAL_PIXEL_METHOD[method_index] @virtual_pixel.setter def virtual_pixel(self, method): assertions.string_in_list(VIRTUAL_PIXEL_METHOD, 'wand.image.VIRTUAL_PIXEL_METHOD', virtual_pixel=method) library.MagickSetImageVirtualPixelMethod( self.wand, VIRTUAL_PIXEL_METHOD.index(method) ) @property def wand(self): """Internal pointer to the MagickWand instance. It may raise :exc:`ClosedImageError` when the instance has destroyed already. """ try: return self.resource except DestroyedResourceError: raise ClosedImageError(repr(self) + ' is closed already') @wand.setter def wand(self, wand): try: self.resource = wand except TypeError: raise TypeError(repr(wand) + ' is not a MagickWand instance') @wand.deleter def wand(self): del self.resource @property def width(self): """(:class:`numbers.Integral`) The width of this image.""" return library.MagickGetImageWidth(self.wand) @width.setter @manipulative def width(self, width): assertions.assert_unsigned_integer(width=width) library.MagickSetSize(self.wand, width, self.height) @property def white_point(self): """(:class:`tuple`) The chromatic white point for the image. With ImageMagick-6 the primary value is ``(x, y)`` coordinates; however, ImageMagick-7 has ``(x, y, z)``. .. versionadded:: 0.5.2 """ x = ctypes.c_double(0.0) y = ctypes.c_double(0.0) r = None p = None if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickGetImageWhitePoint(self.wand, x, y) p = (x.value, y.value) else: # pragma: no cover z = ctypes.c_double(0.0) r = library.MagickGetImageWhitePoint(self.wand, x, y, z) p = (x.value, y.value, z.value) if not r: # pragma: no cover self.raise_exception() return p @white_point.setter def white_point(self, coordinates): r = None if not isinstance(coordinates, abc.Sequence): raise TypeError('Primary must be a tuple') if MAGICK_VERSION_NUMBER < 0x700: x, y = coordinates r = library.MagickSetImageWhitePoint(self.wand, x, y) else: # pragma: no cover x, y, z = coordinates r = library.MagickSetImageWhitePoint(self.wand, x, y, z) if not r: # pragma: no cover self.raise_exception() @manipulative def _auto_orient(self): """Fallback for :attr:`auto_orient()` method (which wraps :c:func:`MagickAutoOrientImage`), fixes orientation by checking EXIF data. .. versionadded:: 0.4.1 """ v_ptr = library.MagickGetImageProperty(self.wand, b'exif:orientation') if v_ptr: exif_orientation = ctypes.string_at(v_ptr) v_ptr = library.MagickRelinquishMemory(v_ptr) else: return if not exif_orientation: return orientation_type = ORIENTATION_TYPES[int(exif_orientation)] fn_lookup = { 'undefined': None, 'top_left': None, 'top_right': self.flop, 'bottom_right': functools.partial(self.rotate, degree=180.0), 'bottom_left': self.flip, 'left_top': self.transpose, 'right_top': functools.partial(self.rotate, degree=90.0), 'right_bottom': self.transverse, 'left_bottom': functools.partial(self.rotate, degree=270.0) } fn = fn_lookup.get(orientation_type) if not fn: return fn() self.orientation = 'top_left' def _channel_to_mask(self, value): """Attempts to resolve user input into a :c:type:`ChannelType` bit-mask. User input can be an integer, a string defined in :const:`CHANNELS`, or a string following ImageMagick's `CLI format`__. __ https://imagemagick.org/script/command-line-options.php#channel .. code:: # User generated bit-mask. mask = self._channel_to_mask(CHANNELS['red'] | CHANNELS['green']) # Defined constant. mask = self._channel_to_mask('red') # CLI format. mask = self._channel_to_mask('RGB,Sync') :param value: Mixed user input. :type value: :class:`numbers.Integral` or :class:`basestring` :returns: Bit-mask constant. :rtype: :class:`int` .. versionadded:: 0.5.5 """ mask = -1 if isinstance(value, numbers.Integral) and not isinstance(value, bool): mask = value elif isinstance(value, string_type): if value in CHANNELS: mask = CHANNELS[value] elif libmagick.ParseChannelOption: mask = libmagick.ParseChannelOption(binary(value)) else: raise TypeError(repr(value) + ' is an invalid channel type' '; see wand.image.CHANNELS dictionary') if mask < 0: raise ValueError('expected value from wand.image.CHANNELS, not ' + repr(value)) return mask def _gravity_to_offset(self, gravity, width, height): """Calculate the top/left offset by a given gravity. Some methods in MagickWand's C-API do not respect gravity, but instead, expect a x/y offset. This is confusing to folks coming from the CLI documentation that does respect gravity :param gravity: Value from :const:`GRAVITY_TYPES`. :type gravity: :class:`basestring` :raises: :class:`ValueError` if gravity is no known. :returns: :class:`numbers.Intergal` top, :class:`numbers.Intergal` left .. versionadded:: 0.5.3 """ top, left = 0, 0 assertions.string_in_list(GRAVITY_TYPES, 'wand.image.GRAVITY_TYPES', gravity=gravity) # Set `top` based on given gravity if gravity in ('north_west', 'north', 'north_east'): top = 0 elif gravity in ('west', 'center', 'east'): top = int(self.height / 2) - int(height / 2) elif gravity in ('south_west', 'south', 'south_east'): top = self.height - height # Set `left` based on given gravity if gravity in ('north_west', 'west', 'south_west'): left = 0 elif gravity in ('north', 'center', 'south'): left = int(self.width / 2) - int(width / 2) elif gravity in ('north_east', 'east', 'south_east'): left = self.width - width return top, left @manipulative @trap_exception def adaptive_blur(self, radius=0.0, sigma=0.0, channel=None): """Adaptively blurs the image by decreasing Gaussian as the operator approaches detected edges. :see: Example of :ref:`adaptive_blur`. :param radius: size of gaussian aperture. :type radius: :class:`numbers.Real` :param sigma: Standard deviation of the gaussian filter. :type sigma: :class:`numbers.Real` :param channel: Apply the blur effect on a specific channel. See :const:`CHANNELS`. :type channel: :class:`basestring` .. versionadded:: 0.5.3 .. versionchanged:: 0.5.5 Added optional ``channel`` argument """ assertions.assert_real(radius=radius, sigma=sigma) if channel is None: r = library.MagickAdaptiveBlurImage(self.wand, radius, sigma) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickAdaptiveBlurImageChannel(self.wand, channel_ch, radius, sigma) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickAdaptiveBlurImage(self.wand, radius, sigma) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def adaptive_resize(self, columns=None, rows=None): """Adaptively resize image by applying Mesh interpolation. :param columns: width of resized image. :type columns: :class:`numbers.Integral` :param rows: height of resized image. :type rows: :class:`numbers.Integral` .. versionadded:: 0.5.3 """ if columns is None: columns = self.width if rows is None: rows = self.height assertions.assert_integer(columns=columns, rows=rows) return library.MagickAdaptiveResizeImage(self.wand, columns, rows) @manipulative @trap_exception def adaptive_sharpen(self, radius=0.0, sigma=0.0, channel=None): """Adaptively sharpens the image by sharpening more intensely near image edges and less intensely far from edges. :see: Example of :ref:`adaptive_sharpen`. :param radius: size of gaussian aperture. :type radius: :class:`numbers.Real` :param sigma: Standard deviation of the gaussian filter. :type sigma: :class:`numbers.Real` :param channel: Apply the sharpen effect on a specific channel. See :const:`CHANNELS`. :type channel: :class:`basestring` .. versionadded:: 0.5.3 .. versionchanged:: 0.5.5 Added optional ``channel`` argument """ assertions.assert_real(radius=radius, sigma=sigma) if channel is None: r = library.MagickAdaptiveSharpenImage(self.wand, radius, sigma) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickAdaptiveSharpenImageChannel(self.wand, channel_ch, radius, sigma) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickAdaptiveSharpenImage(self.wand, radius, sigma) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative def adaptive_threshold(self, width, height, offset=0.0): """Applies threshold for each pixel based on neighboring pixel values. :param width: size of neighboring pixels on the X-axis. :type width: :class:`numbers.Integral` :param height: size of neighboring pixels on the Y-axis. :type height: :class:`numbers.Integral` :param offset: normalized number between `0.0` and :attr:`quantum_range`. Forces the pixels to black if values are below ``offset``. :type offset: :class:`numbers.Real` .. versionadded:: 0.5.3 """ assertions.assert_integer(width=width, height=height) assertions.assert_real(offset=offset) if MAGICK_VERSION_NUMBER < 0x700: offset = int(offset) return library.MagickAdaptiveThresholdImage(self.wand, width, height, offset) @manipulative @trap_exception def annotate(self, text, drawing_wand, left=0, baseline=0, angle=0): """Draws text on an image. This method differs from :meth:`caption()` as it uses :class:`~wand.drawing.Drawing` class to manage the font configuration & style context. .. code:: from wand.drawing import Drawing from wand.image import Image with Image(filename='input.jpg') as img: with Drawing() as ctx: ctx.font_family = 'Times New Roman, Nimbus Roman No9' ctx.font_size = 18 ctx.text_decoration = 'underline' ctx.text_kerning = -1 img.annotate('Hello World', ctx, left=20, baseline=50) img.save(filename='output.jpg') :param text: String to annotate on image. :type text: :class:`basestring` :param drawing_wand: Font configuration & style context. :type text: :class:`wand.drawing.Drawing` :param left: X-axis offset of the text baseline. :type left: :class:`numbers.Real` :param baseline: Y-axis offset of the bottom of the text. :type baseline: :class:`numbers.Real` :param angle: Degree rotation to draw text at. :type angle: :class:`numbers.Real` .. versionadded:: 0.5.6 """ from .drawing import Drawing if not isinstance(drawing_wand, Drawing): raise TypeError('drawing_wand must be in instances of ' + 'wand.drawing.Drawing, not ' + repr(drawing_wand)) assertions.assert_real(left=left, baseline=baseline, angle=angle) btext = binary(text) return library.MagickAnnotateImage(self.wand, drawing_wand.resource, left, baseline, angle, btext) @manipulative @trap_exception def auto_gamma(self): """Adjust the gamma level of an image. .. versionadded:: 0.5.4 """ return library.MagickAutoGammaImage(self.wand) @manipulative @trap_exception def auto_level(self): """Scale the minimum and maximum values to a full quantum range. .. versionadded:: 0.5.4 """ return library.MagickAutoLevelImage(self.wand) @manipulative @trap_exception def auto_orient(self): """Adjusts an image so that its orientation is suitable for viewing (i.e. top-left orientation). If available it uses :c:func:`MagickAutoOrientImage` (was added in ImageMagick 6.8.9+) if you have an older magick library, it will use :attr:`_auto_orient()` method for fallback. .. versionadded:: 0.4.1 """ try: return library.MagickAutoOrientImage(self.wand) except AttributeError: # pragma: no cover self._auto_orient() return True @manipulative @trap_exception def auto_threshold(self, method='kapur'): """Automatically performs threshold method to reduce grayscale data down to a binary black & white image. Included algorithms are Kapur, Otsu, and Triangle methods. .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. :param method: Which threshold method to apply. See :const:`AUTO_THRESHOLD_METHODS`. Defaults to ``'kapur'``. :type method: :class:`basestring` :raises WandLibraryVersionError: if function is not available on system's library. .. versionadded:: 0.5.5 """ if library.MagickAutoThresholdImage is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) assertions.string_in_list(AUTO_THRESHOLD_METHODS, 'wand.image.AUTO_THRESHOLD_METHODS', method=method) method_idx = AUTO_THRESHOLD_METHODS.index(method) return library.MagickAutoThresholdImage(self.wand, method_idx) @manipulative @trap_exception def black_threshold(self, threshold): """Forces all pixels above a given color as black. Leaves pixels above threshold unaltered. :param threshold: Color to be referenced as a threshold. :type threshold: :class:`Color` .. versionadded:: 0.5.3 """ if isinstance(threshold, string_type): threshold = Color(threshold) assertions.assert_color(threshold=threshold) with threshold: r = library.MagickBlackThresholdImage(self.wand, threshold.resource) return r @manipulative @trap_exception def blue_shift(self, factor=1.5): """Mutes colors of the image by shifting blue values. :see: Example of :ref:`blue_shift` :param factor: Amount to adjust values. :type factor: :class:`numbers.Real` .. versionadded:: 0.5.3 """ assertions.assert_real(factor=factor) return library.MagickBlueShiftImage(self.wand, factor) @manipulative @trap_exception def blur(self, radius=0.0, sigma=0.0, channel=None): """Blurs the image. Convolve the image with a gaussian operator of the given ``radius`` and standard deviation (``sigma``). For reasonable results, the ``radius`` should be larger than ``sigma``. Use a ``radius`` of 0 and :meth:`blur()` selects a suitable ``radius`` for you. :see: Example of :ref:`blur`. :param radius: the radius of the, in pixels, not counting the center pixel. Default is ``0.0``. :type radius: :class:`numbers.Real` :param sigma: the standard deviation of the, in pixels. Default value is ``0.0``. :type sigma: :class:`numbers.Real` :param channel: Optional color channel to apply blur. See :const:`CHANNELS`. :type channel: :class:`basestring` .. versionadded:: 0.4.5 .. versionchanged:: 0.5.5 Added optional ``channel`` argument. .. versionchanged:: 0.5.7 Positional arguments ``radius`` & ``sigman`` have been converted to key-word arguments. """ assertions.assert_real(radius=radius, sigma=sigma) if channel is None: r = library.MagickBlurImage(self.wand, radius, sigma) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickBlurImageChannel(self.wand, channel_ch, radius, sigma) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickBlurImage(self.wand, radius, sigma) library.MagickSetImageChannelMask(self.wand, mask) return r @trap_exception def border(self, color, width, height, compose="copy"): """Surrounds the image with a border. :param bordercolor: the border color pixel wand :type image: :class:`~wand.color.Color` :param width: the border width :type width: :class:`numbers.Integral` :param height: the border height :type height: :class:`numbers.Integral` :param compose: Use composite operator when applying frame. Only used if called with ImageMagick 7+. :type compose: :class:`basestring` .. versionadded:: 0.3.0 .. versionchanged:: 0.5.0 Added ``compose`` parameter, and ImageMagick 7 support. """ if isinstance(color, string_type): color = Color(color) assertions.assert_color(color=color) with color: if MAGICK_VERSION_NUMBER < 0x700: result = library.MagickBorderImage(self.wand, color.resource, width, height) else: # pragma: no cover assertions.string_in_list(COMPOSITE_OPERATORS, 'wand.image.COMPOSITE_OPERATORS', compose=compose) compose_idx = COMPOSITE_OPERATORS.index(compose) result = library.MagickBorderImage(self.wand, color.resource, width, height, compose_idx) return result @manipulative @trap_exception def brightness_contrast(self, brightness=0.0, contrast=0.0, channel=None): """Converts ``brightness`` & ``contrast`` parameters into a slope & intercept, and applies a polynomial function. :param brightness: between ``-100.0`` and ``100.0``. Default is ``0.0`` for unchanged. :type brightness: :class:`numbers.Real` :param contrast: between ``-100.0`` and ``100.0``. Default is ``0.0`` for unchanged. :type contrast: :class:`numbers.Real` :param channel: Isolate a single color channel to apply contrast. See :const:`CHANNELS`. .. versionadded:: 0.5.4 .. versionchanged:: 0.5.5 Optional ``channel`` argument added. """ assertions.assert_real(brightness=brightness, contrast=contrast) if channel is None: r = library.MagickBrightnessContrastImage(self.wand, brightness, contrast) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickBrightnessContrastImageChannel(self.wand, channel_ch, brightness, contrast) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickBrightnessContrastImage(self.wand, brightness, contrast) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def canny(self, radius=0.0, sigma=1.0, lower_percent=0.1, upper_percent=0.3): """Detect edges by leveraging a multi-stage Canny algorithm. .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. :param radius: Size of gaussian filter. :type radius: :class:`numbers.Real` :param sigma: Standard deviation of gaussian filter. :type sigma: :class:`numbers.Real` :param lower_percent: Normalized lower threshold. Values between ``0.0`` (0%) and ``1.0`` (100%). The default value is ``0.1`` or 10%. :type lower_percent: :class:`numbers.Real` :param upper_percent: Normalized upper threshold. Values between ``0.0`` (0%) and ``1.0`` (100%). The default value is ``0.3`` or 30%. :type upper_percent: :class:`numbers.Real` :raises WandLibraryVersionError: if function is not available on system's library. .. versionadded:: 0.5.5 """ if library.MagickCannyEdgeImage is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) assertions.assert_real(radius=radius, sigma=sigma, lower_percent=lower_percent, upper_percent=upper_percent) return library.MagickCannyEdgeImage(self.wand, radius, sigma, lower_percent, upper_percent) @manipulative def caption(self, text, left=0, top=0, width=None, height=None, font=None, gravity=None): """Writes a caption ``text`` into the position. :param text: text to write :type text: :class:`basestring` :param left: x offset in pixels :type left: :class:`numbers.Integral` :param top: y offset in pixels :type top: :class:`numbers.Integral` :param width: width of caption in pixels. default is :attr:`width` of the image :type width: :class:`numbers.Integral` :param height: height of caption in pixels. default is :attr:`height` of the image :type height: :class:`numbers.Integral` :param font: font to use. default is :attr:`font` of the image :type font: :class:`wand.font.Font` :param gravity: text placement gravity. uses the current :attr:`gravity` setting of the image by default :type gravity: :class:`basestring` .. versionadded:: 0.3.0 """ assertions.assert_integer(left=left, top=top) if font is not None and not isinstance(font, Font): raise TypeError('font must be a wand.font.Font, not ' + repr(font)) if gravity is not None: assertions.string_in_list(GRAVITY_TYPES, 'wand.image.GRAVITY_TYPES', gravity=gravity) if width is None: width = self.width - left else: assertions.assert_integer(width=width) if height is None: height = self.height - top else: assertions.assert_integer(height=height) if font is None: try: font = self.font if font is None: raise TypeError() except TypeError: raise TypeError('font must be specified or existing in image') with Image() as textboard: library.MagickSetSize(textboard.wand, width, height) textboard.font = font textboard.gravity = gravity or self.gravity with Color('transparent') as background_color: library.MagickSetBackgroundColor(textboard.wand, background_color.resource) textboard.read(filename=b'caption:' + text.encode('utf-8')) self.composite(textboard, left, top) def cdl(self, ccc): """Alias for :meth:`color_decision_list`. .. versionadded:: 0.5.7 """ return self.color_decision_list(ccc) @trap_exception def charcoal(self, radius, sigma): """Transform an image into a simulated charcoal drawing. :see: Example of :ref:`charcoal`. :param radius: The size of the Gaussian operator. :type radius: :class:`numbers.Real` :param sigma: The standard deviation of the Gaussian. :type sigma: :class:`numbers.Real` .. versionadded:: 0.5.3 """ assertions.assert_real(radius=radius, sigma=sigma) return library.MagickCharcoalImage(self.wand, radius, sigma) @manipulative @trap_exception def chop(self, width=None, height=None, x=None, y=None, gravity=None): """Removes a region of an image, and reduces the image size accordingly. :param width: Size of region. :type width: :class:`numbers.Integral` :param height: Size of region. :type height: :class:`numbers.Integral` :param x: Offset on the X-axis. :type x: :class:`numbers.Integral` :param y: Offset on the Y-axis. :type y: :class:`numbers.Integral` :param gravity: Helper to auto-calculate offset. See :const:`GRAVITY_TYPES`. :type gravity: :class:`basestring` .. versionadded:: 0.5.5 .. versionchanged:: 0.6.8 Added ``gravity`` argument. .. versionchanged:: 0.6.12 Allow zero values for ``width`` & ``height`` arguments. """ if width is None: width = self.width if height is None: height = self.height assertions.assert_unsigned_integer(width=width, height=height) if gravity is None: if x is None: x = 0 if y is None: y = 0 else: if x is not None or y is not None: raise ValueError('x & y can not be used with gravity.') y, x = self._gravity_to_offset(gravity, width, height) assertions.assert_integer(x=x, y=y) return library.MagickChopImage(self.wand, width, height, x, y) @manipulative @trap_exception def clahe(self, width, height, number_bins, clip_limit): """Contrast limited adaptive histogram equalization. .. warning:: The CLAHE method is only available with ImageMagick-7. :param width: Tile division width. :type width: :class:`numbers.Integral` :param height: Tile division height. :type height: :class:`numbers.Integral` :param number_bins: Histogram bins. :type number_bins: :class:`numbers.Real` :param clip_limit: contrast limit. :type clip_limit: :class:`numbers.Real` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.5 """ if library.MagickCLAHEImage is None: msg = 'CLAHE method not defined in ImageMagick library.' raise WandLibraryVersionError(msg) assertions.assert_unsigned_integer(width=width, height=height) assertions.assert_real(number_bins=number_bins, clip_limit=clip_limit) return library.MagickCLAHEImage(self.wand, width, height, number_bins, clip_limit) @trap_exception def clamp(self, channel=None): """Restrict color values between 0 and quantum range. This is useful when applying arithmetic operations that could result in color values over/under-flowing. :param channel: Optional color channel. :type channel: :class:`basestring` .. versionadded:: 0.5.0 .. versionchanged:: 0.5.5 Added ``channel`` argument. """ if channel is None: r = library.MagickClampImage(self.wand) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickClampImageChannel(self.wand, channel_ch) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickClampImage(self.wand) library.MagickSetImageChannelMask(self.wand, mask) return r def clone(self): """Clones the image. It is equivalent to call :class:`Image` with ``image`` parameter. :: with img.clone() as cloned: # manipulate the cloned image pass :returns: the cloned new image :rtype: :class:`Image` .. versionadded:: 0.1.1 """ return Image(image=self) @manipulative @trap_exception def clut(self, image, method='undefined', channel=None): """Replace color values by referencing another image as a Color Look Up Table. :param image: Color Look Up Table image. :type image: :class:`wand.image.BaseImage` :param method: Pixel Interpolate method. Only available with ImageMagick-7. See :const:`PIXEL_INTERPOLATE_METHODS` :type method: :class:`basestring` :param channel: Optional color channel to target. See :const:`CHANNELS` :type channel: :class:`basestring` .. versionadded:: 0.5.0 .. versionchanged:: 0.5.5 Added optional ``channel`` argument. """ if not isinstance(image, BaseImage): raise TypeError('image must be a base image, not ' + repr(image)) if MAGICK_VERSION_NUMBER < 0x700: if channel is None: r = library.MagickClutImage(self.wand, image.wand) else: channel_ch = self._channel_to_mask(channel) r = library.MagickClutImageChannel(self.wand, channel_ch, image.wand) else: # pragma: no cover assertions.string_in_list(PIXEL_INTERPOLATE_METHODS, 'wand.image.PIXEL_INTERPOLATE_METHODS', pixel_interpolate_method=method) method_idx = PIXEL_INTERPOLATE_METHODS.index(method) if channel is None: r = library.MagickClutImage(self.wand, image.wand, method_idx) else: channel_ch = self._channel_to_mask(channel) mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickClutImage(self.wand, image.wand, method_idx) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def coalesce(self): """Rebuilds image sequence with each frame size the same as first frame, and composites each frame atop of previous. .. note:: Only affects GIF, and other formats with multiple pages/layers. .. versionadded:: 0.5.0 """ r = library.MagickCoalesceImages(self.wand) if r: self.wand = r self.reset_sequence() return bool(r) @manipulative @trap_exception def color_decision_list(self, ccc): """Applies color correction from a Color Correction Collection (CCC) xml string. An example of xml: .. code-block:: xml 0.9 1.2 0.5 0.4 -0.5 0.6 1.0 0.8 1.5 0.85 :param ccc: A XML string of the CCC contents. :type ccc: :class:`basestring` .. versionadded:: 0.5.7 """ return library.MagickColorDecisionListImage(self.wand, binary(ccc)) def color_map(self, index, color=None): """Get & Set a color at a palette index. If ``color`` is given, the color at the index location will be set & returned. Omitting the ``color`` argument will only return the color value at index. Valid indexes are between ``0`` and total :attr:`colors` of the image. .. note:: Ensure the image type is set to ``'palette'`` before calling the :meth:`color_map` method. For example:: with Image(filename='graph.png') as img: img.type = 'palette' palette = [img.color_map(idx) for idx in range(img.colors)] # ... :param index: The color position of the image palette. :type index: :class:`numbers.Integral` :param color: Optional color to _set_ at the given index. :type color: :class:`wand.color.Color` :returns: Color at index. :rtype: :class:`wand.color.Color` .. versionadded:: 0.5.3 """ if not isinstance(index, numbers.Integral): raise TypeError('index most be an integer, not ' + repr(index)) if index < 0 or index >= self.colors: raise ValueError('index is out of palette range') if color: if isinstance(color, string_type): color = Color(color) if not isinstance(color, Color): raise TypeError('expecting in instance of Color, not ' + repr(color)) with color: r = library.MagickSetImageColormapColor(self.wand, index, color.resource) if not r: # pragma: no cover self.raise_exception() else: color_ptr = library.NewPixelWand() r = library.MagickGetImageColormapColor(self.wand, index, color_ptr) if not r: # pragma: no cover color_ptr = library.DestroyPixelWand(color_ptr) self.raise_exception() color = Color.from_pixelwand(color_ptr) color_ptr = library.DestroyPixelWand(color_ptr) return color @manipulative @trap_exception def color_matrix(self, matrix): """Adjust color values by applying a matrix transform per pixel. Matrix should be given as 2D list, with a max size of 6x6. An example of 3x3 matrix:: matrix = [ [1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0], ] Which would translate RGB color channels by calculating the following: .. math:: \\begin{aligned} red' &= 1.0 * red + 0.0 * green + 0.0 * blue\\\\ green' &= 0.0 * red + 1.0 * green + 0.0 * blue\\\\ blue' &= 0.0 * red + 0.0 * green + 1.0 * blue\\\\ \\end{aligned} For RGB colorspace images, the rows & columns are laid out as: +---------+-----+-------+------+------+-------+--------+ | | Red | Green | Blue | n/a | Alpha | Offset | +=========+=====+=======+======+======+=======+========+ | Red' | 1 | 0 | 0 | 0 | 0 | 0 | +---------+-----+-------+------+------+-------+--------+ | Green' | 0 | 1 | 0 | 0 | 0 | 0 | +---------+-----+-------+------+------+-------+--------+ | Blue' | 0 | 0 | 1 | 0 | 0 | 0 | +---------+-----+-------+------+------+-------+--------+ | n/a | 0 | 0 | 0 | 0 | 0 | 0 | +---------+-----+-------+------+------+-------+--------+ | Alpha' | 0 | 0 | 0 | 0 | 0 | 0 | +---------+-----+-------+------+------+-------+--------+ | Offset' | 0 | 0 | 0 | 0 | 0 | 0 | +---------+-----+-------+------+------+-------+--------+ Or for a CMYK colorspace image: +----------+------+--------+---------+-------+-------+--------+ | | Cyan | Yellow | Magenta | Black | Alpha | Offset | +==========+======+========+=========+=======+=======+========+ | Cyan' | 1 | 0 | 0 | 0 | 0 | 0 | +----------+------+--------+---------+-------+-------+--------+ | Yellow' | 0 | 1 | 0 | 0 | 0 | 0 | +----------+------+--------+---------+-------+-------+--------+ | Magenta' | 0 | 0 | 1 | 0 | 0 | 0 | +----------+------+--------+---------+-------+-------+--------+ | Black' | 0 | 0 | 0 | 1 | 0 | 0 | +----------+------+--------+---------+-------+-------+--------+ | Alpha' | 0 | 0 | 0 | 0 | 0 | 0 | +----------+------+--------+---------+-------+-------+--------+ | Offset' | 0 | 0 | 0 | 0 | 0 | 0 | +----------+------+--------+---------+-------+-------+--------+ See `color-matrix`__ for examples. __ https://www.imagemagick.org/Usage/color_mods/#color-matrix :see: Example of :ref:`color_matrix`. :param matrix: 2D List of doubles. :type matrix: :class:`collections.abc.Sequence` .. versionadded:: 0.5.3 """ if not isinstance(matrix, abc.Sequence): raise TypeError('matrix must be a sequence, not ' + repr(matrix)) rows = len(matrix) columns = None values = [] for row in matrix: if not isinstance(row, abc.Sequence): raise TypeError('nested row must be a sequence, not ' + repr(row)) if columns is None: columns = len(row) elif columns != len(row): raise ValueError('rows have different column length') for column in row: values.append(str(column)) kernel = binary('{0}x{1}:{2}'.format(columns, rows, ','.join(values))) exception_info = libmagick.AcquireExceptionInfo() if MAGICK_VERSION_NUMBER < 0x700: kernel_info = libmagick.AcquireKernelInfo(kernel) else: # pragma: no cover kernel_info = libmagick.AcquireKernelInfo(kernel, exception_info) exception_info = libmagick.DestroyExceptionInfo(exception_info) r = library.MagickColorMatrixImage(self.wand, kernel_info) kernel_info = libmagick.DestroyKernelInfo(kernel_info) return r @manipulative @trap_exception def color_threshold(self, start=None, stop=None): """Forces all pixels in color range to white, and all other pixels to black. .. note:: This method is only works with ImageMagick-7.0.10, or later. :param start: Color to begin color range. :type start: :class:`wand.color.Color` :param stop: Color to end color range. :type stop: :class:`wand.color.Color` .. versionadded:: 0.6.4 """ if isinstance(start, string_type): start = Color(start) if isinstance(stop, string_type): stop = Color(stop) assertions.assert_color(start=start, stop=stop) if library.MagickColorThresholdImage is None: msg = 'Method "color_threshold" not available.' raise WandLibraryVersionError(msg) with start: with stop: r = library.MagickColorThresholdImage(self.wand, start.resource, stop.resource) return r @manipulative @trap_exception def colorize(self, color=None, alpha=None): """Blends a given fill color over the image. The amount of blend is determined by the color channels given by the ``alpha`` argument. :see: Example of :ref:`colorize`. :param color: Color to paint image with. :type color: :class:`wand.color.Color` :param alpha: Defines how to blend color. :type alpha: :class:`wand.color.Color` .. versionadded:: 0.5.3 """ if isinstance(color, string_type): color = Color(color) if isinstance(alpha, string_type): alpha = Color(alpha) assertions.assert_color(color=color, alpha=alpha) with color: with alpha: r = library.MagickColorizeImage(self.wand, color.resource, alpha.resource) return r @manipulative @trap_exception def combine(self, channel='rgb_channels', colorspace='rgb'): """Creates an image where each color channel is assigned by a grayscale image in a sequence. .. warning:: If your using ImageMagick-6, use ``channel`` argument to control the color-channel order. With ImageMagick-7, the ``channel`` argument has been replaced with ``colorspace``. For example:: for wand.image import Image with Image() as img: img.read(filename='red_channel.png') img.read(filename='green_channel.png') img.read(filename='blue_channel.png') img.combine(colorspace='rgb') img.save(filename='output.png') :param channel: Determines the colorchannel ordering of the sequence. Only used for ImageMagick-6. See :const:`CHANNELS`. :type channel: :class:`basestring` :param colorspace: Determines the colorchannel ordering of the sequence. Only used for ImageMagick-7. See :const:`COLORSPACE_TYPES`. :type colorspace: :class:`basestring` .. versionadded:: 0.5.9 """ assertions.string_in_list(COLORSPACE_TYPES, 'wand.image.COLORSPACE_TYPES', colorspace=colorspace) library.MagickResetIterator(self.wand) colorspace_c = COLORSPACE_TYPES.index(colorspace) channel_c = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: new_wand = library.MagickCombineImages(self.wand, channel_c) else: # pragma: no-cover new_wand = library.MagickCombineImages(self.wand, colorspace_c) if new_wand: self.wand = new_wand self.reset_sequence() return bool(new_wand) @manipulative def compare(self, image, metric='undefined', highlight=None, lowlight=None): """Compares an image with another, and returns a reconstructed image & computed distortion. The reconstructed image will show the differences colored with ``highlight``, and similarities with ``lowlight``. If you need the computed distortion between to images without a image being reconstructed, use :meth:`get_image_distortion()` method. Set :attr:`fuzz` property to adjust pixel-compare thresholds. For example:: from wand.image import Image with Image(filename='input.jpg') as base: with Image(filename='subject.jpg') as img: base.fuzz = base.quantum_range * 0.20 # Threshold of 20% result_image, result_metric = base.compare(img) with result_image: result_image.save(filename='diff.jpg') :param image: The reference image :type image: :class:`wand.image.Image` :param metric: The metric type to use for comparing. See :const:`COMPARE_METRICS` :type metric: :class:`basestring` :param highlight: Set the color of the delta pixels in the resulting difference image. :type highlight: :class:`~wand.color.Color` or :class:`basestring` :param lowlight: Set the color of the similar pixels in the resulting difference image. :type lowlight: :class:`~wand.color.Color` or :class:`basestring` :returns: The difference image(:class:`wand.image.Image`), the computed distortion between the images (:class:`numbers.Real`) :rtype: :class:`tuple` ( :class:`Image`, :class:`numbers.Real` ) .. versionadded:: 0.4.3 .. versionchanged:: 0.5.3 Added support for ``highlight`` & ``lowlight``. """ assertions.string_in_list(COMPARE_METRICS, 'wand.image.COMPARE_METRICS', metric=metric) if highlight: if isinstance(highlight, Color): highlight = highlight.string library.MagickSetImageArtifact(self.wand, b'compare:highlight-color', binary(highlight)) if lowlight: if isinstance(lowlight, Color): lowlight = lowlight.string library.MagickSetImageArtifact(self.wand, b'compare:lowlight-color', binary(lowlight)) metric = COMPARE_METRICS.index(metric) distortion = ctypes.c_double(0.0) compared_image = library.MagickCompareImages(self.wand, image.wand, metric, ctypes.byref(distortion)) return Image(BaseImage(compared_image)), distortion.value @manipulative def complex(self, operator='undefined', snr=None): """Performs `complex`_ mathematics against two images in a sequence, and generates a new image with two results. .. seealso:: :meth:`forward_fourier_transform` & :meth:`inverse_fourier_transform` .. code:: from wand.image import Image with Image(filename='real_part.png') as imgA: with Image(filename='imaginary_part.png') as imgB: imgA.sequence.append(imgB) with imgA.complex('conjugate') as results: results.save(filename='output-%02d.png') .. _complex: https://en.wikipedia.org/wiki/Complex_number .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. :param operator: Define which mathematic operator to perform. See :const:`COMPLEX_OPERATORS`. :type operator: :class:`basestring` :param snr: Optional ``SNR`` parameter for ``'divide'`` operator. :type snr: :class:`basestring` :raises WandLibraryVersionError: If ImageMagick library does not support this function. .. versionadded:: 0.5.5 """ if library.MagickComplexImages is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) assertions.string_in_list(COMPLEX_OPERATORS, 'wand.image.COMPLEX_OPERATORS', operator=operator) if snr is not None: key = b'complex:snr=float' val = to_bytes(snr) library.MagickSetImageArtifact(self.wand, key, val) operator_idx = COMPLEX_OPERATORS.index(operator) wand = library.MagickComplexImages(self.wand, operator_idx) if not bool(wand): self.raise_exception() return Image(BaseImage(wand)) @trap_exception def composite(self, image, left=None, top=None, operator='over', arguments=None, gravity=None): """Places the supplied ``image`` over the current image, with the top left corner of ``image`` at coordinates ``left``, ``top`` of the current image. The dimensions of the current image are not changed. :param image: the image placed over the current image :type image: :class:`wand.image.Image` :param left: the x-coordinate where `image` will be placed :type left: :class:`numbers.Integral` :param top: the y-coordinate where `image` will be placed :type top: :class:`numbers.Integral` :param operator: the operator that affects how the composite is applied to the image. available values can be found in the :const:`COMPOSITE_OPERATORS` list. Default is ``'over'``. :type operator: :class:`basestring` :param arguments: Additional numbers given as a geometry string, or comma delimited values. This is needed for ``'blend'``, ``'displace'``, ``'dissolve'``, and ``'modulate'`` operators. :type arguments: :class:`basestring` :param gravity: Calculate the ``top`` & ``left`` values based on gravity value from :const:`GRAVITY_TYPES`. :type: gravity: :class:`basestring` .. versionadded:: 0.2.0 .. versionchanged:: 0.5.3 The operator can be set, as well as additional composite arguments. .. versionchanged:: 0.5.3 Optional ``gravity`` argument was added. """ if top is None and left is None: if gravity is None: gravity = self.gravity top, left = self._gravity_to_offset(gravity, image.width, image.height) elif gravity is not None: raise TypeError('Can not use gravity if top & left are given') elif top is None: top = 0 elif left is None: left = 0 assertions.assert_integer(left=left, top=top) try: op = COMPOSITE_OPERATORS.index(operator) except IndexError: raise ValueError(repr(operator) + ' is an invalid composite ' 'operator type; see wand.image.COMPOSITE_' 'OPERATORS dictionary') if arguments: assertions.assert_string(arguments=arguments) r = library.MagickSetImageArtifact(image.wand, binary('compose:args'), binary(arguments)) if not r: self.raise_exception() r = library.MagickSetImageArtifact(self.wand, binary('compose:args'), binary(arguments)) if not r: # pragma: no cover self.raise_exception() if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickCompositeImage(self.wand, image.wand, op, int(left), int(top)) else: # pragma: no cover r = library.MagickCompositeImage(self.wand, image.wand, op, True, int(left), int(top)) return r @manipulative @trap_exception def composite_channel(self, channel, image, operator, left=None, top=None, arguments=None, gravity=None): """Composite two images using the particular ``channel``. :param channel: the channel type. available values can be found in the :const:`CHANNELS` mapping :param image: the composited source image. (the receiver image becomes the destination) :type image: :class:`Image` :param operator: the operator that affects how the composite is applied to the image. available values can be found in the :const:`COMPOSITE_OPERATORS` list :type operator: :class:`basestring` :param left: the column offset of the composited source image :type left: :class:`numbers.Integral` :param top: the row offset of the composited source image :type top: :class:`numbers.Integral` :param arguments: Additional numbers given as a geometry string, or comma delimited values. This is needed for ``'blend'``, ``'displace'``, ``'dissolve'``, and ``'modulate'`` operators. :type arguments: :class:`basestring` :param gravity: Calculate the ``top`` & ``left`` values based on gravity value from :const:`GRAVITY_TYPES`. :type: gravity: :class:`basestring` :raises ValueError: when the given ``channel`` or ``operator`` is invalid .. versionadded:: 0.3.0 .. versionchanged:: 0.5.3 Support for optional composite arguments has been added. .. versionchanged:: 0.5.3 Optional ``gravity`` argument was added. """ assertions.assert_string(operator=operator) ch_const = self._channel_to_mask(channel) if gravity: if left is None and top is None: top, left = self._gravity_to_offset(gravity, image.width, image.height) else: raise TypeError('Can not use gravity if top & left are given') if top is None: top = 0 if left is None: left = 0 assertions.assert_integer(left=left, top=top) try: op = COMPOSITE_OPERATORS.index(operator) except IndexError: raise IndexError(repr(operator) + ' is an invalid composite ' 'operator type; see wand.image.COMPOSITE_' 'OPERATORS dictionary') if arguments: assertions.assert_string(arguments=arguments) library.MagickSetImageArtifact(image.wand, binary('compose:args'), binary(arguments)) library.MagickSetImageArtifact(self.wand, binary('compose:args'), binary(arguments)) if library.MagickCompositeImageChannel: r = library.MagickCompositeImageChannel(self.wand, ch_const, image.wand, op, int(left), int(top)) else: # pragma: no cover ch_mask = library.MagickSetImageChannelMask(self.wand, ch_const) r = library.MagickCompositeImage(self.wand, image.wand, op, True, int(left), int(top)) library.MagickSetImageChannelMask(self.wand, ch_mask) return r @manipulative @trap_exception def concat(self, stacked=False): """Concatenates images in stack into a single image. Left-to-right by default, top-to-bottom if ``stacked`` is True. :param stacked: stack images in a column, or in a row (default) :type stacked: :class:`bool` .. versionadded:: 0.5.0 """ assertions.assert_bool(stacked=stacked) r = library.MagickAppendImages(self.wand, stacked) if r: self.wand = r self.reset_sequence() return bool(r) def connected_components(self, **kwargs): """Evaluates binary image, and groups connected pixels into objects. This method will also return a list of :class:`ConnectedComponentObject` instances that will describe an object's features. .. code:: from wand.image import Image with Image(filename='objects.gif') as img: objects = img.connected_components() for cc_obj in objects: print("{0._id}: {0.size} {0.offset}".format(cc_obj)) #=> 0: (256, 171) (0, 0) #=> 2: (120, 135) (104, 18) #=> 3: (50, 36) (129, 44) #=> 4: (21, 23) (0, 45) #=> 1: (4, 10) (252, 0) .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. .. tip:: Set :attr:`fuzz` property to increase pixel matching by reducing tolerance of color-value comparisons:: from wand.image import Image from wand.version import QUANTUM_RANGE with Image(filename='objects.gif') as img: img.fuzz = 0.1 * QUANTUM_RANGE # 10% objects = img.connected_components() :param angle_threshold: Optional argument that merges any region with an equivalent ellipse smaller than a given value. Requires ImageMagick-7.0.9-24, or greater. :type angle_threshold: :class:`basestring` :param area_threshold: Optional argument to merge objects under an area size. :type area_threshold: :class:`basestring` :param background_id: Optional argument to identify which object should be the background. Requires ImageMagick-7.0.9-24, or greater. :type background_id: :class:`basestring` :param circularity_threshold: Optional argument that merges any region smaller than value defined as: ``4*pi*area/perimeter^2``. Requires ImageMagick-7.0.9-24, or greater. :type circularity_threshold: :class:`basestring` :param connectivity: Either ``4``, or ``8``. A value of ``4`` will evaluate each pixels top-bottom, & left-right neighbors. A value of ``8`` will use the same pixels as with ``4``, but will also include the four corners of each pixel. Default value of ``4``. :type connectivity: :class:`numbers.Integral` :param diameter_threshold: Optional argument to merge any region under a given value. A region is defined as: ``sqr(4*area/pi)``. Requires ImageMagick-7.0.9-24. :type diameter_threshold: :class:`basestring` :param eccentricity_threshold: Optional argument to merge any region with ellipse eccentricity under a given value. Requires ImageMagick-7.0.9-24, or greater. :param keep: Comma separated list of object IDs to isolate, the reset are converted to transparent. :type keep: :class:`basestring` :param keep_colors: Semicolon separated list of objects to keep by their color value. Requires ImageMagick-7.0.9-24, or greater. :type keep_colors: :class:`basestring` :param keep_top: Keeps only the top number of objects by area. Requires ImageMagick-7.0.9-24, or greater. :type keep_top: :class:`basestring` :param major_axis_threshold: Optional argument to merge any ellipse with a major axis smaller then given value. Requires ImageMagick-7.0.9-24, or greater. :type major_axis_threshold: :class:`basestring` :param mean_color: Optional argument. Replace object color with mean color of the source image. :type mean_color: :class:`bool` :param minor_axis_threshold: Optional argument to merge any ellipse with a minor axis smaller then given value. Requires ImageMagick-7.0.9-24, or greater. :type minor_axis_threshold: :class:`basestring` :param perimeter_threshold: Optional argument to merge any region with a perimeter smaller than the given value. Requires ImageMagick-7.0.9-24, or greater. :param remove: Comma separated list of object IDs to ignore, and convert to transparent. :type remove: :class:`basestring` :param remove_colors: Semicolon separated list of objects to remove by there color. Requires ImageMagick-7.0.9-24, or greater. :type remove_colors: :class:`basestring` :returns: A list of :class:`ConnectedComponentObject`. :rtype: :class:`list` [:class:`ConnectedComponentObject`] :raises WandLibraryVersionError: If ImageMagick library does not support this method. .. versionadded:: 0.5.5 .. versionchanged:: 0.5.6 Added ``mean_color``, ``keep``, & ``remove`` optional arguments. .. versionchanged:: 0.6.4 Added ``angle_threshold``, ``circularity_threshold``, ``diameter_threshold``, ``eccentricity_threshold``, ``keep_colors``, ``major_axis_threshold``, ``minor_axis_threshold``, ``perimeter_threshold``, and ``remove_colors`` optional arguments. """ angle_threshold = kwargs.get('angle_threshold', None) area_threshold = kwargs.get('area_threshold', None) background_id = kwargs.get('background_id', None) circularity_threshold = kwargs.get('circularity_threshold', None) connectivity = kwargs.get('connectivity', 4) diameter_threshold = kwargs.get('diameter_threshold', None) eccentricity_threshold = kwargs.get('eccentricity_threshold', None) keep = kwargs.get('keep', None) keep_colors = kwargs.get('keep_colors', None) keep_top = kwargs.get('keep_top', None) major_axis_threshold = kwargs.get('major_axis_threshold', None) mean_color = kwargs.get('mean_color', False) minor_axis_threshold = kwargs.get('minor_axis_threshold', None) perimeter_threshold = kwargs.get('perimeter_threshold', None) remove = kwargs.get('remove', None) remove_colors = kwargs.get('remove_colors', None) if library.MagickConnectedComponentsImage is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) if connectivity not in (4, 8): raise ValueError('connectivity must be 4, or 8.') if angle_threshold is not None: key = b'connected-components:angle-threshold' val = to_bytes(angle_threshold) library.MagickSetImageArtifact(self.wand, key, val) if area_threshold is not None: key = b'connected-components:area-threshold' val = to_bytes(area_threshold) library.MagickSetImageArtifact(self.wand, key, val) if background_id is not None: key = b'connected-components:background-id' val = to_bytes(background_id) library.MagickSetImageArtifact(self.wand, key, val) if circularity_threshold is not None: key = b'connected-components:circularity-threshold' val = to_bytes(circularity_threshold) library.MagickSetImageArtifact(self.wand, key, val) if diameter_threshold is not None: key = b'connected-components:diameter-threshold' val = to_bytes(diameter_threshold) library.MagickSetImageArtifact(self.wand, key, val) if eccentricity_threshold is not None: key = b'connected-components:eccentricity-threshold' val = to_bytes(eccentricity_threshold) library.MagickSetImageArtifact(self.wand, key, val) if keep is not None: key = b'connected-components:keep' val = to_bytes(keep) library.MagickSetImageArtifact(self.wand, key, val) if keep_colors is not None: key = b'connected-components:keep-colors' val = to_bytes(keep_colors) library.MagickSetImageArtifact(self.wand, key, val) if keep_top is not None: key = b'connected-components:keep-top' val = to_bytes(keep_top) library.MagickSetImageArtifact(self.wand, key, val) if major_axis_threshold is not None: key = b'connected-components:major-axis-threshold' val = to_bytes(major_axis_threshold) library.MagickSetImageArtifact(self.wand, key, val) if mean_color: key = b'connected-components:mean-color' val = b'true' library.MagickSetImageArtifact(self.wand, key, b'true') if minor_axis_threshold is not None: key = b'connected-components:minor-axis-threshold' val = to_bytes(minor_axis_threshold) library.MagickSetImageArtifact(self.wand, key, val) if perimeter_threshold is not None: key = b'connected-components:perimeter-threshold' val = to_bytes(perimeter_threshold) library.MagickSetImageArtifact(self.wand, key, val) if remove is not None: key = b'connected-components:remove' val = to_bytes(remove) library.MagickSetImageArtifact(self.wand, key, val) if remove_colors is not None: key = b'connected-components:remove-colors' val = to_bytes(remove_colors) library.MagickSetImageArtifact(self.wand, key, val) objects_ptr = ctypes.c_void_p(0) CCObjectInfoStructure = CCObjectInfo if MAGICK_VERSION_NUMBER > 0x70B: CCObjectInfoStructure = CCObjectInfo710 elif MAGICK_VERSION_NUMBER > 0x709: CCObjectInfoStructure = CCObjectInfo70A ccoi_mem_size = ctypes.sizeof(CCObjectInfoStructure) r = library.MagickConnectedComponentsImage(self.wand, connectivity, ctypes.byref(objects_ptr)) objects = [] if r and objects_ptr.value: for i in xrange(self.colors): temp = CCObjectInfoStructure() src_addr = objects_ptr.value + (i * ccoi_mem_size) ctypes.memmove(ctypes.addressof(temp), src_addr, ccoi_mem_size) objects.append(ConnectedComponentObject(temp)) del temp objects_ptr = libmagick.RelinquishMagickMemory(objects_ptr) else: self.raise_exception() return objects @manipulative @trap_exception def contrast(self, sharpen=True): """Enhances the difference between lighter & darker values of the image. Set ``sharpen`` to ``False`` to reduce contrast. :param sharpen: Increase, or decrease, contrast. Default is ``True`` for increased contrast. :type sharpen: :class:`bool` .. versionadded:: 0.5.7 """ assertions.assert_bool(sharpen=sharpen) return library.MagickContrastImage(self.wand, sharpen) @manipulative @trap_exception def contrast_stretch(self, black_point=0.0, white_point=None, channel=None): """Enhance contrast of image by adjusting the span of the available colors. :param black_point: black point between 0.0 and 1.0. default is 0.0 :type black_point: :class:`numbers.Real` :param white_point: white point between 0.0 and 1.0. Defaults to the same value given to the ``black_point`` argument. :type white_point: :class:`numbers.Real` :param channel: optional color channel to apply contrast stretch :type channel: :const:`CHANNELS` :raises ValueError: if ``channel`` is not in :const:`CHANNELS` .. versionadded:: 0.4.1 .. versionchanged:: 0.5.5 The ``white_point`` argument will now default to the value given by the ``black_point`` argument. """ assertions.assert_real(black_point=black_point) # If only black-point is given, match CLI behavior by # calculating white point if white_point is None: white_point = black_point assertions.assert_real(white_point=white_point) contrast_range = float(self.width * self.height) if 0.0 < black_point <= 1.0: black_point *= contrast_range if 0.0 < white_point <= 1.0: white_point *= contrast_range white_point = contrast_range - white_point if channel is None: r = library.MagickContrastStretchImage(self.wand, black_point, white_point) else: ch_const = self._channel_to_mask(channel) if library.MagickContrastStretchImageChannel: r = library.MagickContrastStretchImageChannel(self.wand, ch_const, black_point, white_point) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_const) r = library.MagickContrastStretchImage(self.wand, black_point, white_point) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return r def convex_hull(self, background=None): """Find the smallest convex polygon, and returns a list of points. .. note:: Requires ImageMagick-7.0.10 or greater. You can pass the list of points directly to :meth:`Drawing.polygon() ` method to draw the convex hull shape on the image. .. code:: from wand.image import Image from wand.drawing import Drawing with Image(filename='kdf_black.png') as img: points = img.convex_hull() with Drawing() as ctx: ctx.fill_color = 'transparent' ctx.stroke_color = 'red' ctx.polygon(points=points) ctx(img) img.save(filename='kdf_black_convex_hull.png') .. image:: ../_images/wand/image/kdf_black.png .. image:: ../_images/wand/image/kdf_black_convex_hull.png :param background: Define which color value to evaluate as the background. :type background: :class:`basestring` or :class:`~wand.color.Color` :returns: list of points :rtype: :class:`list` [ :class:`tuple` ( :class:`float`, :class:`float` ) ] .. versionadded:: 0.6.4 """ r = [] if MAGICK_VERSION_NUMBER < 0x70A: msg = 'ImageMagick-7.0.10 is required to use convex_hull().' raise WandLibraryVersionError(msg) with self.clone() as tmp: if background is not None: if isinstance(background, Color): background = background.string assertions.assert_string(background=background) key = b'convex-hull:background-color' val = to_bytes(background) library.MagickSetImageArtifact(tmp.wand, key, val) library.MagickSetOption(tmp.wand, b'format', b'%[convex-hull]') library.MagickSetImageFormat(tmp.wand, b'INFO') length = ctypes.c_size_t() blob_p = library.MagickGetImageBlob(tmp.wand, ctypes.byref(length)) if blob_p: blob = ctypes.string_at(blob_p, length.value) blob_p = library.MagickRelinquishMemory(blob_p) pts = blob.decode('ascii', 'ignore').strip().split(' ') r = [tuple(map(lambda x: float(x), p.split(','))) for p in pts] else: self.raise_exception() return r @manipulative @trap_exception def crop(self, left=0, top=0, right=None, bottom=None, width=None, height=None, reset_coords=True, gravity=None): """Crops the image in-place. .. sourcecode:: text +--------------------------------------------------+ | ^ ^ | | | | | | top | | | | | | | v | | | <-- left --> +-------------------+ bottom | | | ^ | | | | | <-- width --|---> | | | | | height | | | | | | | | | | | v | | | | +-------------------+ v | | <--------------- right ----------> | +--------------------------------------------------+ :param left: x-offset of the cropped image. default is 0 :type left: :class:`numbers.Integral` :param top: y-offset of the cropped image. default is 0 :type top: :class:`numbers.Integral` :param right: second x-offset of the cropped image. default is the :attr:`width` of the image. this parameter and ``width`` parameter are exclusive each other :type right: :class:`numbers.Integral` :param bottom: second y-offset of the cropped image. default is the :attr:`height` of the image. this parameter and ``height`` parameter are exclusive each other :type bottom: :class:`numbers.Integral` :param width: the :attr:`width` of the cropped image. default is the :attr:`width` of the image. this parameter and ``right`` parameter are exclusive each other :type width: :class:`numbers.Integral` :param height: the :attr:`height` of the cropped image. default is the :attr:`height` of the image. this parameter and ``bottom`` parameter are exclusive each other :type height: :class:`numbers.Integral` :param reset_coords: optional flag. If set, after the rotation, the coordinate frame will be relocated to the upper-left corner of the new image. By default is `True`. :type reset_coords: :class:`bool` :param gravity: optional flag. If set, will calculate the :attr:`top` and :attr:`left` attributes. This requires both :attr:`width` and :attr:`height` parameters to be included. :type gravity: :const:`GRAVITY_TYPES` :raises ValueError: when one or more arguments are invalid .. note:: If you want to crop the image but not in-place, use slicing operator. .. versionchanged:: 0.4.1 Added ``gravity`` option. Using ``gravity`` along with ``width`` & ``height`` to auto-adjust ``left`` & ``top`` attributes. .. versionchanged:: 0.1.8 Made to raise :exc:`~exceptions.ValueError` instead of :exc:`~exceptions.IndexError` for invalid ``width``/``height`` arguments. .. versionadded:: 0.1.7 """ if not (right is None or width is None): raise TypeError('parameters right and width are exclusive each ' 'other; use one at a time') elif not (bottom is None or height is None): raise TypeError('parameters bottom and height are exclusive each ' 'other; use one at a time') def abs_(n, m, null=None): if n is None: return m if null is None else null elif not isinstance(n, numbers.Integral): raise TypeError('expected integer, not ' + repr(n)) elif n > m: raise ValueError(repr(n) + ' > ' + repr(m)) return m + n if n < 0 else n # Define left & top if gravity is given. if gravity: if width is None or height is None: raise TypeError( 'both width and height must be defined with gravity' ) top, left = self._gravity_to_offset(gravity, width, height) else: left = abs_(left, self.width, 0) top = abs_(top, self.height, 0) if width is None: right = abs_(right, self.width) width = right - left if height is None: bottom = abs_(bottom, self.height) height = bottom - top assertions.assert_counting_number(width=width, height=height) if ( left == top == 0 and width == self.width and height == self.height ): return True if self.animation: self.wand = library.MagickCoalesceImages(self.wand) self.reset_sequence() library.MagickSetLastIterator(self.wand) n = library.MagickGetIteratorIndex(self.wand) library.MagickResetIterator(self.wand) for i in xrange(0, n + 1): library.MagickSetIteratorIndex(self.wand, i) r = library.MagickCropImage(self.wand, width, height, left, top) if reset_coords: self.reset_coords() else: r = library.MagickCropImage(self.wand, width, height, left, top) if reset_coords: self.reset_coords() return r @trap_exception def cycle_color_map(self, offset=1): """Shift the image color-map by a given offset. :param offset: number of steps to rotate index by. :type offset: :class:`numbers.Integral` .. versionadded:: 0.5.3 """ assertions.assert_integer(offset=offset) return library.MagickCycleColormapImage(self.wand, offset) @manipulative @trap_exception def decipher(self, passphrase): """Decrypt ciphered pixels into original values. .. note:: :class:`~wand.exceptions.ImageError` will be thrown if the system's ImageMagick library was compiled without cipher support. :param passphrase: the secret passphrase to decrypt with. :type passphrase: :class:`basestring` .. versionadded:: 0.6.3 """ assertions.assert_string(passphrase=passphrase) return library.MagickDecipherImage(self.wand, binary(passphrase)) @manipulative @trap_exception def deconstruct(self): """Iterates over internal image stack, and adjust each frame size to minimum bounding region of any changes from the previous frame. .. versionadded:: 0.5.0 """ r = library.MagickDeconstructImages(self.wand) if r: self.wand = r self.reset_sequence() return bool(r) @manipulative @trap_exception def deskew(self, threshold): """Attempts to remove skew artifacts common with most scanning & optical import devices. :params threshold: limit between foreground & background. Use a real number between `0.0` & `1.0` to match CLI's percent argument. :type threshold: :class:`numbers.Real` .. versionadded:: 0.5.0 """ assertions.assert_real(threshold=threshold) if 0 < threshold <= 1.0: threshold *= self.quantum_range return library.MagickDeskewImage(self.wand, threshold) @manipulative @trap_exception def despeckle(self): """Applies filter to reduce noise in image. :see: Example of :ref:`despeckle`. .. versionadded:: 0.5.0 """ return library.MagickDespeckleImage(self.wand) @manipulative @trap_exception def distort(self, method, arguments, best_fit=False, filter=None): """Distorts an image using various distorting methods. .. code:: python from wand.image import Image from wand.color import Color with Image(filename='checks.png') as img: img.virtual_pixel = 'background' img.background_color = Color('green') img.matte_color = Color('skyblue') arguments = (0, 0, 20, 60, 90, 0, 70, 63, 0, 90, 5, 83, 90, 90, 85, 88) img.distort('perspective', arguments) img.save(filename='checks_perspective.png') .. image:: ../_images/wand/image/checks.png .. image:: ../_images/wand/image/checks_perspective.png Use :attr:`virtual_pixel`, :attr:`background_color`, and :attr:`matte_color` properties to control the behavior of pixels rendered outside of the image boundaries. Use :attr:`interpolate_method` to control how images scale-up. Distortion viewport, and scale, can be defined by using :attr:`Image.artifacts` dictionary. For example:: img.artifacts['distort:viewport'] = '44x44+15+0' img.artifacts['distort:scale'] = '10' :see: Additional examples of :ref:`distort`. :param method: Distortion method name from :const:`DISTORTION_METHODS` :type method: :class:`basestring` :param arguments: List of distorting float arguments unique to distortion method :type arguments: :class:`collections.abc.Sequence` :param best_fit: Attempt to resize resulting image fit distortion. Defaults False :type best_fit: :class:`bool` :param filter: Optional resampling filter used when calculating pixel-value. Defaults to ``'mitchell'``, or ``'lanczos'`` based on image type & operation. :type filter: :class:`basestring` .. versionadded:: 0.4.1 .. versionchanged:: 0.6.11 Included `filter=` parameter. """ assertions.string_in_list(DISTORTION_METHODS, 'wand.image.DISTORTION_METHODS', method=method) if not isinstance(arguments, abc.Sequence): raise TypeError('expected sequence of doubles, not ' + repr(arguments)) argc = len(arguments) argv = (ctypes.c_double * argc)(*arguments) method_idx = DISTORTION_METHODS.index(method) if filter is not None: assertions.string_in_list(FILTER_TYPES, 'wand.image.FILTER_TYPES', filter=filter) ok = False if library.MagickSetImageFilter: filter_idx = FILTER_TYPES.index(filter) ok = library.MagickSetImageFilter(self.wand, filter_idx) else: img_info_ptr = libmagick.AcquireImageInfo() exp_ptr = libmagick.AcquireExceptionInfo() img_ptr = library.GetImageFromMagickWand(self.wand) if all([img_info_ptr, exp_ptr, img_ptr]): libmagick.SetImageOption(img_info_ptr, b'filter', filter.encode()) ok = libmagick.SyncImageSettings(img_info_ptr, img_ptr, exp_ptr) if img_info_ptr: img_info_ptr = libmagick.DestroyImageInfo(img_info_ptr) if exp_ptr: exp_ptr = libmagick.DestroyExceptionInfo(exp_ptr) if not ok: raise AttributeError('Unable to set filter for ' + filter) return library.MagickDistortImage(self.wand, method_idx, argc, argv, bool(best_fit)) @manipulative @trap_exception def edge(self, radius=0.0): """Applies convolution filter to detect edges. :see: Example of :ref:`edge`. :param radius: aperture of detection filter. :type radius: :class:`numbers.Real` .. versionadded:: 0.5.0 """ assertions.assert_real(radius=radius) return library.MagickEdgeImage(self.wand, radius) @manipulative @trap_exception def emboss(self, radius=0.0, sigma=0.0): """Applies convolution filter against Gaussians filter. .. note:: The `radius` value should be larger than `sigma` for best results. :see: Example of :ref:`emboss`. :param radius: filter aperture size. :type radius: :class:`numbers.Real` :param sigma: standard deviation. :type sigma: :class:`numbers.Real` .. versionadded:: 0.5.0 """ assertions.assert_real(radius=radius, sigma=sigma) return library.MagickEmbossImage(self.wand, radius, sigma) @manipulative @trap_exception def encipher(self, passphrase): """Encrypt plain pixels into ciphered values. .. note:: :class:`~wand.exceptions.ImageError` will be thrown if the system's ImageMagick library was compiled without cipher support. :param passphrase: the secret passphrase to encrypt with. :type passphrase: :class:`basestring` .. versionadded:: 0.6.3 .. versionchanged:: 0.6.8 Fixed C-API call. """ assertions.assert_string(passphrase=passphrase) return library.MagickEncipherImage(self.wand, binary(passphrase)) @manipulative @trap_exception def enhance(self): """Applies digital filter to reduce noise. :see: Example of :ref:`enhance`. .. versionadded:: 0.5.0 """ return library.MagickEnhanceImage(self.wand) @manipulative @trap_exception def equalize(self, channel=None): """Equalizes the image histogram :param channel: Optional channel. See :const:`CHANNELS`. :type channel: :class:`basestring` .. versionadded:: 0.3.10 .. versionchanged:: 0.5.5 Added optional ``channel`` argument. """ if channel is None: r = library.MagickEqualizeImage(self.wand) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickEqualizeImageChannel(self.wand, channel_ch) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickEqualizeImage(self.wand) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def evaluate(self, operator=None, value=0.0, channel=None): """Apply arithmetic, relational, or logical expression to an image. Percent values must be calculated against the quantum range of the image:: fifty_percent = img.quantum_range * 0.5 img.evaluate(operator='set', value=fifty_percent) :see: Example of :ref:`evaluate`. :param operator: Type of operation to calculate :type operator: :const:`EVALUATE_OPS` :param value: Number to calculate with ``operator`` :type value: :class:`numbers.Real` :param channel: Optional channel to apply operation on. :type channel: :const:`CHANNELS` :raises TypeError: When ``value`` is not numeric. :raises ValueError: When ``operator``, or ``channel`` are not defined in constants. .. versionadded:: 0.4.1 """ assertions.string_in_list(EVALUATE_OPS, 'wand.image.EVALUATE_OPS', operator=operator) assertions.assert_real(value=value) idx_op = EVALUATE_OPS.index(operator) if channel is None: r = library.MagickEvaluateImage(self.wand, idx_op, value) else: ch_const = self._channel_to_mask(channel) # Use channel method if IM6, else create channel mask for IM7. if library.MagickEvaluateImageChannel: r = library.MagickEvaluateImageChannel(self.wand, ch_const, idx_op, value) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_const) r = library.MagickEvaluateImage(self.wand, idx_op, value) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return r def export_pixels(self, x=0, y=0, width=None, height=None, channel_map="RGBA", storage='char'): """Export pixel data from a raster image to a list of values. The ``channel_map`` tells ImageMagick which color channels to export, and what order they should be written as -- per pixel. Valid entries for ``channel_map`` are: - ``'R'`` - Red channel - ``'G'`` - Green channel - ``'B'`` - Blue channel - ``'A'`` - Alpha channel (``0`` is transparent) - ``'O'`` - Alpha channel (``0`` is opaque) - ``'C'`` - Cyan channel - ``'Y'`` - Yellow channel - ``'M'`` - Magenta channel - ``'K'`` - Black channel - ``'I'`` - Intensity channel (only for grayscale) - ``'P'`` - Padding See :const:`STORAGE_TYPES` for a list of valid ``storage`` options. This tells ImageMagick what type of data it should calculate & write to. For example; a storage type of ``'char'`` will write a 8-bit value between 0 ~ 255, a storage type of ``'short'`` will write a 16-bit value between 0 ~ 65535, and a ``'integer'`` will write a 32-bit value between 0 ~ 4294967295. .. note:: By default, the entire image will be exported as ``'char'`` storage with each pixel mapping Red, Green, Blue, & Alpha channels. :param x: horizontal starting coordinate of raster. :type x: :class:`numbers.Integral` :param y: vertical starting coordinate of raster. :type y: :class:`numbers.Integral` :param width: horizontal length of raster. :type width: :class:`numbers.Integral` :param height: vertical length of raster. :type height: :class:`numbers.Integral` :param channel_map: a string listing the channel data format for each pixel. :type channel_map: :class:`basestring` :param storage: what data type each value should be calculated as. :type storage: :class:`basestring` :returns: list of values. :rtype: :class:`collections.abc.Sequence` .. versionadded:: 0.5.0 .. versionchanged:: 0.6.11 Update storage type size for `"long"` & `"quantum"` values. """ _w, _h = self.size if width is None: width = _w if height is None: height = _h assertions.assert_integer(x=x, y=y, width=width, height=height) assertions.assert_string(channel_map=channel_map) assertions.string_in_list(STORAGE_TYPES, 'wand.image.STORAGE_TYPES', storage=storage) channel_map = channel_map.upper() valid_channels = 'RGBAOCYMKIP' for channel in channel_map: if channel not in valid_channels: raise ValueError('Unknown channel label: ' + repr(channel)) c_storage_types = [ None, # undefined ctypes.c_ubyte, # char ctypes.c_double, # double ctypes.c_float, # float ctypes.c_uint, # integer ctypes.c_uint64, # long library.PixelGetRedQuantum.restype, # quantum ctypes.c_ushort # short ] s_index = STORAGE_TYPES.index(storage) c_storage = c_storage_types[s_index] total_pixels = width * height c_buffer_size = total_pixels * len(channel_map) c_buffer = (c_buffer_size * c_storage)() r = library.MagickExportImagePixels(self.wand, x, y, width, height, binary(channel_map), s_index, ctypes.byref(c_buffer)) if not r: # pragma: no cover self.raise_exception() return c_buffer[:c_buffer_size] @manipulative @trap_exception def extent(self, width=None, height=None, x=None, y=None, gravity=None): """Adjust the canvas size of the image. Use ``x`` & ``y`` to offset the image's relative placement in the canvas, or ``gravity`` helper for quick position placement. :param width: the target width of the extended image. Default is the :attr:`width` of the image. :type width: :class:`numbers.Integral` :param height: the target height of the extended image. Default is the :attr:`height` of the image. :type height: :class:`numbers.Integral` :param x: the x-axis offset of the extended image. Default is 0, and can not be used with ``gravity``. :type x: :class:`numbers.Integral` :param y: the :attr:`y` offset of the extended image. Default is 0, and can not be used with ``gravity``. :type y: :class:`numbers.Integral` :param gravity: position of the item extent when not using ``x`` & ``y``. See :const:`GRAVITY_TYPES`. :type gravity: :class:`basestring` .. versionadded:: 0.4.5 .. versionchanged:: 0.6.8 Added ``gravity`` argument. """ if width is None or width == 0: width = self.width if height is None or height == 0: height = self.height assertions.assert_unsigned_integer(width=width, height=height) if gravity is None: if x is None: x = 0 if y is None: y = 0 else: if x is not None or y is not None: raise ValueError('x & y can not be used with gravity.') y, x = self._gravity_to_offset(gravity, width, height) assertions.assert_integer(x=x, y=y) return library.MagickExtentImage(self.wand, width, height, x, y) def features(self, distance): """Calculate directional image features for each color channel. Feature metrics including: - angular second moment - contrast - correlation - variance sum of squares - inverse difference moment - sum average - sum variance - sum entropy - entropy - difference variance - difference entropy - information measures of correlation 1 - information measures of correlation 2 - maximum correlation coefficient With each metric containing horizontal, vertical, left & right diagonal values. .. code:: from wand.image import Image with Image(filename='rose:') as img: channel_features = img.features(distance=32) for channels, features in channel_features.items(): print(channels) for feature, directions in features.items(): print(' ', feature) for name, value in directions.items(): print(' ', name, value) :param distance: Define the distance if pixels to calculate. :type distance: :class:`numbers.Integral` :returns: a dict mapping each color channel with a dict of each feature. :rtype: :class:`dict` .. versionadded:: 0.5.5 """ def build_channel(address, channel): feature = ChannelFeature() size = ctypes.sizeof(feature) ctypes.memmove(ctypes.addressof(feature), feature_ptr + (CHANNELS[channel] * size), size) keys = ('horizontal', 'vertical', 'left_diagonal', 'right_diagonal') feature_dict = {} for k in feature._fields_: a = k[0] feature_dict[a] = dict(zip(keys, getattr(feature, a))) return feature_dict if MAGICK_VERSION_NUMBER < 0x700: method = library.MagickGetImageChannelFeatures else: # pragma: no cover method = library.MagickGetImageFeatures assertions.assert_unsigned_integer(distance=distance) feature_ptr = method(self.wand, distance) response = {} if feature_ptr: colorspace = self.colorspace if self.alpha_channel: response['alpha'] = build_channel(feature_ptr, 'alpha') if colorspace == 'gray': response['gray'] = build_channel(feature_ptr, 'gray') elif colorspace == 'cmyk': response['cyan'] = build_channel(feature_ptr, 'cyan') response['magenta'] = build_channel(feature_ptr, 'magenta') response['yellow'] = build_channel(feature_ptr, 'yellow') response['black'] = build_channel(feature_ptr, 'black') else: response['red'] = build_channel(feature_ptr, 'red') response['green'] = build_channel(feature_ptr, 'green') response['blue'] = build_channel(feature_ptr, 'blue') feature_ptr = library.MagickRelinquishMemory(feature_ptr) return response def fft(self, magnitude=True): """Alias for :meth:`forward_fourier_transform`. .. versionadded:: 0.5.7 """ return self.forward_fourier_transform(magnitude) @manipulative @trap_exception def flip(self): """Creates a vertical mirror image by reflecting the pixels around the central x-axis. It manipulates the image in place. :see: Example of :ref:`flip_flop`. .. versionadded:: 0.3.0 """ return library.MagickFlipImage(self.wand) @manipulative @trap_exception def flop(self): """Creates a horizontal mirror image by reflecting the pixels around the central y-axis. It manipulates the image in place. :see: Example of :ref:`flip_flop`. .. versionadded:: 0.3.0 """ return library.MagickFlopImage(self.wand) @trap_exception def forward_fourier_transform(self, magnitude=True): """Performs a discrete Fourier transform. The image stack is replaced with the results. Either a pair of magnitude & phase images, or real & imaginary (HDRI). .. code:: from wand.image import Image from wand.version import QUANTUM_RANGE with Image(filename='source.png') as img: img.forward_fourier_transform() img.depth = QUANTUM_RANGE img.save(filename='fft_%02d.png') .. seealso:: :meth:`inverse_fourier_transform` & :meth:`complex` .. note:: ImageMagick must have HDRI support to compute real & imaginary components (i.e. ``magnitude=False``). :param magnitude: If ``True``, generate magnitude & phase, else real & imaginary. Default ``True`` :type magnitude: :class:`bool` .. versionadded:: 0.5.5 """ assertions.assert_bool(magnitude=magnitude) return library.MagickForwardFourierTransformImage(self.wand, magnitude) @manipulative @trap_exception def frame(self, matte=None, width=1, height=1, inner_bevel=0, outer_bevel=0, compose='over'): """Creates a bordered frame around image. Inner & outer bevel can simulate a 3D effect. :param matte: color of the frame :type matte: :class:`wand.color.Color` :param width: total size of frame on x-axis :type width: :class:`numbers.Integral` :param height: total size of frame on y-axis :type height: :class:`numbers.Integral` :param inner_bevel: inset shadow length :type inner_bevel: :class:`numbers.Real` :param outer_bevel: outset highlight length :type outer_bevel: :class:`numbers.Real` :param compose: Optional composite operator. Default ``'over'``, and only available with ImageMagick-7. :type compose: :class:`basestring` .. versionadded:: 0.4.1 .. versionchanged:: 0.5.6 Added optional ``compose`` parameter. """ if matte is None: matte = Color('gray') if isinstance(matte, string_type): matte = Color(matte) assertions.assert_color(matte=matte) assertions.assert_integer(width=width, height=height) assertions.assert_real(inner_bevel=inner_bevel, outer_bevel=outer_bevel) with matte: if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickFrameImage(self.wand, matte.resource, width, height, inner_bevel, outer_bevel) else: # pragma: no cover assertions.string_in_list(COMPOSITE_OPERATORS, 'wand.image.COMPOSITE_OPERATORS', compose=compose) op = COMPOSITE_OPERATORS.index(compose) r = library.MagickFrameImage(self.wand, matte.resource, width, height, inner_bevel, outer_bevel, op) return r @manipulative @trap_exception def function(self, function, arguments, channel=None): """Apply an arithmetic, relational, or logical expression to an image. Defaults entire image, but can isolate affects to single color channel by passing :const:`CHANNELS` value to ``channel`` parameter. .. note:: Support for function methods added in the following versions of ImageMagick. - ``'polynomial'`` >= 6.4.8-8 - ``'sinusoid'`` >= 6.4.8-8 - ``'arcsin'`` >= 6.5.3-1 - ``'arctan'`` >= 6.5.3-1 :see: Example of :ref:`function`. :param function: a string listed in :const:`FUNCTION_TYPES` :type function: :class:`basestring` :param arguments: a sequence of doubles to apply against ``function`` :type arguments: :class:`collections.abc.Sequence` :param channel: optional :const:`CHANNELS`, defaults all :type channel: :class:`basestring` :raises ValueError: when a ``function``, or ``channel`` is not defined in there respected constant :raises TypeError: if ``arguments`` is not a sequence .. versionadded:: 0.4.1 """ assertions.string_in_list(FUNCTION_TYPES, 'wand.image.FUNCTION_TYPES', function=function) if not isinstance(arguments, abc.Sequence): raise TypeError('expecting sequence of arguments, not ' + repr(arguments)) argc = len(arguments) argv = (ctypes.c_double * argc)(*arguments) index = FUNCTION_TYPES.index(function) if channel is None: r = library.MagickFunctionImage(self.wand, index, argc, argv) else: ch_channel = self._channel_to_mask(channel) # Use channel method if IM6, else create channel mask for IM7. if library.MagickFunctionImageChannel: r = library.MagickFunctionImageChannel(self.wand, ch_channel, index, argc, argv) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_channel) r = library.MagickFunctionImage(self.wand, index, argc, argv) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return r @manipulative def fx(self, expression, channel=None): """Manipulate each pixel of an image by given expression. FX will preserver current wand instance, and return a new instance of :class:`Image` containing affected pixels. Defaults entire image, but can isolate affects to single color channel by passing :const:`CHANNELS` value to ``channel`` parameter. .. seealso:: The anatomy of FX expressions can be found at http://www.imagemagick.org/script/fx.php :see: Example of :ref:`fx`. :param expression: The entire FX expression to apply :type expression: :class:`basestring` :param channel: Optional channel to target. :type channel: :const:`CHANNELS` :returns: A new instance of an image with expression applied :rtype: :class:`Image` .. versionadded:: 0.4.1 .. versionchanged:: 0.6.9 Will raise :class:`WandRuntimeError` if method is unable to generate a new image & doesn't throw an exception. """ assertions.assert_string(expression=expression) c_expression = binary(expression) if channel is None: new_wand = library.MagickFxImage(self.wand, c_expression) else: ch_channel = self._channel_to_mask(channel) if library.MagickFxImageChannel: new_wand = library.MagickFxImageChannel(self.wand, ch_channel, c_expression) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_channel) new_wand = library.MagickFxImage(self.wand, c_expression) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) if new_wand: return Image(image=BaseImage(new_wand)) else: # pragma: no cover self.raise_exception() # If no exception is on the stack, then raise a generic run-time # error. This can happen naturally if the source image is null, # or the FX expression was unable to generate a new raster. raise WandRuntimeError('No FX Image was generated by expression.') @manipulative @trap_exception def gamma(self, adjustment_value=1.0, channel=None): """Gamma correct image. Specific color channels can be correct individual. Typical values range between 0.8 and 2.3. :see: Example of :ref:`gamma`. :param adjustment_value: value to adjust gamma level. Default `1.0` :type adjustment_value: :class:`numbers.Real` :param channel: optional channel to apply gamma correction :type channel: :class:`basestring` :raises TypeError: if ``gamma_point`` is not a :class:`numbers.Real` :raises ValueError: if ``channel`` is not in :const:`CHANNELS` .. versionadded:: 0.4.1 """ assertions.assert_real(adjustment_value=adjustment_value) if channel is None: r = library.MagickGammaImage(self.wand, adjustment_value) else: ch_const = self._channel_to_mask(channel) if library.MagickGammaImageChannel: r = library.MagickGammaImageChannel(self.wand, ch_const, adjustment_value) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_const) r = library.MagickGammaImage(self.wand, adjustment_value) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return r @manipulative @trap_exception def gaussian_blur(self, radius=0.0, sigma=0.0, channel=None): """Blurs the image. We convolve the image with a gaussian operator of the given ``radius`` and standard deviation (``sigma``). For reasonable results, the ``radius`` should be larger than ``sigma``. Use a ``radius`` of 0 and :meth:`blur()` selects a suitable ``radius`` for you. :see: Example of :ref:`gaussian_blur`. :param radius: the radius of the, in pixels, not counting the center pixel :type radius: :class:`numbers.Real` :param sigma: the standard deviation of the, in pixels :type sigma: :class:`numbers.Real` :param channel: Optional color channel to target. See :const:`CHANNELS` :type channel: :class:`basestring` .. versionadded:: 0.3.3 .. versionchanged:: 0.5.5 Added ``channel`` argument. .. versionchanged:: 0.5.7 Positional arguments ``radius`` & ``sigma`` have been converted to keyword arguments. """ assertions.assert_real(radius=radius, sigma=sigma) if channel is None: r = library.MagickGaussianBlurImage(self.wand, radius, sigma) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickGaussianBlurImageChannel(self.wand, channel_ch, radius, sigma) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickGaussianBlurImage(self.wand, radius, sigma) library.MagickSetImageChannelMask(self.wand, mask) return r def get_image_distortion(self, image, metric='undefined'): """Compares two images, and return the specified distortion metric. This method is faster than :meth:`compare()` method as ImageMagick will not need to reconstruct an image. :param image: Image to reference. :type image: :class:`wand.image.BaseImage` :param metric: Compare disortion metric to use. See :const:`COMPARE_METRICS`. :type metric: :class:`basestring` :returns: Computed value of the distortion metric used. :rtype: :class:`numbers.Real` .. versionadded:: 0.6.6 """ if not isinstance(image, BaseImage): raise TypeError('expecting a base image, not ' + repr(image)) assertions.string_in_list(COMPARE_METRICS, 'wand.image.COMPARE_METRICS', metric=metric) metric_idx = COMPARE_METRICS.index(metric) dist = ctypes.c_double(0.0) ok = library.MagickGetImageDistortion(self.wand, image.wand, metric_idx, dist) if not ok: self.raise_exception() return dist.value @manipulative @trap_exception def hald_clut(self, image, channel=None): """Replace color values by referencing a Higher And Lower Dimension (HALD) Color Look Up Table (CLUT). You can generate a HALD image by using ImageMagick's `hald:` protocol. :: with Image(filename='rose:') as img: with Image(filename='hald:3') as hald: hald.gamma(1.367) img.hald_clut(hald) :param image: The HALD color matrix. :type image: :class:`wand.image.BaseImage` :param channel: Optional color channel to target. See :const:`CHANNELS` :type channel: :class:`basestring` .. versionadded:: 0.5.0 .. versionchanged:: 0.5.5 Added ``channel`` argument. """ if not isinstance(image, BaseImage): raise TypeError('expecting a base image, not ' + repr(image)) if channel is None: r = library.MagickHaldClutImage(self.wand, image.wand) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickHaldClutImageChannel(self.wand, channel_ch, image.wand) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickHaldClutImage(self.wand, image.wand) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def hough_lines(self, width, height=None, threshold=40): """Identify lines within an image. Use :meth:`canny` to reduce image to a binary edge before calling this method. .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. :param width: Local maxima of neighboring pixels. :type width: :class:`numbers.Integral` :param height: Local maxima of neighboring pixels. :type height: :class:`numbers.Integral` :param threshold: Line count to limit. Default to 40. :type threshold: :class:`numbers.Integral` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.5 """ if library.MagickHoughLineImage is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) if height is None: height = width assertions.assert_unsigned_integer(width=width, height=height, threshold=threshold) return library.MagickHoughLineImage(self.wand, width, height, threshold) def ift(self, phase, magnitude=True): """Alias for :meth:`inverse_fourier_transform`. .. versionadded:: 0.5.7 """ return self.inverse_fourier_transform(phase, magnitude) @trap_exception def implode(self, amount=0.0, method="undefined"): """Creates a "imploding" effect by pulling pixels towards the center of the image. :see: Example of :ref:`implode`. :param amount: Normalized degree of effect between `0.0` & `1.0`. :type amount: :class:`numbers.Real` :param method: Which interpolate method to apply to effected pixels. See :const:`PIXEL_INTERPOLATE_METHODS` for a list of options. Only available with ImageMagick-7. :type method: :class:`basestring` .. versionadded:: 0.5.2 """ assertions.assert_real(amount=amount) assertions.string_in_list(PIXEL_INTERPOLATE_METHODS, 'wand.image.PIXEL_INTERPOLATE_METHODS', method=method) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickImplodeImage(self.wand, amount) else: # pragma: no cover method_idx = PIXEL_INTERPOLATE_METHODS.index(method) r = library.MagickImplodeImage(self.wand, amount, method_idx) return r @trap_exception def import_pixels(self, x=0, y=0, width=None, height=None, channel_map='RGB', storage='char', data=None): """Import pixel data from a byte-string to the image. The instance of :class:`Image` must already be allocated with the correct size. The ``channel_map`` tells ImageMagick which color channels to export, and what order they should be written as -- per pixel. Valid entries for ``channel_map`` are: - ``'R'`` - Red channel - ``'G'`` - Green channel - ``'B'`` - Blue channel - ``'A'`` - Alpha channel (``0`` is transparent) - ``'O'`` - Alpha channel (``0`` is opaque) - ``'C'`` - Cyan channel - ``'Y'`` - Yellow channel - ``'M'`` - Magenta channel - ``'K'`` - Black channel - ``'I'`` - Intensity channel (only for grayscale) - ``'P'`` - Padding See :const:`STORAGE_TYPES` for a list of valid ``storage`` options. This tells ImageMagick what type of data it should calculate & write to. For example; a storage type of ``'char'`` will write a 8-bit value between 0 ~ 255, a storage type of ``'short'`` will write a 16-bit value between 0 ~ 65535, and a ``'integer'`` will write a 32-bit value between 0 ~ 4294967295. .. note:: By default, the entire image will be exported as ``'char'`` storage with each pixel mapping Red, Green, Blue, & Alpha channels. :param x: horizontal starting coordinate of raster. :type x: :class:`numbers.Integral` :param y: vertical starting coordinate of raster. :type y: :class:`numbers.Integral` :param width: horizontal length of raster. :type width: :class:`numbers.Integral` :param height: vertical length of raster. :type height: :class:`numbers.Integral` :param channel_map: a string listing the channel data format for each pixel. :type channel_map: :class:`basestring` :param storage: what data type each value should be calculated as. :type storage: :class:`basestring` .. versionadded:: 0.5.0 .. versionchanged:: 0.6.11 Update storage type size for `"long"` & `"quantum"` values. """ _w, _h = self.size if width is None: width = _w if height is None: height = _h assertions.assert_integer(x=x, y=y, width=width, height=height) assertions.string_in_list(STORAGE_TYPES, 'wand.image.STORAGE_TYPES', storage=storage) assertions.assert_string(channel_map=channel_map) channel_map = channel_map.upper() valid_channels = 'RGBAOCYMKIP' for channel in channel_map: if channel not in valid_channels: raise ValueError('Unknown channel label: ' + repr(channel)) if not isinstance(data, abc.Sequence): raise TypeError('data must list of values, not' + repr(data)) # Ensure enough data was given. expected_len = width * height * len(channel_map) given_len = len(data) if expected_len != given_len: msg = 'data length should be {0}, not {1}.'.format( expected_len, given_len ) raise ValueError(msg) c_storage_types = [ None, # undefined ctypes.c_ubyte, # char ctypes.c_double, # double ctypes.c_float, # float ctypes.c_uint, # integer ctypes.c_uint64, # long library.PixelGetRedQuantum.restype, # quantum ctypes.c_ushort # short ] s_index = STORAGE_TYPES.index(storage) c_type = c_storage_types[s_index] c_buffer = (len(data) * c_type)(*data) r = library.MagickImportImagePixels(self.wand, x, y, width, height, binary(channel_map), s_index, ctypes.byref(c_buffer)) return r @trap_exception def inverse_fourier_transform(self, phase, magnitude=True): """Applies the inverse of a discrete Fourier transform. The image stack is replaced with the results. Either a pair of magnitude & phase images, or real & imaginary (HDRI). .. code:: from wand.image import Image with Image(filename='magnitude.png') as img: with Image(filename='phase.png') as phase: img.inverse_fourier_transform(phase) img.save(filename='output.png') .. seealso:: :meth:`forward_fourier_transform` & :meth:`complex` .. note:: ImageMagick must have HDRI support to compute real & imaginary components (i.e. ``magnitude=False``). :param phase: Second part (image) of the transform. Either the phase, or the imaginary part. :type phase: :class:`BaseImage` :param magnitude: If ``True``, accept magnitude & phase input, else real & imaginary. Default ``True`` :type magnitude: :class:`bool` .. versionadded:: 0.5.5 """ if not isinstance(phase, BaseImage): raise TypeError('phase must be an image, not ' + repr(phase)) assertions.assert_bool(magnitude=magnitude) return library.MagickInverseFourierTransformImage(self.wand, phase.wand, magnitude) def iterator_first(self): """Sets the internal image-stack iterator to the first image. Useful for prepending an image at the start of the stack. .. versionadded:: 0.6.2 """ library.MagickSetFirstIterator(self.wand) def iterator_get(self): """Returns the position of the internal image-stack index. :rtype: :class:`int` .. versionadded:: 0.6.2 """ return library.MagickGetIteratorIndex(self.wand) def iterator_last(self): """Sets the internal image-stack iterator to the last image. Useful for appending an image to the end of the stack. .. versionadded:: 0.6.2 """ library.MagickSetLastIterator(self.wand) def iterator_length(self): """Get the count of images in the image-stack. :rtype: :class:`int` .. versionadded:: 0.6.2 """ return library.MagickGetNumberImages(self.wand) def iterator_next(self): """Steps the image-stack index forward by one :rtype: :class:`bool` .. versionadded:: 0.6.2 """ has_next = library.MagickHasNextImage(self.wand) if has_next: idx = library.MagickGetIteratorIndex(self.wand) has_next = library.MagickSetIteratorIndex(self.wand, idx + 1) return has_next def iterator_previous(self): """Steps the image-stack index back by one. :rtype: :class:`bool` .. versionadded:: 0.6.2 """ has_prev = library.MagickHasPreviousImage(self.wand) if has_prev: idx = library.MagickGetIteratorIndex(self.wand) has_prev = library.MagickSetIteratorIndex(self.wand, idx - 1) return has_prev def iterator_reset(self): """Reset internal image-stack iterator. Useful for iterating over the image-stack without allocating :class:`~wand.sequence.Sequence`. .. versionadded:: 0.6.2 """ library.MagickResetIterator(self.wand) def iterator_set(self, index): """Sets the index of the internal image-stack. :rtype: :class:`bool` .. versionadded:: 0.6.2 """ assertions.assert_integer(index=index) return library.MagickSetIteratorIndex(self.wand, index) @manipulative @trap_exception def kmeans(self, number_colors=None, max_iterations=100, tolerance=0.01): """Reduces the number of colors in an image by applying the K-means clustering algorithm. .. note:: Requires ImageMagick-7.0.10-37, or later. :param number_colors: the target number of colors to use as seeds. :type number_colors: :class:`numbers.Integral` :param max_iterations: maximum number of iterations needed until convergence. Default ``100``. :type max_iterations: :class:`numbers.Integral` :param tolerance: maximum tolerance between distrotion iterations. Default ``0.01`` :type tolerance: :class:`numbers.Real` .. versionadded:: 0.6.4 """ if MAGICK_VERSION_NUMBER < 0x70A or library.MagickKmeansImage is None: msg = "Kmeans requires ImageMagick-7.0.10-37 or later." raise WandLibraryVersionError(msg) assertions.assert_unsigned_integer(number_colors=number_colors, max_iterations=max_iterations) assertions.assert_real(tolerance=tolerance) return library.MagickKmeansImage(self.wand, number_colors, max_iterations, tolerance) def kurtosis_channel(self, channel='default_channels'): """Calculates the kurtosis and skewness of the image. .. code:: python from wand.image import Image with Image(filename='input.jpg') as img: kurtosis, skewness = img.kurtosis_channel() :param channel: Select which color channel to evaluate. See :const:`CHANNELS`. Default ``'default_channels'``. :type channel: :class:`basestring` :returns: Tuple of :attr:`kurtosis` & :attr:`skewness` values. :rtype: :class:`tuple` .. versionadded:: 0.5.3 """ ch_channel = self._channel_to_mask(channel) k = ctypes.c_double(0.0) s = ctypes.c_double(0.0) if MAGICK_VERSION_NUMBER < 0x700: library.MagickGetImageChannelKurtosis(self.wand, ch_channel, ctypes.byref(k), ctypes.byref(s)) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_channel) library.MagickGetImageKurtosis(self.wand, ctypes.byref(k), ctypes.byref(s)) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return k.value, s.value @manipulative @trap_exception def kuwahara(self, radius=1.0, sigma=None): """Edge preserving noise reduction filter. https://en.wikipedia.org/wiki/Kuwahara_filter If ``sigma`` is not given, the value will be calculated as: sigma = radius - 0.5 To match original algorithm's behavior, increase ``radius`` value by one: myImage.kuwahara(myRadius + 1, mySigma) .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. :see: Example of :ref:`kuwahara`. :param radius: Size of the filter aperture. :type radius: :class:`numbers.Real` :param sigma: Standard deviation of Gaussian filter. :type sigma: :class:`numbers.Real` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.5 """ if library.MagickKuwaharaImage is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) if sigma is None: sigma = radius - 0.5 assertions.assert_real(radius=radius, sigma=sigma) return library.MagickKuwaharaImage(self.wand, radius, sigma) @manipulative def label(self, text, left=None, top=None, font=None, gravity=None, background_color='transparent'): """Writes a label ``text`` into the position on top of the existing canvas. This method doesn't autofit text like :meth:`caption`. Use ``left`` & ``top``, or ``gravity``, to position the text. :param text: text to write. :type text: :class:`basestring` :param left: x offset in pixels. :type left: :class:`numbers.Integral` :param top: y offset in pixels. :type top: :class:`numbers.Integral` :param font: font to use. default is :attr:`font` of the image. :type font: :class:`wand.font.Font` :param gravity: text placement gravity. :type gravity: :class:`basestring` .. versionadded:: 0.6.8 """ if font is not None and not isinstance(font, Font): raise TypeError('font must be a wand.font.Font, not ' + repr(font)) if gravity is not None: assertions.string_in_list(GRAVITY_TYPES, 'wand.image.GRAVITY_TYPES', gravity=gravity) if font is None: try: font = self.font if font is None: raise TypeError() except TypeError: raise TypeError('font must be specified or existing in image') with Image() as textboard: textboard.font = font textboard.background_color = background_color textboard.read(filename=b'label:' + text.encode('utf-8')) self.composite(textboard, left=left, top=top, gravity=gravity) @trap_exception def level(self, black=0.0, white=None, gamma=1.0, channel=None): """Adjusts the levels of an image by scaling the colors falling between specified black and white points to the full available quantum range. If only ``black`` is given, ``white`` will be adjusted inward. :see: Example of :ref:`level`. :param black: Black point, as a percentage of the system's quantum range. Defaults to 0. :type black: :class:`numbers.Real` :param white: White point, as a percentage of the system's quantum range. Defaults to 1.0. :type white: :class:`numbers.Real` :param gamma: Optional gamma adjustment. Values > 1.0 lighten the image's midtones while values < 1.0 darken them. :type gamma: :class:`numbers.Real` :param channel: The channel type. Available values can be found in the :const:`CHANNELS` mapping. If ``None``, normalize all channels. :type channel: :const:`CHANNELS` .. note:: Images may not be affected if the ``white`` value is equal to or less than the ``black`` value. .. versionadded:: 0.4.1 """ assertions.assert_real(black=black) # If white is not given, mimic CLI behavior by reducing top point if white is None: white = 1.0 - black assertions.assert_real(white=white, gamma=gamma) bp = float(self.quantum_range * black) wp = float(self.quantum_range * white) if MAGICK_HDRI: # pragma: no cover bp -= 0.5 # TODO: Document why HDRI requires 0.5 adjustments. wp -= 0.5 if channel is None: r = library.MagickLevelImage(self.wand, bp, gamma, wp) else: ch_const = self._channel_to_mask(channel) if library.MagickLevelImageChannel: r = library.MagickLevelImageChannel(self.wand, ch_const, bp, gamma, wp) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_const) r = library.MagickLevelImage(self.wand, bp, gamma, wp) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return r @manipulative @trap_exception def level_colors(self, black_color, white_color, channel=None): """Maps given colors to "black" & "white" values. .. warning:: This class method is only available with ImageMagick 7.0.8-54, or greater. :param black_color: linearly map given color as "black" point. :type black_color: :class:`Color` :param white_color: linearly map given color as "white" point. :type white_color: :class:`Color` :param channel: target a specific color-channel to levelize. :type channel: :class:`basestring` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.6 """ if library.MagickLevelImageColors is None: msg = 'Method requires ImageMagick version 7.0.8-54 or greater.' raise WandLibraryVersionError(msg) if isinstance(black_color, string_type): black_color = Color(black_color) if isinstance(white_color, string_type): white_color = Color(white_color) assertions.assert_color(black_color=black_color, white_color=white_color) channel_mask = None if channel is not None: ch_const = self._channel_to_mask(channel) channel_mask = library.MagickSetImageChannelMask(self.wand, ch_const) with black_color: with white_color: r = library.MagickLevelImageColors(self.wand, black_color.resource, white_color.resource, False) if channel is not None: library.MagickSetImageChannelMask(self.wand, channel_mask) return r @manipulative @trap_exception def levelize(self, black=0.0, white=None, gamma=1.0, channel=None): """Reverse of :meth:`level()`, this method compresses the range of colors between ``black`` & ``white`` values. If only ``black`` is given, ``white`` will be adjusted inward. .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. :param black: Black point, as a percentage of the system's quantum range. Defaults to 0. :type black: :class:`numbers.Real` :param white: White point, as a percentage of the system's quantum range. Defaults to 1.0. :type white: :class:`numbers.Real` :param gamma: Optional gamma adjustment. Values > 1.0 lighten the image's midtones while values < 1.0 darken them. :type gamma: :class:`numbers.Real` :param channel: The channel type. Available values can be found in the :const:`CHANNELS` mapping. If ``None``, normalize all channels. :type channel: :const:`CHANNELS` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.5 """ if library.MagickLevelizeImage is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) if white is None: white = float(self.quantum_range) assertions.assert_real(black=black, white=white, gamma=gamma) if 0 < black <= 1.0: black *= self.quantum_range if 0 < white <= 1.0: white *= self.quantum_range if channel is None: r = library.MagickLevelizeImage(self.wand, black, gamma, white) else: ch_const = self._channel_to_mask(channel) channel_mask = library.MagickSetImageChannelMask(self.wand, ch_const) r = library.MagickLevelizeImage(self.wand, black, gamma, white) library.MagickSetImageChannelMask(self.wand, channel_mask) return r @manipulative @trap_exception def levelize_colors(self, black_color, white_color, channel=None): """Reverse of :meth:`level_colors()`, and creates a de-contrasting gradient of given colors. This works best with grayscale images. .. warning:: This class method is only available with ImageMagick 7.0.8-54, or greater. :param black_color: tint map given color as "black" point. :type black_color: :class:`Color` :param white_color: tint map given color as "white" point. :type white_color: :class:`Color` :param channel: target a specific color-channel to levelize. :type channel: :class:`basestring` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.6 """ if library.MagickLevelImageColors is None: msg = 'Method requires ImageMagick version 7.0.8-54 or greater.' raise WandLibraryVersionError(msg) if isinstance(black_color, string_type): black_color = Color(black_color) if isinstance(white_color, string_type): white_color = Color(white_color) assertions.assert_color(black_color=black_color, white_color=white_color) channel_mask = None ch_const = None if channel is not None: ch_const = self._channel_to_mask(channel) channel_mask = library.MagickSetImageChannelMask(self.wand, ch_const) with black_color: with white_color: r = library.MagickLevelImageColors(self.wand, black_color.resource, white_color.resource, True) if channel is not None: library.MagickSetImageChannelMask(self.wand, channel_mask) return r @manipulative @trap_exception def linear_stretch(self, black_point=0.0, white_point=1.0): """Enhance saturation intensity of an image. :param black_point: Black point between 0.0 and 1.0. Default 0.0 :type black_point: :class:`numbers.Real` :param white_point: White point between 0.0 and 1.0. Default 1.0 :type white_point: :class:`numbers.Real` .. versionadded:: 0.4.1 """ assertions.assert_real(black_point=black_point, white_point=white_point) linear_range = float(self.width * self.height) return library.MagickLinearStretchImage(self.wand, linear_range * black_point, linear_range * white_point) @manipulative def liquid_rescale(self, width, height, delta_x=0, rigidity=0): """Rescales the image with `seam carving`_, also known as image retargeting, content-aware resizing, or liquid rescaling. :param width: the width in the scaled image :type width: :class:`numbers.Integral` :param height: the height in the scaled image :type height: :class:`numbers.Integral` :param delta_x: maximum seam transversal step. 0 means straight seams. default is 0 :type delta_x: :class:`numbers.Real` :param rigidity: introduce a bias for non-straight seams. default is 0 :type rigidity: :class:`numbers.Real` :raises wand.exceptions.MissingDelegateError: when ImageMagick isn't configured ``--with-lqr`` option. .. note:: This feature requires ImageMagick to be configured ``--with-lqr`` option. Or it will raise :exc:`~wand.exceptions.MissingDelegateError`: .. seealso:: `Seam carving`_ --- Wikipedia The article which explains what seam carving is on Wikipedia. .. _Seam carving: http://en.wikipedia.org/wiki/Seam_carving """ assertions.assert_integer(width=width, height=height) assertions.assert_real(delta_x=delta_x, rigidity=rigidity) library.MagickLiquidRescaleImage(self.wand, width, height, delta_x, rigidity) try: self.raise_exception() except MissingDelegateError as e: # pragma: no cover raise MissingDelegateError( str(e) + '\n\nImageMagick in the system is likely to be ' 'impossible to load liblqr. You might not install liblqr, ' 'or ImageMagick may not compiled with liblqr.' ) @manipulative @trap_exception def local_contrast(self, radius=10, strength=12.5): """Increase light-dark transitions within image. .. warning:: This class method is only available with ImageMagick 6.9.3, or greater. :param radius: The size of the Gaussian operator. Default value is ``10.0``. :type radius: :class:`numbers.Real` :param strength: Percentage of blur mask to apply. Values can be between ``0.0`` and ``100`` with a default of ``12.5``. :type strength: :class:`numbers.Real` .. versionadded:: 0.5.7 """ if library.MagickLocalContrastImage is None: # pragma: no cover msg = 'Method requires ImageMagick version 6.9.3 or greater.' raise WandLibraryVersionError(msg) assertions.assert_real(radius=radius, strength=strength) return library.MagickLocalContrastImage(self.wand, radius, strength) @manipulative @trap_exception def magnify(self): """Quickly double an image in size. This is a convenience method. Use :meth:`resize()`, :meth:`resample()`, or :meth:`sample()` for more control. .. versionadded:: 0.5.5 """ return library.MagickMagnifyImage(self.wand) def mean_channel(self, channel='default_channels'): """Calculates the mean and standard deviation of the image. .. code:: python from wand.image import Image with Image(filename='input.jpg') as img: mean, stddev = img.mean_channel() :param channel: Select which color channel to evaluate. See :const:`CHANNELS`. Default ``'default_channels'``. :type channel: :class:`basestring` :returns: Tuple of :attr:`mean` & :attr:`standard_deviation` values. The ``mean`` value will be between 0.0 & :attr:`quantum_range` :rtype: :class:`tuple` .. versionadded:: 0.5.3 """ ch_channel = self._channel_to_mask(channel) m = ctypes.c_double(0.0) s = ctypes.c_double(0.0) if MAGICK_VERSION_NUMBER < 0x700: library.MagickGetImageChannelMean(self.wand, ch_channel, ctypes.byref(m), ctypes.byref(s)) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_channel) library.MagickGetImageMean(self.wand, ctypes.byref(m), ctypes.byref(s)) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return m.value, s.value @manipulative @trap_exception def mean_shift(self, width, height, color_distance=0.1): """Recalculates pixel value by comparing neighboring pixels within a color distance, and replacing with a mean value. Works best with Gray, YCbCr, YIQ, or YUV colorspaces. .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. :param width: Size of the neighborhood window in pixels. :type width: :class:`numbers.Integral` :param height: Size of the neighborhood window in pixels. :type height: :class:`numbers.Integral` :param color_distance: Include pixel values within this color distance. :type color_distance: :class:`numbers.Real` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.5 """ if library.MagickMeanShiftImage is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) assertions.assert_counting_number(width=width, height=height) assertions.assert_real(color_distance=color_distance) if 0 < color_distance <= 1.0: color_distance *= self.quantum_range return library.MagickMeanShiftImage(self.wand, width, height, color_distance) @manipulative @trap_exception def merge_layers(self, method): """Composes all the image layers from the current given image onward to produce a single image of the merged layers. The initial canvas's size depends on the given ImageLayerMethod, and is initialized using the first images background color. The images are then composited onto that image in sequence using the given composition that has been assigned to each individual image. The method must be set with a value from :const:`IMAGE_LAYER_METHOD` that is acceptable to this operation. (See ImageMagick documentation for more details.) :param method: the method of selecting the size of the initial canvas. :type method: :class:`basestring` .. versionadded:: 0.4.3 """ assertions.assert_string(method=method) if method not in ('merge', 'flatten', 'mosaic', 'trimbounds'): raise ValueError('method can only be \'merge\', \'flatten\', ' '\'mosaic\', or \'trimbounds\'') m = IMAGE_LAYER_METHOD.index(method) r = library.MagickMergeImageLayers(self.wand, m) if r: self.wand = r self.reset_sequence() return bool(r) def minimum_bounding_box(self, orientation=None): """Find the minimum bounding box within the image. Use properties :attr:`fuzz` & :attr:`background_color` to influence bounding box thresholds. .. code:: from wand.image import Image from wand.drawing import Drawing with Image(filename='kdf_black.png') as img: img.fuzz = img.quantum_range * 0.1 img.background_color = 'black' mbr = img.minimum_bounding_box() with Drawing() as ctx: ctx.fill_color = 'transparent' ctx.stroke_color = 'red' ctx.polygon(points=mbr['points']) ctx.fill_color = 'red' ctx.stroke_color = 'transparent' ctx.text(1, 10, '{0:.4g}\u00B0'.format(mbr['angle'])) ctx(img) img.save(filename='kdf_black_mbr.png') .. image:: ../_images/wand/image/kdf_black.png .. image:: ../_images/wand/image/kdf_black_mbr.png .. note:: Requires ImageMagick-7.0.10 or later. :param orientation: sets the image orientation. Values can be ``'landscape'``, or ``'portrait'``. :type orientation: :class:`basestring` :returns: a directory of MBR properties & corner points. :rtype: :class:`dict` { "points": :class:`list` [ :class:`tuple` ( :class:`float`, :class:`float` ) ], "area": :class:`float`, "width": :class:`float`, "height": :class:`float`, "angle": :class:`float`, "unrotate": :class:`float` } .. versionadded:: 0.6.4 """ r = {} if MAGICK_VERSION_NUMBER < 0x70A: msg = 'ImageMagick-7.0.10 is required to use convex_hull().' raise WandLibraryVersionError(msg) with self.clone() as tmp: if orientation is not None: if orientation not in ('landscape', 'portrait'): msg = 'orientation can only be landscape, or portrait, not' msg += ' ' + repr(orientation) raise ValueError(msg) key = b'minimum-bounding-box:orientation' val = to_bytes(orientation) library.MagickSetImageArtifact(tmp.wand, key, val) mbr_str = b'%[minimum-bounding-box]' mbr_str += b'|%[minimum-bounding-box:area]' mbr_str += b'|%[minimum-bounding-box:width]' mbr_str += b'|%[minimum-bounding-box:height]' mbr_str += b'|%[minimum-bounding-box:angle]' mbr_str += b'|%[minimum-bounding-box:unrotate]' library.MagickSetOption(tmp.wand, b'format', mbr_str) library.MagickSetImageFormat(tmp.wand, b'INFO') length = ctypes.c_size_t() blob_p = library.MagickGetImageBlob(tmp.wand, ctypes.byref(length)) if blob_p: blob = ctypes.string_at(blob_p, length.value) blob_p = library.MagickRelinquishMemory(blob_p) parts = blob.decode('ascii', 'ignore').split('|') pts = parts[0].strip().split(' ') r = [tuple(map(lambda x: float(x), p.split(','))) for p in pts] attr = list(map(lambda x: float(x.strip()), parts[1:])) keys = ['area', 'width', 'height', 'angle', 'unrotate'] r = dict(zip(keys, attr), points=r) else: self.raise_exception() return r @manipulative def mode(self, width, height=None): """Replace each pixel with the mathematical mode of the neighboring colors. This is an alias of the :meth:`statistic` method. :param width: Number of neighboring pixels to include in mode. :type width: :class:`numbers.Integral` :param height: Optional height of neighboring pixels, defaults to the same value as ``width``. :type height: :class:`numbers.Integral` .. versionadded:: 0.5.4 """ if height is None: height = width self.statistic('mode', width, height) @manipulative @trap_exception def modulate(self, brightness=100.0, saturation=100.0, hue=100.0): """Changes the brightness, saturation and hue of an image. We modulate the image with the given ``brightness``, ``saturation`` and ``hue``. :param brightness: percentage of brightness :type brightness: :class:`numbers.Real` :param saturation: percentage of saturation :type saturation: :class:`numbers.Real` :param hue: percentage of hue rotation :type hue: :class:`numbers.Real` :raises ValueError: when one or more arguments are invalid .. versionadded:: 0.3.4 """ assertions.assert_real(brightness=brightness, saturation=saturation, hue=hue) return library.MagickModulateImage( self.wand, brightness, saturation, hue ) @manipulative @trap_exception def morphology(self, method=None, kernel=None, iterations=1, channel=None): """Manipulate pixels based on the shape of neighboring pixels. The ``method`` determines what type of effect to apply to matching ``kernel`` shapes. Common methods can be add/remove, or lighten/darken pixel values. The ``kernel`` describes the shape of the matching neighbors. Common shapes are provided as "built-in" kernels. See :const`KERNEL_INFO_TYPES` for examples. The format for built-in kernels is: .. sourcecode:: text label:geometry Where `label` is the kernel name defined in :const:`KERNEL_INFO_TYPES`, and `:geometry` is an optional geometry size. For example:: with Image(filename='rose:') as img: img.morphology(method='dilate', kernel='octagon:3x3') # or simply img.morphology(method='edgein', kernel='octagon') Custom kernels can be applied by following a similar format: .. sourcecode:: text geometry:args Where `geometry` is the size of the custom kernel, and `args` list a comma separated list of values. For example:: custom_kernel='5x3:nan,1,1,1,nan 1,1,1,1,1 nan,1,1,1,nan' with Image(filename='rose:') as img: img.morphology(method='dilate', kernel=custom_kernel) :param method: effect function to apply. See :const:`MORPHOLOGY_METHODS` for a list of methods. :type method: :class:`basestring` :param kernel: shape to evaluate surrounding pixels. See :const:`KERNEL_INFO_TYPES` for a list of built-in shapes. :type kernel: :class:`basestring` :param iterations: Number of times a morphology method should be applied to the image. Default ``1``. Use ``-1`` for unlimited iterations until the image is unchanged by the method operator. :type iterations: :class:`numbers.Integral` :param channel: Optional color channel to target. See :const:`CHANNELS` :type channel: `basestring` .. versionadded:: 0.5.0 .. versionchanged:: 0.5.5 Added ``channel`` argument. """ assertions.assert_string(method=method, kernel=kernel) assertions.assert_integer(iterations=iterations) builtin = None geometry = '' parts = kernel.split(':') if parts[0] in KERNEL_INFO_TYPES: builtin = parts[0] if len(parts) == 2: geometry = parts[1] exception_info = libmagick.AcquireExceptionInfo() if builtin: kernel_idx = KERNEL_INFO_TYPES.index(builtin) geometry_info = GeometryInfo() flags = libmagick.ParseGeometry(binary(geometry), ctypes.byref(geometry_info)) if builtin in ('unity',): if (flags & geometry_info.RhoValue) == 0: geometry_info.rho = 1.0 elif builtin in ('square', 'diamond', 'octagon', 'disk', 'plus', 'cross'): if (flags & geometry_info.SigmaValue) == 0: geometry_info.sigma = 1.0 elif builtin in ('ring',): if (flags & geometry_info.XiValue) == 0: geometry_info.xi = 1.0 elif builtin in ('rectangle',): if (flags & geometry_info.RhoValue) == 0: geometry_info.rho = geometry_info.sigma if geometry_info.rho < 1.0: geometry_info.rho = 3.0 if geometry_info.sigma < 1.0: geometry_info.sigma = geometry_info.rho if (flags & geometry_info.XiValue) == 0: geometry_info.xi = (geometry_info.rho - 1.0) / 2.0 if (flags & geometry_info.PsiValue) == 0: geometry_info.psi = (geometry_info.sigma - 1.0) / 2.0 elif builtin in ('chebyshev', 'manhattan', 'octagonal', 'euclidean'): if (flags & geometry_info.SigmaValue) == 0: geometry_info.sigma = 100.0 elif (flags & geometry_info.AspectValue) != 0: geometry_info.sigma = (float(self.quantum_range) / (geometry_info.sigma + 1.0)) elif (flags & geometry_info.PercentValue) != 0: geometry_info.sigma *= float(self.quantum_range) / 100.0 if MAGICK_VERSION_NUMBER < 0x700: kernel_info = libmagick.AcquireKernelBuiltIn( kernel_idx, ctypes.byref(geometry_info) ) else: # pragma: no cover kernel_info = libmagick.AcquireKernelBuiltIn( kernel_idx, ctypes.byref(geometry_info), exception_info ) elif kernel: if MAGICK_VERSION_NUMBER < 0x700: kernel_info = libmagick.AcquireKernelInfo( binary(kernel) ) else: # pragma: no cover kernel_info = libmagick.AcquireKernelInfo( binary(kernel), exception_info ) r = None exception_info = libmagick.DestroyExceptionInfo(exception_info) if kernel_info: method_idx = MORPHOLOGY_METHODS.index(method) if channel is None: r = library.MagickMorphologyImage(self.wand, method_idx, iterations, kernel_info) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickMorphologyImageChannel(self.wand, channel_ch, method_idx, iterations, kernel_info) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickMorphologyImage(self.wand, method_idx, iterations, kernel_info) library.MagickSetImageChannelMask(self.wand, mask) kernel_info = libmagick.DestroyKernelInfo(kernel_info) else: raise ValueError('Unable to parse kernel info for ' + repr(kernel)) return r @manipulative @trap_exception def motion_blur(self, radius=0.0, sigma=0.0, angle=0.0, channel=None): """Apply a Gaussian blur along an ``angle`` direction. This simulates motion movement. :see: Example of :ref:`motion_blur`. :param radius: Aperture size of the Gaussian operator. :type radius: :class:`numbers.Real` :param sigma: Standard deviation of the Gaussian operator. :type sigma: :class:`numbers.Real` :param angle: Apply the effect along this angle. :type angle: :class:`numbers.Real` .. versionadded:: 0.5.4 """ assertions.assert_real(radius=radius, sigma=sigma, angle=angle) if channel is None: r = library.MagickMotionBlurImage(self.wand, radius, sigma, angle) else: ch_const = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickMotionBlurImageChannel(self.wand, ch_const, radius, sigma, angle) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_const) r = library.MagickMotionBlurImage(self.wand, radius, sigma, angle) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return r @manipulative @trap_exception def negate(self, grayscale=False, channel=None): """Negate the colors in the reference image. :param grayscale: if set, only negate grayscale pixels in the image. :type grayscale: :class:`bool` :param channel: the channel type. available values can be found in the :const:`CHANNELS` mapping. If ``None``, negate all channels. :type channel: :class:`basestring` .. versionadded:: 0.3.8 """ if channel is None: r = library.MagickNegateImage(self.wand, grayscale) else: ch_const = self._channel_to_mask(channel) if library.MagickNegateImageChannel: r = library.MagickNegateImageChannel(self.wand, ch_const, grayscale) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_const) r = library.MagickNegateImage(self.wand, grayscale) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return r @manipulative @trap_exception def noise(self, noise_type='uniform', attenuate=1.0, channel=None): """Adds noise to image. :see: Example of :ref:`noise`. :param noise_type: type of noise to apply. See :const:`NOISE_TYPES`. :type noise_type: :class:`basestring` :param attenuate: rate of distribution. Only available in ImageMagick-7. Default is ``1.0``. :type attenuate: :class:`numbers.Real` :param channel: Optionally target a color channel to apply noise to. See :const:`CHANNELS`. :type channel: :class:`basestring` .. versionadded:: 0.5.3 .. versionchanged:: 0.5.5 Added optional ``channel`` argument. """ assertions.string_in_list(NOISE_TYPES, 'wand.image.NOISE_TYPES', noise_type=noise_type) assertions.assert_real(attenuate=attenuate) noise_type_idx = NOISE_TYPES.index(noise_type) if MAGICK_VERSION_NUMBER < 0x700: if channel is None: r = library.MagickAddNoiseImage(self.wand, noise_type_idx) else: channel_ch = self._channel_to_mask(channel) r = library.MagickAddNoiseImageChannel(self.wand, channel_ch, noise_type_idx) else: # pragma: no cover if channel is None: r = library.MagickAddNoiseImage(self.wand, noise_type_idx, attenuate) else: channel_ch = self._channel_to_mask(channel) mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickAddNoiseImage(self.wand, noise_type_idx, attenuate) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def normalize(self, channel=None): """Normalize color channels. :param channel: the channel type. available values can be found in the :const:`CHANNELS` mapping. If ``None``, normalize all channels. :type channel: :class:`basestring` """ if channel is None: r = library.MagickNormalizeImage(self.wand) else: ch_const = self._channel_to_mask(channel) if library.MagickNormalizeImageChannel: r = library.MagickNormalizeImageChannel(self.wand, ch_const) else: # pragma: no cover with Image(image=self) as mask: # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(mask.wand, ch_const) r = library.MagickNormalizeImage(mask.wand) # Restore original state of channels. library.MagickSetImageChannelMask(mask.wand, channel_mask) # Copy adjusted mask over original value. copy_mask = COMPOSITE_OPERATORS.index('copy_' + channel) library.MagickCompositeImage(self.wand, mask.wand, copy_mask, False, 0, 0) return r @manipulative @trap_exception def oil_paint(self, radius=0.0, sigma=0.0): """Simulates an oil painting by replace each pixel with most frequent surrounding color. :param radius: The size of the surrounding neighbors. :type radius: :class:`numbers.Real` :param sigma: The standard deviation used by the Gaussian operator. This is only available with ImageMagick-7. :type sigma: :class:`numbers.Real` .. versionadded:: 0.5.4 """ assertions.assert_real(radius=radius, sigma=sigma) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickOilPaintImage(self.wand, radius) else: # pragma: no cover r = library.MagickOilPaintImage(self.wand, radius, sigma) return r @manipulative @trap_exception def opaque_paint(self, target=None, fill=None, fuzz=0.0, invert=False, channel=None): """Replace any color that matches ``target`` with ``fill``. Use ``fuzz`` to control the threshold of the target match. The ``invert`` will replace all colors *but* the pixels matching the ``target`` color. :param target: The color to match. :type target: :class:`wand.color.Color` :param fill: The color to paint with. :type fill: :class:`wand.color.Color` :param fuzz: Normalized real number between `0.0` and :attr:`quantum_range`. Default is `0.0`. :type fuzz: class:`numbers.Real` :param invert: Replace all colors that do not match target. Default is ``False``. :type invert: :class:`bool` :param channel: Optional color channel to target. See :const:`CHANNELS` :type channel: :class:`basestring` .. versionadded:: 0.5.4 .. versionchanged:: 0.5.5 Added ``channel`` parameter. """ if isinstance(target, string_type): target = Color(target) if isinstance(fill, string_type): fill = Color(fill) assertions.assert_color(target=target, fill=fill) assertions.assert_real(fuzz=fuzz) assertions.assert_bool(invert=invert) with target: with fill: if channel is None: r = library.MagickOpaquePaintImage(self.wand, target.resource, fill.resource, fuzz, invert) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickOpaquePaintImageChannel( self.wand, channel_ch, target.resource, fill.resource, fuzz, invert ) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickOpaquePaintImage(self.wand, target.resource, fill.resource, fuzz, invert) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def optimize_layers(self): """Attempts to crop each frame to the smallest image without altering the animation. For best results, call :meth:`Image.coalesce() ` before manipulating any frames. For timing accuracy, any :attr:`SingleImage.delay ` overwrites must be applied after optimizing layers. .. note:: This will only affect ``GIF`` image formats. .. versionadded:: 0.5.0 """ r = library.MagickOptimizeImageLayers(self.wand) if r: self.wand = r self.reset_sequence() return bool(r) @manipulative @trap_exception def optimize_transparency(self): """Iterates over frames, and sets transparent values for each pixel unchanged by previous frame. .. note:: This will only affect ``GIF`` image formats. .. versionadded:: 0.5.0 """ if library.MagickOptimizeImageTransparency: return library.MagickOptimizeImageTransparency(self.wand) else: # pragma: no cover raise AttributeError('`MagickOptimizeImageTransparency\' not ' 'available on current version of MagickWand ' 'library.') @manipulative @trap_exception def ordered_dither(self, threshold_map='threshold', channel=None): """Executes a ordered-based dither operations based on predetermined threshold maps. +-----------+-------+-----------------------------+ | Map | Alias | Description | +===========+=======+=============================+ | threshold | 1x1 | Threshold 1x1 (non-dither) | +-----------+-------+-----------------------------+ | checks | 2x1 | Checkerboard 2x1 (dither) | +-----------+-------+-----------------------------+ | o2x2 | 2x2 | Ordered 2x2 (dispersed) | +-----------+-------+-----------------------------+ | o3x3 | 3x3 | Ordered 3x3 (dispersed) | +-----------+-------+-----------------------------+ | o4x4 | 4x4 | Ordered 4x4 (dispersed) | +-----------+-------+-----------------------------+ | o8x8 | 8x8 | Ordered 8x8 (dispersed) | +-----------+-------+-----------------------------+ | h4x4a | 4x1 | Halftone 4x4 (angled) | +-----------+-------+-----------------------------+ | h6x6a | 6x1 | Halftone 6x6 (angled) | +-----------+-------+-----------------------------+ | h8x8a | 8x1 | Halftone 8x8 (angled) | +-----------+-------+-----------------------------+ | h4x4o | | Halftone 4x4 (orthogonal) | +-----------+-------+-----------------------------+ | h6x6o | | Halftone 6x6 (orthogonal) | +-----------+-------+-----------------------------+ | h8x8o | | Halftone 8x8 (orthogonal) | +-----------+-------+-----------------------------+ | h16x16o | | Halftone 16x16 (orthogonal) | +-----------+-------+-----------------------------+ | c5x5b | c5x5 | Circles 5x5 (black) | +-----------+-------+-----------------------------+ | c5x5w | | Circles 5x5 (white) | +-----------+-------+-----------------------------+ | c6x6b | c6x6 | Circles 6x6 (black) | +-----------+-------+-----------------------------+ | c6x6w | | Circles 6x6 (white) | +-----------+-------+-----------------------------+ | c7x7b | c7x7 | Circles 7x7 (black) | +-----------+-------+-----------------------------+ | c7x7w | | Circles 7x7 (white) | +-----------+-------+-----------------------------+ :param threshold_map: Name of threshold dither to use, followed by optional arguments. :type threshold_map: :class:`basestring` :param channel: Optional argument to apply dither to specific color channel. See :const:`CHANNELS`. :type channel: :class:`basestring` .. versionadded:: 0.5.7 """ assertions.assert_string(threshold_map=threshold_map) bmap = binary(threshold_map) if MAGICK_VERSION_NUMBER <= 0x700: if channel is None: r = library.MagickOrderedPosterizeImage(self.wand, bmap) else: channel_ch = self._channel_to_mask(channel) r = library.MagickOrderedPosterizeImageChannel(self.wand, channel_ch, bmap) else: # pragma: no cover if channel is None: r = library.MagickOrderedDitherImage(self.wand, bmap) else: channel_ch = self._channel_to_mask(channel) mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickOrderedDitherImage(self.wand, bmap) library.MagickSetImageChannelMask(self.wand, mask) return r def parse_meta_geometry(self, geometry): """Helper method to translate geometry format, and calculate meta-characters against image dimensions. See "Image Geometry" definitions & examples for more info: https://imagemagick.org/script/command-line-processing.php#geometry :param geometry: user string following ImageMagick's geometry format. :type geometry: :class:`basestring` :returns: Calculated width, height, offset-x, & offset-y. :rtype: :class:`tuple` :raises ValueError: If given geometry can not be parsed. .. versionadded:: 0.5.6 """ assertions.assert_string(geometry=geometry) x = ctypes.c_ssize_t(0) y = ctypes.c_ssize_t(0) width = ctypes.c_size_t(self.width) height = ctypes.c_size_t(self.height) r = libmagick.ParseMetaGeometry(binary(geometry), ctypes.byref(x), ctypes.byref(y), ctypes.byref(width), ctypes.byref(height)) if not bool(r): raise ValueError('Unable to parse geometry') return (width.value, height.value, x.value, y.value) def percent_escape(self, string_format): """Convenience method that expands ImageMagick's `Percent Escape`_ characters into image attribute values. .. _Percent Escape: https://imagemagick.org/script/escape.php .. code:: with wand.image import Image with Image(filename='tests/assets/sasha.jpg') as img: print(img.percent_escape('%f %wx%h')) #=> sasha.jpg 204x247 .. note:: Not all percent escaped values can be populated as I/O operations are managed by Python, and not the CLI utility. :param string_format: The prescient escaped string to be translated. :type string_format: :class:`basestring` :returns: String of expanded values. :rtype: :class:`basestring` .. versionadded:: 0.5.6 """ local_overwrites = { '%m': self.format, '%[magick]': self.format } for k, v in local_overwrites.items(): string_format = string_format.replace(k, v) self.options['format'] = string_format return text(self.make_blob('INFO')) @manipulative @trap_exception def polaroid(self, angle=0.0, caption=None, font=None, method='undefined'): """Creates a special effect simulating a Polaroid photo. :see: Example of :ref:`polaroid`. :param angle: applies a shadow effect along this angle. :type angle: :class:`numbers.Real` :param caption: Writes a message at the bottom of the photo's border. :type caption: :class:`basestring` :param font: Specify font style. :type font: :class:`wand.font.Font` :param method: Interpolation method. ImageMagick-7 only. :type method: :class:`basestring` .. versionadded:: 0.5.4 """ assertions.assert_real(angle=angle) assertions.string_in_list(PIXEL_INTERPOLATE_METHODS, 'wand.image.PIXEL_INTERPOLATE_METHODS', method=method) ctx_ptr = library.NewDrawingWand() if caption: assertions.assert_string(caption=caption) caption = binary(caption) library.MagickSetImageProperty(self.wand, b'Caption', caption) if isinstance(font, Font): if font.path: library.DrawSetFont(ctx_ptr, binary(font.path)) if font.size: library.DrawSetFontSize(ctx_ptr, font.size) if font.color: with font.color: library.DrawSetFillColor(ctx_ptr, font.color.resource) library.DrawSetTextAntialias(ctx_ptr, font.antialias) if font.stroke_color: with font.stroke_color: library.DrawSetStrokeColor(ctx_ptr, font.stroke_color.resource) if font.stroke_width: library.DrawSetStrokeWidth(ctx_ptr, font.stroke_width) elif font: raise TypeError('font must be in instance of ' 'wand.font.Font, not ' + repr(font)) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickPolaroidImage(self.wand, ctx_ptr, angle) else: # pragma: no cover method_idx = PIXEL_INTERPOLATE_METHODS.index(method) r = library.MagickPolaroidImage(self.wand, ctx_ptr, caption, angle, method_idx) ctx_ptr = library.DestroyDrawingWand(ctx_ptr) return r @manipulative @trap_exception def polynomial(self, arguments): """Replace image with the sum of all images in a sequence by calculating the pixel values a coefficient-weight value, and a polynomial-exponent. For example:: with Image(filename='rose:') as img: img.polynomial(arguments=[0.5, 1.0]) The output image will be calculated as: .. math:: output = 0.5 * image ^ {1.0} This can work on multiple images in a sequence by calculating across each frame in the image stack. .. code:: with Image(filename='2frames.gif') as img: img.polynomial(arguments=[0.5, 1.0, 0.25, 1.25]) Where the results would be calculated as: .. math:: output = 0.5 * frame1 ^ {1.0} + 0.25 * frame2 ^ {1.25} .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. :param arguments: A list of real numbers where at least two numbers (weight & exponent) are need for each image in the sequence. :type arguments: :class:`collections.abc.Sequence` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.5 """ if library.MagickPolynomialImage is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) if not isinstance(arguments, abc.Sequence): raise TypeError('expected sequence of doubles, not ' + repr(arguments)) argc = len(arguments) argv = (ctypes.c_double * argc)(*arguments) return library.MagickPolynomialImage(self.wand, (argc >> 1), argv) @manipulative @trap_exception def posterize(self, levels=None, dither='no'): """Reduce color levels per channel. :param levels: Number of levels per channel. :type levels: :class:`numbers.Integral` :param dither: Dither method to apply. See :const:`DITHER_METHODS`. :type dither: `basestring` .. versionadded:: 0.5.0 """ assertions.assert_integer(levels=levels) assertions.string_in_list(DITHER_METHODS, 'wand.image.DITHER_METHODS', dither=dither) dither_idx = DITHER_METHODS.index(dither) return library.MagickPosterizeImage(self.wand, levels, dither_idx) @manipulative @trap_exception def quantize(self, number_colors, colorspace_type=None, treedepth=0, dither=False, measure_error=False): """`quantize` analyzes the colors within a sequence of images and chooses a fixed number of colors to represent the image. The goal of the algorithm is to minimize the color difference between the input and output image while minimizing the processing time. :param number_colors: The target number of colors to reduce the image. :type number_colors: :class:`numbers.Integral` :param colorspace_type: Available value can be found in the :const:`COLORSPACE_TYPES`. Defaults :attr:`colorspace`. :type colorspace_type: :class:`basestring` :param treedepth: A value between ``0`` & ``8`` where ``0`` will allow ImageMagick to calculate the optimal depth with ``Log4(number_colors)``. Default value is ``0``. :type treedepth: :class:`numbers.Integral` :param dither: Perform dither operation between neighboring pixel values. If using ImageMagick-6, this can be a value of ``True``, or ``False``. With ImageMagick-7, use a string from :const:`DITHER_METHODS`. Default ``False``. :type dither: :class:`bool`, or :class:`basestring` :param measure_error: Include total quantization error of all pixels in an image & quantized value. :type measure_error: :class:`bool` .. versionadded:: 0.4.2 .. versionchanged:: 0.5.9 Fixed ImageMagick-7 ``dither`` argument, and added keyword defaults. """ assertions.assert_integer(number_colors=number_colors) if colorspace_type is None: colorspace_type = self.colorspace assertions.string_in_list(COLORSPACE_TYPES, 'wand.image.COLORSPACE_TYPES', colorspace_type=colorspace_type) assertions.assert_integer(treedepth=treedepth) if MAGICK_VERSION_NUMBER < 0x700: assertions.assert_bool(dither=dither) else: # pragma: no cover if dither is False: dither = 'no' elif dither is True: dither = 'riemersma' assertions.string_in_list(DITHER_METHODS, 'wand.image.DITHER_METHODS', dither=dither) dither = DITHER_METHODS.index(dither) assertions.assert_bool(measure_error=measure_error) return library.MagickQuantizeImage( self.wand, number_colors, COLORSPACE_TYPES.index(colorspace_type), treedepth, dither, measure_error ) @manipulative @trap_exception def random_threshold(self, low=0.0, high=1.0, channel=None): """Performs a random dither to force a pixel into a binary black & white state. Each color channel operarates independently from each other. :param low: bottom threshold. Any pixel value below the given value will be rendered "0", or no value. Given threshold value can be between ``0.0`` & ``1.0``, or ``0`` & :attr:`quantum_range`. :type low: :class:`numbers.Real` :param high: top threshold. Any pixel value above the given value will be rendered as max quantum value. Given threshold value can be between ``0.0`` & ``1.0``, or ``0`` & :attr:`quantum_range`. :type high: :class:`numbers.Real` :param channel: Optional argument to apply dither to specific color channel. See :const:`CHANNELS`. :type channel: :class:`basestring` .. versionadded:: 0.5.7 """ assertions.assert_real(low=low, high=high) if 0 < low <= 1.0: low *= self.quantum_range if 0 < high <= 1.0: high *= self.quantum_range if channel is None: r = library.MagickRandomThresholdImage(self.wand, low, high) else: ch_channel = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickRandomThresholdImageChannel(self.wand, ch_channel, low, high) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_channel) r = library.MagickRandomThresholdImage(self.wand, low, high) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return r def range_channel(self, channel='default_channels'): """Calculate the minimum and maximum of quantum values in image. .. code:: python from wand.image import Image with Image(filename='input.jpg') as img: minima, maxima = img.range_channel() :param channel: Select which color channel to evaluate. See :const:`CHANNELS`. Default ``'default_channels'``. :type channel: :class:`basestring` :returns: Tuple of :attr:`minima` & :attr:`maxima` values. Each value will be between 0.0 & :attr:`quantum_range`. :rtype: :class:`tuple` .. versionadded:: 0.5.3 """ ch_channel = self._channel_to_mask(channel) min_color = ctypes.c_double(0.0) max_color = ctypes.c_double(0.0) if MAGICK_VERSION_NUMBER < 0x700: library.MagickGetImageChannelRange(self.wand, ch_channel, ctypes.byref(min_color), ctypes.byref(max_color)) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, ch_channel) library.MagickGetImageRange(self.wand, ctypes.byref(min_color), ctypes.byref(max_color)) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return min_color.value, max_color.value @manipulative @trap_exception def range_threshold(self, low_black=0.0, low_white=None, high_white=None, high_black=None): """Applies soft & hard thresholding. For a soft thresholding, parameters should be monotonically increasing: with Image(filename='text.png') as img: img.range_threshold(0.2, 0.4, 0.6, 0.8) For a hard thresholding, parameters should be the same: with Image(filename='text.png') as img: img.range_threshold(0.4, 0.4, 0.6, 0.6) .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. :param low_black: Define the minimum threshold value. :type low_black: :class:`numbers.Real` :param low_white: Define the minimum threshold value. :type low_white: :class:`numbers.Real` :param high_white: Define the maximum threshold value. :type high_white: :class:`numbers.Real` :param high_black: Define the maximum threshold value. :type high_black: :class:`numbers.Real` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.5 """ if library.MagickRangeThresholdImage is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) # Populate defaults to follow CLI behavior if low_white is None: low_white = low_black if high_white is None: high_white = low_white if high_black is None: high_black = high_white assertions.assert_real(low_black=low_black, low_white=low_white, high_white=high_white, high_black=high_black) if 0 < low_black <= 1.0: low_black *= self.quantum_range if 0 < low_white <= 1.0: low_white *= self.quantum_range if 0 < high_white <= 1.0: high_white *= self.quantum_range if 0 < high_black <= 1.0: high_black *= self.quantum_range return library.MagickRangeThresholdImage(self.wand, low_black, low_white, high_white, high_black) @trap_exception def read_mask(self, clip_mask=None): """Sets the read mask where the gray values of the clip mask are used to blend during composite operations. Call this method with a ``None`` argument to clear any previously set masks. This method is also useful for :meth:`compare` method for limiting region of interest. .. warning:: This method is only available with ImageMagick-7. :param clip_mask: Image to reference as blend mask. :type clip_mask: :class:`BaseImage` .. versionadded:: 0.5.7 """ r = False ReadPixelMask = 0x000001 if library.MagickSetImageMask is None: raise WandLibraryVersionError('Method requires ImageMagick-7.') else: # pragma: no cover if clip_mask is None: r = library.MagickSetImageMask(self.wand, ReadPixelMask, None) elif isinstance(clip_mask, BaseImage): r = library.MagickSetImageMask(self.wand, ReadPixelMask, clip_mask.wand) return r def region(self, width=None, height=None, x=None, y=None, gravity=None): """Extract an area of the image. This is the same as :meth:`crop`, but returns a new instance of :class:`Image` without altering the original source image. .. code-block:: python from wand.image import Image with Image(filename='input.jpg') as img: with img.region(width=100, height=100, x=0, y=0) as area: pass :param width: Area size on the X-axis. Default value is the image's :attr:`page_width`. :type width: :class:`numbers.Integral` :param height: Area size on the Y-axis.Default value is the image's :attr:`page_height`. :type height: :class:`numbers.Integral` :param x: X-axis offset. This number can be negative. Default value is the image's :attr:`page_x`. :type x: :class:`numbers.Integral` :param y: Y-axis offset. This number can be negative. Default value is the image's :attr:`page_y`. :type y: :class:`numbers.Integral` :param region: Helper attribute to set ``x`` & ``y`` offset. See :const:`GRAVITY_TYPES`. :type region: :class:`basestring` :returns: New instance of Wand. :rtype: :class:`Image` .. versionadded:: 0.6.8 """ ow, oh, ox, oy = self.page if width is None: width = ow if height is None: height = oh assertions.assert_unsigned_integer(width=width, height=height) if gravity is not None: if x is not None or y is not None: raise ValueError('x & y can not be used with gravity.') y, x = self._gravity_to_offset(gravity, width, height) if x is None: x = ox if y is None: y = oy assertions.assert_integer(x=x, y=y) new_wand = library.MagickGetImageRegion(self.wand, width, height, x, y) if not new_wand: self.raise_exception() return Image(BaseImage(new_wand)) @manipulative @trap_exception def remap(self, affinity=None, method='no'): """Rebuild image palette with closest color from given affinity image. :see: Example of :ref:`remap`. :param affinity: reference image. :type affinity: :class:`BaseImage` :param method: dither method. See :const:`DITHER_METHODS`. Default is ``'no'`` dither. :type method: :class:`basestring` .. versionadded:: 0.5.3 """ if not isinstance(affinity, BaseImage): raise TypeError('Expecting affinity to be a BaseImage, not ' + repr(affinity)) assertions.string_in_list(DITHER_METHODS, 'wand.image.DITHER_METHODS', method=method) method_idx = DITHER_METHODS.index(method) return library.MagickRemapImage(self.wand, affinity.wand, method_idx) @manipulative @trap_exception def resample(self, x_res=None, y_res=None, filter='undefined', blur=1): """Adjust the number of pixels in an image so that when displayed at the given Resolution or Density the image will still look the same size in real world terms. .. note:: This method will automatically :meth:`coalesce` & resample all frames in a GIF animation. For other image formats, :meth:`resample` will only effect the current image in the stack. Use :meth:`iterator_reset` & :meth:`iterator_next` to traverse the image stack to resample all images in a multi-layer document. .. code:: with Image(filename='input.tiff') as img: img.iterator_reset() while True: img.resample(128, 128) if not img.iterator_next(): break :param x_res: the X resolution (density) in the scaled image. default is the original resolution. :type x_res: :class:`numbers.Real` :param y_res: the Y resolution (density) in the scaled image. default is the original resolution. :type y_res: :class:`numbers.Real` :param filter: a filter type to use for resizing. choose one in :const:`FILTER_TYPES`. default is ``'undefined'`` which means IM will try to guess best one to use. :type filter: :class:`basestring`, :class:`numbers.Integral` :param blur: the blur factor where > 1 is blurry, < 1 is sharp. default is 1 :type blur: :class:`numbers.Real` .. versionadded:: 0.4.5 """ if x_res is None: x_res, _ = self.resolution if y_res is None: _, y_res = self.resolution assertions.assert_real(x_res=x_res, y_res=y_res, blur=blur) if x_res < 1: raise ValueError('x_res must be a Real number, not ' + repr(x_res)) elif y_res < 1: raise ValueError('y_res must be a Real number, not ' + repr(y_res)) elif not isinstance(filter, (string_type, numbers.Integral)): raise TypeError('filter must be one string defined in wand.image.' 'FILTER_TYPES or an integer, not ' + repr(filter)) if isinstance(filter, string_type): try: filter = FILTER_TYPES.index(filter) except IndexError: raise ValueError(repr(filter) + ' is an invalid filter type; ' 'choose on in ' + repr(FILTER_TYPES)) elif (isinstance(filter, numbers.Integral) and not (0 <= filter < len(FILTER_TYPES))): raise ValueError(repr(filter) + ' is an invalid filter type') blur = ctypes.c_double(float(blur)) if self.animation: self.wand = library.MagickCoalesceImages(self.wand) self.reset_sequence() library.MagickSetLastIterator(self.wand) n = library.MagickGetIteratorIndex(self.wand) library.MagickResetIterator(self.wand) for i in xrange(n + 1): library.MagickSetIteratorIndex(self.wand, i) r = library.MagickResampleImage(self.wand, x_res, y_res, filter, blur) else: r = library.MagickResampleImage(self.wand, x_res, y_res, filter, blur) return r def reset_coords(self): """Reset the coordinate frame of the image so to the upper-left corner is (0, 0) again (crop and rotate operations change it). .. versionadded:: 0.2.0 """ library.MagickResetImagePage(self.wand, None) def reset_sequence(self): """Abstract method prototype. See :meth:`wand.image.Image.reset_sequence()`. .. versionadded:: 0.6.0 """ pass @manipulative @trap_exception def resize(self, width=None, height=None, filter='undefined', blur=1): """Resizes the image. :param width: the width in the scaled image. default is the original width :type width: :class:`numbers.Integral` :param height: the height in the scaled image. default is the original height :type height: :class:`numbers.Integral` :param filter: a filter type to use for resizing. choose one in :const:`FILTER_TYPES`. default is ``'undefined'`` which means IM will try to guess best one to use :type filter: :class:`basestring`, :class:`numbers.Integral` :param blur: the blur factor where > 1 is blurry, < 1 is sharp. default is 1 :type blur: :class:`numbers.Real` .. versionchanged:: 0.2.1 The default value of ``filter`` has changed from ``'triangle'`` to ``'undefined'`` instead. .. versionchanged:: 0.1.8 The ``blur`` parameter changed to take :class:`numbers.Real` instead of :class:`numbers.Rational`. .. versionadded:: 0.1.1 """ if width is None: width = self.width if height is None: height = self.height assertions.assert_counting_number(width=width, height=height) assertions.assert_real(blur=blur) if not isinstance(filter, (string_type, numbers.Integral)): raise TypeError('filter must be one string defined in wand.image.' 'FILTER_TYPES or an integer, not ' + repr(filter)) if isinstance(filter, string_type): try: filter = FILTER_TYPES.index(filter) except IndexError: raise ValueError(repr(filter) + ' is an invalid filter type; ' 'choose on in ' + repr(FILTER_TYPES)) elif (isinstance(filter, numbers.Integral) and not (0 <= filter < len(FILTER_TYPES))): raise ValueError(repr(filter) + ' is an invalid filter type') blur = ctypes.c_double(float(blur)) if self.animation: self.wand = library.MagickCoalesceImages(self.wand) self.reset_sequence() library.MagickSetLastIterator(self.wand) n = library.MagickGetIteratorIndex(self.wand) library.MagickResetIterator(self.wand) for i in xrange(n + 1): library.MagickSetIteratorIndex(self.wand, i) r = library.MagickResizeImage(self.wand, width, height, filter, blur) library.MagickSetSize(self.wand, width, height) else: r = library.MagickResizeImage(self.wand, width, height, filter, blur) library.MagickSetSize(self.wand, width, height) return r @manipulative @trap_exception def roll(self, x=0, y=0): """Shifts all pixels over by an X/Y offset. :param x: Number of columns to roll over. Negative value will roll pixels from right-to-left, and positive value will roll pixels from left-to-right. Default value: ``0``. :type x: :class:`numbers.Integral` :param y: Number of rows to roll over. Negative value will roll pixels from bottom-to-top, and positive value will roll pixels from top-to-bottm. Default value: ``0``. :type y: :class:`numbers.Integral` .. versionadded:: 0.6.8 """ assertions.assert_integer(x=x, y=y) return library.MagickRollImage(self.wand, x, y) @manipulative @trap_exception def rotate(self, degree, background=None, reset_coords=True): """Rotates the image right. It takes a ``background`` color for ``degree`` that isn't a multiple of 90. :see: Example of :ref:`rotate`. :param degree: a degree to rotate. multiples of 360 affect nothing :type degree: :class:`numbers.Real` :param background: an optional background color. default is transparent :type background: :class:`wand.color.Color` :param reset_coords: optional flag. If set, after the rotation, the coordinate frame will be relocated to the upper-left corner of the new image. By default is `True`. :type reset_coords: :class:`bool` .. versionadded:: 0.2.0 The ``reset_coords`` parameter. .. versionadded:: 0.1.8 """ if background is None: background = Color('transparent') elif isinstance(background, string_type): background = Color(background) assertions.assert_color(background=background) assertions.assert_real(degree=degree) with background: if self.animation: self.wand = library.MagickCoalesceImages(self.wand) self.reset_sequence() library.MagickSetLastIterator(self.wand) n = library.MagickGetIteratorIndex(self.wand) library.MagickResetIterator(self.wand) for i in xrange(0, n + 1): library.MagickSetIteratorIndex(self.wand, i) result = library.MagickRotateImage(self.wand, background.resource, degree) if reset_coords: library.MagickResetImagePage(self.wand, None) else: result = library.MagickRotateImage(self.wand, background.resource, degree) if reset_coords: self.reset_coords() return result @manipulative @trap_exception def rotational_blur(self, angle=0.0, channel=None): """Blur an image in a radius around the center of an image. .. warning:: Requires ImageMagick-6.8.8 or greater. :see: Example of :ref:`rotational_blur`. :param angle: Degrees of rotation to blur with. :type angle: :class:`numbers.Real` :param channel: Optional channel to apply the effect against. See :const:`CHANNELS` for a list of possible values. :type channel: :class:`basestring` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.4 """ if not library.MagickRotationalBlurImage: # pragma: no cover msg = ("Method `rotational_blur` not available on installed " "version of ImageMagick library. ") raise WandLibraryVersionError(msg) assertions.assert_real(angle=angle) if channel: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickRotationalBlurImageChannel(self.wand, channel_ch, angle) else: # pragma: no cover channel_mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickRotationalBlurImage(self.wand, angle) library.MagickSetImageChannelMask(self.wand, channel_mask) else: r = library.MagickRotationalBlurImage(self.wand, angle) return r @manipulative @trap_exception def sample(self, width=None, height=None): """Resizes the image by sampling the pixels. It's basically quicker than :meth:`resize()` except less quality as a trade-off. :param width: the width in the scaled image. default is the original width :type width: :class:`numbers.Integral` :param height: the height in the scaled image. default is the original height :type height: :class:`numbers.Integral` .. versionadded:: 0.3.4 """ if width is None: width = self.width if height is None: height = self.height assertions.assert_counting_number(width=width, height=height) if self.animation: self.wand = library.MagickCoalesceImages(self.wand) self.reset_sequence() library.MagickSetLastIterator(self.wand) n = library.MagickGetIteratorIndex(self.wand) library.MagickResetIterator(self.wand) for i in xrange(n + 1): library.MagickSetIteratorIndex(self.wand, i) r = library.MagickSampleImage(self.wand, width, height) library.MagickSetSize(self.wand, width, height) else: r = library.MagickSampleImage(self.wand, width, height) library.MagickSetSize(self.wand, width, height) return bool(r) @manipulative @trap_exception def scale(self, columns=1, rows=1): """Increase image size by scaling each pixel value by given ``columns`` and ``rows``. :param columns: The number of columns, in pixels, to scale the image horizontally. :type columns: :class:`numbers.Integral` :param rows: The number of rows, in pixels, to scale the image vertically. :type rows: :class:`numbers.Integral` .. versionadded:: 0.5.7 """ assertions.assert_counting_number(columns=columns, rows=rows) return library.MagickScaleImage(self.wand, columns, rows) @manipulative @trap_exception def selective_blur(self, radius=0.0, sigma=0.0, threshold=0.0, channel=None): """Blur an image within a given threshold. For best effects, use a value between 10% and 50% of :attr:`quantum_range` .. code:: from wand.image import Image with Image(filename='photo.jpg') as img: # Apply 8x3 blur with a 10% threshold img.selective_blur(8.0, 3.0, 0.1 * img.quantum_range) :see: Example of :ref:`selective_blur`. :param radius: Size of gaussian aperture. :type radius: :class:`numbers.Real` :param sigma: Standard deviation of gaussian operator. :type sigma: :class:`numbers.Real` :param threshold: Only pixels within contrast threshold are effected. Value should be between ``0.0`` and :attr:`quantum_range`. :type threshold: :class:`numbers.Real` :param channel: Optional color channel to target. See :const:`CHANNELS` :type channel: :class:`basestring` .. versionadded:: 0.5.3 .. versionchanged:: 0.5.5 Added ``channel`` argument. """ assertions.assert_real(radius=radius, sigma=sigma, threshold=threshold) if channel is None: r = library.MagickSelectiveBlurImage(self.wand, radius, sigma, threshold) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickSelectiveBlurImageChannel(self.wand, channel_ch, radius, sigma, threshold) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickSelectiveBlurImage(self.wand, radius, sigma, threshold) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def sepia_tone(self, threshold=0.8): """Creates a Sepia Tone special effect similar to a darkroom chemical toning. :see: Example of :ref:`sepia_tone`. :param threshold: The extent of the toning. Value can be between ``0`` & :attr:`quantum_range`, or ``0`` & ``1.0``. Default value is ``0.8`` or "80%". :type threshold: :class:`numbers.Real` .. versionadded:: 0.5.7 """ assertions.assert_real(threshold=threshold) if 0.0 < threshold <= 1.0: threshold *= self.quantum_range return library.MagickSepiaToneImage(self.wand, threshold) @manipulative @trap_exception def shade(self, gray=False, azimuth=0.0, elevation=0.0): """Creates a 3D effect by simulating a light from an elevated angle. :see: Example of :ref:`shade`. :param gray: Isolate the effect on pixel intensity. Default is False. :type gray: :class:`bool` :param azimuth: Angle from x-axis. :type azimuth: :class:`numbers.Real` :param elevation: Amount of pixels from the z-axis. :type elevation: :class:`numbers.Real` .. versionadded:: 0.5.0 """ assertions.assert_real(azimuth=azimuth, elevation=elevation) return library.MagickShadeImage(self.wand, gray, azimuth, elevation) @manipulative @trap_exception def shadow(self, alpha=0.0, sigma=0.0, x=0, y=0): """Generates an image shadow. :param alpha: Ratio of transparency. :type alpha: :class:`numbers.Real` :param sigma: Standard deviation of the gaussian filter. :type sigma: :class:`numbers.Real` :param x: x-offset. :type x: :class:`numbers.Integral` :param y: y-offset. :type y: :class:`numbers.Integral` .. versionadded:: 0.5.0 """ assertions.assert_real(alpha=alpha, sigma=sigma) assertions.assert_integer(x=x, y=y) return library.MagickShadowImage(self.wand, alpha, sigma, x, y) @manipulative @trap_exception def sharpen(self, radius=0.0, sigma=0.0, channel=None): """Applies a gaussian effect to enhance the sharpness of an image. .. note:: For best results, ensure ``radius`` is larger than ``sigma``. Defaults values of zero will have ImageMagick attempt to auto-select suitable values. :see: Example of :ref:`sharpen`. :param radius: size of gaussian aperture. :type radius: :class:`numbers.Real` :param sigma: Standard deviation of the gaussian filter. :type sigma: :class:`numbers.Real` :param channel: Optional color channel to target. See :const:`CHANNELS`. :type channel: :class:`basestring` .. versionadded:: 0.5.0 .. versionchanged:: 0.5.5 Added ``channel`` argument. """ assertions.assert_real(radius=radius, sigma=sigma) if channel is None: r = library.MagickSharpenImage(self.wand, radius, sigma) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickSharpenImageChannel(self.wand, channel_ch, radius, sigma) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickSharpenImage(self.wand, radius, sigma) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def shave(self, columns=0, rows=0): """Remove pixels from the edges. :param columns: amount to shave off both sides of the x-axis. :type columns: :class:`numbers.Integral` :param rows: amount to shave off both sides of the y-axis. :type rows: :class:`numbers.Integral` .. versionadded:: 0.5.0 """ assertions.assert_integer(columns=columns, row=rows) return library.MagickShaveImage(self.wand, columns, rows) @manipulative @trap_exception def shear(self, background='WHITE', x=0.0, y=0.0): """Shears the image to create a parallelogram, and fill the space created with a ``background`` color. :param background: Color to fill the void created by shearing the image. :type background: :class:`wand.color.Color` :param x: Slide the image along the X-axis. :type x: :class:`numbers.Real` :param y: Slide the image along the Y-axis. :type y: :class:`numbers.Real` .. versionadded:: 0.5.4 """ if isinstance(background, string_type): background = Color(background) assertions.assert_color(background=background) assertions.assert_real(x=x, y=y) with background: r = library.MagickShearImage(self.wand, background.resource, x, y) return r @manipulative @trap_exception def sigmoidal_contrast(self, sharpen=True, strength=0.0, midpoint=0.0, channel=None): """Modifies the contrast of the image by applying non-linear sigmoidal algorithm. .. code:: python with Image(filename='photo.jpg') as img: img.sigmoidal_contrast(sharpen=True, strength=3, midpoint=0.65 * img.quantum_range) :param sharpen: Increase the contrast when ``True`` (default), else reduces contrast. :type sharpen: :class:`bool` :param strength: How much to adjust the contrast. Where a value of ``0.0`` has no effect, ``3.0`` is typical, and ``20.0`` is extreme. :type strength: :class:`numbers.Real` :param midpoint: Normalized value between `0.0` & :attr:`quantum_range` :type midpoint: :class:`numbers.Real` :param channel: Optional color channel to target. See :const:`CHANNELS`. :type channel: :class:`basestring` .. versionadded:: 0.5.4 .. versionchanged:: 0.5.5 Added ``channel`` argument. """ assertions.assert_bool(sharpen=sharpen) assertions.assert_real(strength=strength, midpoint=midpoint) if channel is None: r = library.MagickSigmoidalContrastImage(self.wand, sharpen, strength, midpoint) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickSigmoidalContrastImageChannel( self.wand, channel_ch, sharpen, strength, midpoint ) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickSigmoidalContrastImage(self.wand, sharpen, strength, midpoint) library.MagickSetImageChannelMask(self.wand, mask) return r def similarity(self, reference, threshold=0.0, metric='undefined'): """Scan image for best matching ``reference`` image, and return location & similarity. Use parameter ``threshold`` to stop subimage scanning if the matching similarity value is below the given value. This is the same as the CLI ``-similarity-threshold`` option. This method will always return a location & the lowest computed similarity value. Users are responsible for checking the similarity value to determine if a matching location is valid. Traditionally, a similarity value greater than `0.3183099` is considered dissimilar. .. code:: python from wand.image import Image dissimilarity_threshold = 0.318 similarity_threshold = 0.05 with Image(filename='subject.jpg') as img: with Image(filename='object.jpg') as reference: location, diff = img.similarity(reference, similarity_threshold) if diff > dissimilarity_threshold: print('Images too dissimilar to match') elif diff <= similarity_threshold: print('First match @ {left}x{top}'.format(**location)) else: print('Best match @ {left}x{top}'.format(**location)) .. warning:: This operation can be slow to complete. :param reference: Image to search for. :type reference: :class:`wand.image.Image` :param threshold: Stop scanning if reference similarity is below given threshold. Value can be between ``0.0`` and :attr:`quantum_range`. Default is ``0.0``. :type threshold: :class:`numbers.Real` :param metric: specify which comparison algorithm to use. See :const:`COMPARE_METRICS` for a list of values. Only used by ImageMagick-7. :type metric: :class:`basestring` :returns: List of location & similarity value. Location being a dictionary of ``width``, ``height``, ``left``, & ``top``. The similarity value is the compare distance, so a value of ``0.0`` means an exact match. :rtype: :class:`tuple` (:class:`dict`, :class:`numbers.Real`) .. versionadded:: 0.5.4 has been added. """ assertions.assert_real(threshold=threshold) if not isinstance(reference, BaseImage): raise TypeError('reference must be in instance of ' 'wand.image.Image, not ' + repr(reference)) rio = RectangleInfo(0, 0, 0, 0) diff = ctypes.c_double(0.0) if MAGICK_VERSION_NUMBER < 0x700: artifact_value = binary(str(threshold)) # FIXME library.MagickSetImageArtifact(self.wand, b'compare:similarity-threshold', artifact_value) r = library.MagickSimilarityImage(self.wand, reference.wand, ctypes.byref(rio), ctypes.byref(diff)) else: # pragma: no cover assertions.string_in_list(COMPARE_METRICS, 'wand.image.COMPARE_METRICS', metric=metric) metric_idx = COMPARE_METRICS.index(metric) r = library.MagickSimilarityImage(self.wand, reference.wand, metric_idx, threshold, ctypes.byref(rio), ctypes.byref(diff)) if not r: # pragma: no cover self.raise_exception() else: r = library.DestroyMagickWand(r) location = dict(width=rio.width, height=rio.height, top=rio.y, left=rio.x) return (location, diff.value) @manipulative @trap_exception def sketch(self, radius=0.0, sigma=0.0, angle=0.0): """Simulates a pencil sketch effect. For best results, ``radius`` value should be larger than ``sigma``. :see: Example of :ref:`sketch`. :param radius: size of Gaussian aperture. :type radius: :class:`numbers.Real` :param sigma: standard deviation of the Gaussian operator. :type sigma: :class:`numbers.Real` :param angle: direction of blur. :type angle: :class:`numbers.Real` .. versionadded:: 0.5.3 """ assertions.assert_real(radius=radius, sigma=sigma, angle=angle) return library.MagickSketchImage(self.wand, radius, sigma, angle) @trap_exception def smush(self, stacked=False, offset=0): """Appends all images together. Similar behavior to :meth:`concat`, but with an optional offset between images. :param stacked: If True, will join top-to-bottom. If False, join images from left-to-right (default). :type stacked: :class:`bool` :param offset: Minimum space (in pixels) between each join. :type offset: :class:`numbers.Integral` .. versionadded:: 0.5.3 """ assertions.assert_integer(offset=offset) library.MagickResetIterator(self.wand) result = library.MagickSmushImages(self.wand, bool(stacked), offset) if result: self.wand = result self.reset_sequence() return bool(result) @manipulative @trap_exception def solarize(self, threshold=0.0, channel=None): """Simulates extreme overexposure. :see: Example of :ref:`solarize`. :param threshold: between ``0.0`` and :attr:`quantum_range`. :type threshold: :class:`numbers.Real` :param channel: Optional color channel to target. See :const:`CHANNELS` :type channel: :class:`basestring` .. versionadded:: 0.5.3 .. versionchanged:: 0.5.5 Added ``channel`` argument. """ assertions.assert_real(threshold=threshold) if channel is None: r = library.MagickSolarizeImage(self.wand, threshold) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickSolarizeImageChannel(self.wand, channel_ch, threshold) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickSolarizeImage(self.wand, threshold) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def sparse_color(self, method, colors, channel_mask=0x7): """Interpolates color values between points on an image. The ``colors`` argument should be a dict mapping :class:`~wand.color.Color` keys to coordinate tuples. For example:: from wand.color import Color from wand.image import Image colors = { Color('RED'): (10, 50), Color('YELLOW'): (174, 32), Color('ORANGE'): (74, 123) } with Image(filename='input.png') as img: img.sparse_color('bilinear', colors) The available interpolate methods are: - ``'barycentric'`` - ``'bilinear'`` - ``'shepards'`` - ``'voronoi'`` - ``'inverse'`` - ``'manhattan'`` You can control which color channels are effected by building a custom channel mask. For example:: from wand.image import Image, CHANNELS with Image(filename='input.png') as img: colors = { img[50, 50]: (50, 50), img[100, 50]: (100, 50), img[50, 75]: (50, 75), img[100, 100]: (100, 100) } # Only apply Voronoi to Red & Alpha channels mask = CHANNELS['red'] | CHANNELS['alpha'] img.sparse_color('voronoi', colors, channel_mask=mask) :param method: Interpolate method. See :const:`SPARSE_COLOR_METHODS` :type method: :class:`basestring` :param colors: A dictionary of :class:`~wand.color.Color` keys mapped to an (x, y) coordinate tuple. :type colors: :class:`abc.Mapping` { :class:`~wand.color.Color`: (int, int) } :param channel_mask: Isolate specific color channels to apply interpolation. Default to RGB channels. :type channel_mask: :class:`numbers.Integral` .. versionadded:: 0.5.3 """ assertions.string_in_list(SPARSE_COLOR_METHODS, 'wand.image.SPARSE_COLOR_METHODS', method=method) if not isinstance(colors, abc.Mapping): raise TypeError('Colors must be a dict, not' + repr(colors)) assertions.assert_unsigned_integer(channel_mask=channel_mask) method_idx = SPARSE_COLOR_METHODS[method] arguments = list() for color, point in colors.items(): if isinstance(color, string_type): color = Color(color) x, y = point arguments.append(x) arguments.append(y) with color as c: if channel_mask & CHANNELS['red']: arguments.append(c.red) if channel_mask & CHANNELS['green']: arguments.append(c.green) if channel_mask & CHANNELS['blue']: arguments.append(c.blue) if channel_mask & CHANNELS['alpha']: arguments.append(c.alpha) argc = len(arguments) args = (ctypes.c_double * argc)(*arguments) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickSparseColorImage(self.wand, channel_mask, method_idx, argc, args) else: # pragma: no cover # Set active channel, and capture mask to restore. channel_mask = library.MagickSetImageChannelMask(self.wand, channel_mask) r = library.MagickSparseColorImage(self.wand, method_idx, argc, args) # Restore original state of channels library.MagickSetImageChannelMask(self.wand, channel_mask) return r @manipulative @trap_exception def splice(self, width=None, height=None, x=None, y=None, gravity=None): """Partitions image by splicing a ``width`` x ``height`` rectangle at (``x``, ``y``) offset coordinate. The space inserted will be replaced by the :attr:`background_color` value. :param width: number of pixel columns. :type width: :class:`numbers.Integral` :param height: number of pixel rows. :type height: :class:`numbers.Integral` :param x: offset on the X-axis. :type x: :class:`numbers.Integral` :param y: offset on the Y-axis. :type y: :class:`numbers.Integral` .. versionadded:: 0.5.3 """ ow, oh = self.size if width is None: width = ow if height is None: height = oh assertions.assert_unsigned_integer(width=width, height=height) if gravity is None: if x is None: x = 0 if y is None: y = 0 else: if x is not None or y is not None: raise ValueError('x & y can not be used with gravity.') y, x = self._gravity_to_offset(gravity, width, height) assertions.assert_integer(x=x, y=y) return library.MagickSpliceImage(self.wand, width, height, x, y) @manipulative @trap_exception def spread(self, radius=0.0, method='undefined'): """Randomly displace pixels within a defined radius. :see: Example of :ref:`spread`. :param radius: Distance a pixel can be displaced from source. Default value is ``0.0``, which will allow ImageMagick to auto select a radius. :type radius: :class:`numbers.Real` :param method: Interpolation method. Only available with ImageMagick-7. See :const:`PIXEL_INTERPOLATE_METHODS`. .. versionadded:: 0.5.3 .. versionchanged:: 0.5.7 Added default value to ``radius``. """ assertions.assert_real(radius=radius) assertions.string_in_list(PIXEL_INTERPOLATE_METHODS, 'wand.image.PIXEL_INTERPOLATE_METHODS', method=method) method_idx = PIXEL_INTERPOLATE_METHODS.index(method) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickSpreadImage(self.wand, radius) else: # pragma: no cover r = library.MagickSpreadImage(self.wand, method_idx, radius) return r @manipulative @trap_exception def statistic(self, stat='undefined', width=None, height=None, channel=None): """Replace each pixel with the statistic results from neighboring pixel values. The ``width`` & ``height`` defines the size, or aperture, of the neighboring pixels. :see: Example of :ref:`statistic`. :param stat: The type of statistic to calculate. See :const:`STATISTIC_TYPES`. :type stat: :class:`basestring` :param width: The size of neighboring pixels on the X-axis. :type width: :class:`numbers.Integral` :param height: The size of neighboring pixels on the Y-axis. :type height: :class:`numbers.Integral` :param channel: Optional color channel to target. See :const:`CHANNELS` :type channel: :class:`basestring` .. versionadded:: 0.5.3 .. versionchanged:: 0.5.5 Added optional ``channel`` argument. """ assertions.string_in_list(STATISTIC_TYPES, 'wand.image.STATISTIC_TYPES', statistic=stat) assertions.assert_integer(width=width, height=height) stat_idx = STATISTIC_TYPES.index(stat) if channel is None: r = library.MagickStatisticImage(self.wand, stat_idx, width, height) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickStatisticImageChannel(self.wand, channel_ch, stat_idx, width, height) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickStatisticImage(self.wand, stat_idx, width, height) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def stegano(self, watermark, offset=0): """Hide a digital watermark of an image within the image. .. code-block:: python from wand.image import Image # Embed watermark with Image(filename='source.png') as img: with Image(filename='gray_watermark.png') as watermark: print('watermark size (for recovery)', watermark.size) img.stegano(watermark) img.save(filename='public.png') # Recover watermark with Image(width=w, height=h, pseudo='stegano:public.png') as img: img.save(filename='recovered_watermark.png') :param watermark: Image to hide within image. :type watermark: :class:`wand.image.Image` :param offset: Start embedding image after a number of pixels. :type offset: :class:`numbers.Integral` .. versionadded:: 0.5.4 """ if not isinstance(watermark, BaseImage): raise TypeError('Watermark image must be in instance of ' 'wand.image.Image, not ' + repr(watermark)) assertions.assert_integer(offset=offset) new_wand = library.MagickSteganoImage(self.wand, watermark.wand, offset) if new_wand: self.wand = new_wand self.reset_sequence() return bool(new_wand) @trap_exception def strip(self): """Strips an image of all profiles and comments. .. versionadded:: 0.2.0 """ return library.MagickStripImage(self.wand) @manipulative @trap_exception def swirl(self, degree=0.0, method="undefined"): """Swirls pixels around the center of the image. The larger the degree the more pixels will be effected. :see: Example of :ref:`swirl`. :param degree: Defines the amount of pixels to be effected. Value between ``-360.0`` and ``360.0``. :type degree: :class:`numbers.Real` :param method: Controls interpolation of the effected pixels. Only available for ImageMagick-7. See :const:`PIXEL_INTERPOLATE_METHODS`. :type method: :class:`basestring` .. versionadded:: 0.5.7 """ assertions.assert_real(degree=degree) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickSwirlImage(self.wand, degree) else: # pragma: no cover assertions.string_in_list(PIXEL_INTERPOLATE_METHODS, 'wand.image.PIXEL_INTERPOLATE_METHODS', method=method) method_idx = PIXEL_INTERPOLATE_METHODS.index(method) r = library.MagickSwirlImage(self.wand, degree, method_idx) return r @manipulative @trap_exception def texture(self, tile): """Repeat tile-image across the width & height of the image. .. code:: python from wand.image import Image with Image(width=100, height=100) as canvas: with Image(filename='tile.png') as tile: canvas.texture(tile) canvas.save(filename='output.png') :param tile: image to repeat across canvas. :type tile: :class:`Image ` .. versionadded:: 0.5.4 """ if not isinstance(tile, BaseImage): raise TypeError('Tile image must be an instance of ' 'wand.image.Image, not ' + repr(tile)) r = library.MagickTextureImage(self.wand, tile.wand) if r: self.wand = r return bool(r) @manipulative @trap_exception def threshold(self, threshold=0.5, channel=None): """Changes the value of individual pixels based on the intensity of each pixel compared to threshold. The result is a high-contrast, two color image. It manipulates the image in place. :param threshold: threshold as a factor of quantum. A normalized float between ``0.0`` and ``1.0``. :type threshold: :class:`numbers.Real` :param channel: the channel type. available values can be found in the :const:`CHANNELS` mapping. If ``None``, threshold all channels. :type channel: :class:`basestring` .. versionadded:: 0.3.10 """ assertions.assert_real(threshold=threshold) threshold *= self.quantum_range + 1 if channel is None: r = library.MagickThresholdImage(self.wand, threshold) else: ch_const = self._channel_to_mask(channel) r = library.MagickThresholdImageChannel( self.wand, ch_const, threshold ) return r @manipulative @trap_exception def thumbnail(self, width=None, height=None): """Changes the size of an image to the given dimensions and removes any associated profiles. The goal is to produce small low cost thumbnail images suited for display on the web. :param width: the width in the scaled image. default is the original width :type width: :class:`numbers.Integral` :param height: the height in the scaled image. default is the original height :type height: :class:`numbers.Integral` .. versionadded:: 0.5.4 """ if width is None: width = self.width if height is None: height = self.height assertions.assert_unsigned_integer(width=width, height=height) return library.MagickThumbnailImage(self.wand, width, height) @manipulative @trap_exception def tint(self, color=None, alpha=None): """Applies a color vector to each pixel in the image. :see: Example of :ref:`tint`. :param color: Color to calculate midtone. :type color: :class:`~wand.color.Color` :param alpha: Determine how to blend. :type alpha: :class:`~wand.color.Color` .. versionadded:: 0.5.3 """ if isinstance(color, string_type): color = Color(color) if isinstance(alpha, string_type): alpha = Color(alpha) assertions.assert_color(color=color, alpha=alpha) with color: with alpha: r = library.MagickTintImage(self.wand, color.resource, alpha.resource) return r @manipulative @trap_exception def transform(self, crop='', resize=''): """Transforms the image using :c:func:`MagickTransformImage`, which is a convenience function accepting geometry strings to perform cropping and resizing. Cropping is performed first, followed by resizing. Either or both arguments may be omitted or given an empty string, in which case the corresponding action will not be performed. Geometry specification strings are defined as follows: A geometry string consists of a size followed by an optional offset. The size is specified by one of the options below, where **bold** terms are replaced with appropriate integer values: **scale**\\ ``%`` Height and width both scaled by specified percentage. **scale-x**\\ ``%x``\\ \\ **scale-y**\\ ``%`` Height and width individually scaled by specified percentages. Only one % symbol is needed. **width** Width given, height automagically selected to preserve aspect ratio. ``x``\\ \\ **height** Height given, width automagically selected to preserve aspect ratio. **width**\\ ``x``\\ **height** Maximum values of width and height given; aspect ratio preserved. **width**\\ ``x``\\ **height**\\ ``!`` Width and height emphatically given; original aspect ratio ignored. **width**\\ ``x``\\ **height**\\ ``>`` Shrinks images with dimension(s) larger than the corresponding width and/or height dimension(s). **width**\\ ``x``\\ **height**\\ ``<`` Enlarges images with dimensions smaller than the corresponding width and/or height dimension(s). **area**\\ ``@`` Resize image to have the specified area in pixels. Aspect ratio is preserved. **X**\\ ``:``\\ **Y** Resize at a given aspect ratio. Common aspect ratios may include ``4:3`` for video/tv, ``3:2`` for 35mm film, ``16:9`` for HDTV, and ``2.39:1`` for cinema. Aspect ratio can be used with the crop parameter, but is only available with ImageMagick version 7.0.8 or greater. The offset, which only applies to the cropping geometry string, is given by ``{+-}``\\ **x**\\ ``{+-}``\\ **y**\\ , that is, one plus or minus sign followed by an **x** offset, followed by another plus or minus sign, followed by a **y** offset. Offsets are in pixels from the upper left corner of the image. Negative offsets will cause the corresponding number of pixels to be removed from the right or bottom edge of the image, meaning the cropped size will be the computed size minus the absolute value of the offset. For example, if you want to crop your image to 300x300 pixels and then scale it by 2x for a final size of 600x600 pixels, you can call:: image.transform('300x300', '200%') This method is a fairly thin wrapper for the C API, and does not perform any additional checking of the parameters except insofar as verifying that they are of the correct type. Thus, like the C API function, the method is very permissive in terms of what it accepts for geometry strings; unrecognized strings and trailing characters will be ignored rather than raising an error. :param crop: A geometry string defining a subregion of the image to crop to :type crop: :class:`basestring` :param resize: A geometry string defining the final size of the image :type resize: :class:`basestring` .. seealso:: `ImageMagick Geometry Specifications`__ Cropping and resizing geometry for the ``transform`` method are specified according to ImageMagick's geometry string format. The ImageMagick documentation provides more information about geometry strings. __ http://www.imagemagick.org/script/command-line-processing.php#geometry .. versionadded:: 0.2.2 .. versionchanged:: 0.5.0 Will call :meth:`crop()` followed by :meth:`resize()` in the event that :c:func:`MagickTransformImage` is not available. .. deprecated:: 0.6.0 Use :meth:`crop()` and :meth:`resize()` instead. """ # noqa # Check that the values given are the correct types. ctypes will do # this automatically, but we can make the error message more friendly # here. assertions.assert_string(crop=crop, resize=resize) # Also verify that only ASCII characters are included try: crop = crop.encode('ascii') except UnicodeEncodeError: raise ValueError('crop must only contain ascii-encodable ' + 'characters.') try: resize = resize.encode('ascii') except UnicodeEncodeError: raise ValueError('resize must only contain ascii-encodable ' + 'characters.') if not library.MagickTransformImage: # pragma: no cover # Method removed from ImageMagick-7. if crop: x = ctypes.c_ssize_t(0) y = ctypes.c_ssize_t(0) width = ctypes.c_size_t(self.width) height = ctypes.c_size_t(self.height) if b':' in crop: # For "4:3" aspect cropping. libmagick.ParseMetaGeometry(crop, ctypes.byref(x), ctypes.byref(y), ctypes.byref(width), ctypes.byref(height)) else: libmagick.GetGeometry(crop, ctypes.byref(x), ctypes.byref(y), ctypes.byref(width), ctypes.byref(height)) self.crop(top=y.value, left=x.value, width=width.value, height=height.value, reset_coords=False) if resize: x = ctypes.c_ssize_t(0) y = ctypes.c_ssize_t(0) width = ctypes.c_size_t(self.width) height = ctypes.c_size_t(self.height) libmagick.ParseMetaGeometry(resize, ctypes.byref(x), ctypes.byref(y), ctypes.byref(width), ctypes.byref(height)) self.resize(width=width.value, height=height.value) # Both `BaseImage.crop` & `BaseImage.resize` will handle # animation & error handling, so we can stop here. return True if self.animation: new_wand = library.NewMagickWand() src_wand = library.MagickCoalesceImages(self.wand) length = library.MagickGetNumberImages(self.wand) for i in xrange(length): library.MagickSetIteratorIndex(src_wand, i) tmp_wand = library.MagickTransformImage(src_wand, crop, resize) library.MagickAddImage(new_wand, tmp_wand) if bool(tmp_wand): library.DestroyMagickWand(tmp_wand) if bool(src_wand): library.DestroyMagickWand(src_wand) self.reset_sequence() else: new_wand = library.MagickTransformImage(self.wand, crop, resize) if new_wand: self.wand = new_wand return bool(new_wand) @manipulative @trap_exception def transform_colorspace(self, colorspace_type): """Transform image's colorspace. :param colorspace_type: colorspace_type. available value can be found in the :const:`COLORSPACE_TYPES` :type colorspace_type: :class:`basestring` .. versionadded:: 0.4.2 """ assertions.string_in_list(COLORSPACE_TYPES, 'wand.image.COLORSPACE_TYPES', colorspace=colorspace_type) return library.MagickTransformImageColorspace( self.wand, COLORSPACE_TYPES.index(colorspace_type) ) @manipulative @trap_exception def transparent_color(self, color, alpha, fuzz=0, invert=False): """Makes the color ``color`` a transparent color with a tolerance of fuzz. The ``alpha`` parameter specify the transparency level and the parameter ``fuzz`` specify the tolerance. :param color: The color that should be made transparent on the image, color object :type color: :class:`wand.color.Color` :param alpha: the level of transparency: 1.0 is fully opaque and 0.0 is fully transparent. :type alpha: :class:`numbers.Real` :param fuzz: By default target must match a particular pixel color exactly. However, in many cases two colors may differ by a small amount. The fuzz member of image defines how much tolerance is acceptable to consider two colors as the same. For example, set fuzz to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color for the color. :type fuzz: :class:`numbers.Real` :param invert: Boolean to tell to paint the inverse selection. :type invert: :class:`bool` .. versionadded:: 0.3.0 .. versionchanged:: 0.6.3 Parameter ``fuzz`` type switched from Integral to Real. """ assertions.assert_real(alpha=alpha, fuzz=fuzz) if isinstance(color, string_type): color = Color(color) assertions.assert_color(color=color) with color: r = library.MagickTransparentPaintImage(self.wand, color.resource, alpha, fuzz, invert) return r @manipulative def transparentize(self, transparency): """Makes the image transparent by subtracting some percentage of the black color channel. The ``transparency`` parameter specifies the percentage. :param transparency: the percentage fade that should be performed on the image, from 0.0 to 1.0 :type transparency: :class:`numbers.Real` .. versionadded:: 0.2.0 """ if transparency: t = ctypes.c_double(float(self.quantum_range * float(transparency))) if t.value > self.quantum_range or t.value < 0: raise ValueError('transparency must be a numbers.Real value ' + 'between 0.0 and 1.0') # Set the wand to image zero, in case there are multiple images # in it library.MagickSetIteratorIndex(self.wand, 0) # Change the pixel representation of the image # to RGB with an alpha channel if MAGICK_VERSION_NUMBER < 0x700: image_type = 'truecolormatte' else: # pragma: no cover image_type = 'truecoloralpha' library.MagickSetImageType(self.wand, IMAGE_TYPES.index(image_type)) # Perform the black channel subtraction self.evaluate(operator='subtract', value=t.value, channel='opacity') self.raise_exception() @manipulative @trap_exception def transpose(self): """Creates a vertical mirror image by reflecting the pixels around the central x-axis while rotating them 90-degrees. .. versionadded:: 0.4.1 """ return library.MagickTransposeImage(self.wand) @manipulative @trap_exception def transverse(self): """Creates a horizontal mirror image by reflecting the pixels around the central y-axis while rotating them 270-degrees. .. versionadded:: 0.4.1 """ return library.MagickTransverseImage(self.wand) @manipulative @trap_exception def trim(self, color=None, fuzz=0.0, reset_coords=False, percent_background=None, background_color=None): """Remove solid border from image. Uses top left pixel as a guide by default, or you can also specify the ``color`` to remove. :param color: the border color to remove. if it's omitted top left pixel is used by default :type color: :class:`~wand.color.Color` :param fuzz: Defines how much tolerance is acceptable to consider two colors as the same. Value can be between ``0.0``, and :attr:`quantum_range`. :type fuzz: :class:`numbers.Real` :param reset_coords: Reset coordinates after trimming image. Default ``False``. :type reset_coords: :class:`bool` :param percent_background: Sets how aggressive the trim operation will be. A value of `0.0` will trim to the minimal bounding box of all matching color, and `1.0` to the most outer edge. :type percent_background: :class:`numbers.Real` :param background_color: Local alias to :attr:`background_color`, and has the same effect as defining ``color`` parameter -- but much faster. .. versionadded:: 0.2.1 .. versionchanged:: 0.3.0 Optional ``color`` and ``fuzz`` parameters. .. versionchanged:: 0.5.2 The ``color`` parameter may accept color-compliant strings. .. versionchanged:: 0.6.0 Optional ``reset_coords`` parameter added. .. versionchanged:: 0.6.4 Optional ``percent_background`` & ``background_color`` parameters have been added. """ use_border = background_color is None if use_border: if color is None: color = self[0, 0] elif isinstance(color, string_type): color = Color(color) assertions.assert_color(color=color) with color: self.border(color, 1, 1, compose='copy') assertions.assert_real(fuzz=fuzz) assertions.assert_bool(reset_coords=reset_coords) if percent_background is not None: assertions.assert_real(percent_background=percent_background) percent_background = max(min(percent_background, 1.0), 0.0) * 100.0 str_pb = '{0:g}%'.format(percent_background) library.MagickSetImageArtifact(self.wand, binary('trim:percent-background'), binary(str_pb)) if not use_border: if isinstance(background_color, string_type): background_color = Color(background_color) assertions.assert_color(background_color=background_color) bc_key = 'trim:background-color' bc_val = background_color.string library.MagickSetImageArtifact(self.wand, binary(bc_key), binary(bc_val)) r = library.MagickTrimImage(self.wand, fuzz) if reset_coords: self.reset_coords() elif use_border: # Re-calculate page coordinates as we added a 1x1 border before # applying the trim. adjusted_coords = list(self.page) # Width & height are unsigned. adjusted_coords[0] = max(adjusted_coords[0] - 2, 0) adjusted_coords[1] = max(adjusted_coords[1] - 2, 0) # X & Y are signed. It's common for page offsets to be negative. adjusted_coords[2] -= 1 adjusted_coords[3] -= 1 self.page = adjusted_coords return r @manipulative @trap_exception def unique_colors(self): """Discards all duplicate pixels, and rebuilds the image as a single row. .. versionadded:: 0.5.0 """ return library.MagickUniqueImageColors(self.wand) @manipulative @trap_exception def unsharp_mask(self, radius=0.0, sigma=1.0, amount=1.0, threshold=0.0, channel=None): """Sharpens the image using unsharp mask filter. We convolve the image with a Gaussian operator of the given ``radius`` and standard deviation (``sigma``). For reasonable results, ``radius`` should be larger than ``sigma``. Use a radius of 0 and :meth:`unsharp_mask()` selects a suitable radius for you. :see: Example of :ref:`unsharp_mask`. :param radius: the radius of the Gaussian, in pixels, not counting the center pixel :type radius: :class:`numbers.Real` :param sigma: the standard deviation of the Gaussian, in pixels :type sigma: :class:`numbers.Real` :param amount: the percentage of the difference between the original and the blur image that is added back into the original :type amount: :class:`numbers.Real` :param threshold: the threshold in pixels needed to apply the difference amount. :type threshold: :class:`numbers.Real` :param channel: Optional color channel to target. See :const:`CHANNELS` :type channel: :class:`basestring` .. versionadded:: 0.3.4 .. versionchanged:: 0.5.5 Added optional ``channel`` argument. .. versionchanged:: 0.5.7 Added default values to match CLI behavior. """ assertions.assert_real(radius=radius, sigma=sigma, amount=amount, threshold=threshold) if channel is None: r = library.MagickUnsharpMaskImage(self.wand, radius, sigma, amount, threshold) else: channel_ch = self._channel_to_mask(channel) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickUnsharpMaskImageChannel( self.wand, channel_ch, radius, sigma, amount, threshold ) else: # pragma: no cover mask = library.MagickSetImageChannelMask(self.wand, channel_ch) r = library.MagickUnsharpMaskImage(self.wand, radius, sigma, amount, threshold) library.MagickSetImageChannelMask(self.wand, mask) return r @manipulative @trap_exception def vignette(self, radius=0.0, sigma=0.0, x=0, y=0): """Creates a soft vignette style effect on the image. :see: Example of :ref:`vignette`. :param radius: the radius of the Gaussian blur effect. :type radius: :class:`numbers.Real` :param sigma: the standard deviation of the Gaussian effect. :type sigma: :class:`numbers.Real` :param x: Number of pixels to offset inward from the top & bottom of the image before drawing effect. :type x: :class:`numbers.Integral` :param y: Number of pixels to offset inward from the left & right of the image before drawing effect. :type y: :class:`numbers.Integral` .. versionadded:: 0.5.2 """ assertions.assert_real(radius=radius, sigma=sigma) return library.MagickVignetteImage(self.wand, radius, sigma, x, y) @manipulative def watermark(self, image, transparency=0.0, left=0, top=0): """Transparentized the supplied ``image`` and places it over the current image, with the top left corner of ``image`` at coordinates ``left``, ``top`` of the current image. The dimensions of the current image are not changed. :param image: the image placed over the current image :type image: :class:`wand.image.Image` :param transparency: the percentage fade that should be performed on the image, from 0.0 to 1.0 :type transparency: :class:`numbers.Real` :param left: the x-coordinate where `image` will be placed :type left: :class:`numbers.Integral` :param top: the y-coordinate where `image` will be placed :type top: :class:`numbers.Integral` .. versionadded:: 0.2.0 """ with image.clone() as watermark_image: watermark_image.transparentize(transparency) watermark_image.clamp() self.composite(watermark_image, left=left, top=top) self.raise_exception() @manipulative @trap_exception def wave(self, amplitude=0.0, wave_length=0.0, method='undefined'): """Creates a ripple effect within the image. :see: Example of :ref:`wave`. :param amplitude: height of wave form. :type amplitude: :class:`numbers.Real` :param wave_length: width of wave form. :type wave_length: :class:`numbers.Real` :param method: pixel interpolation method. Only available with ImageMagick-7. See :const:`PIXEL_INTERPOLATE_METHODS` :type method: :class:`basestring` .. versionadded:: 0.5.2 """ assertions.assert_real(amplitude=amplitude, wave_length=wave_length) assertions.string_in_list(PIXEL_INTERPOLATE_METHODS, 'wand.image.PIXEL_INTERPOLATE_METHODS', method=method) if MAGICK_VERSION_NUMBER < 0x700: r = library.MagickWaveImage(self.wand, amplitude, wave_length) else: # pragma: no cover method_idx = PIXEL_INTERPOLATE_METHODS.index(method) r = library.MagickWaveImage(self.wand, amplitude, wave_length, method_idx) return r @manipulative @trap_exception def wavelet_denoise(self, threshold=0.0, softness=0.0): """Removes noise by applying a `wavelet transform`_. .. _`wavelet transform`: https://en.wikipedia.org/wiki/Wavelet_transform .. warning:: This class method is only available with ImageMagick 7.0.8-41, or greater. :see: Example of :ref:`wavelet_denoise`. :param threshold: Smoothing limit. :type threshold: :class:`numbers.Real` :param softness: Attenuate of the smoothing threshold. :type softness: :class:`numbers.Real` :raises WandLibraryVersionError: If system's version of ImageMagick does not support this method. .. versionadded:: 0.5.5 """ if library.MagickWaveletDenoiseImage is None: msg = 'Method requires ImageMagick version 7.0.8-41 or greater.' raise WandLibraryVersionError(msg) assertions.assert_real(threshold=threshold, softness=softness) if 0.0 < threshold <= 1.0: threshold *= self.quantum_range if 0.0 < softness <= 1.0: softness *= self.quantum_range return library.MagickWaveletDenoiseImage(self.wand, threshold, softness) @manipulative @trap_exception def white_balance(self): """Uses LAB colorspace to apply a white balance to the image. .. note:: Requires ImageMagick-7.0.10-37 or later. .. versionadded:: 0.6.4 """ msg = 'Requires ImageMagick-7.0.10-37, or later.' if MAGICK_VERSION_NUMBER < 0x70A: raise WandLibraryVersionError(msg) elif library.MagickWhiteBalanceImage is None: raise WandLibraryVersionError(msg) return library.MagickWhiteBalanceImage(self.wand) @manipulative @trap_exception def white_threshold(self, threshold): """Forces all pixels above a given color as white. Leaves pixels below threshold unaltered. :param threshold: Color to be referenced as a threshold. :type threshold: :class:`Color` .. versionadded:: 0.5.2 """ if isinstance(threshold, string_type): threshold = Color(threshold) assertions.assert_color(threshold=threshold) with threshold: r = library.MagickWhiteThresholdImage(self.wand, threshold.resource) return r @trap_exception def write_mask(self, clip_mask=None): """Sets the write mask which prevents pixel-value updates to the image. Call this method with a ``None`` argument to clear any previously set masks. .. warning:: This method is only available with ImageMagick-7. :param clip_mask: Image to reference as blend mask. :type clip_mask: :class:`BaseImage` .. versionadded:: 0.5.7 """ r = False WritePixelMask = 0x000002 if library.MagickSetImageMask is None: raise WandLibraryVersionError('Method requires ImageMagick-7.') else: # pragma: no cover if clip_mask is None: w, h = self.size with Image(width=w, height=h, pseudo='xc:none') as clear: r = library.MagickSetImageMask(self.wand, WritePixelMask, clear.wand) elif isinstance(clip_mask, BaseImage): r = library.MagickSetImageMask(self.wand, WritePixelMask, clip_mask.wand) return r class Image(BaseImage): """An image object. :param image: makes an exact copy of the ``image`` :type image: :class:`Image` :param blob: opens an image of the ``blob`` byte array :type blob: :class:`bytes` :param file: opens an image of the ``file`` object :type file: file object :param filename: opens an image of the ``filename`` string. Additional :ref:`read_mods` are supported. :type filename: :class:`basestring` :param format: forces filename to buffer. ``format`` to help ImageMagick detect the file format. Used only in ``blob`` or ``file`` cases :type format: :class:`basestring` :param width: the width of new blank image or an image loaded from raw data. :type width: :class:`numbers.Integral` :param height: the height of new blank image or an image loaded from raw data. :type height: :class:`numbers.Integral` :param depth: the depth used when loading raw data. :type depth: :class:`numbers.Integral` :param background: an optional background color. default is transparent :type background: :class:`wand.color.Color` :param resolution: set a resolution value (dpi), useful for vectorial formats (like pdf) :type resolution: :class:`collections.abc.Sequence`, :Class:`numbers.Integral` :param colorspace: sets the stack's default colorspace value before reading any images. See :const:`COLORSPACE_TYPES`. :type colorspace: :class:`basestring` :param units: paired with ``resolution`` for defining an image's pixel density. See :const:`UNIT_TYPES`. :type units: :class:`basestring` .. versionadded:: 0.1.5 The ``file`` parameter. .. versionadded:: 0.1.1 The ``blob`` parameter. .. versionadded:: 0.2.1 The ``format`` parameter. .. versionadded:: 0.2.2 The ``width``, ``height``, ``background`` parameters. .. versionadded:: 0.3.0 The ``resolution`` parameter. .. versionadded:: 0.4.2 The ``depth`` parameter. .. versionchanged:: 0.4.2 The ``depth``, ``width`` and ``height`` parameters can be used with the ``filename``, ``file`` and ``blob`` parameters to load raw pixel data. .. versionadded:: 0.5.0 The ``pseudo`` parameter. .. versionchanged:: 0.5.4 Read constructor no longer sets "transparent" background by default. Use the ``background`` parameter to specify canvas color when reading in image. .. versionchanged:: 0.5.7 Added the ``colorspace`` & ``units`` parameter. .. versionchanged:: 0.6.3 Added ``sampling_factors`` parameter for working with YUV streams. .. describe:: [left:right, top:bottom] Crops the image by its ``left``, ``right``, ``top`` and ``bottom``, and then returns the cropped one. :: with img[100:200, 150:300] as cropped: # manipulated the cropped image pass Like other subscriptable objects, default is 0 or its width/height:: img[:, :] #--> just clone img[:100, 200:] #--> equivalent to img[0:100, 200:img.height] Negative integers count from the end (width/height):: img[-70:-50, -20:-10] #--> equivalent to img[width-70:width-50, height-20:height-10] :returns: the cropped image :rtype: :class:`Image` .. versionadded:: 0.1.2 """ #: (:class:`ArtifactTree`) A dict mapping to image artifacts. #: Similar to :attr:`metadata`, but used to alter behavior of various #: internal operations. #: #: .. versionadded:: 0.5.0 artifacts = None #: (:class:`ChannelImageDict`) The mapping of separated channels #: from the image. :: #: #: with image.channel_images['red'] as red_image: #: display(red_image) channel_images = None #: (:class:`ChannelDepthDict`) The mapping of channels to their depth. #: Read only. #: #: .. versionadded:: 0.3.0 channel_depths = None #: (:class:`Metadata`) The metadata mapping of the image. Read only. #: #: .. versionadded:: 0.3.0 metadata = None #: (:class:`ProfileDict`) The mapping of image profiles. #: #: .. versionadded:: 0.5.1 profiles = None def __init__(self, image=None, blob=None, file=None, filename=None, pseudo=None, background=None, colorspace=None, depth=None, extract=None, format=None, height=None, interlace=None, resolution=None, sampling_factors=None, units=None, width=None): new_args = width, height, background, depth open_args = blob, file, filename if any(a is not None for a in new_args) and image is not None: raise TypeError("blank image parameters can't be used with image " 'parameter') if sum(a is not None for a in open_args + (image,)) > 1: raise TypeError(', '.join(open_args) + ' and image parameters are exclusive each other; ' 'use only one at once') with self.allocate(): if image is None: wand = library.NewMagickWand() super(Image, self).__init__(wand) if image is not None: if not isinstance(image, BaseImage): raise TypeError('image must be a wand.image.Image ' 'instance, not ' + repr(image)) wand = library.CloneMagickWand(image.wand) super(Image, self).__init__(wand) elif any(a is not None for a in open_args): self._preamble_read( background=background, colorspace=colorspace, depth=depth, extract=extract, format=format, height=height, interlace=interlace, resolution=resolution, sampling_factors=sampling_factors, width=width ) if file is not None: self.read(file=file) elif blob is not None: self.read(blob=blob) elif filename is not None: self.read(filename=filename) # clear the wand format, otherwise any subsequent call to # MagickGetImageBlob will silently change the image to this # format again. library.MagickSetFormat(self.wand, binary("")) elif width is not None and height is not None: if pseudo is None: self.blank(width, height, background) else: self.pseudo(width, height, pseudo) if depth: r = library.MagickSetImageDepth(self.wand, depth) if not r: raise self.raise_exception() if units is not None: self.units = units self.metadata = Metadata(self) self.artifacts = ArtifactTree(self) from .sequence import Sequence self.sequence = Sequence(self) self.profiles = ProfileDict(self) self.raise_exception() def __repr__(self): return super(Image, self).__repr__( extra_format=' {self.format!r} ({self.width}x{self.height})' ) def _preamble_read(self, background=None, colorspace=None, depth=None, extract=None, format=None, height=None, interlace=None, resolution=None, sampling_factors=None, units=None, width=None): """Set-up MagickWand properties before reading an image file. The properties are unique to the image decoder. :param background: Defines the default background color. :type background: :class:`Color`, :class:`basestring` :param colorspace: Defines what colorspace the decoder should operate in. See :const:`COLORSPACE_TYPES`. :type colorspace: :class:`basestring` :param depth: Bits per color sample. :type depth: :class:`numbers.Integral` :param extract: Only decode a sub-region of the image. :type extract: :class:`basestring` :param format: Defines the decoder image format. :type format: :class:`basestring` :param height: Defines how high a blank canvas should be. Only used if ``width`` is also defined. :type height: :class:`numbers.Integral` :param interlace: Defines the interlacing scheme for raw data streams. See :const:`INTERLACE_TYPES`. :type interlace: :class:`basestring` :param resolution: Defines the pixel density of a scalable formats. PDF & SVG as examples. :type resolution: :class:`collections.abc.Sequence`, :class:`numbers.Integral` :param sampling_factors: Defines how a YUV might be upsampled. :type sampling_factors: :class:`collections.abc.Sequence`, :class:`basestring` :param units: Unused. :type units: :class:`numbers.Integral` :param width: Defines how wide a blank canvas should be. Only used if ``height`` is also defined. :type width: :class:`numbers.Intragal` .. versionadded:: 0.6.3 """ if background: if isinstance(background, string_type): background = Color(background) assertions.assert_color(background=background) with background: library.MagickSetBackgroundColor(self.wand, background.resource) if colorspace is not None: assertions.string_in_list( COLORSPACE_TYPES, 'wand.image.COLORSPACE_TYPES', colorspace=colorspace ) colorspace_idx = COLORSPACE_TYPES.index(colorspace) library.MagickSetColorspace(self.wand, colorspace_idx) if depth is not None: assertions.assert_counting_number(depth=depth) library.MagickSetDepth(self.wand, depth) if extract is not None: assertions.assert_string(extract=extract) library.MagickSetExtract(self.wand, binary(extract)) if format is not None: assertions.assert_string(format=format) library.MagickSetFormat(self.wand, binary(format)) library.MagickSetFilename(self.wand, b'buffer.' + binary(format)) if interlace is not None: assertions.string_in_list( INTERLACE_TYPES, 'wand.image.INTERLACE_TYPES', interlace=interlace ) c_interlace = INTERLACE_TYPES.index(interlace) library.MagickSetInterlaceScheme(self.wand, c_interlace) if resolution is not None: if (isinstance(resolution, abc.Sequence) and len(resolution) == 2): library.MagickSetResolution(self.wand, *resolution) elif isinstance(resolution, numbers.Real): library.MagickSetResolution(self.wand, resolution, resolution) else: raise TypeError('resolution must be a (x, y) pair or an ' 'real number of the same x/y') if sampling_factors is not None: self.sampling_factors = sampling_factors if width is not None and height is not None: assertions.assert_counting_number(width=width, height=height) library.MagickSetSize(self.wand, width, height) def _repr_png_(self): with self.convert('png') as cloned: return cloned.make_blob() @classmethod def from_array(cls, array, channel_map=None, storage=None): """Create an image instance from a :mod:`numpy` array, or any other datatype that implements `__array_interface__`__ protocol. .. code:: import numpy from wand.image import Image matrix = numpy.random.rand(100, 100, 3) with Image.from_array(matrix) as img: img.save(filename='noise.png') Use the optional ``channel_map`` & ``storage`` arguments to specify the order of color channels & data size. If ``channel_map`` is omitted, this method will will guess ``"RGB"``, or ``"CMYK"`` based on array shape. If ``storage`` is omitted, this method will reference the array's ``typestr`` value, and raise a :class:`ValueError` if storage-type can not be mapped. Float values must be normalized between `0.0` and `1.0`, and signed integers should be converted to unsigned values between `0` and max value of type. Instances of :class:`Image` can also be exported to numpy arrays:: with Image(filename='rose:') as img: matrix = numpy.array(img) __ https://docs.scipy.org/doc/numpy/reference/arrays.interface.html :param array: Numpy array of pixel values. :type array: :class:`numpy.array` :param channel_map: Color channel layout. :type channel_map: :class:`basestring` :param storage: Datatype per pixel part. :type storage: :class:`basestring` :returns: New instance of an image. :rtype: :class:`~wand.image.Image` .. versionadded:: 0.5.3 .. versionchanged:: 0.6.0 Input ``array`` now expects the :attr:`shape` property to be defined as ```( 'height', 'width', 'channels' )```. """ arr_itr = array.__array_interface__ typestr = arr_itr['typestr'] # Required by interface. shape = arr_itr['shape'] # Required by interface. if storage is None: # Attempt to guess storage storage_map = dict(u1='char', i1='char', u2='short', i2='short', u4='integer', i4='integer', u8='long', i8='integer', f4='float', f8='double') for token in storage_map: if token in typestr: storage = storage_map[token] break if storage is None: raise ValueError('Unable to determine storage type.') if channel_map is None: # Attempt to guess channel map if len(shape) == 3: if shape[2] < 5: channel_map = 'RGBA'[0:shape[2]] else: channel_map = 'CMYKA'[0:shape[2]] else: channel_map = 'R' strides = arr_itr.get('strides', None) if hasattr(array, 'ctypes') and strides is None: data_ptr = array.ctypes.data_as(ctypes.c_void_p) elif hasattr(array, 'tobytes'): data_ptr = array.tobytes() elif hasattr(array, 'tostring'): data_ptr = array.tostring() else: data_ptr, _ = arr_itr.get('data') storage_idx = STORAGE_TYPES.index(storage) height, width = shape[:2] genesis() wand = library.NewMagickWand() instance = cls(BaseImage(wand)) r = library.MagickConstituteImage(instance.wand, width, height, binary(channel_map), storage_idx, data_ptr) if not r: instance.raise_exception(cls) return instance @classmethod def ping(cls, file=None, filename=None, blob=None, **kwargs): """Ping image header into Image() object, but without any pixel data. This is useful for inspecting image meta-data without decoding the whole image. :param blob: reads an image from the ``blob`` byte array :type blob: :class:`bytes` :param file: reads an image from the ``file`` object :type file: file object :param filename: reads an image from the ``filename`` string :type filename: :class:`basestring` :param resolution: set a resolution value (DPI), useful for vector formats (like PDF) :type resolution: :class:`collections.abc.Sequence`, :class:`numbers.Integral` :param format: suggest image file format when reading from a ``blob``, or ``file`` property. :type format: :class:`basestring` .. versionadded:: 0.5.6 """ r = None instance = cls() instance._preamble_read(**kwargs) if file is not None: if (isinstance(file, file_types) and hasattr(libc, 'fdopen') and hasattr(file, 'mode')): fd = libc.fdopen(file.fileno(), file.mode) r = library.MagickPingImageFile(instance.wand, fd) elif not callable(getattr(file, 'read', None)): raise TypeError('file must be a readable file object' ', but the given object does not ' 'have read() method') else: blob = file.read() file = None if blob is not None: if not isinstance(blob, abc.Iterable): raise TypeError('blob must be iterable, not ' + repr(blob)) if not isinstance(blob, binary_type): blob = b''.join(blob) r = library.MagickPingImageBlob(instance.wand, blob, len(blob)) elif filename is not None: filename = encode_filename(filename) r = library.MagickPingImage(instance.wand, filename) if not r: instance.raise_exception() msg = ('MagickPingImage returns false, but did raise ImageMagick ' 'exception. This can occur when a delegate is missing, or ' 'returns EXIT_SUCCESS without generating a raster.') raise WandRuntimeError(msg) else: units = kwargs.get('units') if units is not None: instance.units = units instance.metadata = Metadata(instance) instance.artifacts = ArtifactTree(instance) from .sequence import Sequence instance.sequence = Sequence(instance) instance.profiles = ProfileDict(instance) return instance @classmethod def stereogram(cls, left, right): """Create a new stereogram image from two existing images. :see: Example of :ref:`stereogram`. :param left: Left-eye image. :type left: :class:`wand.image.Image` :param right: Right-eye image. :type right: :class:`wand.image.Image` .. versionadded:: 0.5.4 """ if not isinstance(left, BaseImage): raise TypeError('Left image must be in instance of ' 'wand.image.Image, not ' + repr(left)) if not isinstance(right, BaseImage): raise TypeError('Right image must be in instance of ' 'wand.image.Image, not ' + repr(right)) wand = library.MagickStereoImage(left.wand, right.wand) if not wand: # pragma: no cover left.raise_exception() return cls(BaseImage(wand)) @property def animation(self): is_gif = self.mimetype in ('image/gif', 'image/x-gif') frames = library.MagickGetNumberImages(self.wand) return is_gif and frames > 1 @property def mimetype(self): """(:class:`basestring`) The MIME type of the image e.g. ``'image/jpeg'``, ``'image/png'``. .. versionadded:: 0.1.7 """ mtype = None rp = libmagick.MagickToMime(binary(self.format)) if rp: mtype = text(ctypes.string_at(rp)) rp = libmagick.DestroyString(rp) return mtype def blank(self, width, height, background=None): """Creates blank image. :param width: the width of new blank image. :type width: :class:`numbers.Integral` :param height: the height of new blank image. :type height: :class:`numbers.Integral` :param background: an optional background color. default is transparent :type background: :class:`wand.color.Color` :returns: blank image :rtype: :class:`Image` .. versionadded:: 0.3.0 """ assertions.assert_counting_number(width=width, height=height) if background is None: background = Color('transparent') elif isinstance(background, string_type): background = Color(background) assertions.assert_color(background=background) with background: r = library.MagickNewImage(self.wand, width, height, background.resource) if not r: self.raise_exception() return self def clear(self): """Clears resources associated with the image, leaving the image blank, and ready to be used with new image. .. versionadded:: 0.3.0 """ library.ClearMagickWand(self.wand) def close(self): """Closes the image explicitly. If you use the image object in :keyword:`with` statement, it was called implicitly so don't have to call it. .. note:: It has the same functionality of :attr:`destroy()` method. """ self.destroy() def compare_layers(self, method): """Generates new images showing the delta pixels between layers. Similar pixels are converted to transparent. Useful for debugging complex animations. :: with img.compare_layers('compareany') as delta: delta.save(filename='framediff_%02d.png') .. note:: May not work as expected if animations are already optimized. :param method: Can be ``'compareany'``, ``'compareclear'``, or ``'compareoverlay'`` :type method: :class:`basestring` :returns: new image stack. :rtype: :class:`Image` .. versionadded:: 0.5.0 """ if not isinstance(method, string_type): raise TypeError('method must be a string from IMAGE_LAYER_METHOD, ' 'not ' + repr(method)) if method not in ('compareany', 'compareclear', 'compareoverlay'): raise ValueError('method can only be \'compareany\', ' '\'compareclear\', or \'compareoverlay\'') r = None m = IMAGE_LAYER_METHOD.index(method) if MAGICK_VERSION_NUMBER >= 0x700: # pragma: no cover r = library.MagickCompareImagesLayers(self.wand, m) elif library.MagickCompareImageLayers: r = library.MagickCompareImageLayers(self.wand, m) elif library.MagickCompareImagesLayers: # pragma: no cover r = library.MagickCompareImagesLayers(self.wand, m) else: raise AttributeError('MagickCompareImageLayers method ' 'not available on system.') if not r: self.raise_exception() return Image(image=BaseImage(r)) def convert(self, format): """Converts the image format with the original image maintained. It returns a converted image instance which is new. :: with img.convert('png') as converted: converted.save(filename='converted.png') :param format: image format to convert to :type format: :class:`basestring` :returns: a converted image :rtype: :class:`Image` :raises ValueError: when the given ``format`` is unsupported .. versionadded:: 0.1.6 .. versionchanged:: 0.6.11 Call :c:func:`MagickSetFormat` method after :c:func:`MagickSetImageFormat`. This will ensure image info, magick, and filename properties are aligned. """ cloned = self.clone() cloned.format = format library.MagickSetFormat(cloned.wand, binary(format.strip().upper())) return cloned def data_url(self): """Generate a base64 `data-url`_ string from the loaded image. Useful for converting small graphics into ASCII strings for HTML/CSS web development. .. _data-url: https://en.wikipedia.org/wiki/Data_URI_scheme :returns: a data-url formatted string. :rtype: :class:`basestring` .. versionadded:: 0.6.3 """ from base64 import b64encode mime_type = self.mimetype base_bytes = b64encode(self.make_blob()) return "data:{0};base64,{1}".format(mime_type, text(base_bytes)) @trap_exception def image_add(self, image): """Copies a given image on to the image stack. By default, the added image will be append at the end of the stack, or immediately after the current image iterator defined by :meth:`~BaseImage.iterator_set`. Use :meth:`~BaseImage.iterator_reset` before calling this method to insert the new image before existing images on the stack. :param image: raster to add. :type image: :class:`Image` .. versionadded:: 0.6.7 """ if not isinstance(image, Image): raise TypeError('image must be instance of wand.image.Image') return library.MagickAddImage(self.wand, image.wand) def image_get(self): """Generate & return a clone of a single image at the current image-stack index. .. versionadded:: 0.6.7 """ r = library.MagickGetImage(self.wand) if not r: self.raise_exception() return None # noqa - Safety if exception isn't thrown. return Image(BaseImage(r)) @trap_exception def image_remove(self): """Remove an image from the image-stack at the current index. .. versionadded:: 0.6.7 """ return library.MagickRemoveImage(self.wand) @trap_exception def image_set(self, image): """Overwrite current image on the image-stack with given image. :param image: Wand instance of images to write to stack. :type image: :class:`wand.image.Image` .. versionadded:: 0.6.7 """ if not isinstance(image, Image): raise TypeError('image must be an instance of wand.image.Image,', ' not ' + repr(image)) return library.MagickSetImage(self.wand, image.wand) @trap_exception def image_swap(self, i, j): """Swap two images on the image-stack. :param i: image index to replace with ``j`` :type i: :class:`numbers.Integral` :param j: image index to replace with ``i`` :type j: :class:`numbers.Integral` .. versionadded:: 0.6.7 """ assertions.assert_integer(i=i) assertions.assert_integer(j=j) op = self.iterator_get() self.iterator_set(i) with self.image_get() as a: self.iterator_set(j) with self.image_get() as b: self.image_set(a) self.iterator_set(i) self.image_set(b) self.iterator_set(op) def make_blob(self, format=None): """Makes the binary string of the image. :param format: the image format to write e.g. ``'png'``, ``'jpeg'``. it is omittable :type format: :class:`basestring` :returns: a blob (bytes) string :rtype: :class:`bytes` :raises ValueError: when ``format`` is invalid .. versionchanged:: 0.1.6 Removed a side effect that changes the image :attr:`format` silently. .. versionadded:: 0.1.5 The ``format`` parameter became optional. .. versionadded:: 0.1.1 """ if format is not None: with self.convert(format) as converted: return converted.make_blob() library.MagickResetIterator(self.wand) length = ctypes.c_size_t() blob_p = None if library.MagickGetNumberImages(self.wand) > 1: blob_p = library.MagickGetImagesBlob(self.wand, ctypes.byref(length)) else: blob_p = library.MagickGetImageBlob(self.wand, ctypes.byref(length)) if blob_p and length.value: blob = ctypes.string_at(blob_p, length.value) blob_p = library.MagickRelinquishMemory(blob_p) return blob else: # pragma: no cover self.raise_exception() @trap_exception def montage(self, font=None, tile=None, thumbnail=None, mode='unframe', frame=None): """Generates a new image containing thumbnails if each previous image read. :: with Image() as img: for file_path in ['first.png', 'second.png', 'third.png']: with Image(filename=file_path) as item: img.options['label'] = file_path img.image_add(item) style = Font('monospace', 24, 'green') img.montage(font=style, tile='3x1', thumbnail='15x15') img.save(filename='montage.png') :param font: Define font style to use when labeling each thumbnail. Thumbnail labeling will only be rendered if ``'label'`` value in :attr:`options` dict is defined. :type font: :class:`~wand.font.Font` :param tile: The number of thunbnails per rows & column on a page. Example: ``"6x4"``. :type tile: :class:`basestring` :param thumbnail: Preferred image size. Montage will attempt to generate a thumbnail to match the geometry. This can also define the border size on each thumbnail. Example: ``"120x120x+4+3>"``. :type thumbnail: :class:`basestring` :param mode: Which effect to render. Options include ``"frame"``, ``"unframe"``, and ``"concatenate"``. Default ``"frame"``. :type mode: :class:`basestring` :param frame: Define ornamental boarder around each thrumbnail. The color of the frame is defined by the image's matte color. Example: ``"15x15+3+3"``. :type frame: :class:`basestring` .. versionadded:: 0.6.8 """ if font is not None: if not isinstance(font, Font): msg = 'font must be an instance of wand.font.Font' raise TypeError(msg) else: font = Font('helvetica', 16, 'black') if tile is not None: assertions.assert_string(tile=tile) tile = binary(tile) if thumbnail is not None: assertions.assert_string(thumbnail=thumbnail) thumbnail = binary(thumbnail) assertions.in_list(MONTAGE_MODES, 'wand.image.MONTAGE_MODES', mode=mode) mode_idx = MONTAGE_MODES.index(mode) if frame is not None: assertions.assert_string(frame=frame) frame = binary(frame) ctx_ptr = library.NewDrawingWand() if font.path: library.DrawSetFont(ctx_ptr, binary(font.path)) library.DrawSetFontFamily(ctx_ptr, binary(font.path)) if font.size: library.DrawSetFontSize(ctx_ptr, font.size) if font.color: with font.color: library.DrawSetFillColor(ctx_ptr, font.color.resource) if font.stroke_color: with font.stroke_color: library.DrawSetStrokeColor(ctx_ptr, font.stroke_color.resource) new_wand = library.MagickMontageImage(self.wand, ctx_ptr, tile, thumbnail, mode_idx, frame) ctx_ptr = library.DestroyDrawingWand(ctx_ptr) ok = bool(new_wand) if ok: self.wand = new_wand self.reset_sequence() return ok def pseudo(self, width, height, pseudo='xc:'): """Creates a new image from ImageMagick's internal protocol coders. :param width: Total columns of the new image. :type width: :class:`numbers.Integral` :param height: Total rows of the new image. :type height: :class:`numbers.Integral` :param pseudo: The protocol & arguments for the pseudo image. :type pseudo: :class:`basestring` .. versionadded:: 0.5.0 """ assertions.assert_counting_number(width=width, height=height) assertions.assert_string(pseudo=pseudo) r = library.MagickSetSize(self.wand, width, height) if not r: self.raise_exception() r = library.MagickReadImage(self.wand, encode_filename(pseudo)) if not r: self.raise_exception() def read(self, file=None, filename=None, blob=None, background=None, colorspace=None, depth=None, extract=None, format=None, height=None, interlace=None, resolution=None, sampling_factors=None, units=None, width=None): """Read new image into Image() object. :param blob: reads an image from the ``blob`` byte array :type blob: :class:`bytes` :param file: reads an image from the ``file`` object :type file: file object :param filename: reads an image from the ``filename`` string. Additional :ref:`read_mods` are supported. :type filename: :class:`basestring` :param background: set default background color. :type background: :class:`Color`, :class:`basestring` :param colorspace: set default colorspace. See :const:`COLORSPACE_TYPES`. :type colorspace: :class:`basestring` :param depth: sets bits per color sample. Usually ``8``, or ``16``. :type depth: :class:`numbers.Integral` :param format: sets which image decoder to read with. Helpful when reading ``blob`` data with ambiguous headers. :type format: :class:`basestring` :param height: used with ``width`` to define the canvas size. Useful for reading image streams. :type height: :class:`numbers.Integral` :param interlace: Defines the interlacing scheme for raw data streams. See :const:`INTERLACE_TYPES`. :type interlace: :class:`basestring` :param resolution: set a resolution value (DPI), useful for vectorial formats (like PDF) :type resolution: :class:`collections.abc.Sequence`, :class:`numbers.Integral` :param sampling_factors: set up/down stampling factors for YUV data stream. Usually ``"4:2:2"`` :type sampling_factors: :class:`collections.abc.Sequence`, :class:`basestring` :param units: used with ``resolution``, can either be ``'pixelperinch'``, or ``'pixelpercentimeter'``. :type units: :class:`basestring` :param width: used with ``height`` to define the canvas size. Useful for reading image streams. :type width: :class:`numbers.Integral` .. versionadded:: 0.3.0 .. versionchanged:: 0.5.7 Added ``units`` parameter. .. versionchanged:: 0.6.3 Added, or documented, optional pre-read parameters: ``background``, ``colorspace``, ``depth``, ``format``, ``height``, ``interlace``, ``sampling_factors``, & ``width``. """ r = None # Resolution must be set after image reading. self._preamble_read( background=background, colorspace=colorspace, depth=depth, extract=extract, format=format, height=height, interlace=interlace, resolution=resolution, sampling_factors=sampling_factors, width=width ) if file is not None: if (isinstance(file, file_types) and hasattr(libc, 'fdopen') and hasattr(file, 'mode')): fd = libc.fdopen(file.fileno(), file.mode) r = library.MagickReadImageFile(self.wand, fd) elif not callable(getattr(file, 'read', None)): raise TypeError('file must be a readable file object' ', but the given object does not ' 'have read() method') else: blob = file.read() file = None if blob is not None: if not isinstance(blob, abc.Iterable): raise TypeError('blob must be iterable, not ' + repr(blob)) if not isinstance(blob, binary_type): blob = b''.join(blob) r = library.MagickReadImageBlob(self.wand, blob, len(blob)) elif filename is not None: filename = encode_filename(filename) r = library.MagickReadImage(self.wand, filename) if not r: self.raise_exception() msg = ('MagickReadImage returns false, but did not raise ' 'ImageMagick exception. This can occur when a delegate ' 'is missing, or returns EXIT_SUCCESS without generating a ' 'raster.') raise WandRuntimeError(msg) else: if units is not None: self.units = units def reset_sequence(self): """Remove any previously allocated :class:`~wand.sequence.SingleImage` instances in :attr:`sequence` attribute. .. versionadded:: 0.6.0 """ for instance in self.sequence.instances: if hasattr(instance, 'destroy'): instance.destroy() self.sequence.instances = [] def save(self, file=None, filename=None, adjoin=True): """Saves the image into the ``file`` or ``filename``. It takes only one argument at a time. :param file: a file object to write to :type file: file object :param filename: a filename string to write to :type filename: :class:`basestring` :param adjoin: write all images to a single multi-image file. Only available if file format supports frames, layers, & etc. :type adjoin: :class:`bool` .. versionadded:: 0.1.1 .. versionchanged:: 0.1.5 The ``file`` parameter was added. .. versionchanged:: 6.0.0 The ``adjoin`` parameter was added. """ if file is None and filename is None: raise TypeError('expected an argument') elif file is not None and filename is not None: raise TypeError('expected only one argument; but two passed') elif file is not None: if isinstance(file, string_type): raise TypeError('file must be a writable file object, ' 'but {0!r} is a string; did you want ' '.save(filename={0!r})?'.format(file)) elif isinstance(file, file_types) and hasattr(libc, 'fdopen'): fd = libc.fdopen(file.fileno(), file.mode) if library.MagickGetNumberImages(self.wand) > 1: r = library.MagickWriteImagesFile(self.wand, fd) else: r = library.MagickWriteImageFile(self.wand, fd) libc.fflush(fd) if not r: self.raise_exception() else: if not callable(getattr(file, 'write', None)): raise TypeError('file must be a writable file object, ' 'but it does not have write() method: ' + repr(file)) file.write(self.make_blob()) else: if not isinstance(filename, string_type): if not hasattr(filename, '__fspath__'): raise TypeError('filename must be a string, not ' + repr(filename)) filename = encode_filename(filename) if library.MagickGetNumberImages(self.wand) > 1: r = library.MagickWriteImages(self.wand, filename, adjoin) else: r = library.MagickWriteImage(self.wand, filename) if not r: self.raise_exception() class Iterator(Resource, abc.Iterator): """Row iterator for :class:`Image`. It shouldn't be instantiated directly; instead, it can be acquired through :class:`Image` instance:: assert isinstance(image, wand.image.Image) iterator = iter(image) It doesn't iterate every pixel, but rows. For example:: for row in image: for col in row: assert isinstance(col, wand.color.Color) print(col) Every row is a :class:`collections.abc.Sequence` which consists of one or more :class:`wand.color.Color` values. :param image: the image to get an iterator :type image: :class:`Image` .. versionadded:: 0.1.3 """ c_is_resource = library.IsPixelIterator c_destroy_resource = library.DestroyPixelIterator c_get_exception = library.PixelGetIteratorException c_clear_exception = library.PixelClearIteratorException def __init__(self, image=None, iterator=None): if image is not None and iterator is not None: raise TypeError('it takes only one argument at a time') with self.allocate(): if image is not None: if not isinstance(image, Image): raise TypeError('expected a wand.image.Image instance, ' 'not ' + repr(image)) self.resource = library.NewPixelIterator(image.wand) self.height = image.height else: if not isinstance(iterator, Iterator): raise TypeError('expected a wand.image.Iterator instance, ' 'not ' + repr(iterator)) self.resource = library.ClonePixelIterator(iterator.resource) self.height = iterator.height self.raise_exception() self.cursor = 0 def __iter__(self): return self def seek(self, y): assertions.assert_unsigned_integer(seek=y) if y > self.height: raise ValueError('can not be greater than height') self.cursor = y if y == 0: library.PixelSetFirstIteratorRow(self.resource) else: if not library.PixelSetIteratorRow(self.resource, y - 1): self.raise_exception() def __next__(self, x=None): if self.cursor >= self.height: self.destroy() raise StopIteration() self.cursor += 1 width = ctypes.c_size_t() pixels = library.PixelGetNextIteratorRow(self.resource, ctypes.byref(width)) if x is None: r_pixels = [None] * width.value for x in xrange(width.value): r_pixels[x] = Color.from_pixelwand(pixels[x]) return r_pixels return Color.from_pixelwand(pixels[x]) if pixels else None next = __next__ # Python 2 compatibility def clone(self): """Clones the same iterator. """ return type(self)(iterator=self) class ImageProperty(object): """The mixin class to maintain a weak reference to the parent :class:`Image` object. .. versionadded:: 0.3.0 """ def __init__(self, image): if not isinstance(image, BaseImage): raise TypeError('expected a wand.image.BaseImage instance, ' 'not ' + repr(image)) self._image = weakref.ref(image) @property def image(self): """(:class:`Image`) The parent image. It ensures that the parent :class:`Image`, which is held in a weak reference, still exists. Returns the dereferenced :class:`Image` if it does exist, or raises a :exc:`ClosedImageError` otherwise. :exc: `ClosedImageError` when the parent Image has been destroyed """ # Dereference our weakref and check that the parent Image still exists image = self._image() if image is not None: return image raise ClosedImageError( 'parent Image of {0!r} has been destroyed'.format(self) ) class OptionDict(ImageProperty, abc.MutableMapping): """Free-form mutable mapping of global internal settings. .. versionadded:: 0.3.0 .. versionchanged:: 0.5.0 Remove key check to :const:`OPTIONS`. Image properties are specific to vendor, and this library should not attempt to manage the 100+ options in a whitelist. """ def __iter__(self): return iter(OPTIONS) def __len__(self): return len(OPTIONS) def __getitem__(self, key): assertions.assert_string(key=key) opt_str = b'' opt_p = library.MagickGetOption(self.image.wand, binary(key)) if opt_p: opt_str = text(ctypes.string_at(opt_p)) opt_p = library.MagickRelinquishMemory(opt_p) else: raise KeyError(key) return opt_str def __setitem__(self, key, value): assertions.assert_string(key=key, value=value) image = self.image library.MagickSetOption(image.wand, binary(key), binary(value)) def __delitem__(self, key): self[key] = '' class Metadata(ImageProperty, abc.MutableMapping): """Class that implements dict-like read-only access to image metadata like EXIF or IPTC headers. Most WRITE encoders will ignore properties assigned here. :param image: an image instance :type image: :class:`Image` .. note:: You don't have to use this by yourself. Use :attr:`Image.metadata` property instead. .. versionadded:: 0.3.0 """ def __init__(self, image): if not isinstance(image, Image): raise TypeError('expected a wand.image.Image instance, ' 'not ' + repr(image)) super(Metadata, self).__init__(image) def __getitem__(self, k): """ :param k: Metadata header name string. :type k: :class:`basestring` :returns: a header value string :rtype: :class:`str` """ assertions.assert_string(key=k) image = self.image value = b'' vp = library.MagickGetImageProperty(image.wand, binary(k)) if vp: value = text(ctypes.string_at(vp)) vp = library.MagickRelinquishMemory(vp) else: raise KeyError(k) return value def __setitem__(self, k, v): """ :param k: Metadata header name string. :type k: :class:`basestring` :param v: Value to assign. :type v: :class:`basestring` .. versionadded: 0.5.0 """ assertions.assert_string(key=k, value=v) image = self.image r = library.MagickSetImageProperty(image.wand, binary(k), binary(v)) if not r: image.raise_exception() return v def __delitem__(self, k): """ :param k: Metadata header name string. :type k: :class:`basestring` .. versionadded: 0.5.0 """ assertions.assert_string(key=k) image = self.image r = library.MagickDeleteImageProperty(image.wand, binary(k)) if not r: image.raise_exception() def __iter__(self): image = self.image num = ctypes.c_size_t() props_p = library.MagickGetImageProperties(image.wand, b'', num) props = [text(ctypes.string_at(props_p[i])) for i in xrange(num.value)] props_p = library.MagickRelinquishMemory(props_p) return iter(props) def __len__(self): image = self.image num = ctypes.c_size_t() props_p = library.MagickGetImageProperties(image.wand, b'', num) props_p = library.MagickRelinquishMemory(props_p) return num.value class ArtifactTree(ImageProperty, abc.MutableMapping): """Splay tree to map image artifacts. Values defined here are intended to be used elseware, and will not be written to the encoded image. For example:: # Omit timestamp from PNG file headers. with Image(filename='input.png') as img: img.artifacts['png:exclude-chunks'] = 'tIME' img.save(filename='output.png') :param image: an image instance :type image: :class:`Image` .. note:: You don't have to use this by yourself. Use :attr:`Image.artifacts` property instead. .. versionadded:: 0.5.0 """ def __init__(self, image): if not isinstance(image, Image): raise TypeError('expected a wand.image.Image instance, ' 'not ' + repr(image)) super(ArtifactTree, self).__init__(image) def __getitem__(self, k): """ :param k: Metadata header name string. :type k: :class:`basestring` :returns: a header value string :rtype: :class:`str` .. versionadded: 0.5.0 """ assertions.assert_string(key=k) image = self.image vs = b'' vp = library.MagickGetImageArtifact(image.wand, binary(k)) if vp: vs = text(ctypes.string_at(vp)) vp = library.MagickRelinquishMemory(vp) if len(vs) < 1: vp = library.MagickGetImageProperty(image.wand, binary(k)) if vp: vs = text(ctypes.string_at(vp)) vp = library.MagickRelinquishMemory(vp) else: vs = None return vs def __setitem__(self, k, v): """ :param k: Metadata header name string. :type k: :class:`basestring` :param v: Value to assign. :type v: :class:`basestring` .. versionadded: 0.5.0 """ assertions.assert_string(key=k, value=v) image = self.image r = library.MagickSetImageArtifact(image.wand, binary(k), binary(v)) if not r: # pragma: no cover image.raise_exception() return v def __delitem__(self, k): """ :param k: Metadata header name string. :type k: :class:`basestring` .. versionadded: 0.5.0 """ assertions.assert_string(key=k) image = self.image r = library.MagickDeleteImageArtifact(image.wand, binary(k)) if not r: # pragma: no cover image.raise_exception() def __iter__(self): image = self.image num = ctypes.c_size_t(0) art_p = library.MagickGetImageArtifacts(image.wand, b'', num) props = [text(ctypes.string_at(art_p[i])) for i in xrange(num.value)] art_p = library.MagickRelinquishMemory(art_p) return iter(props) def __len__(self): image = self.image num = ctypes.c_size_t(0) art_p = library.MagickGetImageArtifacts(image.wand, b'', num) art_p = library.MagickRelinquishMemory(art_p) return num.value class ProfileDict(ImageProperty, abc.MutableMapping): """The mapping table of embedded image profiles. Use this to get, set, and delete whole profile payloads on an image. Each payload is a raw binary string. For example:: with Image(filename='photo.jpg') as img: # Extract EXIF with open('exif.bin', 'wb') as payload: payload.write(img.profiles['exif']) # Import ICC with open('color_profile.icc', 'rb') as payload: img.profiles['icc'] = payload.read() # Remove XMP del imp.profiles['xmp'] .. seealso:: `Embedded Image Profiles`__ for a list of supported profiles. __ https://imagemagick.org/script/formats.php#embedded .. versionadded:: 0.5.1 """ def __init__(self, image): if not isinstance(image, Image): raise TypeError('expected a wand.image.Image instance, ' 'not ' + repr(image)) super(ProfileDict, self).__init__(image) def __delitem__(self, k): assertions.assert_string(key=k) num = ctypes.c_size_t(0) profile_p = library.MagickRemoveImageProfile(self.image.wand, binary(k), num) profile_p = library.MagickRelinquishMemory(profile_p) def __getitem__(self, k): assertions.assert_string(key=k) num = ctypes.c_size_t(0) return_profile = None profile_p = library.MagickGetImageProfile(self.image.wand, binary(k), num) if num.value > 0: return_profile = ctypes.string_at(profile_p, num.value) profile_p = library.MagickRelinquishMemory(profile_p) return return_profile def __iter__(self): num = ctypes.c_size_t(0) prop = library.MagickGetImageProfiles(self.image.wand, b'', num) profiles = [text(ctypes.string_at(prop[i])) for i in xrange(num.value)] prop = library.MagickRelinquishMemory(prop) return iter(profiles) def __len__(self): num = ctypes.c_size_t(0) profiles_p = library.MagickGetImageProfiles(self.image.wand, b'', num) profiles_p = library.MagickRelinquishMemory(profiles_p) return num.value def __setitem__(self, k, v): assertions.assert_string(key=k) if not isinstance(v, binary_type): raise TypeError('value must be a binary string, not ' + repr(v)) r = library.MagickSetImageProfile(self.image.wand, binary(k), v, len(v)) if not r: self.image.raise_exception() class ChannelImageDict(ImageProperty, abc.Mapping): """The mapping table of separated images of the particular channel from the image. :param image: an image instance :type image: :class:`Image` .. note:: You don't have to use this by yourself. Use :attr:`Image.channel_images` property instead. .. versionadded:: 0.3.0 """ def __iter__(self): return iter(CHANNELS) def __len__(self): return len(CHANNELS) def __getitem__(self, channel): c = CHANNELS[channel] img = self.image.clone() if library.MagickSeparateImageChannel: succeeded = library.MagickSeparateImageChannel(img.wand, c) else: succeeded = library.MagickSeparateImage(img.wand, c) if not succeeded: try: img.raise_exception() except WandException: img.close() raise return img class ChannelDepthDict(ImageProperty, abc.Mapping): """The mapping table of channels to their depth. :param image: an image instance :type image: :class:`Image` .. note:: You don't have to use this by yourself. Use :attr:`Image.channel_depths` property instead. .. versionadded:: 0.3.0 """ def __iter__(self): return iter(CHANNELS) def __len__(self): return len(CHANNELS) def __getitem__(self, channel): c = CHANNELS[channel] if library.MagickGetImageChannelDepth: depth = library.MagickGetImageChannelDepth(self.image.wand, c) else: mask = 0 if c != 0: mask = library.MagickSetImageChannelMask(self.image.wand, c) depth = library.MagickGetImageDepth(self.image.wand) if mask != 0: library.MagickSetImageChannelMask(self.image.wand, mask) return int(depth) class HistogramDict(abc.Mapping): """Specialized mapping object to represent color histogram. Keys are colors, and values are the number of pixels. :param image: the image to get its histogram :type image: :class:`BaseImage` .. versionadded:: 0.3.0 """ def __init__(self, image): self.size = ctypes.c_size_t() self.pixels = library.MagickGetImageHistogram( image.wand, ctypes.byref(self.size) ) self.counts = None def __del__(self): if self.pixels: self.pixels = library.DestroyPixelWands(self.pixels, self.size.value) def __len__(self): if self.counts is None: return self.size.value return len(self.counts) def __iter__(self): if self.counts is None: self._build_counts() return iter(self.counts) def __getitem__(self, color): if self.counts is None: self._build_counts() if isinstance(color, string_type): color = Color(color) assertions.assert_color(color=color) return self.counts[color] def _build_counts(self): self.counts = {} for i in xrange(self.size.value): color_count = library.PixelGetColorCount(self.pixels[i]) color = Color.from_pixelwand(self.pixels[i]) self.counts[color] = color_count class ConnectedComponentObject(object): """Generic Python wrapper to translate :c:type:`CCObjectInfo` structure into a class describing objects found within an image. This class is generated by :meth:`Image.connected_components() ` method. .. versionadded:: 0.5.5 .. versionchanged:: 0.6.3 Added :attr:`merge` & :attr:`metric` for ImageMagick 7.0.10 .. versionchanged:: 0.6.8 Added :attr:`key` property for ImageMagick 7.1.0 """ #: (:class:`numbers.Integral`) Serialized object identifier #: starting at `0`. _id = None #: (:class:`numbers.Integral`) Width of objects minimum #: bounding rectangle. width = None #: (:class:`numbers.Integral`) Height of objects minimum #: bounding rectangle. height = None #: (:class:`numbers.Integral`) X offset of objects minimum #: bounding rectangle. left = None #: (:class:`numbers.Integral`) Y offset of objects minimum #: bounding rectangle. top = None #: (:class:`numbers.Real`) X offset of objects centroid. center_x = None #: (:class:`numbers.Real`) Y offset of objects centroid. center_y = None #: (:class:`numbers.Real`) Quantity of pixels that make-up #: the objects shape. area = None #: (:class:`~wand.color.Color`) The average color of the #: shape. mean_color = None #: (:class:`bool`) Object merge flag. Only available after #: ImageMagick-7.0.10. #: ..versionadded:: 0.6.3 merge = None #: (:class:`list`) List of doubles used by metric. Only available after #: ImageMagick-7.0.10. #: ..versionadded:: 0.6.3 metric = None def __init__(self, cc_object=None): if isinstance(cc_object, CCObjectInfo): self.clone_from_cc_object_info(cc_object) if isinstance(cc_object, CCObjectInfo70A): self.clone_from_cc_object_info(cc_object) self.clone_from_extra_70A_info(cc_object) if isinstance(cc_object, CCObjectInfo710): self.clone_from_cc_object_info(cc_object) self.clone_from_extra_70A_info(cc_object) self.clone_from_extra_710_info(cc_object) @property def size(self): """(:class:`tuple` (:attr:`width`, :attr:`height`)) Minimum bounding rectangle.""" return self.width, self.height @property def offset(self): """(:class:`tuple` (:attr:`left`, :attr:`top`)) Position of objects minimum bounding rectangle.""" return self.left, self.top @property def centroid(self): """(:class:`tuple` (:attr:`center_x`, :attr:`center_y`)) Center of object.""" return self.center_x, self.center_y def clone_from_cc_object_info(self, cc_object): """Copy data from :class:`~wand.cdefs.structures.CCObjectInfo`.""" self._id = cc_object._id self.width = cc_object.bounding_box.width self.height = cc_object.bounding_box.height self.left = cc_object.bounding_box.x self.top = cc_object.bounding_box.y self.center_x = cc_object.centroid.x self.center_y = cc_object.centroid.y self.area = cc_object.area pinfo_size = ctypes.sizeof(PixelInfo) raw_buffer = ctypes.create_string_buffer(pinfo_size) ctypes.memmove(raw_buffer, ctypes.byref(cc_object.color), pinfo_size) self.mean_color = Color(raw=raw_buffer) def clone_from_extra_70A_info(self, cc_object): """Copy the additional values from CCObjectInfo structure. This is the :attr:`merge` & :attr:`metric` properties added in ImageMagick 7.0.10. .. versionadded:: 0.6.3 """ self.merge = cc_object.merge self.metric = [] for i in range(cc_object.CCMaxMetrics): self.metric.append(cc_object.metric[i]) def clone_from_extra_710_info(self, cc_object): """Copy additional value from CCObjectInfo structure for properties added to ImageMagick 7.1.0. .. versionadded:: 0.6.8 """ self.key = cc_object.key def __repr__(self): fmt = ("{name}({_id}: {width}x{height}+{left}+{top} {center_x:.2f}," "{center_y:.2f} {area:.0f} {mean_color})") return fmt.format(name=self.__class__.__name__, **self.__dict__) class ClosedImageError(DestroyedResourceError): """An error that rises when some code tries access to an already closed image. """