SegmentationImage

SUMMARY

An image in which each pixel stores a segmentation label.

from telekinesis import datatypes
import numpy as np
segmentation_image = datatypes.SegmentationImage(np.zeros((4, 4), dtype=np.uint8))

API Reference

Complete API documentation for SegmentationImage, including parameters, attributes, and methods.

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray	Required	Per-pixel segmentation labels with shape (H, W) and a supported integer dtype.
compression	ImageCompression | int	ImageCompression.NONE	Compression codec used during serialization.

Raises

Exception	Condition
TypeError	data isn't an np.ndarray
ValueError	data isn't 2-D, is empty (H or W is 0), has an unsupported dtype, contains a negative label (checked for signed dtypes only), or compression is invalid

Supported Dtypes

uint8, uint16, uint32, uint64, int8, int16, int32, int64. No floating-point dtypes.

Attributes

Attribute	Type	Description
data	np.ndarray	Defensive copy of the label array. Assigning re-validates the same way as construction.
shape	tuple[int, int]	(height, width).
height	int	Image height.
width	int	Image width.
dtype	np.dtype	Dtype of the label array.
compression	ImageCompression	On-wire codec. Read-only (no setter).
label_codes	np.ndarray	Sorted unique label codes present in data, recomputed via np.unique on every access (not cached).
number_of_labels	int	Count of distinct label codes present, recomputed via np.unique on every access (not cached).

Methods

Method	Type	Description
SegmentationImage.coerce(value)	SegmentationImage	Converts an np.ndarray of label codes into a SegmentationImage, running the same validation as the constructor. If value is already a SegmentationImage, it is returned unchanged.
SegmentationImage.from_raw_buffer(buffer, shape, dtype, compression=NONE)	SegmentationImage	Builds a SegmentationImage from raw label bytes, reshaping them to shape. buffer's size must match shape.
SegmentationImage.from_encoded_buffer(buffer, compression=NONE)	SegmentationImage	Decodes a single-channel encoded image (e.g. an 8-bit or 16-bit PNG) directly into per-pixel label codes; no scaling or colormap lookup is applied.
SegmentationImage.from_path(path, compression=NONE)	SegmentationImage	Reads and decodes an encoded label image file from disk, the same way as from_encoded_buffer.
SegmentationImage.from_url(url, compression=NONE, connect_timeout=5.0, read_timeout=30.0)	SegmentationImage	Downloads and decodes an encoded label image from a URL, the same way as from_encoded_buffer.
to_numpy(copy=True)	np.ndarray	Returns the label array as a plain array. With the default copy=True you get an independent copy; pass copy=False to get a direct reference to the internal array instead, so mutating it also mutates the SegmentationImage.
to_binary()	SegmentationImage	Returns a new uint8 SegmentationImage where every non-zero label becomes 1 (foreground) and 0 stays 0 (background). Label identity beyond zero/non-zero is not preserved.
copy()	SegmentationImage	Returns a new, independent SegmentationImage with the same labels and compression setting.
save_to_path(path)	None	Writes the label image to disk as a lossless PNG, creating any missing parent directories. Only uint8, uint16, and int32 label data can be saved this way.

Operators

Operation	Behavior
img == other	True only if other is a SegmentationImage with an element-equal label array; compression is not compared. NotImplemented if other isn't a SegmentationImage.
np.asarray(img)	Returns a copy of the label array as an np.ndarray; NumPy functions accept a SegmentationImage directly. Passing copy=False raises ValueError.
repr(img)	Shows label_codes/number_of_labels when compression is NONE; otherwise just shape/dtype/compression (skips the label scan).

Visualization

import rerun as rr

# Your code block
# ....

rr.init("segmentation_image_example", spawn=True)
datatypes.visualize(segmentation_image, entity_path="/segmentation_image", label="SegmentationImage")

Example

"""Demonstrates the Telekinesis SegmentationImage datatype."""

import time
from pathlib import Path

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

from telekinesis import datatypes

def segmentation_image_example():
    """Demonstrate creation, inspection, operations, visualization, and serialization."""

    # ======================= Create ============================================
    data = np.random.randint(0, 5, (480, 640), dtype=np.uint8)
    segmentation_image = datatypes.SegmentationImage(data)
    logger.info(f"Created SegmentationImage: {segmentation_image}")

    segmentation_image_from_coerce = datatypes.SegmentationImage.coerce(data)
    logger.info(f"SegmentationImage created via coerce: {segmentation_image_from_coerce}")

    raw_buffer = data.tobytes()
    segmentation_image_from_raw_buffer = datatypes.SegmentationImage.from_raw_buffer(
        raw_buffer, shape=data.shape, dtype=data.dtype
    )
    logger.info(f"SegmentationImage created from raw buffer: {segmentation_image_from_raw_buffer}")

    save_path = Path("results/segmentation_image_example.png")
    save_path.parent.mkdir(parents=True, exist_ok=True)
    segmentation_image.save_to_path(save_path)
    segmentation_image_from_path = datatypes.SegmentationImage.from_path(save_path)
    logger.info(f"SegmentationImage created from path: {segmentation_image_from_path}")

    encoded_buffer = save_path.read_bytes()
    segmentation_image_from_encoded_buffer = datatypes.SegmentationImage.from_encoded_buffer(
        encoded_buffer
    )
    logger.info(
        f"SegmentationImage created from encoded buffer: {segmentation_image_from_encoded_buffer}"
    )

    # ======================= Inspect ===========================================
    logger.info(f"data={segmentation_image.data}")
    logger.info(f"shape={segmentation_image.shape}")
    logger.info(f"height={segmentation_image.height}")
    logger.info(f"width={segmentation_image.width}")
    logger.info(f"dtype={segmentation_image.dtype}")
    logger.info(f"label_codes={segmentation_image.label_codes}")
    logger.info(f"number_of_labels={segmentation_image.number_of_labels}")
    logger.info(f"compression={segmentation_image.compression}")

    # ======================= Operations =========================================
    updated_data = np.random.randint(0, 5, (480, 640), dtype=np.uint8)
    segmentation_image.data = updated_data
    logger.info(f"Updated SegmentationImage: {segmentation_image}")

    binary_segmentation_image = segmentation_image.to_binary()
    logger.info(f"Binary SegmentationImage: {binary_segmentation_image}")

    segmentation_image_copy = segmentation_image.copy()
    logger.info(f"Copied SegmentationImage: {segmentation_image_copy}")

    segmentation_image_numpy = segmentation_image.to_numpy(copy=True)
    logger.info(f"NumPy array:\n{segmentation_image_numpy}")

    numpy_array = np.asarray(segmentation_image)
    logger.info(f"Mean label value: {np.mean(numpy_array)}")

    # ======================= Visualize =========================================
    rr.init("segmentation_image_example", spawn=True)
    datatypes.visualize(
        segmentation_image, entity_path="/segmentation_image/updated"
    )
    datatypes.visualize(
        binary_segmentation_image, entity_path="/segmentation_image/binary"
    )

    # ======================= Serialize / Deserialize ===========================
    start = time.perf_counter()
    serialized = datatypes.serialize(segmentation_image)
    serialization_ms = (time.perf_counter() - start) * 1000

    start = time.perf_counter()
    deserialized = datatypes.deserialize(serialized)["param_0"]
    deserialization_ms = (time.perf_counter() - start) * 1000

    logger.info(f"Deserialized SegmentationImage: {deserialized}")
    logger.info(f"Round-trip successful: {segmentation_image == deserialized}")
    logger.info(f"Serialization time: {serialization_ms:.3f} ms")
    logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")


if __name__ == "__main__":
    segmentation_image_example()