Tobii and OpenSesame

Last modified by Iris Spruit on 2023/10/06 10:29

Introduction

OpenSesame uses the PyGaze library to enable eye tracking. With this library eye tracking is possible with many eye trackers, including Tobii. PyGaze uses the Tobii Pro software development kit (SDK) to communicate with the Tobii eye tracker. The PyGaze library is automatically installed with the OpenSesame Windows version. However, see the instructions below for setting up/installing OpenSesame for working specifically with a Tobii eye tracker.

Setting up OpenSesame for Tobii

The Tobii research library (part of the Tobii Pro SDK) is unfortunately not available for Python 3.7, which is what the current OpenSesame distribution comes with (OpenSesame 3.3). As a result, you cannot use Tobii eye-trackers with the downloadable version of OpenSesame 3.3. To get around this, OpenSesame can be run in its own Python 3.8 environment, which is supported by Tobii. Running OpenSesame inside an environment can be done using Conda.

Conda is a package manager included in Anaconda and Miniconda. Please make sure one of the two is installed before attempting to use Conda. It is preferable to install Anaconda as it provides a handy graphical user interface and more features, although those are not required for the steps described here. Note that both Miniconda and Anaconda can be installed for the current user without admin privileges by choosing “just me” at the “install for” prompt.

If you want to use Tobii and OpenSesame on an FSW PC, you can request support via labsupport@fsw.leidenuniv.nl.

Running OpenSesame Through Conda

To run OpenSesame through Conda for the purpose of using Tobii, a new Python 3.8 environment must be created and configured. Subsequently, the OpenSesame code and all its dependencies must be downloaded and installed inside that environment.

Once the environment has been set up, the OpenSesame installed inside of it can be launched by first activating that environment, then running the opensesame command.

Launching the installed OpenSesame by running it from a desktop shortcut or from the start menu, or by double-clicking an osexp file, will not launch the OpenSesame version inside of the new environment. Instead, the OpenSesame version installed on the PC will launch in its own bundled Python runtime.

The full process of creating a new environment, activating it and launching OpenSesame is described below.

Creating the OpenSesame Python 3.8 environment.

Once either Anaconda (preferred) or Miniconda has been installed, launch the “Anaconda Prompt” by clicking the Windows Start Menu icon, then typing “anaconda prompt”. Once the “Anaconda Prompt” app option has appeared, launch it by clicking it.

Now, create a new Python 3.8 environment for OpenSesame and activate it (info):

conda create -n opensesame-py38 python=3.8
conda activate opensesame-py38

Next, add the relevant channels (cogsci) and (conda-forge) and install all relevant packages. Make sure that pyqode.core and pyqode.python are >= 3.2 from the cogsci channel, and not the older versions from the conda-forge channel. Note: pyqode extensions and pyqtewebengine extension were added.

conda config --add channels cogsci --add channels conda-forge
conda install python-opensesame opensesame-extension-osweb opensesame-plugin-psychopy psychopy rapunzel python-pygaze
conda install -c cogsci pyqode.core pyqode.python pyqode.qt
conda install -c conda-forge pyqtwebengine

Some packages are not available through Conda. Use pip install for these.

pip install soundfile pygame yolk3k opensesame-extension-osf python-qtpip http://files.cogsci.nl/expyriment-0.10.0+opensesame2-py3-none-any.whl
pip install tobii_research

The environment has now been created, activated, configured and populated. You can now run OpenSesame (while the new environment is still active) by running:

opensesame

Launching OpenSesame in the Python 3.8 Environment

To launch OpenSesame, open the “Anaconda Prompt” by clicking the Windows Start Menu icon, then typing “anaconda prompt”. Once the “Anaconda Prompt” app option has appeared, launch it by clicking it.

Now, activate the correct environment and launch OpenSesame in it by running the following commands:

conda activate opensesame-py38
opensesame

Batch Script Automation

