This project allows you to leverage the output of Pupil Cloud's Face Mapper and map gaze on facial landmarks detected in the scene camera. It generates a new visualization with the detected facial landmarks overlaid on the video and gaze on top, and also generates a new CSV file with the mapped gaze on facial landmarks.
You should have Python 3.9 or higher.
Make sure you have tkinter module installed, this usually comes with most modern python distributions, but it might be different for you if for example, you installed python using homebrew.
Check if you have tkinter installed:
python -m tkinterIf you don't have it installed, install it:
brew install python-tk@3.11 # Change according to your python versionIn order to download the package, you can simply run the following command from the terminal:
git clone https://github.com/pupil-labs/gaze-on-facial-landmarks.gitOptional, but highly recommended: Create a virtual environment!
python3.11 -m venv venv
source venv/bin/activateGo to the folder directory and install the dependencies
cd your_directory/gaze-on-facial-landmarks
pip install -e . Run it and map gaze on facial landmarks!
pl-gaze-on-facial-landmarks Once you hit run, a pop-up window will appear prompting you to select the following:
- Face Mapper output folder: The enrichment folder downloaded from Pupil Cloud
- Raw data output folder: The "Timeseries Data + Scene Video" downloaded from Pupil Cloud
- AOI radius: The radius of the circle to be used as an AOI mask for the eyes and nose (default: 30)
- Ellipse size: The size of the ellipse to be used as an AOI mask for the mouth (default: 30)
- Gaze circle size: The size of the usual red circle that reflects the gaze points (default: 20)
If there are more subfolders in the Raw data output folder (i.e., more than one recordings), you will be prompted to select which subfolder you would like to select.
For any questions/bugs, reach out to our Discord server or send us an email to info@pupil-labs.com.