Types

Structured data types used throughout PyEtSimul.

Geometry

Structured dataclasses to replace raw numpy arrays.

Provides type-safe dataclasses that improve code readability and maintain semantic meaning while supporting arithmetic operations and numpy integration.

class pyetsimul.types.geometry.Point2D(x, y)[source]

Bases: object

A 2D point with validation.

Parameters:

x (float)
y (float)

x: float

y: float

to_array()[source]

Convert to numpy array.

Return type:: ndarray

classmethod from_array(arr)[source]

Create Point2D from numpy array.

Return type:: Point2D
Parameters:: arr (ndarray)

isclose(other, rtol=1e-09, atol=1e-12)[source]

Compare with tolerance.

Return type:

bool

Parameters:

other (Point2D)
rtol (float)
atol (float)

assert_close(other, rtol=1e-09, atol=1e-12, msg='')[source]

Assert close with custom error message.

Return type:

None

Parameters:

other (Point2D)
rtol (float)
atol (float)
msg (str)

serialize()[source]

Serialize to dictionary representation.

Return type:: dict

classmethod deserialize(data)[source]

Deserialize from dictionary representation.

Return type:: Point2D
Parameters:: data (dict)

class pyetsimul.types.geometry.Point3D(x, y, z)[source]

Bases: object

A 3D point with validation.

Parameters:

x (float)
y (float)
z (float)

x: float

y: float

z: float

to_array()[source]

Convert to numpy array.

Return type:: ndarray

to_homogeneous()[source]

Convert to homogeneous coordinates [x, y, z, 1].

Return type:: ndarray

classmethod from_array(arr)[source]

Create Point3D from numpy array.

Return type:: Point3D
Parameters:: arr (ndarray)

distance_to(other)[source]

Calculate Euclidean distance to another point.

Return type:: float
Parameters:: other (Point3D)

isclose(other, rtol=1e-09, atol=1e-12)[source]

Compare with tolerance.

Return type:

bool

Parameters:

other (Point3D)
rtol (float)
atol (float)

assert_close(other, rtol=1e-09, atol=1e-12, msg='')[source]

Assert close with custom error message.

Return type:

None

Parameters:

other (Point3D)
rtol (float)
atol (float)
msg (str)

to_position3d()[source]

Convert to Position3D (homogeneous coordinates with w=1).

Return type:: Position3D

class pyetsimul.types.geometry.Vector3D(x, y, z)[source]

Bases: object

A 3D vector with validation and common operations.

Parameters:

x (float)
y (float)
z (float)

x: float

y: float

z: float

to_array()[source]

Convert to numpy array for compatibility.

Return type:: ndarray

to_homogeneous()[source]

Convert to homogeneous coordinates [x, y, z, 0].

Return type:: ndarray

classmethod from_array(arr)[source]

Create Vector3D from numpy array.

Return type:: Vector3D
Parameters:: arr (ndarray)

magnitude()[source]

Calculate vector magnitude.

Return type:: float

normalize()[source]

Return normalized vector.

Return type:: Vector3D

dot(other)[source]

Calculate dot product with another vector.

Return type:: float

cross(other)[source]

Calculate cross product with another vector.

Return type:: Vector3D
Parameters:: other (Vector3D)

to_direction3d()[source]

Convert to Direction3D.

Return type:: Direction3D

isclose(other, rtol=1e-09, atol=1e-12)[source]

Compare with tolerance.

Return type:

bool

Parameters:

other (Vector3D)
rtol (float)
atol (float)

assert_close(other, rtol=1e-09, atol=1e-12, msg='')[source]

Assert close with custom error message.

Return type:

None

Parameters:

other (Vector3D)
rtol (float)
atol (float)
msg (str)

serialize()[source]

Serialize to dictionary representation.

Return type:: dict

classmethod deserialize(data)[source]

Deserialize from dictionary representation.

Return type:: Vector3D
Parameters:: data (dict)

class pyetsimul.types.geometry.Position3D(x, y, z)[source]

Bases: object

A 3D position that can be converted to homogeneous coordinates [x,y,z,1].

Parameters:

x (float)
y (float)
z (float)

x: float

y: float

z: float

to_array()[source]

Convert to homogeneous 4D array [x,y,z,1].

Return type:: ndarray

classmethod from_array(arr)[source]

Create from 4D homogeneous array [x,y,z,1] or 3D array [x,y,z].

Return type:: Position3D
Parameters:: arr (ndarray)

to_point3d()[source]

Convert to Point3D.

Return type:: Point3D

isclose(other, rtol=1e-09, atol=1e-12)[source]

Compare with tolerance.

Return type:

bool

Parameters:

other (Position3D)
rtol (float)
atol (float)

assert_close(other, rtol=1e-09, atol=1e-12, msg='')[source]

Assert close with custom error message.

Return type:

None

Parameters:

