{"id":6549,"library":"blendmodes","title":"Blend Modes for Images","description":"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.","status":"active","version":"2025","language":"en","source_language":"en","source_url":"https://github.com/FHPythonUtils/BlendModes","tags":["image processing","blend modes","pillow","image manipulation","graphics"],"install":[{"cmd":"pip install blendmodes","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for image manipulation and representation (PIL.Image.Image objects).","package":"Pillow","optional":false}],"imports":[{"symbol":"blendLayers","correct":"from blendmodes import blendLayers"},{"symbol":"BlendType","correct":"from blendmodes import BlendType"}],"quickstart":{"code":"from PIL import Image\nfrom blendmodes import blendLayers, BlendType\n\n# Create dummy images for demonstration. In a real application,\n# load images from files and ensure they are in 'RGBA' mode.\nbackground_img = Image.new(\"RGBA\", (400, 300), (255, 0, 0, 255)) # Red background\nforeground_img = Image.new(\"RGBA\", (200, 150), (0, 0, 255, 128)) # Semi-transparent blue foreground\n\n# Example: Place foreground at offset (50, 50) on background\n# The blendLayers function handles positioning by drawing the foreground\n# onto a canvas, then applying the blend mode.\n# For simpler examples, ensure foreground is smaller or equal to background\n# or use offsets carefully.\n\n# Blend the images using 'multiply' mode with 75% opacity and an offset\nblended_img = blendLayers(\n    background=background_img,\n    foreground=foreground_img,\n    blendType=BlendType.MULTIPLY,\n    opacity=0.75,\n    offsets=(50, 50)\n)\n\n# Display or save the result\n# blended_img.save(\"blended_image.png\")\nprint(f\"Blended image created with size: {blended_img.size} and mode: {blended_img.mode}\")\n# blended_img.show() # Uncomment to display the image graphically\n","lang":"python","description":"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."},"warnings":[{"fix":"Migrate usage to `blendLayers(..., offsets=(x, y))`. Review the `blendLayers` signature for new parameters.","message":"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.","severity":"breaking","affected_versions":">=2024.1"},{"fix":"Ensure your `background` image is sufficiently large to accommodate the `foreground` image at the desired `offsets`, or pre-process/crop the `foreground` image.","message":"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.","severity":"gotcha","affected_versions":">=2024.1"},{"fix":"Always convert your `PIL.Image.Image` objects to 'RGBA' mode before blending, e.g., `image.convert('RGBA')`.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}