You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
10888 lines
421 KiB
Python
10888 lines
421 KiB
Python
![]()
2 months ago
|
""":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() <wand.image.BaseImage.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() <wand.image.BaseImage.compare>` and
|
||
|
#: :meth:`Image.similarity() <wand.image.BaseImage.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() <wand.image.BaseImage.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() <BaseImage.posterize>` and
|
||
|
#: :meth:`Image.remap() <BaseImage.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() <BaseImage.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() <BaseImage.resample>` and
|
||
|
#: :meth:`Image.resize() <BaseImage.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 <BaseImage.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() <wand.image.BaseImage.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 <wand.image.BaseImage.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() <wand.image.BaseImage.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() <wand.image.BaseImage.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 <wand.image.BaseImage>`
|
||
|
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() <wand.image.BaseImage.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
|
||
|
|
||
|
<ColorCorrectionCollection xmlns="urn:ASC:CDL:v1.2">
|
||
|
<ColorCorrection id="cc03345">
|
||
|
<SOPNode>
|
||
|
<Slope> 0.9 1.2 0.5 </Slope>
|
||
|
<Offset> 0.4 -0.5 0.6 </Offset>
|
||
|
<Power> 1.0 0.8 1.5 </Power>
|
||
|
</SOPNode>
|
||
|
<SATNode>
|
||
|
<Saturation> 0.85 </Saturation>
|
||
|
</SATNode>
|
||
|
</ColorCorrection>
|
||
|
</ColorCorrectionCollection>
|
||
|
|
||
|
: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() <wand.drawing.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() <wand.image.BaseImage.coalesce>` before
|
||
|
manipulating any frames. For timing accuracy, any
|
||
|
:attr:`SingleImage.delay <wand.sequence.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 <wand.image.BaseImage>`
|
||
|
|
||
|
.. 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()
|
||
|
<wand.image.BaseImage.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.
|
||
|
|
||
|
"""
|