Image

Represents a monochrome or color image. Instances can be constructed from a NumPy array (recommended) or from raw bytes with optional pixel_format or with color_model and channel_datatype. Supports encoding (e.g. PNG) and compression (e.g. ZSTD). This datatype is used for image inputs and outputs throughout the Telekinesis ecosystem.

Field

Required

Provide either image or bytes (with width and height).

Field	Type	Description
image	np.ndarray	Image data; 2D or 3D (height, width[, channels]). Infers size and dtype (e.g. uint8). Use instead of bytes when supplying pixel data directly.
bytes	bytes	Raw pixel bytes. Requires width, height, and either pixel_format or color_model + channel_datatype.
width	int	Image width in pixels (int). Required when using bytes.
height	int	Image height in pixels (int). Required when using bytes.

Optional

Field	Type	Description
color_model	ColorModel or str	e.g. "RGB", "L", "RGBA". Inferred from array when using image. See Enums.
pixel_format	int	Pixel format enum (e.g. NV12); mutually exclusive with color_model/channel_datatype.
channel_datatype	ChannelDatatype	Channel type (e.g. ChannelDatatype.U8); required with bytes when not using pixel_format. See Enums.

Methods

Method	Description
to_numpy()	Returns the image as a NumPy array: shape (height, width) for grayscale or (height, width, channels) for color (e.g. 3 or 4). Dtype matches the channel type (e.g. uint8). Decodes bytes if the image was stored as encoded/compressed.

Example

From the datatypes examples:

import numpy as np
from datatypes import datatypes
from loguru import logger

# ------------------------------------------------
# 1. Create Image instance (RGBA)
# ------------------------------------------------
image_rgba = np.array([
    [[255, 0, 0, 255], [0, 255, 0, 255]],
    [[0, 0, 255, 255], [255, 255, 0, 255]],
], dtype=np.uint8)
img_rgba = datatypes.Image(image=image_rgba)

# ------------------------------------------------
# 2. Access data via to_numpy (RGBA case)
# ------------------------------------------------
numpy_array = img_rgba.to_numpy()
logger.info("Image (RGBA) to_numpy shape={}", numpy_array.shape)
logger.info("Image (RGBA) to_numpy dtype={}", numpy_array.dtype)
logger.info("Image (RGBA) width={}", img_rgba.width)
logger.info("Image (RGBA) height={}", img_rgba.height)
logger.info("Image (RGBA) color_model={}", img_rgba.color_model)
logger.info("Image (RGBA) channel_datatype={}", img_rgba.channel_datatype)

# ------------------------------------------------
# 3. Create Image instance (BGR)
# ------------------------------------------------
image_bgr = np.array([
    [[255, 0, 0], [0, 255, 0]],
    [[0, 0, 255], [255, 255, 0]],
], dtype=np.uint8)
img_bgr = datatypes.Image(image=image_bgr)

# ------------------------------------------------
# 4. Access data via to_numpy (BGR case)
# ------------------------------------------------
numpy_array_bgr = img_bgr.to_numpy()
logger.info("Image (BGR) to_numpy shape={}", numpy_array_bgr.shape)
logger.info("Image (BGR) to_numpy dtype={}", numpy_array_bgr.dtype)
logger.info("Image (BGR) width={}", img_bgr.width)
logger.info("Image (BGR) height={}", img_bgr.height)