Bitwise XOR Images

SUMMARY

Bitwise XOR Images performs bitwise XOR between two images.

Computes the pixel-wise logical XOR of two images. For binary images, the result is 1 where exactly one image has 1 (exclusive regions). Useful for finding differences between masks and highlighting changes.

Use this Skill when you want to find exclusive regions between two masks.

The Skill

from telekinesis import pupil

result = pupil.bitwise_xor_images(image_1=image, image_2=image_2)

API Reference

Example

Image A

First Image

Image B

Second Mask

Result

Bitwise XOR Result

The Code

from telekinesis import pupil
from datatypes import io
import pathlib
from loguru import logger

DATA_DIR = pathlib.Path("path/to/telekinesis-data")

# Load images
filepath_1 = str(DATA_DIR / "images" / "gear_with_texture.jpg")
filepath_2 = str(DATA_DIR / "images" / "bin_1.webp")
image_a = io.load_image(filepath=filepath_1, as_binary=True, binary_method="fixed")
image_b = io.load_image(filepath=filepath_2, as_binary=True, binary_method="fixed")

# Resize image_b to match image_a dimensions
image_2_resized = pupil.resize_image_with_aspect_fit(
    image=image_b,
    resize_width=image_a.width,
    resize_height=image_a.height,
)

# Perform bitwise XOR between two images
result = pupil.bitwise_xor_images(image_a=image_a, image_b=image_2_resized)

# Access results
result_np = result.to_numpy()
logger.success("Bitwise XOR. Output shape: {}", result_np.shape)

The Explanation of the Code

The code begins by importing the necessary modules: pupil for image processing operations, io for data handling, pathlib for path management, and loguru for logging.

from telekinesis import pupil
from datatypes import io
import pathlib
from loguru import logger

Next, images are loaded from files using the io.load_image function. Both images are loaded as binary masks and must have the same dimensions; one may be resized to match before the XOR operation.

DATA_DIR = pathlib.Path("path/to/telekinesis-data")

filepath_1 = str(DATA_DIR / "images" / "gear_with_texture.jpg")
filepath_2 = str(DATA_DIR / "images" / "bin_1.webp")
image_a = io.load_image(filepath=filepath_1, as_binary=True, binary_method="fixed")
image_b = io.load_image(filepath=filepath_2, as_binary=True, binary_method="fixed")

The main operation uses the bitwise_xor_images Skill from the pupil module. This Skill performs pixel-wise logical XOR between two images, producing 1 where exactly one image has 1 (exclusive regions). For identical images, the result is all zeros.

result = pupil.bitwise_xor_images(image_a=image_a, image_b=image_2_resized)

Finally, the result is converted to a NumPy array using to_numpy() for further processing, visualization, or downstream tasks.

result_np = result.to_numpy()
logger.success(f"Output shape: {result_np.shape}")

This operation is particularly useful in robotics and vision pipelines for change detection, finding exclusive regions, and comparing masks, where highlighting differences between two binary masks is required.

Running the Example

Runnable examples are available in the Telekinesis examples repository. Follow the README in that repository to set up the environment. Once set up, you can run this specific example with:

cd telekinesis-examples
python examples/pupil_examples.py --example bitwise_xor_images

How to Tune the Parameters

The bitwise_xor_images Skill has no tunable parameters. It operates on two input images of the same dimensions and returns their pixel-wise logical XOR. Ensure both images are binary for mask comparison and change detection.

TIP

Best practice: Ensure both images have identical width and height. Use for change detection, finding exclusive regions, or comparing segmentation outputs.

Where to Use the Skill in a Pipeline

Bitwise XOR Images is commonly used in the following pipelines:

• Change detection - Highlight differences between masks
• Exclusive regions - Find pixels in one mask but not the other
• Mask comparison - Compare segmentation outputs

Related skills to build such a pipeline:

• bitwise_and_images: Intersection
• bitwise_or_images: Union
• bitwise_difference_images: Absolute pixel difference (grayscale/color)

Alternative Skills

Skill	vs. Bitwise XOR
bitwise_difference_images	Use for absolute pixel difference on grayscale/color images (not logical XOR).
bitwise_and_images	Use for intersection (AND).

When Not to Use the Skill

Do not use Bitwise XOR Images when:

• You need absolute pixel difference (Use bitwise_difference_images for grayscale/color)
• You need intersection or union (Use bitwise_and_images or bitwise_or_images)
• Images have different sizes (Resize to match first)