tlc.core.builtins.schemas.geometries

Schemas for geometric data.

This module provides reusable schema building blocks for common geometry types (2D/3D points, lines, triangles, axis-aligned and oriented boxes) and user-facing composites for keypoints and oriented bounding boxes.

Schemas describe per-instance geometry with optional per-point, per-line, per-triangle, and per-instance attributes.

Module Contents

Classes

Class	Description
BoundingBox2DSchema	Defines a single axis-aligned 2D bounding box defined by minimum and maximum values on X and Y.
BoundingBox3DSchema	Defines a single axis-aligned 3D bounding box defined by minimum and maximum values on each axis.
Geometry2DSchema	Schema root for 2D scenes with optional vertices, lines, triangles, and boxes.
Geometry3DSchema	Schema root for 3D scenes with optional points, lines, triangles, and boxes.
GeometrySchema	Base class for 2D/3D geometry collections.
Keypoints2DSchema	Defines a schema for 2D keypoint instances.
OrientedBoundingBox2DSchema	Defines a single 2D oriented bounding box defined by center position, size, and rotation (radians).
OrientedBoundingBox3DSchema	Defines a single 3D oriented bounding box defined by center position, size along each axis, and orientation (yaw, pitch, roll in radians).
OrientedBoundingBoxes2DSchema	Defines a user-facing schema for 2D oriented bounding boxes.
OrientedBoundingBoxes3DSchema	Defines a user-facing schema for 3D oriented bounding boxes.

API

class BoundingBox2DSchema(

is_list: bool = False,

**schema_kwargs: Any,

)

Bases: tlc.core.schema.Schema

Defines a single axis-aligned 2D bounding box defined by minimum and maximum values on X and Y.

class BoundingBox3DSchema(

is_list: bool = False,

**schema_kwargs: Any,

)

Bases: tlc.core.schema.Schema

Defines a single axis-aligned 3D bounding box defined by minimum and maximum values on each axis.

class Geometry2DSchema(

include_2d_vertices: bool = False,

include_lines: bool = False,

include_triangles: bool = False,

include_2d_bounding_boxes: bool = False,

include_2d_oriented_bounding_boxes: bool = False,

per_vertex_schemas: dict[str, Schema] | None = None,

per_line_schemas: dict[str, Schema] | None = None,

per_triangle_schemas: dict[str, Schema] | None = None,

per_instance_schemas: dict[str, Schema] | None = None,

is_bulk_data: bool = False,

**schema_kwargs: Any,

)

Bases: tlc.core.builtins.schemas.geometries.GeometrySchema

Schema root for 2D scenes with optional vertices, lines, triangles, and boxes.

The root includes the overall axis-aligned extent of the scene.

Parameters:

• include_2d_vertices – Whether instances include 2D vertices.

• include_lines – Whether instances include lines.

• include_triangles – Whether instances include triangles.

• include_2d_bounding_boxes – Whether instances include axis-aligned 2D boxes.

• include_2d_oriented_bounding_boxes – Whether instances include oriented 2D boxes.

• per_vertex_schemas – Additional attributes attached to each 2D vertex.

• per_line_schemas – Additional attributes attached to each line.

• per_triangle_schemas – Additional attributes attached to each triangle.

• per_instance_schemas – Additional attributes attached per instance.

• is_bulk_data – Declares that the data described by the Schema is bulk data. This will force any data added using a TableWriter to be stored as bulk data.

• schema_kwargs – Additional keyword arguments forwarded to the base Schema.

class Geometry3DSchema(

include_3d_vertices: bool = False,

include_lines: bool = False,

include_triangles: bool = False,

include_3d_bounding_boxes: bool = False,

include_3d_oriented_bounding_boxes: bool = False,

per_vertex_schemas: dict[str, Schema] | None = None,

per_triangle_schemas: dict[str, Schema] | None = None,

per_line_schemas: dict[str, Schema] | None = None,

per_instance_schemas: dict[str, Schema] | None = None,

is_bulk_data: bool = False,

**schema_kwargs: Any,

)

