worldcoin · ShevchenkoRostyslav · Sep 1, 2025 · Jul 21, 2025 · Jul 21, 2025 · Jul 21, 2025
@@ -23,7 +23,7 @@ iris.pipelines.iris\_pipeline module
 iris.pipelines.multiframe\_aggregation\_pipeline module
 -------------------------------------------------------
 
-.. automodule:: iris.pipelines.templates_aggregation_pipeline
+.. automodule:: iris.pipelines.multiframe_aggregation_pipeline
    :members:
    :undoc-members:
    :show-inheritance:

@@ -1 +1 @@
-__version__ = "1.9.1"
+__version__ = "1.9.2"
@@ -1,5 +1,7 @@
 from typing import List
 
+import numpy as np
+
 from iris.callbacks.callback_interface import Callback
 from iris.io.class_configs import Algorithm
 from iris.io.dataclasses import EyeCenters, GeometryPolygons
@@ -9,11 +11,18 @@
 
 
 class FusionExtrapolation(Algorithm):
-    """Algorithm implements fusion extrapolation that consist of two concreate extrapolation algoriths.
-        1) circle extrapolation algorithm - linear extrapolation algorithm
-        2) ellipse extrapolation algorithm - least square ellipse fit with iris polygon refinement.
+    """Fuse two extrapolation strategies and pick the result based on shape statistics.
+
+    1) Circle-like extrapolation: LinearExtrapolation (linear extrapolation algorithm)
+    2) Ellipse-like extrapolation: LSQEllipseFitWithRefinement (least square ellipse fit with iris polygon refinement)
+
+    By default, the linear extrapolation is used. If the (relative) spread of radii
+    exceeds a threshold and the ellipse-based result looks sufficiently "regular"
+    (based on squared radii ratios), we prefer the ellipse fit.
 
-    By default the linear extrapolation algorithm is used but if standard deviation of radiuses is greater than given threshold then least square ellipse fit algorithm is applied because eye is ver likely to be more elliptical then circular.
+    Notes:
+    - "Relative std" means std/mean with an epsilon guard.
+    - We compare regularity via the relative std of iris/pupil squared-radius ratios under three centering choices (circle/circle, ellipse/ellipse, ellipse/circle).
     """
 
     class Parameters(Algorithm.Parameters):
@@ -22,33 +31,73 @@ class Parameters(Algorithm.Parameters):
         circle_extrapolation: Algorithm
         ellipse_fit: Algorithm
         algorithm_switch_std_threshold: float
+        algorithm_switch_std_conditioned_multiplier: float
 
     __parameters_type__ = Parameters
 
     def __init__(
         self,
         circle_extrapolation: Algorithm = LinearExtrapolation(dphi=360 / 512),
         ellipse_fit: Algorithm = LSQEllipseFitWithRefinement(dphi=360 / 512),
-        algorithm_switch_std_threshold: float = 3.5,
+        algorithm_switch_std_threshold: float = 0.014,
+        algorithm_switch_std_conditioned_multiplier: float = 2.0,
         callbacks: List[Callback] = [],
     ) -> None:
         """Assign parameters.
 
         Args:
             circle_extrapolation (Algorithm, optional): More circular shape estimation algorithm. Defaults to LinearExtrapolation(dphi=360 / 512, degrees / width of normalized image).
             ellipse_fit (Algorithm, optional): More elliptical shape estimation algorithm. Defaults to LSQEllipseFitWithRefinement(dphi=360 / 512, degrees / width of normalized image).
