pyetsimul 3.2.4__tar.gz → 3.3.0__tar.gz

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: pyetsimul
-Version: 3.2.4
+Version: 3.3.0
 Summary: PyEtSimul: An Open-Source Python Software Framework for Eye Tracking Simulation
 Project-URL: Homepage, https://github.com/mh-salari/pyetsimul
 Project-URL: Repository, https://github.com/mh-salari/pyetsimul
 Project-URL: Documentation, https://pyetsimul.readthedocs.io/
 Project-URL: Issues, https://github.com/mh-salari/pyetsimul/issues
-Author-email: Mohammadhossein Salari <Mohammadhossein.Salari@gmail.com>
+Author-email: Mohammadhossein Salari <mohammadhossein.salari@gmail.com>
 License: GPL-3.0-or-later
 License-File: LICENSE
 Keywords: eye-tracker,eye-tracking,gaze-estimation,simulation
@@ -27,7 +27,7 @@ Description-Content-Type: text/markdown
 [![Downloads](https://static.pepy.tech/badge/pyetsimul)](https://pepy.tech/project/pyetsimul)
 [![License](https://img.shields.io/badge/License-GPL--3.0-green)](https://github.com/mh-salari/pyetsimul/blob/main/LICENSE)
 [![Documentation](https://readthedocs.org/projects/pyetsimul/badge/?version=latest)](https://pyetsimul.readthedocs.io/)
-[![DOI](https://img.shields.io/badge/DOI-coming_soon-blue)](#citation)
+[![DOI](https://img.shields.io/badge/DOI-10.1145%2F3806023-blue)](https://doi.org/10.1145/3806023)
 
 PyEtSimul is an open-source Python framework for simulating video-based eye trackers
 by generating synthetic eye features through geometric modeling. The framework allows
@@ -87,13 +87,12 @@ After installation, explore the various examples in the `examples/` directory to
 
 ## Citation
 
-This work has been accepted for publication at ETRA 2026. The DOI will be added when the proceedings are published.
-
 **Cite as:**
 ```
 Salari, M., Niehorster, D. C., Hansen, D. W., & Bednarik, R. (2026).
 PyEtSimul: An Open-Source Python Framework for Eye-Tracking Simulation.
-In Proceedings of the 2026 Eye Tracking Research & Applications (ETRA 2026). ACM.
+Proceedings of the ACM on Human-Computer Interaction (PACMHCI), ETRA 2026. ACM.
+DOI: 10.1145/3806023
 ```
 
 **Also cite the original work:**

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/README.md

@@ -4,7 +4,7 @@
 [![Downloads](https://static.pepy.tech/badge/pyetsimul)](https://pepy.tech/project/pyetsimul)
 [![License](https://img.shields.io/badge/License-GPL--3.0-green)](https://github.com/mh-salari/pyetsimul/blob/main/LICENSE)
 [![Documentation](https://readthedocs.org/projects/pyetsimul/badge/?version=latest)](https://pyetsimul.readthedocs.io/)
-[![DOI](https://img.shields.io/badge/DOI-coming_soon-blue)](#citation)
+[![DOI](https://img.shields.io/badge/DOI-10.1145%2F3806023-blue)](https://doi.org/10.1145/3806023)
 
 PyEtSimul is an open-source Python framework for simulating video-based eye trackers
 by generating synthetic eye features through geometric modeling. The framework allows
@@ -64,13 +64,12 @@ After installation, explore the various examples in the `examples/` directory to
 
 ## Citation
 
-This work has been accepted for publication at ETRA 2026. The DOI will be added when the proceedings are published.
-
 **Cite as:**
 ```
 Salari, M., Niehorster, D. C., Hansen, D. W., & Bednarik, R. (2026).
 PyEtSimul: An Open-Source Python Framework for Eye-Tracking Simulation.
-In Proceedings of the 2026 Eye Tracking Research & Applications (ETRA 2026). ACM.
+Proceedings of the ACM on Human-Computer Interaction (PACMHCI), ETRA 2026. ACM.
+DOI: 10.1145/3806023
 ```
 
 **Also cite the original work:**

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/docs/conf.py

@@ -1,13 +1,14 @@
 """Sphinx configuration for PyEtSimul documentation."""
 
 import sys
+from datetime import UTC, datetime
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
 project = "PyEtSimul"
 author = "Mohammadhossein Salari"
-copyright = "2025, Mohammadhossein Salari"  # noqa: A001
+copyright = f"2025-{datetime.now(tz=UTC).year}, {author}"  # noqa: A001
 
 extensions = [
     "sphinx.ext.autodoc",

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/docs/index.rst

@@ -15,8 +15,8 @@ PyEtSimul Documentation
    :target: https://github.com/mh-salari/pyetsimul/blob/main/LICENSE
    :alt: License
 
-.. |DOI| image:: https://img.shields.io/badge/DOI-coming_soon-blue
-   :target: #
+.. |DOI| image:: https://img.shields.io/badge/DOI-10.1145%2F3806023-blue
+   :target: https://doi.org/10.1145/3806023
    :alt: DOI
 
 **PyEtSimul** is an open-source Python framework for simulating video-based eye trackers
@@ -75,7 +75,7 @@ of gaze estimation algorithms across calibrated and uncalibrated settings.
    by the same authors. If you use PyEtSimul in your research, please cite [2].
 
 | [1] Bohme, M., Dorr, M., Graw, M., Martinetz, T., & Barth, E. (2008). A software framework for simulating eye trackers. In *Proceedings of the 2008 Symposium on Eye Tracking Research & Applications (ETRA '08)*, pp. 251-258. ACM. `DOI: 10.1145/1344471.1344529 <https://doi.org/10.1145/1344471.1344529>`_
-| [2] Salari, M., Niehorster, D. C., Hansen, D. W., & Bednarik, R. (2026). PyEtSimul: An Open-Source Python Framework for Eye-Tracking Simulation. In *Proceedings of the 2026 Eye Tracking Research & Applications (ETRA 2026)*. ACM. *[Accepted; DOI forthcoming]*
+| [2] Salari, M., Niehorster, D. C., Hansen, D. W., & Bednarik, R. (2026). PyEtSimul: An Open-Source Python Framework for Eye-Tracking Simulation. *Proceedings of the ACM on Human-Computer Interaction (PACMHCI)*, ETRA 2026. ACM. `DOI: 10.1145/3806023 <https://doi.org/10.1145/3806023>`_
 
 .. note::
 

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/examples/custom_gaze_model.md

@@ -24,7 +24,7 @@ PyEtSimul gaze estimation models follow a simple pattern:
 ### Placeholder Code
 
 ```python
-class MyAlgorithmState(AlgorithmState): # Inherit from pyetsimul.types.algorithms.AlgorithmState
+class MyAlgorithmState(AlgorithmState):  # Inherit from pyetsimul.types.algorithms.AlgorithmState
     """
     State for your custom gaze model.
     TODO: Add fields to store your calibration parameters.
@@ -34,7 +34,7 @@ class MyAlgorithmState(AlgorithmState): # Inherit from pyetsimul.types.algorithm
         """Serialize the state to a dictionary for saving."""
         # TODO: Add your custom parameters to the dictionary.
         # Ensure they are JSON-serializable.
-        return {} # Return a dictionary of your state
+        return {}  # Return a dictionary of your state
 
     @classmethod
     def deserialize(cls, data: dict) -> "MyAlgorithmState":
@@ -58,7 +58,7 @@ class MyAlgorithmState(AlgorithmState): # Inherit from pyetsimul.types.algorithm
 ### Placeholder Code
 
 ```python
-class MyGazeModel(EyeTracker): # Inherit from pyetsimul.core.EyeTracker
+class MyGazeModel(EyeTracker):  # Inherit from pyetsimul.core.EyeTracker
     """
     A template for a custom gaze estimation model.
     TODO: Describe what your model does.
@@ -66,7 +66,7 @@ class MyGazeModel(EyeTracker): # Inherit from pyetsimul.core.EyeTracker
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
-        self.algorithm_state = MyAlgorithmState() # Instance of your custom AlgorithmState
+        self.algorithm_state = MyAlgorithmState()  # Instance of your custom AlgorithmState
 
     @property
     def algorithm_name(self) -> str:
@@ -80,13 +80,13 @@ class MyGazeModel(EyeTracker): # Inherit from pyetsimul.core.EyeTracker
         # TODO: Add any specific parameters your model needs for instantiation
     ) -> "MyGazeModel":
         """A factory method for clean instantiation."""
-        return cls() # Return an instance of your model
+        return cls()  # Return an instance of your model
 
     # --- Block 3: Calibration Logic ---
     # Purpose: Learn the mapping from eye features to world coordinates.
     # This method modifies the internal state of the tracker, specifically `self.algorithm_state`.
     # It does not return a value.
-    def calibrate(self, calibration_measurements: list[EyeMeasurement]) -> None: # EyeMeasurement from pyetsimul.types
+    def calibrate(self, calibration_measurements: list[EyeMeasurement]) -> None:  # EyeMeasurement from pyetsimul.types
         """Calibrate the model by learning the mapping from eye features to gaze."""
         # TODO: Implement your calibration logic here.
         # This method should update `self.algorithm_state` with learned parameters.
@@ -96,7 +96,7 @@ class MyGazeModel(EyeTracker): # Inherit from pyetsimul.core.EyeTracker
     # --- Block 4: Prediction Logic ---
     # Purpose: Estimate gaze from a single eye measurement using the learned model.
     # This method returns a `GazePrediction` object.
-    def predict_gaze(self, measurement: EyeMeasurement) -> GazePrediction: # GazePrediction from pyetsimul.types
+    def predict_gaze(self, measurement: EyeMeasurement) -> GazePrediction:  # GazePrediction from pyetsimul.types
         """Predict gaze position from a single eye measurement."""
         # TODO: Implement your gaze prediction logic here.
         # Extract features from `measurement`.
@@ -105,7 +105,7 @@ class MyGazeModel(EyeTracker): # Inherit from pyetsimul.core.EyeTracker
 
         # Return a GazePrediction object
         return GazePrediction(
-            gaze_point=Point3D(0.0, 0.0, 0.0), # Point3D from pyetsimul.types
+            gaze_point=Point3D(0.0, 0.0, 0.0),  # Point3D from pyetsimul.types
             confidence=0.0,
             algorithm_name=self.algorithm_name,
             processing_time=0.0,

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/examples/experiments/README.md

@@ -7,6 +7,7 @@ Create a custom parameter variation in 3 steps:
 ```python
 from pyetsimul.simulation import GenericEyeVariation
 
+
 class MyCustomVariation(GenericEyeVariation):
     """Custom variation that changes any eye parameter."""
 
@@ -31,6 +32,7 @@ class MyCustomVariation(GenericEyeVariation):
 ```python
 from pyetsimul.core.cornea import ConicCornea
 
+
 class ConicCorneaKVariation(GenericEyeVariation):
     def __init__(self, k_range: list[float], num_steps: int = 10):
         super().__init__("cornea.anterior_k", k_range, num_steps)
@@ -42,6 +44,7 @@ class ConicCorneaKVariation(GenericEyeVariation):
     def apply_to_eye(self, eye, value: float) -> None:
         eye.cornea.anterior_k = value
 
+
 # Usage
 variation = ConicCorneaKVariation([-0.05, -0.15], 5)
 ```
@@ -58,7 +61,7 @@ config = ExperimentConfig(
     eyes=[Eye()],  # Add your custom eye setup if needed
     cameras=[Camera()],
     lights=[Light()],
-    output_dir="outputs"
+    output_dir="outputs",
 )
 
 # Generate data

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/examples/experiments/data_validation.py

@@ -119,7 +119,7 @@ def validate_measurements(data: dict[str, Any]) -> bool:
     return valid_measurements == total_measurements
 
 
-def compare_values(actual: Any, expected: Any, field_name: str, tolerance: float = 1e-10) -> bool:  # noqa: ANN401, PLR0911
+def compare_values(actual: Any, expected: Any, field_name: str, tolerance: float = 1e-10) -> bool:  # noqa: ANN401
     """Compare actual vs expected values with tolerance."""
     if actual is None and expected is None:
         return True

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/pyetsimul/core/eye_tracker.py

@@ -116,13 +116,16 @@ class EyeTracker(ABC):
         failed_points = []
 
         info(f"Collecting calibration data at {n_points} points...")
+        if len(self.cameras) > 1:
+            warning(
+                f"calibrate() uses only the first of {len(self.cameras)} configured cameras; "
+                "multi-camera calibration is not implemented."
+            )
 
         for i, calib_point in enumerate(self.calib_points):
             # Make eye look at calibration point
             eye.look_at(calib_point, legacy=self.use_legacy_look_at)
 
-            # Take images from all cameras (currently uses first camera)
-            # TODO: Multi-camera support requires algorithm-specific implementation
             if not self.cameras:
                 raise ValueError("No cameras available for calibration")
 

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/pyetsimul/gaze_mapping/stampe1993/stampe1993_gaze_model.py

@@ -87,20 +87,69 @@ class Stampe1993GazeModel(PolynomialGazeModel):
         )
 
     def calibrate(self, calibration_measurements: list[EyeMeasurement]) -> None:
-        """Two-stage calibration: biquadratic polynomial, then corner correction."""
-        # Stage 1: Fit the biquadratic polynomial
+        """Two-stage calibration matching Stampe (1993) / EyeLink 1000 Plus.
+
+        Fits the biquadratic polynomial on the **inner** cal points (centre + edges,
+        no corners), then a per-quadrant corner correction on the **outer** (corner)
+        cal points. This staged split reproduces the EyeLink 1000 Plus stored !CAL
+        polynomial coefficients.
+        """
         self.plane_info = detect_calibration_plane(self.calib_points)
         info(summarize_plane_detection(self.calib_points, self.plane_info))
-        self._calibrate_same_xy(calibration_measurements)
 
-        # Stage 2: Fit corner correction from residuals
-        self._fit_corner_correction(calibration_measurements)
-
-    def _fit_corner_correction(self, calibration_measurements: list[EyeMeasurement]) -> None:
+        # Identify inner (centre+edges) vs outer (corner) calibration points by their
+        # 2-D target positions: a "corner" target is off both cardinal axes relative
+        # to the calibration-grid centroid (large |Δx · Δy|). For HV9 this picks the
+        # 4 corners and leaves the 5 inner points (centre + 4 edges) for the polynomial fit.
+        calib_coords_2d = np.array([self.plane_info.extract_2d_coords(pt) for pt in self.calib_points])
+        centroid = calib_coords_2d.mean(axis=0)
+        off_axis = np.abs((calib_coords_2d[:, 0] - centroid[0]) * (calib_coords_2d[:, 1] - centroid[1]))
+        n = len(self.calib_points)
+        n_corners = min(4, n - 1)
+        if n_corners <= 0 or n <= n_corners:
+            inner_idx = list(range(n))
+            corner_idx: list[int] = []
+        else:
+            order = np.argsort(off_axis)
+            inner_idx = order[:-n_corners].tolist()
+            corner_idx = order[-n_corners:].tolist()
+
+        # Stage 1: polynomial fit on inner cal points only. Temporarily restrict
+        # self.calib_points + the measurement list so the parent fitter sees only the inner subset.
+        saved_calib_points = self.calib_points
+        try:
+            self.calib_points = [saved_calib_points[i] for i in inner_idx]
+            inner_measurements = [calibration_measurements[i] for i in inner_idx]
+            self._calibrate_same_xy(inner_measurements)
+        finally:
+            self.calib_points = saved_calib_points
+
+        # Stage 2: corner correction on the 4 outer cal points (1 per quadrant for HV9).
+        if corner_idx:
+            self._fit_corner_correction(
+                [calibration_measurements[i] for i in corner_idx],
+                indices=corner_idx,
+            )
+        else:
+            # No corners (e.g. HV5 monocular geometry): zero out corner correction.
+            self.corner_coefficients = np.zeros((4, 2))
+            coords_array = np.array([self.plane_info.extract_2d_coords(pt) for pt in self.calib_points])
+            self.screen_center_2d = (float(coords_array[:, 0].mean()), float(coords_array[:, 1].mean()))
+
+    def _fit_corner_correction(
+        self,
+        calibration_measurements: list[EyeMeasurement],
+        indices: list[int] | None = None,
+    ) -> None:
         """Fit per-quadrant corner correction coefficients from polynomial residuals.
 
         The screen is divided into 4 quadrants relative to the calibration grid center.
         Corner correction: X_final = X_poly + cx[q] * (X_poly - Xc) * (Y_poly - Yc)
+
+        When ``indices`` is provided, position ``i`` in ``calibration_measurements`` is
+        paired with target coordinates from ``self.calib_points[indices[i]]``. This lets
+        the caller pass only a subset (the outer cal points) while the grid centroid is
+        still computed from the full ``self.calib_points`` set.
         """
         self.corner_coefficients = np.zeros((4, 2))  # [quadrant][cx, cy]
 
@@ -112,6 +161,9 @@ class Stampe1993GazeModel(PolynomialGazeModel):
         cx_center, cy_center = self.screen_center_2d
         info(f"\nCalibration grid center (2D): ({cx_center:.1f}, {cy_center:.1f}) mm")
 
+        if indices is None:
+            indices = list(range(len(calibration_measurements)))
+
         # Group points by quadrant relative to calibration center
         quadrant_data: dict[int, list[tuple[float, float, float, float]]] = {0: [], 1: [], 2: [], 3: []}
 
@@ -134,7 +186,7 @@ class Stampe1993GazeModel(PolynomialGazeModel):
             gaze_2d = coefficient_matrix @ poly_features.features
             poly_x, poly_y = gaze_2d[0], gaze_2d[1]
 
-            target_x, target_y = calib_coords_2d[i]
+            target_x, target_y = calib_coords_2d[indices[i]]
 
             # Quadrant relative to calibration center
             dx = poly_x - cx_center

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/pyetsimul/simulation/composed_variation.py

@@ -94,5 +94,4 @@ class SequentialVariation(ParameterVariation):
         """Generate sequential values from all variations."""
         for i, variation in enumerate(self.variations):
             for value in variation.generate_values():
-                combination = {"variation_index": i, "variation_name": variation.param_name, "value": value}
-                yield combination
+                yield {"variation_index": i, "variation_name": variation.param_name, "value": value}

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/pyetsimul/types/geometry.py

@@ -4,6 +4,7 @@ Provides type-safe dataclasses that improve code readability and maintain
 semantic meaning while supporting arithmetic operations and numpy integration.
 """
 
+import math
 from dataclasses import dataclass
 from typing import Self, Union, overload
 
@@ -49,7 +50,7 @@ class Point2D:
                 error_msg = f"{msg}: {error_msg}"
             raise AssertionError(error_msg)
 
-    def __sub__(self, other: "Point2D | float | int") -> "Point2D":
+    def __sub__(self, other: "Point2D | float") -> "Point2D":
         """Subtract point or scalar from point."""
         if isinstance(other, Point2D):
             return Point2D(self.x - other.x, self.y - other.y)
@@ -57,7 +58,7 @@ class Point2D:
             return Point2D(self.x - other, self.y - other)
         return NotImplemented
 
-    def __add__(self, other: "Point2D | float | int") -> "Point2D":
+    def __add__(self, other: "Point2D | float") -> "Point2D":
         """Add two points/vectors or add scalar to point."""
         if isinstance(other, Point2D):
             return Point2D(self.x + other.x, self.y + other.y)
@@ -161,7 +162,7 @@ class Point3D:
             return Point3D(self.x - other, self.y - other, self.z - other)
         return NotImplemented
 
-    def __add__(self, other: "Vector3D | float | int") -> "Point3D":
+    def __add__(self, other: "Vector3D | float") -> "Point3D":
         """Add a vector or scalar to a point to get a new point."""
         if isinstance(other, Vector3D):
             return Point3D(self.x + other.x, self.y + other.y, self.z + other.z)
@@ -278,7 +279,7 @@ class Vector3D:
             return Vector3D.from_array(result)
         return NotImplemented
 
-    def __add__(self, other: "Vector3D | float | int") -> "Vector3D":
+    def __add__(self, other: "Vector3D | float") -> "Vector3D":
         """Add two vectors or add scalar to vector."""
         if isinstance(other, Vector3D):
             return Vector3D(self.x + other.x, self.y + other.y, self.z + other.z)
@@ -286,7 +287,7 @@ class Vector3D:
             return Vector3D(self.x + other, self.y + other, self.z + other)
         return NotImplemented
 
-    def __sub__(self, other: "Vector3D | float | int") -> "Vector3D":
+    def __sub__(self, other: "Vector3D | float") -> "Vector3D":
         """Subtract vector or scalar from vector."""
         if isinstance(other, Vector3D):
             return Vector3D(self.x - other.x, self.y - other.y, self.z - other.z)
@@ -364,9 +365,10 @@ class Position3D:
     def from_array(cls, arr: np.ndarray) -> "Position3D":
         """Create from 4D homogeneous array [x,y,z,1] or 3D array [x,y,z]."""
         if arr.shape == (4,):
-            if arr[3] != 1.0 and arr[3] != 0.0:
-                # De-homogenize if needed
-                return cls(arr[0] / arr[3], arr[1] / arr[3], arr[2] / arr[3])
+            w = float(arr[3])
+            # w == 1 (point) or w == 0 (direction) → take xyz directly; otherwise de-homogenize.
+            if not math.isclose(w, 1.0) and not math.isclose(w, 0.0):
+                return cls(arr[0] / w, arr[1] / w, arr[2] / w)
             return cls(arr[0], arr[1], arr[2])
         if arr.shape == (3,):
             return cls(arr[0], arr[1], arr[2])
@@ -422,7 +424,7 @@ class Position3D:
             return Position3D(self.x - other, self.y - other, self.z - other)
         return NotImplemented
 
-    def __add__(self, other: "Vector3D | Direction3D | Point3D | float | int") -> "Position3D":
+    def __add__(self, other: "Vector3D | Direction3D | Point3D | float") -> "Position3D":
         """Add a vector, direction, point, or scalar to a position to get a new position."""
         if isinstance(other, (Vector3D, Direction3D, Point3D)):
             return Position3D(self.x + other.x, self.y + other.y, self.z + other.z)
@@ -438,7 +440,7 @@ class Position3D:
         """Multiply position by a scalar (reverse order)."""
         return self.__mul__(scalar)
 
-    def __radd__(self, other: "Vector3D | Direction3D | Point3D | float | int") -> "Position3D":
+    def __radd__(self, other: "Vector3D | Direction3D | Point3D | float") -> "Position3D":
         """Add position to a scalar (reverse order)."""
         return self.__add__(other)
 
@@ -601,7 +603,7 @@ class Direction3D:
         # For other operations, defer to numpy
         return NotImplemented
 
-    def __add__(self, other: "Direction3D | float | int") -> "Direction3D":
+    def __add__(self, other: "Direction3D | float") -> "Direction3D":
         """Add two directions or add scalar to direction."""
         if isinstance(other, Direction3D):
             return Direction3D(self.x + other.x, self.y + other.y, self.z + other.z)
@@ -609,7 +611,7 @@ class Direction3D:
             return Direction3D(self.x + other, self.y + other, self.z + other)
         return NotImplemented
 
-    def __sub__(self, other: "Direction3D | float | int") -> "Direction3D":
+    def __sub__(self, other: "Direction3D | float") -> "Direction3D":
         """Subtract direction or scalar from direction."""
         if isinstance(other, Direction3D):
             return Direction3D(self.x - other.x, self.y - other.y, self.z - other.z)

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 name = "pyetsimul"
 dynamic = ["version"]
 description = "PyEtSimul: An Open-Source Python Software Framework for Eye Tracking Simulation"
-authors = [{name = "Mohammadhossein Salari", email = "Mohammadhossein.Salari@gmail.com"}]
+authors = [{name = "Mohammadhossein Salari", email = "mohammadhossein.salari@gmail.com"}]
 license = {text = "GPL-3.0-or-later"}
 readme = "README.md"
 keywords = ["eye-tracking", "simulation", "eye-tracker", "gaze-estimation"]
@@ -38,6 +38,7 @@ tag-regex = "^(?P<version>\\d+\\.\\d+\\.\\d+)$"
 
 [dependency-groups]
 dev = [
+    "ruff>=0.13.0",
     "jupyterlab>=4.4.7",
     "pytest>=8.4.1",
     "scipy-stubs>=1.16.2.0",
@@ -146,27 +147,28 @@ ignore = [
     "TID252", # Flake8-tidy-imports - Prefer absolute imports over relative imports from parent modules
     "FBT001", # Flake8-boolean-trap - Boolean-typed positional argument in function definition
     "FBT002", # Flake8-boolean-trap - Boolean default positional argument in function definition
+    "PLR0911", # Pylint - Too many return statements
+    "C901",  # McCabe - Function is too complex
+    "PLR0912", # Pylint - Too many branches
     "PLR0913", # Pylint - Too many arguments
     "PLR0914", # Pylint - Too many local variables
-    "PLR0904", # Pylint - Too many public methods
     "PLR0915", # Pylint - Too many statements
     "PLR0917", # Pylint - Too many positional arguments
     "TRY003", # Tryceratops - Avoid specifying long messages outside the exception class
     "EM101", # Flake8-errmsg - Exception must not use a string literal, assign to variable first
     "EM102", # Flake8-errmsg - Exception must not use an f-string literal, assign to variable first
     "D401", # Pydocstyle - First line of docstring should be in imperative mood
-    "PLW3201", # Pylint - Bad dunder method name
-    "PT011", # Flake8-pytest-style - pytest.raises() is too broad
-    "TD002", # Flake8-todos - Missing author in TODO
-    "TD003", # Flake8-todos - Missing issue link in TODO
-    "FIX002", # Flake8-fixme - Line contains TODO
-    "N803", # PEP8-naming - Argument name should be lowercase
-    "C901", # McCabe - Function is too complex
-    "PLR0912", # Pylint - Too many branches
-    "INP001", # Flake8-no-pep420 - Implicit namespace package (requires __init__.py)
+    "N803", # PEP8-naming - Argument name should be lowercase (math vars like X, Y, N are conventional in this codebase)
 ]
 
+[tool.ruff.lint.pylint]
+# NumPy array-protocol hooks: NumPy looks these up by exact name when a custom
+# class is passed to np.asarray() / ufuncs. Not typos; not generic Python dunders.
+allow-dunder-method-names = ["__array__", "__array_ufunc__"]
+
 [tool.ruff.lint.per-file-ignores]
 "unit_tests/**/*.py" = ["S101"]
 "examples/run_all_examples.py" = ["S404", "S603"]
 "pyetsimul/log.py" = ["ANN401"]
+"docs/conf.py" = ["INP001"]  # Sphinx config file, not a package member
+"pyetsimul/core/eye.py" = ["PLR0904"]  # Eye is a domain object with many natural operations (orientation, pupil, cornea, eyelid, fovea, refraction, serialization)

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/unit_tests/test_angle2gaze.py

@@ -1,6 +1,7 @@
 """Unit tests for angle2gaze function."""
 
 import numpy as np
+import pytest
 
 from pyetsimul.geometry.conversions import angle2gaze
 from pyetsimul.types import Direction3D, Point2D, RotationMatrix
@@ -51,4 +52,4 @@ def test_output_properties() -> None:
     # The to_array() method should return a 4D homogeneous vector with the last component as 0
     result_array = np.array(result)
     assert result_array.shape == (4,)
-    assert result_array[3] == 0.0
+    assert result_array[3] == pytest.approx(0.0, abs=1e-9)

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/unit_tests/test_eye_find_cr.py

@@ -1,6 +1,7 @@
 """Unit tests for Eye.find_cr method."""
 
 import numpy as np
+import pytest
 
 from pyetsimul.core.camera import Camera
 from pyetsimul.core.eye import Eye
@@ -104,4 +105,4 @@ def test_output_properties() -> None:
     # Check types and shapes
     arr = np.array(cr)
     assert arr.shape == (4,)
-    assert arr[3] == 1.0  # Homogeneous coordinate
+    assert arr[3] == pytest.approx(1.0)  # Homogeneous coordinate

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/unit_tests/test_eye_find_cr_simple.py

@@ -1,6 +1,7 @@
 """Unit tests for Eye.find_cr_simple method."""
 
 import numpy as np
+import pytest
 
 from pyetsimul.core.camera import Camera
 from pyetsimul.core.eye import Eye
@@ -29,7 +30,7 @@ def test_basic_simple_corneal_reflex() -> None:
     # Test 4D homogeneous coordinates
     arr = np.array(cr)
     assert arr.shape == (4,)
-    assert arr[3] == 1.0
+    assert arr[3] == pytest.approx(1.0)
 
 
 def test_angled_positions() -> None:
@@ -52,7 +53,7 @@ def test_angled_positions() -> None:
     # Test 4D homogeneous coordinates
     arr = np.array(cr)
     assert arr.shape == (4,)
-    assert arr[3] == 1.0
+    assert arr[3] == pytest.approx(1.0)
 
 
 def test_reflex_outside_cornea_boundary() -> None:
@@ -85,4 +86,4 @@ def test_output_properties() -> None:
     # Check types and shapes
     arr = np.array(cr)
     assert arr.shape == (4,)
-    assert arr[3] == 1.0  # Homogeneous coordinate
+    assert arr[3] == pytest.approx(1.0)  # Homogeneous coordinate

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/unit_tests/test_geometry_types_arithmetic.py

@@ -183,7 +183,7 @@ class TestVector3D:
 
         # Magnitude
         mag = v.magnitude()
-        assert mag == 5.0
+        assert mag == pytest.approx(5.0)
 
         # Normalize
         normalized = v.normalize()
@@ -253,7 +253,7 @@ class TestPosition3D:
         pos2 = Position3D(3, 4, 0)
 
         distance = pos1.distance_to(pos2)
-        assert distance == 5.0
+        assert distance == pytest.approx(5.0)
 
 
 class TestDirection3D:

{pyetsimul-3.2.4 → pyetsimul-3.3.0}/unit_tests/test_glint_noise.py

@@ -55,19 +55,19 @@ def test_constant_offset_noise() -> None:
 
 def test_config_validation() -> None:
     """Test that GlintNoiseConfig raises errors for invalid configurations."""
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match=r"requires 'std' to be specified"):
         GlintNoiseConfig(noise_type="gaussian")  # Missing std
 
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match=r"requires 'std' to be specified"):
         GlintNoiseConfig(noise_type="uniform")  # Missing std
 
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match=r"requires 'offset_x' and 'offset_y'"):
         GlintNoiseConfig(noise_type="constant_offset", offset_x=1.0)  # Missing offset_y
 
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match=r"requires 'offset_x' and 'offset_y'"):
         GlintNoiseConfig(noise_type="constant_offset", offset_y=1.0)  # Missing offset_x
 
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match=r"Unknown noise type"):
         GlintNoiseConfig(noise_type="unknown_noise")  # Unknown noise type
 
 
@@ -88,21 +88,21 @@ def test_advanced_noise() -> None:
 def test_advanced_mode_validation() -> None:
     """Test validation for advanced mode parameters."""
     # Missing covariance
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match=r"requires both 'mean' and 'covariance'"):
         GlintNoiseConfig(mean=[0.0, 0.0])
 
     # Missing mean
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match=r"requires both 'mean' and 'covariance'"):
         GlintNoiseConfig(covariance=[[1.0, 0.0], [0.0, 1.0]])
 
     # Wrong mean size
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match=r"'mean' must be a 2-element list"):
         GlintNoiseConfig(mean=[0.0], covariance=[[1.0, 0.0], [0.0, 1.0]])
 
     # Wrong covariance size
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match=r"'covariance' must be a 2x2 matrix"):
         GlintNoiseConfig(mean=[0.0, 0.0], covariance=[[1.0]])
 
     # Negative definite covariance
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match=r"positive semidefinite"):
         GlintNoiseConfig(mean=[0.0, 0.0], covariance=[[-1.0, 0.0], [0.0, 1.0]])