# `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 returns 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)

  Return type:

    `Image`

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

  Add two images, without clipping the result.

      out = ((image1 + image2) % MAX)

  Return type:

    `Image`

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

  Blend images using constant transparency weight. Alias for `PIL.Image.blend()`.

  Return type:

    `Image`

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

  Create composite using transparency mask. Alias for `PIL.Image.composite()`.

  Return type:

    `Image`

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

  Fill a channel with a given gray level.

  Return type:

    `Image`

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)

  Return type:

    `Image`

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)

  Return type:

    `Image`

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

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

  Return type:

    `Image`

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

  Invert an image (channel).

      out = MAX - image

  Return type:

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

  Return type:

    `Image`

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)

  Return type:

    `Image`

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)

  Return type:

    `Image`

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)

  Return type:

    `Image`

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

  Return type:

    `Image`

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

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

  Return type:

    `Image`

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

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

  Return type:

    `Image`

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

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

  Return type:

    `Image`

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.

  Return type:

    `Image`

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

  Superimposes two inverted images on top of each other.

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

  Return type:

    `Image`

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)

  Return type:

    `Image`

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

  Subtract two images, without clipping the result.

      out = ((image1 - image2) % MAX)

  Return type:

    `Image`