Bases: tlc.core.builtins.schemas.geometries.GeometrySchema

Schema root for 3D scenes with optional points, lines, triangles, and boxes.

The root includes the overall axis-aligned extent of the scene.

Parameters:

• include_3d_vertices – Whether instances include 3D vertices.

• include_lines – Whether instances include lines.

• include_triangles – Whether instances include triangles.

• include_3d_bounding_boxes – Whether instances include axis-aligned 3D boxes.

• include_3d_oriented_bounding_boxes – Whether instances include oriented 3D boxes.

• per_vertex_schemas – Additional attributes attached to each 3D vertex.

• per_triangle_schemas – Additional attributes attached to each triangle.

• per_line_schemas – Additional attributes attached to each line.

• per_instance_schemas – Additional attributes attached per instance.

• is_bulk_data – Declares that the data described by the Schema is bulk data. This will force any data added using a TableWriter to be stored as bulk data.

• schema_kwargs – Additional keyword arguments forwarded to the base Schema.

class GeometrySchema(

include_triangles: bool = False,

include_lines: bool = False,

per_line_schemas: dict[str, Schema] | None = None,

per_triangle_schemas: dict[str, Schema] | None = None,

per_instance_schemas: dict[str, Schema] | None = None,

is_bulk_data: bool = False,

**kwargs: Any,

)

Bases: tlc.core.schema.Schema

Base class for 2D/3D geometry collections.

Each instance can optionally include points, lines, and triangles with additional per-element attributes. Per-instance attributes can also be attached, for example labels and confidences.

Parameters:

• include_lines – Whether instances include lines.

• include_triangles – Whether instances include triangles.

• per_line_schemas – Additional attributes attached to each line.

• per_triangle_schemas – Additional attributes attached to each triangle.

• per_instance_schemas – Additional attributes attached per instance.

• is_bulk_data – Declares that the data described by the Schema is bulk data. This will force any data added using a TableWriter to be stored as bulk data.

• kwargs – Additional keyword arguments forwarded to the base Schema.

class Keypoints2DSchema(

classes: str | Sequence[str] | Sequence[dict[str, str]] | Sequence[MapElement] | dict[float, str] | dict[int, str] | dict[float, MapElement] | dict[int, MapElement] | None,

num_keypoints: int,

points: list[float] | list[list[float]] | ndarray | None = None,

point_attributes: list[str] | list[dict[str, Any]] | None = None,

lines: list[int] | list[list[int]] | ndarray | None = None,

line_attributes: list[str] | list[dict[str, Any]] | None = None,

triangles: list[int] | list[list[int]] | ndarray | None = None,

triangle_attributes: list[str] | list[dict[str, Any]] | None = None,

flip_indices: list[int] | None = None,

oks_sigmas: list[float] | None = None,

include_per_point_confidence: bool = False,

include_per_point_visibility: bool = False,

include_per_instance_label: bool = True,

include_per_instance_confidence: bool = False,

per_instance_schemas: dict[str, Schema] | None = None,

**schema_kwargs: Any,

)

Bases: tlc.core.builtins.schemas.geometries.Geometry2DSchema

Defines a schema for 2D keypoint instances.

Adds a default set of points per instance and can include a default connectivity (lines) and mesh faces (triangles). Axis-aligned 2D boxes and per-instance labels are included by default.

Parameters:

• classes – Class map or a single class name for per-instance labels, or None to skip labels.

• num_keypoints – Number of keypoints (> 0).

• points – Default relative keypoint coordinates used when creating new instances. Inputs may be nested; values are flattened internally. The flattened length must be num_keypoints*2 in the order [x0, y0, …, xN-1, yN-1].

• point_attributes – Per-point role names in the same order as keypoints; defaults to [“kpt_0”, …, “kpt_{N-1}”].

