`tlc.data_types.geometries`¶

2D and 3D geometry instances.

Module Contents¶

Classes¶

Class	Description
`Geometry2D`	Container for 2D geometry instances — the general form.
`Geometry3D`	Container for 3D geometry instances — the general form.

API¶

class Geometry2D¶

Bases: tlc.data_types._geometry_base.Geometry2DBase

Container for 2D geometry instances — the general form.

Supports all primitives: vertices, lines, triangles, axis-aligned bounding boxes (bounding_boxes, stored xyxy), and oriented bounding boxes (obbs). Each storage list holds one per-instance numpy array; num_instances is determined from the consistent length across all non-empty per-instance lists. The specialized classes (BoundingBoxes2D, Keypoints2D, OrientedBoundingBoxes2D) are narrower forms with a single primary array.

Serialization is handled by the geometry_2d sample type.

Objects can be created in two ways:

Direct construction: Pass all data at once.
Build incrementally: Use create_empty() and add_instance().

Example:

import numpy as np

# Direct construction — one instance with vertices + an axis-aligned bounding box
g = Geometry2D(
    vertices=[np.array([0, 0, 10, 0, 5, 10], dtype=np.float32)],
    bounding_boxes=[np.array([[0, 0, 10, 10]], dtype=np.float32)],
    labels=[3],
    confidences=[0.9],
    x_max=100, y_max=100,
)

# Build incrementally — promoted `label`/`confidence` like the specialized classes
g = Geometry2D.create_empty(x_max=100, y_max=100)
g.add_instance(
    vertices=np.array([[0, 0], [10, 0], [5, 10]], dtype=np.float32),
    lines=np.array([0, 1, 1, 2], dtype=np.int32),
    triangles=np.array([0, 1, 2], dtype=np.int32),
    label=3,
    confidence=0.9,
)

# COCO/YOLO-format bounding box input — converted to xyxy in __post_init__
g = Geometry2D(vertices=..., bounding_boxes=[xywh_arr], bounding_box_format="xywh")

# Serialization
row = g.to_row()
g = Geometry2D.from_row(row)

Note

Extras (per_point, per_line, per_triangle, per_instance) support scalars, fixed-size arrays, and composite Python objects (e.g., dicts).

Add a 2D instance.

Parameters:

vertices – Array of shape (N, 2) or flattened (2N,), dtype float32. In externalized mode, a URL string referencing a pre-existing chunk file.
per_vertex_extras – Dict of arrays of shape (N,). In externalized mode, dict of URL strings.
per_instance_extras – Dict of scalar per-instance attributes (one value or length-1 array).
lines – Flattened int array (2L,) of vertex indices forming L line segments. In externalized mode, a URL string.
triangles – Flattened int array (3T,) of vertex indices forming T triangles. In externalized mode, a URL string.
bounding_boxes – Array of shape (B, 4) or flattened (4B,), dtype float32. Not supported in externalized mode.
obbs – Array of shape (O, 5) or flattened (5O,), dtype float32. Not supported in externalized mode.
label – Optional integer class label for this instance.
confidence – Optional confidence score for this instance.
per_line_extras – Dict of arrays of shape (L,) for per-line extras. In externalized mode, dict of URL strings.
per_triangle_extras – Dict of arrays of shape (T,) for per-triangle extras. In externalized mode, dict of URL strings.

Raises:

ValueError – On shape/type/index validation errors, or on mixing externalized/materialized modes.

bounding_box_format: InitVar['xyxy' | 'xywh' | 'cxywh'] = xyxy¶: Format of the input bounding_boxes arrays. Storage is always "xyxy". Applies to every instance’s bounding_boxes array uniformly. obbs is unaffected.

bounding_boxes: list[ndarray] = field(...)¶

List of (Bi, 4) float32 arrays. Always stored as [x_min, y_min, x_max, y_max] (xyxy).

Use bounding_box_format= on the constructor to supply "xywh" (COCO) or "cxywh" (YOLO) input; conversion is applied to every instance’s array.

classmethod create_empty( *, x_min: float | None = None, y_min: float | None = None, x_max: float | None = None, y_max: float | None = None, ) → Geometry2D¶

Create an empty Geometry2D container.

Parameters:

