# `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'`

  Added in version 0.5.5.

class wand.image.ArtifactTree(image)

  Splay tree to map image artifacts. Values defined here are intended to be used elsewhere, 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.

  Added in version 0.5.0.

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

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

    See:

      Example of Adaptive Blur.

    Parameters:

      - radius (`numbers.Real`) – size of gaussian aperture.

      - sigma (`numbers.Real`) – Standard deviation of the gaussian filter.

      - channel (`str`) – Apply the blur effect on a specific channel. See `CHANNELS`.

    Added 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:

      - columns (`numbers.Integral`) – width of resized image.

      - rows (`numbers.Integral`) – height of resized image.

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

    See:

      Example of Adaptive Sharpen.

    Parameters:

      - radius (`numbers.Real`) – size of gaussian aperture.

      - sigma (`numbers.Real`) – Standard deviation of the gaussian filter.

      - channel (`str`) – Apply the sharpen effect on a specific channel. See `CHANNELS`.

    Added 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:

      - width (`numbers.Integral`) – size of neighboring pixels on the X-axis.

      - height (`numbers.Integral`) – size of neighboring pixels on the Y-axis.

      - offset (`numbers.Real`) – normalized number between 0.0 and `quantum_range`. Forces the pixels to black if values are below `offset`.

    Added in version 0.5.3.

  affine(sx=1, rx=0, ry=0, sy=1, tx=0, ty=0)

    Transforms an image by applying an affine matrix.

                                          | sx  rx  0 |
        | x', y', 1 |  =  | x, y, 1 |  *  | ry  sy  0 |
                                          | tx  ty  1 |

    Where `sx` & `sy` control the scale / shearing, `rx` & `ry` control the rotational values, and the `tx` & `ty` control the translations.

    Set the `virtual_pixel` attribute before invoking `affine()` method.

        from wand.image import Image

        with Image(filename='wizard:') as img:
            img.virtual_pixel = 'mirror'
            img.affine(sx=0.9, ry=1.1)
            img.save(filename='output.png')

    Parameters:

      - sx (`numbers.Real`) – Horizontal scale/shear. Default value 1.0.

      - rx (`numbers.Real`) – Horizontal rotation. Default value 0.0.

      - ry (`numbers.Real`) – Vertical rotation. Default value 0.0.

      - sy (`numbers.Real`) – Vertical scale/shear. Default value 1.0.

      - tx (`numbers.Real`) – Horizontal translation. Default value 0.0.

      - ty (`numbers.Real`) – Vertical translation. Default value 0.0.

    Added in version 0.7.0.

  property alpha_channel

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

    Behavior of setting `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.

    Note

    The `alpha_channel` attribute will always return `True` if alpha channel is enabled, and `False` otherwise. Setting this property with a string value from `ALPHA_CHANNEL_TYPES` will resolve to a `bool` after applying channel operations listed above.

    With ImageMagick-6, values `'on'` & `'off'` are aliased to `'activate'` & `'deactivate'`. However in ImageMagick-7, both `'on'` & `'off'` have their own behavior.

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

  property 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 consists 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`.

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

    Added in version 0.5.6.

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

    Added in version 0.5.4.

  auto_level()

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

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

    Added 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 (`str`) – Which threshold method to apply. See `AUTO_THRESHOLD_METHODS`. Defaults to `'kapur'`.

    Raises:

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

    Added in version 0.5.5.

  property background_color

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

    Added in version 0.1.9.

    Changed in version 0.6.7: Allow property to be set before image read.

  bilateral_blur(width=1.0, height=None, intensity=None, spatial=None)

    Noise-reducing Gaussian distribution filter. Preserves edges by replacing pixel intensity with weighted averages of neighboring pixels. Parameters `width` & `height` define the area-size around each pixel to include in the neighboring sample.

    Warning

    This method is only available with ImageMagick version 7.1.1 or greater.

    Parameters:

      - width (`numbers.Real`) – The neighboring pixel area width.

      - height (`numbers.Real`) – The neighboring pixel area height. Default the given `width` value.

      - intensity (`numbers.Real`) – Influence the distance between colors values. Default 75% of the neighboring pixel area.

      - spatial (`numbers.Real`) – Influence the coordinate distance weights. Default 25% of the neighboring pixel area.

    Added in version 0.7.0.

  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.

    Added in version 0.5.3.

  property 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)`.

    Added in version 0.5.2.

  blue_shift(factor=1.5)

    Mutes colors of the image by shifting blue values.

    See:

      Example of Blue Shift

    Parameters:

      factor (`numbers.Real`) – Amount to adjust values.

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

    See:

      Example of Blur.

    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 (`str`) – Optional color channel to apply blur. See `CHANNELS`.

    Added in version 0.4.5.

    Changed in version 0.5.5: Added optional `channel` argument.

    Changed in version 0.5.7: Positional arguments `radius` & `sigma` 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 (`str`) – Use composite operator when applying frame. Only used if called with ImageMagick 7+.

    Added in version 0.3.0.

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

  property border_color

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

    Added in version 0.5.4.

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

    Converts `brightness` & `contrast` parameters 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`.

    Added in version 0.5.4.

    Changed in version 0.5.5: Optional `channel` argument added.

  c_clear_exception = <_FuncPtr object>

    (`ctypes.CFUNCTYPE`) The `ctypes` function that clears an exception of the `resource`.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  c_destroy_resource = <_FuncPtr object>

    (`ctypes.CFUNCTYPE`) The `ctypes` function that destroys the `resource`.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  c_get_exception = <_FuncPtr object>

    (`ctypes.CFUNCTYPE`) The `ctypes` function that gets an exception from the `resource`.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  c_is_resource = <_FuncPtr object>

    (`ctypes.CFUNCTYPE`) The `ctypes` predicate function that returns whether the given pointer (that contains a resource data usually) is a valid resource.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  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.

    Added 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:

      - text (`str`) – text to write

      - left (`numbers.Integral`) – x offset in pixels

      - top (`numbers.Integral`) – y offset in pixels

      - width (`numbers.Integral`) – width of caption in pixels. default is `width` of the image

      - height (`numbers.Integral`) – height of caption in pixels. default is `height` of the image

      - font (`wand.font.Font`) – font to use. default is `font` of the image

      - gravity (`str`) – text placement gravity. uses the current `gravity` setting of the image by default

    Added in version 0.3.0.

  cdl(ccc)

    Alias for `color_decision_list()`.

    Added in version 0.5.7.

  charcoal(radius, sigma)

    Transform an image into a simulated charcoal drawing.

    See:

      Example of Charcoal.

    Parameters:

      - radius (`numbers.Real`) – The size of the Gaussian operator.

      - sigma (`numbers.Real`) – The standard deviation of the Gaussian.

    Added in version 0.5.3.

  chop(width=None, height=None, x=None, y=None, gravity=None)

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

    Parameters:

      - width (`numbers.Integral`) – Size of region.

      - height (`numbers.Integral`) – Size of region.

      - x (`numbers.Integral`) – Offset on the X-axis.

      - y (`numbers.Integral`) – Offset on the Y-axis.

      - gravity (`str`) – Helper to auto-calculate offset. See `GRAVITY_TYPES`.

    Added in version 0.5.5.

    Changed in version 0.6.8: Added `gravity` argument.

    Changed in version 0.6.12: Allow zero values for `width` & `height` arguments.

    Changed in version 0.7.0: Allow `x` & `y` offset to apply relative to `gravity`.

  clahe(width, height, number_bins, clip_limit)

    Contrast limited adaptive histogram equalization.

    Warning

    The CLAHE method is only available with ImageMagick-7.

    Parameters:

      - width (`numbers.Integral`) – Tile division width.

      - height (`numbers.Integral`) – Tile division height.

      - number_bins (`numbers.Real`) – Histogram bins.

      - clip_limit (`numbers.Real`) – contrast limit.

    Raises:

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

    Added 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 (`str`) – Optional color channel.

    Added 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`

    Added 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:

      - image (`wand.image.BaseImage`) – Color Look Up Table image.

      - method (`str`) – Pixel Interpolate method. Only available with ImageMagick-7. See `PIXEL_INTERPOLATE_METHODS`

      - channel (`str`) – Optional color channel to target. See `CHANNELS`

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

    Added 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 (`str`) – A XML string of the CCC contents.

    Added 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:

      - index (`numbers.Integral`) – The color position of the image palette.

      - color (`wand.color.Color`) – Optional color to _set_ at the given index.

    Returns:

      Color at index.

    Return type:

      `wand.color.Color`

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

    See color-matrix for examples.

    See:

      Example of Color Matrix.

    Parameters:

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

    Added in version 0.5.3.

  color_threshold(start=None, stop=None)

    Forces all pixels in color range to white, and all other pixels to black.

    Note

    This method is only works with ImageMagick-7.0.10, or later.

    Parameters:

      - start (`wand.color.Color`) – Color to begin color range.

      - stop (`wand.color.Color`) – Color to end color range.

    Added in version 0.6.4.

  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.

    See:

      Example of Colorize.

    Parameters:

      - color (`wand.color.Color`) – Color to paint image with.

      - alpha (`wand.color.Color`) – Defines how to blend color.

    Added in version 0.5.3.

  property colors

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

    Added in version 0.5.3.

  property colorspace

    (`str`) The image colorspace.

    Defines image colorspace as in `COLORSPACE_TYPES` enumeration.

    It may raise `ValueError` when the colorspace is unknown.

    Added 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 (`str`) – Determines the colorchannel ordering of the sequence. Only used for ImageMagick-6. See `CHANNELS`.

      - colorspace (`str`) – Determines the colorchannel ordering of the sequence. Only used for ImageMagick-7. See `COLORSPACE_TYPES`.

    Added in version 0.5.9.

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

    Compares an image with another, and returns a reconstructed image & computed distortion. The reconstructed image will show the differences colored with `highlight`, and similarities with `lowlight`.

    If you need the computed distortion between to images without a image being reconstructed, use `get_image_distortion()` method.

    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 (`str`) – The metric type to use for comparing. See `COMPARE_METRICS`

      - highlight (`Color` or `str`) – Set the color of the delta pixels in the resulting difference image.

      - lowlight (`Color` or `str`) – 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.Real`)

    Return type:

      `tuple` ( `Image`, `numbers.Real` )

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

    See also

    `forward_fourier_transform()` & `inverse_fourier_transform()`

        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 (`str`) – Define which mathematic operator to perform. See `COMPLEX_OPERATORS`.

      - snr (`str`) – Optional `SNR` parameter for `'divide'` operator.

    Raises:

      WandLibraryVersionError – If ImageMagick library does not support this function.

    Added in version 0.5.5.

  property compose

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

    Added 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 (`str`) – 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 (`str`) – 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: `str`

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

    Changed in version 0.7.0: Allow `x` & `y` offset to apply relative to `gravity`.

  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 (`str`) – 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 (`str`) – 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: `str`

    Raises:

      ValueError – when the given `channel` or `operator` is invalid

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

    Changed in version 0.7.0: Allow `x` & `y` offset to apply relative to `gravity`.

  property compression

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

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

  property compression_quality

    (`numbers.Integral`) Compression quality of this image.

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

    Added in version 0.5.0.

  connected_components(**kwargs)

    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:

      - angle_threshold (`str`) – Optional argument that merges any region with an equivalent ellipse smaller than a given value. Requires ImageMagick-7.0.9-24, or greater.

      - area_threshold (`str`) – Optional argument to merge objects under an area size.

      - background_id (`str`) – Optional argument to identify which object should be the background. Requires ImageMagick-7.0.9-24, or greater.

      - circularity_threshold (`str`) – Optional argument that merges any region smaller than value defined as: `4*pi*area/perimeter^2`. Requires ImageMagick-7.0.9-24, or greater.

      - 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. Default value of `4`.

      - diameter_threshold (`str`) – Optional argument to merge any region under a given value. A region is defined as: `sqr(4*area/pi)`. Requires ImageMagick-7.0.9-24.

      - eccentricity_threshold – Optional argument to merge any region with ellipse eccentricity under a given value. Requires ImageMagick-7.0.9-24, or greater.

      - keep (`str`) – Comma separated list of object IDs to isolate, the reset are converted to transparent.

      - keep_colors (`str`) – Semicolon separated list of objects to keep by their color value. Requires ImageMagick-7.0.9-24, or greater.

      - keep_top (`str`) – Keeps only the top number of objects by area. Requires ImageMagick-7.0.9-24, or greater.

      - major_axis_threshold (`str`) – Optional argument to merge any ellipse with a major axis smaller then given value. Requires ImageMagick-7.0.9-24, or greater.

      - mean_color (`bool`) – Optional argument. Replace object color with mean color of the source image.

      - minor_axis_threshold (`str`) – Optional argument to merge any ellipse with a minor axis smaller then given value. Requires ImageMagick-7.0.9-24, or greater.

      - perimeter_threshold – Optional argument to merge any region with a perimeter smaller than the given value. Requires ImageMagick-7.0.9-24, or greater.

      - remove (`str`) – Comma separated list of object IDs to ignore, and convert to transparent.

      - remove_colors (`str`) – Semicolon separated list of objects to remove by there color. Requires ImageMagick-7.0.9-24, or greater.

    Returns:

      A list of `ConnectedComponentObject`.

    Return type:

      `list` [`ConnectedComponentObject`]

    Raises:

      WandLibraryVersionError – If ImageMagick library does not support this method.

    Added in version 0.5.5.

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

    Changed in version 0.6.4: Added `angle_threshold`, `circularity_threshold`, `diameter_threshold`, `eccentricity_threshold`, `keep_colors`, `major_axis_threshold`, `minor_axis_threshold`, `perimeter_threshold`, and `remove_colors` optional arguments.

  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.

    Added 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`

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

  convex_hull(background=None)

    Find the smallest convex polygon, and returns a list of points.

    Note

    Requires ImageMagick-7.0.10 or greater.

    You can pass the list of points directly to `Drawing.polygon()` method to draw the convex hull shape on the image.

        from wand.image import Image
        from wand.drawing import Drawing

        with Image(filename='kdf_black.png') as img:
          points = img.convex_hull()
          with Drawing() as ctx:
            ctx.fill_color = 'transparent'
            ctx.stroke_color = 'red'
            ctx.polygon(points=points)
            ctx(img)
        img.save(filename='kdf_black_convex_hull.png')

    Parameters:

      background (`str` or `Color`) – Define which color value to evaluate as the background.

    Returns:

      list of points

    Return type:

      `list` [ `tuple` ( `float`, `float` ) ]

    Added in version 0.6.4.

  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.

    Added in version 0.1.7.

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

    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.7.0: Allow `x` & `y` offset to apply relative to `gravity`.

  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.

    Added in version 0.5.3.

  decipher(passphrase)

    Decrypt ciphered pixels into original values.

    Note

    `ImageError` will be thrown if the system’s ImageMagick library was compiled without cipher support.

    Parameters:

      passphrase (`str`) – the secret passphrase to decrypt with.

    Added in version 0.6.3.

  deconstruct()

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

    Added in version 0.5.0.

  property delay

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

    Added in version 0.5.9.

  property depth

    (`numbers.Integral`) The depth of this image.

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

    Added in version 0.5.0.

  despeckle()

    Applies filter to reduce noise in image.

    See:

      Example of Despeckle.

    Added in version 0.5.0.

  dirty = None

    (`bool`) Whether the image is changed or not.

  property dispose

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

    Added in version 0.5.0.

  distort(method, arguments, best_fit=False, filter=None)

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

    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'

    See:

      Additional examples of Distortion.

    Parameters:

      - method (`str`) – 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

      - filter (`str`) – Optional resampling filter used when calculating pixel-value. Defaults to `'mitchell'`, or `'lanczos'` based on image type & operation.

    Added in version 0.4.1.

    Changed in version 0.6.11: Included filter= parameter.

  edge(radius=0.0)

    Applies convolution filter to detect edges.

    See:

      Example of Edge.

    Parameters:

      radius (`numbers.Real`) – aperture of detection filter.

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

    See:

      Example of Emboss.

    Parameters:

      - radius (`numbers.Real`) – filter aperture size.

      - sigma (`numbers.Real`) – standard deviation.

    Added in version 0.5.0.

  encipher(passphrase)

    Encrypt plain pixels into ciphered values.

    Note

    `ImageError` will be thrown if the system’s ImageMagick library was compiled without cipher support.

    Parameters:

      passphrase (`str`) – the secret passphrase to encrypt with.

    Added in version 0.6.3.

    Changed in version 0.6.8: Fixed C-API call.

  enhance()

    Applies digital filter to reduce noise.

    See:

      Example of Enhance.

    Added in version 0.5.0.

  equalize(channel=None)

    Equalizes the image histogram

    Parameters:

      channel (`str`) – Optional channel. See `CHANNELS`.

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

    See:

      Example of Evaluate Expression.

    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.

    Added in version 0.4.1.

  evaluate_images(operator=None)

    Create a new image by applying arithmetic operation between all images loaded in the image-stack.

    For example:

        with Image() as img:
             img.read(filename='first.png')
             img.read(filename='second.png')
             with img.evaluate_images('add') as sum:
                 sum.save(filename='sum.png')

    Parameters:

      operator (`EVALUATE_OPS`) – Type of operation to calculate.

    Added in version 0.7.0.

  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 (`str`) – a string listing the channel data format for each pixel.

      - storage (`str`) – what data type each value should be calculated as.

    Returns:

      list of values.

    Return type:

      `collections.abc.Sequence`

    Added in version 0.5.0.

    Changed in version 0.6.11: Update storage type size for “long” & “quantum” values.

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

    Adjust the canvas size of the image. Use `x` & `y` to offset the image’s relative placement in the canvas, or `gravity` helper for quick position placement.

    Parameters:

      - width (`numbers.Integral`) – the target width of the extended image. Default is the `width` of the image.

      - height (`numbers.Integral`) – the target height of the extended image. Default is the `height` of the image.

      - x (`numbers.Integral`) – the x-axis offset of the extended image. Default is 0, and can not be used with `gravity`.

      - y (`numbers.Integral`) – the `y` offset of the extended image. Default is 0, and can not be used with `gravity`.

      - gravity (`str`) – position of the item extent when not using `x` & `y`. See `GRAVITY_TYPES`.

    Added in version 0.4.5.

    Changed in version 0.6.8: Added `gravity` argument.

    Changed in version 0.7.0: Allow `x` & `y` offset to apply relative to `gravity`.

  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`

    Added in version 0.5.5.

  fft(magnitude=True)

    Alias for `forward_fourier_transform()`.

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

    See:

      Example of Flip and flop.

    Added in version 0.3.0.

  floodfill(fill='none', fuzz=0.1, bordercolor=None, x=0, y=0, invert=False, channel='default_channels')

    Changes pixel value to `fill` color at (`x`, `y`) coordinate, and repeats for all neighboring pixels until border is reached. Use `fuzz` and/or `bordercolor` to defined tolerance & border values.

    Parameters:

      - fill (`wand.color.Color` or `str`) – New target color value.

      - fuzz (`numbers.Real`) – Fill threshold. Values between 0.0 and 1.0. Default 0.1 (10%).

      - bordercolor (`wand.color.Color` or `str`) – Optional color to use as a border. Default `None`.

      - x (`number.Integral`) – Starting point X coordinate. Default `0`.

      - y (`number.Integral`) – Starting point Y coordinate. Default `0`.

      - invert (`bool`) – Only paint none-matching pixels. Default `False`.

      - channel (`CHANNELS`) – Optional channel mask. Default `'default_channels'`.

    Added in version 0.7.0.

  flop()

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

    See:

      Example of Flip and flop.

    Added in version 0.3.0.

  property font

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

  property font_antialias

    Deprecated since version 0.5.0: Use `antialias` instead.

  property font_path

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

  property font_size

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

  property format

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

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

    See also

    `inverse_fourier_transform()` & `complex()`

    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`

    Added 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 (`str`) – Optional composite operator. Default `'over'`, and only available with ImageMagick-7.

    Added 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

    See:

      Example of Function Expression.

    Parameters:

      - function (`str`) – a string listed in `FUNCTION_TYPES`

      - arguments (`collections.abc.Sequence`) – a sequence of doubles to apply against `function`

      - channel (`str`) – optional `CHANNELS`, defaults all

    Raises:

      - ValueError – when a `function`, or `channel` is not defined in there respected constant

      - TypeError – if `arguments` is not a sequence

    Added in version 0.4.1.

  property fuzz

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

    Added 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

    See:

      Example of FX.

    Parameters:

      - expression (`str`) – 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`

    Added in version 0.4.1.

    Changed in version 0.6.9: Will raise `WandRuntimeError` if method is unable to generate a new image & doesn’t throw an exception.

  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.

    See:

      Example of Gamma.

    Parameters:

      - adjustment_value (`numbers.Real`) – value to adjust gamma level. Default 1.0

      - channel (`str`) – optional channel to apply gamma correction

    Raises:

      - TypeError – if `gamma_point` is not a `numbers.Real`

      - ValueError – if `channel` is not in `CHANNELS`

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

    See:

      Example of Gaussian Blur.

    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 (`str`) – Optional color channel to target. See `CHANNELS`

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

  get_image_distortion(image, metric='undefined')

    Compares two images, and return the specified distortion metric.

    This method is faster than `compare()` method as ImageMagick will not need to reconstruct an image.

    Parameters:

      - image (`wand.image.BaseImage`) – Image to reference.

      - metric (`str`) – Compare distortion metric to use. See `COMPARE_METRICS`.

    Returns:

      Computed value of the distortion metric used.

    Return type:

      `numbers.Real`

    Added in version 0.6.6.

  property gravity

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

  property 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)`.

    Added 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:

      - image (`wand.image.BaseImage`) – The HALD color matrix.

      - channel (`str`) – Optional color channel to target. See `CHANNELS`

    Added in version 0.5.0.

    Changed in version 0.5.5: Added `channel` argument.

  property height

    (`numbers.Integral`) The height of this image.

  property 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

    Added 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:

      - width (`numbers.Integral`) – Local maxima of neighboring pixels.

      - height (`numbers.Integral`) – Local maxima of neighboring pixels.

      - threshold (`numbers.Integral`) – Line count to limit. Default to 40.

    Raises:

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

    Added in version 0.5.5.

  ift(phase, magnitude=True)

    Alias for `inverse_fourier_transform()`.

    Added in version 0.5.7.

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

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

    See:

      Example of Implode.

    Parameters:

      - amount (`numbers.Real`) – Normalized degree of effect between 0.0 & 1.0.

      - method (`str`) – Which interpolate method to apply to effected pixels. See `PIXEL_INTERPOLATE_METHODS` for a list of options. Only available with ImageMagick-7.

    Added 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 (`str`) – a string listing the channel data format for each pixel.

      - storage (`str`) – what data type each value should be calculated as.

    Added in version 0.5.0.

    Changed in version 0.6.11: Update storage type size for “long” & “quantum” values.

  property interlace_scheme

    (`str`) The interlace used by the image. See `INTERLACE_TYPES`.

    Added in version 0.5.2.

    Changed in version 0.6.2: The `interlace_scheme` property now points to the image. Previously was pointing to the `MagickWand`.

  property interpolate_method

    (`str`) The interpolation method of the image. See `PIXEL_INTERPOLATE_METHODS`.

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

    See also

    `forward_fourier_transform()` & `complex()`

    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`

    Added in version 0.5.5.

  iterator_first()

    Sets the internal image-stack iterator to the first image. Useful for prepending an image at the start of the stack.

    Added in version 0.6.2.

  iterator_get()

    Returns the position of the internal image-stack index.

    Return type:

      `int`

    Added in version 0.6.2.

  iterator_last()

    Sets the internal image-stack iterator to the last image. Useful for appending an image to the end of the stack.

    Added in version 0.6.2.

  iterator_length()

    Get the count of images in the image-stack.

    Return type:

      `int`

    Added in version 0.6.2.

  iterator_next()

    Steps the image-stack index forward by one

    Return type:

      `bool`

    Added in version 0.6.2.

  iterator_previous()

    Steps the image-stack index back by one.

    Return type:

      `bool`

    Added in version 0.6.2.

  iterator_reset()

    Reset internal image-stack iterator. Useful for iterating over the image-stack without allocating `Sequence`.

    Added in version 0.6.2.

  iterator_set(index)

    Sets the index of the internal image-stack.

    Return type:

      `bool`

    Added in version 0.6.2.

  kmeans(number_colors=None, max_iterations=100, tolerance=0.01)

    Reduces the number of colors in an image by applying the K-means clustering algorithm.

    Note

    Requires ImageMagick-7.0.10-37, or later.

    Parameters:

      - number_colors (`numbers.Integral`) – the target number of colors to use as seeds.

      - max_iterations (`numbers.Integral`) – maximum number of iterations needed until convergence. Default `100`.

      - tolerance (`numbers.Real`) – maximum tolerance between distortion iterations. Default `0.01`

    Added in version 0.6.4.

  property kurtosis

    (`numbers.Real`) The kurtosis of the image.

    Tip

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

    Added 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 (`str`) – Select which color channel to evaluate. See `CHANNELS`. Default `'default_channels'`.

    Returns:

      Tuple of `kurtosis` & `skewness` values.

    Return type:

      `tuple`

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

    See:

      Example of Kuwahara.

    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.

    Added in version 0.5.5.

  label(text, left=None, top=None, font=None, gravity=None, background_color='transparent')

    Writes a label `text` into the position on top of the existing canvas. This method doesn’t auto-fit text like `caption()`. Use `left` & `top`, or `gravity`, to position the text.

    Parameters:

      - text (`str`) – text to write.

      - left (`numbers.Integral`) – x offset in pixels.

      - top (`numbers.Integral`) – y offset in pixels.

      - font (`wand.font.Font`) – font to use. default is `font` of the image.

      - gravity (`str`) – text placement gravity.

    Added in version 0.6.8.

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

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

    See:

      Example of Level.

    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 to or less than the `black` value.

    Added 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 (`str`) – target a specific color-channel to levelize.

    Raises:

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

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

    Added 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 (`str`) – target a specific color-channel to levelize.

    Raises:

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

    Added 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

    Added in version 0.4.1.

  liquid_rescale(width, height, delta_x=1, 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 1

    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.

    Changed in version 0.7.0: Updated default value of `delta_x` to `1` to match CLI.

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

    Added in version 0.5.7.

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

    Added in version 0.5.5.

  property matte_color

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

    Added in version 0.4.1.

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

    Added in version 0.5.3.

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

    Added 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 (`str`) – 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`

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

    Added 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 (`str`) – the method of selecting the size of the initial canvas.

    Added in version 0.4.3.

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

    Added in version 0.5.3.

  minimum_bounding_box(orientation=None)

    Find the minimum bounding box within the image. Use properties `fuzz` & `background_color` to influence bounding box thresholds.

        from wand.image import Image
        from wand.drawing import Drawing

        with Image(filename='kdf_black.png') as img:
            img.fuzz = img.quantum_range * 0.1
            img.background_color = 'black'
            mbr = img.minimum_bounding_box()
            with Drawing() as ctx:
                ctx.fill_color = 'transparent'
                ctx.stroke_color = 'red'
                ctx.polygon(points=mbr['points'])
                ctx.fill_color = 'red'
                ctx.stroke_color = 'transparent'
                ctx.text(1, 10, '{0:.4g}°'.format(mbr['angle']))
                ctx(img)
            img.save(filename='kdf_black_mbr.png')

    Note

    Requires ImageMagick-7.0.10 or later.

    Parameters:

      orientation (`str`) – sets the image orientation. Values can be `'landscape'`, or `'portrait'`.

    Returns:

      a directory of MBR properties & corner points.

    Return type:

      `dict` { “points”: `list` [ `tuple` ( `float`, `float` ) ], “area”: `float`, “width”: `float`, “height”: `float`, “angle”: `float`, “unrotate”: `float` }

    Added in version 0.6.4.

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

    Added 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:

      - brightness (`numbers.Real`) – percentage of brightness

      - saturation (`numbers.Real`) – percentage of saturation

      - hue (`numbers.Real`) – percentage of hue rotation

    Raises:

      ValueError – when one or more arguments are invalid

    Added 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 (`str`) – effect function to apply. See `MORPHOLOGY_METHODS` for a list of methods.

      - kernel (`str`) – 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 (str) – Optional color channel to target. See `CHANNELS`

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

    See:

      Example of Motion Blur.

    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.

    Added 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 (`str`) – the channel type. available values can be found in the `CHANNELS` mapping. If `None`, negate all channels.

    Added in version 0.3.8.

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

    Adds noise to image.

    See:

      Example of Add Noise.

    Parameters:

      - noise_type (`str`) – type of noise to apply. See `NOISE_TYPES`.

      - attenuate (`numbers.Real`) – rate of distribution. Only available in ImageMagick-7. Default is `1.0`.

      - channel (`str`) – Optionally target a color channel to apply noise to. See `CHANNELS`.

    Added in version 0.5.3.

    Changed in version 0.5.5: Added optional `channel` argument.

  normalize(channel=None)

    Normalize color channels.

    Parameters:

      channel (`str`) – 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.

    Added 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 (`str`) – Optional color channel to target. See `CHANNELS`

    Added in version 0.5.4.

    Changed in version 0.5.5: Added `channel` parameter.

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

    Added 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 formats.

    Added in version 0.5.0.

  options = None

    (`OptionDict`) The mapping of internal option settings.

    Added 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 (`str`) – Name of threshold dither to use, followed by optional arguments.

      - channel (`str`) – Optional argument to apply dither to specific color channel. See `CHANNELS`.

    Added in version 0.5.7.

  property orientation

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

    Added in version 0.3.0.

  property page

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

        with Image(filename='wizard:') as img:
            img.page = (595, 842, 0, 0)

    Note that since it is based on the virtual canvas, it may not equal the dimensions of an image. See the ImageMagick documentation on the virtual canvas for more information.

    This attribute can also be set by using a named papersize. For example:

        with Image(filename='wizard:') as img:
            img.page = 'a4'

    Added in version 0.4.3.

    Changed in version 0.6.4: Added support for setting by papersize.

  property page_height

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

    Added in version 0.4.3.

  property page_width

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

    Added in version 0.4.3.

  property page_x

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

    Added in version 0.4.3.

  property page_y

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

    Added 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 (`str`) – 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.

    Added 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 (`str`) – The percent escaped string to be translated.

    Returns:

      String of expanded values.

    Return type:

      `str`

    Added in version 0.5.6.

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

    Creates a special effect simulating a Polaroid photo.

    See:

      Example of Polaroid.

    Parameters:

      - angle (`numbers.Real`) – applies a shadow effect along this angle.

      - caption (`str`) – Writes a message at the bottom of the photo’s border.

      - font (`wand.font.Font`) – Specify font style.

      - method (`str`) – Interpolation method. ImageMagick-7 only.

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

    Added in version 0.5.5.

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

    Reduce color levels per channel.

    Parameters:

      - levels (`numbers.Integral`) – Number of levels per channel.

      - dither (str) – Dither method to apply. See `DITHER_METHODS`.

    Added in version 0.5.0.

  quantize(number_colors, colorspace_type='undefined', 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 (`str`) – Available value can be found in the `COLORSPACE_TYPES`. Defaults value `"undefined"`.

      - 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 `str`) – 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.

    Added in version 0.4.2.

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

    Changed in version 0.7.0: The default value for `colorspace_type` argument is now set to `"undefined"` to match CLI behavior.

  property quantum_range

    (:class:`numbers.Integral) The maximum value of a color channel that is supported by the imagemagick library.

    Added 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 operates 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 (`str`) – Optional argument to apply dither to specific color channel. See `CHANNELS`.

    Added 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 (`str`) – 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`

    Added in version 0.5.3.

  range_threshold(low_black=0.0, low_white=None, high_white=None, high_black=None)

    Applies soft & hard threshold.

    For a soft threshold, 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 threshold, 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.

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

    Added in version 0.5.7.

  property 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)`.

    Added in version 0.5.2.

  region(width=None, height=None, x=None, y=None, gravity=None)

    Extract an area of the image. This is the same as `crop()`, but returns a new instance of `Image` without altering the original source image.

        from wand.image import Image

        with Image(filename='input.jpg') as img:
            with img.region(width=100, height=100, x=0, y=0) as area:
                pass

    Parameters:

      - width (`numbers.Integral`) – Area size on the X-axis. Default value is the image’s `page_width`.

      - height (`numbers.Integral`) – Area size on the Y-axis.Default value is the image’s `page_height`.

      - x (`numbers.Integral`) – X-axis offset. This number can be negative. Default value is the image’s `page_x`.

      - y (`numbers.Integral`) – Y-axis offset. This number can be negative. Default value is the image’s `page_y`.

      - region (`str`) – Helper attribute to set `x` & `y` offset. See `GRAVITY_TYPES`.

    Returns:

      New instance of Wand.

    Return type:

      `Image`

    Added in version 0.6.8.

    Changed in version 0.7.0: Allow `x` & `y` offset to apply relative to `gravity`.

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

    Rebuild image palette with closest color from given affinity image.

    See:

      Example of Remap.

    Parameters:

      - affinity (`BaseImage`) – reference image.

      - method (`str`) – dither method. See `DITHER_METHODS`. Default is `'no'` dither.

    Added in version 0.5.3.

  property rendering_intent

    (`str`) PNG rendering intent. See `RENDERING_INTENT_TYPES` for valid options.

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

    Note

    This method will automatically `coalesce()` & resample all frames in a GIF animation. For other image formats, `resample()` will only effect the current image in the stack. Use `iterator_reset()` & `iterator_next()` to traverse the image stack to resample all images in a multi-layer document.

        with Image(filename='input.tiff') as img:
            img.iterator_reset()
            while True:
                img.resample(128, 128)
                if not img.iterator_next():
                    break

    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 (`str`, `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

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

    Added in version 0.2.0.

  reset_sequence()

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

    Added 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 (`str`, `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`.

    Added in version 0.1.1.

  property resolution

    (`tuple`) Resolution of this image.

    Added in version 0.3.0.

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

  roll(x=0, y=0)

    Shifts all pixels over by an X/Y offset.

    Parameters:

      - x (`numbers.Integral`) – Number of columns to roll over. Negative value will roll pixels from right-to-left, and positive value will roll pixels from left-to-right. Default value: `0`.

      - y (`numbers.Integral`) – Number of rows to roll over. Negative value will roll pixels from bottom-to-top, and positive value will roll pixels from top-to-bottom. Default value: `0`.

    Added in version 0.6.8.

  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.

    See:

      Example of Rotation.

    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.

    Added in version 0.2.0: The `reset_coords` parameter.

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

    See:

      Example of Rotational Blur.

    Parameters:

      - angle (`numbers.Real`) – Degrees of rotation to blur with.

      - channel (`str`) – 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.

    Added 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

    Added in version 0.3.4.

  property sampling_factors

    (`tuple`) Factors used in sampling data streams. This can be set by given it a string `"4:2:2"`, or tuple of numbers `(2, 1, 1)`. However the given string value will be parsed to aspect ratio (i.e. `"4:2:2"` internally becomes `"2,1"`).

    Note

    This property is only used by YUV, DPX, & EXR encoders. For JPEG & TIFF set `"jpeg:sampling-factor"` on `Image.options` dictionary:

        with Image(filename='input.jpg') as img:
            img.options['jpeg:sampling-factor'] = '2x1'

    Added in version 0.6.3.

  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.

    Added in version 0.5.7.

  property scene

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

    Added in version 0.5.4.

  property seed

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

    Warning

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

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

    See:

      Example of Selective Blur.

    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 (`str`) – Optional color channel to target. See `CHANNELS`

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

    See:

      Example of Sepia Tone.

    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%”.

    Added in version 0.5.7.

  sequence = None

    (`collections.abc.Sequence`) The list of `SingleImage`s that the image contains.

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

    See:

      Example of Shade.

    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.

    Added in version 0.5.0.

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

    Generates an image shadow.

    Parameters:

      - alpha (`numbers.Real`) – Ratio of transparency.

      - sigma (`numbers.Real`) – Standard deviation of the gaussian filter.

      - x (`numbers.Integral`) – x-offset.

      - y (`numbers.Integral`) – y-offset.

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

    See:

      Example of Sharpen.

    Parameters:

      - radius (`numbers.Real`) – size of gaussian aperture.

      - sigma (`numbers.Real`) – Standard deviation of the gaussian filter.

      - channel (`str`) – Optional color channel to target. See `CHANNELS`.

    Added 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:

      - columns (`numbers.Integral`) – amount to shave off both sides of the x-axis.

      - rows (`numbers.Integral`) – amount to shave off both sides of the y-axis.

    Added 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:

      - background (`wand.color.Color`) – Color to fill the void created by shearing the image.

      - x (`numbers.Real`) – Slide the image along the X-axis.

      - y (`numbers.Real`) – Slide the image along the Y-axis.

    Added 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 (`str`) – Optional color channel to target. See `CHANNELS`.

    Added in version 0.5.4.

    Changed in version 0.5.5: Added `channel` argument.

  property signature

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

    Added 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 (`str`) – 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`)

    Added in version 0.5.4: has been added.

  property 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`.

    See:

      Example of Sketch.

    Parameters:

      - radius (`numbers.Real`) – size of Gaussian aperture.

      - sigma (`numbers.Real`) – standard deviation of the Gaussian operator.

      - angle (`numbers.Real`) – direction of blur.

    Added in version 0.5.3.

  property skewness

    (`numbers.Real`) The skewness of the image.

    Tip

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

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

    Added in version 0.5.3.

  solarize(threshold=0.0, channel=None)

    Simulates extreme overexposure.

    See:

      Example of Solarize.

    Parameters:

      - threshold (`numbers.Real`) – between `0.0` and `quantum_range`.

      - channel (`str`) – Optional color channel to target. See `CHANNELS`

    Added in version 0.5.3.

    Changed in version 0.5.5: Added `channel` argument.

  sparse_color(method='barycentric', colors=None, channel_mask=7)

    Interpolates color values between points on an image.

    The `colors` argument should be a list of tuples containing the point’s x, y coordinate & `Color` value.

    For example:

        from wand.image import Image

        colors = [
            (10, 50, 'RED'),
            (174, 32, 'YELLOW'),
            (74, 123, 'ORANGE')
        ]
        with Image(filename='input.png') as img:
            img.sparse_color('bilinear', colors)

    The available interpolate methods are:

    - `'barycentric'`

    - `'bilinear'`

    - `'shepards'`

    - `'voronoi'`

    - `'inverse'`

    - `'manhattan'`

    You can control which color channels are effected by building a custom channel mask. For example:

        from wand.image import Image, CHANNELS

        with Image(filename='input.png') as img:
            colors = [
                (50, 50, img[50, 50]),
                (100, 50, img[100, 50]),
                (50, 75, img[50, 75]),
                (100, 100, img[100, 100])
            ]
            # Only apply Voronoi to Red & Alpha channels
            mask = CHANNELS['red'] | CHANNELS['alpha']
            img.sparse_color('voronoi', colors, channel_mask=mask)

    Parameters:

      - method (`str`) – Interpolate method. See `SPARSE_COLOR_METHODS`

      - colors (`abc.Iterable` [ int, int, `Color` ]) – A list of (x, y, color) tuples.

      - channel_mask (`numbers.Integral`) – Isolate specific color channels to apply interpolation. Default to RGB channels.

    Added in version 0.5.3.

    Changed in version 0.7.0: The `colors` argument switch from a `dict` to `list` to allow two, or more, points of the same `Color`.

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

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

    Parameters:

      - width (`numbers.Integral`) – number of pixel columns.

      - height (`numbers.Integral`) – number of pixel rows.

      - x (`numbers.Integral`) – offset on the X-axis.

      - y (`numbers.Integral`) – offset on the Y-axis.

    Added in version 0.5.3.

    Changed in version 0.7.0: Allow `x` & `y` offset to apply relative to `gravity`.

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

    Randomly displace pixels within a defined radius.

    See:

      Example of Spread.

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

    Added in version 0.5.3.

    Changed in version 0.5.7: Added default value to `radius`.

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

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

    See:

      Example of Statistic.

    Parameters:

      - stat (`str`) – 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 (`str`) – Optional color channel to target. See `CHANNELS`

    Added 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:

      - watermark (`wand.image.Image`) – Image to hide within image.

      - offset (`numbers.Integral`) – Start embedding image after a number of pixels.

    Added in version 0.5.4.

  strip()

    Strips an image of all profiles and comments.

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

    See:

      Example of Swirl.

    Parameters:

      - degree (`numbers.Real`) – Defines the amount of pixels to be effected. Value between `-360.0` and `360.0`.

      - method (`str`) – Controls interpolation of the effected pixels. Only available for ImageMagick-7. See `PIXEL_INTERPOLATE_METHODS`.

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

    Added 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 (`str`) – the channel type. available values can be found in the `CHANNELS` mapping. If `None`, threshold all channels.

    Added 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

    Added in version 0.5.4.

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

    See:

      Example of Tint.

    Parameters:

      - color (`Color`) – Color to calculate midtone.

      - alpha (`Color`) – Determine how to blend.

    Added 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`%x` scale-y`%`

      Height and width individually scaled by specified percentages. Only one % symbol is needed.

    width

      Width given, height automatically selected to preserve aspect ratio.

    `x` height

      Height given, width automatically selected to preserve aspect ratio.

    width `x` height

      Maximum values of width and height given; aspect ratio preserved.

    width `x` height`!`

      Width and height emphatically given; original aspect ratio ignored.

    width `x` height`>`

      Shrinks images with dimension(s) larger than the corresponding width and/or height dimension(s).

    width `x` height`<`

      Enlarges images with dimensions smaller than the corresponding width and/or height dimension(s).

    area`@`

      Resize image to have the specified area in pixels. Aspect ratio is preserved.

    X`:`Y

      Resize at a given aspect ratio. Common aspect ratios may include `4:3` for video/tv, `3:2` for 35mm film, `16:9` for HDTV, and `2.39:1` for cinema. Aspect ratio can be used with the crop parameter, but is only available with ImageMagick version 7.0.8 or greater.

    The offset, which only applies to the cropping geometry string, is given by `{+-}`x`{+-}`y, that is, one plus or minus sign followed by an x offset, followed by another plus or minus sign, followed by a y offset. Offsets are in pixels from the upper left corner of the image. Negative offsets will cause the corresponding number of pixels to be removed from the right or bottom edge of the image, meaning the cropped size will be the computed size minus the absolute value of the offset.

    For example, if you want to crop your image to 300x300 pixels and then scale it by 2x for a final size of 600x600 pixels, you can call:

        image.transform('300x300', '200%')

    This method is a fairly thin wrapper for the C API, and does not perform any additional checking of the parameters except insofar as verifying that they are of the correct type. Thus, like the C API function, the method is very permissive in terms of what it accepts for geometry strings; unrecognized strings and trailing characters will be ignored rather than raising an error.

    Parameters:

      - crop (`str`) – A geometry string defining a subregion of the image to crop to

      - resize (`str`) – 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.

    Added 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 (`str`) – colorspace_type. available value can be found in the `COLORSPACE_TYPES`

    Added 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.Real`) – 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.

    Added in version 0.3.0.

    Changed in version 0.6.3: Parameter `fuzz` type switched from Integral to Real.

  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

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

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

    Added in version 0.4.1.

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

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

    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 trimming image. Default `False`.

      - percent_background (`numbers.Real`) – Sets how aggressive the trim operation will be. A value of 0.0 will trim to the minimal bounding box of all matching color, and 1.0 to the most outer edge.

      - background_color – Local alias to `background_color`, and has the same effect as defining `color` parameter – but much faster.

    Added 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 accept color-compliant strings.

    Changed in version 0.6.0: Optional `reset_coords` parameter added.

    Changed in version 0.6.4: Optional `percent_background` & `background_color` parameters have been added.

  property type

    (`str`) The image type.

    Defines image type as in `IMAGE_TYPES` enumeration.

    It may raise `ValueError` when the type is unknown.

    Added in version 0.2.2.

  unique_colors()

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

    Added in version 0.5.0.

  property units

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

    See:

      Example of Unsharp Mask.

    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 (`str`) – Optional color channel to target. See `CHANNELS`

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

    See:

      Example of Vignette.

    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.

    Added in version 0.5.2.

  property virtual_pixel

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

  property 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

    Added in version 0.2.0.

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

    Creates a ripple effect within the image.

    See:

      Example of Wave.

    Parameters:

      - amplitude (`numbers.Real`) – height of wave form.

      - wave_length (`numbers.Real`) – width of wave form.

      - method (`str`) – pixel interpolation method. Only available with ImageMagick-7. See `PIXEL_INTERPOLATE_METHODS`

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

    See:

      Example of Wavelet Denoise.

    Parameters:

      - threshold (`numbers.Real`) – Smoothing limit.

      - softness (`numbers.Real`) – Attenuate of the smoothing threshold.

    Raises:

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

    Added in version 0.5.5.

  white_balance()

    Uses LAB colorspace to apply a white balance to the image.

    Note

    Requires ImageMagick-7.0.10-37 or later.

    Added in version 0.6.4.

  property 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)`.

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

    Added in version 0.5.2.

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

    Added in version 0.5.7.

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

  Added 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

  See also

  ImageMagick Compare Operations

  Added 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', 'freeze', 'interpolate', 'negate', 'reflect', 'soft_burn', 'soft_dodge', 'stamp', 'rmse', 'saliency_blend', 'seamless_blend')

  (`tuple`) The list of composition operators

  - `'undefined'`

  - `'alpha'` - Only available with ImageMagick-7

  - `'atop'`

  - `'blend'`

  - `'blur'`

  - `'bumpmap'`

  - `'change_mask'`

  - `'clear'`

  - `'color_burn'`

  - `'color_dodge'`

  - `'colorize'`

  - `'copy_black'`

  - `'copy_blue'`

  - `'copy'`

  - `'copy_alpha'` - Only available with ImageMagick-7

  - `'copy_cyan'`

  - `'copy_green'`

  - `'copy_magenta'`

  - `'copy_opacity'` - Only available with ImageMagick-6

  - `'copy_red'`

  - `'copy_yellow'`

  - `'darken'`

  - `'darken_intensity'`

  - `'difference'`

  - `'displace'`

  - `'dissolve'`

  - `'distort'`

  - `'divide_dst'`

  - `'divide_src'`

  - `'dst_atop'`

  - `'dst'`

  - `'dst_in'`

  - `'dst_out'`

  - `'dst_over'`

  - `'exclusion'`

  - `'freeze'` - Added with ImageMagick-7.0.10

  - `'hard_light'`

  - `'hard_mix'`

  - `'hue'`

  - `'in'`

  - `'intensity'` - Only available with ImageMagick-7

  - `'interpolate'` - Added with ImageMagick-7.0.10

  - `'lighten'`

  - `'lighten_intensity'`

  - `'linear_burn'`

  - `'linear_dodge'`

  - `'linear_light'`

  - `'luminize'`

  - `'mathematics'`

  - `'minus_dst'`

  - `'minus_src'`

  - `'modulate'`

  - `'modulus_add'`

  - `'modulus_subtract'`

  - `'multiply'`

  - `'negate'` - Added with ImageMagick-7.0.10

  - `'no'`

  - `'out'`

  - `'over'`

  - `'overlay'`

  - `'pegtop_light'`

  - `'pin_light'`

  - `'plus'`

  - `'reflect'` - Added with ImageMagick-7.0.10

  - `'replace'`

  - `'rmse'` - Added with ImageMagick-7.1.0

  - `'saliency_blend'` - Added with ImageMagick-7.1.1

  - `'saturate'`

  - `'screen'`

  - `'seamless_blend'` - Added with ImageMagick-7.1.1

  - `'soft_burn'` - Added with ImageMagick-7.0.10

  - `'soft_dodge'` - Added with ImageMagick-7.0.10

  - `'soft_light'`

  - `'src_atop'`

  - `'src'`

  - `'src_in'`

  - `'src_out'`

  - `'src_over'`

  - `'stamp'` - Added with ImageMagick-7.0.10

  - `'stereo'`

  - `'threshold'`

  - `'vivid_light'`

  - `'xor'`

  Changed in version 0.3.0: Renamed from `COMPOSITE_OPS` to `COMPOSITE_OPERATORS`.

  Changed in version 0.5.6: Operators have been updated to reflect latest changes in C-API. For ImageMagick-6, `'add'` has been renamed to `'modulus_add'`, `'subtract'` has been renamed to `'modulus_subtract'`, `'divide'` has been split into `'divide_dst'` & `'divide_src'`, and `'minus'` has been split into `'minus_dst'` & `'minus_src'`.

  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.

  - `'undefined'`

  - `'b44a'`

  - `'b44'`

  - `'bzip'`

  - `'dxt1'`

  - `'dxt3'`

  - `'dxt5'`

  - `'fax'`

  - `'group4'`

  - `'jbig1'`

  - `'jbig2'`

  - `'jpeg2000'`

  - `'jpeg'`

  - `'losslessjpeg'`

  - `'lzma'`

  - `'lzw'`

  - `'no'`

  - `'piz'`

  - `'pxr24'`

  - `'rle'`

  - `'zip'`

  - `'zips'`

  Added in version 0.3.6.

  Changed in version 0.5.0: Support for ImageMagick-6 & ImageMagick-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.

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

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

  Added in version 0.5.5.

  Changed in version 0.6.3: Added `merge` & `metric` for ImageMagick 7.0.10

  Changed in version 0.6.8: Added `key` property for ImageMagick 7.1.0

  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.

  property centroid

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

  clone_from_cc_object_info(cc_object)

    Copy data from `CCObjectInfo`.

  clone_from_extra_70A_info(cc_object)

    Copy the additional values from CCObjectInfo structure. This is the `merge` & `metric` properties added in ImageMagick 7.0.10.

    Added in version 0.6.3.

  clone_from_extra_710_info(cc_object)

    Copy additional value from CCObjectInfo structure for properties added to ImageMagick 7.1.0.

    Added in version 0.6.8.

  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.

  merge = None

    (`bool`) Object merge flag. Only available after ImageMagick-7.0.10. ..versionadded:: 0.6.3

  metric = None

    (`list`) List of doubles used by metric. Only available after ImageMagick-7.0.10. ..versionadded:: 0.6.3

  property offset

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

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

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

  (`tuple`) The list of `BaseImage.dispose` types.

  - `'undefined'`

  - `'none'`

  - `'background'`

  - `'previous'`

  Added 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', 'rigidaffine')

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

  - `'rigidaffine'` - Only available with ImageMagick-7.0.10, or later.

  Added 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'`

  Added 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', 'inverse_log')

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

  - `'undefined'`

  - `'abs'`

  - `'add'`

  - `'addmodulus'`

  - `'and'`

  - `'cosine'`

  - `'divide'`

  - `'exponential'`

  - `'gaussiannoise'`

  - `'impulsenoise'`

  - `'inverse_log'` - Added with ImageMagick-7.0.10-24

  - `'laplaciannoise'`

  - `'leftshift'`

  - `'log'`

  - `'max'`

  - `'mean'`

  - `'median'`

  - `'min'`

  - `'multiplicativenoise'`

  - `'multiply'`

  - `'or'`

  - `'poissonnoise'`

  - `'pow'`

  - `'rightshift'`

  - `'set'`

  - `'sine'`

  - `'subtract'`

  - `'sum'`

  - `'threshold'`

  - `'thresholdblack'`

  - `'thresholdwhite'`

  - `'uniformnoise'`

  - `'xor'`

  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', 'lanczosradius', 'cubicspline', 'magickernelsharp2013', 'magickernelsharp2021', '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'`

  - `'lanczosradius'`

  - `'cubicspline'`

  - `'magickernelsharp2013'`

  - `'magickernelsharp2021'`

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

  Added in version 0.3.0.

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

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

  - `'undefined'`

  - `'coalesce'`

  - `'compareany'` - Only used for `compare_layers()`.

  - `'compareclear'` - Only used for `compare_layers()`.

  - `'compareoverlay'` - Only used for `compare_layers()`.

  - `'dispose'`

  - `'optimize'`

  - `'optimizeimage'`

  - `'optimizeplus'`

  - `'optimizetrans'`

  - `'removedups'`

  - `'removezero'`

  - `'composite'`

  - `'merge'` - Only used for `merge_layers()`.

  - `'flatten'` - Only used for `merge_layers()`.

  - `'mosaic'` - Only used for `merge_layers()`.

  - `'trimbounds'` - Only used for `merge_layers()`.

  Added 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'`

  Added in version 0.5.2.

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

  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 (`str`) – opens an image of the `filename` string. Additional Read Modifiers are supported.

    - format (`str`) – 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 (`str`,) – sets the stack’s default colorspace value before reading any images. See `COLORSPACE_TYPES`.

    - units (`str`) – paired with `resolution` for defining an image’s pixel density. See `UNIT_TYPES`.

  Added in version 0.1.5: The `file` parameter.

  Added in version 0.1.1: The `blob` parameter.

  Added in version 0.2.1: The `format` parameter.

  Added in version 0.2.2: The `width`, `height`, `background` parameters.

  Added in version 0.3.0: The `resolution` parameter.

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

  Added 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` parameter to specify canvas color when reading in image.

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

  Changed in version 0.6.3: Added `sampling_factors` parameter for working with YUV streams.

  [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`

    Added in version 0.1.2.

  property animation

    (`bool`) Returns `True` if the image mimetype matches a known animation format, and contains more than one frame.

    Added in version 0.3.0.

    Changed in version 0.7.1: Included additional popular animation formats.

  artifacts = None

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

    Added in version 0.5.0.

  blank(width, height, background=None)

    Creates blank image.

    Parameters:

      - width (`numbers.Integral`) – the width of new blank image.

      - height (`numbers.Integral`) – the height of new blank image.

      - background (`wand.color.Color`) – an optional background color. default is transparent

    Returns:

      blank image

    Return type:

      `Image`

    Added in version 0.3.0.

  channel_depths = None

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

    Added in version 0.3.0.

  channel_fx(expression)

    Generate a new image by applying the Channel-FX expression. Useful for exchanging, copying, or extracting image channels.

    For example:

        # Swap the red and green channels of an image.
        with Image(filename='input.png') as img:
            with img.channel_fx('red <=> green') as swapped:
                swapped.save(filename='swapped_output.png')

    See also

    Channel FX for more details.

    Warning

    This class method is only available with ImageMagick 7.x.x, or greater.

    Parameters:

      expression (`str`) – The Channel-FX expression to apply.

    Returns:

      A new image with Channel-FX expression applied.

    Return type:

      `Image`

    Added in version 0.7.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.

    Added 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 (`str`) – Can be `'compareany'`, `'compareclear'`, or `'compareoverlay'`

    Returns:

      new image stack.

    Return type:

      `Image`

    Added 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 (`str`) – image format to convert to

    Returns:

      a converted image

    Return type:

      `Image`

    Raises:

      ValueError – when the given `format` is unsupported

    Added in version 0.1.6.

    Changed in version 0.6.11: Call `MagickSetFormat()` method after `MagickSetImageFormat()`. This will ensure image info, magick, and filename properties are aligned.

  data_url()

    Generate a base64 data-url string from the loaded image. Useful for converting small graphics into ASCII strings for HTML/CSS web development.

    Returns:

      a data-url formatted string.

    Return type:

      `str`

    Added in version 0.6.3.

  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"`, 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 (`str`) – Color channel layout.

      - storage (`str`) – Datatype per pixel part.

    Returns:

      New instance of an image.

    Return type:

      `Image`

    Added 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' )``.

  image_add(image)

    Copies a given image on to the image stack. By default, the added image will be append at the end of the stack, or immediately after the current image iterator defined by `iterator_set()`. Use `iterator_reset()` before calling this method to insert the new image before existing images on the stack.

    Parameters:

      image (`Image`) – raster to add.

    Added in version 0.6.7.

  image_get()

    Generate & return a clone of a single image at the current image-stack index.

    Added in version 0.6.7.

  image_remove()

    Remove an image from the image-stack at the current index.

    Added in version 0.6.7.

  image_set(image)

    Overwrite current image on the image-stack with given image.

    Parameters:

      image (`wand.image.Image`) – Wand instance of images to write to stack.

    Added in version 0.6.7.

  image_swap(i, j)

    Swap two images on the image-stack.

    Parameters:

      - i (`numbers.Integral`) – image index to replace with `j`

      - j (`numbers.Integral`) – image index to replace with `i`

    Added in version 0.6.7.

  make_blob(format=None)

    Makes the binary string of the image.

    Parameters:

      format (`str`) – 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.

    Added in version 0.1.5: The `format` parameter became optional.

    Added in version 0.1.1.

  metadata = None

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

    Added in version 0.3.0.

  property mimetype

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

    Added in version 0.1.7.

  montage(font=None, tile=None, thumbnail=None, mode='unframe', frame=None)

    Generates a new image containing thumbnails if each previous image read.

        with Image() as img:
            for file_path in ['first.png', 'second.png', 'third.png']:
                with Image(filename=file_path) as item:
                    img.options['label'] = file_path
                    img.image_add(item)
            style = Font('monospace', 24, 'green')
            img.montage(font=style, tile='3x1', thumbnail='15x15')
            img.save(filename='montage.png')

    Parameters:

      - font (`Font`) – Define font style to use when labeling each thumbnail. Thumbnail labeling will only be rendered if `'label'` value in `options` dict is defined.

      - tile (`str`) – The number of thumbnails per rows & column on a page. Example: `"6x4"`.

      - thumbnail (`str`) – Preferred image size. Montage will attempt to generate a thumbnail to match the geometry. This can also define the border size on each thumbnail. Example: `"120x120x+4+3>"`.

      - mode (`str`) – Which effect to render. Options include `"frame"`, `"unframe"`, and `"concatenate"`. Default `"frame"`.

      - frame (`str`) – Define ornamental boarder around each thumbnail. The color of the frame is defined by the image’s matte color. Example: `"15x15+3+3"`.

    Added in version 0.6.8.

  morph(number_frames=5)

    Creates a new image by linearly interpolating pixels from the image stack.

        from wand.image import Image

        with Image() as img:
            img.read(filename='start.png')
            img.read(filename='end.png')
            with img.morph(32) as morph:
                morph.save(filename='animation.gif')

    Parameters:

      number_frames (`numbers.Integral`) – The number of in-between images to generate.

    Returns:

      New `Image` instance.

    Return type:

      `Image`

    Added in version 0.7.0.

  classmethod ping(file=None, filename=None, blob=None, **kwargs)

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

    Parameters:

      - blob (`bytes`) – reads an image from the `blob` byte array

      - file (file object) – reads an image from the `file` object

      - filename (`str`) – 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 (`str`) – suggest image file format when reading from a `blob`, or `file` property.

    Added in version 0.5.6.

  profiles = None

    (`ProfileDict`) The mapping of image profiles.

    Added 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 (`str`) – The protocol & arguments for the pseudo image.

    Added in version 0.5.0.

  read(file=None, filename=None, blob=None, background=None, colorspace=None, depth=None, extract=None, format=None, height=None, interlace=None, resolution=None, sampling_factors=None, units=None, width=None)

    Read new image into Image() object.

    Parameters:

      - blob (`bytes`) – reads an image from the `blob` byte array

      - file (file object) – reads an image from the `file` object

      - filename (`str`) – reads an image from the `filename` string. Additional Read Modifiers are supported.

      - background (`Color`, `str`) – set default background color.

      - colorspace (`str`) – set default colorspace. See `COLORSPACE_TYPES`.

      - depth (`numbers.Integral`) – sets bits per color sample. Usually `8`, or `16`.

      - format (`str`) – sets which image decoder to read with. Helpful when reading `blob` data with ambiguous headers.

      - height (`numbers.Integral`) – used with `width` to define the canvas size. Useful for reading image streams.

      - interlace (`str`) – Defines the interlacing scheme for raw data streams. See `INTERLACE_TYPES`.

      - resolution (`collections.abc.Sequence`, `numbers.Integral`) – set a resolution value (DPI), useful for vectorial formats (like PDF)

      - sampling_factors (`collections.abc.Sequence`, `str`) – set up/down sampling factors for YUV data stream. Usually `"4:2:2"`

      - units (`str`) – used with `resolution`, can either be `'pixelperinch'`, or `'pixelpercentimeter'`.

      - width (`numbers.Integral`) – used with `height` to define the canvas size. Useful for reading image streams.

    Added in version 0.3.0.

    Changed in version 0.5.7: Added `units` parameter.

    Changed in version 0.6.3: Added, or documented, optional pre-read parameters: `background`, `colorspace`, `depth`, `format`, `height`, `interlace`, `sampling_factors`, & `width`.

  reset_sequence()

    Remove any previously allocated `SingleImage` instances in `sequence` attribute.

    Added 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 (`str`) – 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.

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

    See:

      Example of Stereogram.

    Parameters:

      - left (`wand.image.Image`) – Left-eye image.

      - right (`wand.image.Image`) – Right-eye image.

    Added in version 0.5.4.

