tlc.core.data_formats.geometries

2D and 3D geometry instances.

Module Contents

Classes

Class

Description

Geometry2DInstances

Container for 2D geometry instances.

Geometry3DInstances

Container for 3D geometry instances.

API

class Geometry2DInstances

Container for 2D geometry instances.

Supports all primitives: vertices, lines, triangles, axis-aligned bounding boxes, and oriented bounding boxes.

Note

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

x_min: float = None

Minimum x coordinate of the 2D bounds

y_min: float = None

Minimum y coordinate of the 2D bounds

x_max: float = None

Maximum x coordinate of the 2D bounds

y_max: float = None

Maximum y coordinate of the 2D bounds

vertices: list[ndarray] = None

List of (Ni, 2) float32 arrays (flattened to 2Ni)

per_vertex_extras: dict[str, list[ndarray]] = None

Mapping from extra name to list of (Ni,) arrays

lines: list[ndarray] = None

List of (Li,) int32 arrays of vertex indices (flattened pairs)

per_line_extras: dict[str, list[ndarray]] = None

Mapping from extra name to list of (Li,) arrays

triangles: list[ndarray] = None

List of (Ti,) int32 arrays of vertex indices (flattened triples)

per_triangle_extras: dict[str, list[ndarray]] = None

Mapping from extra name to list of (Ti,) arrays

bbs_2d: list[ndarray] = None

List of (Bi, 4) float32 arrays [x_min, y_min, x_max, y_max]

oriented_bbs_2d: list[ndarray] = None

List of (Oi, 5) float32 arrays [cx, cy, w, h, rotation]

per_instance_extras: dict[str, ndarray] = None

Mapping from extra name to (num_instances,) arrays

classmethod create_empty(
x_min: float = 0.0,
y_min: float = 0.0,
x_max: float = 0.0,
y_max: float = 0.0,
per_vertex_extras_keys: Sequence[str] | None = None,
per_line_extras_keys: Sequence[str] | None = None,
per_triangle_extras_keys: Sequence[str] | None = None,
instance_extras_keys: Sequence[str] | None = None,
) → Geometry2DInstances

Create an empty Geometry2DInstances container.

Parameters:

  • x_min – Minimum x coordinate (default 0.0)

  • y_min – Minimum y coordinate (default 0.0)

  • x_max – Maximum x coordinate

  • y_max – Maximum y coordinate

  • per_vertex_extras_keys – Sequence of keys for per-vertex additional data to initialize

  • per_line_extras_keys – Sequence of keys for per-line additional data to initialize

  • per_triangle_extras_keys – Sequence of keys for per-triangle additional data to initialize

  • instance_extras_keys – Sequence of keys for per-instance additional data to initialize

Raises:

ValueError – If bounds are invalid (e.g., x_max < x_min)

add_instance(
vertices: ndarray,
lines: ndarray | None = None,
triangles: ndarray | None = None,
bbs_2d: ndarray | None = None,
oriented_bbs_2d: ndarray | None = None,
per_vertex_extras: Mapping[str, ndarray] | None = None,
per_line_extras: Mapping[str, ndarray] | None = None,
per_triangle_extras: Mapping[str, ndarray] | None = None,
per_instance_extras: Mapping[str, Any] | None = None,
) → None

Add a 2D instance.

Parameters:

  • vertices – Array of shape (N, 2) or flattened (2N,), dtype float32

  • per_vertex_extras – Dict of arrays of shape (N,)

  • 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

  • triangles – Flattened int array (3T,) of vertex indices forming T triangles

  • bbs_2d – Array of shape (B, 4) or flattened (4B,), dtype float32

  • oriented_bbs_2d – Array of shape (O, 5) or flattened (5O,), dtype float32

  • per_line_extras – Dict of arrays of shape (L,) for per-line extras

  • per_triangle_extras – Dict of arrays of shape (T,) for per-triangle extras

Raises:

ValueError – On shape/type/index validation errors

to_row() → dict[str, Any]

Convert to the internal 3LC row format used by Geometry2D columns.

classmethod from_row(
row: Mapping[str, Any],
) → Geometry2DInstances

Parse a Geometry2D row into a Geometry2DInstances object.

Parameters:

row – Row dictionary with INSTANCES, X_MIN, Y_MIN, X_MAX, Y_MAX keys

Raises:

ValueError – If bounds are missing or invalid

class Geometry3DInstances

Container for 3D geometry instances.

