{"id":7986,"library":"blend-modes","title":"Blend Modes for Image Processing","description":"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.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/flrs/blend_modes","tags":["image processing","blend modes","graphics","numpy","computer vision"],"install":[{"cmd":"pip install blend-modes","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge blend_modes","lang":"bash","label":"Conda-forge"}],"dependencies":[{"reason":"Required for image array manipulation and core blending logic.","package":"numpy","optional":false},{"reason":"Commonly used for loading/saving images, but not a direct dependency of blend-modes itself.","package":"Pillow","optional":true},{"reason":"Commonly used for loading/saving images, but not a direct dependency of blend-modes itself.","package":"opencv-python","optional":true}],"imports":[{"note":"Blend mode functions are imported directly.","symbol":"soft_light","correct":"from blend_modes import soft_light"},{"note":"Other blend modes like 'multiply', 'addition', 'overlay' are similarly imported.","symbol":"multiply","correct":"from blend_modes import multiply"},{"symbol":"addition","correct":"from blend_modes import addition"}],"quickstart":{"code":"import numpy as np\nfrom blend_modes import soft_light\n\n# Simulate loading images (typically done with Pillow or OpenCV)\n# Images must be float arrays (0.0-255.0) and have shape (H, W, 4) for RGBA.\nheight, width = 100, 150\n\n# Background image: a gradient\nbg_img = np.zeros((height, width, 4), dtype=float)\nbg_img[:, :, 0] = np.linspace(0, 255, width) # Red gradient\nbg_img[:, :, 1] = np.linspace(0, 255, height).reshape(-1, 1) # Green gradient\nbg_img[:, :, 2] = 100.0 # Blue channel constant\nbg_img[:, :, 3] = 255.0 # Full opacity\n\n# Foreground image: a circle\nfg_img = np.zeros((height, width, 4), dtype=float)\ny, x = np.ogrid[0:height, 0:width]\ncenter_y, center_x = height // 2, width // 2\nradius = min(height, width) // 3\nmask = (x - center_x)**2 + (y - center_y)**2 < radius**2\nfg_img[mask, 0] = 255.0 # Red circle\nfg_img[mask, 3] = 150.0 # Partial opacity for foreground\n\nopacity = 0.7 # Opacity of the foreground layer (0.0 to 1.0)\n\n# Perform blending\nblended_img = soft_light(bg_img, fg_img, opacity)\n\nprint(\"Blended image shape:\", blended_img.shape)\nprint(\"Blended image min value:\", blended_img.min())\nprint(\"Blended image max value:\", blended_img.max())\n# In a real application, you would save or display blended_img,\n# e.g., using Pillow: Image.fromarray(blended_img.astype(np.uint8)).save('output.png')","lang":"python","description":"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."},"warnings":[{"fix":"For the old `overlay` behavior, use `blend_modes.soft_light` instead. For the new standard `overlay` behavior, continue using `blend_modes.overlay`.","message":"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.","severity":"breaking","affected_versions":">=2.0.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)`.","message":"Input images (background and foreground) must be NumPy arrays of `float` dtype. Pixel values must be in the range `0.0` to `255.0`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Both input images (background and foreground) must have identical dimensions and shape `(height, width, 4)` for RGBA channels.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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)`.","cause":"Input image array is not of float type or does not have the expected 3 dimensions (height, width, channels) with 4 channels (RGBA).","error":"TypeError: img_in must be a 3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0"},{"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.","cause":"The background and foreground images have different `height` or `width` dimensions, preventing element-wise operations.","error":"ValueError: operands could not be broadcast together with shapes (H1,W1,4) (H2,W2,4)"},{"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.","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.","error":"Image shows unexpected blending behavior when using 'overlay' blend mode."}]}