EyE Annotation Tool

A Qt-based desktop tool for annotating pupil, limbus (iris), eyelid, and glints in eye images. Supports monocular and binocular projects with per-eye detector selection and annotations, and auto-detectors for each annotation type. Auto-detectors come from cheshm.

Features

• Monocular and binocular projects; detector selection, ROIs, and annotations stored per eye.
• Manual annotation of pupil ellipse, limbus ellipse, eyelid mask, and glints.
• Live auto-detection that re-runs on image load and detector swap.
• Auto-detectors are every pupil / glint / limbus detector cheshm exposes (Simple, ElSe, ExCuSe, PuRe, PuReST, PupilLabs2D, Starburst, Swirski2D for pupil; Simple for glint; active_contour, integro_differential, pupil_guided for limbus). See cheshm's detector list for licences.
• Project sessions with persistent defaults, undo, brightness/zoom controls, and review mode.
• CLI flags for batch use: --images, --review, --auto-detectors.

Installation

Requirements

• Python ≥3.10

From PyPI

pip install eye_annotation_tool

Using uv

uv pip install eye_annotation_tool

Or, to add it to an existing uv project:

uv add eye_annotation_tool

From source (editable / development)

git clone https://github.com/mh-salari/eye_annotation_tool.git
cd eye_annotation_tool
uv sync

Or with pip:

git clone https://github.com/mh-salari/eye_annotation_tool.git
cd eye_annotation_tool
python3 -m pip install -e .

Usage

eye_annotation_tool

Or as a module:

python -m eye_annotation_tool

Common CLI flags:

# Open a project and load extra images on top
eye_annotation_tool --project my_project.json --images img1.png img2.png

# Re-annotate a subset of images against an existing project (read-only)
eye_annotation_tool --project my_project.json --review img1.png img2.png

# Enable only a subset of auto-detectors this session
eye_annotation_tool --auto-detectors pupil,limbus

See eye_annotation_tool --help for the full flag list.

Adding your own detectors

To add a custom detector without modifying this project, drop a .py file in ~/.config/eye_annotation_tool/plugins/ (or any directory listed in the EYE_ANNOTATION_PLUGINS env var) that declares a module-level PLUGINS = [DetectorPlugin(...)] list. See eye_annotation_tool/auto_detectors/README.md for the full plugin contract and a minimal example.

Citing

If you use this software, please cite it using the following BibTeX entry:

@software{salari2025eye,
  author    = {Salari, Mohammadhossein},
  title     = {{EyE Annotation Tool}},
  year      = {2026},
  url       = {https://github.com/mh-salari/eye_annotation_tool},
  doi       = {10.5281/zenodo.18723470},
  license   = {MIT}
}

You can also click the "Cite this repository" button on the GitHub page for more citation formats.

License

This project is licensed under the MIT License - see the 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.