class wand.image.ImageProperty(image)

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

  Added in version 0.3.0.

  property 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

  Added in version 0.1.3.

  c_clear_exception = <_FuncPtr object>

    (`ctypes.CFUNCTYPE`) The `ctypes` function that clears an exception of the `resource`.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  c_destroy_resource = <_FuncPtr object>

    (`ctypes.CFUNCTYPE`) The `ctypes` function that destroys the `resource`.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  c_get_exception = <_FuncPtr object>

    (`ctypes.CFUNCTYPE`) The `ctypes` function that gets an exception from the `resource`.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  c_is_resource = <_FuncPtr object>

    (`ctypes.CFUNCTYPE`) The `ctypes` predicate function that returns whether the given pointer (that contains a resource data usually) is a valid resource.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  clone()

    Clones the same iterator.

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

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.

  Added in version 0.3.0.

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

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

  Added in version 0.3.0.

class wand.image.OptionDict(image)

  Free-form mutable mapping of global internal settings.

  Added 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.PAPERSIZE_MAP = {'10x13': (720, 936), '10x14': (720, 1008), '11x17': (792, 1224), '2A0': (3370, 4768), '4A0': (4768, 6741), '4x6': (288, 432), '5x7': (360, 504), '7x9': (504, 648), '8x10': (576, 720), '9x11': (648, 792), '9x12': (648, 864), 'a0': (2384, 3370), 'a1': (1684, 2384), 'a10': (74, 105), 'a2': (1191, 1684), 'a3': (842, 1191), 'a4': (595, 842), 'a4small': (595, 842), 'a5': (420, 595), 'a6': (298, 420), 'a7': (210, 298), 'a8': (147, 210), 'a9': (105, 147), 'archC': (1296, 1728), 'archa': (648, 864), 'archb': (864, 1296), 'archd': (1728, 2592), 'arche': (2592, 3456), 'b0': (2920, 4127), 'b1': (2064, 2920), 'b10': (91, 127), 'b2': (1460, 2064), 'b3': (1032, 1460), 'b4': (729, 1032), 'b5': (516, 729), 'b6': (363, 516), 'b7': (258, 363), 'b8': (181, 258), 'b9': (127, 181), 'c0': (2599, 3676), 'c1': (1837, 2599), 'c2': (1298, 1837), 'c3': (918, 1296), 'c4': (649, 918), 'c5': (459, 649), 'c6': (323, 459), 'c7': (230, 323), 'csheet': (1224, 1584), 'dsheet': (1584, 2448), 'esheet': (2448, 3168), 'executive': (540, 720), 'flsa': (612, 936), 'flse': (612, 936), 'folio': (612, 936), 'halfletter': (396, 612), 'isob0': (2835, 4008), 'isob1': (2004, 2835), 'isob10': (88, 125), 'isob2': (1417, 2004), 'isob3': (1001, 1417), 'isob4': (709, 1001), 'isob5': (499, 709), 'isob6': (354, 499), 'isob7': (249, 354), 'isob8': (176, 249), 'isob9': (125, 176), 'jisb0': (1030, 1456), 'jisb1': (728, 1030), 'jisb2': (515, 728), 'jisb3': (364, 515), 'jisb4': (257, 364), 'jisb5': (182, 257), 'jisb6': (128, 182), 'ledger': (1224, 792), 'legal': (612, 1008), 'letter': (612, 792), 'lettersmall': (612, 792), 'monarch': (279, 540), 'quarto': (610, 780), 'statement': (396, 612), 'tabloid': (792, 1224)}

  (`dict`) Map of papersize names to page sizes. Each page size is a width & height `tuple` at a 72dpi resolution.

      from wand.image import Image, PAPERSIZE_MAP

      w, h = PAPERSIZE_MAP["a4"]
      with Image(width=w, height=h, background="white") as img:
          img.save(filename="a4_page.png")

  Added in version 0.6.4.

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

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

  Added in version 0.5.1.

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

  Added 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'`

  Added 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'`

  Added 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'`

  Added in version 0.5.0.

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

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

  Added in version 0.4.1.

wand.image.manipulative(function)

  Mark the operation manipulating itself instead of returning new one.