Metadata-Version: 2.4
Name: pyelink
Version: 1.0.1
Summary: Python wrapper for SR Research EyeLink eye trackers
Project-URL: Homepage, https://github.com/mh-salari/pyelink
Project-URL: Documentation, https://github.com/mh-salari/pyelink#readme
Project-URL: Repository, https://github.com/mh-salari/pyelink
Project-URL: Issues, https://github.com/mh-salari/pyelink/issues
Author-email: Mohammadhossein Salari <Mohammadhossein.salari@gmail.com>
License: MIT
License-File: LICENSE
Keywords: eyelink,eyetracking,neuroscience,psychopy,pygame,pyglet
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: fixation-target>=1.4.2
Requires-Dist: numpy<2.3.0,>=1.20.0
Requires-Dist: pyaudio>=0.2.14
Requires-Dist: pydantic<3.0,>=2.0
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: psychopy
Requires-Dist: pillow>=8.0.0; extra == 'psychopy'
Requires-Dist: psychopy>=2023.1.0; (python_version < '3.12') and extra == 'psychopy'
Provides-Extra: pygame
Requires-Dist: pygame>=2.6.1; extra == 'pygame'
Provides-Extra: pyglet
Requires-Dist: pyglet>=2.1.11; extra == 'pyglet'
Description-Content-Type: text/markdown

# PyeLink

Python wrapper for SR Research EyeLink eye trackers.

## Installation

**You must specify a backend when installing pyelink.** A simple `pip install pyelink` will NOT work because pyelink requires one of three mutually exclusive display backends (pygame, psychopy, or pyglet).

Choose ONE backend:

```bash
# For Pygame users
pip install pyelink[pygame]

# For PsychoPy users (Python < 3.12 only)
pip install pyelink[psychopy]

# For Pyglet users (pyglet 2.0+)
pip install pyelink[pyglet]
```

You'll also need to install pylink separately from SR Research:
```bash
pip install --index-url=https://pypi.sr-support.com sr-research-pylink
```

**Note:** This codebase has been tested on macOS ARM (Apple Silicon) only.

### ⚠️ Backend Compatibility Warning

**You CANNOT install both `psychopy` and `pyglet` backends together.**

**Why?** PsychoPy pins `pyglet==1.4.11` (from 2017) as a dependency, while the modern pyglet backend requires `pyglet>=2.0.0`. These versions are incompatible.

**Solution:** Choose ONE backend:
- **Pygame** (recommended): Works everywhere, no conflicts
- **PsychoPy**: Use if you need PsychoPy features, but cannot use pyglet 2.0+
- **Pyglet**: Use if you want modern pyglet (2.0+) but don't need PsychoPy

### Platform-Specific Notes

**macOS:**
- PyAudio requires PortAudio. Install it first:
```bash
brew install portaudio
```

## Quick Start

```python
import pyelink as el

# Configure tracker with backend
settings = el.Settings(
    backend='pygame',  # or 'psychopy', 'pyglet'
    fullscreen=True,
    screen_width=1920,
    screen_height=1080,
    filename="mydata",
    filepath="./data/",
)

# Tracker creates and owns the window
tracker = el.EyeLink(settings)

# Calibrate (optionally record samples during calibration)
tracker.calibrate(record_samples=True)

# Option A: Direct window access for custom drawing
tracker.window.fill((128, 128, 128))  # pygame example
# ... backend-specific drawing ...
tracker.flip()

# Option B: Helper methods for common patterns
tracker.show_message("Press SPACE to begin")
tracker.wait_for_key('space')

# Run your experiment
tracker.start_recording()
# ... show stimuli, collect data ...
tracker.stop_recording()

# Clean up (closes window and saves EDF automatically)
tracker.end_experiment()
```

## Development

For development with different backends:

```bash
# PsychoPy backend
uv pip uninstall pyelink && uv pip install -e ".[psychopy]" && uv pip install --index-url=https://pypi.sr-support.com sr-research-pylink

# Pygame backend
uv pip uninstall pyelink && uv pip install -e ".[pygame]" && uv pip install --index-url=https://pypi.sr-support.com sr-research-pylink

# Pyglet backend
uv pip uninstall pyelink && uv pip install -e ".[pyglet]" && uv pip install --index-url=https://pypi.sr-support.com sr-research-pylink
```

## Attribution

This package is based on code originally developed by:

- **Marcus Nyström** (Lund University Humanities Lab, Lund, Sweden)
  - Email: marcus.nystrom@humlab.lu.se

- **pylinkwrapper** by Nick DiQuattro
  - Repository: https://github.com/ndiquattro/pylinkwrapper
  - Core EyeLink functionality and wrapper architecture


## 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="https://github.com/mh-salari/zarafe/raw/main/resources/Funded_by_EU_Eyes4ICU.png" alt="Funded by EU Eyes4ICU" width="500">
</p>
