Metadata-Version: 2.4
Name: syelink
Version: 1.2.4
Summary: Parse EyeLink eye tracker data from ASC files
Project-URL: Homepage, https://github.com/mh-salari/syelink
Project-URL: Repository, https://github.com/mh-salari/syelink
Author: mh-salari
License: MIT
Keywords: asc,calibration,eye-tracker,eye-tracking,eyelink,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: adjusttext>=1.3.0
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: numpy>=1.20.0
Requires-Dist: pillow>=12.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# syelink

[![PyPI version](https://img.shields.io/pypi/v/syelink)](https://pypi.org/project/syelink/)
[![Downloads](https://static.pepy.tech/badge/syelink)](https://pepy.tech/project/syelink)
[![License](https://img.shields.io/pypi/l/syelink)](https://github.com/mh-salari/syelink/blob/main/LICENSE)
[![Documentation](https://readthedocs.org/projects/syelink/badge/?version=latest)](https://syelink.readthedocs.io/)
[![DOI](https://img.shields.io/badge/DOI-10.1145%2F3797246.3805844-blue)](https://doi.org/10.1145/3797246.3805844)

Parse EyeLink eye tracker data from ASC files.
For full documentation, see [syelink.readthedocs.io](https://syelink.readthedocs.io/).

## Features

- Parse EyeLink ASC files into structured JSON
- Extract calibration, validation, recording, and gaze sample data
- Export gaze samples to CSV with optional raw pupil/CR data
- Visualize calibration and validation results
- Command-line interface for common tasks
- Support for binocular and monocular (left/right only) recordings

## Installation

```bash
uv pip install syelink
```

Or install from source:

```bash
git clone https://github.com/mh-salari/syelink.git
cd syelink
uv pip install -e .
```

## Quick Start

### Convert an ASC file to JSON, text files, and CSV

```bash
uv run syelink convert data.asc
```

This creates:
- `data.json` - All session data (calibration, validation, recordings, gaze samples)
- `data_samples.csv` - Gaze samples with timestamps, positions, pupil sizes, and optional raw data
- Human-readable text files: `recordings.txt`, `calibrations.txt`, `validations.txt`, `metadata.txt`

To export only specific formats:

```bash
uv run syelink convert data.asc --json      # JSON only
uv run syelink convert data.asc --text      # Text files only
uv run syelink convert data.asc --samples   # CSV samples only
```

### View session information

```bash
uv run syelink info data.json
```

Shows calibration/validation count, display info, and gaze sample statistics.

### Export gaze samples to CSV

```bash
uv run syelink export-samples data.asc -o samples.csv
```

### Generate validation plot

```bash
uv run syelink plot-validation data.json -i 0 -o validation.png
```

### Generate calibration plot

```bash
uv run syelink plot-calibration data.json -i 0 -o calibration.png
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `syelink convert <asc_file>` | Convert ASC file to JSON, text files, and/or CSV samples |
| `syelink info <data_file>` | Show session information (accepts ASC or JSON) |
| `syelink export-samples <data_file>` | Export gaze samples to CSV |
| `syelink plot-validation <json_file>` | Plot validation data |
| `syelink plot-calibration <json_file>` | Plot calibration data |

### Options

**convert**
- `-o, --output` - Output directory (default: same directory as ASC file)
- `--json` - Export JSON file only
- `--text` - Export text files only
- `--samples` - Export gaze samples CSV only
- Without flags: exports all formats (JSON + text + CSV)

**export-samples**
- `-o, --output` - Output CSV file path (default: `<filename>_samples.csv`)

**info**
- Shows calibration/validation counts, display info, and gaze sample statistics

**plot-validation / plot-calibration**
- `-i, --index` - Calibration/validation index (default: 0)
- `-o, --output` - Output image path
- `--show` - Show plot interactively
- `--target-image` - Custom target image (validation only)

## Python API

```python
from syelink import parse_asc_file, SessionData

# Parse ASC file
session = parse_asc_file("data.asc")

# Access data
print(f"Display: {session.display_coords.width}x{session.display_coords.height}")
print(f"Calibrations: {len(session.calibrations)}")
print(f"Validations: {len(session.validations)}")
print(f"Gaze samples: {len(session.gaze_samples):,}")

# Save to JSON
session.save_json("data.json")

# Save gaze samples to CSV
session.save_samples_csv("gaze_samples.csv")

# Load from JSON
session = SessionData.load_json("data.json")

# Access validation errors
for val in session.validations:
    if val.summary_left:
        print(f"Left eye avg error: {val.summary_left.error_avg_deg:.2f}°")

# Access gaze samples
for sample in session.gaze_samples[:10]:  # First 10 samples
    print(f"Time: {sample.timestamp}, Left: ({sample.left_gaze_x}, {sample.left_gaze_y})")
```

## Data Structure

The parsed data includes:

- **Display coordinates** - Screen resolution and boundaries
- **Calibrations** - Calibration points, polynomial coefficients, gains, results
- **Validations** - Target positions, gaze offsets, error metrics
- **Recordings** - Start/end timestamps for recording blocks
- **Gaze samples** - Timestamps, gaze positions (x, y), pupil sizes, and optional raw pupil/CR data
  - Supports binocular (both eyes) and monocular (left or right only) recordings
  - CSV export includes 32 columns: metadata, gaze data, and raw camera measurements

## Examples

Check the `examples/` directory for complete usage examples:

- `basic_usage.py` - Parse ASC files, save to JSON/CSV/text, and load data
- `plot_example.py` - Generate calibration and validation plots

Run examples with:

```bash
cd examples
uv run python basic_usage.py data/both_eyes/both_eyes.asc
uv run python plot_example.py data/both_eyes/parsed_output.json
```

Example data includes:
- `both_eyes/` - Binocular tracking data
- `left_eye/` - Left eye only tracking data
- `right_eye/` - Right eye only tracking data

## Citation

**Cite as:**
```
Salari, M., Nyström, M., Niehorster, D. C., & Bednarik, R. (2026).
PyeLink and SyeLink: Open-source Python tools for low-level EyeLink experiment control and data parsing.
In Proceedings of the 2026 Eye Tracking Research & Applications (ETRA 2026) Late-Breaking Work. ACM.
DOI: 10.1145/3797246.3805844
```

## License

MIT

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