Bitwise NOT Image

SUMMARY

Bitwise NOT Image performs a pixel-wise bitwise NOT (inversion) on an image.

Each output pixel is the bitwise complement of the input pixel — for an 8-bit image this is 255 - value. On a 0/255 binary mask, this swaps foreground and background. It is a single-image operation with no second input to align.

Use this Skill when you want to invert a binary mask (foreground/background swap) or invert pixel intensities.

The Skill

from telekinesis import pupil

result_image = pupil.bitwise_not_image(image=image)

API Reference

Full parameter and return type documentation for bitwise_not_image.

View Reference →

Example

Input Image

Original image

Result

Inverted image

The Code

"""Demonstrates bitwise NOT operation on an image."""

from loguru import logger
import rerun as rr

from telekinesis import pupil, datatypes


def bitwise_not_image_example():
    """Performs bitwise NOT (inversion) on an image."""
    # ===================== Load Image ==========================================
    image_url = "https://assets.telekinesis.ai/examples/v1/images/einstein.png"
    image = datatypes.Image.from_url(image_url)

    # ===================== Run Skill ==========================================
    filtered_image = pupil.bitwise_not_image(image=image)

    # ===================== Log ================================================
    logger.success(f"Bitwise NOT on {image}")
    logger.success(f"Result: {filtered_image}")

    # ===================== Visualization  (Optional) ======================
    rr.init("bitwise_not_image_example", spawn=True)
    datatypes.visualize(image, entity_path="1-Original")
    datatypes.visualize(filtered_image, entity_path="2-Inverted")

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

Parameter Configuration

Key	Type	Default	Description
image	datatypes.Image | np.ndarray	required	The input image to invert, shape (H, W) or (H, W, C)

Returns

Type	Description
datatypes.Image	Same shape as image, with each pixel value inverted (255 - value for 8-bit images)

Raises

Exception	Condition
TypeError	image has an invalid type
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_not_image has no tunable parameters — it takes a single required image and inverts it unconditionally.

TIP

Best practice: Use this on binary masks to swap which region is "foreground" without recomputing a segmentation, or chain it with bitwise_and_images to mask out a region (AND with the inverted mask) instead of masking one in.

Where to Use the Skill

Common pipelines include:

• Mask inversion – Swap foreground and background in a binary mask
• Complement masking – Apply a downstream operation to everything outside a masked region
• Compound logical masks – Build AND/OR/NOT combinations of multiple masks

Alternative Skills

Skill	vs. Bitwise NOT Image
bitwise_and_images	Combines two images by intersection; pair with this Skill's inverted output to mask a region out instead of in.
bitwise_or_images	Combines two images by union; use together with an inverted mask to fill in the complement of a region.

When Not to Use the Skill

Do not use Bitwise NOT Image when:

• You need to combine two images (this Skill only operates on one image at a time; use bitwise_and_images, bitwise_or_images, or bitwise_xor_images for two-image operations)
• You're working with a non-binary intensity image and want a specific tone curve (a plain bitwise NOT just complements every pixel value; consider enhance_image_using_clahe or enhance_image_using_auto_gamma_correction if you need a different brightness adjustment)
• You need to invert only a sub-region of an image (mask the region first, e.g. with bitwise_and_images, then invert)