Bitwise Difference Images

SUMMARY

Bitwise Difference Images computes the pixel-wise absolute difference between two images.

Each output pixel is abs(image_a - image_b), so identical regions go to zero and differing regions stand out proportionally to how much they differ. Unlike bitwise_xor_images, this works on full-intensity grayscale/color images, not just binary masks. The two inputs must share the same width and height — resize one first (e.g. with resize_image_with_aspect_fit) if they don't.

Use this Skill when you want to subtract a reference image from a test image to detect changes or defects.

The Skill

from telekinesis import pupil

result_image = pupil.bitwise_difference_images(image_a=image_a, image_b=image_b)

API Reference

Full parameter and return type documentation for bitwise_difference_images.

View Reference →

Example

Image A

Reference image

Image B

Test image, resized to match Image A

Result

Absolute difference — brighter pixels indicate larger change

The Code

"""Demonstrates bitwise difference operation between two images."""

from loguru import logger
import rerun as rr

from telekinesis import pupil, datatypes


def bitwise_difference_images_example():
    """Performs bitwise difference between two images."""
    # ===================== Load Images ==========================================
    image_url_a = "https://assets.telekinesis.ai/examples/v1/images/driver_screw.png"
    image_url_b = "https://assets.telekinesis.ai/examples/v1/images/difference_image.png"
    image_a = datatypes.Image.from_url(image_url_a)
    image_b = datatypes.Image.from_url(image_url_b)

    # ===================== Resize Image B ==========================================
    image_b_resized = pupil.resize_image_with_aspect_fit(
        image=image_b,
        resize_width=image_a.width,
        resize_height=image_a.height,
    )

    # ===================== Run Skill ==========================================
    filtered_image = pupil.bitwise_difference_images(
        image_a=image_a, image_b=image_b_resized
    )

    # ===================== Log ================================================
    logger.success(f"Bitwise difference between {image_a} and {image_b_resized}")
    logger.success(f"Result: {filtered_image}")

    # ===================== Visualization  (Optional) ======================
    rr.init("bitwise_difference_images_example", spawn=True)
    datatypes.visualize(image_a, entity_path="1-Original")
    datatypes.visualize(image_b_resized, entity_path="2-Resized")
    datatypes.visualize(filtered_image, entity_path="3-Filtered Image")


if __name__ == "__main__":
    bitwise_difference_images_example()

Runnable examples are available in the Telekinesis examples repository.

Follow the README in that repository to set up the environment, run this specific example with:

cd telekinesis-examples
python examples/image_processing/bitwise_difference_images.py

Parameter Configuration

Key	Type	Default	Description
image_a	datatypes.Image | np.ndarray	required	First (e.g. reference) input image, shape (H, W) or (H, W, C)
image_b	datatypes.Image | np.ndarray	required	Second (e.g. test) input image, subtracted from image_a. Must have the same (H, W) as image_a — use resize_image_with_aspect_fit first if the sizes differ

Returns

Type	Description
datatypes.Image	Same shape as image_a, containing abs(image_a - image_b) per pixel

Raises

Exception	Condition
TypeError	image_a or image_b has an invalid type
ValueError	image_a and image_b have different width or height
ConfigurationError	The TELEKINESIS_API_KEY environment variable is not set
SerializationError	The request input failed to serialize, or the response failed to deserialize
RequestTimeoutError	The request to the Pupil service timed out
TransportError	A network failure occurred before a response was received
ClientError	The Pupil service rejected the request due to invalid input, invalid data, or another unexpected 4xx response
AuthenticationError	The API key was rejected as invalid or expired
AuthenticationServiceError	The authentication service was unavailable
ServerError	The Pupil service returned a 5xx or otherwise unexpected error response

How to Tune the Parameters

bitwise_difference_images has no tunable parameters — it takes two required images and returns their fixed absolute difference. The only requirement is that image_a and image_b have matching width and height.

TIP

Best practice: Align image_a and image_b as closely as possible before diffing (same crop, same lighting, same camera pose) — any misalignment shows up as difference noise unrelated to the actual change you're trying to detect. Threshold the result (e.g. with a Cornea segmentation skill) to turn it into a binary defect/change mask.

Where to Use the Skill

Common pipelines include:

• Defect detection – Compare a golden reference part against a test part to surface defects
• Change detection – Detect scene or object changes between two captures
• Alignment verification – Check how closely two images match after a registration step
• Motion analysis – Compare consecutive video frames to isolate moving regions

Alternative Skills

Skill	vs. Bitwise Difference Images
bitwise_xor_images	Computes a logical XOR on binary masks instead of an intensity difference; use it when both inputs are already binary.
overlay_images_using_weighted_overlay	Blends two images together instead of highlighting where they differ.

When Not to Use the Skill

Do not use Bitwise Difference Images when:

• Both inputs are already binary masks and you want a logical comparison (use bitwise_xor_images instead)
• You want to blend or composite two images rather than compare them (use overlay_images_using_weighted_overlay)
• image_a and image_b have different dimensions (resize one to match first, e.g. with resize_image_with_aspect_fit)
• The two images aren't spatially aligned (register/align them first, otherwise the difference reflects misalignment rather than real change)