x_min – Minimum x coordinate (optional).
y_min – Minimum y coordinate (optional).
x_max – Maximum x coordinate (optional).
y_max – Maximum y coordinate (optional).

image_height: InitVar[float | None] = None¶: Convenience parameter: sets y_max = (y_min or 0) + image_height.

image_width: InitVar[float | None] = None¶: Convenience parameter: sets x_max = (x_min or 0) + image_width.

lines: list[ndarray] = field(...)¶: List of line index arrays per instance

normalized: InitVar[bool] = False¶

Whether the input coordinates (vertices, bounding_boxes, obbs) are normalized to [0, 1].

When True, all spatial coordinates are denormalized to absolute pixel values using the image dimensions derived from bounds. Rotation in obbs is not affected. Bounds must be set. Applied after bounding_box_format conversion.

property num_instances: int¶: Return the number of geometry instances.

obbs: list[ndarray] = field(...)¶: List of (Oi, 5) float32 arrays [cx, cy, w, h, rotation]

per_line_extras: dict[str, list[ndarray]] = field(...)¶: Per-line additional data

per_triangle_extras: dict[str, list[ndarray]] = field(...)¶: Per-triangle additional data

per_vertex_extras: dict[str, list[ndarray]] = field(...)¶: Per-vertex additional data

classmethod schema( *, 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, x_min_default: float | None = None, y_min_default: float | None = None, x_max_default: float | None = None, y_max_default: float | None = None, display_name: str = '', description: str = '', writable: bool = True, default_visible: bool = True, display_importance: float = 0, ) → Schema¶

Build the column Schema describing a 2D geometry scene.

Parameters:

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 is bulk data.
x_min_default – Default scene x_min bound.
y_min_default – Default scene y_min bound.
x_max_default – Default scene x_max bound.
y_max_default – Default scene y_max bound.
display_name – Column display name in the Dashboard.
description – Column description.
writable – Whether the column is editable in the Dashboard.
default_visible – Whether the column is visible by default.
display_importance – Ordering weight for column display.

Returns:

A column schema describing the serialized form of this class.

triangles: list[ndarray] = field(...)¶: List of triangle index arrays per instance

vertices: list[ndarray] = field(...)¶: List of flattened vertex arrays per instance

class Geometry3D¶

Bases: tlc.data_types._geometry_base.Geometry3DBase

Container for 3D geometry instances — the general form.

Supports all primitives: vertices, lines, triangles, axis-aligned bounding boxes (bounding_boxes, stored xyzxyz), and oriented bounding boxes (obbs). Each storage list holds one per-instance numpy array; num_instances is determined from the consistent length across all non-empty per-instance lists. The specialized classes (BoundingBoxes3D, OrientedBoundingBoxes3D) are narrower forms with a single primary array.

Serialization is handled by the geometry_3d sample type.

Objects can be created in two ways:

Direct construction: Pass all data at once.
Build incrementally: Use create_empty() and add_instance().

Example:

import numpy as np

# Direct construction — one instance with vertices + an AABB
g = Geometry3D(
    vertices=[np.array([0, 0, 0, 1, 1, 1], dtype=np.float32)],
    bounding_boxes=[np.array([[0, 0, 0, 1, 1, 1]], dtype=np.float32)],
    labels=[1],
    confidences=[0.9],
    x_max=10, y_max=10, z_max=10,
)

# Build incrementally
g = Geometry3D.create_empty(x_max=10, y_max=10, z_max=10)
g.add_instance(
    vertices=np.array([[0, 0, 0], [1, 1, 1]], dtype=np.float32),
    label=1,
    confidence=0.9,
)

# Top-corner + size bounding box input — converted to xyzxyz in __post_init__
g = Geometry3D(vertices=..., bounding_boxes=[corner_size], bounding_box_format="xyzwhd")

# Serialization
row = g.to_row()
g = Geometry3D.from_row(row)

Note

Extras (per_point, per_line, per_triangle, per_instance) support scalars, fixed-size arrays, and composite Python objects (e.g., dicts).

Add a 3D instance.

Parameters:

