Wand Documentation

When distorting images, new regions may be created outside the original bounding box. These are called 'virtual pixels'. You can control how these regions are filled by setting the Image.virtual_pixel attribute using values from wand.image.VIRTUAL_PIXEL_METHOD.

Common values include:

• 'transparent'
• 'black'
• 'white'
• 'background' (uses the existing background color)
• 'dither'
• 'edge'
• 'mirror'
• 'random'
• 'tile'

with Image(filename='rose:') as img:
    img.resize(140, 92)
    img.background_color = img[70, 46]
    img.virtual_pixel = 'background'
    img.distort('arc', (60, ))

Wand provides a PIL compatibility layer to allow existing Python projects that depend on PIL to use Wand instead. There are two ways to implement this:

1. Module-level compatibility: Manually change your imports to use wand.pilcompat.Image instead of PIL.Image.
2. Global monkeypatcher: Use the patch() function from wand.pilcompat.monkey to modify sys.modules. This allows existing code that calls import PIL.Image to transparently use Wand's implementation.

# Method 1: Module-level compatibility
try:
    from wand.pilcompat import Image
except ImportError:
    from PIL import Image

# Method 2: Global monkeypatcher
from wand.pilcompat.monkey import patch; patch()
import PIL.Image  # it imports wand.pilcompat.Image module

While Wand implements destructors that invoke Resource.destroy(), relying on automatic deallocation via Python's garbage collector is discouraged.

On CPython, reference counting often handles deallocation automatically, but this is an implementation detail. On other implementations like PyPy, which uses a non-deterministic garbage collector, the timing of destructor invocation is not guaranteed. Relying on automatic cleanup in these environments can lead to broken programs or resource leaks. Always use with statements or explicit .destroy()/.close() calls.

ImageMagick-7 enables High Dynamic Range Imaging (HDRI) by default. This can lead to color-value underflow or overflow during arithmetic operations.

To ensure consistent results, do not hard-code maximum color values; instead, use Image.quantum_range. To prevent underflow/overflow when using methods like Image.evaluate(), Image.function(), or Image.composite_channel(), use the Image.clamp() method.

with Image(width=1, height=1, background=Color("gray5")) as canvas:
    canvas.evaluate("subtract", canvas.quantum_range * 0.07)
    canvas.clamp()
    print(canvas[0, 0]) #=> srgb(0,0,0)

Wand provides access to approximately three dozen pre-built kernels via ImageMagick. To use a built-in kernel, provide a string in the following format:

label[:arg1,arg2,arg3,..]

• label: A string defined in wand.image.KERNEL_INFO_TYPES (e.g., disk, square, cross).
• arg1, arg2, ...: Optional arguments defined as a comma-separated list of doubles.

Common Kernel Examples:

• Cross: kernel='cross:3'
• Diamond: kernel='diamond:3'
• Disk: kernel='disk:5'
• Octagon: kernel='octagon:5'
• Plus: kernel='plus:3'
• Ring: kernel='ring:5,4'
• Square: kernel='square:3'

img.morphology(method='dilate', kernel='disk:5')

Wand supports sequential images (e.g., animated GIFs or multi-icon .ico files) via the sequence attribute on an Image object. The sequence attribute is a list-like object implementing the collections.MutableSequence protocol, allowing you to iterate over it, index it, slice it, or use len().

Each item within the sequence is an instance of wand.sequence.SingleImage. Both wand.image.Image and wand.sequence.SingleImage share a common superclass, wand.image.BaseImage, meaning most operations and properties are available for both.

from wand.image import Image
import urllib2
with Image(file=urllib2.urlopen('https://github.com/favicon.ico')) as ico:
    max(ico.sequence, key=lambda i: i.width * i.height)

While both inherit from wand.image.BaseImage and share methods like resize() and the size property, they serve different purposes:

• wand.image.Image: A container representing the entire image file (e.g., the whole GIF). It provides file-level operations like save() and the mimetype attribute.
• wand.sequence.SingleImage: Represents an individual frame or icon size within a sequence. It provides frame-specific attributes like delay and index.

Warning: When dealing with animated GIFs or multi-size ICO files, ensure you are using the correct type for the operation you intend to perform.

Wand provides access to image profiles (like EXIF, ICC, or XMP) via the Image.profiles dictionary. Because ImageMagick is not a tag editor, you should treat profiles as binary blobs (byte-arrays). To modify a profile, you must export the payload, modify it externally, and then import it back.

Important: Every write operation on a profile requires the raster image data to be re-encoded. For lossy formats, this can result in generation loss.

with Image(filename='wandtests/assets/beach.jpg') as image:
    # Extract EXIF payload
    if 'EXIF' in image.profiles:
        exif_binary = image.profiles['EXIF']

    # Import/replace ICC payload
    with open('color_profile.icc', 'rb') as icc:
        image.profiles['ICC'] = icc.read()

    # Remove XMP payload
    del image.profiles['XMP']

Wand includes unit and regression tests. You can run them using the setup.py script, which will automatically install pytest if it is missing, or you can use pytest directly after installing it manually.

To run all tests via setup.py:

$ python setup.py test

To run tests manually using pytest:

$ pip install pytest
$ pytest