-            algorithm_switch_std_threshold (float, optional): Algorithm switch threshold. Defaults to 3.5.
+            algorithm_switch_std_threshold (float, optional): Threshold on (rel. std of iris + rel. std of pupil) beyond which we consider switching to ellipse.. Defaults to 0.014.
+            algorithm_switch_std_conditioned_multiplier (float, optional): How strongly iris spread penalizes circle regularity in the switch condition. Default: 2.0.
             callbacks (List[Callback], optional): _description_. Defaults to [].
         """
         super().__init__(
             ellipse_fit=ellipse_fit,
             circle_extrapolation=circle_extrapolation,
             algorithm_switch_std_threshold=algorithm_switch_std_threshold,
+            algorithm_switch_std_conditioned_multiplier=algorithm_switch_std_conditioned_multiplier,
             callbacks=callbacks,
         )
 
+    @staticmethod
+    def _relative_std(x: np.ndarray, eps: float = 1e-12) -> float:
+        """
+        Relative std = std / max(mean, eps).
+
+        Args:
+            x: 1D array-like.
+            eps: Small guard to avoid division by zero.
+
+        Returns:
+            float: relative std.
+        """
+        x = np.asarray(x)
+        m = float(np.mean(x))
+        s = float(np.std(x))
+        return s / max(abs(m), eps)
+
+    @staticmethod
+    def _squared_relative_radii(
+        iris_centered: np.ndarray, pupil_centered: np.ndarray, eps: float = 1e-12
+    ) -> np.ndarray:
+        """
+        Ratio of iris over pupil squared radii, element wise.
+
+        Args:
+            iris_centered: (N, 2) centered iris points.
+            pupil_centered: (N, 2) centered pupil points.
+            eps: Small guard to avoid division by zero.
+
+        Returns:
+            (N,) array: iris_sq / pupil_sq
+        """
+        iris_sq = np.sum(iris_centered**2, axis=1)
+        pupil_sq = np.sum(pupil_centered**2, axis=1)
+        return np.divide(iris_sq, np.maximum(pupil_sq, eps))
+
     def run(self, input_polygons: GeometryPolygons, eye_center: EyeCenters) -> GeometryPolygons:
-        """Perform extrapolation algorithm.
+        """Perform extrapolation algorithm and select the most plausible result.
 
         Args:
             input_polygons (GeometryPolygons): Smoothed polygons.
@@ -57,18 +106,53 @@ def run(self, input_polygons: GeometryPolygons, eye_center: EyeCenters) -> Geome
         Returns:
             GeometryPolygons: Extrapolated polygons
         """
-        xs, ys = input_polygons.iris_array[:, 0], input_polygons.iris_array[:, 1]
-        rhos, _ = cartesian2polar(xs, ys, eye_center.iris_x, eye_center.iris_y)
+        xs_iris, ys_iris = input_polygons.iris_array[:, 0], input_polygons.iris_array[:, 1]
+        rhos_iris, _ = cartesian2polar(xs_iris, ys_iris, eye_center.iris_x, eye_center.iris_y)
+        xs_pupil, ys_pupil = input_polygons.pupil_array[:, 0], input_polygons.pupil_array[:, 1]
+        rhos_pupil, _ = cartesian2polar(xs_pupil, ys_pupil, eye_center.pupil_x, eye_center.pupil_y)
+        circle_poly = self.params.circle_extrapolation(input_polygons, eye_center)
+        ellipse_poly = self.params.ellipse_fit(input_polygons)
+
+        circle_iris = circle_poly.iris_array
+        circle_pupil = circle_poly.pupil_array
+        ellipse_iris = ellipse_poly.iris_array
+        ellipse_pupil = ellipse_poly.pupil_array
+
+        circle_center = np.mean(circle_pupil, axis=0)
+        ellipse_center = np.mean(ellipse_pupil, axis=0)
+
+        circle_iris_centered = circle_iris - circle_center
+        circle_pupil_centered = circle_pupil - circle_center
+        ellipse_iris_centered = ellipse_iris - ellipse_center
+        ellipse_pupil_centered = ellipse_pupil - ellipse_center
+        ec_iris_centered = ellipse_iris - circle_center
+
+        cc = self._squared_relative_radii(circle_iris_centered, circle_pupil_centered)
+        ee = self._squared_relative_radii(ellipse_iris_centered, ellipse_pupil_centered)
+        ec = self._squared_relative_radii(ec_iris_centered, circle_pupil_centered)
+        cc_reg = self._relative_std(cc)
+        ee_reg = self._relative_std(ee)
+        ec_reg = self._relative_std(ec)
+
+        radius_std_iris = self._relative_std(rhos_iris)
+        radius_std_pupil = self._relative_std(rhos_pupil)
+        min_reg = min(ee_reg, ec_reg)
 
-        new_poly = self.params.circle_extrapolation(input_polygons, eye_center)
+        spread_ok = (radius_std_iris + radius_std_pupil) >= self.params.algorithm_switch_std_threshold
+        reg_ok = min_reg <= (cc_reg + radius_std_iris * self.params.algorithm_switch_std_conditioned_multiplier)
 
-        radius_std = rhos.std()
-        if radius_std > self.params.algorithm_switch_std_threshold:
-            ellipse_poly = self.params.ellipse_fit(input_polygons)
-            new_poly = GeometryPolygons(
-                pupil_array=new_poly.pupil_array,
-                iris_array=ellipse_poly.iris_array,
-                eyeball_array=input_polygons.eyeball_array,
-            )
+        if spread_ok and reg_ok:
+            if ee_reg <= ec_reg:
+                return GeometryPolygons(
+                    pupil_array=ellipse_poly.pupil_array,
+                    iris_array=ellipse_poly.iris_array,
+                    eyeball_array=input_polygons.eyeball_array,
+                )
+            else:
+                return GeometryPolygons(
+                    pupil_array=circle_poly.pupil_array,
+                    iris_array=ellipse_poly.iris_array,
+                    eyeball_array=input_polygons.eyeball_array,
+                )
 
