BlendModes

BlendModes is a Python library for compositing two images using the same layer blend modes found in professional photo editors such as Photoshop, GIMP, and Paint.NET. It exposes over 30 separable and non-separable blend functions - multiply, screen, overlay, soft light, hue, saturation, luminosity, and more - through a single high-level function that takes a background image, a foreground image, and a blend type.

Built on NumPy for vectorized pixel math and Pillow for image I/O, it works directly with RGBA images or raw arrays and includes opacity control and an optional command-line interface for blending files from the terminal.

What You Get

• A single blendLayers entry point that composites two RGBA images with a chosen blend mode and opacity
• Over 30 blend modes exposed through a typed BlendType enum, including separable and non-separable (hue, saturation, colour, luminosity) modes
• An array-level blendLayersArray API for working directly with NumPy arrays instead of Pillow images
• A blendmodes command-line tool for blending image files without writing code
• Image-difference helpers for comparing blend results

Common Use Cases

• Programmatically compositing image layers in a batch pipeline the way a designer would in Photoshop
• Generating textures, overlays, and lighting effects for procedural or generative art
• Reproducing the visual output of Open Raster (.ora) or Paint.NET files that rely on layer blend modes
• Adding photo-editor-style blending to an image-processing or content-generation service

Under The Hood

Architecture - The library centers on blendmodes/blend.py, where each blend mode is a small pure function taking background and foreground NumPy arrays and returning a blended array; a dispatch table maps each BlendType enum value (defined in blendtype.py) to its function, and blendLayers/blendLayersArray orchestrate alpha handling, opacity weighting, and normalization around that dispatch. cli.py wraps the array API with argparse for terminal use, and imgdiff.py provides comparison helpers.

Tech Stack - Pure Python (3.9+) built on NumPy 2.x for vectorized pixel math and Pillow for image loading and conversion, with aenum powering the multi-value BlendType enum and loguru for logging. Packaging uses Hatchling, and the project targets modern Python via pyproject.toml.

Code Quality - The repo ships a real test suite (test_blend.py, test_cli.py, test_imgdiff.py, test_perf.py) with reference image data, runs Ruff with the full ALL ruleset plus Pyright type checking, and is tox-tested across Python versions. Functions are small, single-purpose, and type-annotated.

API Design - The public surface is intentionally tiny: import blendLayers, pass two images plus a BlendType and opacity, and get a composited result. The typed enum makes the 30+ modes discoverable, and the array-level variant offers an escape hatch for performance-sensitive code without changing the mental model.