tlc.helpers.annotation_helper¶

Annotation column discovery and inspection.

Provides AnnotationHelper and AnnotationColumn for locating annotation columns in a table without hard-coding column names or schema field names. The structural shape (legacy bb_list, new geometry sample types, segmentation RLEs, etc.) is enough to identify the annotation type and its label path.

Module Contents¶

Classes¶

Class

Description

AnnotationColumn

Structural view of an annotation column.

AnnotationHelper

Discover and inspect annotation columns in a table without depending on column names or schema constants.

AnnotationType

Supported annotation column types.

API¶

class AnnotationColumn¶

Structural view of an annotation column.

Variables:

  • name – Top-level column name in the table.

  • type – The detected annotation type.

  • label_path – Full dot-separated path to the label leaf, or None if the column has no label field.

label_path: str | None = None¶
name: str = None¶
type: AnnotationType = None¶
class AnnotationHelper¶

Discover and inspect annotation columns in a table without depending on column names or schema constants.

static find(
table: Table,
*,
type: AnnotationType | None = None,
) → AnnotationColumn | None¶

Locate the annotation column in a table.

The detection is purely structural — column names are not consulted; sample-type config and well-known sub-field names are. Asking for type=BOUNDING_BOXES matches both new and legacy bounding box columns; type=LEGACY_BOUNDING_BOXES matches legacy only. All other type filters are exact.

Parameters:

  • table – The table to inspect.

  • type – Optional type filter. If omitted, any annotation column matches.

Returns:

The single matching AnnotationColumn, or None if no annotation column matches.

Raises:

ValueError – If more than one column matches. The error lists the candidate names; pass AnnotationHelper.get() with an explicit column_name to disambiguate.

static get(
table: Table,
column_name: str,
) → AnnotationColumn¶

Classify a known annotation column by name.

Parameters:

  • table – The table containing the column.

  • column_name – Top-level column name.

Returns:

The AnnotationColumn view of the column.

Raises:

  • KeyError – If the column does not exist in the table.

  • ValueError – If the column exists but is not annotation-shaped.

class AnnotationType¶

Bases: enum.Enum

Supported annotation column types.

BOUNDING_BOXES = bounding_boxes¶
KEYPOINTS = keypoints¶
LEGACY_BOUNDING_BOXES = legacy_bounding_boxes¶
ORIENTED_BOUNDING_BOXES = oriented_bounding_boxes¶
SEGMENTATION = segmentation¶