Merge pull request #164 from worldcoin/dev

Dev

Author: ycbiometrics

IRIS_PERFORMANCE_CARD.md

@@ -10,7 +10,7 @@ A list of public and private entities participated in the ICE 2005 is shown belo
 
 <img src="./docs/performance_card/ice2005_results.png" width="800" alt="ICE 2005 results">
 
-Fig. 1(a) and 1(b) show the ROC on right and left eye, respectively, from all participants in Iris Challenge Evaluation (ICE) 2005 and Fig. 2(a) and 2(b) show our ROC in comparison*. Although the exact error rates were not published in [1], these plots show IRIS performs as good as if not better than commercial algorithms available at the time.
+Fig. 1(a) and 1(b) show the ROC on right and left eye, respectively, from all participants in Iris Challenge Evaluation (ICE) 2005 and Fig. 2(a) and 2(b) show our ROC in comparison*. Although the exact error rates were not published in [1], these plots show IRIS performs better than commercial algorithms available at the time.
 
 |<img src="./docs/performance_card/comparison_1a.png" alt="1a"> Fig. 1(a) participant ROC on ICE 2005 (right eye) [1]| <img src="./docs/performance_card/comparison_1b.png" alt="1b"> Fig. 1(b) participant ROC on ICE 2005 (left eye) [1]|
 |---|---|
@@ -21,16 +21,16 @@ Fig. 1(a) and 1(b) show the ROC on right and left eye, respectively, from all pa
 
 We also compare our performance with the latest available iris open source algorithm OSIRIS, which has three versions OSIRISV2, OSIRISV4, OSIRISV4.1 [3] as well as HDBIF [4]. As we can see in the table below, IRIS achieves significantly lower False NonMatch Rate (FNMR) at False Match Rate (FMR) of 0.001 and 0.0001 than these open source algorithms.
 
-|                   | OSIRISV2 <br>[2009] | OSIRISV4 <br>[2011] | OSIRISV4.1 <br>[2016] | HDBIF <br>[2019] | IRIS\* <br>[2023] |
+|                   | OSIRISV2 <br>[2009] | OSIRISV4 <br>[2011] | OSIRISV4.1 <br>[2016] | HDBIF <br>[2019] | IRIS\* <br>[2025] |
 |-------------------|----------|----------|------------|-------|--------|
-| FNMR @ FMR=0.001  | 0.174    | 0.031    | 0.019      | 0.025 | 0.003  |
-| FNMR @ FMR=0.0001 | 0.268    | 0.058    | 0.034      | 0.039 | 0.006  |
+| FNMR @ FMR=0.001  | 0.174    | 0.031    | 0.019      | 0.025 | 0.0012 |
+| FNMR @ FMR=0.0001 | 0.268    | 0.058    | 0.034      | 0.039 | 0.0020 |
 
-\*Note that four left eye images failed the default enrollment setting in IRIS with a Failure-To-Enroll (FTE) rate of 0.00135. 
+\*Note that five left eye and two right eye images failed enrollment in IRIS with a Failure-To-Enroll (FTE) rate of 0.00238.
 
 ## ND-LG4000 dataset
 
-ND-LG4000 dataset is part of the ND-CrossSensor-Iris-2013 public dataset from the University of Notre Dame [5]. This dataset was collected from 676 subjects using LG IrisAccess 4000 scanner with image resolution 640x480. We randomly chose 541 subjects for training, 67 subjects for validating the segmentation model in IRIS. The remaining 2187 images from 68 subjects were used for testing, resulting in a total of ~2.4 million matches.
+ND-LG4000 dataset is part of the ND-CrossSensor-Iris-2013 public dataset from the University of Notre Dame [5]. This dataset was collected from 676 subjects using LG IrisAccess 4000 scanner with image resolution 640x480. We randomly chose 541 subjects for training, 67 subjects for validating the segmentation model in IRIS. The remaining 2187 images from 68 subjects were used for testing, including 4 images failed in enrollment, resulting in a total of ~2.4 million matches.
 
 |<img src="./docs/performance_card/lg4000_3a.png" alt="3a"> Fig. 3(a) IRIS ROC on ND-LG4000| <img src="./docs/performance_card/lg4000_3b.png" alt="3b"> Fig. 3(b) IRIS DET on ND-LG4000|
 |---|---|

colab/ConfiguringCustomPipeline.ipynb

@@ -126,7 +126,7 @@
     "```yaml\n",
     "metadata:\n",
     "  pipeline_name: iris_pipeline\n",
-    "  iris_version: 1.9.4\n",
+    "  iris_version: 1.9.5\n",
     "```\n",
     "\n",
     "The top YAML file contains `IRISPipeline` metadata, used to both describe `IRISPipeline` and specify package parameters that are later used to verify compatibility between `iris` package version/release and later, specified in the `pipeline` YAML file section, pipeline's graph.\n",
