Color

Represents an RGBA color.

Parameters

Field	Type	Description
data	np.ndarray | list | tuple	3 (RGB) or 4 (RGBA) channel values. A 3-element input is padded with a fully-opaque alpha (255) before validation.

Raises

Exception	Condition
TypeError	data isn't array-like convertible to float32
ValueError	data isn't length 3 or 4 after conversion; contains a non-finite value (NaN/Inf, per BaseTensor); or any channel is outside [0, 255]

Attributes

Attribute	Type	Description
data	np.ndarray	Defensive copy, shape (4,) float32, channels in [0, 255]. Assigning re-validates the same way as construction.
shape	tuple[int, ...]	Always (4,).
ndim	int	Always 1.
dtype	np.dtype	Always float32.
size	int	Always 4.

Methods

Method	Description
to_hex()	Returns an 8-digit hex string "#RRGGBBAA", each channel rounded to the nearest int.
Color.from_hex(hex_str)	Constructs a Color from a 6-digit (RRGGBB, alpha defaults to 255) or 8-digit (RRGGBBAA) hex string, with or without a leading #. Raises TypeError if not a str, ValueError if not 6/8 valid hex digits.
to_numpy(copy=True)	Inherited from BaseTensor. Returns the array as np.ndarray; copy=False gives a zero-copy reference.
copy()	Inherited from BaseTensor. Returns a new Color with an independent data buffer.
Color.coerce(value)	Inherited from BaseTensor. Returns value unchanged if already a Color; otherwise wraps a np.ndarray/list/tuple. Raises TypeError for anything else.

Operators

Operation	Behavior
c == other	Inherited from BaseTensor: True only if other is exactly type Color (not just any BaseTensor) with element-equal data. False/NotImplemented otherwise.
len(c)	Always 4.
np.asarray(c)	Returns a copy of the [R, G, B, A] array (values in [0, 255], not normalized). copy=False raises ValueError; use to_numpy(copy=False).
hash(c)	Not supported.
repr(c)	Overridden to "Color(#RRGGBBAA)" (equivalent to to_hex()), instead of BaseTensor's default array dump.

Visualization

datatypes.visualize(color, entity_path=...) logs the color as a 2x2-pixel RGBA rr.Image swatch (a genuine 1x1 pixel is ambiguous to rerun's shape inference, so a small patch is used instead).

Example

"""Demonstrates the Telekinesis Color datatype."""

import time

from loguru import logger
import rerun as rr

from telekinesis import datatypes

def rgba32_example():
    """Demonstrate creation, inspection, visualization, hex conversion, and serialization."""

    # ======================= Create ============================================
    rgb = [255, 0, 128]
    color = datatypes.Color(rgb)
    logger.info(f"Original Color: {color}")

    # ======================= Inspect ===========================================
    data = color.data
    shape = color.shape
    size = color.size
    dtype = color.dtype
    ndim = color.ndim
    numpy_array = color.to_numpy()
    color_copy = color.copy()

    logger.info(
        f"shape={shape}, "
        f"size={size}, "
        f"ndim={ndim}, "
        f"dtype={dtype}"
    )
    logger.info(f"Color data: {data}")
    logger.info(f"NumPy array: {numpy_array}")
    logger.info(f"Copied Color: {color_copy}")

    # ======================= Visualize =========================================
    rr.init("rgba32_example", spawn=True)
    datatypes.visualize(color, entity_path="/Color")

    # ======================= Update ============================================
    color.data = [0, 255, 255, 255]
    logger.info(f"Updated Color: {color}")
    datatypes.visualize(color, entity_path="/Color/updated")

    # ======================= From Hex ==========================================
    hex_color = "#FF00FF80"
    color_from_hex = datatypes.Color.from_hex(hex_color)
    hex_from_color = color_from_hex.to_hex()

    logger.info(f"Color from hex {hex_color}: {color_from_hex}")
    logger.info(f"Hex round-trip successful: {hex_from_color == hex_color}")
    datatypes.visualize(color_from_hex, entity_path="/Color/from_hex")

    # ======================= Serialize / Deserialize ===========================
    start = time.perf_counter()
    serialized = datatypes.serialize(color)
    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 Color: {deserialized}")
    logger.info(f"Round-trip successful: {deserialized == color}")
    logger.info(f"Serialization time: {serialization_ms:.3f} ms")
    logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")


if __name__ == "__main__":
    rgba32_example()