other (Position3D)
rtol (float)
atol (float)
msg (str)

classmethod from_point3d(point)[source]

Create Position3D from Point3D.

Return type:: Position3D
Parameters:: point (Point3D)

distance_to(other)[source]

Calculate Euclidean distance to another position.

Return type:: float
Parameters:: other (Position3D)

serialize()[source]

Serialize to dictionary representation.

Return type:: dict

classmethod deserialize(data)[source]

Deserialize from dictionary representation.

Return type:: Position3D
Parameters:: data (dict)

class pyetsimul.types.geometry.Direction3D(x, y, z)[source]

Bases: object

A 3D direction vector that converts to homogeneous [x,y,z,0].

Parameters:

x (float)
y (float)
z (float)

x: float

y: float

z: float

to_array()[source]

Convert to homogeneous 4D array [x,y,z,0].

Return type:: ndarray

classmethod from_array(arr)[source]

Create from 4D homogeneous array [x,y,z,0] or 3D array [x,y,z].

Return type:: Direction3D
Parameters:: arr (ndarray)

magnitude()[source]

Calculate vector magnitude.

Return type:: float

normalize()[source]

Return normalized direction vector.

Return type:: Direction3D

dot(other)[source]

Calculate dot product with another direction.

Return type:: float

cross(other)[source]

Calculate cross product with another direction.

Return type:: Direction3D
Parameters:: other (Direction3D)

to_vector3d()[source]

Convert to Vector3D.

Return type:: Vector3D

isclose(other, rtol=1e-09, atol=1e-12)[source]

Compare with tolerance.

Return type:

bool

Parameters:

other (Direction3D)
rtol (float)
atol (float)

assert_close(other, rtol=1e-09, atol=1e-12, msg='')[source]

Assert close with custom error message.

Return type:

None

Parameters:

other (Direction3D)
rtol (float)
atol (float)
msg (str)

serialize()[source]

Serialize to dictionary representation.

Return type:: dict

classmethod deserialize(data)[source]

Deserialize from dictionary representation.

Return type:: Direction3D
Parameters:: data (dict)

class pyetsimul.types.geometry.Ray(origin, direction)[source]

Bases: object

A ray defined by origin point and direction vector.

Parameters:

origin (Point3D)
direction (Direction3D)

origin: Point3D

direction: Direction3D

point_at(t)[source]

Get point along ray at parameter t.

Return type:: Point3D
Parameters:: t (float)

classmethod from_two_points(p1, p2)[source]

Create ray from two points.

Return type:

Ray

Parameters:

p1 (Point3D)
p2 (Point3D)

class pyetsimul.types.geometry.IntersectionResult(intersects, point=None, distance=None, surface_normal=None)[source]

Bases: object

Result of ray-surface intersection calculation.

Parameters:

intersects (bool)
point (Point3D | None)
distance (float | None)
surface_normal (Direction3D | None)

intersects: bool

point: Point3D | None = None

distance: float | None = None

surface_normal: Direction3D | None = None

classmethod no_intersection()[source]

Create result indicating no intersection.

Return type:: IntersectionResult

classmethod intersection_at(point, distance, normal=None)[source]

Create result indicating intersection at given point.

Return type:

IntersectionResult

Parameters:

point (Point3D)
distance (float)
normal (Direction3D | None)

class pyetsimul.types.geometry.RotationMatrix(input_array, validate_handedness=True)[source]

Bases: ndarray

A 3x3 rotation matrix that validates its mathematical properties.

Parameters:

input_array (ndarray | list)
validate_handedness (bool)

Return type:

Self

classmethod identity()[source]

Create an identity rotation matrix.

Return type:: RotationMatrix

classmethod deserialize(data)[source]

Create RotationMatrix from serialized data with automatic handedness detection.

Tries strict right-handed validation first, falls back to allowing left-handed matrices for legacy compatibility.

Parameters:: data (dict) – Matrix data (list or array)
Return type:: RotationMatrix

class pyetsimul.types.geometry.TransformationMatrix(input_array)[source]

Bases: ndarray

A 4x4 homogeneous transformation matrix with convenient factory methods.

Parameters:: input_array (ndarray | list)
Return type:: Self

classmethod identity()[source]

Create an identity transformation matrix.

Return type:: TransformationMatrix

classmethod from_translation(translation)[source]

Create a translation matrix from a Position3D.

Return type:: TransformationMatrix
Parameters:: translation (Position3D)

classmethod from_rotation(rotation_matrix)[source]

Create a transformation matrix from a 3x3 rotation matrix.

Return type:: TransformationMatrix
Parameters:: rotation_matrix (RotationMatrix)

classmethod from_translation_and_rotation(translation, rotation_matrix)[source]

Create a transformation matrix from a 3x3 rotation matrix.

Return type:

TransformationMatrix

Parameters:

translation (Position3D)
rotation_matrix (RotationMatrix)

