add cli and more tests

Author: FredHappyface

blendmodes/__main.py

@@ -0,0 +1,4 @@
+from blendmodes.cli import main
+
+if __name__ == "__main__":
+	main()

blendmodes/blend.py

@@ -26,6 +26,8 @@
 
 from blendmodes.blendtype import BlendType
 
+HALF_THRESHOLD = 0.5
+
 
 def normal(background: np.ndarray, foreground: np.ndarray) -> np.ndarray:
 	"""BlendType.NORMAL."""
@@ -76,7 +78,7 @@ def glow(background: np.ndarray, foreground: np.ndarray) -> np.ndarray:
 def overlay(background: np.ndarray, foreground: np.ndarray) -> np.ndarray:
 	"""BlendType.OVERLAY."""
 	return np.where(
-		background < 0.5,
+		background < HALF_THRESHOLD,
 		2 * background * foreground,
 		1.0 - (2 * (1.0 - background) * (1.0 - foreground)),
 	)
@@ -125,7 +127,7 @@ def softlight(background: np.ndarray, foreground: np.ndarray) -> np.ndarray:
 def hardlight(background: np.ndarray, foreground: np.ndarray) -> np.ndarray:
 	"""BlendType.HARDLIGHT."""
 	return np.where(
-		foreground < 0.5,
+		foreground < HALF_THRESHOLD,
 		np.minimum(background * 2 * foreground, 1.0),
 		np.minimum(1.0 - ((1.0 - background) * (1.0 - (foreground - 0.5) * 2.0)), 1.0),
 	)
@@ -148,16 +150,16 @@ def divide(background: np.ndarray, foreground: np.ndarray) -> np.ndarray:
 
 def pinlight(background: np.ndarray, foreground: np.ndarray) -> np.ndarray:
 	"""BlendType.PINLIGHT."""
-	return np.minimum(background, 2 * foreground) * (foreground < 0.5) + np.maximum(
+	return np.minimum(background, 2 * foreground) * (foreground < HALF_THRESHOLD) + np.maximum(
 		background, 2 * (foreground - 0.5)
-	) * (foreground >= 0.5)
+	) * (foreground >= HALF_THRESHOLD)
 
 
 def vividlight(background: np.ndarray, foreground: np.ndarray) -> np.ndarray:
 	"""BlendType.VIVIDLIGHT."""
-	return colourburn(background, foreground * 2) * (foreground < 0.5) + colourdodge(
+	return colourburn(background, foreground * 2) * (foreground < HALF_THRESHOLD) + colourdodge(
 		background, 2 * (foreground - 0.5)
-	) * (foreground >= 0.5)
+	) * (foreground >= HALF_THRESHOLD)
 
 
 def exclusion(background: np.ndarray, foreground: np.ndarray) -> np.ndarray:
