s6.schema.primitives

Lightweight geometry and data primitives used across Sense Core.

This module defines small pydantic models and vector utilities commonly exchanged between pipeline stages, visualization, and telemetry layers.

Coordinate conventions

  • Pixel coordinates are represented as (x, y) in Vector2D instances.

  • BoundingBox2D stores fields in image-slice order (y, x, w, h) to match NumPy row/column indexing; helper methods clarify conversions.

  • Methods operating on image arrays assume NumPy’s HxW(xC) memory layout.

class s6.schema.primitives.BoundingBox2D(*, y: float, x: float, w: float, h: float, normalised: bool = False)

Bases: BaseModel

Axis-aligned rectangle in image coordinates.

y, x

Top-left corner in pixel coordinates (row y, column x).

Type:

float

w, h

Width and height in pixels.

Type:

float

normalised

If True, fields are normalised relative to image size.

Type:

bool

y: float
x: float
w: float
h: float
normalised: bool
crop_image(image: ndarray)

Return the region of image covered by this box.

Parameters:

image (np.ndarray) – Source image array (H x W x C or H x W).

Returns:

A view/slice of image bounded by the box.

Return type:

np.ndarray

classmethod from_center_radius(cx: float, cy: float, radius: float, normalised: bool = False) → BoundingBox2D

Create a square box centered at (cx, cy) with side 2*radius.

Parameters:

  • cx (float) – Center coordinates in pixels.

  • cy (float) – Center coordinates in pixels.

  • radius (float) – Half of the side length in pixels.

  • normalised (bool, optional) – Whether the returned coordinates are normalised.

Returns:

The constructed bounding box.

Return type:

BoundingBox2D

classmethod from_vector_radius(center: Vector2D, radius: float, normalised: bool = False) → BoundingBox2D

Create a square box centered at center with side 2*radius.

Parameters:

  • center (Vector2D) – Center coordinate.

  • radius (float) – Half of the side length in pixels.

  • normalised (bool, optional) – Whether the returned coordinates are normalised.

Returns:

The constructed bounding box.

Return type:

BoundingBox2D

crop_points(points: Vector2D | List[Tuple[float, float]] | List[Vector2D] | ndarray) → Vector2D | List[Tuple[float, float]] | List[Vector2D] | ndarray

Convert points from image coordinates to this box’s local coordinates.

For each point:

  • If provided as a tuple (y, x) or as a numpy array (assumed order [y, x]), the cropped coordinate is (y - self.y, x - self.x).

  • If provided as a Vector2D (with fields x and y), the cropped coordinate is Vector2D(x = original.x - self.x, y = original.y - self.y).

uncrop_points(points: Vector2D | List[Tuple[float, float]] | List[Vector2D] | ndarray) → Vector2D | List[Tuple[float, float]] | List[Vector2D] | ndarray

Convert points from this box’s local coordinates back to image space.

For each point:

  • If provided as a tuple (y, x) or as a numpy array (assumed order [y, x]), the original coordinate is (y + self.y, x + self.x).

  • If provided as a Vector2D (with fields x and y), the original coordinate is Vector2D(x = original.x + self.x, y = original.y + self.y).

property center: Vector2D

Center point of the box as a Vector2D.

class s6.schema.primitives.ComponentStat(*, y: float, x: float, w: float, h: float, normalised: bool = False, area: float)

Bases: BoundingBox2D

Bounding box with connected-component area statistic.

area: float
static from_tuple(*args)

Construct from an OpenCV-style tuple (x, y, w, h, area).

class s6.schema.primitives.Vector2D(*, x: float, y: float)

Bases: BaseModel

2D vector/point with convenience math and conversion helpers.

Supports basic arithmetic (+, -, *, /), dot product, magnitude/normalization, and conversion to/from NumPy and Torch tensors.

x: float
y: float
tolist()

Return [x, y] list representation.

static from_numpy(array)

Create from a NumPy array-like (x, y).

numpy()

Return a NumPy array of shape (2,) with dtype float32.

to_torch(dtype=torch.float32, device=None)

Return a Torch tensor tensor([x, y]) with the given dtype/device.

static from_torch(tensor) → Vector2D

Create from a Torch tensor of shape (2,) or (2, 1).

dot(other)

Dot product with another Vector2D.

magnitude()

Euclidean length sqrt(x^2 + y^2).

normalize()

Return a unit-length vector in the same direction.

Raises:

ValueError – If this vector has zero length.

clone()

Return a shallow copy of this vector.

class s6.schema.primitives.Vector3D(*, x: float, y: float, z: float)

Bases: BaseModel

3D vector/point with arithmetic and conversion helpers.

Provides vector math (add/subtract, scalar mul/div, dot/cross) and conversions to/from NumPy arrays and Torch tensors.

x: float
y: float
z: float
clone()

Return a shallow copy of this vector.

tolist()

Return [x, y, z] list representation.

numpy()

Return a NumPy array of shape (3,) with dtype float32.

static from_numpy(array)

Create from a NumPy sequence (x, y, z).

to_torch(dtype=torch.float32, device=None)

Return a Torch tensor tensor([x, y, z]) with the given dtype/device.

static from_torch(tensor) → Vector3D

Create from a Torch tensor of shape (3,) or (3, 1).

dot(other)

Dot product with another Vector3D.

cross(other)

Cross product with another Vector3D (right-handed).

magnitude()

Euclidean length sqrt(x^2 + y^2 + z^2).

normalize()

Return a unit-length vector in the same direction.

Raises:

ValueError – If this vector has zero length.

classmethod zero() → Vector3D

Convenience constructor for the zero vector (0, 0, 0).

class s6.schema.primitives.Circle2D(*, x: float, y: float, r: float)

Bases: Vector2D

2D circle parameterized by center (x, y) and radius r.

r: float
class s6.schema.primitives.TrackingTarget

Bases: object

Simple container describing a tracked region in an image.

input_image: ndarray
bounding_box: BoundingBox2D