Reference¶

The `Image` class¶

class Image¶

classmethod open(file)¶

Opens the provided image file detects the format from the image header using Python’s filetype module.

Returns a subclass of ImageFile

If the image format is unrecognized, this throws a willow.image.UnrecognisedImageFormatError (a subclass of IOError)

classmethod operation()¶

A decorator for registering operations.

The operations will be automatically registered when the image class is registered.

from willow.image import Image

class MyImage(Image):

    @Image.operation
    def resize(self, size):
        return MyImage(self.image.resize(size))

classmethod converter_from(other_classes, cost=100)¶

A decorator for registering a “from” converter, which is a classmethod that converts an instance of another image class into an instance of this one.

The other_classes parameter specifies which classes this converter can convert from. It can be a single class or a list.

from willow.image import Image

class MyImage(Image):
    ...

    @classmethod
    @Image.converter_from(JPEGImageFile)
    def open_jpeg_file(cls, image_file):
        return cls(image=open_jpeg(image_file.f))

It can also be applied multiple times to the same function allowing different costs to be specified for different classes:

@classmethod
@Image.converter_from([JPEGImageFile, PNGImageFile])
@Image.converter_from(GIFImageFile, cost=200)
def open_file(cls, image_file):
    ...

classmethod converter_to(other_class, cost=100)¶

A decorator for registering a “to” converter, which is a method that converts this image into an instance of another class.

The other_class parameter specifies which class this function converts to. An individual “to” converter can only convert to a single class.

from willow.image import Image

class MyImage(Image):
    ...

    @Image.converter_to(PillowImage)
    def convert_to_pillow(self):
        image = PIL.Image()  # Code to create PIL image object here
        return PillowImage(image)

Builtin operations¶

Here’s a full list of operations provided by Willow out of the box:

get_size()¶

Returns the size of the image as a tuple of two integers:

width, height = image.get_size()

get_frame_count()¶

Returns the number of frames in an animated image:

number_of_frames = image.get_frame_count()

has_alpha()¶

Returns True if the image has an alpha channel.

if image.has_alpha():
    # Image has alpha

has_animation()¶

Returns True if the image is animated.

if image.has_animation():
    # Image has animation

resize(size)¶

(supported natively for SVG, Pillow/Wand required for others)

Stretches the image to fit the specified size. Size must be a sequence of two integers:

# Resize the image to 100x100 pixels
resized_image = source_image.resize((100, 100))

crop(region)¶

(supported natively for SVG, Pillow/Wand required for others)

Cuts out the specified region of the image. The region must be a sequence of four integers (left, top, right, bottom):

# Cut out a square from the middle of the image
cropped_image = source_image.resize((100, 100, 200, 200))

If the crop rectangle overlaps the image boundaries, it will be reduced to fit within those boundaries, resulting in an output image smaller than specified. If the crop rectangle is entirely outside the image, or the coordinates are out of range in any other way (such as a left coordinate greater than the right coordinate), this throws a willow.image.BadImageOperationError (a subclass of ValueError).

set_background_color_rgb(color)¶

(Pillow/Wand only)

If the image has an alpha channel, this will add a background color using the alpha channel as a mask. The alpha channel will be removed from the resulting image.

The background color must be specified as a tuple of three integers with values between 0 - 255.

This operation will convert the image to RGB format, but will not do anything if there is not an alpha channel.

# Set the background color of the image to white
image = source_image.set_background_color_rgb((255, 255, 255))

transform_colorspace_to_srgb(rendering_intent=0)¶

(Pillow only)

Note: This operation has no effect if the image does not have an embedded ICC color profile.

Transforms the colors of the image to fit inside sRGB color gamut using data from the embedded ICC profile. The resulting image will always be in RGB format (or RGBA for images with transparency) and will have a small generic sRGB ICC profile embedded.

A large number of devices lack the capability to display images in color spaces other than sRGB and will automatically squash the colors to fit inside sRGB gamut. In order to do this accurately, the device uses the embedded ICC profile. You can use this operation to do the same thing upfront and save on image size by replacing the (large) embedded profile with a small generic sRGB profile. Keep in mind that this operation is lossy, devices that do support wider color gamuts, like DCI-P3 or Adobe RGB, will not be able to display the image in its original colors if the original colors were outside of sRGB gamut.

The rendering_intent parameter specifies the rendering intent to use. It defaults to 0 (perceptual). This controls how out-of-gamut colors are handled.

