Titta is a toolbox for using eye trackers from Tobii Pro AB with MATLAB or GNU Octave, specifically offering integration with PsychToolbox. A Python version that integrates with PsychoPy is also available from https://github.com/marcus-nystrom/Titta. For a similar toolbox for SMI eye trackers, please see www.github.com/dcnieho/SMITE.

The current repository furthermore offers a C++ wrapper around the Tobii SDK, which is in turn used as a basis for the MEX file TittaMex providing MATLAB/Octave with connectivity to the Tobii eye trackers and TittaPy (pip install TittaPy) for providing Python 3 with the same. This C++ wrapper can be consumed by your own C++ projects as well, or be wrapped for other programming languages (pull requests welcome).

Please cite: Niehorster, D.C., Andersson, R. & Nyström, M. (2020). Titta: A toolbox for creating PsychToolbox and Psychopy experiments with Tobii eye trackers. Behavior Research Methods. doi: 10.3758/s13428-020-01358-8

For questions, bug reports or to check for updates, please visit www.github.com/dcnieho/Titta.

Titta is licensed under the Creative Commons Attribution 4.0 (CC BY 4.0) license. Note that the tobii_research*.h header files located in this repository at SDK_wrapper/deps/include/ carry a different license, please refer to the Tobii License Agreement for more information.

demos/readmeMinimal.m shows a minimal example of using the toolbox's functionality, and the demo_experiments folder contains various other examples. For documentation of the various data fields in the .mat file produced by the demos, see the Tobii SDK documentation. Example fixation detection and AOI analysis code is also included.

Ideally, make sure that the eye tracker is detected and works in the Tobii Eye Tracker Manager before trying to use it with Titta. Note also that some of the supported eye trackers require several setup steps before they are ready for use (e.g. do a display setup in Eye Tracker Manager). If these steps have not been performed, Titta will throw strange error messages.

To run the toolbox, the Tobii Pro SDK must be available. Titta for MATLAB and PsychToolbox includes the Tobii Pro SDK dynamic link libraries, so you do not have to install it separately. An up-to-date version of PsychToolbox is recommended.

Only the Titta.calibrate() and Titta.calibrateAdvanced() functions and optionally the TalkToProLab constructor use Psychtoolbox functionality, the rest of the toolbox can be used from MATLAB/Octave without having PsychToolbox installed.

Supported platforms

Currently the toolbox is only supported on Windows 10 (Windows 7 may continue to work but is not tested) and Linux. OSX support may appear if time and hardware availability permit. Given that OSX is not recommended for visual stimulus presentation, this however is low priority.

Only 64-bit MATLAB and GNU Octave are supported. 32-bit MATLAB support was previously available for Windows, but has been discontinued when the Tobii SDK dropped support for 32-bit platforms. The last version of Titta supporting 32-bit Matlab is available here.

Windows

Using the newest Psychtoolbox version is recommended for use with both Matlab and GNU Octave. For use with Matlab, at minimum PsychToolbox version 3.0.16 "Crowning achievement", released on 2020-05-10 is required. Titta has been tested on MATLAB version R2022b. To use Titta with GNU Octave at minimum Octave version 7.3 is required, which also entails at minimum PsychToolbox version 3.0.19, "Virtuality", released on 2023-02-17. The main Titta class, TittaMex and the readme demos have been tested to work on Octave. The breakOut demo does not work due to incomplete classdef support in Octave.

Linux

Using version Psychtoolbox 3.0.18.7 release "Experimental Taylor expansion" SP2, released on 2022-04-20 or later is recommended, but at minimum PsychToolbox version 3.0.16 "Crowning achievement", released on 2020-05-10 is required. Titta has been tested on MATLAB version R2022a. GNU Octave support has been tested with Octave versions 6.4 and 7.3. Titta for Linux is currently built on Ubuntu 22.04, which means it doesn not work out of the box on other Ubuntu releases. See the TittaMex readme for more information how to make it work on your platform.

Mac OSX

OSX is currently not supported, although the TittaMex file does build succesfully on OSX with the makeTittaMex.m script.

How to acquire

The recommended way to acquire Titta is to use the git tool to download it. Alternatively you can download the components separately and place them in the right locations. Here are instructions for these two routes:

1. Using Git
   1. install git from https://git-scm.org if you don't already have it. If you do not like using the command line/terminal, consider using a graphical git tool such as SmartGit, which is available free for non-commercial use.
   2. Download Titta and its dependencies in one go using the following command: git clone --recurse-submodules -j8 git://github.com/dcnieho/Titta.git.
   3. Should this not work due to your git version being too old, try executing the following commands:

      git clone git://github.com/dcnieho/Titta.git`
      cd Titta
      git submodule update --init --recursive

      If you have already cloned Titta but do not have the MatlabWebSocket submodule populated yet, issuing the git submodule update --init --recursive command will take care of that.

2. Manual download:
   1. First download Titta and place it, unzipped if necessary, in your preferred folder.
   2. Then download MatlabWebSocket (available from https://github.com/jebej/MatlabWebSocket). Download the currently tested version.
   3. Put the MatlabWebSocket directory inside Titta at the right location: <tittaRootDir>/talkToProLab/MatlabWebSocket).
