Registry / ai-ml / blend-modes

blend-modes

JSON →
library2.2.0pypypi✓ verified 85d ago

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.

pip install blend-modes
INSTALL
IMPORT
SIG · BLEND-MODES
B
blend-modes
ai-mlpythonv2.2.0
Install
3.6s avg
Import
260ms
Disk
89MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.256s · 89.4MB
glibc
py 3.103.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')
Debug
Known issues
breakingThe 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`.
affects: >=2.0.0
gotchaInput 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)`.
affects: All versions
gotchaBoth 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.
affects: All versions
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).
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)
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.
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.
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.
Agent activity
33 hits · last 30 days
node
27
Amazon
1
OpenAI (training)
1
Resources
blend-modes — pip install blend-modes · libregistry