COCOObjectDetectionResult

SUMMARY

A single COCO-style object detection or instance segmentation result.

from telekinesis import datatypes
result = datatypes.COCOObjectDetectionResult(
    image_id=7,
    category_id=1,
    image_height=720,
    image_width=1280,
    score=0.95,
    bbox=[0, 0, 10, 10]
)

API Reference

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

View Reference →

Parameters

Parameter	Type	Default	Description
image_id	int	Required	Identifier of the source image.
category_id	int	Required	Identifier of the detected category.
image_height	int	Required	Height of the source image in pixels. Must be positive.
image_width	int	Required	Width of the source image in pixels. Must be positive.
score	float	Required	Detection confidence score. Must be greater than or equal to 0.
bbox	np.ndarray | list[float] | list[int] | None	None	Optional bounding box [x, y, width, height] with shape (4,). Width and height must be non-negative. At least one of bbox or segmentation must be provided.
segmentation	COCORLESegmentationLike | None	None	Optional compressed or uncompressed COCO RLE segmentation. The value is normalized to compressed RLE during construction. At least one of bbox or segmentation must be provided.

Raises

Exception	Condition
TypeError	segmentation is present but isn't a dict with size/counts keys, or counts is none of str, bytes, or list[int].
ValueError	Both bbox and segmentation are None.
ValueError	bbox is provided but doesn't have shape (4,), contains a non-finite value, or has negative width/height.
ValueError	image_height or image_width is <= 0.
ValueError	score is negative or non-finite.
ValueError	segmentation is structurally invalid (non-positive size, negative RLE counts, non-UTF-8 encoded counts bytes), or its size doesn't match (image_height, image_width).

Attributes

Attribute	Type	Description
image_id	int	Source image id.
category_id	int	Category id.
image_height	int	Source image height.
image_width	int	Source image width.
score	float	Detection confidence score.
bbox	np.ndarray | None	Defensive copy of the box, shape (4,), [x, y, w, h], or None.
segmentation	COCORLESegmentation | None	Defensive copy of the canonical encoded COCO RLE dict, or None.

Methods

Method	Type	Description
COCOObjectDetectionResult.coerce(value)	COCOObjectDetectionResult	Converts a dict or an existing COCOObjectDetectionResult into one. If value is already a COCOObjectDetectionResult, it is returned unchanged; a dict is unpacked into the constructor as keyword arguments.
COCOObjectDetectionResult.from_mask(*, image_id, category_id, score, mask, bbox=None)	COCOObjectDetectionResult	Builds one directly from a binary mask (np.ndarray or SegmentationImage) instead of hand-building a segmentation; image_height/image_width are filled in from the mask's shape automatically.
COCOObjectDetectionResult.from_polygon(*, image_id, category_id, image_height, image_width, score, polygon, bbox=None)	COCOObjectDetectionResult	Builds one from one or more flattened [x1, y1, x2, y2, ...] polygons, rasterizing them to RLE at the given (image_height, image_width).
as_mask()	COCOObjectDetectionResultAsMask	Returns this result with its segmentation expressed as a binary mask instead of RLE.
as_polygon(min_points=3, epsilon=0.0)	COCOObjectDetectionResultAsPolygon	Returns this result with its segmentation expressed as polygon contours instead of RLE. min_points drops any extracted polygon with fewer vertices; epsilon, if positive, simplifies each contour by that tolerance.
COCOObjectDetectionResult.mask_to_rle(mask)	COCORLESegmentation	Encodes a binary mask into a canonical RLE segmentation.
COCOObjectDetectionResult.polygon_to_rle(polygon, *, height, width)	COCORLESegmentation	Rasterizes one or more polygons (COCOPolygonSegmentationLike) onto a canvas of the given height and width, then encodes the result as a canonical RLE segmentation.
COCOObjectDetectionResult.rle_to_mask(rle)	np.ndarray	Decodes an RLE segmentation (COCORLESegmentationLike) back into a binary mask, shape (H, W) and dtype uint8.
COCOObjectDetectionResult.rle_to_polygon(rle, *, min_points=3, epsilon=0.0)	COCOPolygonSegmentation	Approximates an RLE segmentation (COCORLESegmentationLike) as a polygon by decoding it to a mask, filling any holes, and tracing its outer contours via marching squares.