@@ -206,7 +206,7 @@
    "outputs": [],
    "source": [
     "default_pipeline_conf = {\n",
-    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.9.4\"},\n",
+    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.9.5\"},\n",
     "    \"pipeline\": [\n",
     "        {\n",
     "            \"name\": \"segmentation\",\n",
@@ -481,7 +481,7 @@
    "outputs": [],
    "source": [
     "new_pipeline_conf = {\n",
-    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.9.4\"},\n",
+    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.9.5\"},\n",
     "    \"pipeline\": [\n",
     "        {\n",
     "            \"name\": \"segmentation\",\n",
@@ -760,7 +760,7 @@
    "outputs": [],
    "source": [
     "default_pipeline_conf = {\n",
-    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.9.4\"},\n",
+    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.9.5\"},\n",
     "    \"pipeline\": [\n",
     "        {\n",
     "            \"name\": \"segmentation\",\n",
@@ -1035,7 +1035,7 @@
    "outputs": [],
    "source": [
     "new_pipeline_conf = {\n",
-    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.9.4\"},\n",
+    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.9.5\"},\n",
     "    \"pipeline\": [\n",
     "        {\n",
     "            \"name\": \"segmentation\",\n",

docs/performance_card/comparison_2a.png

@@ -18,7 +18,7 @@ When the ``IRISPipeline`` pipeline is created with default parameters, it's grap
 
     metadata:
     pipeline_name: iris_pipeline
-    iris_version: 1.9.4
+    iris_version: 1.9.5
 
 The top YAML file contains ``IRISPipeline`` metadata, used to both describe ``IRISPipeline`` and specify package parameters that are later used to verify compatibility between ``iris`` package version/release and later, specified in the ``pipeline`` YAML file section, pipeline's graph.
 
@@ -93,7 +93,7 @@ First let's intantiate ``IRISPipeline`` with default configuration and see ``iri
 .. code-block:: python
 
     default_pipeline_conf = {
-        "metadata": {"pipeline_name": "iris_pipeline", "iris_version": "1.9.4"},
+        "metadata": {"pipeline_name": "iris_pipeline", "iris_version": "1.9.5"},
         "pipeline": [
             {
                 "name": "segmentation",
@@ -320,7 +320,7 @@ As expected all threshold values are set to default ``0.5`` value. Now, let's mo
 .. code-block:: python
 
     new_pipeline_conf = {
-        "metadata": {"pipeline_name": "iris_pipeline", "iris_version": "1.9.4"},
+        "metadata": {"pipeline_name": "iris_pipeline", "iris_version": "1.9.5"},
         "pipeline": [
             {
                 "name": "segmentation",
@@ -552,7 +552,7 @@ First let's instantiate ``IRISPipeline`` with default configuration and see node
 .. code-block:: python
 
     default_pipeline_conf = {
-        "metadata": {"pipeline_name": "iris_pipeline", "iris_version": "1.9.4"},
+        "metadata": {"pipeline_name": "iris_pipeline", "iris_version": "1.9.5"},
         "pipeline": [
             {
                 "name": "segmentation",
@@ -783,7 +783,7 @@ As expected, ``input_polygons`` argument of the ``run`` method is taken from the
 .. code-block:: python
 
     new_pipeline_conf = {
-        "metadata": {"pipeline_name": "iris_pipeline", "iris_version": "1.9.4"},
+        "metadata": {"pipeline_name": "iris_pipeline", "iris_version": "1.9.5"},
         "pipeline": [
             {
                 "name": "segmentation",

docs/performance_card/comparison_2b.png

@@ -1 +1 @@
-__version__ = "1.9.4"
+__version__ = "1.9.5"

docs/performance_card/lg4000_3a.png

@@ -38,18 +38,51 @@ def __init__(self, **kwargs: Any) -> None:
         """Assign parameters."""
         super().__init__(**kwargs)
 
-    def preprocess(self, image: np.ndarray, input_resolution: Tuple[int, int], nn_input_channels: int) -> np.ndarray:
+    def image_denoise(
+        self, image: np.ndarray, d: int, sigmaColor: int, sigmaSpace: int, intensityIgnore: int
+    ) -> np.ndarray:
+        """Apply de-noising preprocessing step.
+
+        Args:
+            image (np.ndarray): Image to denoise.
+            d (int): Diameter of each pixel neighborhood that is used during filtering.
+            sigmaColor (int): Filter sigma in color space.
+            sigmaSpace (int): Filter sigma in coordinate space.
+            intensityIgnore (int): Intensity threshold below which we do not apply filtering.
+
+        Returns:
+            np.ndarray: Denoised image.
+        """
+        # Bilateral filter to reduce noise while preserving edges.
+        filtered_image = cv2.bilateralFilter(image, d=d, sigmaColor=sigmaColor, sigmaSpace=sigmaSpace)
+        # Invert the mask to get the areas you do NOT want to filter
+        inverse_mask = image < intensityIgnore
+        filtered_region = filtered_image * (~inverse_mask)
+        # Isolate the original, unfiltered region (where the inverse mask is white)
+        original_region = image * inverse_mask
+        # Combine the two regions to get the final image
+        denoised_image = cv2.add(filtered_region, original_region)
+
+        return denoised_image
+
+    def preprocess(
+        self, image: np.ndarray, input_resolution: Tuple[int, int], nn_input_channels: int, denoise: bool
+    ) -> np.ndarray:
         """Preprocess image before running a model inference.
 
         Args:
             image (np.ndarray): Image to preprocess.
             input_resolution (Tuple[int, int]): A model input resolution.
+            denoise (bool): Whether to apply de-noising preprocessing step.
             nn_input_channels (int): A model input channels.
 
         Returns:
             np.ndarray: Preprocessed image.
         """
-        nn_input = cv2.resize(image.astype(float), input_resolution)
+        nn_input = cv2.resize(image.astype(float), input_resolution).astype(np.uint8)
+        if denoise:
+            nn_input = self.image_denoise(nn_input, d=5, sigmaColor=75, sigmaSpace=10, intensityIgnore=75)
+
         nn_input = np.divide(nn_input, 255)  # Replicates torchvision's ToTensor
 
         nn_input = np.expand_dims(nn_input, axis=-1)

docs/performance_card/lg4000_3b.png

@@ -26,6 +26,7 @@ class Parameters(MultilabelSemanticSegmentationInterface.Parameters):
         session: ort.InferenceSession
         input_resolution: Tuple[PositiveInt, PositiveInt]
         input_num_channels: Literal[1, 3]
+        denoise: bool
 
     __parameters_type__ = Parameters
 
@@ -35,6 +36,7 @@ def create_from_hugging_face(
         model_name: str = "iris_semseg_upp_scse_mobilenetv2.onnx",
         input_resolution: Tuple[PositiveInt, PositiveInt] = (640, 480),
         input_num_channels: Literal[1, 3] = 3,
+        denoise: bool = False,
         callbacks: List[Callback] = [],
     ) -> ONNXMultilabelSegmentation:
         """Create ONNXMultilabelSegmentation object with by downloading model from HuggingFace repository `MultilabelSemanticSegmentationInterface.HUGGING_FACE_REPO_ID`.
@@ -43,6 +45,7 @@ def create_from_hugging_face(
             model_name (str, optional): Name of the ONNX model stored in HuggingFace repo. Defaults to "iris_semseg_upp_scse_mobilenetv2.onnx".
             input_resolution (Tuple[PositiveInt, PositiveInt], optional): Neural Network input image resolution. Defaults to (640, 480).
             input_num_channels (Literal[1, 3], optional): Neural Network input image number of channels. Defaults to 3.
+            denoise (bool, optional): Whether to apply denoising preprocessing step. Defaults to False.
             callbacks (List[Callback], optional): List of algorithm callbacks. Defaults to [].
 
         Returns:
@@ -55,13 +58,14 @@ def create_from_hugging_face(
             filename=model_name,
         )
 
-        return ONNXMultilabelSegmentation(model_path, input_resolution, input_num_channels, callbacks)
+        return ONNXMultilabelSegmentation(model_path, input_resolution, input_num_channels, denoise, callbacks)
 
     def __init__(
         self,
         model_path: str,
         input_resolution: Tuple[PositiveInt, PositiveInt] = (640, 480),
         input_num_channels: Literal[1, 3] = 3,
+        denoise: bool = False,
         callbacks: List[Callback] = [],
     ) -> None:
         """Assign parameters.
@@ -70,6 +74,7 @@ def __init__(
             model_path (str): Path to the ONNX model.
             input_resolution (Tuple[PositiveInt, PositiveInt], optional): Neural Network input image resolution. Defaults to (640, 480).
             input_num_channels (Literal[1, 3], optional): Neural Network input image number of channels. Defaults to 3.
+            denoise (bool, optional): Whether to apply denoising preprocessing step. Defaults to False.
             callbacks (List[Callback], optional): List of algorithm callbacks. Defaults to [].
         """
         onnx_model = onnx.load(model_path)
@@ -79,6 +84,7 @@ def __init__(
             session=ort.InferenceSession(model_path, providers=["CPUExecutionProvider"]),
             input_resolution=input_resolution,
             input_num_channels=input_num_channels,
+            denoise=denoise,
             callbacks=callbacks,
         )
 
@@ -108,7 +114,9 @@ def _preprocess(self, image: np.ndarray) -> Dict[str, np.ndarray]:
         """
         nn_input = image.copy()
 
-        nn_input = self.preprocess(nn_input, self.params.input_resolution, self.params.input_num_channels)
+        nn_input = self.preprocess(
+            nn_input, self.params.input_resolution, self.params.input_num_channels, self.params.denoise
+        )
 
         return {self.params.session.get_inputs()[0].name: nn_input.astype(np.float32)}