______________________________________________________________________
<div align="center">
<p align="center">
<a href="https://worldcoin.org/"><img src="https://github.com/worldcoin/open-iris/blob/main/docs/source/images/logos/wld.png" width=150px></img></a>
</p>
# **_IRIS: Iris Recognition Inference System_**
<a href="https://worldcoin.github.io/open-iris/">Package documentation</a> •
<a href="https://colab.research.google.com/github/worldcoin/open-iris/blob/main/colab/GettingStarted.ipynb">_Getting started_ tutorial</a> •
<a href="https://huggingface.co/Worldcoin/iris-semantic-segmentation/tree/main">Hugging Face repo</a> •
<a href="https://worldcoin.org/blog/engineering/iris-recognition-inference-system">IRIS blog post</a>
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/astral-sh/ruff)
[](https://github.com/psf/black)
[](https://pycqa.github.io/isort/)
[](http://www.pydocstyle.org/en/stable/) <br />
[](https://github.com/worldcoin/open-iris/actions/workflows/ci-testing.yml)
[](https://github.com/worldcoin/open-iris/actions/workflows/check-release-version.yml)
______________________________________________________________________
</div>
## Table of contents
- [About](#about)
- [Quickstart](#quickstart)
- [Installation](#installation)
- [Setup for development](#setup-for-development)
- [Running inference](#Running-inference)
- [Project structure](#project-structure)
- [Example notebooks](#example-notebooks)
- [Documentation](#documentation)
- [Issues, pull requests and feature requests](#issues-pull-requests-and-feature-requests)
- [License](#license)
- [Resources](#resources)
## About
Welcome to Worldcoin's Iris Recognition Inference System (IRIS) project, an advanced iris recognition pipeline designed for robust and secure biometric verification. This project leverages state-of-the-art computer vision and machine learning techniques to provide accurate and efficient iris recognition system.
Iris recognition is a powerful biometric technology that identifies individuals based on the unique patterns within the iris of the eye. IRIS package aims to make iris recognition accessible and enable further advancement in the field.
Project features highlights are:
- **Large-Scale Verification**: Capable of verifying uniqueness among billions of users.
- **High-Performance Iris Segmentation**: Accurate segmentation of iris regions for precise feature extraction.
- **Scalable Matching Algorithm**: Robust matching algorithm designed for scalability without compromising accuracy.
- **User-Friendly Integration**: Simple integration into applications that demand seamless biometric verification.
High-level iris recognition pipeline steps overview:
1. **Iris Image Input**: Provide an iris image for verification.
2. **Iris Segmentation**: Identify and isolate the iris region within the image.
3. **Feature Extraction**: Extract unique features from the iris to create a template.
4. **Scalable Matching**: Efficiently compare extracted features for large-scale uniqueness verification.
5. **Result**: Receive the verification result with a confidence score, enabling secure and scalable authentication.
The Worldcoin system utilizes iris recognition algorithm for verifying uniqueness in a challenging environment, involving billions of individuals. This entails a detailed exploration of the Worldcoin biometric pipeline, a system that confirms uniqueness through the encoding of iris texture into an iris code.
More detailed pipeline overview can be found in our [blog post](https://worldcoin.org/blog/engineering/iris-recognition-inference-system) dedicated to IRIS project.
## Disclaimer
_The Iris Recognition Inference System (IRIS) software repository is owned and maintained by the Worldcoin Foundation, the steward of the Worldcoin protocol; the repository is not affiliated with any other project or service provider_
## Quickstart
### Installation
Installation is as simple as running `pip install` with specifying `IRIS_ENV` installation global flag (`IRIS_ENV` flag may be skipped if `iris` is installed from PyPl server but this option is only available when `iris` is installed on local machine). The `IRIS_ENV` flag is used to indicate an "environment" in which package is meant to work. Possible options are:
1. `SERVER` - For installing `iris` package with dependecies required for running an inference on a local machines.
```bash
# On a local machine
pip install open-iris
# or directly from GitHub
IRIS_ENV=SERVER pip install git+https://github.com/worldcoin/open-iris.git
```
2. `ORB` - For installing `iris` package with dependecies required for running an inference on the Orb.
```bash
# On the Orb
IRIS_ENV=ORB pip install git+https://github.com/worldcoin/open-iris.git
```
3. `DEV` - For installing iris package together with packages necessary for development of `iris` package.
```bash
# For development
IRIS_ENV=DEV pip install git+https://github.com/worldcoin/open-iris.git
```
After successfully installing `iris`, verify your installation by attempting to import.
```bash
python3 -c "import iris; print(iris.__version__)"
```
### Setup for development
A `conda` environment simplifies the setup process for developing on the `iris` package. This `conda` environment ensures a seamless and consistent setup for contributors, reducing the complexity of dependency management. By utilizing `conda`, developers can easily replicate the development environment across different systems, minimizing potential setup obstacles. This approach aims to make it straightforward for anyone interested in contributing to quickly set up and engage in the development of `iris` package.
```bash
# Clone the iris repo
git clone https://github.com/worldcoin/open-iris
# Go to the repo directory
cd open-iris
# Create and activate conda environment
IRIS_ENV=DEV conda env create -f ./conda/environment_dev.yml
conda activate iris_dev
# (Optional, but recommended) Install git hooks to preserve code format consistency
pre-commit install
nb-clean add-filter --remove-empty-cells
```
### Running inference
A simple inference run can be achived by running source code below.
```python
import cv2
import iris
# 1. Create IRISPipeline object
iris_pipeline = iris.IRISPipeline()
# 2. Load IR image of an eye
img_pixels = cv2.imread("/path/to/ir/image", cv2.IMREAD_GRAYSCALE)
# 3. Perform inference
# Options for the `eye_side` argument are: ["left", "right"]
output = iris_pipeline(img_data=img_pixels, eye_side="left")
```
To fully explore and understand the extensive capabilities of the iris package, visit the [Example notebooks](#example-notebooks) section. Here, you'll find a collection of Jupyter Notebooks that serve as valuable resources, offering practical guides and real-world examples to provide a comprehensive insight into the rich functionalities and potential applications of the `iris` package.
## Project structure
The `iris` package features a structured design with modular components, enhancing code organization and scalability.
| **Module** | **Description** |
|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| [`iris`](https://worldcoin.github.io/open-iris/) | an iris recognition package |
| [`iris.callbacks`](https://worldcoin.github.io/open-iris/) | a module that implements callbacks used to customize on execute start and end behaviours of node or pipeline call |
| [`iris.io`](https://worldcoin.github.io/open-iris/) | a module that contains dataclasses and errors that flow through iris recognition pipeline when called |
| [`iris.nodes`](https://worldcoin.github.io/open-iris/) | a module that contains implementation of iris recognition pipeline nodes |
| [`iris.orchestration`](https://worldcoin.github.io/open-iris/) | a module that contains iris recognition pipeline's orchestration support mechanisms |
| [`iris.pipelines`](https://worldcoin.github.io/open-iris/) | a module that contains implementation of iris recognition pipelines |
| [`iris.utils`](https://worldcoin.github.io/open-iris/) | a module that contains utilities used throughout the code base and modules usefull for outputs analysis |
## Example notebooks
The Jupyter Notebooks provided present practical guides and real-world instances to demonstrate the complete capabilities of the `iris` package.
1. **Getting started** [](https://colab.research.google.com/github/worldcoin/open-iris/blob/main/colab/GettingStarted.ipynb)
2. **Configuring custom pipeline** [](https://colab.research.google.com/github/worldcoin/open-iris/blob/main/colab/ConfiguringCustomPipeline.ipynb)
## Documentation
For detailed documentation, including installation instructions, usage guidelines, and configuration options, please refer to the IRIS project [documentation](https://worldcoin.github.io/open-iris/).
## Issues, pull requests and feature requests
If you have any question or you found a bug or you feel like some feature is missing, please don't hesitate to file a new issue, discussion or PR with respective title and description.
Any suggestion for potential project improvements are and will always be welcome!
Feel free to reach out to any project [contributor](https://github.com/worldcoin/open-iris/graphs/contributors)!
## License
This project is licensed under the [MIT license](https://github.com/worldcoin/open-iris/blob/main/LICENSE).
## Resources
1. [_"Iris Recognition Inference System"_](https://worldcoin.org/blog/engineering/iris-recognition-inference-system)
2. [_"Iris feature extraction with 2D Gabor wavelets"_](https://worldcoin.org/blog/engineering/iris-feature-extraction)
3. [_"How iris recognition works"_](https://ieeexplore.ieee.org/document/1262028)
Raw data
{
"_id": null,
"home_page": "https://github.com/worldcoin/open-iris",
"name": "open-iris",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "biometrics,iris recognition",
"author": "Worldcoin AI",
"author_email": "ai@worldcoin.org",
"download_url": "https://files.pythonhosted.org/packages/2d/3a/3c5d6ead10da276b86f28338a857e663bc33f804c45ff9bdc7d27e7dcb32/open-iris-1.0.0.tar.gz",
"platform": null,
"description": "______________________________________________________________________\n<div align=\"center\">\n\n<p align=\"center\">\n <a href=\"https://worldcoin.org/\"><img src=\"https://github.com/worldcoin/open-iris/blob/main/docs/source/images/logos/wld.png\" width=150px></img></a>\n</p>\n\n# **_IRIS: Iris Recognition Inference System_**\n\n<a href=\"https://worldcoin.github.io/open-iris/\">Package documentation</a> \u2022\n<a href=\"https://colab.research.google.com/github/worldcoin/open-iris/blob/main/colab/GettingStarted.ipynb\">_Getting started_ tutorial</a> \u2022\n<a href=\"https://huggingface.co/Worldcoin/iris-semantic-segmentation/tree/main\">Hugging Face repo</a> \u2022\n<a href=\"https://worldcoin.org/blog/engineering/iris-recognition-inference-system\">IRIS blog post</a>\n\n[](https://github.com/pre-commit/pre-commit)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/psf/black)\n[](https://pycqa.github.io/isort/)\n[](http://www.pydocstyle.org/en/stable/) <br />\n[](https://github.com/worldcoin/open-iris/actions/workflows/ci-testing.yml)\n[](https://github.com/worldcoin/open-iris/actions/workflows/check-release-version.yml)\n\n______________________________________________________________________\n\n</div>\n\n## Table of contents\n\n- [About](#about)\n- [Quickstart](#quickstart)\n - [Installation](#installation)\n - [Setup for development](#setup-for-development)\n - [Running inference](#Running-inference)\n- [Project structure](#project-structure)\n- [Example notebooks](#example-notebooks)\n- [Documentation](#documentation)\n- [Issues, pull requests and feature requests](#issues-pull-requests-and-feature-requests)\n- [License](#license)\n- [Resources](#resources)\n\n## About\n\nWelcome to Worldcoin's Iris Recognition Inference System (IRIS) project, an advanced iris recognition pipeline designed for robust and secure biometric verification. This project leverages state-of-the-art computer vision and machine learning techniques to provide accurate and efficient iris recognition system.\n\nIris recognition is a powerful biometric technology that identifies individuals based on the unique patterns within the iris of the eye. IRIS package aims to make iris recognition accessible and enable further advancement in the field.\n\nProject features highlights are:\n- **Large-Scale Verification**: Capable of verifying uniqueness among billions of users.\n- **High-Performance Iris Segmentation**: Accurate segmentation of iris regions for precise feature extraction.\n- **Scalable Matching Algorithm**: Robust matching algorithm designed for scalability without compromising accuracy.\n- **User-Friendly Integration**: Simple integration into applications that demand seamless biometric verification.\n\nHigh-level iris recognition pipeline steps overview:\n1. **Iris Image Input**: Provide an iris image for verification.\n2. **Iris Segmentation**: Identify and isolate the iris region within the image.\n3. **Feature Extraction**: Extract unique features from the iris to create a template.\n4. **Scalable Matching**: Efficiently compare extracted features for large-scale uniqueness verification.\n5. **Result**: Receive the verification result with a confidence score, enabling secure and scalable authentication.\n\nThe Worldcoin system utilizes iris recognition algorithm for verifying uniqueness in a challenging environment, involving billions of individuals. This entails a detailed exploration of the Worldcoin biometric pipeline, a system that confirms uniqueness through the encoding of iris texture into an iris code.\n\nMore detailed pipeline overview can be found in our [blog post](https://worldcoin.org/blog/engineering/iris-recognition-inference-system) dedicated to IRIS project.\n\n\n## Disclaimer\n\n_The Iris Recognition Inference System (IRIS) software repository is owned and maintained by the Worldcoin Foundation, the steward of the Worldcoin protocol; the repository is not affiliated with any other project or service provider_\n\n\n## Quickstart\n\n### Installation\n\nInstallation is as simple as running `pip install` with specifying `IRIS_ENV` installation global flag (`IRIS_ENV` flag may be skipped if `iris` is installed from PyPl server but this option is only available when `iris` is installed on local machine). The `IRIS_ENV` flag is used to indicate an \"environment\" in which package is meant to work. Possible options are:\n1. `SERVER` - For installing `iris` package with dependecies required for running an inference on a local machines.\n```bash\n# On a local machine\npip install open-iris\n# or directly from GitHub\nIRIS_ENV=SERVER pip install git+https://github.com/worldcoin/open-iris.git\n```\n2. `ORB` - For installing `iris` package with dependecies required for running an inference on the Orb.\n```bash\n# On the Orb\nIRIS_ENV=ORB pip install git+https://github.com/worldcoin/open-iris.git\n```\n3. `DEV` - For installing iris package together with packages necessary for development of `iris` package.\n```bash\n# For development\nIRIS_ENV=DEV pip install git+https://github.com/worldcoin/open-iris.git\n```\n\nAfter successfully installing `iris`, verify your installation by attempting to import.\n```bash\npython3 -c \"import iris; print(iris.__version__)\"\n```\n\n### Setup for development\n\nA `conda` environment simplifies the setup process for developing on the `iris` package. This `conda` environment ensures a seamless and consistent setup for contributors, reducing the complexity of dependency management. By utilizing `conda`, developers can easily replicate the development environment across different systems, minimizing potential setup obstacles. This approach aims to make it straightforward for anyone interested in contributing to quickly set up and engage in the development of `iris` package.\n\n```bash\n# Clone the iris repo\ngit clone https://github.com/worldcoin/open-iris\n\n# Go to the repo directory\ncd open-iris\n\n# Create and activate conda environment\nIRIS_ENV=DEV conda env create -f ./conda/environment_dev.yml\nconda activate iris_dev\n\n# (Optional, but recommended) Install git hooks to preserve code format consistency\npre-commit install\nnb-clean add-filter --remove-empty-cells\n```\n\n### Running inference\n\nA simple inference run can be achived by running source code below.\n\n```python\nimport cv2\nimport iris\n\n# 1. Create IRISPipeline object\niris_pipeline = iris.IRISPipeline()\n\n# 2. Load IR image of an eye\nimg_pixels = cv2.imread(\"/path/to/ir/image\", cv2.IMREAD_GRAYSCALE)\n\n# 3. Perform inference\n# Options for the `eye_side` argument are: [\"left\", \"right\"]\noutput = iris_pipeline(img_data=img_pixels, eye_side=\"left\")\n```\n\nTo fully explore and understand the extensive capabilities of the iris package, visit the [Example notebooks](#example-notebooks) section. Here, you'll find a collection of Jupyter Notebooks that serve as valuable resources, offering practical guides and real-world examples to provide a comprehensive insight into the rich functionalities and potential applications of the `iris` package.\n\n## Project structure\n\nThe `iris` package features a structured design with modular components, enhancing code organization and scalability.\n\n| **Module** | **Description** |\n|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|\n| [`iris`](https://worldcoin.github.io/open-iris/) | an iris recognition package |\n| [`iris.callbacks`](https://worldcoin.github.io/open-iris/) | a module that implements callbacks used to customize on execute start and end behaviours of node or pipeline call |\n| [`iris.io`](https://worldcoin.github.io/open-iris/) | a module that contains dataclasses and errors that flow through iris recognition pipeline when called |\n| [`iris.nodes`](https://worldcoin.github.io/open-iris/) | a module that contains implementation of iris recognition pipeline nodes |\n| [`iris.orchestration`](https://worldcoin.github.io/open-iris/) | a module that contains iris recognition pipeline's orchestration support mechanisms |\n| [`iris.pipelines`](https://worldcoin.github.io/open-iris/) | a module that contains implementation of iris recognition pipelines |\n| [`iris.utils`](https://worldcoin.github.io/open-iris/) | a module that contains utilities used throughout the code base and modules usefull for outputs analysis |\n\n## Example notebooks\n\nThe Jupyter Notebooks provided present practical guides and real-world instances to demonstrate the complete capabilities of the `iris` package.\n\n1. **Getting started** [](https://colab.research.google.com/github/worldcoin/open-iris/blob/main/colab/GettingStarted.ipynb)\n2. **Configuring custom pipeline** [](https://colab.research.google.com/github/worldcoin/open-iris/blob/main/colab/ConfiguringCustomPipeline.ipynb)\n\n## Documentation\n\nFor detailed documentation, including installation instructions, usage guidelines, and configuration options, please refer to the IRIS project [documentation](https://worldcoin.github.io/open-iris/).\n\n## Issues, pull requests and feature requests\n\nIf you have any question or you found a bug or you feel like some feature is missing, please don't hesitate to file a new issue, discussion or PR with respective title and description.\nAny suggestion for potential project improvements are and will always be welcome!\n\nFeel free to reach out to any project [contributor](https://github.com/worldcoin/open-iris/graphs/contributors)!\n\n## License\n\nThis project is licensed under the [MIT license](https://github.com/worldcoin/open-iris/blob/main/LICENSE).\n\n## Resources\n\n1. [_\"Iris Recognition Inference System\"_](https://worldcoin.org/blog/engineering/iris-recognition-inference-system)\n2. [_\"Iris feature extraction with 2D Gabor wavelets\"_](https://worldcoin.org/blog/engineering/iris-feature-extraction)\n3. [_\"How iris recognition works\"_](https://ieeexplore.ieee.org/document/1262028)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "IRIS: Iris Recognition Inference System of the Worldcoin project.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/worldcoin/open-iris"
},
"split_keywords": [
"biometrics",
"iris recognition"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad5d70a9e5ea5630931048d3d101611888d167970b8c74a3924b9c6f915b514a",
"md5": "c1d4f04bd863209a5ae8cc484e2a7024",
"sha256": "e718209cbbd3989fd3a68cae6502422f0a1a1619084df6b01432a58a06ba272f"
},
"downloads": -1,
"filename": "open_iris-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c1d4f04bd863209a5ae8cc484e2a7024",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 91612,
"upload_time": "2023-12-14T12:26:38",
"upload_time_iso_8601": "2023-12-14T12:26:38.717173Z",
"url": "https://files.pythonhosted.org/packages/ad/5d/70a9e5ea5630931048d3d101611888d167970b8c74a3924b9c6f915b514a/open_iris-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2d3a3c5d6ead10da276b86f28338a857e663bc33f804c45ff9bdc7d27e7dcb32",
"md5": "02f3ffd2ed965c1fef12e42cf59c0fe6",
"sha256": "136cea786891c77bbde498b6765d15f42bb9072027d2a58874d6911f2938d9ff"
},
"downloads": -1,
"filename": "open-iris-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "02f3ffd2ed965c1fef12e42cf59c0fe6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 71350,
"upload_time": "2023-12-14T12:27:13",
"upload_time_iso_8601": "2023-12-14T12:27:13.346437Z",
"url": "https://files.pythonhosted.org/packages/2d/3a/3c5d6ead10da276b86f28338a857e663bc33f804c45ff9bdc7d27e7dcb32/open-iris-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-14 12:27:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "worldcoin",
"github_project": "open-iris",
"github_not_found": true,
"lcname": "open-iris"
}
JSON
