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.

static unsigned_angle_between(source: Vector2D, target: Vector2D, *, min_norm: float = 1e-06) → float | None

Return the unsigned angle between two vectors in radians.

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.Quaternion(*, w: float, x: float, y: float, z: float)

Bases: BaseModel

Unit quaternion representing a 3D rotation.

The component order in this project is (w, x, y, z). Helper methods provide deterministic normalization and conversions to/from rotation matrices, NumPy arrays, and Torch tensors.

w: float

x: float

y: float

z: float

clone() → Quaternion

Return a shallow copy of this quaternion.

tolist() → list[float]

Return [w, x, y, z] list representation.

numpy() → ndarray

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

static from_numpy(array) → Quaternion

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

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

Return a Torch tensor tensor([w, x, y, z]).

static from_torch(tensor) → Quaternion

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

magnitude() → float

Return the Euclidean norm of the quaternion components.

normalize() → Quaternion

Return a unit quaternion in a deterministic hemisphere.

Raises:

ValueError – If this quaternion has zero length.

flip_z_axis() → Quaternion

Return this rotation in a basis with the z axis inverted.

Notes

This applies the reflected-basis change S * R * S with S = diag(1, 1, -1) to the quaternion’s rotation matrix. The returned quaternion remains normalized and uses the project’s deterministic sign convention.

conjugate() → Quaternion

Return the quaternion conjugate.

inverse() → Quaternion

Return the multiplicative inverse quaternion.

classmethod identity() → Quaternion

Return the identity rotation quaternion.

classmethod zero() → Quaternion

Return the canonical quaternion for zero rotation.

classmethod from_axis_angle(axis: Vector3D | Sequence[float], angle: float) → Quaternion

Create a quaternion from a right-handed axis-angle rotation.

classmethod from_rotation_matrix(matrix) → Quaternion

Create a quaternion from a 3x3 rotation matrix.

to_rotation_matrix() → Tensor

Return the equivalent 3x3 rotation matrix.

class s6.schema.primitives.Pose3DRecoveryResult(*, rotation: Quaternion, translation: Vector3D, num_points: int, point_keys: List[str] | None = None, mean_error: float, rmse: float, max_error: float, per_point_errors: List[float], reflection_corrected: bool)

Bases: BaseModel

Best-fit rigid pose recovered from 3D point correspondences.

rotation

Model-to-observed best-fit rotation.

Type:

Quaternion

translation

Model-to-observed translation computed from the fitted centroids.

Type:

Vector3D

num_points

Number of correspondences used by the solver.

Type:

int

point_keys

Ordered correspondence keys for mapping-based inputs.

Type:

list[str] | None

mean_error, rmse, max_error

Euclidean residual summary statistics in the input point units.

Type:

float

per_point_errors

Euclidean residual for each paired point in solver order.

Type:

list[float]

reflection_corrected

Whether the SVD solve required a reflection fix to enforce det(R) = +1.

Type:

bool

rotation: Quaternion

translation: Vector3D

num_points: int

point_keys: List[str] | None

mean_error: float

rmse: float

max_error: float

per_point_errors: List[float]

reflection_corrected: bool

class s6.schema.primitives.LineSegment2D(*, start: Vector2D, end: Vector2D, infinite: bool = False)

Bases: _LineSegmentBase, BaseModel

Finite or infinite 2D line represented by two support endpoints.

start, end

Stored support endpoints in image or planar coordinates.

Type:

Vector2D

infinite

If True, geometry methods operate on the infinite supporting line while preserving start and end as anchor points.

Type:

bool, optional

start: Vector2D

end: Vector2D

infinite: bool

class s6.schema.primitives.MaskLineSegment2D(*, start: Vector2D, end: Vector2D, infinite: bool = False, centroid: Vector2D)

Bases: LineSegment2D

Image-space mask-supported line segment with component centroid.

start, end

Clipped segment endpoints in image coordinates.

Type:

Vector2D

centroid

Centroid of the dominant connected-component mask support in the same image coordinates.

Type:

Vector2D

infinite

Preserved for API compatibility with LineSegment2D; detector outputs remain finite by default.

Type:

bool, optional

centroid: Vector2D

class s6.schema.primitives.LineSegment3D(*, start: Vector3D, end: Vector3D, infinite: bool = False)

Bases: _LineSegmentBase, BaseModel

Finite or infinite 3D line represented by two support endpoints.

start, end

Stored support endpoints in world or camera coordinates.

Type:

Vector3D

infinite

If True, geometry methods operate on the infinite supporting line while preserving start and end as anchor points.

Type:

bool, optional

start: Vector3D

end: Vector3D

infinite: bool

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