ImageMath Module

The ImageMath module can be used to evaluate “image expressions”. Themodule provides a single eval() function, which takesan expression string and one or more images.

Example: Using the ImageMath module

from PIL import Image, ImageMath
 
im1 = Image.open("image1.jpg")
im2 = Image.open("image2.jpg")
 
out = ImageMath.eval("convert(min(a, b), 'L')", a=im1, b=im2)
out.save("result.png")

• PIL.ImageMath.eval(expression, environment)[source]
• Evaluate expression in the given environment.

In the current version, ImageMath only supportssingle-layer images. To process multi-band images, use thesplit() method or merge()function.

Parameters:

• expression – A string which uses the standard Python expressionsyntax. In addition to the standard operators, you canalso use the functions described below.
• environment – A dictionary that maps image names to Image instances.You can use one or more keyword arguments instead of adictionary, as shown in the above example. Note thatthe names must be valid Python identifiers.Returns:
  An image, an integer value, a floating point value,or a pixel tuple, depending on the expression.

Expression syntax

Expressions are standard Python expressions, but they’re evaluated in anon-standard environment. You can use PIL methods as usual, plus the followingset of operators and functions:

Standard Operators

You can use standard arithmetical operators for addition (+), subtraction (-),multiplication (*), and division (/).

The module also supports unary minus (-), modulo (%), and power (**) operators.

Note that all operations are done with 32-bit integers or 32-bit floatingpoint values, as necessary. For example, if you add two 8-bit images, theresult will be a 32-bit integer image. If you add a floating point constant toan 8-bit image, the result will be a 32-bit floating point image.

You can force conversion using the convert(),float(), and int() functionsdescribed below.

Bitwise Operators

The module also provides operations that operate on individual bits. Thisincludes and (&), or (|), and exclusive or (^). You can also invert (~) allpixel bits.

Note that the operands are converted to 32-bit signed integers before thebitwise operation is applied. This means that you’ll get negative values ifyou invert an ordinary greyscale image. You can use the and (&) operator tomask off unwanted bits.

Bitwise operators don’t work on floating point images.

Logical Operators

Logical operators like and, or, and not workon entire images, rather than individual pixels.

An empty image (all pixels zero) is treated as false. All other images aretreated as true.

Note that and and or return the last evaluated operand,while not always returns a boolean value.

Built-in Functions

These functions are applied to each individual pixel.

• abs(image)
• Absolute value.

• convert(image, mode)
• Convert image to the given mode. The mode must be given as a stringconstant.

• float(image)
• Convert image to 32-bit floating point. This is equivalent toconvert(image, “F”).

• int(image)
• Convert image to 32-bit integer. This is equivalent to convert(image, “I”).

Note that 1-bit and 8-bit images are automatically converted to 32-bitintegers if necessary to get a correct result.

• max(image1, image2)
• Maximum value.

• min(image1, image2)
• Minimum value.