It can be one of the following values:

0 - Perceptual (default)
1 - Relative colorimetric
2 - Saturation
3 - Absolute colorimetric

image = image.transform_colorspace_to_srgb()

auto_orient()¶

(Pillow/Wand only)

Some JPEG files have orientation data in an EXIF tag that needs to be applied to the image. This method applies this orientation to the image (it is a no-op for other image formats).

This should be run before performing any other image operations.

image = image.auto_orient()

detect_features()¶

(OpenCV only)

Uses OpenCV to find the most prominent corners in the image. Useful for detecting interesting features for cropping against.

Returns a list of two integer tuples containing the coordinates of each point on the image

points = image.detect_features()

detect_faces(cascade_filename)¶

(OpenCV only)

Uses OpenCV’s cascade classification to detect faces in the image.

By default the haarcascade_frontalface_alt2.xml (provided by OpenCV) cascade file is used. You can specify the filename to a different cascade file in the first parameter.

Returns a list of four integer tuples containing the left, top, right, bottom locations of each face detected in the image.

faces = image.detect_faces()

save_as_jpeg(file, quality=85, optimize=False)¶

(Pillow/Wand only)

Saves the image to the specified file-like object in JPEG format.

Note: If the image has an alpha channel, this operation may raise an exception or save a broken image (depending on the backend being used). To resolve this, use the set_background_color_rgb() method to replace the alpha channel with a solid background color before saving as JPEG.

Returns a JPEGImageFile wrapping the file.

with open('out.jpg', 'wb') as f:
    image.save_as_jpeg(f)

save_as_png(file, optimize=False)¶

(Pillow/Wand only)

Saves the image to the specified file-like object in PNG format.

Returns a PNGImageFile wrapping the file.

with open('out.png', 'wb') as f:
    image.save_as_png(f)

save_as_gif(file)¶

(Pillow/Wand only)

Saves the image to the specified file-like object in GIF format.

returns a GIFImageFile wrapping the file.

with open('out.gif', 'wb') as f:
    image.save_as_gif(f)

save_as_webp(file, quality=80, lossless=False)¶

(Pillow/Wand only)

Saves the image to the specified file-like object in WEBP format.

returns a WebPImageFile wrapping the file.

with open('out.webp', 'wb') as f:
    image.save_as_webp(f)

save_as_heic(file, quality=80, lossless=False)¶

(Pillow only; requires the pillow-heif library)

Saves the image to the specified file-like object in HEIF format.

returns a HeicImageFile wrapping the file.

with open('out.heic', 'wb') as f:
    image.save_as_heic(f)

save_as_avif(file, quality=80, lossless=False)¶

(requires the pillow-heif library)

Saves the image to the specified file-like object in AVIF format. When saving with lossless=True, the quality value is set to -1 and chroma to 444.

returns a AvifImageFile wrapping the file.

with open('out.avif', 'wb') as f:
    image.save_as_avif(f)

save_as_svg(file)¶

(SVG images only)

Saves the image to the specified file-like object in SVG format.

returns a SvgImageFile wrapping the file.

with open('out.svg', 'w') as f:
    image.save_as_svg(f)

save_as_ico(file)¶

Saves the image to the specified file-like object in ICO format.

returns a IcoImageFile wrapping the file.

with open('out.ico', 'w') as f:
    image.save_as_ico(f)

get_pillow_image()¶

(Pillow only)

Returns a PIL.Image object for the specified image. This may be useful for reusing existing code that requires a Pillow image.

do_thing(image.get_pillow_image())

You can convert a PIL.Image object back into a Willow Image using the PillowImage class:

import PIL.Image
from willow.plugins.pillow import PillowImage

pillow_image = PIL.Image.open('test.jpg')
image = PillowImage(pillow_image)

# Now you can use any Willow operation on that image
faces = image.detect_faces()

get_wand_image()¶

(Wand only)

Returns a Wand.Image object for the specified image. This may be useful for reusing existing code that requires a Wand image.

do_thing(image.get_wand_image())

You can convert a Wand.Image object back into a Willow Image using the WandImage class:

from wand.image import Image
from willow.plugins.wand import WandImage

# wand_image is an instance of Wand.Image
wand_image = Image(filename='pikachu.png')
image = WandImage(wand_image)

# Now you can use any Willow operation on that image
faces = image.detect_faces()

Reference¶

The Image class¶

Builtin operations¶

The `Image` class¶