Bitwise OR Images

SUMMARY

Bitwise OR Images performs bitwise OR between two images.

Computes the pixel-wise logical OR of two images. For binary images, the result is 1 where either image has 1. Useful for mask union, combining detection results, and merging regions.

Use this Skill when you want to combine two binary masks (union).

The Skill

from telekinesis import pupil

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

API Reference

Example

Image A

First Image

Image B

Second Mask

Result

Bitwise OR 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" / "can_vertical_6_mask.webp")
filepath_2 = str(DATA_DIR / "images" / "rectangles_mask.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_b = pupil.resize_image_with_aspect_fit(
    image=image_b,
    resize_width=image_a.width,
    resize_height=image_a.height,
    pad_color=(0, 0, 0),
)

# Perform bitwise OR between two images
result = pupil.bitwise_or_images(image_a=image_a, image_b=image_b)

# Access results
result_np = result.to_numpy()
logger.success("Bitwise OR. 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 using as_binary=True and must have the same dimensions for the bitwise OR operation.

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

filepath_1 = str(DATA_DIR / "images" / "can_vertical_6_mask.webp")
filepath_2 = str(DATA_DIR / "images" / "rectangles_mask.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_or_images Skill from the pupil module. This Skill performs pixel-wise logical OR between two images, producing 1 where either image has 1. For binary masks, this combines two masks into their union.

result = pupil.bitwise_or_images(image_a=image_a, image_b=image_b)

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 mask union, combining detection results, and merging regions, where combining 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_or_images

How to Tune the Parameters

The bitwise_or_images Skill has no tunable parameters. It operates on two input images of the same dimensions and returns their pixel-wise logical OR. Ensure both images are binary (0/255 or 0/1) for mask union operations.

TIP

Best practice: Ensure both images have identical width and height. Use for mask union, combining detections, or filling gaps between partial masks.

Where to Use the Skill in a Pipeline

Bitwise OR Images is commonly used in the following pipelines:

• Mask union - Merge multiple segmentation masks
• Combining detections - Aggregate regions from different detectors
• Filling gaps - Combine partial masks

Related skills to build such a pipeline:

• bitwise_and_images: Intersection of masks
• bitwise_xor_images: Exclusive regions
• bitwise_not_image: Invert masks

Alternative Skills

Skill	vs. Bitwise OR
bitwise_and_images	Use for intersection (AND) instead of union (OR).
bitwise_xor_images	Use for exclusive regions (XOR).

When Not to Use the Skill

Do not use Bitwise OR Images when:

• You need intersection (Use bitwise_and_images)
• You need exclusive regions (Use bitwise_xor_images)
• Images have different sizes (Resize to match first)