PyEtSimul Documentation

PyEtSimul is an open-source Python framework for simulating video-based eye trackers by generating synthetic eye features through geometric modeling. The framework allows flexible positioning of eyes, cameras, and light sources in 3D space, with controlled variation of eye anatomical features and camera properties.

PyEtSimul’s core code is based on et_simul [1], but extends it by generalizing corneal modeling to conic surfaces rather than the common sphere, supporting non-circular pupil shapes, size-dependent pupil decentration, eyelid occlusion, and camera lens distortion. It also supports systematic data generation and principled comparison of gaze estimation algorithms across calibrated and uncalibrated settings.

Contents

• Getting Started
  • Installation
  • Basic Usage
  • Key Concepts
  • Examples

Theory

• Coordinate Systems
  • Overview
  • World Coordinate System
  • Eye Coordinate System
  • Camera Coordinate System
  • Image Coordinate System
  • Transformation Pipeline
• Eye Model
  • Eye Rotation
  • Cornea
  • Pupil
  • Eyelid Occlusion
• Optical Calculations
  • Corneal Reflection
  • Corneal Refraction (Pupil Imaging)
• Camera and Light Sources
  • Camera Model
  • Light Sources
• Gaze Estimation Models
  • Polynomial Models
  • Stampe (1993) Biquadratic Model
  • Homography Normalization
• Evaluation Workflow
  • Experimental Setup
  • Parameter Variations
  • Gaze Mapping Algorithms
  • Evaluation Process
• Default Parameters
  • Eye Anatomy
  • Spherical Cornea
  • Pupil
  • Pupil Decentration
  • Eyelid
  • Camera

Guides

• Template for Custom Gaze Estimation Models
  • Core Architecture
  • Block 1: Algorithm State
  • Blocks 2, 3, and 4: The Gaze Model Class and its Logic
• Creating Custom Parameter Variations
  • Quick Start: Custom Variation
  • Real Example: Corneal K Parameter
  • Run Your Custom Variation

API Reference

• API Reference
  • Types
  • Core
  • Geometry
  • Optics
  • Gaze Mapping
  • Evaluation
  • Visualization
  • Simulation

---

Note

The theoretical content in this documentation is derived from the PyEtSimul paper [2] by the same authors. If you use PyEtSimul in your research, please cite [2].

[1] Bohme, M., Dorr, M., Graw, M., Martinetz, T., & Barth, E. (2008). A software framework for simulating eye trackers. In Proceedings of the 2008 Symposium on Eye Tracking Research & Applications (ETRA ‘08), pp. 251-258. ACM. DOI: 10.1145/1344471.1344529

[2] Salari, M., Niehorster, D. C., Hansen, D. W., & Bednarik, R. (2026). PyEtSimul: An Open-Source Python Framework for Eye-Tracking Simulation. Proceedings of the ACM on Human-Computer Interaction (PACMHCI), ETRA 2026. ACM. DOI: 10.1145/3806023

Note

This project has received funding from the European Union’s Horizon Europe research and innovation funding program under grant agreement No 101072410, Eyes4ICU project.

Author: Mohammadhossein Salari