-        return new_poly
+        return circle_poly
@@ -69,7 +69,7 @@ def __safe_serialize(object: Optional[Any]) -> Optional[Any]:
     elif isinstance(object, (list, tuple)):
         return type(object)(__safe_serialize(sub_object) for sub_object in object)
     elif isinstance(object, np.ndarray):
-        return object.tolist()
+        return object
     elif isinstance(object, (str, int, float, bool)):
         return object
     else:

@@ -1,12 +1,12 @@
 metadata:
   pipeline_name: multiframe_iris_pipeline
-  iris_version: 1.9.1
+  iris_version: 1.9.2
 
 # Configuration for individual image processing (IRISPipeline)
 iris_pipeline:
   metadata:
     pipeline_name: iris_pipeline
-    iris_version: 1.9.1
+    iris_version: 1.9.2
 
   pipeline:
     - name: segmentation
@@ -120,7 +120,8 @@ iris_pipeline:
             class_name: iris.LSQEllipseFitWithRefinement
             params:
               dphi: 0.703125
-          algorithm_switch_std_threshold: 3.5
+          algorithm_switch_std_threshold: 0.014
+          algorithm_switch_std_conditioned_multiplier: 2.0
       inputs:
         - name: input_polygons
           source_node: smoothing
@@ -313,7 +314,7 @@ iris_pipeline:
 # Configuration for template aggregation (TemplatesAggregationPipeline)
 templates_aggregation_pipeline:
   metadata:
-    iris_version: 1.9.1
+    iris_version: 1.9.2
     pipeline_name: templates_aggregation
 
   pipeline:

@@ -1,6 +1,6 @@
 metadata:
   pipeline_name: iris_pipeline
-  iris_version: 1.9.1
+  iris_version: 1.9.2
 
 pipeline:
   - name: segmentation
@@ -114,7 +114,8 @@ pipeline:
           class_name: iris.LSQEllipseFitWithRefinement
           params:
             dphi: 0.703125
-        algorithm_switch_std_threshold: 3.5
+        algorithm_switch_std_threshold: 0.014
+        algorithm_switch_std_conditioned_multiplier: 2.0
     inputs:
       - name: input_polygons
         source_node: smoothing

@@ -1,6 +1,6 @@
 metadata:
   pipeline_name: iris_pipeline
-  iris_version: 1.9.1
+  iris_version: 1.9.2
 
 pipeline:
   - name: segmentation
@@ -114,7 +114,8 @@ pipeline:
           class_name: iris.LSQEllipseFitWithRefinement
           params:
             dphi: 0.703125
-        algorithm_switch_std_threshold: 3.5
+        algorithm_switch_std_threshold: 0.014
+        algorithm_switch_std_conditioned_multiplier: 2.0
     inputs:
       - name: input_polygons
         source_node: smoothing
@@ -305,7 +306,7 @@ pipeline:
 
 templates_aggregation:
   metadata:
-    iris_version: 1.9.1
+    iris_version: 1.9.2
     pipeline_name: templates_aggregation
 
   pipeline:

@@ -288,19 +288,15 @@ def test_immutable_model_serialization(self):
         eye_centers = EyeCenters(pupil_x=1.0, pupil_y=2.0, iris_x=3.0, iris_y=4.0)
         assert SAFE_SERIALIZE(eye_centers) == eye_centers.serialize()
 
-    def test_numpy_array_to_list(self):
-        arr = np.array([[1, 2], [3, 4]])
-        assert SAFE_SERIALIZE(arr) == arr.tolist()
-
     def test_list_and_tuple_recursion(self):
         offgaze = Offgaze(score=0.25)
         arr = np.array([1, 2, 3])
 
         data_list = [1, "a", offgaze, arr]
-        assert SAFE_SERIALIZE(data_list) == [1, "a", offgaze.serialize(), arr.tolist()]
+        assert SAFE_SERIALIZE(data_list) == [1, "a", offgaze.serialize(), arr]
 
         data_tuple = (True, 3.14, offgaze, arr)
-        assert SAFE_SERIALIZE(data_tuple) == (True, 3.14, offgaze.serialize(), arr.tolist())
+        assert SAFE_SERIALIZE(data_tuple) == (True, 3.14, offgaze.serialize(), arr)
 
     def test_primitives_passthrough(self):
         assert SAFE_SERIALIZE("hello") == "hello"