Bitwise Difference Images

SUMMARY

Bitwise Difference Images performs absolute difference between two images.

Computes the pixel-wise absolute difference |image_1 - image_2|. Useful for change detection, motion analysis, and comparing images. Highlights regions where the two images differ in intensity.

Use this Skill when you want to find pixel-wise differences between two images.

The Skill

from telekinesis import pupil

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

API Reference

Example

Image A

First Image

Image B

Second Mask

Result

Absolute Difference 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" / "driver_screw.webp")
filepath_2 = str(DATA_DIR / "images" / "difference_image.webp")
image_a = io.load_image(filepath=filepath_1, as_binary=True, binary_method="otsu")
image_b = io.load_image(filepath=filepath_2, as_binary=True, binary_method="otsu")

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

# Perform absolute difference between two images
result = pupil.bitwise_difference_images(image_a=image_a, image_b=image_b_resized)

# Access results
result_np = result.to_numpy()
logger.success("Bitwise difference. 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 .png files using the io.load_image function. Both images are loaded as binary masks. The images must have the same dimensions; one may be resized to match before computing the absolute difference.

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

filepath_1 = str(DATA_DIR / "images" / "driver_screw.webp")
filepath_2 = str(DATA_DIR / "images" / "difference_image.webp")
image_a = io.load_image(filepath=filepath_1, as_binary=True, binary_method="otsu")
image_b = io.load_image(filepath=filepath_2, as_binary=True, binary_method="otsu")

The main operation uses the bitwise_difference_images Skill from the pupil module. This Skill computes the pixel-wise absolute difference |image_a - image_b|, highlighting regions where the two images differ. Works on grayscale and color images.

result = pupil.bitwise_difference_images(image_a=image_a, image_b=image_b_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, motion analysis, and image comparison, where finding pixel-wise differences between two images 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_difference_images

How to Tune the Parameters

The bitwise_difference_images Skill has no tunable parameters. It operates on two input images of the same dimensions and returns their pixel-wise absolute difference. Works with grayscale and color images for change detection and motion analysis.

TIP

Best practice: Ensure both images have identical width and height. Use for change detection, motion analysis, or highlighting differences between images.

Where to Use the Skill in a Pipeline

Bitwise Difference Images is commonly used in the following pipelines:

• Change detection - Detect motion or scene changes
• Alignment verification - Check alignment quality
• Defect detection - Compare reference vs. sample
• Motion analysis - Frame-to-frame differences in video

Related skills to build such a pipeline:

• bitwise_xor_images: Logical XOR for binary masks
• rotate_image: Create test differences

Alternative Skills

Skill	vs. Bitwise Difference
bitwise_xor_images	Use for logical XOR on binary masks; difference is for intensity.
overlay_images_using_weighted_overlay	Use for blending; difference highlights changes.

When Not to Use the Skill

Do not use Bitwise Difference Images when:

• You need logical XOR on binary masks (Use bitwise_xor_images)
• You need to blend images (Use overlay_images_using_weighted_overlay)
• Images have different sizes (Resize to match first)