wand.image — Image objects

Opens and manipulates images. Image objects can be used in 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)
wand.image.ALPHA_CHANNEL_TYPES = ('undefined', 'activate', 'associate', 'background', 'copy', 'deactivate', 'discrete', 'disassociate', 'extract', 'off', 'on', 'opaque', 'remove', 'set', 'shape', 'transparent')

(tuple) The list of 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'

See also

ImageMagick Image Channel
Describes the SetImageAlphaChannel method which can be used to modify alpha channel. Also describes AlphaChannelType
wand.image.AUTO_THRESHOLD_METHODS = ('undefined', 'kapur', 'otsu', 'triangle')

(tuple) The list of methods used by Image.auto_threshold()

  • 'undefined'
  • 'kapur'
  • 'otsu'
  • 'triangle'

New in version 0.5.5.

wand.image.CHANNELS = {'all_channels': 134217727, 'alpha': 16, 'black': 8, 'blue': 4, 'composite_channels': 31, 'cyan': 1, 'default_channels': 134217727, 'gray': 1, 'gray_channels': 1, 'green': 2, 'index': 32, 'magenta': 2, 'meta': 256, 'opacity': 16, 'readmask': 64, 'red': 1, 'rgb': 7, 'rgb_channels': 7, 'sync_channels': 131072, 'true_alpha': 256, 'undefined': 0, 'write_mask': 128, 'yellow': 4}