vertices – Array of shape (N, 3) or flattened (3N,), dtype float32. In externalized mode, a URL string referencing a pre-existing chunk file.
lines – Flattened int array (2L,) of vertex indices forming L line segments. In externalized mode, a URL string.
triangles – Flattened int array (3T,) of vertex indices forming T triangles. In externalized mode, a URL string.
bounding_boxes – Array of shape (B, 6) or flattened (6B,), dtype float32. Not supported in externalized mode.
obbs – Array of shape (O, 9) or flattened (9O,), dtype float32. Not supported in externalized mode.
label – Optional integer class label for this instance.
confidence – Optional confidence score for this instance.
per_vertex_extras – Dict of arrays of shape (N,). In externalized mode, dict of URL strings.
per_line_extras – Dict of arrays of shape (L,) for per-line extras. In externalized mode, dict of URL strings.
per_triangle_extras – Dict of arrays of shape (T,) for per-triangle extras. In externalized mode, dict of URL strings.
per_instance_extras – Dict of scalar per-instance attributes (one value or length-1 array).

Raises:

ValueError – On shape/type/index validation errors, or on mixing externalized/materialized modes.

bounding_box_format: InitVar['xyzxyz' | 'xyzwhd'] = xyzxyz¶: Format of the input bounding_boxes arrays. Storage is always "xyzxyz". Applies to every instance’s bounding_boxes array uniformly. obbs is unaffected.

bounding_boxes: list[ndarray] = field(...)¶: List of (Bi, 6) float32 arrays. Always stored as [x_min, y_min, z_min, x_max, y_max, z_max] (xyzxyz). Use bounding_box_format= on the constructor to supply "xyzwhd" (top-corner + size) input; conversion is applied to every instance’s array.

Create an empty Geometry3D container.

Parameters:

x_min – Minimum x coordinate (optional).
x_max – Maximum x coordinate (optional).
y_min – Minimum y coordinate (optional).
y_max – Maximum y coordinate (optional).
z_min – Minimum z coordinate (optional).
z_max – Maximum z coordinate (optional).

image_height: InitVar[float | None] = None¶: Convenience parameter: sets y_max = (y_min or 0) + image_height.

image_width: InitVar[float | None] = None¶: Convenience parameter: sets x_max = (x_min or 0) + image_width.

lines: list[ndarray] = field(...)¶: List of line index arrays per instance

normalized: InitVar[bool] = False¶

Whether the input coordinates (vertices, bounding_boxes, obbs) are normalized to [0, 1].

When True, all spatial coordinates are denormalized to absolute values using the dimensions derived from bounds. Angles in obbs are not affected. Bounds must be set. Applied after bounding_box_format conversion.

property num_instances: int¶: Return the number of geometry instances.

obbs: list[ndarray] = field(...)¶: List of (Oi, 9) float32 arrays, oriented boxes per instance

per_line_extras: dict[str, list[ndarray]] = field(...)¶: Per-line additional data

per_triangle_extras: dict[str, list[ndarray]] = field(...)¶: Per-triangle additional data

per_vertex_extras: dict[str, list[ndarray]] = field(...)¶: Per-vertex additional data

classmethod schema( *, 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, x_min_default: float | None = None, y_min_default: float | None = None, z_min_default: float | None = None, x_max_default: float | None = None, y_max_default: float | None = None, z_max_default: float | None = None, display_name: str = '', description: str = '', writable: bool = True, default_visible: bool = True, display_importance: float = 0, ) → Schema¶

Build the column Schema describing a 3D geometry scene.

Parameters:

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 is bulk data.
x_min_default – Default scene x_min bound.
y_min_default – Default scene y_min bound.
z_min_default – Default scene z_min bound.
x_max_default – Default scene x_max bound.
y_max_default – Default scene y_max bound.
z_max_default – Default scene z_max bound.
display_name – Column display name in the Dashboard.
description – Column description.
writable – Whether the column is editable in the Dashboard.
default_visible – Whether the column is visible by default.
display_importance – Ordering weight for column display.

Returns:

A column schema describing the serialized form of this class.

triangles: list[ndarray] = field(...)¶: List of triangle index arrays per instance

vertices: list[ndarray] = field(...)¶: List of flattened vertex arrays per instance

tlc.data_types.geometries¶

Module Contents¶

Classes¶

API¶

`tlc.data_types.geometries`¶