Install & Compatibility
Where this runs
tested against v2.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.256s · 89.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.6s · import 0.263s · 86MB
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
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')
Errors
Common errors & fixes
TypeError: img_in must be a 3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0
Input image array is not of float type or does not have the expected 3 dimensions (height, width, channels) with 4 channels (RGBA).
fixConvert 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)
The background and foreground images have different `height` or `width` dimensions, preventing element-wise operations.
fixBefore 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.
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.
fixIf 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.
Upgrade
Version history
2.2.0latest on PyPI · released Oct 16, 2024
Audit
Dependencies
numpyrequiredRequired for image array manipulation and core blending logic.
PillowoptionalCommonly used for loading/saving images, but not a direct dependency of blend-modes itself.
opencv-pythonoptionalCommonly used for loading/saving images, but not a direct dependency of blend-modes itself.