To make the process described above easier, a collection of batch scripts has been created. To use the batch scripts to setup the OpenSesame environment and subsequently launch it that environment, follow the steps below:

  1. Have Conda:
    • Make sure Anaconda or Miniconda is installed. If it is not and you are using an FSW lab PC, request an installation via labsupport@fsw.leidenuniv.nl. If you are using your own office or home PC, you can download and install Anaconda (preferred) or Miniconda yourself.
  2. Download batch files:
    • Download a zip file containing the batch files here. Make sure to unzip the zip file before running the .bat files inside of it.
  3. Create the environment
    • Run create_env.bat to create and configure the environment. This will create a Conda environment named opensesame-py38, which runs Python 3.8. It will also download OpenSesame and all its dependencies to it, including the Tobii research code.
  4. Run OpenSesame
    • Run run_OpenSesame_in_env.bat to launch OpenSesame in the new environment (opensesame-py38). Only this step needs to be done when subsequently launching OpenSesame.

The file find_conda.bat is used by the other two bat files to find the currently installed Conda. The batch scripts are maintained here on GitHub.

Creating the environment may take quite long (possibly 15+ minutes); please be patient!

Tip: because OpenSesame takes in the osexp filename as the first argument, you can modify run_OpenSesame_in_env.bat to open OpenSesame in a given environment, then immediately open the specified osexp file.

Troubleshooting

  • For many issues the following steps are good to try first:
    • Close OpenSesame
    • Open an Anaconda Prompt make and make sure the anaconda env
    • conda deactivate opensesame-py38
    • Check if the env is still present in C:\ProgramData\anaconda3\envs\ 
  • OpenSesame does not launch from the bat file.
    • Try to launch it manually from the Anaconda Prompt
  • Error "module soundfile not found"
    • Open an Anaconda prompt, deactivate the environment
    • conda deactivate opensesame-py38
    • Remove the environment
    • conda env remove -n opensesame-py38
    • Open explorer, go to C:\ProgramData\anaconda3\envs\  and see if there is still a folder called opensesame-py38, if so, delete it
    • Finally reinstall the environment and OpenSesame following the steps above.

Configuring PyGaze for Tobii

A sample OpenSesame task with PyGaze and Tobii can be downloaded here.

For more general information about using the PyGaze library in OpenSesame, check the PyGaze and OpenSesame page and the official OpenSesame documentation. Below, some information when working specifically with Tobii are given.

Serial number

Before you can use a Tobii eye-tracker with PyGaze, which is what OpenSesame uses to interface with eye-trackers, you need to register the eye-tracker's serial number. This can be done by adding a Python Inline script item at the start of the experiment sequence, and then adding the following code to it:

"""
When using Tobii eye-trackers, add a Python inline script to the
top of the experiment with the code below. Change the serial number
to the one matching your device. Use the Tobii Eye Tracker Manager
to find the serial number:
  https://www.tobiipro.com/product-listing/eye-tracker-manager/
"""


from pygaze import settings
settings.TRACKERSERIALNUMBER = "X3120-XXXXXXXXXXXXX"

Make sure to change the serial number to one matching the eye-tracker you have and want to use. You can find the serial number in the Eye Tracker Manager when the eye-tracker is connected to the PC and turned on. 

Tobii-SerialNumber.PNG

Initialize PyGaze

Make sure to configure the pygaze_init object so that it communicates with a Tobii eye-tracker (Select tracker type: Tobii). Also, it is highly advised to check the Calibrate tracker option, so that the eye-tracker is calibrated at the start of the task.

FAQ

TopicQuestionAnswer
OpenSesame crashes with AttributeError: 'TobiiProTracker' object has no attribute 't0' Somehow, the eye tracker is often not found immediately. This is usually resolved by just running the task again. See discussion and solution here. The find_all_eyetrackers() function needs to be adjusted to solve the issue.
Tags:
   
solo
XWiki 14.10.13
contact@xwiki.com