3. When running on Windows, ensure you have the latest version of the Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017, 2019 and 2022 installed. This is the most likely cause of errors like "The specified module could not be found" when loading the TittaMex file.

Contents

The toolbox consists of multiple parts:

The Titta class

The Titta class is the main workhorse of this toolbox, providing a wrapper around the Tobii Pro SDK as well as the TittaMex class described below, and a convenient graphical user interface (rendered through PsychToolbox) for participant setup, calibration and validation. Only the Titta.calibrate() and Titta.calibrateAdvanced() participant setup and calibration interfaces require PsychToolbox.

The Titta, TittaMex and TittaPy classes in the SDK_wrapper directory

The Titta C++ class, the TittaMex MATLAB/Octave wrapper and the TittaPy Python wrapper are alternatives to the Tobii Pro MATLAB and Python SDKs for handling data streams and calibration, and can be used without making use of the Titta interface. The C++ code can be compiled and used as a static library without Matlab/Octave or Python. It is used by both the MATLAB and Python versions of Titta under the hood (Titta users can access it directly through the Titta.buffer property).

Besides providing access to the same tracker functionality as the Tobii Pro MATLAB SDK, it has two main features: (1) more complete and granular access to the data streams: (a): support for both consuming (destructive) and peeking (non-destructive) data streams; (b): support for only accessing or clearing specific parts of the tracker's data streams; and (c) data provided as structs-of-arrays instead of arrays-of-structs which makes data access significantly simpler and is much more memory efficient. The second main feature is (2) asynchronous calibration methods, allowing to issue non-blocking method calls for all stages of the calibration process, such that the interface can remain responsive. It furthermore offers GNU Octave support, which the MATLAB SDK has dropped since version 1.10, and provides eye openness data alongside data in the gaze stream instead of in a separate stream that the user then has to link up later themselves. Finally, other functions implemented in TittaMex provide return values that are a bit friendlier to use in MATLAB/Octave, in the author's opinion (e.g. doubles which are MATLAB's native data type instead of singles) and no use of MATLAB classes to just hold plain data.

On the Python side, besides the above benefits, use of the Titta C++ wrapper in TittaPy prevents issues where data is lost with the Tobii Python SDK's callback-style interface if the user does not sleep or yield often enough in their code, and also provides data from the various streams as a dict-of-lists instead of a list-of-dicts, which in the author's opinion is easier to use, and is straightforwardly transformed to a pandas.DataFrame, or saved to an HDF5 file.

The TalkToProLab class

The TalkToProLab class provides an implementation of Tobii Pro Lab's External Presenter interface, allowing experiments to be created and run from MATLAB/Octave with PsychToolbox or other presentation methods, while recording, project management, recording playback/visualization and analysis can be performed in Tobii Pro Lab.

The TalkToProLab class must be able to communicate with the External Presenter interface of Pro Lab for it to operate. As such, to use the TalkToProLab class, do the following: 1) Open an External Presenter project in Tobii Pro Lab, make sure its name matches what you provide to the TalkToProLab constructor. 2) Navigate to the 'record'-tab in Pro Lab 3) Make sure that the External presenter button is red and says 'not connected' 4) Run this script

Usage

As demonstrated in the demo scripts, the toolbox is configured through the following interface:

1. Retrieve (default) settings for eye tracker of interest: settings = Titta.getDefaults('tracker model name'); Supported eye trackers and their corresponding model names in the Tobii Pro SDK/Titta are:

   Eye tracker	Model name
   Tobii Pro Spectrum	Tobii Pro Spectrum
   Tobii Pro Fusion	Tobii Pro Fusion
   Tobii Pro TX300	Tobii TX300
   Tobii Pro T60 XL	Tobii T60 XL
   Tobii Pro Spark	Tobii Pro Spark
   Tobii Pro Nano	Tobii Pro Nano
   Tobii Pro X3-120	Tobii Pro X3-120 or Tobii Pro X3-120 EPU
   Tobii Pro X2-60	X2-60_Compact
   Tobii Pro X2-30	X2-30_Compact
   Tobii Pro X60	Tobii X60
   Tobii Pro X120	Tobii X120
   Tobii Pro T60	Tobii T60
   Tobii Pro T120	Tobii T120
   Tobii 4C*	IS4_Large_Peripheral

   Note that the VR eye trackers are not supported by Titta.

   ^*Note that a Pro upgrade license key is required to be able to use the Tobii 4C for research purposes, and for it to function with Titta. Unfortunately, the Pro upgrade license key is no longer sold by Tobii Pro. If you try to use a 4C without upgrade key with Titta, you will not receive data streams, and some calls, such as calibrate(), will yield error 201: TOBII_RESEARCH_STATUS_SE_INSUFFICIENT_LICENSE.

2. Change settings from their defaults if wanted (see supported options section below)

3. Create a Titta instance using this settings struct: EThndl = Titta(settings);

