How pupil-labs/pupil-detectors works
Project Type and Purpose
• This is an open-source Python library (“pupil-detectors”) that provides standalone 2D pupil detection algorithms.
• It exposes a Python API (Detector2D) that wraps high-performance C++ implementations (coarse pupil detector, single-eye fitter, detector_2d).
File Structure
Top-level files
• setup.py, pyproject.toml, setup.cfg, MANIFEST.in – packaging and installation.
• .github/, tox.ini, pytest.ini – CI, linting, testing configurations.
• docs/ and README.rst – user and developer documentation.
• scripts/ – helper scripts for building manylinux wheels.
• tests/ – pytest test suite (tests/test_api.py).
src/pupil_detectors/
• __init__.py, roi.py – Python modules forming the high-level API.
• detector_base.pyx/.pxd – Cython base bindings.
• detector_2d/ – second detector implementation with its own .pyx/.pxd and CMakeLists.
• coarse_pupil.pxd – Cython declarations for coarse pupil.
• cpp/ – raw C++ source code:
– shared/ – common geometry and math data types and utilities (Circle, Ellipse, Sphere, distance, intersect).
– singleeyefitter/ – image-processing pipeline, ellipse fitting, thinning, contour extraction.
• CMakeLists.txt – builds the native code.
Key Insights from README
• The main export is Detector2D, which under the hood uses OpenCV for I/O and Eigen for math.
• Users install via pip, import Detector2D, feed in grayscale images (numpy arrays), and receive ellipse parameters.
Main Components
A. Python Layer
– User Application: imports and calls Detector2D.
– pupil_detectors Python package: roi.py, __init__.py.
B. Cython Bridge Layer
– detector_base.pyx/pxd, detector_2d.pyx/pxd, c_types_wrapper.pxd: expose C++ classes/functions as Python objects.
C. Native C++ Layer
1. Shared Utilities:
• Geometry (Ellipse, Circle, Conic).
• Math (distance, intersect).
2. Coarse Detector: coarse_pupil functionality (declared in coarse_pupil.pxd).
3. Single-Eye Fitter: image processing (thinning, contour), solver, projection, ellipse evaluation.
D. External Dependencies
– Eigen: linear algebra for ellipse fitting.
– CMake: builds native code.
– pytest: test harness.
– Sphinx: docs generation.
E. Support Infrastructure
– CI/CD: GitHub workflows, pre-commit, flake8, mypy.
– Packaging: setup.py, MANIFEST.in, pyproject.toml.
Relationships and Data Flow
1. User Code → Python API (Detector2D.detect).
2. Python API calls Cython wrappers.
3. Cython wrappers call compiled C++ functions.
4. C++ code processes image data (via numpy buffer), runs detection pipelines, returns raw results.
5. Results propagate back through Cython to Python objects (dictionaries with ellipse data).
Architectural Patterns and Principles
– Layered architecture (Python API → Cython → C++).
– Modular native code: shared utilities vs. detector implementations.
– Clear separation between interface (Python/Cython) and implementation (C++).
– Single Responsibility: each C++ module focuses on one stage (geometry, contour extraction, solver).