Eyeloop

EyeLoop is a Python 3-based eye-tracker tailored specifically to dynamic, closed-loop experiments on consumer-grade hardware.
Alternatives To Eyeloop
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Psychopy1,518
10 hours ago30May 24, 2022256gpl-3.0Python
For running psychology and neuroscience experiments
Awesome Neuroscience974
a year ago
A curated list of awesome neuroscience libraries, software and any content related to the domain.
Eyeloop383
a year ago6gpl-3.0Python
EyeLoop is a Python 3-based eye-tracker tailored specifically to dynamic, closed-loop experiments on consumer-grade hardware.
Neurokit.py253524 years ago6September 05, 201731mitPython
A Python Toolbox for Statistics and Neurophysiological Signal Processing (EEG, EDA, ECG, EMG...).
Opensesame223112 days ago61November 29, 202378gpl-3.0Python
Graphical experiment builder for the social sciences
Psycho.r11043 years ago17January 19, 202117otherR
An R package for experimental psychologists
Expyriment104
10 months ago6gpl-3.0Python
Platform-independent lightweight Python library for designing and conducting timing-critical behavioural and neuroimaging experiments
Awesome Tech Rss66
2 months ago1cc0-1.0Python
List of awesome RSS channels related to startup, science and technology.
Awesome Cogsci49
3 years ago12mit
An Awesome List of Cognitive Science Resources
Datasciencepsychneuro47
7 months ago7lgpl-3.0Jupyter Notebook
Repository for the Data Science for Psychology and Neuroscience course at CMU (Verstynen)
Alternatives To Eyeloop
Select To Compare


Alternative Project Comparisons
Readme

EyeLoop License: GPL v3 contributions welcome Build Status version lab beta

   

EyeLoop is a Python 3-based eye-tracker tailored specifically to dynamic, closed-loop experiments on consumer-grade hardware. Users are encouraged to contribute to EyeLoop's development.

Features

  • [x] High-speed > 1000 Hz on non-specialized hardware (no dedicated processing units necessary).
  • [x] Modular, readable, customizable.
  • [x] Open-source, and entirely Python 3.
  • [x] Works on any platform, easy installation.

Overview

How it works

EyeLoop consists of two functional domains: the engine and the optional modules. The engine performs the eye-tracking, whereas the modules perform optional tasks, such as:

  • Experiments
  • Data acquisition
  • Importing video sequences to the engine

The modules import or extract data from the engine, and are therefore called Importers and Extractors, respectively.

One of EyeLoop's most appealing features is its modularity: Experiments are built simply by combining modules with the core Engine. Thus, the Engine has one task only: to compute eye-tracking data based on an imported sequence, and offer the generated data for extraction.

How does the Engine work?
How does the Importer work?
How does the Extractor work?

Getting started

Installation

Install EyeLoop by cloning the repository:

git clone https://github.com/simonarvin/eyeloop.git

Dependencies: python -m pip install -r requirements.txt

Using pip: pip install .

You may want to use a Conda or Python virtual environment when installing eyeloop, to avoid mixing up with your system dependencies.

Using pip and a virtual environment:

python -m venv venv

source venv/bin/activate

(venv) pip install .

Alternatively:

  • numpy: python pip install numpy
  • opencv: python pip install opencv-python

To download full examples with footage, check out EyeLoop's playground repository:

git clone https://github.com/simonarvin/eyeloop_playground.git

Initiation

EyeLoop is initiated through the command-line utility eyeloop.

eyeloop

To access the video sequence, EyeLoop must be connected to an appropriate importer class module. Usually, the default opencv importer class (cv) is sufficient. For some machine vision cameras, however, a vimba-based importer (vimba) is neccessary.

eyeloop --importer cv/vimba

Click here for more information on importers.

To perform offline eye-tracking, we pass the video argument --video with the path of the video sequence:

eyeloop --video [file]/[folder]

EyeLoop can be used on a multitude of eye types, including rodents, human and non-human primates. Specifically, users can suit their eye-tracking session to any species using the --model argument.

eyeloop --model ellipsoid/circular

In general, the ellipsoid pupil model is best suited for rodents, whereas the circular model is best suited for primates.

To learn how to optimize EyeLoop for your video material, see EyeLoop Playground.

To see all command-line arguments, pass:

eyeloop --help

Designing your first experiment

In EyeLoop, experiments are built by stacking modules. By default, EyeLoop imports two base extractors, namely a FPS-counter and a data acquisition tool. To add custom extractors, e.g., for experimental purposes, use the argument tag --extractors:

eyeloop --extractors [file_path]/p (where p = file prompt)

Inside the extractor file, or a composite python file containing several extractors, define the list of extractors to be added:

extractors_add = [extractor1, extractor2, etc]

Extractors are instantiated by EyeLoop at start-up. Then, at every subsequent time-step, the extractor's fetch() function is called by the engine.

class Extractor:
    def __init__(self) -> None:
        ...
    def fetch(self, core) -> None:
        ...

fetch() gains access to all eye-tracking data in real-time via the core pointer.

Click here for more information on extractors.

Open-loop example

As an example, we'll here design a simple open-loop experiment where the brightness of a PC monitor is linked to the phase of the sine wave function. We create anew python-file, say "test_ex.py", and in it define the sine wave frequency and phase using the instantiator:

class Experiment:
    def __init__(self) -> None:
        self.frequency = ...
        self.phase = 0

Then, by using fetch(), we shift the phase of the sine wave function at every time-step, and use this to control the brightness of a cv-render.

    ...
    def fetch(self, engine) -> None:
        self.phase += self.frequency
        sine = numpy.sin(self.phase) * .5 + .5
        brightness = numpy.ones((height, width), dtype=float) * sine
        cv2.imshow("Experiment", brightness)

To add our test extractor to EyeLoop, we'll need to define an extractors_add array:

extractors_add = [Experiment()]

Finally, we test the experiment by running command:

eyeloop --extractors path/to/test_ex.py

See Examples for demo recordings and experimental designs.

For extensive test data, see EyeLoop Playground

Data

EyeLoop produces a json-datalog for each eye-tracking session. The datalog's first column is the timestamp. The next columns define the pupil (if tracked):

((center_x, center_y), radius1, radius2, angle)

The next columns define the corneal reflection (if tracked):

((center_x, center_y), radius1, radius2, angle)

The next columns contain any data produced by custom Extractor modules

Graphical user interface

The default graphical user interface in EyeLoop is minimum-gui.

EyeLoop is compatible with custom graphical user interfaces through its modular logic. Click here for instructions on how to build your own.

Running unit tests

Install testing requirements by running in a terminal:

pip install -r requirements_testing.txt

Then run tox: tox

Reports and results will be outputted to /tests/reports

Known issues

  • [ ] Respawning/freezing windows when running minimum-gui in Ubuntu.

References

If you use any of this code or data, please cite [Arvin et al. 2021] (article).


@ARTICLE{Arvin2021-tg,
  title    = "{EyeLoop}: An open-source system for high-speed, closed-loop
              eye-tracking",
  author   = "Arvin, Simon and Rasmussen, Rune and Yonehara, Keisuke",
  journal  = "Front. Cell. Neurosci.",
  volume   =  15,
  pages    = "494",
  year     =  2021
}

License

This project is licensed under the GNU General Public License v3.0. Note that the software is provided "as is", without warranty of any kind, express or implied.

Authors

Lead Developer: Simon Arvin, [email protected]

Researchers:

Corresponding Author: Keisuke Yonehera, [email protected]


         

    

Popular Neuroscience Projects
Popular Psychology Projects
Popular Science Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Python
Neuroscience
Psychology