eye-annotation-tool 1.0.0__tar.gz

eye_annotation_tool-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: twine upload dist/*

eye_annotation_tool-1.0.0/.gitignore

@@ -0,0 +1,170 @@
+.vscode
+ai/settings.json
+.DS_Store
+annotation_app/_version.py
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# uv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

eye_annotation_tool-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mohammadhossein Salari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eye_annotation_tool-1.0.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: eye_annotation_tool
+Version: 1.0.0
+Summary: A tool for annotating pupil and iris in eye images
+Project-URL: Homepage, https://github.com/mh-salari/eye_annotation_tool
+Project-URL: Repository, https://github.com/mh-salari/eye_annotation_tool
+Project-URL: Issues, https://github.com/mh-salari/eye_annotation_tool/issues
+Author-email: Mohammadhossein Salari <mohammadhossein.salari@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: annotation,computer vision,eye,eyelid,iris,pupil
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: pupil-detectors>=2.0.0
+Requires-Dist: pyqt5>=5.15.0
+Requires-Dist: scipy>=1.7.0
+Description-Content-Type: text/markdown
+
+# EyE Annotation Tool
+
+EyE Annotation Tool is a tool for annotating pupil, iris and eyelid in eye images. It provides a user-friendly interface for manual annotation and supports AI-assisted detection.
+
+<p align="center">
+<img src="annotation_app/resources/main_page.png" alt="EyE Annotation Tool Main Page" width="800">
+</p>
+
+## Features
+
+- Load and navigate through multiple eye images
+- Manual annotation of pupil, iris, eyelid, and glints
+- AI-assisted detection of pupil, iris, eyelid, and glints
+- Undo functionality for annotations
+- Save and load annotations
+- Extensible plugin system for custom detectors
+
+## Installation
+
+```bash
+pip install eye_annotation_tool
+```
+
+For the latest development version:
+
+```bash
+pip install git+https://github.com/mh-salari/eye_annotation_tool.git
+```
+
+### Using uv
+
+If you prefer [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/mh-salari/eye_annotation_tool.git
+cd eye_annotation_tool
+uv sync
+```
+
+> **Apple Silicon (M1/M2/M3) Note:** The `pupil-detectors` dependency only provides pre-built wheels for x86_64. On Apple Silicon Macs, you need to use an x86_64 Python via Rosetta 2:
+>
+> ```bash
+> uv python install cpython-3.11-macos-x86_64
+> uv python pin cpython-3.11-macos-x86_64
+> uv sync
+> ```
+
+## Usage
+
+```bash
+eye_annotation_tool
+```
+
+Or with uv:
+
+```bash
+uv run eye_annotation_tool
+```
+
+Or run it as a module:
+
+```bash
+python -m eye_annotation_tool
+```
+
+## Adding Custom Plugins
+
+EyE Annotation Tool supports custom plugins for pupil, iris and eyelid detection. To add a new plugin:
+
+1. Create a new Python file in the appropriate plugin directory.
+2. Define your detector class in this file.
+3. Ensure your detector follows the required interface.
+
+For a detailed guide on creating plugins, see the [Plugin Development Guide](ai/README.md) in the `ai` directory.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+This project has received funding from the European Union's Horizon Europe research and innovation funding program under grant agreement No 101072410, Eyes4ICU project.
+
+<p align="center">
+<img src="annotation_app/resources/Funded_by_EU_Eyes4ICU.png" alt="Funded by EU Eyes4ICU" width="500">
+</p>

eye_annotation_tool-1.0.0/README.md

@@ -0,0 +1,90 @@
+# EyE Annotation Tool
+
+EyE Annotation Tool is a tool for annotating pupil, iris and eyelid in eye images. It provides a user-friendly interface for manual annotation and supports AI-assisted detection.
+
+<p align="center">
+<img src="annotation_app/resources/main_page.png" alt="EyE Annotation Tool Main Page" width="800">
+</p>
+
+## Features
+
+- Load and navigate through multiple eye images
+- Manual annotation of pupil, iris, eyelid, and glints
+- AI-assisted detection of pupil, iris, eyelid, and glints
+- Undo functionality for annotations
+- Save and load annotations
+- Extensible plugin system for custom detectors
+
+## Installation
+
+```bash
+pip install eye_annotation_tool
+```
+
+For the latest development version:
+
+```bash
+pip install git+https://github.com/mh-salari/eye_annotation_tool.git
+```
+
+### Using uv
+
+If you prefer [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/mh-salari/eye_annotation_tool.git
+cd eye_annotation_tool
+uv sync
+```
+
+> **Apple Silicon (M1/M2/M3) Note:** The `pupil-detectors` dependency only provides pre-built wheels for x86_64. On Apple Silicon Macs, you need to use an x86_64 Python via Rosetta 2:
+>
+> ```bash
+> uv python install cpython-3.11-macos-x86_64
+> uv python pin cpython-3.11-macos-x86_64
+> uv sync
+> ```
+
+## Usage
+
+```bash
+eye_annotation_tool
+```
+
+Or with uv:
+
+```bash
+uv run eye_annotation_tool
+```
+
+Or run it as a module:
+
+```bash
+python -m eye_annotation_tool
+```
+
+## Adding Custom Plugins
+
+EyE Annotation Tool supports custom plugins for pupil, iris and eyelid detection. To add a new plugin:
+
+1. Create a new Python file in the appropriate plugin directory.
+2. Define your detector class in this file.
+3. Ensure your detector follows the required interface.
+
+For a detailed guide on creating plugins, see the [Plugin Development Guide](ai/README.md) in the `ai` directory.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+This project has received funding from the European Union's Horizon Europe research and innovation funding program under grant agreement No 101072410, Eyes4ICU project.
+
+<p align="center">
+<img src="annotation_app/resources/Funded_by_EU_Eyes4ICU.png" alt="Funded by EU Eyes4ICU" width="500">
+</p>

eye_annotation_tool-1.0.0/ai/README.md

@@ -0,0 +1,54 @@
+# Creating a New Plugin for EyE Annotation Tool
+
+This guide explains how to create a new pupil, iris or eyelid detector plugin for the EyE Annotation Tool application.
+
+## Steps to Create a New Plugin
+
+1. Create a new Python file in the appropriate directory:
+   - For pupil detectors: `ai/plugins/pupil_detectors/`
+   - For iris detectors: `ai/plugins/iris_detectors/`
+   - For eyelid detectors: `ai/plugins/eyelid_detectors/`
+
+2. Import the necessary modules:
+   ```python
+   from ai.plugin_interface import DetectorPlugin
+   import numpy as np
+   ```
+
+3. Create a new class that inherits from `DetectorPlugin`:
+   ```python
+   class MyNewDetector(DetectorPlugin):
+       def __init__(self):
+           # Initialize your detector here
+           pass
+
+       def detect(self, image_path):
+           # Implement your detection algorithm here
+           # Return the ellipse parameters and points
+           return ellipse, points
+
+       @property
+       def name(self):
+           # Return a unique name for your detector
+           return "my_new_detector"
+   ```
+
+4. Implement the `detect` method:
+   - Input: `image_path` path of the eye image
+   - Output: `ellipse` (dict with keys: 'center', 'axes', 'angle') and `points` (list of point coordinates)
+
+5. Set a unique `name` for your detector in the `name` property.
+
+6. Save your file with a descriptive name (e.g., `my_new_detector.py`).
+
+The plugin manager will automatically discover and load your new plugin when the application starts.
+
+## Example
+
+See `placeholder_iris_detector.py` for a simple example of a detector plugin.
+
+## Notes
+
+- Ensure your detector class inherits from `DetectorPlugin` and implements all required methods.
+- The `name` property should return a unique string to identify your detector.
+- Your `detect` method should handle various image sizes and conditions robustly.

eye_annotation_tool-1.0.0/ai/__init__.py

@@ -0,0 +1,6 @@
+"""AI plugin system for eye annotation detectors."""
+
+from .plugin_interface import DetectorPlugin
+from .plugin_manager import PluginManager
+
+__all__ = ["DetectorPlugin", "PluginManager"]

eye_annotation_tool-1.0.0/ai/plugin_interface.py

@@ -0,0 +1,28 @@
+"""Abstract base class for detector plugins."""
+
+from abc import ABC, abstractmethod
+
+
+class DetectorPlugin(ABC):
+    """Base class for all detector plugins (pupil, iris, eyelid)."""
+
+    @abstractmethod
+    def __init__(self) -> None:
+        """Initialize the detector plugin."""
+
+    @abstractmethod
+    def detect(self, image: str) -> tuple | list:
+        """Detect features in the given image.
+
+        Args:
+            image: Path to the image file.
+
+        Returns:
+            Detection results as tuple or list depending on detector type.
+
+        """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Get the name of the detector plugin."""

eye_annotation_tool-1.0.0/ai/plugin_manager.py

@@ -0,0 +1,119 @@
+"""Plugin manager for loading and managing detector plugins."""
+
+import importlib.util
+from pathlib import Path
+
+from .plugin_interface import DetectorPlugin
+
+
+class PluginManager:
+    """Manages loading and accessing detector plugins for pupil, iris, and eyelid detection."""
+
+    def __init__(self) -> None:
+        """Initialize the PluginManager."""
+        self.pupil_detectors = {}
+        self.iris_detectors = {}
+        self.eyelid_detectors = {}
+        self.load_plugins()
+
+    def load_plugins(self) -> None:
+        """Load all detector plugins from the plugins directory."""
+        plugin_dirs = [
+            Path(__file__).parent / "plugins" / "pupil_detectors",
+            Path(__file__).parent / "plugins" / "iris_detectors",
+            Path(__file__).parent / "plugins" / "eyelid_detectors",
+        ]
+
+        for plugin_dir in plugin_dirs:
+            self.load_plugins_from_directory(plugin_dir)
+
+    def load_plugins_from_directory(self, directory: Path) -> None:
+        """Load plugins from a specific directory and register them by type.
+
+        Args:
+            directory: Path to the directory containing plugin files.
+
+        """
+        plugin_type = Path(directory).name
+        for file_path in Path(directory).iterdir():
+            if file_path.suffix == ".py" and not file_path.name.startswith("__"):
+                module_name = file_path.stem
+                module_path = str(file_path)
+                spec = importlib.util.spec_from_file_location(module_name, module_path)
+                module = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(module)
+                for item_name in dir(module):
+                    item = getattr(module, item_name)
+                    if isinstance(item, type) and issubclass(item, DetectorPlugin) and item is not DetectorPlugin:
+                        plugin_instance = item()
+                        if plugin_type == "pupil_detectors":
+                            self.pupil_detectors[plugin_instance.name] = plugin_instance
+                        elif plugin_type == "iris_detectors":
+                            self.iris_detectors[plugin_instance.name] = plugin_instance
+                        elif plugin_type == "eyelid_detectors":
+                            self.eyelid_detectors[plugin_instance.name] = plugin_instance
+                        else:
+                            print(f"Unknown plugin type: {plugin_type}")
+
+    def get_pupil_detector(self, name: str) -> DetectorPlugin | None:
+        """Get a pupil detector plugin by name.
+
+        Args:
+            name: Name of the pupil detector.
+
+        Returns:
+            The detector plugin instance or None if not found.
+
+        """
+        return self.pupil_detectors.get(name)
+
+    def get_iris_detector(self, name: str) -> DetectorPlugin | None:
+        """Get an iris detector plugin by name.
+
+        Args:
+            name: Name of the iris detector.
+
+        Returns:
+            The detector plugin instance or None if not found.
+
+        """
+        return self.iris_detectors.get(name)
+
+    def get_pupil_detector_names(self) -> list[str]:
+        """Get list of available pupil detector names.
+
+        Returns:
+            List of pupil detector names.
+
+        """
+        return list(self.pupil_detectors.keys())
+
+    def get_iris_detector_names(self) -> list[str]:
+        """Get list of available iris detector names.
+
+        Returns:
+            List of iris detector names.
+
+        """
+        return list(self.iris_detectors.keys())
+
+    def get_eyelid_detector(self, name: str) -> DetectorPlugin | None:
+        """Get an eyelid detector plugin by name.
+
+        Args:
+            name: Name of the eyelid detector.
+
+        Returns:
+            The detector plugin instance or None if not found.
+
+        """
+        return self.eyelid_detectors.get(name)
+
+    def get_eyelid_detector_names(self) -> list[str]:
+        """Get list of available eyelid detector names.
+
+        Returns:
+            List of eyelid detector names.
+
+        """
+        return list(self.eyelid_detectors.keys())

eye_annotation_tool-1.0.0/ai/plugins/__init__.py

@@ -0,0 +1,4 @@
+"""AI detector plugins for pupil, iris, and eyelid detection."""
+
+# This file can be left empty
+# It marks the plugins directory as a Python package

eye_annotation_tool-1.0.0/ai/plugins/eyelid_detectors/__init__.py

@@ -0,0 +1 @@
+"""Eyelid detector plugins."""

eye_annotation_tool-1.0.0/ai/plugins/eyelid_detectors/placeholder_eyelid_detector.py

@@ -0,0 +1,42 @@
+"""Placeholder eyelid detector for testing purposes."""
+
+from ai.plugin_interface import DetectorPlugin
+
+
+class PlaceholderEyelidDetector(DetectorPlugin):
+    """Placeholder eyelid detector that returns dummy contour points."""
+
+    def __init__(self) -> None:
+        """Initialize the PlaceholderEyelidDetector."""
+
+    def detect(self, image_path: str) -> list[tuple[float, float]]:  # noqa: PLR6301 ARG002
+        """Detect eyelid contour in the given image (returns placeholder data).
+
+        Args:
+            image_path: Path to the image file.
+
+        Returns:
+            List of points representing the eyelid contour.
+
+        """
+        # For this example, we'll ignore the actual image content
+        # and just return 4 fixed points representing an eyelid contour
+
+        # Assuming image size of 192x192 (same as in the iris example)
+        height, width = 192, 192
+
+        # Define 4 points for the eyelid contour
+        # These points form a simple curve across the top of the "eye"
+        points = [
+            (width * 0.2, height * 0.3),  # Left point
+            (width * 0.4, height * 0.2),  # Left-middle point
+            (width * 0.6, height * 0.2),  # Right-middle point
+            (width * 0.8, height * 0.3),  # Right point
+        ]
+
+        return points
+
+    @property
+    def name(self) -> str:
+        """Get the name of the detector plugin."""
+        return "test"