4. Interact with the eye tracker using the below API.

5. When calling Titta.calibrate(), a participant setup and calibration and validation interface is shown. For each screen, several keyboard hotkeys are available to activate certain functionality. By default, the hotkey for each button is printed in the button's label. It can be configured to different keys with the settings.UI.button options listed below. In addition, a few global hotkeys are available. These are documented below in the API documentation of the Titta.calibrate() method. A more advanced participant setup, calibration and validation interface intended especially to enable work with participants who are unable to follow instructions such as infants and non-human primates is provided by the Titta.calibrateAdvanced() function. The validation screen of both interfaces lists the data quality of the gaze signal recorded during validation, see below for a description of the reported data quality metrics.

6. Example analysis scripts for the recorded data (fixation classification and AOI analysis) are also provided.

Validation screen

The validation screens of both Titta.calibrate() and Titta.calibrateAdvanced() report several data quality metrics for the gaze data recorded during validation. These metrics are also converted to text by Titta.getValidationQualityMessage() and this text is stored as a timestamped message in the Titta message stream (see Titta.getMessages()) as part of the validation procedure. This message as well as the calibration data from which it is generated is stored to file by most of the data saving functions in Titta (see details in the documentation of each function, it depends on the format's capabilities). See this script for an example of extracting the data quality metrics of a validation from the .mat files stored by Titta.saveData().

For validation, by default, 0.5 s of gaze data is collected per validation point (see settings.val.collectDuration). The metrics calculated for the data of each validation point are decribed below. The metrics are calculated in the private function getDataQuality() inside Titta.m separately for the left and right eye (if both are recorded).

API

Titta class

Help on each of the below listed static methods, methods and properties can be had inside MATLAB by typing on the commands line help Titta.<function name>, e.g. help Titta.calibrate. Help on the constructor is had with help Titta.Titta.

Static methods

The below method can be called on a Titta instance or on the Titta class directly.

Construction

An instance of Titta is constructed by calling Titta() with either the name of a specific supported eye tracker model (in which case default settings for this model will be used) or with a settings struct retrieved from Titta.getDefaults(), possibly with changed settings (passing the settings struct unchanged is equivalent to using the eye tracker model name as input argument).

Methods

The following method calls are available on a Titta instance:

Properties

The following read-only properties are available for a Titta instance:

The following settable properties are available for a Titta instance:

Supported options

Which of the below options are available depends on the eye tracker model. The getDefaults() and getOptions() method calls return the appropriate set of options for the indicated eye tracker.

Text options

Texts take all or some of the below options:

Button options

Each button takes the below options:

The fields string, fillColor, edgeColor and textColor can be single entries, 2-element cell array or 3-element cell arrays. This is used to specify different looks for the button when in inactive state, hovered state, and activated state. If a single text or color is provided, this text/look applies to all three button states. If two are provided, the first text/color applies to both the inactive and hovered button states and the second to the activated state. If three are provided, they apply to the inactive, hovered and activated states, respectively. The string, fillColor, edgeColor and textColor can have these properties set independently from each other (you could thus provide different strings for the three states, while keeping colors constant over them).

Titta, TittaMex, TittaPy classes

The below documents the available functions and properties on a Titta SDK wrapper class. The functionality below is exposed under the same names in TittaMex. The same functionality is also available from a TittaPy instance, but in that case all function and property names as well as stream names use snake_case names instead of camelCase. Furthermore, static functions in the Titta class are found at the module level in TittaPy.

Static methods

Construction and initialization

An instance of Titta/TittaMex/TittaPy is constructed by calling Titta(), TittaMex() or TittaPy(). Before it becomes fully functional, its init() method should be called to provide it with the address of an eye tracker to connect to. A list of connected eye trackers is provided by calling the static function Titta.findAllEyeTrackers().

Methods

The following method calls are available on a Titta instance:

Properties

The following read-only properties are available for a Titta instance:

The following settable properties are available for a Titta instance:

TalkToProLab class

Static methods

The below method can be called on a TalkToProLab instance or on the TalkToProLab class directly.

Construction

An instance of TalkToProLab is constructed by calling TalkToProLab() and providing the constructor with the name of the External Presenter project that should be opened in Pro Lab. One optional additional constructor arguments can be provided:

• IPorFQDN: this is to indicate the IP or FQDN where the Pro Lab instance can be contacted. Defaults to 'localhost' for a one-computer setup. If you want to connect to Pro Lab on another computer, specify that computer's IP as this parameter.

When connected to Pro Lab on a remote computer, timestamps provided to sendStimulusEvent and sendCustomEvent will be automatically converted from the local computer's clock to the Pro Lab computer's clock. This conversation requires the clocks of the two computers to be synced, which will be done automatically whenever needed (automatically determined by the sync code). Depending on network performance, such a sync will take about 60 ms or more. Be aware of these possible slowdowns when calling sendStimulusEvent and sendCustomEvent.

Methods

The following method calls are available on a TalkToProLab instance

Properties

The following read-only properties are available for a TalkToProLab instance: