Categories

SUMMARY

A collection of COCO-style object categories.

from telekinesis import datatypes
categories = datatypes.Categories(
    ids=[1, 2, 3], names=["person", "bicycle", "car"], supercategories=["person", "vehicle", "vehicle"]
)

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
ids	array-like	Required	(N,) category ids.
names	array-like	Required	(N,) category names. Elements are stored as given and are not individually coerced to str.
supercategories	array-like	Required	(N,) supercategory names. Elements are stored as given and are not individually coerced to str.

Raises

Exception	Condition
ValueError	names or supercategories doesn't have the same length as ids (N = len(ids)).

Attributes

Attribute	Type	Description
ids	np.ndarray	Defensive copy, shape (N,) int32, category ids.
names	np.ndarray	Defensive copy, shape (N,) object/str, category names.
supercategories	np.ndarray	Defensive copy, shape (N,) object/str, supercategory names.

Methods

Method	Type	Description
Categories.coerce(value)	Categories	Converts a dict or an existing Categories into one. If value is already a Categories, it is returned unchanged; a dict with ids, names, and supercategories keys is unpacked into the constructor.

Operators

Operation	Behavior
len(cats)	Number of categories N in the table.
cats[i]	An int returns the Category at that position (0-based; negative indices wrap like a Python list). This is positional indexing, not a lookup by category id. A slice or boolean np.ndarray mask returns a new Categories sub-table. Raises IndexError for an out-of-range int, ValueError for a wrong-length boolean mask, or TypeError for any other index type.
a == b	True only if b is also a Categories with equal ids, names, and supercategories (element-wise); NotImplemented if b isn't a Categories.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("categories_example", spawn=True)
datatypes.visualize(categories, entity_path="/categories", label="Categories")

Example

"""Demonstrates the Telekinesis Categories datatype."""

import time

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

from telekinesis import datatypes

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

    # ======================= Create ============================================
    categories = datatypes.Categories(
        ids=np.array([1, 2, 3], dtype=np.int32),
        names=np.array(["person", "bicycle", "car"]),
        supercategories=np.array(["person", "vehicle", "vehicle"]),
    )
    logger.info(f"Created Categories: {categories}")

    # ======================= Inspect ===========================================
    logger.info(f"ids={categories.ids}")
    logger.info(f"names={categories.names}")
    logger.info(f"supercategories={categories.supercategories}")

    # ======================= Operations =========================================
    logger.info(f"length={len(categories)}")

    # int indexing returns the Category at that position (not an id lookup)
    index = 1
    logger.info(f"categories[{index}] = {categories[index]}")

    sliced = categories[0:2]
    logger.info(f"categories[0:2] = {sliced}")

    mask = categories.ids >= 2
    masked = categories[mask]
    logger.info(f"categories[ids >= 2] = {masked}")

    # Categories is immutable; build a new instance to add or change entries.
    updated = datatypes.Categories(
        ids=np.append(categories.ids, 4),
        names=np.append(categories.names, "traffic light"),
        supercategories=np.append(categories.supercategories, "outdoor"),
    )
    logger.info(f"Updated Categories: {updated}")

    order = np.argsort(-updated.ids)
    logger.info(f"Categories ranked by id (descending): {updated.names[order]}")

    # ======================= Visualize =========================================
    rr.init("categories_example", spawn=True)
    datatypes.visualize(categories, entity_path="/categories/original")
    datatypes.visualize(updated, entity_path="/categories/updated")

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


if __name__ == "__main__":
    categories_example()