Blend Modes for Image Processing

2.2.0 · active · verified Thu Apr 16

The `blend-modes` package provides a Python implementation of various blend modes commonly found in graphics software like Adobe Photoshop or GIMP. It enables blending different images or image layers to create a wide array of visual effects. The library is optimized for performance through NumPy vectorization. The current version is 2.2.0, released on October 16, 2024, indicating an active development and release cadence.

Common errors

```
TypeError: img_in must be a 3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0
```
cause Input image array is not of float type or does not have the expected 3 dimensions (height, width, channels) with 4 channels (RGBA).

fix Convert your image array to `dtype=float` and ensure it has 4 channels (RGBA), even if the alpha channel is opaque. Example: `my_image.astype(float)` and ensure shape is `(H, W, 4)`.
```
ValueError: operands could not be broadcast together with shapes (H1,W1,4) (H2,W2,4)
```
cause The background and foreground images have different `height` or `width` dimensions, preventing element-wise operations.

fix Before blending, ensure both `bg_img` and `fg_img` have the exact same `(height, width)` dimensions. Resizing one or both images may be necessary.
```
Image shows unexpected blending behavior when using 'overlay' blend mode.
```
cause Prior to version 2.0.0, the `overlay` blend mode's implementation was identical to `soft_light`. If you updated from an older version, the `overlay` behavior has changed to a standard implementation.

fix If you intend the pre-2.0.0 `overlay` behavior, use `blend_modes.soft_light` instead. If you prefer the new standard `overlay` behavior, no change is needed, but be aware of the visual difference.

Warnings

breaking The implementation of the `overlay` blend mode was significantly changed in version 2.0.0. Previously, it behaved identically to `soft_light`. Post 2.0.0, it aligns with the standard definition (e.g., from Wikipedia). If you relied on the old behavior, `soft_light` should be used for backward compatibility.
Fix: For the old `overlay` behavior, use `blend_modes.soft_light` instead. For the new standard `overlay` behavior, continue using `blend_modes.overlay`.
gotcha Input images (background and foreground) must be NumPy arrays of `float` dtype. Pixel values must be in the range `0.0` to `255.0`.
Fix: Ensure images are converted to `numpy.ndarray` with `dtype=float` and pixel values scaled to `0.0-255.0` before passing to blend functions. E.g., `image_uint8.astype(float)`.
gotcha Both input images (background and foreground) must have identical dimensions and shape `(height, width, 4)` for RGBA channels.
Fix: Resize or crop images to match dimensions and ensure they have 4 channels (RGBA) before blending. An alpha channel is mandatory even if fully opaque.

Install

pip install blend-modes PyPI
conda install -c conda-forge blend_modes Conda-forge

Imports

soft_light
```
from blend_modes import soft_light
```
Blend mode functions are imported directly.
multiply
```
from blend_modes import multiply
```
Other blend modes like 'multiply', 'addition', 'overlay' are similarly imported.
addition
```
from blend_modes import addition
```

Quickstart

This quickstart demonstrates how to prepare two dummy RGBA images (background and foreground) as NumPy float arrays (0.0-255.0) and apply the `soft_light` blend mode. The output is also a NumPy float array in the same format. In a real application, image loading and saving would typically be handled by libraries like Pillow or OpenCV.

import numpy as np
from blend_modes import soft_light

# Simulate loading images (typically done with Pillow or OpenCV)
# Images must be float arrays (0.0-255.0) and have shape (H, W, 4) for RGBA.
height, width = 100, 150

# Background image: a gradient
bg_img = np.zeros((height, width, 4), dtype=float)
bg_img[:, :, 0] = np.linspace(0, 255, width) # Red gradient
bg_img[:, :, 1] = np.linspace(0, 255, height).reshape(-1, 1) # Green gradient
bg_img[:, :, 2] = 100.0 # Blue channel constant
bg_img[:, :, 3] = 255.0 # Full opacity

# Foreground image: a circle
fg_img = np.zeros((height, width, 4), dtype=float)
y, x = np.ogrid[0:height, 0:width]
center_y, center_x = height // 2, width // 2
radius = min(height, width) // 3
mask = (x - center_x)**2 + (y - center_y)**2 < radius**2
fg_img[mask, 0] = 255.0 # Red circle
fg_img[mask, 3] = 150.0 # Partial opacity for foreground

opacity = 0.7 # Opacity of the foreground layer (0.0 to 1.0)

# Perform blending
blended_img = soft_light(bg_img, fg_img, opacity)

print("Blended image shape:", blended_img.shape)
print("Blended image min value:", blended_img.min())
print("Blended image max value:", blended_img.max())
# In a real application, you would save or display blended_img,
# e.g., using Pillow: Image.fromarray(blended_img.astype(np.uint8)).save('output.png')

view raw JSON →