Telekinesis Agentic Skill Library

Appearance

Bitwise NOT Image ​

SUMMARY

Bitwise NOT Image performs bitwise NOT (inversion) on an image.

Inverts all pixel values. For binary images, 0 becomes 1 and 1 becomes 0. Useful for inverting masks, swapping foreground/background, and logical complement operations.

Use this Skill when you want to invert a binary mask or image.

The Skill ​

python
from telekinesis import pupil

result = pupil.bitwise_not_image(image=image)

API Reference

Example ​

Input Image

Input

Original binary image

Result

Output

Inverted image

The Code ​

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

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

# Load image
filepath = str(DATA_DIR / "images" / "einstein.webp")
image = io.load_image(filepath=filepath, as_binary=True, binary_method="fixed")
logger.success(f"Loaded image from {filepath}")

# Perform bitwise NOT (inversion) on image
result = pupil.bitwise_not_image(image=image)

# Access results
result_np = result.to_numpy()
logger.success("Bitwise NOT. 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.

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

Next, an image is loaded from a .png file using the io.load_image function. The image is loaded as binary using as_binary=True, which is appropriate for the bitwise NOT operation that inverts pixel values.

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

# Load image
filepath = str(DATA_DIR / "images" / "einstein.webp")
image = io.load_image(filepath=filepath, as_binary=True, binary_method="fixed")

The main operation uses the bitwise_not_image Skill from the pupil module. This Skill performs bitwise NOT (inversion) on an image, flipping each bit so that 0 becomes 255 and 255 becomes 0 for 8-bit binary images.

python
result = pupil.bitwise_not_image(image=image)

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

python
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 inversion, foreground/background swapping, and complement masking, where inverting a binary mask 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:

bash
cd telekinesis-examples
python examples/pupil_examples.py --example bitwise_not_image

How to Tune the Parameters ​

The bitwise_not_image Skill has no tunable parameters. It operates on a single input image and returns its pixel-wise logical NOT (inversion). Use with binary masks for foreground/background swapping.

TIP

Best practice: Use with binary masks for foreground/background swapping. Combine with bitwise_and_images to apply operations to non-masked regions.

Where to Use the Skill in a Pipeline ​

Bitwise NOT Image is commonly used in the following pipelines:

  • Mask inversion - Swap foreground/background
  • Complement masking - Apply operations to non-masked regions
  • Logical operations - Build complex masks with AND/OR/NOT

Related skills to build such a pipeline:

  • bitwise_and_images: Combine with inverted mask
  • bitwise_or_images: Union with complement

When Not to Use the Skill ​

Do not use Bitwise NOT Image when:

  • You need to negate intensity (e.g., 255-x) (NOT is bitwise; for simple inversion of 0/255 binary it is equivalent)
  • You're working with float images (Convert to appropriate format first)
  • You need to invert only a region (Use mask + bitwise operations)