Merge pull request #27 from worldcoin/tanguyjeanneau/open-iris-v1.1.0

worldcoin · Jun 11, 2024 · 8186c74 · 8186c74
2 parents a4748e2 + 6b35c7b
commit 8186c74
Show file tree

Hide file tree

Showing 52 changed files with 778 additions and 110 deletions.
diff --git a/colab/ConfiguringCustomPipeline.ipynb b/colab/ConfiguringCustomPipeline.ipynb
@@ -125,7 +125,7 @@
     "```yaml\n",
     "metadata:\n",
     "  pipeline_name: iris_pipeline\n",
-    "  iris_version: 1.0.0\n",
+    "  iris_version: 1.1.0\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",
@@ -205,7 +205,7 @@
    "outputs": [],
    "source": [
     "default_pipeline_conf = {\n",
-    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.0.0\"},\n",
+    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.1.0\"},\n",
     "    \"pipeline\": [\n",
     "        {\n",
     "            \"name\": \"segmentation\",\n",
@@ -480,7 +480,7 @@
    "outputs": [],
    "source": [
     "new_pipeline_conf = {\n",
-    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.0.0\"},\n",
+    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.1.0\"},\n",
     "    \"pipeline\": [\n",
     "        {\n",
     "            \"name\": \"segmentation\",\n",
@@ -759,7 +759,7 @@
    "outputs": [],
    "source": [
     "default_pipeline_conf = {\n",
-    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.0.0\"},\n",
+    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.1.0\"},\n",
     "    \"pipeline\": [\n",
     "        {\n",
     "            \"name\": \"segmentation\",\n",
@@ -1034,7 +1034,7 @@
    "outputs": [],
    "source": [
     "new_pipeline_conf = {\n",
-    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.0.0\"},\n",
+    "    \"metadata\": {\"pipeline_name\": \"iris_pipeline\", \"iris_version\": \"1.1.0\"},\n",
     "    \"pipeline\": [\n",
     "        {\n",
     "            \"name\": \"segmentation\",\n",
@@ -1385,7 +1385,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.0"
+   "version": "3.9.0"
   }
  },
  "nbformat": 4,

diff --git a/colab/GettingStarted.ipynb b/colab/GettingStarted.ipynb
@@ -111,8 +111,10 @@
    "outputs": [],
    "source": [
     "import cv2\n",
+    "import matplotlib.pyplot as plt\n",
     "\n",
-    "img_pixels = cv2.imread(\"./sample_ir_image.png\", cv2.IMREAD_GRAYSCALE)"
+    "img_pixels = cv2.imread(\"./sample_ir_image.png\", cv2.IMREAD_GRAYSCALE)\n",
+    "plt.imshow(img_pixels, cmap='gray')"
    ]
   },
   {
@@ -208,16 +210,6 @@
     "output[\"error\"] is None"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "6263acc3-3e7d-406b-a1e1-c628b13be7dd",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "output[\"error\"]"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "3b2896e5-5069-48db-b855-cd80ea04cd6e",
@@ -284,6 +276,7 @@
    "id": "d68022fc-51df-469e-8355-ecc6e12681d2",
    "metadata": {},
    "source": [
+    "----\n",
     "## 2. Configuring `IRISPipeline` environment"
    ]
   },
@@ -392,7 +385,8 @@
    "id": "a703f17c-b4ba-4e13-933d-b4101e067fb0",
    "metadata": {},
    "source": [
-    "## 3. Visualizing intermediate results"
+    "----\n",
+    "## 3. Visualizing results"
    ]
   },
   {
@@ -447,6 +441,148 @@
     "plt.show()"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "64c3c4f7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "output['metadata']['eye_side']"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a6ac23dc",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 4. Visualising intermediary results\n",
+    "\n",
+    "Here is how you can access the actual list of nodes (i.e. the graph of algorithms that were used to process the input image into an iris code) used in the iris pipeline"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "01697a7e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "iris_pipeline.params.pipeline"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a3b02dfd",
+   "metadata": {},
+   "source": [
+    "These are declared in the yaml file used to define the computation graph. By delaut, it is located at `src/iris/pipelines/confs/pipeline.yaml`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7eca2f39",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import yaml\n",
+    "with open('../src/iris/pipelines/confs/pipeline.yaml', 'r') as file:\n",
+    "    pipeline_config = yaml.safe_load(file)\n",
+    "pipeline_config"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dd07bc9e",
+   "metadata": {},
+   "source": [
+    "The iris pipeline object stores all intermediary results from the previous computation in its `call_trace`. This is reseted at every call, so only the latest intermediary results are available"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bbe1e8ea",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "iris_pipeline.call_trace['segmentation']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "acdf62cb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "canvas = iris_visualizer.plot_segmentation_map(\n",
+    "    ir_image=iris.IRImage(img_data=img_pixels, eye_side=\"right\"),\n",
+    "    segmap=iris_pipeline.call_trace['segmentation'],\n",
+    ")\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9c2a2a41",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "canvas = iris_visualizer.plot_all_geometry(\n",
+    "    ir_image=iris.IRImage(img_data=img_pixels, eye_side=\"right\"),\n",
+    "    geometry_polygons=iris_pipeline.call_trace['vectorization'],\n",
+    "    eye_orientation=iris_pipeline.call_trace['eye_orientation'],\n",
+    "    eye_center=iris_pipeline.call_trace['eye_center_estimation'],\n",
+    ")\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "52038fef",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "canvas = iris_visualizer.plot_all_geometry(\n",
+    "    ir_image=iris.IRImage(img_data=img_pixels, eye_side=\"right\"),\n",
+    "    geometry_polygons=iris_pipeline.call_trace['geometry_estimation'],\n",
+    "    eye_orientation=iris_pipeline.call_trace['eye_orientation'],\n",
+    "    eye_center=iris_pipeline.call_trace['eye_center_estimation'],\n",
+    ")\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "eba68cd5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "canvas = iris_visualizer.plot_normalized_iris(\n",
+    "    normalized_iris=iris_pipeline.call_trace['normalization'],\n",
+    ")\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d4e6399a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "canvas = iris_visualizer.plot_iris_template(\n",
+    "    iris_template=iris_pipeline.call_trace['encoder'],\n",
+    ")\n",
+    "plt.show()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "a3b7eab7-17cc-4e3f-a0d8-bf8e29463127",
@@ -474,7 +610,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.0"
+   "version": "3.9.0"
   }
  },
  "nbformat": 4,

diff --git a/colab/MatchingEntities.ipynb b/colab/MatchingEntities.ipynb
@@ -103,6 +103,26 @@
     "subject2_image = cv2.imread(\"./subject2_image.png\", cv2.IMREAD_GRAYSCALE)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "plt.imshow(subject1_first_image, cmap='gray')\n",
+    "plt.title('Subject 1, image 1')\n",
+    "plt.show()\n",
+    "\n",
+    "plt.imshow(subject1_second_image, cmap='gray')\n",
+    "plt.title('Subject 1, image 2')\n",
+    "plt.show()\n",
+    "\n",
+    "plt.imshow(subject2_image, cmap='gray')\n",
+    "plt.title('Subject 2, image 1')\n",
+    "plt.show()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -120,12 +140,14 @@
     "\n",
     "iris_pipeline = iris.IRISPipeline()\n",
     "\n",
-    "_ = iris_pipeline(subject1_first_image, eye_side=\"left\")\n",
-    "subject1_first_code = iris_pipeline.call_trace.get(\"encoder\")\n",
-    "_ = iris_pipeline(subject1_second_image, eye_side=\"left\")\n",
-    "subject1_second_code = iris_pipeline.call_trace.get(\"encoder\")\n",
-    "_ = iris_pipeline(subject2_image, eye_side=\"left\")\n",
-    "subject2_code = iris_pipeline.call_trace.get(\"encoder\")"
+    "output_1 = iris_pipeline(subject1_first_image, eye_side=\"left\")\n",
+    "subject1_first_code = output_1['iris_template']\n",
+    "\n",
+    "output_2 = iris_pipeline(subject1_second_image, eye_side=\"left\")\n",
+    "subject1_second_code = output_2['iris_template']\n",
+    "\n",
+    "output_3 = iris_pipeline(subject2_image, eye_side=\"left\")\n",
+    "subject2_code = output_3['iris_template']"
    ]
   },
   {
@@ -188,6 +210,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "The recommended threshold is between 0.34 and 0.39 depending on the sensibitity of your use case, 0.37 is a good choice if you do not favor False Matches or False Non-Matches.\n",
+    "\n",
+    "In this example, the two iris images from the same subject are clearly matched, and those form different subjects clearly non-matched.\n",
+    "\n",
     "### Thank you for making it to the end of this tutorial!"
    ]
   }
@@ -208,7 +234,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.0"
+   "version": "3.9.0"
   }
  },
  "nbformat": 4,

diff --git a/requirements/server.txt b/requirements/server.txt
@@ -1,3 +1,3 @@
 onnx==1.15.0
 onnxruntime==1.16.3
-opencv-python==4.8.1.78
+opencv-python==4.7.0.68
diff --git a/src/iris/__init__.py b/src/iris/__init__.py
@@ -85,4 +85,4 @@
 from iris.orchestration import error_managers, output_builders, pipeline_dataclasses
 from iris.orchestration.environment import Environment
 from iris.pipelines.iris_pipeline import IRISPipeline
-from iris.utils import common, math, visualisation
+from iris.utils import base64_encoding, common, math, visualisation
diff --git a/src/iris/_version.py b/src/iris/_version.py
@@ -1 +1 @@
-__version__ = "1.0.0"
+__version__ = "1.1.0"