# pupil-labs/pupil-detectors architecture

> Architecture diagram of the GitHub repository pupil-labs/pupil-detectors, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pupil-labs/pupil-detectors
- Repository: https://github.com/pupil-labs/pupil-detectors

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python Layer
    subgraph "Python Layer"
        UA["User Application"]:::python
        PD["Detector2D"]:::python
        ROI["roi.py"]:::python
    end

    %% Cython Bridge
    subgraph "Cython Bridge"
        DBP["detector_base.pyx"]:::cython
        DBH["detector_base.pxd"]:::cython
        CTW["c_types_wrapper.pxd"]:::cython
        D2PYX["detector_2d.pyx"]:::cython
        D2PDX["detector_2d.pxd"]:::cython
        D2INIT["__init__.py"]:::cython
    end

    %% C++ Shared Utilities
    subgraph "C++ Shared Utilities"
        subgraph "geometry"
            CIRCLE["Circle.h"]:::cpp
            CONIC["Conic.h"]:::cpp
            CONICOID["Conicoid.h"]:::cpp
            ELLIPSE["Ellipse.h"]:::cpp
            SPHERE["Sphere.h"]:::cpp
        end
        subgraph "math"
            DIST["distance.h"]:::cpp
            INTS["intersect.h"]:::cpp
        end
        subgraph "common"
            TYPES["types.h"]:::cpp
            CONSTS["constants.h"]:::cpp
            COLORS["colors.h"]:::cpp
        end
    end

    %% C++ Coarse Detector
    subgraph "C++ Coarse Detector"
        COARSEPXD["coarse_pupil.pxd"]:::cpp
        CMAKE_ROOT["CMakeLists.txt"]:::cpp
    end

    %% C++ Single-Eye Fitter
    subgraph "Single-Eye Fitter"
        DPE["DistancePointEllipse.h"]:::cpp
        EDA["EllipseDistanceApproxCalculator.h"]:::cpp
        EE2D["EllipseEvaluation2D.h"]:::cpp
        GHT["GuoHallThinner.h"]:::cpp
        IC["ImageContour.h"]:::cpp
        CVXCPP["cvx.cpp"]:::cpp
        CVXH["cvx.h"]:::cpp
        DUCPP["detectorUtils.cpp"]:::cpp
        DUH["detectorUtils.h"]:::cpp
        FUN["fun.h"]:::cpp
        MATHH["mathHelper.h"]:::cpp
        PROJ["projection.h"]:::cpp
        SOLVE["solve.h"]:::cpp
        UTCPP["utils.cpp"]:::cpp
        UTH["utils.h"]:::cpp
    end

    %% C++ 2D Detector Implementation
    subgraph "C++ 2D Detector Implementation"
        D2CMAKE["detector_2d/CMakeLists.txt"]:::cpp
        DETECT2D["detect_2d.hpp"]:::cpp
    end

    %% External Dependencies
    subgraph "External Dependencies"
        OPENCV["OpenCV"]:::ext
        EIGEN["Eigen"]:::ext
        CMAKE["CMake"]:::ext
    end

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        TESTAPI["tests/test_api.py"]:::infra
        PYTESTINI["pytest.ini"]:::infra
        TOXINI["tox.ini"]:::infra
    end

    %% Documentation
    subgraph "Documentation"
        DOCSINDEX["docs/index.rst"]:::infra
        DOCCONF["docs/conf.py"]:::infra
        README["README.rst"]:::infra
    end

    %% Packaging & CI
    subgraph "Packaging & CI"
        SETUPPY["setup.py"]:::infra
        SETUPCFG["setup.cfg"]:::infra
        PYPY["pyproject.toml"]:::infra
        MANIF["MANIFEST.in"]:::infra
        GITHUB[".github/workflows/main.yml"]:::infra
        PRECOM[".pre-commit-config.yaml"]:::infra
        FLAKE[".flake8"]:::infra
    end

    %% Data Flow
    UA -->|"imports"| PD
    PD -->|"uses"| ROI
    PD -->|"wraps"| DBP
    ROI --> DBP
    PD --> D2PYX
    D2PYX --> D2PDX
    D2PYX --> D2INIT
    DBP -->|"calls C++"| CIRCLE
    DBP --> DIST
    DBP --> INTS
    DBP --> COARSEPXD
    DBP --> CMAKE_ROOT
    D2PYX --> DETECT2D
    DETECT2D --> D2CMAKE
    DBP --> DPE
    DBP --> EE2D
    DBP --> GHT
    OPENCV --> PD
    EIGEN --> PD
    CMAKE --> CMAKE_ROOT
    CMAKE --> D2CMAKE
    TESTAPI --> PD
    TESTAPI --> D2PYX
    DOCSINDEX --> PD
    README --> PD
    SETUPPY --> PD
    GITHUB --> SETUPPY

    %% Click Events
    click PD "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/__init__.py"
    click ROI "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/roi.py"
    click DBP "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/detector_base.pyx"
    click DBH "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/detector_base.pxd"
    click CTW "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/c_types_wrapper.pxd"
    click D2PYX "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/detector_2d/detector_2d.pyx"
    click D2PDX "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/detector_2d/detector_2d.pxd"
    click D2INIT "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/detector_2d/__init__.py"
    click CIRCLE "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/shared/include/geometry/Circle.h"
    click CONIC "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/shared/include/geometry/Conic.h"
    click CONICOID "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/shared/include/geometry/Conicoid.h"
    click ELLIPSE "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/shared/include/geometry/Ellipse.h"
    click SPHERE "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/shared/include/geometry/Sphere.h"
    click DIST "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/shared/include/math/distance.h"
    click INTS "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/shared/include/math/intersect.h"
    click TYPES "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/shared/include/common/types.h"
    click CONSTS "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/shared/include/common/constants.h"
    click COLORS "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/shared/include/common/colors.h"
    click COARSEPXD "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/coarse_pupil.pxd"
    click CMAKE_ROOT "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/CMakeLists.txt"
    click DPE "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/DistancePointEllipse.h"
    click EDA "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/EllipseDistanceApproxCalculator.h"
    click EE2D "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/EllipseEvaluation2D.h"
    click GHT "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/ImageProcessing/GuoHallThinner.h"
    click IC "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/ImageProcessing/ImageContour.h"
    click CVXCPP "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/ImageProcessing/cvx.cpp"
    click CVXH "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/ImageProcessing/cvx.h"
    click DUCPP "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/detectorUtils.cpp"
    click DUH "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/detectorUtils.h"
    click FUN "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/fun.h"
    click MATHH "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/mathHelper.h"
    click PROJ "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/projection.h"
    click SOLVE "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/solve.h"
    click UTCPP "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/utils.cpp"
    click UTH "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/cpp/singleeyefitter/utils.h"
    click D2CMAKE "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/detector_2d/CMakeLists.txt"
    click DETECT2D "https://github.com/pupil-labs/pupil-detectors/blob/master/src/pupil_detectors/detector_2d/detect_2d.hpp"
    click TESTAPI "https://github.com/pupil-labs/pupil-detectors/blob/master/tests/test_api.py"
    click PYTESTINI "https://github.com/pupil-labs/pupil-detectors/blob/master/pytest.ini"
    click TOXINI "https://github.com/pupil-labs/pupil-detectors/blob/master/tox.ini"
    click DOCSINDEX "https://github.com/pupil-labs/pupil-detectors/blob/master/docs/index.rst"
    click DOCCONF "https://github.com/pupil-labs/pupil-detectors/blob/master/docs/conf.py"
    click README "https://github.com/pupil-labs/pupil-detectors/blob/master/README.rst"
    click SETUPPY "https://github.com/pupil-labs/pupil-detectors/blob/master/setup.py"
    click SETUPCFG "https://github.com/pupil-labs/pupil-detectors/blob/master/setup.cfg"
    click PYPY "https://github.com/pupil-labs/pupil-detectors/blob/master/pyproject.toml"
    click MANIF "https://github.com/pupil-labs/pupil-detectors/blob/master/MANIFEST.in"
    click GITHUB "https://github.com/pupil-labs/pupil-detectors/blob/master/.github/workflows/main.yml"
    click PRECOM "https://github.com/pupil-labs/pupil-detectors/blob/master/.pre-commit-config.yaml"
    click FLAKE "https://github.com/pupil-labs/pupil-detectors/blob/master/.flake8"

    %% Styles
    classDef python fill:#D6EFFF,stroke:#0288D1,stroke-width:2px
    classDef cython fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px
    classDef cpp fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
    classDef ext fill:#E0E0E0,stroke:#616161,stroke-width:2px
    classDef infra fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px
```
