Titta is a toolbox for using eye trackers from Tobii Pro AB with Python, specifically offering integration with PsychoPy. A Matlab version that integrates with PsychToolbox is also available from https://github.com/dcnieho/Titta. For a similar toolbox for SMI eye trackers, please see www.github.com/marcus-nystrom/SMITE.
Titta is an alternative to using the eye tracking functionality already available in PsychoPy (through ioHub). Instead of the general interface ioHub provides to many eye trackers, Titta is specifically designed to offer full access to the functionality of Tobii eye trackers, has an intuitive participant setup and calibration interface, and includes scripts for analysis of eye-tracking data.
For questions, bug reports or to check for updates, please visit https://github.com/marcus-nystrom/Titta.
To minimize the risk of missing samples, the current repository uses TittaPy (pip install TittaPy
), a C++ wrapper around the Tobii SDK, to pull samples made available from the eye tracker.
If you know what you are doing, install Titta using: pip install titta
or python -m pip install titta
.
If you use a standalone PsychoPy installation, do the following steps:
- Go to
C:\Program Files\PsychoPy
(or wherever you installed PsychoPy) and open a command prompt in the same folder as where you findpython.exe
(should be the main PsychoPy install folder). So the command prompt you have should start with something likeC:\Program Files\PsychoPy>
- Here you can then pip-install titta, by issuing a command like
python -m pip install titta --upgrade
.
Then run read_me.py
from the 'demos' folder (first change the monitor settings and the eye tracker name in read_me.py
). Reading through read_me.py
should provide a good starting point for most users of Titta.
- Open read_read_me_TalkToProLab.py in PsychoPy.
- Download Tobii Pro Lab.
- Open a new External Presenter Project in Pro Lab. The Project name must be the same as the project name in read_read_me_TalkToProLab.py.
- Navigate to the 'record'-tab in Pro Lab, and make sure that the External presenter button is red and says 'not connected'.
- In PsychoPy, run read_read_me_TalkToProLab.py (first change the monitor settings and the eye tracker name).
Tested on Windows 10 using PsychoPy 2022.1.3 using Python 3.8. Ideally, make sure that the eye tracker is detected and works in the Tobii Eye Tracker Manager before trying to use it with Titta.
The toolbox consists of two main parts:
The Titta module (which utilizes the Tobii module) is the main workhorse of this toolbox, providing a wrapper around the Tobii Pro SDK, and a convenient graphical user interface (rendered through PsychoPy) for participant setup, calibration and validation. Only the Titta.calibrate()
participant setup and calibration interface requires PsychoPy.
These modules connect to Tobii via TittaPy
. Although TittaPy
is located in a separate repository, documentation for it is included here since it is powering the Titta
and Tobii
modules here.
The TalkToProLab
class provides an implementation of Tobii Pro Lab's External Presenter interface, allowing experiments to be created and run from Python with PsychoPy or other presentation methods, while recording, project management, recording playback/visualization and analysis can be performed in Tobii Pro Lab.
As demonstrated in the demo scripts, the toolbox is configured through the following interface:
-
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 Nano Tobii Pro Nano
Tobii Pro Spark Tobii Pro Spark
Tobii Pro X3-120 Tobii Pro X3-120
orTobii 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 (Upgrade Key required) IS4_Large_Peripheral
Eye trackers marked in bold font have been tested. Note that the VR eye trackers are not supported by Titta. Also note that the Tobii 4C cannot be used for research purposes without buying the Pro Upgrade Key, and is compatible with Titta only after this purchase. Unfortunately, the Pro Upgrade Key is no longer sold by Tobii.
-
Change settings from their defaults if wanted.
-
Create a Titta instance using this settings struct:
tracker = Titta(settings);
-
Interact with the eye tracker using the Titta API.
-
When calling
Titta.calibrate()
, a participant setup and calibration 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.
The below method can be called on the Titta module directly.
Call | Inputs | Outputs | Description |
---|---|---|---|
get_defaults() |
|
|
Gets all supported settings with defaulted values for the indicated eyeTracker, can be modified and used for constructing an instance of Titta. See the supported options section below. |
An instance of Titta for interaction with the eye tracker (a Titta.MyTobii
instance) is constructed by calling the module-level constructor Titta.Connect()
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.get_defaults()
, possibly with changed settings (passing the settings object unchanged is equivalent to using the eye tracker model name as input argument).
The get_defaults()
method call returns the appropriate set of options for the indicated eye tracker.
Option name | Explanation |
---|---|
settings.SAMPLING_RATE |
Sampling frequency |
The following methods are available for an instance of Tobii.MyTobii
(as created by calling Titta.Connect
).
Property | Description |
---|---|
buffer |
Initialized by call to init() . Returns handle to a TittaPy instance for interaction with the eye tracker's data streams. This handle can furthermore be used for directly interacting with the eye tracker through the Tobii Pro SDK, but note that this is at your own risk. Titta should have minimal assumptions about eye-tracker state, but I cannot guarantee that direct interaction with the eye tracker does not interfere with later use of Titta in the same session. |
The following methods are available for an instance of Tobii.MyTobii
(as created by calling Titta.Connect
).
Call | Inputs | Outputs | Description |
---|---|---|---|
init() |
Connect to the Tobii eye tracker and initialize it according to the requested settings (provided optionally when calling Titta.Connect() ). |
||
calibrate() |
|
Do participant setup, calibration and validation. | |
start_recording() |
|
Begin recording the specified kind of data. If none of the input parameters are set to true, then this method does nothing. | |
stop_recording() |
|
Stop recording the specified kind of data. If none of the input parameters are set to true, then this method does nothing. | |
send_message() |
|
Store timestamped message | |
save_data() |
|
Save data to HDF5 container at specified location | |
calibration_history() |
|
Get the calibration history thus far. | |
system_info() |
|
Get information about the system and connected eye tracker. | |
get_system_time_stamp() |
|
Get the current system time through the Tobii Pro SDK. | |
set_sample_rate() |
|
Set the sampling rate of the connected eye tracker (if it is a supported frequency). | |
get_sample_rate() |
|
Get the sampling rate of the connected eye tracker. |
The TittaPy class can be used for interaction with the eye tracker's data streams. It is accessed via Tobii.MyTobii
's buffer
property. For instance, if tracker
is your Tobii.MyTobii
instance, then you can retrieve the recorded samples using tracker.buffer.consume_N()
. The TittaPy methods and properties are documented in the TittaPy repository.
An instance of TalkToProLab is constructed by calling TalkToProLab()
and optionally providing two constructor arguments:
project_name
: (optional) the name of the External Presenter project that should be opened in Pro Labdummy_mode
: (optional) a bool indicating whether to run in dummy mode. Default: false.
The following method calls are available on a TalkToProLab instance. The majority of return types are the response
dictionary, containing the operation name, the status code, and however many useful variables relevant to this operation. The status codes are as follows:
0: 'Operation successful',
100: 'Bad request',
101: 'Invalid parameter',
102: 'Operation was unsuccessful',
103: 'Operation cannot be executed in current state',
104: 'Access to the service is forbidden',
105: 'Authorization during connection to a service has not been provided',
201: 'Recording finalization failed'.
Call | Inputs | Outputs | Description |
---|---|---|---|
add_participant() |
|
response , a dictionary containing:
|
Create a new participant in the Tobii Pro Lab project. |
find_participant() |
|
|
Find whether a participant already exists in the Tobii Pro Lab project. |
list_participants() |
response , a dictionary containing:
|
List all participants in the Tobii Pro Lab project. | |
upload_media() |
|
Upload media to the Tobii Pro Lab project. | |
find_media() |
|
|
Find media by name in the Tobii Pro Lab project. |
list_media() |
response , a dictionary containing:
|
List all media in the Tobii Pro Lab project. | |
add_aois_to_image |
|
response , a dictionary containing:
|
Define an AOI for a specific media in the Pro Lab project. |
add_aois_to_video |
|
response , a dictionary containing:
|
Define an AOI for a specific media in the Pro Lab project. |
get_state() |
response , a dictionary containing:
|
Get the state of the external presenter service in Pro Lab. | |
start_recording() |
|
response , a dictionary containing:
|
Tell Pro Lab to start a recording. |
stop_recording() |
Stop a currently ongoing recording of Tobii Pro Lab. | ||
finalize_recording() |
|
Finalize the stopped recording in Tobii Pro Lab. Note: after this call, you must still click ok in the Pro Lab user interface. | |
send_stimulus_event() |
|
Inform Pro Lab when and where a media (stimulus) was shown. | |
send_custom_event() |
|
Add an event to Pro Lab's timeline. | |
disconnect() |
Disconnect from Tobii Pro Lab. |