@@ -543,60 +545,54 @@ def blendLayersArray(
 	"""
 
 	# Convert the Image.Image to a numpy array if required
-	if isinstance(background, Image.Image):
-		background = np.array(background.convert("RGBA"))
-	if isinstance(foreground, Image.Image):
-		foreground = np.array(foreground.convert("RGBA"))
+	bg = np.array(background.convert("RGBA")) if isinstance(background, Image.Image) else background
+	fg = np.array(foreground.convert("RGBA")) if isinstance(foreground, Image.Image) else foreground
 
 	# do any offset shifting first
 	if offsets[0] > 0:
-		foreground = np.hstack(
-			(np.zeros((foreground.shape[0], offsets[0], 4), dtype=np.float64), foreground)
-		)
+		fg = np.hstack((np.zeros((bg.shape[0], offsets[0], 4), dtype=np.float64), fg))
 	elif offsets[0] < 0:
-		if offsets[0] > -1 * foreground.shape[1]:
-			foreground = foreground[:, -1 * offsets[0] :, :]
+		if offsets[0] > -1 * fg.shape[1]:
+			fg = fg[:, -1 * offsets[0] :, :]
 		else:
 			# offset offscreen completely, there is nothing left
-			return np.zeros(background.shape, dtype=np.float64)
+			return np.zeros(bg.shape, dtype=np.float64)
 	if offsets[1] > 0:
-		foreground = np.vstack(
-			(np.zeros((offsets[1], foreground.shape[1], 4), dtype=np.float64), foreground)
-		)
+		fg = np.vstack((np.zeros((offsets[1], fg.shape[1], 4), dtype=np.float64), fg))
 	elif offsets[1] < 0:
-		if offsets[1] > -1 * foreground.shape[0]:
-			foreground = foreground[-1 * offsets[1] :, :, :]
+		if offsets[1] > -1 * fg.shape[0]:
+			fg = fg[-1 * offsets[1] :, :, :]
 		else:
 			# offset offscreen completely, there is nothing left
-			return np.zeros(background.shape, dtype=np.float64)
+			return np.zeros(bg.shape, dtype=np.float64)
 
 	# resize array to fill small images with zeros
-	if foreground.shape[0] < background.shape[0]:
-		foreground = np.vstack(
+	if fg.shape[0] < bg.shape[0]:
+		fg = np.vstack(
 			(
-				foreground,
+				fg,
 				np.zeros(
-					(background.shape[0] - foreground.shape[0], foreground.shape[1], 4),
+					(bg.shape[0] - fg.shape[0], fg.shape[1], 4),
 					dtype=np.float64,
 				),
 			)
 		)
-	if foreground.shape[1] < background.shape[1]:
-		foreground = np.hstack(
+	if fg.shape[1] < bg.shape[1]:
+		fg = np.hstack(
 			(
-				foreground,
+				fg,
 				np.zeros(
-					(foreground.shape[0], background.shape[1] - foreground.shape[1], 4),
+					(fg.shape[0], bg.shape[1] - fg.shape[1], 4),
 					dtype=np.float64,
 				),
 			)
 		)
 
 	# crop the source if the backdrop is smaller
-	foreground = foreground[: background.shape[0], : background.shape[1], :]
+	fg = fg[: bg.shape[0], : bg.shape[1], :]
 
-	lower_norm = background / 255.0
-	upper_norm = foreground / 255.0
+	lower_norm = bg / 255.0
+	upper_norm = fg / 255.0
 
 	upper_alpha = upper_norm[:, :, 3] * opacity
 	lower_alpha = lower_norm[:, :, 3]
@@ -639,10 +635,14 @@ def alpha_comp_shell(
 
 	blend_rgb = blend(lower_rgb, upper_rgb, blendType)
 
-	lower_rgb_part = np.multiply(((1.0 - upper_alpha) * lower_alpha)[:, :, None], lower_rgb)
-	upper_rgb_part = np.multiply(((1.0 - lower_alpha) * upper_alpha)[:, :, None], upper_rgb)
-	blended_rgb_part = np.multiply((lower_alpha * upper_alpha)[:, :, None], blend_rgb)
+	lower_rgb_factor = (1.0 - upper_alpha) * lower_alpha
+	upper_rgb_factor = (1.0 - lower_alpha) * upper_alpha
+	blended_rgb_factor = lower_alpha * upper_alpha
 
-	out_rgb = np.divide((lower_rgb_part + upper_rgb_part + blended_rgb_part), out_alpha[:, :, None])
+	out_rgb = (
+		lower_rgb_factor[:, :, None] * lower_rgb
+		+ upper_rgb_factor[:, :, None] * upper_rgb
+		+ blended_rgb_factor[:, :, None] * blend_rgb
+	) / out_alpha[:, :, None]
 
 	return out_rgb, out_alpha

blendmodes/cli.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+from loguru import logger
+from PIL import Image
+
+from blendmodes.blend import blendLayersArray
+from blendmodes.blendtype import BlendType
+from blendmodes.imgdiff import image_diff_array
+
+logger.remove()
+logger.add(sys.stdout, level="INFO", format="<level>{level: <8}</level> | {message}")
+
+
+def get_im_np(image: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> np.ndarray:
+	"""Convert image at path to RGBA NumPy array."""
+	img = image if isinstance(image, Image.Image) else Image.open(image).convert("RGBA")
+	return np.array(img)
+
+
+def main() -> None:
+	# Parent parser with shared arguments
+	common_parser = argparse.ArgumentParser(add_help=False)
+	common_parser.add_argument("image1", type=Path, help="Path to the first image (background)")
+	common_parser.add_argument("image2", type=Path, help="Path to the second image (foreground)")
+
+	# Main parser
+	parser = argparse.ArgumentParser(description="Blend or compare two images")
+	subparsers = parser.add_subparsers(dest="command", required=True)
+
+	# Blend Subcommand
+	blend_parser = subparsers.add_parser("blend", parents=[common_parser], help="Blend two images")
+	blend_parser.add_argument(
+		"--blend",
+		"-b",
+		choices=[alias.lower() for mode in BlendType for alias in mode.values],
+		help="Blend mode to use (e.g. normal, multiply, screen)",
+	)
+	blend_parser.add_argument("--output", "-o", type=Path, required=True, help="Output image path")
+
+	# Diff Subcommand
+	subparsers.add_parser("diff", parents=[common_parser], help="Compare two images")
+
+	# Parse arguments
+	args = parser.parse_args()
+
+	img1 = get_im_np(args.image1)
+	img2 = get_im_np(args.image2)
+
+	if args.command == "diff":
+		diff = image_diff_array(img1, img2)
+		logger.info(
+			f"Comparing {args.image1.name} and {args.image2.name} are {diff * 100:.2f}% different"
+		)
+
+	else:
+		result = blendLayersArray(img1, img2, args.blend)
+		result_im = Image.fromarray(np.uint8(np.around(result, 0)))
+		result_im.save(args.output)
+		logger.info(
+			f"Blending {args.image1.name} and {args.image2.name} and "
+			f"writing the result to {args.output}"
+		)
+
+
+if __name__ == "__main__":
+	main()

blendmodes/imgdiff.py

@@ -1,3 +1,21 @@
+"""
+Image Difference for Blend Modes Library.
+
+This module provides functions to compare two images.
+It calculates the pixel-wise difference and the percentage of differing pixels between
+two images, which is useful for testing and validating blend mode implementations.
+
+Functions:
+- image_diff: Compute the difference between two images as a float between 0-1 or
+0-100
+- image_diff_array: Compute the difference between two images as numpy arrays as a
+float between 0-1 or 0-100
+- is_equal: Check if two images are identical, optionally allowing for a tolerance
+in pixel values.
+- is_x_diff: Compare two images and return True/False if the image is within `tolerance` of
+	`cmp_diff`.
+"""
+
 from __future__ import annotations
 
 import numpy as np
@@ -65,11 +83,7 @@ def is_equal(
 ) -> bool:
 	"""
 	Compare two images and return True/False if the image is within `tolerance` of
-	`cmp_diff`.
-
-	For example, a black and white image compared in 'RGB' mode would
-	return a value of 100, which would then be checked if its between
-	`cmp_diff - tolerance` and `cmp_diff + tolerance`
+	the second image.
 
 	:param Image.Image img1in: image 1 to compare
 	:param Image.Image img2in: image 2 to compare
@@ -174,14 +188,15 @@ def image_diff_array(img1in: Image.Image | np.ndarray, img2in: Image.Image | np.
 
 	"""
 	# Convert PIL images to NumPy arrays if needed
-	img1 = np.array(img1in) if isinstance(img1in, Image.Image) else img1in
-	img2 = np.array(img2in) if isinstance(img2in, Image.Image) else img2in
+	img1 = np.array(img1in, dtype=np.int16) if isinstance(img1in, Image.Image) else img1in
+	img2 = np.array(img2in, dtype=np.int16) if isinstance(img2in, Image.Image) else img2in
 	# Ensure images have the same dimensions
 	if img1.shape != img2.shape:
 		msg = "Images must have the same dimensions for comparison."
 		raise ValueError(msg)
 
 	# Compute absolute difference
+
 	difference = np.abs(img1 - img2)
 
 	# Sum the differences and normalize to get a percentage

documentation/reference/README.md

@@ -5,6 +5,8 @@
 A full list of `Blendmodes` project modules.
 
 - [Blendmodes](blendmodes/index.md#blendmodes)
+    - [Main](blendmodes/__main.md#main)
     - [Blend](blendmodes/blend.md#blend)
     - [BlendType](blendmodes/blendtype.md#blendtype)
+    - [Cli](blendmodes/cli.md#cli)
     - [Imgdiff](blendmodes/imgdiff.md#imgdiff)

documentation/reference/blendmodes/__main.md

@@ -0,0 +1,6 @@
+# Main
+
+[Blendmodes Index](../README.md#blendmodes-index) / [Blendmodes](./index.md#blendmodes) / Main
+
+> Auto-generated documentation for [blendmodes.__main](../../../blendmodes/__main.py) module.
+- [Main](#main)