ImageChops (“channel operations”) module

The ImageChops module contains a number of arithmetical image operations, called channel operations (“chops”). These can be used for various purposes, including special effects, image compositions, algorithmic painting, and more.

For more pre-made operations, see ImageOps.

At this time, most channel operations are only implemented for 8-bit images (e.g. “L” and “RGB”).

Functions

Most channel operations take one or two image arguments and return a new image. Unless otherwise noted, the result of a channel operation is always clipped to the range 0 to MAX (which is 255 for all modes supported by the operations in this module).

PIL.ImageChops.add(image1: Image, image2: Image, scale: float = 1.0, offset: float = 0) → Image

Adds two images, dividing the result by scale and adding the offset. If omitted, scale defaults to 1.0, and offset to 0.0.

out = ((image1 + image2) / scale + offset)

PIL.ImageChops.add_modulo(image1: Image, image2: Image) → Image

Add two images, without clipping the result.

out = ((image1 + image2) % MAX)

PIL.ImageChops.blend(image1: Image, image2: Image, alpha: float) → Image

Blend images using constant transparency weight.

Alias for PIL.Image.blend().

PIL.ImageChops.composite(image1: Image, image2: Image, mask: Image) → Image

Create composite using transparency mask.

Alias for PIL.Image.composite().

PIL.ImageChops.constant(image: Image, value: int) → Image

Fill a channel with a given gray level.

PIL.ImageChops.darker(image1: Image, image2: Image) → Image

Compares the two images, pixel by pixel, and returns a new image containing the darker values.

out = min(image1, image2)

PIL.ImageChops.difference(image1: Image, image2: Image) → Image

Returns the absolute value of the pixel-by-pixel difference between the two images.

out = abs(image1 - image2)

PIL.ImageChops.duplicate(image: Image) → Image

Copy a channel. Alias for PIL.Image.Image.copy().

PIL.ImageChops.invert(image: Image) → Image

Invert an image (channel).

out = MAX - image

PIL.ImageChops.lighter(image1: Image, image2: Image) → Image

Compares the two images, pixel by pixel, and returns a new image containing the lighter values.

out = max(image1, image2)

PIL.ImageChops.logical_and(image1: Image, image2: Image) → Image

Logical AND between two images.

Both of the images must have mode “1”. If you would like to perform a logical AND on an image with a mode other than “1”, try multiply() instead, using a black-and-white mask as the second image.

out = ((image1 and image2) % MAX)

PIL.ImageChops.logical_or(image1: Image, image2: Image) → Image

Logical OR between two images.

Both of the images must have mode “1”.

out = ((image1 or image2) % MAX)

PIL.ImageChops.logical_xor(image1: Image, image2: Image) → Image

Logical XOR between two images.

Both of the images must have mode “1”.

out = ((bool(image1) != bool(image2)) % MAX)

PIL.ImageChops.multiply(image1: Image, image2: Image) → Image

Superimposes two images on top of each other.

If you multiply an image with a solid black image, the result is black. If you multiply with a solid white image, the image is unaffected.

out = image1 * image2 / MAX

PIL.ImageChops.soft_light(image1: Image, image2: Image) → Image

Superimposes two images on top of each other using the Soft Light algorithm

PIL.ImageChops.hard_light(image1: Image, image2: Image) → Image

Superimposes two images on top of each other using the Hard Light algorithm

PIL.ImageChops.overlay(image1: Image, image2: Image) → Image

Superimposes two images on top of each other using the Overlay algorithm

PIL.ImageChops.offset(image: Image, xoffset: int, yoffset: int | None = None) → Image

Returns a copy of the image where data has been offset by the given distances. Data wraps around the edges. If yoffset is omitted, it is assumed to be equal to xoffset.

Parameters:

• image – Input image.

• xoffset – The horizontal distance.

• yoffset – The vertical distance. If omitted, both distances are set to the same value.

PIL.ImageChops.screen(image1: Image, image2: Image) → Image

Superimposes two inverted images on top of each other.

out = MAX - ((MAX - image1) * (MAX - image2) / MAX)

PIL.ImageChops.subtract(image1: Image, image2: Image, scale: float = 1.0, offset: float = 0) → Image

Subtracts two images, dividing the result by scale and adding the offset. If omitted, scale defaults to 1.0, and offset to 0.0.

out = ((image1 - image2) / scale + offset)

PIL.ImageChops.subtract_modulo(image1: Image, image2: Image) → Image

Subtract two images, without clipping the result.

out = ((image1 - image2) % MAX)