ImageChops (“Channel Operations”) Module

The ImageChops module contains a number of arithmetical imageoperations, called channel operations (“chops”). These can be used for variouspurposes, 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 returns a newimage. Unless otherwise noted, the result of a channel operation is alwaysclipped to the range 0 to MAX (which is 255 for all modes supported by theoperations in this module).

  • PIL.ImageChops.add(image1, image2, scale=1.0, offset=0)[source]
  • Adds two images, dividing the result by scale and adding theoffset. If omitted, scale defaults to 1.0, and offset to 0.0.At least one of the images must have mode “1”.
  1. out = ((image1 + image2) / scale + offset)

Return type:Image

  • PIL.ImageChops.addmodulo(_image1, image2)[source]
  • Add two images, without clipping the result. At least one of the imagesmust have mode “1”.
  1. out = ((image1 + image2) % MAX)

Return type:Image

  • PIL.ImageChops.blend(image1, image2, alpha)[source]
  • Blend images using constant transparency weight. Alias forPIL.Image.Image.blend().

Return type:Image

  • PIL.ImageChops.composite(image1, image2, mask)[source]
  • Create composite using transparency mask. Alias forPIL.Image.Image.composite().

Return type:Image

  • PIL.ImageChops.constant(image, value)[source]
  • Fill a channel with a given grey level.

Return type:Image

  • PIL.ImageChops.darker(image1, image2)[source]
  • Compares the two images, pixel by pixel, and returns a new image containingthe darker values. At least one of the images must have mode “1”.
  1. out = min(image1, image2)

Return type:Image

  • PIL.ImageChops.difference(image1, image2)[source]
  • Returns the absolute value of the pixel-by-pixel difference between the twoimages. At least one of the images must have mode “1”.
  1. out = abs(image1 - image2)

Return type:Image

Return type:Image

  • PIL.ImageChops.invert(image)[source]
  • Invert an image (channel).
  1. out = MAX - image

Return type:Image

  • PIL.ImageChops.lighter(image1, image2)[source]
  • Compares the two images, pixel by pixel, and returns a new image containingthe lighter values. At least one of the images must have mode “1”.
  1. out = max(image1, image2)

Return type:Image

  • PIL.ImageChops.logicaland(_image1, image2)[source]
  • Logical AND between two images. At least one of the images must havemode “1”.
  1. out = ((image1 and image2) % MAX)

Return type:Image

  • PIL.ImageChops.logicalor(_image1, image2)[source]
  • Logical OR between two images. At least one of the images must havemode “1”.
  1. out = ((image1 or image2) % MAX)

Return type:Image

  • PIL.ImageChops.logicalxor(_image1, image2)[source]
  • Logical XOR between two images. At least one of the images must havemode “1”.
  1. out = ((bool(image1) != bool(image2)) % MAX)

Return type:Image

  • PIL.ImageChops.multiply(image1, image2)[source]
  • Superimposes two images on top of each other.

If you multiply an image with a solid black image, the result is black. Ifyou multiply with a solid white image, the image is unaffected. At leastone of the images must have mode “1”.

  1. out = image1 * image2 / MAX

Return type:Image

  • PIL.ImageChops.softlight(_image1, image2)[source]
  • Superimposes two images on top of each other using the Soft Light algorithm

Return type:Image

  • PIL.ImageChops.hardlight(_image1, image2)[source]
  • Superimposes two images on top of each other using the Hard Light algorithm

Return type:Image

  • PIL.ImageChops.overlay(image1, image2)[source]
  • Superimposes two images on top of each other using the Overlay algorithm

Return type:Image

  • PIL.ImageChops.offset(image, xoffset, yoffset=None)
  • Returns a copy of the image where data has been offset by the givendistances. Data wraps around the edges. If yoffset is omitted, itis assumed to be equal to xoffset.
  • PIL.ImageChops.screen(image1, image2)[source]
  • Superimposes two inverted images on top of each other. At least one of theimages must have mode “1”.
  1. out = MAX - ((MAX - image1) * (MAX - image2) / MAX)

Return type:Image

  • PIL.ImageChops.subtract(image1, image2, scale=1.0, offset=0)[source]
  • Subtracts two images, dividing the result by scale and adding the offset.If omitted, scale defaults to 1.0, and offset to 0.0. At least one of theimages must have mode “1”.
  1. out = ((image1 - image2) / scale + offset)

Return type:Image

  • PIL.ImageChops.subtractmodulo(_image1, image2)[source]
  • Subtract two images, without clipping the result. At least one of theimages must have mode “1”.
  1. out = ((image1 - image2) % MAX)

Return type:Image