Blend Modes for Images

2025 · active · verified Wed Apr 15

BlendModes is a Python library that allows you to apply various blending modes to a background and foreground image, similar to those found in image editing software. It currently supports version 2025 and releases new major versions annually, with minor patches as needed, typically in January/February.

Warnings

breaking The `imagetools.renderWAlphaOffset` function was removed in version 2024.1. Its functionality for handling image offsets is now integrated directly into the `blendLayers` function via the `offsets` parameter.
Fix: Migrate usage to `blendLayers(..., offsets=(x, y))`. Review the `blendLayers` signature for new parameters.
gotcha When using `blendLayers`, if the `background` image is smaller than the `foreground` image, portions of the `foreground` image that extend beyond the `background` dimensions will be cut off.
Fix: Ensure your `background` image is sufficiently large to accommodate the `foreground` image at the desired `offsets`, or pre-process/crop the `foreground` image.
gotcha For consistent and expected blending results, both `background` and `foreground` images passed to `blendLayers` should be in 'RGBA' mode. Other modes might lead to unexpected color transformations or errors.
Fix: Always convert your `PIL.Image.Image` objects to 'RGBA' mode before blending, e.g., `image.convert('RGBA')`.

Install

pip install blendmodes Install latest version

Imports

blendLayers
```
from blendmodes import blendLayers
```
BlendType
```
from blendmodes import BlendType
```

Quickstart

This quickstart demonstrates how to create two Pillow images, then blend them together using a specified `BlendType` and opacity, with an optional offset. The result is a new `PIL.Image.Image` object.

from PIL import Image
from blendmodes import blendLayers, BlendType

# Create dummy images for demonstration. In a real application,
# load images from files and ensure they are in 'RGBA' mode.
background_img = Image.new("RGBA", (400, 300), (255, 0, 0, 255)) # Red background
foreground_img = Image.new("RGBA", (200, 150), (0, 0, 255, 128)) # Semi-transparent blue foreground

# Example: Place foreground at offset (50, 50) on background
# The blendLayers function handles positioning by drawing the foreground
# onto a canvas, then applying the blend mode.
# For simpler examples, ensure foreground is smaller or equal to background
# or use offsets carefully.

# Blend the images using 'multiply' mode with 75% opacity and an offset
blended_img = blendLayers(
    background=background_img,
    foreground=foreground_img,
    blendType=BlendType.MULTIPLY,
    opacity=0.75,
    offsets=(50, 50)
)

# Display or save the result
# blended_img.save("blended_image.png")
print(f"Blended image created with size: {blended_img.size} and mode: {blended_img.mode}")
# blended_img.show() # Uncomment to display the image graphically

view raw JSON →