• lines – Default connectivity as index pairs. Inputs may be nested; values are flattened internally to [i0, j0, i1, j1, …].

• line_attributes – Per-line role names matching the number of line pairs.

• triangles – Default triangle faces as index triples. Inputs may be nested; values are flattened internally to [i0, j0, k0, i1, j1, k1, …].

• triangle_attributes – Per-triangle role names matching the number of triangle triples.

• flip_indices – Indices used for horizontal-flip augmentation; stored with the points metadata.

• oks_sigmas – Object Keypoint Similarity (OKS) sigmas; defaults to uniform [1/num_keypoints] repeated num_keypoints times; stored with the points metadata.

• include_per_point_confidence – Whether to add a per-point confidence score (read-only).

• include_per_point_visibility – Whether to add a per-point visibility score with categories 0.0=undefined, 1.0=occluded, 2.0=visible.

• include_per_instance_label – Whether to add a per-instance label.

• include_per_instance_confidence – Whether to add a per-instance confidence score.

• per_instance_schemas – Additional per-instance attributes.

• schema_kwargs – Additional keyword arguments forwarded to the base Schema.

Raises:

ValueError – If num_keypoints <= 0.

class OrientedBoundingBox2DSchema(

is_list: bool = False,

**schema_kwargs: Any,

)

Bases: tlc.core.schema.Schema

Defines a single 2D oriented bounding box defined by center position, size, and rotation (radians).

class OrientedBoundingBox3DSchema(

is_list: bool = False,

**schema_kwargs: Any,

)

Bases: tlc.core.schema.Schema

Defines a single 3D oriented bounding box defined by center position, size along each axis, and orientation (yaw, pitch, roll in radians).

class OrientedBoundingBoxes2DSchema(

classes: str | Sequence[str] | Sequence[dict[str, str]] | Sequence[MapElement] | dict[float, str] | dict[int, str] | dict[float, MapElement] | dict[int, MapElement] | None,

include_per_instance_label: bool = True,

include_per_instance_confidence: bool = False,

per_instance_schemas: dict[str, Schema] | None = None,

**schema_kwargs: Any,

)

Bases: tlc.core.builtins.schemas.geometries.Geometry2DSchema

Defines a user-facing schema for 2D oriented bounding boxes.

By default this schema includes oriented 2D boxes and a label per object. It exposes the same include/override options as the 2D geometry schema so callers can flexibly add points, lines, triangles, or axis-aligned boxes.

Parameters:

• classes – Class map or a single class name for instance labels, or None to skip labels.

• include_per_instance_label – Whether to add a per-instance label.

• include_per_instance_confidence – Whether to add a per-instance confidence score.

• per_instance_schemas – Additional per-instance schemas.

• schema_kwargs – Additional keyword arguments forwarded to base Schema.

class OrientedBoundingBoxes3DSchema(

classes: str | Sequence[str] | Sequence[dict[str, str]] | Sequence[MapElement] | dict[float, str] | dict[int, str] | dict[float, MapElement] | dict[int, MapElement] | None,

include_per_instance_label: bool = True,

include_per_instance_confidence: bool = False,

per_instance_schemas: dict[str, Schema] | None = None,

**schema_kwargs: Any,

)

Bases: tlc.core.builtins.schemas.geometries.Geometry3DSchema

Defines a user-facing schema for 3D oriented bounding boxes.

By default this schema includes oriented 3D boxes and a label per object. It exposes the same include/override options as the 3D geometry schema so callers can flexibly add points, lines, triangles, or axis-aligned boxes.

Parameters:

• classes – Class map or a single class name for instance labels, or None to skip labels.

• include_per_instance_label – Whether to add a per-instance label.

• include_per_instance_confidence – Whether to add a per-instance confidence score.

• per_instance_schemas – Additional per-instance schemas.

• schema_kwargs – Additional keyword arguments forwarded to base Schema.