Bitwise AND Images

SUMMARY

Bitwise AND Images computes the pixel-wise bitwise AND of two images or masks.

Each output pixel is the bitwise AND of the corresponding pixels in image_a and image_b. For 0/255 binary masks this keeps a pixel only where both inputs are nonzero, i.e. it isolates the intersection of two regions. 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 mask an image with a binary mask, keeping only pixels inside a region of interest.

The Skill

from telekinesis import pupil

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

API Reference

Full parameter and return type documentation for bitwise_and_images.

View Reference →

Example

Image A

Original image

Image B

Binary mask marking the region of interest

Result

Bitwise AND result — only pixels inside the mask are kept

The Code

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

import numpy as np
from loguru import logger
import rerun as rr

from telekinesis import pupil, datatypes


def bitwise_and_images_example():
    """Performs bitwise AND between two images."""
    # ===================== Load Image ==========================================
    image_url = "https://assets.telekinesis.ai/examples/v1/images/bin_picking_metal_2.jpg"
    image = datatypes.Image.from_url(image_url)

    # ===================== Create Mask ==========================================
    bbox = [450, 210, 1040, 616]
    x1, y1, x2, y2 = bbox
    mask_data = np.zeros(image.shape[:2], dtype=np.uint8)
    mask_data[y1:y2, x1:x2] = 255
    mask = datatypes.Image(mask_data)

    # ===================== Run Skill ==========================================
    result_image = pupil.bitwise_and_images(image_a=image, image_b=mask)

    # ===================== Log ================================================
    logger.success(f"Bitwise AND between {image} and {mask} completed.")
    logger.success(f"Result: {result_image}")

    # ===================== Visualization  (Optional) ==========================
    rr.init("bitwise_and_images_example", spawn=True)
    datatypes.visualize(image, entity_path="1-Original")
    datatypes.visualize(mask, entity_path="2-Mask")
    datatypes.visualize(result_image, entity_path="3-Filtered")

if __name__ == "__main__":
    bitwise_and_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_and_images.py

Parameter Configuration

Key	Type	Default	Description
image_a	datatypes.Image | np.ndarray	required	First input image, shape (H, W) or (H, W, C)
image_b	datatypes.Image | np.ndarray	required	Second input image or mask, combined with image_a via bitwise AND. 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 the pixel-wise bitwise AND of the two inputs

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_and_images has no tunable parameters — it takes two required images and combines them with a fixed AND operation. The only requirement is that image_a and image_b have matching width and height.

TIP

Best practice: If image_b is a mask (e.g. from a bounding box or a segmentation skill), build it at the same resolution as image_a to avoid resizing artifacts. If the sizes already differ, resize with resize_image_with_aspect_fit before calling this Skill rather than relying on it to fail loudly.

Where to Use the Skill

Common pipelines include:

• ROI masking – Keep only the pixels inside a bounding box or region mask before further processing
• Mask intersection – Combine two segmentation masks into their overlap
• Selective filtering – Restrict a downstream operation (e.g. color analysis) to a masked region

Alternative Skills

Skill	vs. Bitwise AND Images
bitwise_or_images	Computes the union of two images instead of their intersection.
bitwise_xor_images	Keeps pixels that differ between the two inputs instead of pixels shared by both.
bitwise_not_image	Inverts a single mask; combine with this Skill to mask out a region instead of masking it in.

When Not to Use the Skill

Do not use Bitwise AND Images when:

• You need the union of two masks (use bitwise_or_images instead)
• You need pixels that differ between two masks (use bitwise_xor_images for a logical comparison, or bitwise_difference_images for an intensity difference)
• image_a and image_b have different dimensions (resize one to match first, e.g. with resize_image_with_aspect_fit)
• You only have one mask and want to invert it (use bitwise_not_image instead)