(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'

See also

ImageMagick Color Channels
Lists the various channel types with descriptions of each

Changed in version 0.5.5: Deprecated true_alpha, rgb_channels, and gray_channels values in favor of MagickCore channel parser.

wand.image.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')

(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'

See also

ImageMagick Color Management
Describes the ImageMagick color management operations

New in version 0.3.4.

wand.image.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')

(tuple) The list of compare metric types used by Image.compare() and Image.similarity() methods.

  • 'undefined'
  • 'absolute'
  • 'fuzz'
  • 'mean_absolute'
  • 'mean_error_per_pixel'
  • 'mean_squared'
  • 'normalized_cross_correlation'
  • 'peak_absolute'
  • 'peak_signal_to_noise_ratio'
  • 'perceptual_hash' - Available with ImageMagick-7
  • 'root_mean_square'
  • 'structural_similarity' - Available with ImageMagick-7
  • 'structural_dissimilarity' - Available with ImageMagick-7

New in version 0.4.3.

Changed in version 0.5.4: - Remapped MetricType enum.

wand.image.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')
'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'.

See also

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 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.
wand.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')

(tuple) The list of Image.compression types.

New in version 0.3.6.

Changed in version 0.5.0: Support for ImageMagick-6 & ImageMagick-7

wand.image.DISPOSE_TYPES = ('undefined', 'none', 'background', 'previous')

(tuple) The list of BaseImage.dispose types.

New in version 0.5.0.

wand.image.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')

(tuple) The list of 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'

New in version 0.4.1.

wand.image.DITHER_METHODS = ('undefined', 'no', 'riemersma', 'floyd_steinberg')

(tuple) The list of Dither methods. Used by Image.posterize() and Image.remap() methods.

  • 'undefined'
  • 'no'
  • 'riemersma'
  • 'floyd_steinberg'

New in version 0.5.0.

wand.image.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')

(tuple) The list of evaluation operators. Used by Image.evaluate() method.

  • 'undefined'
  • 'abs'
  • 'add'
  • 'addmodulus'
  • 'and'
  • 'cosine'
  • 'divide'
  • 'exponential'
  • 'gaussiannoise'
  • 'impulsenoise'
  • 'laplaciannoise'
  • 'leftshift'
  • 'log'
  • 'max'
  • 'mean'
  • 'median'
  • 'min'
  • 'multiplicativenoise'
  • 'multiply'
  • 'or'
  • 'poissonnoise'
  • 'pow'
  • 'rightshift'
  • 'set'
  • 'sine'
  • 'subtract'
  • 'sum'
  • 'threshold'
  • 'thresholdblack'
  • 'thresholdwhite'
  • 'uniformnoise'
  • 'xor'

See also

ImageMagick Image Evaluation Operators
Describes the MagickEvaluateImageChannel method and lists the various evaluations operators
wand.image.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')

(tuple) The list of filter types. Used by Image.resample() and Image.resize() methods.

  • 'undefined'
  • 'point'
  • 'box'
  • 'triangle'
  • 'hermite'
  • 'hanning'
  • 'hamming'
  • 'blackman'
  • 'gaussian'
  • 'quadratic'
  • 'cubic'
  • 'catrom'
  • 'mitchell'
  • 'jinc'
  • 'sinc'
  • 'sincfast'
  • 'kaiser'
  • 'welsh'
  • 'parzen'
  • 'bohman'
  • 'bartlett'
  • 'lagrange'
  • 'lanczos'
  • 'lanczossharp'
  • 'lanczos2'
  • 'lanczos2sharp'
  • 'robidoux'
  • 'robidouxsharp'
  • 'cosine'
  • 'spline'
  • 'sentinel'

See also

ImageMagick Resize Filters
Demonstrates the results of resampling images using the various resize filters and blur settings available in ImageMagick.
wand.image.FUNCTION_TYPES = ('undefined', 'arcsin', 'arctan', 'polynomial', 'sinusoid')

(tuple) The list of Image.function types.

  • 'undefined'
  • 'arcsin'
  • 'arctan'
  • 'polynomial'
  • 'sinusoid'
wand.image.GRAVITY_TYPES = ('forget', 'north_west', 'north', 'north_east', 'west', 'center', 'east', 'south_west', 'south', 'south_east', 'static')

(tuple) The list of gravity types.

  • 'forget'
  • 'north_west'
  • 'north'
  • 'north_east'
  • 'west'
  • 'center'
  • 'east'
  • 'south_west'
  • 'south'
  • 'south_east'

New in version 0.3.0.

wand.image.IMAGE_LAYER_METHOD = ('undefined', 'coalesce', 'compareany', 'compareclear', 'compareoverlay', 'dispose', 'optimize', 'optimizeimage', 'optimizeplus', 'optimizetrans', 'removedups', 'removezero', 'composite', 'merge', 'flatten', 'mosaic', 'trimbounds')

(tuple) The list of methods for merge_layers() and compare_layers().

New in version 0.4.3.

wand.image.IMAGE_TYPES = ('undefined', 'bilevel', 'grayscale', 'grayscalealpha', 'palette', 'palettealpha', 'truecolor', 'truecoloralpha', 'colorseparation', 'colorseparationalpha', 'optimize', 'palettebilevelalpha')

(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

See also

ImageMagick Image Types
Describes the MagickSetImageType method which can be used to set the type of an image
wand.image.INTERLACE_TYPES = ('undefined', 'no', 'line', 'plane', 'partition', 'gif', 'jpeg', 'png')

(tuple) The list of interlace schemes.

  • 'undefined'
  • 'no'
  • 'line'
  • 'plane'
  • 'partition'
  • 'gif'
  • 'jpeg'
  • 'png'

New in version 0.5.2.

wand.image.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')

(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'
wand.image.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')

(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'
wand.image.NOISE_TYPES = ('undefined', 'uniform', 'gaussian', 'multiplicative_gaussian', 'impulse', 'laplacian', 'poisson', 'random')

(tuple) The list of noise types used by Image.noise() method.

  • 'undefined'
  • 'uniform'
  • 'gaussian'
  • 'multiplicative_gaussian'
  • 'impulse'
  • 'laplacian'
  • 'poisson'
  • 'random'

New in version 0.5.3.

wand.image.ORIENTATION_TYPES = ('undefined', 'top_left', 'top_right', 'bottom_right', 'bottom_left', 'left_top', 'right_top', 'right_bottom', 'left_bottom')

(tuple) The list of orientation types.

New in version 0.3.0.

wand.image.PIXEL_INTERPOLATE_METHODS = ('undefined', 'average', 'average9', 'average16', 'background', 'bilinear', 'blend', 'catrom', 'integer', 'mesh', 'nearest', 'spline')

(tuple) List of interpolate pixel methods (ImageMagick-7 only.)

  • 'undefined'
  • 'average'
  • 'average9'
  • 'average16'
  • 'background'
  • 'bilinear'
  • 'blend'
  • 'catrom'
  • 'integer'
  • 'mesh'
  • 'nearest'
  • 'spline'

New in version 0.5.0.

wand.image.RENDERING_INTENT_TYPES = ('undefined', 'saturation', 'perceptual', 'absolute', 'relative')

(tuple) List of rendering intent types used for Image.rendering_intent property.

  • 'undefined'
  • 'saturation'
  • 'perceptual'
  • 'absolute'
  • 'relative'

New in version 0.5.4.

wand.image.SPARSE_COLOR_METHODS = {'barycentric': 1, 'bilinear': 7, 'inverse': 19, 'manhattan': 20, 'shepards': 16, 'undefined': 0, 'voronoi': 18}

(tuple) List of sparse color methods used by Image.sparse_color()

  • 'undefined'
  • 'barycentric'
  • 'bilinear'
  • 'shepards'
  • 'voronoi'
  • 'inverse'
  • 'manhattan'

New in version 0.5.3.

wand.image.STATISTIC_TYPES = ('undefined', 'gradient', 'maximum', 'mean', 'median', 'minimum', 'mode', 'nonpeak', 'root_mean_square', 'standard_deviation')

(tuple) The list of statistic types used by Image.statistic().

  • 'undefined'
  • 'gradient'
  • 'maximum'
  • 'mean'
  • 'median'
  • 'minimum'
  • 'mode'
  • 'nonpeak'
  • 'root_mean_square'
  • 'standard_deviation'

New in version 0.5.3.

wand.image.STORAGE_TYPES = ('undefined', 'char', 'double', 'float', 'integer', 'long', 'quantum', 'short')

(tuple) The list of pixel storage types.

  • 'undefined'
  • 'char'
  • 'double'
  • 'float'
  • 'integer'
  • 'long'
  • 'quantum'
  • 'short'

New in version 0.5.0.

wand.image.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')

(tuple) The list of 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'

New in version 0.4.1.

wand.image.UNIT_TYPES = ('undefined', 'pixelsperinch', 'pixelspercentimeter')

(tuple) The list of resolution unit types.

  • 'undefined'
  • 'pixelsperinch'
  • 'pixelspercentimeter'

See also

ImageMagick Image Units
Describes the MagickSetImageUnits method which can be used to set image units of resolution
class wand.image.BaseImage(wand)

The abstract base of Image (container) and SingleImage. That means the most of operations, defined in this abstract class, are possible for both Image and SingleImage.

New in version 0.3.0.

adaptive_blur(radius=0.0, sigma=0.0, channel=None)

Adaptively blurs the image by decreasing Gaussian as the operator approaches detected edges.

Parameters:
  • radius (numbers.Real) – size of gaussian aperture.
  • sigma (numbers.Real) – Standard deviation of the gaussian filter.
  • channel (basestring) – Apply the blur effect on a specific channel. See CHANNELS.

New in version 0.5.3.

Changed in version 0.5.5: Added optional channel argument

adaptive_resize(columns=None, rows=None)

Adaptively resize image by applying Mesh interpolation.

Parameters:

New in version 0.5.3.

adaptive_sharpen(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.

Parameters:
  • radius (numbers.Real) – size of gaussian aperture.
  • sigma (numbers.Real) – Standard deviation of the gaussian filter.
  • channel (basestring) – Apply the sharpen effect on a specific channel. See CHANNELS.

New in version 0.5.3.

Changed in version 0.5.5: Added optional channel argument

adaptive_threshold(width, height, offset=0.0)

Applies threshold for each pixel based on neighboring pixel values.

Parameters:

New in version 0.5.3.

alpha_channel

(bool) Get state of image alpha channel. It can also be used to enable/disable alpha channel, but with different behavior new, copied, or existing.

Behavior of setting alpha_channel is defined with the following values:

  • 'activate', 'on', or True will enable an images
    alpha channel. Existing alpha data is preserved.
  • 'deactivate', 'off', or 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 background_color.
  • 'remove' will composite background_color value.
  • 'background' replaces full-transparent color with background
    color.

New in version 0.2.1.

Changed in version 0.4.1: Support for additional setting values. However Image.alpha_channel will continue to return bool if the current alpha/matte state is enabled.

Changed in version 0.6.0: Setting the alpha channel will apply the change to all frames in the image stack.

animation

(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 False even if image/ico consits of two or more images of the same size.

For example, it’s False for image/jpeg, image/gif, image/ico.

If image/gif has two or more frames, it’s True. If image/gif has only one frame, it’s False.

New in version 0.3.0.

Changed in version 0.3.8: Became to accept image/x-gif as well.

annotate(text, drawing_wand, left=0, baseline=0, angle=0)

Draws text on an image. This method differs from caption() as it uses Drawing class to manage the font configuration & style context.

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')
Parameters:
  • text (wand.drawing.Drawing) – String to annotate on image.
  • drawing_wand – Font configuration & style context.
  • left (numbers.Real) – X-axis offset of the text baseline.
  • baseline (numbers.Real) – Y-axis offset of the bottom of the text.
  • angle (numbers.Real) – Degree rotation to draw text at.

New in version 0.5.6.

antialias

(bool) If vectors & fonts will use anti-aliasing.

Changed in version 0.5.0: Previously named font_antialias.

auto_gamma()

Adjust the gamma level of an image.

New in version 0.5.4.

auto_level()

Scale the minimum and maximum values to a full quantum range.

New in version 0.5.4.

auto_orient()

Adjusts an image so that its orientation is suitable for viewing (i.e. top-left orientation). If available it uses MagickAutoOrientImage() (was added in ImageMagick 6.8.9+) if you have an older magick library, it will use _auto_orient() method for fallback.

New in version 0.4.1.

auto_threshold(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.

Parameters:method (basestring) – Which threshold method to apply. See AUTO_THRESHOLD_METHODS. Defaults to 'kapur'.
Raises:WandLibraryVersionError – if function is not available on system’s library.

New in version 0.5.5.

background_color

(wand.color.Color) The image background color. It can also be set to change the background color.

New in version 0.1.9.

black_threshold(threshold)

Forces all pixels above a given color as black. Leaves pixels above threshold unaltered.

Parameters:threshold (Color) – Color to be referenced as a threshold.

New in version 0.5.3.

blue_primary

(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).

New in version 0.5.2.

blue_shift(factor=1.5)

Mutes colors of the image by shifting blue values.

Parameters:factor (numbers.Real) – Amount to adjust values.

New in version 0.5.3.

blur(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 blur() selects a suitable radius for you.

Parameters:
  • radius (numbers.Real) – the radius of the, in pixels, not counting the center pixel. Default is 0.0.
  • sigma (numbers.Real) – the standard deviation of the, in pixels. Default value is 0.0.
  • channel (basestring) – Optional color channel to apply blur. See CHANNELS.

New in version 0.4.5.

Changed in version 0.5.5: Added optional channel argument.

Changed in version 0.5.7: Positional arguments radius & sigman have been converted to key-word arguments.

border(color, width, height, compose='copy')

Surrounds the image with a border.

Parameters:
  • bordercolor – the border color pixel wand
  • width (numbers.Integral) – the border width
  • height (numbers.Integral) – the border height
  • compose (basestring) – Use composite operator when applying frame. Only used if called with ImageMagick 7+.

New in version 0.3.0.

Changed in version 0.5.0: Added compose paramater, and ImageMagick 7 support.

border_color

(wand.color.Color) The image border color. Used for special effects like polaroid().

New in version 0.5.4.

brightness_contrast(brightness=0.0, contrast=0.0, channel=None)

Converts brightness & contrast paramaters into a slope & intercept, and applies a polynomial function.

Parameters:
  • brightness (numbers.Real) – between -100.0 and 100.0. Default is 0.0 for unchanged.
  • contrast (numbers.Real) – between -100.0 and 100.0. Default is 0.0 for unchanged.
  • channel – Isolate a single color channel to apply contrast. See CHANNELS.

New in version 0.5.4.

Changed in version 0.5.5: Optional channel argument added.

canny(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.

Parameters:
  • radius (numbers.Real) – Size of gaussian filter.
  • sigma (numbers.Real) – Standard deviation of gaussian filter.
  • lower_percent (numbers.Real) – Normalized lower threshold. Values between 0.0 (0%) and 1.0 (100%). The default value is 0.1 or 10%.
  • upper_percent (numbers.Real) – Normalized upper threshold. Values between 0.0 (0%) and 1.0 (100%). The default value is 0.3 or 30%.
Raises:

WandLibraryVersionError – if function is not available on system’s library.

New in version 0.5.5.

caption(text, left=0, top=0, width=None, height=None, font=None, gravity=None)

Writes a caption text into the position.

Parameters:

New in version 0.3.0.

cdl(ccc)

Alias for color_decision_list().

New in version 0.5.7.

charcoal(radius, sigma)

Transform an image into a simulated charcoal drawing.

Parameters:
  • radius (numbers.Real) – The size of the Gaussian operator.
  • sigma (numbers.Real) – The standard deviation of the Gaussian.

New in version 0.5.3.

chop(width, height, x=0, y=0)

Removes a region of an image, and reduces the image size accordingly.

Parameters:

New in version 0.5.5.

clahe(width, height, number_bins, clip_limit)

Contrast limited adaptive histogram equalization.

Warning

The CLAHE method is only available with ImageMagick-7.

Parameters:
Raises:

WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.5.

clamp(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.

Parameters:channel (basestring) – Optional color channel.

New in version 0.5.0.

Changed in version 0.5.5: Added channel argument.

clone()

Clones the image. It is equivalent to call Image with image parameter.

with img.clone() as cloned:
    # manipulate the cloned image
    pass
Returns:the cloned new image
Return type:Image

New in version 0.1.1.

clut(image, method='undefined', channel=None)

Replace color values by referencing another image as a Color Look Up Table.

Parameters:

New in version 0.5.0.

Changed in version 0.5.5: Added optional channel argument.

coalesce()

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.

New in version 0.5.0.

color_decision_list(ccc)

Applies color correction from a Color Correction Collection (CCC) xml string. An example of 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>
Parameters:ccc (basestring) – A XML string of the CCC contents.

New in version 0.5.7.

color_map(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 colors of the image.

Note

Ensure the image type is set to 'palette' before calling the 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)]
    # ...
Parameters:
Returns:

Color at index.

Return type:

wand.color.Color

New in version 0.5.3.

color_matrix(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:

\[\begin{split}\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}\end{split}\]

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 0 0 0
Alpha’ 0 0 0 0 0 0
Offset’ 0 0 0 0 0 0

See color-matrix for examples.

Parameters:matrix (collections.abc.Sequence) – 2D List of doubles.

New in version 0.5.3.

colorize(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.

Parameters:

New in version 0.5.3.

colors

(numbers.Integral) Count of unique colors used within the image. This is READ ONLY property.

New in version 0.5.3.

colorspace

(basestring) The image colorspace.

Defines image colorspace as in COLORSPACE_TYPES enumeration.

It may raise ValueError when the colorspace is unknown.

New in version 0.3.4.

combine(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')
Parameters:
  • channel (basestring) – Determines the colorchannel ordering of the sequence. Only used for ImageMagick-6. See CHANNELS.
  • colorspace (basestring) – Determines the colorchannel ordering of the sequence. Only used for ImageMagick-7. See COLORSPACE_TYPES.

New in version 0.5.9.

compare(image, metric='undefined', highlight=None, lowlight=None)

Compares an image to a reconstructed image.

Set 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')
Parameters:
  • image (wand.image.Image) – The reference image
  • metric (basestring) – The metric type to use for comparing. See COMPARE_METRICS
  • highlight (Color or basestring) – Set the color of the delta pixels in the resulting difference image.
  • lowlight (Color or basestring) – Set the color of the similar pixels in the resulting difference image.
Returns:

The difference image(wand.image.Image), the computed distortion between the images (numbers.Integral)

Return type:

tuple

New in version 0.4.3.

Changed in version 0.5.3: Added support for highlight & lowlight.

complex(operator='undefined', snr=None)

Performs complex mathematics against two images in a sequence, and generates a new image with two results.

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')

Warning

This class method is only available with ImageMagick 7.0.8-41, or greater.

Parameters:
  • operator (basestring) – Define which mathematic operator to perform. See COMPLEX_OPERATORS.
  • snr (basestring) – Optional SNR parameter for 'divide' operator.
Raises:

WandLibraryVersionError – If ImageMagick library does not support this function.

New in version 0.5.5.

compose

(basestring) The type of image compose. It’s a string from COMPOSITE_OPERATORS list. It also can be set.

New in version 0.5.1.

composite(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.

Parameters:
  • image (wand.image.Image) – the image placed over the current image
  • left (numbers.Integral) – the x-coordinate where image will be placed
  • top (numbers.Integral) – the y-coordinate where image will be placed
  • operator (basestring) – the operator that affects how the composite is applied to the image. available values can be found in the COMPOSITE_OPERATORS list. Default is 'over'.
  • arguments (basestring) – Additional numbers given as a geometry string, or comma delimited values. This is needed for 'blend', 'displace', 'dissolve', and 'modulate' operators.
  • gravity – Calculate the top & left values based on gravity value from GRAVITY_TYPES.
Type:

gravity: basestring

New in version 0.2.0.

Changed in version 0.5.3: The operator can be set, as well as additional composite arguments.

Changed in version 0.5.3: Optional gravity argument was added.

composite_channel(channel, image, operator, left=None, top=None, arguments=None, gravity=None)

Composite two images using the particular channel.

Parameters:
  • channel – the channel type. available values can be found in the CHANNELS mapping
  • image (Image) – the composited source image. (the receiver image becomes the destination)
  • operator (basestring) – the operator that affects how the composite is applied to the image. available values can be found in the COMPOSITE_OPERATORS list
  • left (numbers.Integral) – the column offset of the composited source image
  • top (numbers.Integral) – the row offset of the composited source image
  • arguments (basestring) – Additional numbers given as a geometry string, or comma delimited values. This is needed for 'blend', 'displace', 'dissolve', and 'modulate' operators.
  • gravity – Calculate the top & left values based on gravity value from GRAVITY_TYPES.
Type:

gravity: basestring

Raises:

ValueError – when the given channel or operator is invalid

New in version 0.3.0.

Changed in version 0.5.3: Support for optional composite arguments has been added.

Changed in version 0.5.3: Optional gravity argument was added.

compression

(basestring) The type of image compression. It’s a string from COMPRESSION_TYPES list. It also can be set.

New in version 0.3.6.

Changed in version 0.5.2: Setting compression now sets both image_info and images in the internal image stack.

compression_quality

(numbers.Integral) Compression quality of this image.

New in version 0.2.0.

Changed in version 0.5.2: Setting compression_quality now sets both image_info and images in the internal image stack.

concat(stacked=False)

Concatenates images in stack into a single image. Left-to-right by default, top-to-bottom if stacked is True.

Parameters:stacked (bool) – stack images in a column, or in a row (default)

New in version 0.5.0.

connected_components(connectivity=4, area_threshold=None, mean_color=False, keep=None, remove=None)

Evaluates binary image, and groups connected pixels into objects. This method will also return a list of ConnectedComponentObject instances that will describe an object’s features.

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 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()
Parameters:
  • connectivity (numbers.Integral) – 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.
  • area_threshold (basestring) – Optional argument to exclude objects under an area size.
  • mean_color (bool) – Optional argument. Replace object color with mean color of the source image.
  • keep (basestring) – Comma separated list of object IDs to isolate, the reset are converted to transparent.
  • remove (basestring) – Comma separated list of object IDs to ignore, and convert to transparent.
Returns:

A list of ConnectedComponentObject.

Return type:

list [ConnectedComponentObject]

Raises:

WandLibraryVersionError – If ImageMagick library does not support this method.

New in version 0.5.5.

Changed in version 0.5.6: Added mean_color, keep, & remove optional arguments.

contrast(sharpen=True)

Enhances the difference between lighter & darker values of the image. Set sharpen to False to reduce contrast.

Parameters:sharpen (bool) – Increase, or decrease, contrast. Default is True for increased contrast.

New in version 0.5.7.

contrast_stretch(black_point=0.0, white_point=None, channel=None)

Enhance contrast of image by adjusting the span of the available colors.

Parameters:
  • black_point (numbers.Real) – black point between 0.0 and 1.0. default is 0.0
  • white_point (numbers.Real) – white point between 0.0 and 1.0. Defaults to the same value given to the black_point argument.
  • channel (CHANNELS) – optional color channel to apply contrast stretch
Raises:

ValueError – if channel is not in CHANNELS

New in version 0.4.1.

Changed in version 0.5.5: The white_point argument will now default to the value given by the black_point argument.

crop(left=0, top=0, right=None, bottom=None, width=None, height=None, reset_coords=True, gravity=None)

Crops the image in-place.

+--------------------------------------------------+
|              ^                         ^         |
|              |                         |         |
|             top                        |         |
|              |                         |         |
|              v                         |         |
| <-- left --> +-------------------+  bottom       |
|              |             ^     |     |         |
|              | <-- width --|---> |     |         |
|              |           height  |     |         |
|              |             |     |     |         |
|              |             v     |     |         |
|              +-------------------+     v         |
| <--------------- right ---------->               |
+--------------------------------------------------+
Parameters:
  • left (numbers.Integral) – x-offset of the cropped image. default is 0
  • top (numbers.Integral) – y-offset of the cropped image. default is 0
  • right (numbers.Integral) – second x-offset of the cropped image. default is the width of the image. this parameter and width parameter are exclusive each other
  • bottom (numbers.Integral) – second y-offset of the cropped image. default is the height of the image. this parameter and height parameter are exclusive each other
  • width (numbers.Integral) – the width of the cropped image. default is the width of the image. this parameter and right parameter are exclusive each other
  • height (numbers.Integral) – the height of the cropped image. default is the height of the image. this parameter and bottom parameter are exclusive each other
  • reset_coords (bool) – 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.
  • gravity (GRAVITY_TYPES) – optional flag. If set, will calculate the top and left attributes. This requires both width and height parameters to be included.
Raises:

ValueError – when one or more arguments are invalid

Note

If you want to crop the image but not in-place, use slicing operator.

Changed in version 0.4.1: Added gravity option. Using gravity along with width & height to auto-adjust left & top attributes.

Changed in version 0.1.8: Made to raise ValueError instead of IndexError for invalid width/height arguments.

New in version 0.1.7.

cycle_color_map(offset=1)

Shift the image color-map by a given offset.

Parameters:offset (numbers.Integral) – number of steps to rotate index by.

New in version 0.5.3.

deconstruct()

Iterates over internal image stack, and adjust each frame size to minimum bounding region of any changes from the previous frame.

New in version 0.5.0.

delay

(numbers.Integral) The number of ticks between frames.

New in version 0.5.9.

depth

(numbers.Integral) The depth of this image.

New in version 0.2.1.

deskew(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.

New in version 0.5.0.

despeckle()

Applies filter to reduce noise in image.

New in version 0.5.0.

dirty = None

(bool) Whether the image is changed or not.

dispose

(basestring) Controls how the image data is handled during animations. Values are from DISPOSE_TYPES list, and can also be set.

See also

Dispose Images section in Animation Basics article.

New in version 0.5.0.

distort(method, arguments, best_fit=False)

Distorts an image using various distorting methods.

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')
../_images/checks.png ../_images/checks_perspective.png

Use virtual_pixel, background_color, and matte_color properties to control the behavior of pixels rendered outside of the image boundaries.

Use interpolate_method to control how images scale-up.

Distortion viewport, and scale, can be defined by using Image.artifacts dictionary. For example:

img.artifacts['distort:viewport'] = '44x44+15+0'
img.artifacts['distort:scale'] = '10'
Parameters:
  • method (basestring) – Distortion method name from DISTORTION_METHODS
  • arguments (collections.abc.Sequence) – List of distorting float arguments unique to distortion method
  • best_fit (bool) – Attempt to resize resulting image fit distortion. Defaults False

New in version 0.4.1.

edge(radius=0.0)

Applies convolution filter to detect edges.

Parameters:radius (numbers.Real) – aperture of detection filter.

New in version 0.5.0.

emboss(radius=0.0, sigma=0.0)

Applies convolution filter against Gaussians filter.

Note

The radius value should be larger than sigma for best results.

Parameters:

New in version 0.5.0.

enhance()

Applies digital filter to reduce noise.

New in version 0.5.0.

equalize(channel=None)

Equalizes the image histogram

Parameters:channel (basestring) – Optional channel. See CHANNELS.

New in version 0.3.10.

Changed in version 0.5.5: Added optional channel argument.

evaluate(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)
Parameters:
  • operator (EVALUATE_OPS) – Type of operation to calculate
  • value (numbers.Real) – Number to calculate with operator
  • channel (CHANNELS) – Optional channel to apply operation on.
Raises:
  • TypeError – When value is not numeric.
  • ValueError – When operator, or channel are not defined in constants.

New in version 0.4.1.

export_pixels(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 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.

Parameters:
  • x (numbers.Integral) – horizontal starting coordinate of raster.
  • y (numbers.Integral) – vertical starting coordinate of raster.
  • width (numbers.Integral) – horizontal length of raster.
  • height (numbers.Integral) – vertical length of raster.
  • channel_map (basestring) – a string listing the channel data format for each pixel.
  • storage (basestring) – what data type each value should be calculated as.
Returns:

list of values.

Return type:

collections.abc.Sequence

New in version 0.5.0.

extent(width=None, height=None, x=0, y=0)

extends the image as defined by the geometry, gravity, and wand background color. Set the (x,y) offset of the geometry to move the original wand relative to the extended wand.

Parameters:

New in version 0.4.5.

features(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.

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)
Parameters:distance (numbers.Integral) – Define the distance if pixels to calculate.
Returns:a dict mapping each color channel with a dict of each feature.
Return type:dict

New in version 0.5.5.

fft(magnitude=True)

Alias for forward_fourier_transform().

New in version 0.5.7.

flip()

Creates a vertical mirror image by reflecting the pixels around the central x-axis. It manipulates the image in place.

New in version 0.3.0.

flop()

Creates a horizontal mirror image by reflecting the pixels around the central y-axis. It manipulates the image in place.

New in version 0.3.0.

font

(wand.font.Font) The current font options.

font_antialias

Deprecated since version 0.5.0: Use antialias instead.

font_path

(basestring) The path of the current font. It also can be set.

font_size

(numbers.Real) The font size. It also can be set.

format

(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 ValueError when the format is unsupported.

See also

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.

New in version 0.1.6.

forward_fourier_transform(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).

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')

Note

ImageMagick must have HDRI support to compute real & imaginary components (i.e. magnitude=False).

Parameters:magnitude (bool) – If True, generate magnitude & phase, else real & imaginary. Default True

New in version 0.5.5.

frame(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.

Parameters:
  • matte (wand.color.Color) – color of the frame
  • width (numbers.Integral) – total size of frame on x-axis
  • height (numbers.Integral) – total size of frame on y-axis
  • inner_bevel (numbers.Real) – inset shadow length
  • outer_bevel (numbers.Real) – outset highlight length
  • compose (basestring) – Optional composite operator. Default 'over', and only available with ImageMagick-7.

New in version 0.4.1.

Changed in version 0.5.6: Added optional compose parameter.

function(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 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
Parameters:
Raises:
  • ValueError – when a function, or channel is not defined in there respected constant
  • TypeError – if arguments is not a sequence

New in version 0.4.1.

fuzz

(numbers.Real) The normalized real number between 0.0 and quantum_range. This property influences the accuracy of compare().

New in version 0.5.3.

fx(expression, channel=None)

Manipulate each pixel of an image by given expression.

FX will preserver current wand instance, and return a new instance of Image containing affected pixels.

Defaults entire image, but can isolate affects to single color channel by passing CHANNELS value to channel parameter.

See also

The anatomy of FX expressions can be found at http://www.imagemagick.org/script/fx.php

Parameters:
  • expression (basestring) – The entire FX expression to apply
  • channel (CHANNELS) – Optional channel to target.
Returns:

A new instance of an image with expression applied

Return type:

Image

New in version 0.4.1.

gamma(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.

Parameters:
  • adjustment_value (numbers.Real) – value to adjust gamma level. Default 1.0
  • channel (basestring) – optional channel to apply gamma correction
Raises:

New in version 0.4.1.

gaussian_blur(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 blur() selects a suitable radius for you.

Parameters:
  • radius (numbers.Real) – the radius of the, in pixels, not counting the center pixel
  • sigma (numbers.Real) – the standard deviation of the, in pixels
  • channel (basestring) – Optional color channel to target. See CHANNELS

New in version 0.3.3.

Changed in version 0.5.5: Added channel argument.

Changed in version 0.5.7: Positional arguments radius & sigma have been converted to keyword arguments.

gravity

(basestring) The text placement gravity used when annotating with text. It’s a string from GRAVITY_TYPES list. It also can be set.

green_primary

(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).

New in version 0.5.2.

hald_clut(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)
Parameters:

New in version 0.5.0.

Changed in version 0.5.5: Added channel argument.

height

(numbers.Integral) The height of this image.

histogram

(HistogramDict) The mapping that represents the histogram. Keys are 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 quantize() the image before generating a HistogramDict.

with Image(filename=’hd_photo.jpg’) as img:
img.quantize(255, ‘RGB’, 0, False, False) hist = img.histogram

New in version 0.3.0.

hough_lines(width, height=None, threshold=40)

Identify lines within an image. Use 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.

Parameters:
Raises:

WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.5.

ift(phase, magnitude=True)

Alias for inverse_fourier_transform().

New in version 0.5.7.

implode(amount=0.0, method='undefined')

Creates a “imploding” effect by pulling pixels towards the center of the image.

Parameters:
  • amount (numbers.Real) – Normalized degree of effect between 0.0 & 1.0.
  • method (basestring) – Which interpolate method to apply to effected pixels. See PIXEL_INTERPOLATE_METHODS for a list of options. Only available with ImageMagick-7.

New in version 0.5.2.

import_pixels(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 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 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.

Parameters:
  • x (numbers.Integral) – horizontal starting coordinate of raster.
  • y (numbers.Integral) – vertical starting coordinate of raster.
  • width (numbers.Integral) – horizontal length of raster.
  • height (numbers.Integral) – vertical length of raster.
  • channel_map (basestring) – a string listing the channel data format for each pixel.
  • storage (basestring) – what data type each value should be calculated as.

New in version 0.5.0.

interlace_scheme

(basestring) The interlace used by the image. See INTERLACE_TYPES.

New in version 0.5.2.

interpolate_method

(basestring) The interpolation method of the image. See PIXEL_INTERPOLATE_METHODS.

New in version 0.5.2.

inverse_fourier_transform(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).

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')

Note

ImageMagick must have HDRI support to compute real & imaginary components (i.e. magnitude=False).

Parameters:
  • phase (BaseImage) – Second part (image) of the transform. Either the phase, or the imaginary part.
  • magnitude (bool) – If True, accept magnitude & phase input, else real & imaginary. Default True

New in version 0.5.5.

kurtosis

(numbers.Real) The kurtosis of the image.

Tip

If you want both kurtosis & skewness, it would be faster to call kurtosis_channel() directly.

New in version 0.5.3.

kurtosis_channel(channel='default_channels')

Calculates the kurtosis and skewness of the image.

from wand.image import Image

with Image(filename='input.jpg') as img:
    kurtosis, skewness = img.kurtosis_channel()
Parameters:channel (basestring) – Select which color channel to evaluate. See CHANNELS. Default 'default_channels'.
Returns:Tuple of kurtosis & skewness values.
Return type:tuple

New in version 0.5.3.

kuwahara(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.

Parameters:
  • radius (numbers.Real) – Size of the filter aperture.
  • sigma (numbers.Real) – Standard deviation of Gaussian filter.
Raises:

WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.5.

length_of_bytes

(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.

New in version 0.5.4.

level(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.

Parameters:
  • black (numbers.Real) – Black point, as a percentage of the system’s quantum range. Defaults to 0.
  • white (numbers.Real) – White point, as a percentage of the system’s quantum range. Defaults to 1.0.
  • gamma (numbers.Real) – Optional gamma adjustment. Values > 1.0 lighten the image’s midtones while values < 1.0 darken them.
  • channel (CHANNELS) – The channel type. Available values can be found in the CHANNELS mapping. If None, normalize all channels.

Note

Images may not be affected if the white value is equal, or less then, the black value.

New in version 0.4.1.

level_colors(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.

Parameters:
  • black_color (Color) – linearly map given color as “black” point.
  • white_color (Color) – linearly map given color as “white” point.
  • channel (basestring) – target a specific color-channel to levelize.
Raises:

WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.6.

levelize(black=0.0, white=None, gamma=1.0, channel=None)

Reverse of 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.

Parameters:
  • black (numbers.Real) – Black point, as a percentage of the system’s quantum range. Defaults to 0.
  • white (numbers.Real) – White point, as a percentage of the system’s quantum range. Defaults to 1.0.
  • gamma (numbers.Real) – Optional gamma adjustment. Values > 1.0 lighten the image’s midtones while values < 1.0 darken them.
  • channel (CHANNELS) – The channel type. Available values can be found in the CHANNELS mapping. If None, normalize all channels.
Raises:

WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.5.

levelize_colors(black_color, white_color, channel=None)

Reverse of 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.

Parameters:
  • black_color (Color) – tint map given color as “black” point.
  • white_color (Color) – tint map given color as “white” point.
  • channel (basestring) – target a specific color-channel to levelize.
Raises:

WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.6.

linear_stretch(black_point=0.0, white_point=1.0)

Enhance saturation intensity of an image.

Parameters:
  • black_point (numbers.Real) – Black point between 0.0 and 1.0. Default 0.0
  • white_point (numbers.Real) – White point between 0.0 and 1.0. Default 1.0

New in version 0.4.1.

liquid_rescale(width, height, delta_x=0, rigidity=0)

Rescales the image with seam carving, also known as image retargeting, content-aware resizing, or liquid rescaling.

Parameters:
  • width (numbers.Integral) – the width in the scaled image
  • height (numbers.Integral) – the height in the scaled image
  • delta_x (numbers.Real) – maximum seam transversal step. 0 means straight seams. default is 0
  • rigidity (numbers.Real) – introduce a bias for non-straight seams. default is 0
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 MissingDelegateError:

See also

Seam carving — Wikipedia
The article which explains what seam carving is on Wikipedia.
local_contrast(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.

Parameters:
  • radius (numbers.Real) – The size of the Gaussian operator. Default value is 10.0.
  • strength (numbers.Real) – Percentage of blur mask to apply. Values can be between 0.0 and 100 with a default of 12.5.

New in version 0.5.7.

loop

(numbers.Integral) Number of frame iterations. A value of 0 will loop forever.

magnify()

Quickly double an image in size. This is a convenience method. Use resize(), resample(), or sample() for more control.

New in version 0.5.5.

matte_color

(wand.color.Color) The color value of the matte channel. This can also be set.

New in version 0.4.1.

maxima

(numbers.Real) The maximum quantum value within the image. Value between 0.0 and quantum_range

Tip

If you want both maxima & minima, it would be faster to call range_channel() directly.

New in version 0.5.3.

mean

(numbers.Real) The mean of the image, and have a value between 0.0 and quantum_range

Tip

If you want both mean & standard_deviation, it would be faster to call mean_channel() directly.

New in version 0.5.3.

mean_channel(channel='default_channels')

Calculates the mean and standard deviation of the image.

from wand.image import Image

with Image(filename='input.jpg') as img:
    mean, stddev = img.mean_channel()
Parameters:channel (basestring) – Select which color channel to evaluate. See CHANNELS. Default 'default_channels'.
Returns:Tuple of mean & standard_deviation values. The mean value will be between 0.0 & quantum_range
Return type:tuple

New in version 0.5.3.

mean_shift(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.

Parameters:
  • width (numbers.Integral) – Size of the neighborhood window in pixels.
  • height (numbers.Integral) – Size of the neighborhood window in pixels.
  • color_distance (numbers.Real) – Include pixel values within this color distance.
Raises:

WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.5.

merge_layers(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 IMAGE_LAYER_METHOD that is acceptable to this operation. (See ImageMagick documentation for more details.)

Parameters:method (basestring) – the method of selecting the size of the initial canvas.

New in version 0.4.3.

minima

(numbers.Real) The minimum quantum value within the image. Value between 0.0 and quantum_range

Tip

If you want both maxima & minima, it would be faster to call range_channel() directly.

New in version 0.5.3.

mode(width, height=None)

Replace each pixel with the mathematical mode of the neighboring colors. This is an alias of the statistic() method.

Parameters:
  • width (numbers.Integral) – Number of neighboring pixels to include in mode.
  • height (numbers.Integral) – Optional height of neighboring pixels, defaults to the same value as width.

New in version 0.5.4.

modulate(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.

Parameters:
Raises:

ValueError – when one or more arguments are invalid

New in version 0.3.4.

morphology(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:

label:geometry

Where label is the kernel name defined in 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:

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)
Parameters:
  • method (basestring) – effect function to apply. See MORPHOLOGY_METHODS for a list of methods.
  • kernel (basestring) – shape to evaluate surrounding pixels. See KERNEL_INFO_TYPES for a list of built-in shapes.
  • iterations (numbers.Integral) – 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.
  • channel (basestring) – Optional color channel to target. See CHANNELS

New in version 0.5.0.

Changed in version 0.5.5: Added channel argument.

motion_blur(radius=0.0, sigma=0.0, angle=0.0, channel=None)

Apply a Gaussian blur along an angle direction. This simulates motion movement.

Parameters:
  • radius (numbers.Real) – Aperture size of the Gaussian operator.
  • sigma (numbers.Real) – Standard deviation of the Gaussian operator.
  • angle (numbers.Real) – Apply the effect along this angle.

New in version 0.5.4.

negate(grayscale=False, channel=None)

Negate the colors in the reference image.

Parameters:
  • grayscale (bool) – if set, only negate grayscale pixels in the image.
  • channel (basestring) – the channel type. available values can be found in the CHANNELS mapping. If None, negate all channels.

New in version 0.3.8.

noise(noise_type='uniform', attenuate=1.0, channel=None)

Adds noise to image.

Parameters:
  • noise_type (basestring) – type of noise to apply. See NOISE_TYPES.
  • attenuate (numbers.Real) – rate of distribution. Only available in ImageMagick-7. Default is 1.0.
  • channel (basestring) – Optionally target a color channel to apply noise to. See CHANNELS.

New in version 0.5.3.

Changed in version 0.5.5: Added optional channel argument.

normalize(channel=None)

Normalize color channels.

Parameters:channel (basestring) – the channel type. available values can be found in the CHANNELS mapping. If None, normalize all channels.
oil_paint(radius=0.0, sigma=0.0)

Simulates an oil painting by replace each pixel with most frequent surrounding color.

Parameters:
  • radius (numbers.Real) – The size of the surrounding neighbors.
  • sigma (numbers.Real) – The standard deviation used by the Gaussian operator. This is only available with ImageMagick-7.

New in version 0.5.4.

opaque_paint(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.

Parameters:
  • target (wand.color.Color) – The color to match.
  • fill (wand.color.Color) – The color to paint with.
  • fuzz (class:numbers.Real) – Normalized real number between 0.0 and quantum_range. Default is 0.0.
  • invert (bool) – Replace all colors that do not match target. Default is False.
  • channel (basestring) – Optional color channel to target. See CHANNELS

New in version 0.5.4.

Changed in version 0.5.5: Added channel paramater.

optimize_layers()

Attempts to crop each frame to the smallest image without altering the animation. For best results, call Image.coalesce() before manipulating any frames. For timing accuracy, any SingleImage.delay overwrites must be applied after optimizing layers.

Note

This will only affect GIF image formates.

New in version 0.5.0.

optimize_transparency()

Iterates over frames, and sets transparent values for each pixel unchanged by previous frame.

Note

This will only affect GIF image formates.

New in version 0.5.0.

options = None

(OptionDict) The mapping of internal option settings.

New in version 0.3.0.

Changed in version 0.3.4: Added 'jpeg:sampling-factor' option.

Changed in version 0.3.9: Added 'pdf:use-cropbox' option.

ordered_dither(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)
Parameters:
  • threshold_map (basestring) – Name of threshold dither to use, followed by optional arguments.
  • channel (basestring) – Optional argument to apply dither to specific color channel. See CHANNELS.

New in version 0.5.7.

orientation

(basestring) The image orientation. It’s a string from ORIENTATION_TYPES list. It also can be set.

New in version 0.3.0.

page

The dimensions and offset of this Wand’s page as a 4-tuple: (width, height, x, y).

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.

New in version 0.4.3.

page_height

(numbers.Integral) The height of the page for this wand.

New in version 0.4.3.

page_width

(numbers.Integral) The width of the page for this wand.

New in version 0.4.3.

page_x

(numbers.Integral) The X-offset of the page for this wand.

New in version 0.4.3.

page_y

(numbers.Integral) The Y-offset of the page for this wand.

New in version 0.4.3.

parse_meta_geometry(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

Parameters:geometry (basestring) – user string following ImageMagick’s geometry format.
Returns:Calculated width, height, offset-x, & offset-y.
Return type:tuple
Raises:ValueError – If given geometry can not be parsed.

New in version 0.5.6.

percent_escape(string_format)

Convenience method that expands ImageMagick’s Percent Escape characters into image attribute values.

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.

Parameters:string_format (basestring) – The precent escaped string to be translated.
Returns:String of expanded values.
Return type:basestring

New in version 0.5.6.

polaroid(angle=0.0, caption=None, font=None, method='undefined')

Creates a special effect simulating a Polaroid photo.

Parameters:
  • angle (numbers.Real) – applies a shadow effect along this angle.
  • caption (basestring) – Writes a message at the bottom of the photo’s border.
  • font (wand.font.Font) – Specify font style.
  • method (basestring) – Interpolation method. ImageMagick-7 only.

New in version 0.5.4.

polynomial(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:

\[output = 0.5 * image ^ {1.0}\]

This can work on multiple images in a sequence by calculating across each frame in the image stack.

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:

\[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.

Parameters:arguments (collections.abc.Sequence) – A list of real numbers where at least two numbers (weight & exponent) are need for each image in the sequence.
Raises:WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.5.

posterize(levels=None, dither='no')

Reduce color levels per channel.

Parameters:

New in version 0.5.0.

quantize(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.

Parameters:
  • number_colors (numbers.Integral) – The target number of colors to reduce the image.
  • colorspace_type (basestring) – Available value can be found in the COLORSPACE_TYPES. Defaults colorspace.
  • treedepth (numbers.Integral) – A value between 0 & 8 where 0 will allow ImageMagick to calculate the optimal depth with Log4(number_colors). Default value is 0.
  • dither (bool, or basestring) – 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 DITHER_METHODS. Default False.
  • measure_error (bool) – Include total quantization error of all pixels in an image & quantized value.

New in version 0.4.2.

Changed in version 0.5.9: Fixed ImageMagick-7 dither argument, and added keyword defaults.

quantum_range

(int) The maximum value of a color channel that is supported by the imagemagick library.

New in version 0.2.0.

random_threshold(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.

Parameters:
  • low (numbers.Real) – 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 & quantum_range.
  • high (numbers.Real) – 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 & quantum_range.
  • channel (basestring) – Optional argument to apply dither to specific color channel. See CHANNELS.

New in version 0.5.7.

range_channel(channel='default_channels')

Calculate the minimum and maximum of quantum values in image.

from wand.image import Image

with Image(filename='input.jpg') as img:
    minima, maxima = img.range_channel()
Parameters:channel (basestring) – Select which color channel to evaluate. See CHANNELS. Default 'default_channels'.
Returns:Tuple of minima & maxima values. Each value will be between 0.0 & quantum_range.
Return type:tuple

New in version 0.5.3.

range_threshold(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.

Parameters:
  • low_black (numbers.Real) – Define the minimum threshold value.
  • low_white (numbers.Real) – Define the minimum threshold value.
  • high_white (numbers.Real) – Define the maximum threshold value.
  • high_black (numbers.Real) – Define the maximum threshold value.
Raises:

WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.5.

read_mask(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 compare() method for limiting region of interest.

Warning

This method is only available with ImageMagick-7.

Parameters:clip_mask (BaseImage) – Image to reference as blend mask.

New in version 0.5.7.

red_primary

(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).

New in version 0.5.2.

remap(affinity=None, method='no')

Rebuild image palette with closest color from given affinity image.

Parameters:
  • affinity (BaseImage) – reference image.
  • method (basestring) – dither method. See DITHER_METHODS. Default is 'no' dither.

New in version 0.5.3.

rendering_intent

(basestring) PNG rendering intent. See RENDERING_INTENT_TYPES for valid options.

New in version 0.5.4.

resample(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.

Parameters:
  • x_res (numbers.Real) – the X resolution (density) in the scaled image. default is the original resolution.
  • y_res (numbers.Real) – the Y resolution (density) in the scaled image. default is the original resolution.
  • filter (basestring, numbers.Integral) – a filter type to use for resizing. choose one in FILTER_TYPES. default is 'undefined' which means IM will try to guess best one to use.
  • blur (numbers.Real) – the blur factor where > 1 is blurry, < 1 is sharp. default is 1

New in version 0.4.5.

reset_coords()

Reset the coordinate frame of the image so to the upper-left corner is (0, 0) again (crop and rotate operations change it).

New in version 0.2.0.

reset_sequence()

Abstract method prototype. See wand.image.Image.reset_sequence().

New in version 0.6.0.

resize(width=None, height=None, filter='undefined', blur=1)

Resizes the image.

Parameters:
  • width (numbers.Integral) – the width in the scaled image. default is the original width
  • height (numbers.Integral) – the height in the scaled image. default is the original height
  • filter (basestring, numbers.Integral) – a filter type to use for resizing. choose one in FILTER_TYPES. default is 'undefined' which means IM will try to guess best one to use
  • blur (numbers.Real) – the blur factor where > 1 is blurry, < 1 is sharp. default is 1

Changed in version 0.2.1: The default value of filter has changed from 'triangle' to 'undefined' instead.

Changed in version 0.1.8: The blur parameter changed to take numbers.Real instead of numbers.Rational.

New in version 0.1.1.

resolution

(tuple) Resolution of this image.

New in version 0.3.0.

Changed in version 0.5.8: Resolution returns a tuple of float values to match ImageMagick’s behavior.

rotate(degree, background=None, reset_coords=True)

Rotates the image right. It takes a background color for degree that isn’t a multiple of 90.

Parameters:
  • degree (numbers.Real) – a degree to rotate. multiples of 360 affect nothing
  • background (wand.color.Color) – an optional background color. default is transparent
  • reset_coords (bool) – 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.

New in version 0.2.0: The reset_coords parameter.

New in version 0.1.8.

rotational_blur(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.

Parameters:
  • angle (numbers.Real) – Degrees of rotation to blur with.
  • channel (basestring) – Optional channel to apply the effect against. See CHANNELS for a list of possible values.
Raises:

WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.4.

sample(width=None, height=None)

Resizes the image by sampling the pixels. It’s basically quicker than resize() except less quality as a trade-off.

Parameters:
  • width (numbers.Integral) – the width in the scaled image. default is the original width
  • height (numbers.Integral) – the height in the scaled image. default is the original height

New in version 0.3.4.

scale(columns=1, rows=1)

Increase image size by scaling each pixel value by given columns and rows.

Parameters:
  • columns (numbers.Integral) – The number of columns, in pixels, to scale the image horizontally.
  • rows (numbers.Integral) – The number of rows, in pixels, to scale the image vertically.

New in version 0.5.7.

scene

(numbers.Integral) The scene number of the current frame within an animated image.

New in version 0.5.4.

seed

(numbers.Integral) The seed for random number generator.

Warning

This property is only available with ImageMagick 7.0.8-41, or greater.

New in version 0.5.5.

selective_blur(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 quantum_range

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)
Parameters:
  • radius (numbers.Real) – Size of gaussian aperture.
  • sigma (numbers.Real) – Standard deviation of gaussian operator.
  • threshold (numbers.Real) – Only pixels within contrast threshold are effected. Value should be between 0.0 and quantum_range.
  • channel (basestring) – Optional color channel to target. See CHANNELS

New in version 0.5.3.

Changed in version 0.5.5: Added channel argument.

sepia_tone(threshold=0.8)

Creates a Sepia Tone special effect similar to a darkroom chemical toning.

Parameters:threshold (numbers.Real) – The extent of the toning. Value can be between 0 & quantum_range, or 0 & 1.0. Default value is 0.8 or “80%”.

New in version 0.5.7.

sequence = None

(collections.abc.Sequence) The list of SingleImages that the image contains.

New in version 0.3.0.

shade(gray=False, azimuth=0.0, elevation=0.0)

Creates a 3D effect by simulating a light from an elevated angle.

Parameters:
  • gray (bool) – Isolate the effect on pixel intensity. Default is False.
  • azimuth (numbers.Real) – Angle from x-axis.
  • elevation (numbers.Real) – Amount of pixels from the z-axis.

New in version 0.5.0.

shadow(alpha=0.0, sigma=0.0, x=0, y=0)

Generates an image shadow.

Parameters:

New in version 0.5.0.

sharpen(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.

Parameters:
  • radius (numbers.Real) – size of gaussian aperture.
  • sigma (numbers.Real) – Standard deviation of the gaussian filter.
  • channel (basestring) – Optional color channel to target. See CHANNELS.

New in version 0.5.0.

Changed in version 0.5.5: Added channel argument.

shave(columns=0, rows=0)

Remove pixels from the edges.

Parameters:

New in version 0.5.0.

shear(background='WHITE', x=0.0, y=0.0)

Shears the image to create a parallelogram, and fill the space created with a background color.

Parameters:

New in version 0.5.4.

sigmoidal_contrast(sharpen=True, strength=0.0, midpoint=0.0, channel=None)

Modifies the contrast of the image by applying non-linear sigmoidal algorithm.

with Image(filename='photo.jpg') as img:
    img.sigmoidal_contrast(sharpen=True,
                           strength=3,
                           midpoint=0.65 * img.quantum_range)
Parameters:
  • sharpen (bool) – Increase the contrast when True (default), else reduces contrast.
  • strength (numbers.Real) – How much to adjust the contrast. Where a value of 0.0 has no effect, 3.0 is typical, and 20.0 is extreme.
  • midpoint (numbers.Real) – Normalized value between 0.0 & quantum_range
  • channel (basestring) – Optional color channel to target. See CHANNELS.

New in version 0.5.4.

Changed in version 0.5.5: Added channel argument.

signature

(str) The SHA-256 message digest for the image pixel stream.

New in version 0.1.9.

similarity(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.

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.

Parameters:
  • reference (wand.image.Image) – Image to search for.
  • threshold (numbers.Real) – Stop scanning if reference similarity is below given threshold. Value can be between 0.0 and quantum_range. Default is 0.0.
  • metric (basestring) – specify which comparison algorithm to use. See COMPARE_METRICS for a list of values. Only used by ImageMagick-7.
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.

Return type:

tuple (dict, numbers.Real)

New in version 0.5.4: has been added.

size

(tuple) The pair of (width, height).

Note

When working with animations, or other layer-based image formats, the width & height properties are referencing the last frame read into the image stack. To get the size of the entire animated images, call Image.coalesce() method immediately after reading the image.

sketch(radius=0.0, sigma=0.0, angle=0.0)

Simulates a pencil sketch effect. For best results, radius value should be larger than sigma.

Parameters:

New in version 0.5.3.

skewness

(numbers.Real) The skewness of the image.

Tip

If you want both kurtosis & skewness, it would be faster to call kurtosis_channel() directly.

New in version 0.5.3.

smush(stacked=False, offset=0)

Appends all images together. Similar behavior to concat(), but with an optional offset between images.

Parameters:
  • stacked (bool) – If True, will join top-to-bottom. If False, join images from left-to-right (default).
  • offset (numbers.Integral) – Minimum space (in pixels) between each join.

New in version 0.5.3.

solarize(threshold=0.0, channel=None)

Simulates extreme overexposure.

Parameters:

New in version 0.5.3.

Changed in version 0.5.5: Added channel argument.

sparse_color(method, colors, channel_mask=7)

Interpolates color values between points on an image.

The colors argument should be a dict mapping 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_colors('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_colors('voronoi', colors, channel_mask=mask)
Parameters:
  • method (basestring) – Interpolate method. See SPARSE_COLOR_METHODS
  • colors (abc.Mapping { Color: (int, int) }) – A dictionary of Color keys mapped to an (x, y) coordinate tuple.
  • channel_mask (numbers.Integral) – Isolate specific color channels to apply interpolation. Default to RGB channels.

New in version 0.5.3.

splice(width=None, height=None, x=None, y=None)

Partitions image by splicing a width x height rectangle at (x, y) offset coordinate. The space inserted will be replaced by the background_color value.

Parameters:

New in version 0.5.3.

spread(radius=0.0, method='undefined')

Randomly displace pixels within a defined radius.

Parameters:
  • radius (numbers.Real) – Distance a pixel can be displaced from source. Default value is 0.0, which will allow ImageMagick to auto select a radius.
  • method – Interpolation method. Only available with ImageMagick-7. See PIXEL_INTERPOLATE_METHODS.

New in version 0.5.3.

Changed in version 0.5.7: Added default value to radius.

standard_deviation

(numbers.Real) The standard deviation of the image.

Tip

If you want both mean & standard_deviation, it would be faster to call mean_channel() directly.

New in version 0.5.3.

statistic(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.

Parameters:
  • stat (basestring) – The type of statistic to calculate. See STATISTIC_TYPES.
  • width (numbers.Integral) – The size of neighboring pixels on the X-axis.
  • height (numbers.Integral) – The size of neighboring pixels on the Y-axis.
  • channel (basestring) – Optional color channel to target. See CHANNELS

New in version 0.5.3.

Changed in version 0.5.5: Added optional channel argument.

stegano(watermark, offset=0)

Hide a digital watermark of an image within the image.

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')
Parameters:

New in version 0.5.4.

strip()

Strips an image of all profiles and comments.

New in version 0.2.0.

swirl(degree=0.0, method='undefined')

Swirls pixels around the center of the image. The larger the degree the more pixels will be effected.

Parameters:
  • degree (numbers.Real) – Defines the amount of pixels to be effected. Value between -360.0 and 360.0.
  • method (basestring) – Controls interpolation of the effected pixels. Only available for ImageMagick-7. See PIXEL_INTERPOLATE_METHODS.

New in version 0.5.7.

texture(tile)

Repeat tile-image across the width & height of the image.

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')
Parameters:tile (Image) – image to repeat across canvas.

New in version 0.5.4.

threshold(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.

Parameters:
  • threshold (numbers.Real) – threshold as a factor of quantum. A normalized float between 0.0 and 1.0.
  • channel (basestring) – the channel type. available values can be found in the CHANNELS mapping. If None, threshold all channels.

New in version 0.3.10.

thumbnail(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.

Parameters:
  • width (numbers.Integral) – the width in the scaled image. default is the original width
  • height (numbers.Integral) – the height in the scaled image. default is the original height

New in version 0.5.4.

ticks_per_second

(numbers.Integral) Internal clock for animated images. .. versionadded:: 0.5.4

tint(color=None, alpha=None)

Applies a color vector to each pixel in the image.

Parameters:
  • color (Color) – Color to calculate midtone.
  • alpha (Color) – Determine how to blend.

New in version 0.5.3.

transform(crop='', resize='')

Transforms the image using 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%xscale-y%
Height and width individually scaled by specified percentages. Only one % symbol is needed.
width
Width given, height automagically selected to preserve aspect ratio.
xheight
Height given, width automagically selected to preserve aspect ratio.
widthxheight
Maximum values of width and height given; aspect ratio preserved.
widthxheight!
Width and height emphatically given; original aspect ratio ignored.
widthxheight>
Shrinks images with dimension(s) larger than the corresponding width and/or height dimension(s).
widthxheight<
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.

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.

Parameters:
  • crop (basestring) – A geometry string defining a subregion of the image to crop to
  • resize (basestring) – A geometry string defining the final size of the image

See also

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.

New in version 0.2.2.

Changed in version 0.5.0: Will call crop() followed by resize() in the event that MagickTransformImage() is not available.

Deprecated since version 0.6.0: Use crop() and resize() instead.

transform_colorspace(colorspace_type)

Transform image’s colorspace.

Parameters:colorspace_type (basestring) – colorspace_type. available value can be found in the COLORSPACE_TYPES

New in version 0.4.2.

transparent_color(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.

Parameters:
  • color (wand.color.Color) – The color that should be made transparent on the image, color object
  • alpha (numbers.Real) – the level of transparency: 1.0 is fully opaque and 0.0 is fully transparent.
  • fuzz (numbers.Integral) – 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.
  • invert (bool) – Boolean to tell to paint the inverse selection.

New in version 0.3.0.

transparentize(transparency)

Makes the image transparent by subtracting some percentage of the black color channel. The transparency parameter specifies the percentage.

Parameters:transparency (numbers.Real) – the percentage fade that should be performed on the image, from 0.0 to 1.0

New in version 0.2.0.

transpose()

Creates a vertical mirror image by reflecting the pixels around the central x-axis while rotating them 90-degrees.

New in version 0.4.1.

transverse()

Creates a horizontal mirror image by reflecting the pixels around the central y-axis while rotating them 270-degrees.

New in version 0.4.1.

trim(color=None, fuzz=0.0, reset_coords=False)

Remove solid border from image. Uses top left pixel as a guide by default, or you can also specify the color to remove.

Parameters:
  • color (Color) – the border color to remove. if it’s omitted top left pixel is used by default
  • fuzz (numbers.Real) – Defines how much tolerance is acceptable to consider two colors as the same. Value can be between 0.0, and quantum_range.
  • reset_coords (bool) – Reset coordinates after triming image. Default False.

New in version 0.2.1.

Changed in version 0.3.0: Optional color and fuzz parameters.

Changed in version 0.5.2: The color parameter may except color-compliant strings.

Changed in version 0.6.0: Optional reset_coords parameter added.

type

(basestring) The image type.

Defines image type as in IMAGE_TYPES enumeration.

It may raise ValueError when the type is unknown.

New in version 0.2.2.

unique_colors()

Discards all duplicate pixels, and rebuilds the image as a single row.

New in version 0.5.0.

units

(basestring) The resolution units of this image.

unsharp_mask(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 unsharp_mask() selects a suitable radius for you.

Parameters:
  • radius (numbers.Real) – the radius of the Gaussian, in pixels, not counting the center pixel
  • sigma (numbers.Real) – the standard deviation of the Gaussian, in pixels
  • amount (numbers.Real) – the percentage of the difference between the original and the blur image that is added back into the original
  • threshold (numbers.Real) – the threshold in pixels needed to apply the difference amount.
  • channel (basestring) – Optional color channel to target. See CHANNELS

New in version 0.3.4.

Changed in version 0.5.5: Added optional channel argument.

Changed in version 0.5.7: Added default values to match CLI behavior.

vignette(radius=0.0, sigma=0.0, x=0, y=0)

Creates a soft vignette style effect on the image.

Parameters:
  • radius (numbers.Real) – the radius of the Gaussian blur effect.
  • sigma (numbers.Real) – the standard deviation of the Gaussian effect.
  • x (numbers.Integral) – Number of pixels to offset inward from the top & bottom of the image before drawing effect.
  • y (numbers.Integral) – Number of pixels to offset inward from the left & right of the image before drawing effect.

New in version 0.5.2.

virtual_pixel

(basestring) The virtual pixel of image. This can also be set with a value from VIRTUAL_PIXEL_METHOD … versionadded:: 0.4.1

wand

Internal pointer to the MagickWand instance. It may raise ClosedImageError when the instance has destroyed already.

watermark(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.

Parameters:
  • image (wand.image.Image) – the image placed over the current image
  • transparency (numbers.Real) – the percentage fade that should be performed on the image, from 0.0 to 1.0
  • left (numbers.Integral) – the x-coordinate where image will be placed
  • top (numbers.Integral) – the y-coordinate where image will be placed

New in version 0.2.0.

wave(amplitude=0.0, wave_length=0.0, method='undefined')

Creates a ripple effect within the image.

Parameters:

New in version 0.5.2.

wavelet_denoise(threshold=0.0, softness=0.0)

Removes noise by applying a wavelet transform.

Warning

This class method is only available with ImageMagick 7.0.8-41, or greater.

Parameters:
Raises:

WandLibraryVersionError – If system’s version of ImageMagick does not support this method.

New in version 0.5.5.

white_point

(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).

New in version 0.5.2.

white_threshold(threshold)

Forces all pixels above a given color as white. Leaves pixels below threshold unaltered.

Parameters:threshold (Color) – Color to be referenced as a threshold.

New in version 0.5.2.

width

(numbers.Integral) The width of this image.

write_mask(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.

Parameters:clip_mask (BaseImage) – Image to reference as blend mask.

New in version 0.5.7.

class wand.image.ChannelDepthDict(image)

The mapping table of channels to their depth.

Parameters:image (Image) – an image instance

Note

You don’t have to use this by yourself. Use Image.channel_depths property instead.

New in version 0.3.0.

class wand.image.ChannelImageDict(image)

The mapping table of separated images of the particular channel from the image.

Parameters:image (Image) – an image instance

Note

You don’t have to use this by yourself. Use Image.channel_images property instead.

New in version 0.3.0.

exception wand.image.ClosedImageError

An error that rises when some code tries access to an already closed image.

class wand.image.HistogramDict(image)

Specialized mapping object to represent color histogram. Keys are colors, and values are the number of pixels.

Parameters:image (BaseImage) – the image to get its histogram

New in version 0.3.0.

class wand.image.Image(image=None, blob=None, file=None, filename=None, format=None, width=None, height=None, depth=None, background=None, resolution=None, pseudo=None, colorspace=None, units=None)

An image object.

Parameters:
  • image (Image) – makes an exact copy of the image
  • blob (bytes) – opens an image of the blob byte array
  • file (file object) – opens an image of the file object
  • filename (basestring) – opens an image of the filename string. Additional Read Modifiers are supported.
  • format (basestring) – forces filename to buffer. format to help ImageMagick detect the file format. Used only in blob or file cases
  • width (numbers.Integral) – the width of new blank image or an image loaded from raw data.
  • height (numbers.Integral) – the height of new blank image or an image loaded from raw data.
  • depth (numbers.Integral) – the depth used when loading raw data.
  • background (wand.color.Color) – an optional background color. default is transparent
  • resolution (collections.abc.Sequence, numbers.Integral) – set a resolution value (dpi), useful for vectorial formats (like pdf)
  • colorspace (basestring,) – sets the stack’s default colorspace value before reading any images. See COLORSPACE_TYPES.
  • units (basestring) – paired with resolution for defining an image’s pixel density. See UNIT_TYPES.

New in version 0.1.5: The file parameter.

New in version 0.1.1: The blob parameter.

New in version 0.2.1: The format parameter.

New in version 0.2.2: The width, height, background parameters.

New in version 0.3.0: The resolution parameter.

New in version 0.4.2: The depth parameter.

Changed in version 0.4.2: The depth, width and height parameters can be used with the filename, file and blob parameters to load raw pixel data.

New in version 0.5.0: The pseudo parameter.

Changed in version 0.5.4: Read constructor no longer sets “transparent” background by default. Use the background paramater to specify canvas color when reading in image.

Changed in version 0.5.7: Added the colorspace & units parameter.

[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:Image

New in version 0.1.2.

animation

(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 False even if image/ico consits of two or more images of the same size.

For example, it’s False for image/jpeg, image/gif, image/ico.

If image/gif has two or more frames, it’s True. If image/gif has only one frame, it’s False.

New in version 0.3.0.

Changed in version 0.3.8: Became to accept image/x-gif as well.

artifacts = None

(ArtifactTree) A dict mapping to image artifacts. Similar to metadata, but used to alter behavior of various internal operations.

New in version 0.5.0.

blank(width, height, background=None)

Creates blank image.

Parameters:
Returns:

blank image

Return type:

Image

New in version 0.3.0.

channel_depths = None

(ChannelDepthDict) The mapping of channels to their depth. Read only.

New in version 0.3.0.

channel_images = None

(ChannelImageDict) The mapping of separated channels from the image.

with image.channel_images['red'] as red_image:
    display(red_image)
clear()

Clears resources associated with the image, leaving the image blank, and ready to be used with new image.

New in version 0.3.0.

close()

Closes the image explicitly. If you use the image object in with statement, it was called implicitly so don’t have to call it.

Note

It has the same functionality of destroy() method.

compare_layers(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.

Parameters:method (basestring) – Can be 'compareany', 'compareclear', or 'compareoverlay'
Returns:new image stack.
Return type:Image

New in version 0.5.0.

convert(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')
Parameters:format (basestring) – image format to convert to
Returns:a converted image
Return type:Image
Raises:ValueError – when the given format is unsupported

New in version 0.1.6.

classmethod from_array(array, channel_map=None, storage=None)

Create an image instance from a numpy array, or any other datatype that implements __array_interface__ protocol.

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", "I", or "CMYK" based on array shape. If storage is omitted, this method will reference the array’s typestr value, and raise a 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 Image can also be exported to numpy arrays:

with Image(filename='rose:') as img:
    matrix = numpy.array(img)
Parameters:
  • array (numpy.array) – Numpy array of pixel values.
  • channel_map (basestring) – Color channel layout.
  • storage (basestring) – Datatype per pixel part.
Returns:

New instance of an image.

Return type:

Image

New in version 0.5.3.

Changed in version 0.6.0: Input array now expects the shape property to be defined as `( 'height', 'width', 'channels' )`.

make_blob(format=None)

Makes the binary string of the image.

Parameters:format (basestring) – the image format to write e.g. 'png', 'jpeg'. it is omittable
Returns:a blob (bytes) string
Return type:bytes
Raises:ValueError – when format is invalid

Changed in version 0.1.6: Removed a side effect that changes the image format silently.

New in version 0.1.5: The format parameter became optional.

New in version 0.1.1.

metadata = None

(Metadata) The metadata mapping of the image. Read only.

New in version 0.3.0.

mimetype

(basestring) The MIME type of the image e.g. 'image/jpeg', 'image/png'.

New in version 0.1.7.

classmethod ping(file=None, filename=None, blob=None, resolution=None, format=None)

Ping image header into Image() object, but without any pixel data. This is useful for inspecting image meta-data without decoding the whole image.

Parameters:
  • blob (bytes) – reads an image from the blob byte array
  • file (file object) – reads an image from the file object
  • filename (basestring) – reads an image from the filename string
  • resolution (collections.abc.Sequence, numbers.Integral) – set a resolution value (DPI), useful for vector formats (like PDF)
  • format (basestring) – suggest image file format when reading from a blob, or file property.

New in version 0.5.6.

profiles = None

(ProfileDict) The mapping of image profiles.

New in version 0.5.1.

pseudo(width, height, pseudo='xc:')

Creates a new image from ImageMagick’s internal protocol coders.

Parameters:
  • width (numbers.Integral) – Total columns of the new image.
  • height (numbers.Integral) – Total rows of the new image.
  • pseudo (basestring) – The protocol & arguments for the pseudo image.

New in version 0.5.0.

read(file=None, filename=None, blob=None, resolution=None, units=None)

Read new image into Image() object.

Parameters:
  • blob (bytes) – reads an image from the blob byte array
  • file (file object) – reads an image from the file object
  • filename (basestring) – reads an image from the filename string. Additional Read Modifiers are supported.
  • resolution (collections.abc.Sequence, numbers.Integral) – set a resolution value (DPI), useful for vectorial formats (like PDF)
  • units (basestring) – used with resolution, can either be 'pixelperinch', or 'pixelpercentimeter'.

New in version 0.3.0.

Changed in version 0.5.7: Added units parameter.

reset_sequence()

Remove any previously allocated SingleImage instances in sequence attribute.

New in version 0.6.0.

save(file=None, filename=None, adjoin=True)

Saves the image into the file or filename. It takes only one argument at a time.

Parameters:
  • file (file object) – a file object to write to
  • filename (basestring) – a filename string to write to
  • adjoin (bool) – write all images to a single multi-image file. Only available if file format supports frames, layers, & etc.

New in version 0.1.1.

Changed in version 0.1.5: The file parameter was added.

Changed in version 6.0.0: The adjoin parameter was added.

classmethod stereogram(left, right)

Create a new stereogram image from two existing images.

Parameters:

New in version 0.5.4.

class wand.image.ImageProperty(image)

The mixin class to maintain a weak reference to the parent Image object.

New in version 0.3.0.

image

(Image) The parent image.

It ensures that the parent Image, which is held in a weak reference, still exists. Returns the dereferenced Image if it does exist, or raises a ClosedImageError otherwise.

Exc:ClosedImageError when the parent Image has been destroyed
class wand.image.Iterator(image=None, iterator=None)

Row iterator for Image. It shouldn’t be instantiated directly; instead, it can be acquired through 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 collections.abc.Sequence which consists of one or more wand.color.Color values.

Parameters:image (Image) – the image to get an iterator

New in version 0.1.3.

clone()

Clones the same iterator.

next(x=None)

Return the next item from the iterator. When exhausted, raise StopIteration

class wand.image.Metadata(image)

Class that implements dict-like read-only access to image metadata like EXIF or IPTC headers. Most WRITE encoders will ignore properties assigned here.

Parameters:image (Image) – an image instance

Note

You don’t have to use this by yourself. Use Image.metadata property instead.

New in version 0.3.0.

class wand.image.OptionDict(image)

Free-form mutable mapping of global internal settings.

New in version 0.3.0.

Changed in version 0.5.0: Remove key check to OPTIONS. Image properties are specific to vendor, and this library should not attempt to manage the 100+ options in a whitelist.

wand.image.manipulative(function)

Mark the operation manipulating itself instead of returning new one.

class wand.image.ArtifactTree(image)

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')
Parameters:image (Image) – an image instance

Note

You don’t have to use this by yourself. Use Image.artifacts property instead.

New in version 0.5.0.

class wand.image.ProfileDict(image)

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']

See also

Embedded Image Profiles for a list of supported profiles.

New in version 0.5.1.

class wand.image.ConnectedComponentObject(cc_object=None)

Generic Python wrapper to translate CCObjectInfo structure into a class describing objects found within an image. This class is generated by Image.connected_components() method.

New in version 0.5.5.

area = None

(numbers.Real) Quantity of pixels that make-up the objects shape.

center_x = None

(numbers.Real) X offset of objects centroid.

center_y = None

(numbers.Real) Y offset of objects centroid.

centroid

(tuple (center_x, center_y)) Center of object.

clone_from_cc_object_info(cc_object)

Copy data from CCObjectInfo.

height = None

(numbers.Integral) Height of objects minimum bounding rectangle.

left = None

(numbers.Integral) X offset of objects minimum bounding rectangle.

mean_color = None

(Color) The average color of the shape.

offset

(tuple (left, top)) Position of objects minimum bounding rectangle.

size

(tuple (width, height)) Minimum bounding rectangle.

top = None

(numbers.Integral) Y offset of objects minimum bounding rectangle.

width = None

(numbers.Integral) Width of objects minimum bounding rectangle.