get_rotation()[source]

Extract the 3x3 rotation matrix.

Return type:: RotationMatrix

get_translation()[source]

Extract the translation vector as Position3D.

Return type:: Position3D

class pyetsimul.types.geometry.ScreenGeometry(width, height, plane)[source]

Bases: object

Physical screen dimensions and orientation for visualization.

Defines a screen centered at the origin on the specified plane.

Parameters:

width (float)
height (float)
plane (str)

width: float

height: float

plane: str

Imaging

Dataclasses for camera images, pupil data, and imaging results.

Provides structured dataclasses for imaging operations to replace the Dict[str, Any] pattern with type-safe alternatives.

class pyetsimul.types.imaging.CameraImage(corneal_reflections, pupil_boundary, pupil_center, resolution, glint_sizes_px=None)[source]

Bases: object

Result of camera.take_image() operation.

Parameters:

corneal_reflections (list[Point2D | None])
pupil_boundary (list[Point2D] | None)
pupil_center (Point2D | None)
resolution (Point2D)
glint_sizes_px (list[float | None] | None)

corneal_reflections: list[Point2D | None]

pupil_boundary: list[Point2D] | None

pupil_center: Point2D | None

resolution: Point2D

glint_sizes_px: list[float | None] | None = None

classmethod empty(resolution, num_lights)[source]

Create empty camera image with no detected features.

Return type:

CameraImage

Parameters:

resolution (Point2D)
num_lights (int)

class pyetsimul.types.imaging.PupilData(boundary_points=None, center=None, ellipse_params=None, area=None)[source]

Bases: object

Result of pupil detection/analysis operations.

Parameters:

boundary_points (ndarray | None)
center (Point2D | None)
ellipse_params (ndarray | None)
area (float | None)

boundary_points: ndarray | None = None

center: Point2D | None = None

ellipse_params: ndarray | None = None

area: float | None = None

property is_valid: bool: Check if pupil data contains valid measurements.

classmethod empty()[source]

Create empty pupil data indicating no detection.

Return type:: PupilData

class pyetsimul.types.imaging.EyeMeasurement(camera_image, pupil_data, gaze_direction=None, timestamp=None)[source]

Bases: object

Complete eye measurement from camera.

Parameters:

camera_image (CameraImage)
pupil_data (PupilData)
gaze_direction (Point3D | None)
timestamp (float | None)

camera_image: CameraImage

pupil_data: PupilData

gaze_direction: Point3D | None = None

timestamp: float | None = None

property is_valid: bool: Check if measurement contains valid eye tracking data.

class pyetsimul.types.imaging.ProjectionResult(image_points, distances, valid_mask)[source]

Bases: object

Result of camera projection operation.

Parameters:

image_points (ndarray)
distances (ndarray)
valid_mask (ndarray)

image_points: ndarray

distances: ndarray

valid_mask: ndarray

property num_points: int: Number of projected points.

property valid_points: ndarray: Get only the valid image points.

class pyetsimul.types.imaging.CameraMatrix(matrix=None)[source]

Bases: object

3x3 camera matrix with convenient properties for focal_length and resolution.

Parameters:: matrix (ndarray | None)

__init__(matrix=None)[source]

Initialize camera matrix.

Parameters:: matrix (ndarray | None) – Optional 3x3 camera matrix. If None, uses defaults.
Return type:: None

property focal_length: float: Get the camera focal length in pixels.

property resolution: Point2D: Get the camera resolution in pixels.

property matrix: ndarray: Get the camera intrinsics matrix.

Algorithms

Dataclasses for algorithm configurations and results.

Provides structured dataclasses to replace dictionary-based state management for eye tracking algorithms and their results.

Note: Algorithm-specific state classes (PolynomialGazeModelState, HomographyNormalizationGazeModelState, etc.) are defined in their respective algorithm modules, not here.

class pyetsimul.types.algorithms.GazePrediction(gaze_point, confidence, algorithm_name, processing_time=None, intermediate_results=None)[source]

Bases: object

Result of gaze estimation algorithm.

Parameters:

gaze_point (Point3D)
confidence (float)
algorithm_name (str)
processing_time (float | None)
intermediate_results (dict[str, Any] | None)

gaze_point: Point3D

confidence: float

algorithm_name: str

processing_time: float | None = None

intermediate_results: dict[str, Any] | None = None

property is_reliable: bool: Check if prediction meets minimum confidence threshold.

class pyetsimul.types.algorithms.AlgorithmState(is_calibrated=False, calibration_error=None, last_update=None)[source]

Bases: object

Base class for algorithm state management.

Parameters:

is_calibrated (bool)
calibration_error (float | None)
last_update (float | None)

is_calibrated: bool = False

calibration_error: float | None = None

last_update: float | None = None

reset()[source]

Reset algorithm to uncalibrated state.

Return type:: None