Supports all primitives: vertices, lines, triangles, axis-aligned bounding boxes, and oriented bounding boxes.

Note

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

x_min: float = None

Minimum x coordinate of the 3D bounds

y_min: float = None

Minimum y coordinate of the 3D bounds

z_min: float = None

Minimum z coordinate of the 3D bounds

x_max: float = None

Maximum x coordinate of the 3D bounds

y_max: float = None

Maximum y coordinate of the 3D bounds

z_max: float = None

Maximum z coordinate of the 3D bounds

vertices: list[ndarray] = None

List of (Ni, 3) float32 arrays, vertices for each instance

per_vertex_extras: dict[str, list[ndarray]] = None

Per-vertex extras mapped by key, list per instance

lines: list[ndarray] = None

List of (Li,) int32 arrays, line index pairs per instance

per_line_extras: dict[str, list[ndarray]] = None

Per-line extras mapped by key, list per instance

triangles: list[ndarray] = None

List of (Ti,) int32 arrays, triangle index triples per instance

per_triangle_extras: dict[str, list[ndarray]] = None

Per-triangle extras mapped by key, list per instance

bbs_3d: list[ndarray] = None

List of (Bi, 6) float32 arrays, AABB [x_min,y_min,z_min,x_max,y_max,z_max]

oriented_bbs_3d: list[ndarray] = None

List of (Oi, 9) float32 arrays, oriented boxes per instance

per_instance_extras: dict[str, ndarray] = None

Per-instance extras, arrays of shape (num_instances, …)

classmethod create_empty(
x_min: float = 0.0,
x_max: float = 0.0,
y_min: float = 0.0,
y_max: float = 0.0,
z_min: float = 0.0,
z_max: float = 0.0,
per_vertex_extras_keys: Sequence[str] | None = None,
per_line_extras_keys: Sequence[str] | None = None,
per_triangle_extras_keys: Sequence[str] | None = None,
instance_extras_keys: Sequence[str] | None = None,
) → Geometry3DInstances

Create an empty Geometry3DInstances container.

Parameters:

  • x_min – Minimum x coordinate (default 0.0)

  • x_max – Maximum x coordinate

  • y_min – Minimum y coordinate (default 0.0)

  • y_max – Maximum y coordinate

  • z_min – Minimum z coordinate (default 0.0)

  • z_max – Maximum z coordinate

  • per_vertex_extras_keys – Sequence of keys for per-vertex additional data to initialize

  • per_line_extras_keys – Sequence of keys for per-line additional data to initialize

  • per_triangle_extras_keys – Sequence of keys for per-triangle additional data to initialize

  • instance_extras_keys – Sequence of keys for per-instance additional data to initialize

Raises:

ValueError – If bounds are not fully specified

add_instance(
vertices: ndarray,
lines: ndarray | None = None,
triangles: ndarray | None = None,
bbs_3d: ndarray | None = None,
oriented_bbs_3d: ndarray | None = None,
per_vertex_extras: Mapping[str, ndarray] | None = None,
per_line_extras: Mapping[str, ndarray] | None = None,
per_triangle_extras: Mapping[str, ndarray] | None = None,
per_instance_extras: Mapping[str, Any] | None = None,
) → None

Add a 3D instance.

Parameters:

  • vertices – Array of shape (N, 3) or flattened (3N,), dtype float32

  • lines – Flattened int array (2L,) of vertex indices forming L line segments

  • triangles – Flattened int array (3T,) of vertex indices forming T triangles

  • bbs_3d – Array of shape (B, 6) or flattened (6B,), dtype float32

  • oriented_bbs_3d – Array of shape (O, 9) or flattened (9O,), dtype float32

  • per_vertex_extras – Dict of arrays of shape (N,)

  • per_line_extras – Dict of arrays of shape (L,) for per-line extras

  • per_triangle_extras – Dict of arrays of shape (T,) for per-triangle extras

  • per_instance_extras – Dict of scalar per-instance attributes (one value or length-1 array)

Raises:

ValueError – On shape/type/index validation errors

to_row() → dict[str, Any]

Convert to the internal 3LC row format used by Geometry3D columns.

classmethod from_row(
row: Mapping[str, Any],
) → Geometry3DInstances

Parse a Geometry3D row into a Geometry3DInstances object.

Parameters:

row – Row dictionary with INSTANCES, X_MIN, Y_MIN, Z_MIN, X_MAX, Y_MAX, Z_MAX keys

Raises:

ValueError – If bounds are missing or invalid