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

API

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 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 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 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 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,

**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.

• 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,

**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.

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

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,

**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.

• schema_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 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.