EyeTrack2Saccade 👁

Table of Contents

1. 📚 What is EyeTrack2Saccade?
2. 🔧 How to install EyeTrack2Saccade?
3. 🚀 How to use EyeTrack2Saccade?
4. 📦 Dependencies
5. 📧 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

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:

Example:

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

Time X Y
0 554262330 92.60 648.54

💡 "At timestamp 554262330 the eyes are at coordinates (92.60, 648.54) (in px)."

Output

Output data format:

Example:

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!

If you don't yet have Git installed, you can download it from Git Official Website!

1. Clone the repository by running following command in your terminal:

   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:

   cd EyeTrack2Saccade

3. Create a virtual environment and activate it (Python Version 3.10 or higher):

   python3 -m venv venv
   source venv/bin/activate

4. Install the required packages by running the following command in your terminal:

   pip install -r requirements.txt

🚀 How to use EyeTrack2Saccade?

1. Via file path:
   • _Example .txt-file available in repository 'data/raw/eyetracker_freeviewing.txt'!_

from src.feature_extraction import Eye2SacExtractor

ffe = Eye2SacExtractor(data='../data/raw/eyetracker_freeviewing.txt')
esac = ffe.extract_features()

1. Via pandas DataFrame:
   • If you have left and right eye coordinates:

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:

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
• numpy
• pygaze analyser

📧 Contact

HUman BIosignal Intelligence Hub (HUBII)

• Website
• GitHub
• Hugging Face