EYE2SACC
[markdown]
[](https://example.com)
[](https://example.com)
EyeTrack2Saccade 👁
===
## Table of Contents
1. [📚 What is EyeTrack2Saccade?](#-what-is-eyetrack2saacade)
2. [🔧 How to install EyeTrack2Saccade?](#-how-to-install-saccade)
3. [🚀 How to use EyeTrack2Saccade?](#-how-to-use-eyetrack2saacade)
4. [📦 Dependencies](#-dependencies)
5. [📧 Contact](#-contact)
## 📚 What is EyeTrack2Saccade?
Pipeline to derive saccation features from eye-tracking records.
A saccade is a fast movement of the eye that abruptly changes the point of fixation.
### Input
| Required Features (#2 or #3) | Description |
|:——————————–|:————————————–|
| * Time | Timestamp of the eye-tracking record. |
| * X and Y eye coordinates | Coordinates of the eye gaze. |
| **or** | |
| * Left X and Y eye coordinates | Coordinates of the left eye gaze. |
| * Right X and Y eye coordinates | Coordinates of the right eye gaze. |
The system automatically scans a list of potential column names (case-insensitive) for the features and assigns the values accordingly (see in src/constants.py).
**Supported input data formats:**
[](https://pandas.pydata.org/docs/)
[](https://en.wikipedia.org/wiki/Text_file)
[](https://en.wikipedia.org/wiki/Comma-separated_values)
**Example:**
“`python
Time Left_X Left_Y Right_X Right_Y
0 554262330 92.60 648.54 79.27 648.36
“`
💡 “At timestamp “`554262330“` the left eye is at coordinates “`(92.60, 648.54)“` (in px) and the right eye is at coordinates “`(79.27, 648.36)“` (in px).”
_or_
“`python
Time X Y
0 554262330 92.60 648.54
“`
💡 “At timestamp “`554262330“` the eyes are at coordinates “`(92.60, 648.54)“` (in px).”
### Output
| Features (#7) | Description |
|:————–|:—————————————–|
| * Start Time | Timestamp of the start of the saccade. |
| * End Time | Timestamp of the end of the saccade. |
| * Duration | Duration of the saccade. |
| * Start X | X coordinate of the first saccade point. |
| * Start Y | Y coordinate of the first saccade point. |
| * End X | X coordinate of the last saccade point. |
| * End Y | Y coordinate of the last saccade point. |
**Output data format:**
[](https://pandas.pydata.org/docs/)
**Example:**
“`python
starttime endtime duration startx starty endx endy
0 560999822 561123849 124027 519.355000 635.295000 717.440000 892.385000
“`
💡 “The saccade starts at timestamp “`560999822“` and ends at timestamp “`561123849“`. The duration of the saccade is “`124027“` nanoseconds. The saccade starts at coordinates “`(519.355000, 635.295000)“` (in px) and ends at coordinates “`(717.440000, 892.385000)“` (in px).”
## 🔧 How to install EyeTrack2Saccade?
> If you don’t yet have Python installed, you can download it from [Python Official Website](https://www.python.org/downloads/)!
> If you don’t yet have Git installed, you can download it from [Git Official Website](https://git-scm.com/downloads)!
1. Clone the repository by running following command in your terminal:
“`bash
git clone https://github.com/hubii-world/EyeTrack2Saccade-01.git
“`
2. Navigate to the project root directory by running the following command in your terminal:
“`bash
cd EyeTrack2Saccade
“`
3. Create a virtual environment and activate it (Python Version 3.10 or higher):
“`bash
python3 -m venv venv
source venv/bin/activate
“`
4. Install the required packages by running the following command in your terminal:
“`bash
pip install -r requirements.txt
“`
## 🚀 How to use EyeTrack2Saccade?
1. **Via file path:**
* _Example .txt-file available in repository `’data/raw/eyetracker_freeviewing.txt’`!_
“`python
from src.feature_extraction import Eye2SacExtractor
ffe = Eye2SacExtractor(data=’../data/raw/eyetracker_freeviewing.txt’)
esac = ffe.extract_features()
“`
2. **Via pandas DataFrame:**
* _If you have left and right eye coordinates:_
“`python
import pandas as pd
from src.feature_extraction import Eye2SacExtractor
df = pd.DataFrame({
‘Time’: [554262330, 554264326 , 554266315],
‘Left_X’: [92.60, 185.06, 190.84],
‘Left_Y’: [648.54, 647.05, 637.12],
‘Right_X’: [79.27, 84.30, 84.77],
‘Right_Y’: [648.36, 648.73, 649.84]
})
ffe = Eye2SacExtractor(data=df)
esac = ffe.extract_features()
“`
* _If you only have x and y coordinates:_
“`python
import pandas as pd
from src.feature_extraction import Eye2SacExtractor
df = pd.DataFrame({
‘Time’: [554262330, 554264326 , 554266315],
‘X’: [85.935, 84.680, 87.805],
‘Y’: [648.450, 647.890, 643.480]
})
ffe = Eye2SacExtractor(data=df)
esac = ffe.extract_features()
“`
## 📦 Dependencies
* [pandas](https://pandas.pydata.org/)
* [numpy](https://numpy.org/)
* [pygaze analyser](https://github.com/esdalmaijer/PyGazeAnalyser)
## 📧 Contact
**HUman BIosignal Intelligence Hub (HUBII)**
* [Website](https://hubii.world/)
* [GitHub](https://github.com/hubii-world)
* [Hugging Face](https://huggingface.co/hubii-world)
[/markdown]