Blend
The Blend module provides GPU-accelerated layer compositing with multiple blend modes.
All blend operations modify the base image in-place by compositing the overlay on top of it.
Positioning
Anchors
Position overlays relative to common anchor points. By default, anchor='top-left', which makes offset_x and offset_y behave as absolute pixel coordinates—just like standard graphics APIs.
Example:
Available anchors: 'top-left', 'top-center', 'top-right', 'center-left', 'center', 'center-right', 'bottom-left', 'bottom-center', 'bottom-right'
Offsets
Add pixel offsets from the anchor point for fine-tuning.
Example:
Blend Modes
Normal
Standard alpha blending (Porter-Duff over operation).
Example:
from pyimagecuda import Image, Fill, Blend, save
base = Image(800, 600)
overlay = Image(400, 300)
c1 = (0.2, 0.2, 0.3, 1.0)
c2 = (0.4, 0.3, 0.5, 1.0)
c3 = (1.0, 0.5, 0.0, 0.8)
c4 = (1.0, 0.0, 0.5, 0.8)
Fill.gradient(base, c1, c2, 'radial')
Fill.gradient(overlay, c3, c4, 'horizontal')
Blend.normal(base, overlay, anchor='center')
save(base, 'output.png')
Use for: Standard layer compositing, logos, overlays.
Multiply
Darkens the image by multiplying color values.
Example:
from pyimagecuda import Image, Fill, Blend, save
base = Image(800, 600)
overlay = Image(400, 300)
c1 = (0.2, 0.2, 0.3, 1.0)
c2 = (0.4, 0.3, 0.5, 1.0)
c3 = (1.0, 0.5, 0.0, 0.8)
c4 = (1.0, 0.0, 0.5, 0.8)
Fill.gradient(base, c1, c2, 'radial')
Fill.gradient(overlay, c3, c4, 'horizontal')
Blend.multiply(base, overlay, anchor='center')
save(base, 'output.png')
Use for: Shadows, darkening effects, texture overlays.
Screen
Lightens the image (inverse of multiply).
Example:
from pyimagecuda import Image, Fill, Blend, save
base = Image(800, 600)
overlay = Image(400, 300)
c1 = (0.2, 0.2, 0.3, 1.0)
c2 = (0.4, 0.3, 0.5, 1.0)
c3 = (1.0, 0.5, 0.0, 0.8)
c4 = (1.0, 0.0, 0.5, 0.8)
Fill.gradient(base, c1, c2, 'radial')
Fill.gradient(overlay, c3, c4, 'horizontal')
Blend.screen(base, overlay, anchor='center')
save(base, 'output.png')
Use for: Highlights, light effects, glows.
Add
Additive blending (colors add up, clamped to 1.0).
Example:
from pyimagecuda import Image, Fill, Blend, save
base = Image(800, 600)
overlay = Image(400, 300)
c1 = (0.2, 0.2, 0.3, 1.0)
c2 = (0.4, 0.3, 0.5, 1.0)
c3 = (1.0, 0.5, 0.0, 0.8)
c4 = (1.0, 0.0, 0.5, 0.8)
Fill.gradient(base, c1, c2, 'radial')
Fill.gradient(overlay, c3, c4, 'horizontal')
Blend.add(base, overlay, anchor='center')
save(base, 'output.png')
Use for: Light effects, lens flares, glowing elements.
Overlay
Combines Multiply and Screen modes to increase contrast. Darker values become darker, lighter values become lighter.
Example:
from pyimagecuda import Image, Fill, Blend, save
base = Image(800, 600)
overlay = Image(400, 300)
c1 = (0.2, 0.2, 0.3, 1.0)
c2 = (0.4, 0.3, 0.5, 1.0)
c3 = (1.0, 0.5, 0.0, 0.8)
c4 = (1.0, 0.0, 0.5, 0.8)
Fill.gradient(base, c1, c2, 'radial')
Fill.gradient(overlay, c3, c4, 'horizontal')
Blend.overlay(base, overlay, anchor='center')
save(base, 'output.png')
Use for: Increasing contrast, texture overlays, dramatic effects.
Soft Light
Creates a gentle lighting effect, like shining a diffuse spotlight on the image. Similar to Overlay but more subtle.
Example:
from pyimagecuda import Image, Fill, Blend, save
base = Image(800, 600)
overlay = Image(400, 300)
c1 = (0.2, 0.2, 0.3, 1.0)
c2 = (0.4, 0.3, 0.5, 1.0)
c3 = (1.0, 0.5, 0.0, 0.8)
c4 = (1.0, 0.0, 0.5, 0.8)
Fill.gradient(base, c1, c2, 'radial')
Fill.gradient(overlay, c3, c4, 'horizontal')
Blend.soft_light(base, overlay, anchor='center')
save(base, 'output.png')
Use for: Subtle lighting effects, gentle color adjustments, photo enhancement.
Hard Light
Creates a strong lighting effect, like shining a harsh spotlight on the image. More dramatic than Overlay.
Example:
from pyimagecuda import Image, Fill, Blend, save
base = Image(800, 600)
overlay = Image(400, 300)
c1 = (0.2, 0.2, 0.3, 1.0)
c2 = (0.4, 0.3, 0.5, 1.0)
c3 = (1.0, 0.5, 0.0, 0.8)
c4 = (1.0, 0.0, 0.5, 0.8)
Fill.gradient(base, c1, c2, 'radial')
Fill.gradient(overlay, c3, c4, 'horizontal')
Blend.hard_light(base, overlay, anchor='center')
save(base, 'output.png')
Use for: Strong lighting effects, dramatic contrast, vivid color overlays.
Mask
Applies an image as an alpha mask to the base image, controlling transparency.
Parameters: - mode (str): 'luminance' (default) uses brightness of mask image, 'alpha' uses alpha channel
Example:
from pyimagecuda import Image, Fill, Blend, save
BASE_W, BASE_H = 800, 600
MASK_HOLE_W, MASK_HOLE_H = 200, 100
c1 = (0.2, 0.2, 0.3, 1.0)
c2 = (0.4, 0.3, 0.5, 1.0)
white = (1.0, 1.0, 1.0, 1.0)
black = (0.0, 0.0, 0.0, 1.0)
with Image(BASE_W, BASE_H) as base:
Fill.gradient(base, c1, c2, 'radial')
with Image(BASE_W, BASE_H) as mask:
Fill.color(mask, white)
with Image(400, 300) as hole_shape:
Fill.color(hole_shape, black)
Blend.normal(mask,
hole_shape,
anchor='center')
Blend.mask(base, mask)
save(base, "output.png")
- Use for: Revealing parts of an image, creating vignettes, complex alpha compositing.
- How Works: The mask image's pixel values determine the transparency of the base image. White areas are fully opaque, black areas are fully transparent, and gray areas are partially transparent.
Parameters
All blend modes (except mask) share the same parameters:
base(Image): Base layer (modified in-place)overlay(Image): Layer to composite on topanchor(str): Position anchor point (default:'top-left')offset_x(int): Horizontal offset from anchor in pixels (default: 0)offset_y(int): Vertical offset from anchor in pixels (default: 0)opacity(float): Blend opacity from 0.0 (transparent) to 1.0 (opaque) (default: 1.0)
Mask-specific parameters:
base(Image): Base layer (modified in-place)mask(Image): Mask image to applyanchor(str): Position anchor point (default:'top-left')offset_x(int): Horizontal offset from anchor in pixels (default: 0)offset_y(int): Vertical offset from anchor in pixels (default: 0)mode(str):'luminance'or'alpha'(default:'luminance')