Operators

Operation	Behavior
a == b	Compare with another COCOObjectDetectionResult value.

Representations

Representation	Method	Result
Mask	as_mask()	COCOObjectDetectionResultAsMask
Polygon	as_polygon(min_points=3, epsilon=0.0)	COCOObjectDetectionResultAsPolygon

Visualization

import rerun as rr

# Your code block
# ....

rr.init("coco_object_detection_result_example", spawn=True)
datatypes.visualize(result, entity_path="/result", label="COCOObjectDetectionResult")

Example

"""Demonstrates the Telekinesis COCOObjectDetectionResult datatype."""

import time

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

from telekinesis import datatypes

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

    # ======================= Create ============================================
    # Segmentation is always stored canonically as encoded COCO RLE, regardless
    # of input format. The plain constructor accepts an already-encoded RLE
    # dict directly; `mask_to_rle` builds one from a mask here.
    image_height, image_width = 720, 1280
    mask = np.zeros((image_height, image_width), dtype=np.uint8)
    mask[0:10, 0:10] = 1
    result = datatypes.COCOObjectDetectionResult(
        image_id=7,
        category_id=1,
        image_height=image_height,
        image_width=image_width,
        score=0.95,
        bbox=[0, 0, 10, 10],
        segmentation=datatypes.COCOObjectDetectionResult.mask_to_rle(mask),
    )
    logger.info(f"Created COCOObjectDetectionResult: {result}")

    result_from_polygon = datatypes.COCOObjectDetectionResult.from_polygon(
        image_id=7,
        category_id=2,
        image_height=image_height,
        image_width=image_width,
        score=0.82,
        polygon=[[20, 20, 25, 20, 25, 25, 20, 25]],
        bbox=[20, 20, 5, 5],
    )
    logger.info(f"COCOObjectDetectionResult created from polygon: {result_from_polygon}")

    mask_for_result = np.zeros((image_height, image_width), dtype=np.uint8)
    mask_for_result[100:200, 150:400] = 1
    result_from_mask = datatypes.COCOObjectDetectionResult.from_mask(
        image_id=7,
        category_id=3,
        score=0.71,
        mask=mask_for_result,
    )
    logger.info(f"COCOObjectDetectionResult created from mask: {result_from_mask}")

    # ======================= Inspect ===========================================
    logger.info(f"image_id={result.image_id}")
    logger.info(f"category_id={result.category_id}")
    logger.info(f"image_height={result.image_height}")
    logger.info(f"image_width={result.image_width}")
    logger.info(f"score={result.score}")
    logger.info(f"bbox={result.bbox}")
    logger.info(f"segmentation={result.segmentation}")

    # ======================= Operations =========================================
    result_as_mask = result.as_mask()
    logger.info(
        f"Segmentation as mask: shape={result_as_mask['segmentation'].shape}, "
        f"dtype={result_as_mask['segmentation'].dtype}"
    )

    result_as_polygon = result.as_polygon()
    logger.info(f"Segmentation as polygon: {result_as_polygon['segmentation']}")

    # Mixin helpers shared across all COCO segmentation datatypes.
    mask_from_rle = datatypes.COCOObjectDetectionResult.rle_to_mask(result.segmentation)
    logger.info(f"Mask decoded via rle_to_mask: shape={mask_from_rle.shape}, dtype={mask_from_rle.dtype}")

    polygon_from_rle = datatypes.COCOObjectDetectionResult.rle_to_polygon(result.segmentation)
    logger.info(f"Polygon decoded via rle_to_polygon: {polygon_from_rle}")

    rle_from_polygon = datatypes.COCOObjectDetectionResult.polygon_to_rle(
        [[20, 20, 25, 20, 25, 25, 20, 25]], height=image_height, width=image_width
    )
    logger.info(f"RLE encoded via polygon_to_rle: {rle_from_polygon}")

    # ======================= Visualize =========================================
    rr.init("coco_object_detection_result_example", spawn=True)
    datatypes.visualize(result, entity_path="/coco_object_detection_result")
    datatypes.visualize(result_from_polygon, entity_path="/coco_object_detection_result/from_polygon")
    datatypes.visualize(result_from_mask, entity_path="/coco_object_detection_result/from_mask")

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


if __name__ == "__main__":
    coco_object_detection_result_example()