Image
SUMMARY
An image with a flexible channel layout.
python
from telekinesis import datatypes
import numpy as np
image = datatypes.Image(np.zeros((4, 4, 3), dtype=np.uint8))Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
data | np.ndarray | Required | Pixel values with shape (H, W), (H, W, 3), or (H, W, 4) and a supported dtype. |
compression | ImageCompression | int | ImageCompression.NONE | Compression codec used during serialization. Compression does not change the in-memory pixel values. |
Raises
| Exception | Condition |
|---|---|
TypeError | data isn't an np.ndarray |
ValueError | data's dtype isn't in the allowlist, its shape isn't (H, W)/(H, W, 3)/(H, W, 4), or compression isn't a valid ImageCompression member/matching int |
Supported Dtypes
| Category | Dtypes |
|---|---|
| Unsigned integer | uint8 |
| Signed integer | int32, int64 |
| Floating-point | float16, float32, float64 |
Other dtypes are not supported.
Attributes
| Attribute | Type | Description |
|---|---|---|
data | np.ndarray | Defensive copy of the pixel array. Assigning re-validates like construction. |
shape | tuple[int, ...] | (H, W), (H, W, 3), or (H, W, 4). |
height | int | First axis of shape. |
width | int | Second axis of shape. |
dtype | np.dtype | Dtype of the pixel array. |
channels | int | 1 (grayscale), 3 (RGB), or 4 (RGBA). |
compression | ImageCompression | On-wire codec. Read-only. Construct a new Image to change it. |
Methods
| Method | Type | Description |
|---|---|---|
Image.coerce(value) | Image | Converts array-like data into an Image. If value is already an Image, it is returned unchanged; otherwise a np.ndarray is wrapped the same way as the constructor. |
Image.from_raw_buffer(buffer, shape, dtype, compression=NONE) | Image | Builds an image directly from raw, already-decoded pixel bytes at the given shape and dtype, without copying. For encoded files (JPEG, PNG, ...), use from_encoded_buffer instead. |
Image.from_encoded_buffer(buffer, compression=NONE, dtype=np.uint8) | Image | Decodes an encoded image (JPEG, PNG, ...) into RGB, or RGBA if the source has transparency. Use dtype=np.uint8 for 0-255 values, or a floating dtype to get values normalized to 0.0-1.0. |
Image.from_path(path, compression=NONE, dtype=np.uint8) | Image | Reads an image file from disk and decodes it the same way as from_encoded_buffer. |
Image.from_url(url, compression=NONE, dtype=np.uint8, connect_timeout=5.0, read_timeout=30.0) | Image | Downloads an image from a URL and decodes it the same way as from_encoded_buffer, with configurable connect/read timeouts. |
expand_dims() | ImageBatch | Wraps this image in a length-1 ImageBatch for use with batch-oriented code. |
to_numpy(copy=True) | np.ndarray | Returns the pixel array. With the default copy=True you get an independent copy; pass copy=False for a direct reference to the internal array instead. |
to_rgb() | Image | Converts to 3-channel RGB. Grayscale input is returned unchanged as a copy; 3-channel input is treated as BGR and has its channel order reversed; 4-channel input is treated as BGRA, reordered to RGB, and loses its alpha channel. The result is always 3-channel. Use to_rgba() instead if you need to keep alpha. |
to_bgr() | Image | Converts to 3-channel BGR. Grayscale input is returned unchanged as a copy; 3-channel input is treated as RGB and has its channel order reversed; 4-channel input is treated as RGBA, reordered to BGR, and loses its alpha channel. The result is always 3-channel. Use to_bgra() instead if you need to keep alpha. |
to_rgba() | Image | Converts to 4-channel RGBA. Grayscale input is returned unchanged as a copy, not expanded to 4 channels. 3-channel input is treated as BGR, reversed, and given a new fully-opaque alpha channel. 4-channel input is treated as BGRA, reordered to RGBA, and keeps its existing alpha values. |
to_bgra() | Image | Converts to 4-channel BGRA. Grayscale input is returned unchanged as a copy, not expanded to 4 channels. 3-channel input is treated as RGB, reversed, and given a new fully-opaque alpha channel. 4-channel input is treated as RGBA, reordered to BGRA, and keeps its existing alpha values. |
to_grayscale(colorspace="rgb") | Image | Converts to a single-channel image using BT.601 luminance weights (0.299/0.587/0.114), dropping alpha if present. Set colorspace to "rgb" (default) or "bgr" to match the input's channel order; no other values are accepted. Already-grayscale input is returned unchanged as a copy. |
copy() | Image | Returns a new, independent Image with the same pixels and compression setting. |
save_to_path(path, format=None) | None | Encodes and writes the image to disk. Floating-point pixel data is clipped to [0, 1] and rescaled to uint8 first. The file format is inferred from the path's extension if not given explicitly. |
Operators
| Operation | Behavior |
|---|---|
img == other | Compare image content with another Image value. |
np.asarray(img) | Convert pixel data to a NumPy array with np.asarray(img). |
Visualization
python
import rerun as rr
# Your code block
# ....
rr.init("image_example", spawn=True)
datatypes.visualize(image, entity_path="/image", label="Image")Example
python
"""Demonstrates the Telekinesis Image datatype."""
import time
from pathlib import Path
import numpy as np
import rerun as rr
from loguru import logger
from telekinesis import datatypes
def image_example():
"""Demonstrate creation, inspection, operations, visualization, and serialization."""
# ======================= Create ============================================
root = Path(__file__).parent
data = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
image = datatypes.Image(data)
logger.info(f"Created Image: {image}")
buffer = data.tobytes()
image_from_raw_buffer = datatypes.Image.from_raw_buffer(buffer, shape=data.shape, dtype=data.dtype)
logger.info(f"Image created from raw buffer: {image_from_raw_buffer}")
encoded_buffer = (root / "data/sample.jpg").read_bytes()
image_from_encoded_buffer = datatypes.Image.from_encoded_buffer(encoded_buffer)
logger.info(f"Image created from encoded buffer: {image_from_encoded_buffer}")
image_from_path = datatypes.Image.from_path(root / "data/sample.jpg")
logger.info(f"Image created from path: {image_from_path}")
url = "https://assets.telekinesis.ai/examples/v1/images/screws_standing.jpg"
image_from_url = datatypes.Image.from_url(url)
logger.info(f"Image created from URL: {image_from_url}")
# ======================= Inspect ===========================================
logger.info(f"compression={image.compression}")
logger.info(f"data={image.data}")
logger.info(f"shape={image.shape}")
logger.info(f"height={image.height}")
logger.info(f"width={image.width}")
logger.info(f"channels={image.channels}")
logger.info(f"dtype={image.dtype}")
# ======================= Operations =========================================
image.data = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
logger.info(f"Updated Image: {image}")
gray_image = image_from_path.to_grayscale()
logger.info(f"Grayscale image: {gray_image}")
bgr_image = image_from_path.to_bgr()
logger.info(f"BGR image: {bgr_image}")
rgb_image = bgr_image.to_rgb()
logger.info(f"RGB image: {rgb_image}")
image_batch = image.expand_dims()
logger.info(f"Expanded to ImageBatch: {image_batch}")
image_copy = image.copy()
logger.info(f"Copied Image: {image_copy}")
image_numpy = image.to_numpy(copy=True)
logger.info(f"NumPy Image:\n{image_numpy}")
output_path = root / "data/output_image.jpg"
gray_image.save_to_path(output_path)
logger.info(f"Image saved to: {output_path}")
mean_pixel_value = np.mean(image)
flipped_image = np.flipud(image)
logger.info(f"Mean pixel value: {mean_pixel_value}")
logger.info(f"Flipped shape={flipped_image.shape}, dtype={flipped_image.dtype}")
# ======================= Visualize =========================================
rr.init("image_example", spawn=True)
datatypes.visualize(image, entity_path="/image")
datatypes.visualize(image_from_path, entity_path="/image/from_path")
datatypes.visualize(image_from_url, entity_path="/image/from_url")
datatypes.visualize(gray_image, entity_path="/image/grayscale")
datatypes.visualize(bgr_image, entity_path="/image/bgr")
datatypes.visualize(rgb_image, entity_path="/image/rgb")
# ======================= Serialize / Deserialize ===========================
start = time.perf_counter()
serialized = datatypes.serialize(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 Image: {deserialized}")
logger.info(f"Round-trip successful: {image == deserialized}")
logger.info(f"Serialization time: {serialization_ms:.3f} ms")
logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")
if __name__ == "__main__":
image_example()