`tlc.core.helpers.keypoint_helper`¶

Utilities for reading keypoint-related attributes from 3LC Tables.

Provides helpers to fetch shapes, default points, skeleton lines, triangles, and metadata (e.g., OKS sigmas, flip indices). Follows 3LC conventions so callers do not need to know schema details.

Module Contents¶

Classes¶

Class	Description
`KeypointHelper`	Static helpers to read keypoint geometry and metadata from 3LC Tables.

API¶

class KeypointHelper¶

Static helpers to read keypoint geometry and metadata from 3LC Tables.

Includes COCO defaults (names, skeleton, colors, flip indices) for convenience.

COCO_KEYPOINT_NAMES: ClassVar[list[str]] = ['nose', 'left_eye', 'right_eye', 'left_ear', 'right_ear', 'left_shoulder', 'right_shoulder', 'left_...¶: Names of the 17 COCO person keypoints.

COCO_KEYPOINT_DEFAULT_POSE: ClassVar[list[float]] = [0.5, 0.15, 0.47, 0.14, 0.53, 0.14, 0.45, 0.15, 0.55, 0.15, 0.4, 0.25, 0.6, 0.25, 0.38, 0.4, 0.62, 0...¶

COCO_SKELETON: ClassVar[list[int]] = [3, 1, 4, 2, 1, 0, 0, 2, 5, 6, 5, 7, 6, 8, 7, 9, 8, 10, 11, 12, 11, 13, 12, 14, 13, 15, 14, 16, 5, 1...¶: Default skeleton of the 17 COCO person keypoints.

COCO_SKELETON_COLORS: ClassVar[list[tuple[int, int, int]]] = [(102, 204, 255), (51, 153, 255), (102, 0, 204), (51, 102, 255), (255, 128, 0), (153, 255, 204), (12...¶: Colors for the COCO skeleton line segments.

COCO_SKELETON_NAMES: ClassVar[list[str]] = ['left_ear_to_left_eye', 'right_ear_to_right_eye', 'left_eye_to_nose', 'nose_to_right_eye', 'left_sh...¶: Names for the COCO skeleton line segments.

COCO_FLIP_INDICES: ClassVar[list[int]] = [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15]¶: Flip indices for the COCO person keypoints.

static get_keypoint_shape_from_table( table: Table, label_column_name: str = KEYPOINTS_2D, ) → list[int] | None¶

Return [num_keypoints, num_channels] inferred from the table, or None.

Channels: 2 => x,y only; 3 => x,y plus an extra channel (e.g., visibility).

static get_points_from_table( table: Table, label_column_name: str = KEYPOINTS_2D, ) → list[float] | None¶: Return default vertex coordinates ([x0, y0, …]) or None.

static get_keypoint_attributes_from_table( table: Table, label_column_name: str = KEYPOINTS_2D, ) → list[dict[str, Any]] | None¶: Return keypoint attribute dicts (e.g., names/ids) from the schema, or None.

static get_lines_from_table( table: Table, label_column_name: str = KEYPOINTS_2D, ) → list[int] | None¶: Return flattened skeleton index pairs [i0, j0, i1, j1, …], or None.

static get_line_attributes_from_table( table: Table, label_column_name: str = KEYPOINTS_2D, ) → list[dict[str, Any]] | None¶: Return line attribute dicts (matching the skeleton order), or None.

static get_triangles_from_table( table: Table, label_column_name: str = KEYPOINTS_2D, ) → list[int] | None¶: Return flattened triangle index triplets [i, j, k, …], or None.

static get_triangle_attributes_from_table( table: Table, label_column_name: str = KEYPOINTS_2D, ) → list[dict[str, Any]] | None¶: Return triangle attribute dicts (matching the triangle order), or None.

static get_oks_sigmas_from_table( table: Table, label_column_name: str = KEYPOINTS_2D, ) → list[float] | None¶: Return OKS sigma values list, or None.

static get_flip_indices_from_table( table: Table, label_column_name: str = KEYPOINTS_2D, ) → list[int] | None¶: Return horizontal flip index mapping list, or None.

static flatten_points( points: Sequence[float] | Sequence[Sequence[float]] | ndarray, ) → list[float]¶

Returns a flat list of points.

Parameters:: points – Can be lists of (x,y) or (x, y, z), numpy arrays or nested lists.
Returns:: A flat list of points

static flatten_lines( lines: Sequence[int] | Sequence[Sequence[int]] | ndarray, ) → list[int]¶

Returns a flat list of lines.

Parameters:: lines – Can be lists of (i0, j0, i1, j1, …), numpy arrays or nested lists.
Returns:: A flat list of lines

static flatten_triangles( triangles: Sequence[int] | Sequence[Sequence[int]] | ndarray, ) → list[int]¶

Returns a flat list of triangles.

Parameters:: triangles – Can be lists of (i, j, k, …), numpy arrays or nested lists.
Returns:: A flat list of triangles

static parse_keypoints_with_visibility( keypoints: list[float] | list[list[float]] | list[tuple[float, float]] | ndarray, ) → tuple[ndarray, ndarray | None]¶

Parse keypoints in various formats, extracting coordinates and optional visibility.

Parameters:

keypoints –

Keypoints in one of these formats:

Flat list: [x1, y1, x2, y2, …] or [x1, y1, v1, x2, y2, v2, …]
List of pairs: [[x1, y1], [x2, y2], …]
List of triplets: [[x1, y1, v1], [x2, y2, v2], …]
NumPy array of shape (K, 2) or (K, 3)

Returns:

Tuple of (keypoints_array, visibility_array)

keypoints_array: shape (K, 2) with x,y coordinates
visibility_array: shape (K,) with visibility flags, or None if not present

static parse_bbox( bbox: list[float] | tuple[float, float, float, float] | ndarray, format: str = 'xyxy', ) → ndarray¶

Parse bounding box in various formats.

Parameters:

bbox – Bounding box as list, tuple, or array
format – Currently only “xyxy” is supported

Returns:

Array of shape (1, 4) with [x_min, y_min, x_max, y_max]

Parse and validate per-keypoint visibility or confidence channel.

Parameters:

num_keypoints – Expected number of keypoints
visibility – Optional visibility values
confidence – Optional confidence values
derived_visibility – Optional visibility derived from keypoint parsing

Returns:

Tuple of (visibility_array, confidence_array), both shape (1, K) or None

Raises:

ValueError – If both visibility and confidence are provided

static edit_oks_sigmas( table: Table, oks_sigmas: list[float] | None = None, label_column_name: str = KEYPOINTS_2D, table_name: str = 'edited_oks_sigmas', *, table_url: Url | None = None, ) → Table¶

Edit the OKS sigmas for a keypoint column in a Table.

Parameters:

table – The Table to edit
oks_sigmas – The new OKS sigmas
label_column_name – The name of the keypoint column to edit
table_name – The name of the new table
table_url – The URL of the new table

Returns:

The edited Table

static edit_default_keypoints( table: Table, keypoints: list[float] | list[list[float]] | list[tuple[float, float]] | ndarray, label_column_name: str = KEYPOINTS_2D, table_name: str = 'edited_default_keypoints', *, table_url: Url | None = None, ) → Table¶

Edit the default keypoints for a keypoint column in a Table.

The default keypoint values will be stored in the Table’s rows schema and used for drawing new instances in the 3LC Dashboard.

Parameters:

table – The Table to edit
keypoints – The new keypoints
label_column_name – The name of the keypoint column to edit
table_name – The name of the new table
table_url – The URL of the new table

Returns:

The edited Table

static edit_default_lines( table: Table, lines: list[int] | list[list[int]] | ndarray, label_column_name: str = KEYPOINTS_2D, table_name: str = 'edited_default_lines', *, table_url: Url | None = None, ) → Table¶: Edit the default lines for a keypoint column in a Table.

tlc.core.helpers.keypoint_helper¶

Module Contents¶

Classes¶

API¶

`tlc.core.helpers.keypoint_helper`¶