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).
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.
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.
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.
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.
OSX is currently not supported, although the TittaMex file does build succesfully on OSX with the makeTittaMex.m
script.
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:
- Using Git
- 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.
- Download Titta and its dependencies in one go using the following command:
git clone --recurse-submodules -j8 git://github.com/dcnieho/Titta.git
. - Should this not work due to your git version being too old, try executing the
following commands:
If you have already cloned Titta but do not have the MatlabWebSocket submodule populated yet, issuing the
git clone git://github.com/dcnieho/Titta.git` cd Titta git submodule update --init --recursive
git submodule update --init --recursive
command will take care of that.
- Manual download:
- First download Titta and place it, unzipped if necessary, in your preferred folder.
- Then download MatlabWebSocket (available from https://github.com/jebej/MatlabWebSocket). Download the currently tested version.
- Put the MatlabWebSocket directory inside Titta at the right location:
<tittaRootDir>/talkToProLab/MatlabWebSocket
).
- 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.
The toolbox consists of multiple parts:
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
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. double
s which are MATLAB's native data type instead of single
s) 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 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:
- Open an External Presenter project in Tobii Pro Lab, make sure its name matches what you provide to the
TalkToProLab
constructor. - Navigate to the 'record'-tab in Pro Lab
- Make sure that the External presenter button is red and says 'not connected'
- Run this script
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 Spark Tobii Pro Spark
Tobii Pro Nano Tobii Pro Nano
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* 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 yielderror 201: TOBII_RESEARCH_STATUS_SE_INSUFFICIENT_LICENSE
. -
Change settings from their defaults if wanted (see supported options section below)
-
Create a Titta instance using this settings struct:
EThndl = Titta(settings);
-
Interact with the eye tracker using the below 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. It can be configured to different keys with thesettings.UI.button
options listed below. In addition, a few global hotkeys are available. These are documented below in the API documentation of theTitta.calibrate()
method. A more advanced participant setup and calibration interface intended especially to enable work with non-cooperative subject populations such as infants and primates is provided by theTitta.calibrateAdvanced()
function. -
Example analysis scripts for the recorded data (fixation classification and AOI analysis) are also provided.
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
.
The below method can be called on a Titta instance or on the Titta class directly.
Call | Inputs | Outputs | Description |
---|---|---|---|
getDefaults() |
|
|
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. |
getFileName() |
|
|
Get filename for saving data, with optional versioning. |
getTimeAsSystemTime() |
|
|
Maps the provided PsychtoolBox timestamp (or the current PsychtoolBox time provided by the GetSecs() function) to the Tobii system time provided in microseconds by the Tobii Pro SDK. On Windows, PsychtoolBox time and Tobii system time use the same clock, and this operation thus only entails a conversion from seconds to microseconds. On Linux, the clocks are different, and remapping is performed using the PTB function GetSecs('AllClocks') with an accuracy of 20 microseconds or better. |
getValidationQualityMessage() |
|
|
Provides a textual rendering of data quality as assessed through a validation procedure. |
saveData() |
|
|
Save data returned by Titta.collectSessionData() directly to mat file at the specified location. |
saveDataToParquet() |
|
|
Save data returned by Titta.collectSessionData() to a series of Apache Parquet and JSON files at the specified location. Data from the various streams is written as tables into Parquet files, metadata and calibration info as JSON files. |
saveGazeDataToTSV() |
|
|
Save gaze data and messages returned by Titta.collectSessionData() to tsv files at the specified location. |
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).
The following method calls are available on a Titta instance:
Call | Inputs | Outputs | Description |
---|---|---|---|
setDummyMode() |
|
Turn the current Titta instance into a dummy mode class. |
|
getOptions() |
|
Get active settings, returns only those that can be changed in the current state (which is a subset of all settings once init() has been called) |
|
setOptions() |
|
Change active settings. First use getOptions() to get an up-to-date settings struct, then edit the wanted settings and use this function to set them |
|
init() |
|
Connect to the Tobii eye tracker and initialize it according to the requested settings. If a specific eye tracker address is provided, this eye tracker is directly connected to. | |
calibrate() |
|
|
Do participant setup, calibration and validation. Issue help Titta.calibrate on the matlab command prompt for further documentation. |
calibrateAdvanced() |
|
|
Do participant setup, calibration and validation using an advanced procedure suitable for non-compliant subjects. Issue help Titta.calibrateAdvanced on the matlab command prompt for further documentation. |
sendMessage() |
|
|
Store timestamped message |
getMessages() |
|
Get all the timestamped messages stored during the current session. | |
collectSessionData() |
|
Collects all data one may want to store to file, neatly organized. | |
deInit() |
|
Close connection to the eye tracker and clean up |
The following read-only properties are available for a Titta instance:
Property | Description |
---|---|
geom |
Filled by init() . Struct with information about the setup geometry known to the eye tracker, such as screen width and height, and the screen's location in the eye tracker's user coordinate system. |
calibrateHistory |
Returns cell array with information about all calibration attempts during the current session |
buffer |
Initialized by call to init() . Returns handle to TittaMex 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. |
deviceName |
Get connected eye tracker's device name. |
serialNumber |
Get connected eye tracker's serial number. |
model |
Get connected eye tracker's model name. |
firmwareVersion |
Get connected eye tracker's firmware version. |
runtimeVersion |
Get connected eye tracker's runtime version. |
address |
Get connected eye tracker's address. |
capabilities |
Get connected eye tracker's exposed capabilities. |
supportedFrequencies |
Get connected eye tracker's supported sampling frequencies. |
supportedModes |
Get connected eye tracker's supported tracking modes. |
systemInfo |
Filled by init() . Struct with information about the eye tracker connected to: the device name, serial number, model name, firmware version, runtime version, address, sampling frequency, tracking mode, capabilities, supported sampling frequencies, and supported tracking modes of the connected eye tracker. |
The following settable properties are available for a Titta instance:
Property | Description |
---|---|
frequency |
Get or set connected eye tracker's sampling frequency. |
trackingMode |
Get or set connected eye tracker's tracking mode. |
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.
Option name | Explanation |
---|---|
settings.trackingMode |
Some trackers, like the Spectrum with firmware version>=1.7.6, have multiple tracking modes, select tracking mode by providing its name. |
settings.freq |
Sampling frequency |
settings.calibrateEye |
Which eye to calibrate: 'both', also possible if supported by eye tracker: 'left' and 'right'. |
settings.serialNumber |
If looking to connect to a specific eye tracker when multiple are available on the network, provide its serial number here. |
settings.licenseFile |
If you tracker needs a license file applied (e.g. Tobii 4C), provide the full path to the license file here, or a cell array of full paths if there are multiple licenses to apply. |
settings.nTryReConnect |
How many times to retry connecting before giving up? Something larger than zero is good as it may take more time than the first call to TittaMex.findAllEyeTrackers() for network eye trackers to be found. |
settings.connectRetryWait |
Seconds: time to wait between connection retries. |
settings.debugMode |
Only for Titta developer use. Prints some debug output to command window. |
settings.cal.pointPos |
Nx2 matrix of screen positions ([0,1] range) of calibration points, leave empty to do a zero-point calibration, i.e., use the tracker's default calibration. |
settings.cal.pointPosTrackerSpace |
Nx2 matrix of screen positions ([0,1] range) of calibration points to be sent to the Tobii SDK during calibration. Use when the screen shown to the participant does not match the plane to which the eye tracker is calibrated (e.g. because it is flipped because it is viewed through a mirror). Should be the same size as settings.cal.pointPos . See also settings.val.pointPosTrackerSpace . |
settings.cal.autoPace |
0: manually confirm each calibration point. 1: only manually confirm the first point, the rest will be autoaccepted. 2: all calibration points will be auto-accepted. Applies also to validation points since calibration and validation points are shown as one continuous stream. |
settings.cal.paceDuration |
Minimum duration (s) that each calibration point is shown. |
settings.cal.doRandomPointOrder |
If true, the calibration points are shown in random order. If false, each row in settings.cal.pointPos is worked through in order. |
settings.cal.bgColor |
RGB (0-255) background color for calibration/validation screen. |
settings.cal.fixBackSize |
Size (pixels) of large circle in fixation cross. |
settings.cal.fixFrontSize |
Size (pixels) of small circle in fixation cross. |
settings.cal.fixBackColor |
Color (RGB, 0-255) of large circle in fixation cross. |
settings.cal.fixFrontColor |
Color (RGB, 0-255) of small circle in fixation cross. |
settings.cal.drawFunction |
Function to be called to draw calibration screen. See the AnimatedCalibrationDisplay class packaged with Titta for an example. |
settings.cal.doRecordEyeImages |
If true, eye images are recorded during calibration and validation, if supported by the eye tracker. |
settings.cal.doRecordExtSignal |
If true, external signals are recorded during calibration and validation, if supported by the eye tracker. |
settings.cal.pointNotifyFunction |
If provided, this callback is called for each calibration point when collecting data for the point completes (either successfully or failed). |
settings.val.pointPos |
Nx2 matrix of screen positions ([0,1] range) of validation points. |
settings.val.pointPosTrackerSpace |
Nx2 matrix of screen positions ([0,1] range) of validation points in tracker space. Only needed when settings.cal.pointPosTrackerSpace is specified. |
settings.val.paceDuration |
Minimum duration (s) that each validation point is shown. |
settings.val.collectDuration |
Amount of validation data (seconds) to collect for each validation point. |
settings.val.doRandomPointOrder |
If true, the calibration points are shown in random order. If false, each row in settings.val.pointPos is worked through in order. |
settings.val.pointNotifyFunction |
If provided, this callback is called for each validation point when collecting gaze data for the point completes. |
settings.UI.startScreen |
0: skip head positioning, go straight to calibration; 1: start with head positioning interface. |
settings.UI.hardExitClosesPTB |
If true (default), pressing shift-escape in the calibration interface causes the PTB window to close. |
settings.UI.setup.showEyes |
Show eyes on disk representing head used for head position visualization? |
settings.UI.setup.showPupils |
Show pupils in the eyes? |
settings.UI.setup.referencePos |
Location of head in trackbox for which head circle exactly overlaps reference circle in the head positioning visualization. [x y z] in cm. If empty, default: middle of trackbox |
settings.UI.setup.doCenterRefPos |
if true, reference circle is always at center of screen, regardless of x- and y-components of settings.UI.setup.referencePos . If false, circle is positioned settings.UI.setup.referencePos(1) cm horizontally and settings.UI.setup.referencePos(2) cm vertically from the center of the screen (assuming screen dimensions were correctly set in Tobii Eye Tracker Manager). |
settings.UI.setup.bgColor |
RGB (0-255) background color for setup screen. |
settings.UI.setup.refCircleClr |
Color of reference circle for head position visualization. |
settings.UI.setup.headCircleEdgeClr |
Color of egde of disk representing head used for head position visualization. |
settings.UI.setup.headCircleFillClr |
Color of fill of disk representing head used for head position visualization. |
settings.UI.setup.eyeClr |
Color of eyes in head. |
settings.UI.setup.pupilClr |
Color of pupils in eyes. |
settings.UI.setup.crossClr |
Color of cross taking position of ignored eye when doing monocular calibration. |
settings.UI.setup.fixBackSize |
Size (pixels) of large circle in fixation cross. |
settings.UI.setup.fixFrontSize |
Size (pixels) of small circle in fixation cross. |
settings.UI.setup.fixBackColor |
Color (RGB, 0-255) of large circle in fixation cross. |
settings.UI.setup.fixFrontColor |
Color (RGB, 0-255) of small circle in fixation cross. |
settings.UI.setup.showHeadToSubject |
If true (default), the reference circle and head display are shown on the participant monitor when showing setup display. |
settings.UI.setup.showInstructionToSubject |
If true (default), the instruction text is shown on the participant monitor when showing setup display. |
settings.UI.setup.showFixPointsToSubject |
If true (default), the fixation points in the corners of the screen are shown on the participant monitor when showing setup display. |
settings.UI.setup.instruct.strFun |
Function handle to function producing positioning instruction string. This function should take six inputs: current head position x , y , and z as well as reference position x , y and z . |
settings.UI.setup.instruct.font |
See Text options. |
settings.UI.setup.instruct.size |
See Text options. |
settings.UI.setup.instruct.color |
See Text options. |
settings.UI.setup.instruct.style |
See Text options. |
settings.UI.setup.instruct.vSpacing |
See Text options. |
settings.UI.button.margins |
For all interface buttons, internal margins around their text content. |
settings.UI.button.setup.text.font |
Setting for all buttons on the setup screen. See Text options. |
settings.UI.button.setup.text.size |
Setting for all buttons on the setup screen. See Text options. |
settings.UI.button.setup.text.style |
Setting for all buttons on the setup screen. See Text options. |
settings.UI.button.setup.eyeIm |
Toggle button for showing or hiding eye image (if eye tracker provides them). See Button options. Default hotkey: e . |
settings.UI.button.setup.cal |
Button for starting a calibration. See Button options. Default hotkey: spacebar . |
settings.UI.button.setup.prevcal |
Button for going to the validation result screen, only available if there are previous successful calibrations. See Button options. Default hotkey: p . |
settings.UI.button.val.text.font |
Setting for all buttons on the validation result screen. See Text options. |
settings.UI.button.val.text.size |
Setting for all buttons on the validation result screen. See Text options. |
settings.UI.button.val.text.style |
Setting for all buttons on the validation result screen. See Text options. |
settings.UI.button.val.recal |
Button for starting a new calibration. See Button options. Default hotkey: escape . |
settings.UI.button.val.reval |
Button for revalidating the currently selected calibration. See Button options. Default hotkey: v . |
settings.UI.button.val.continue |
Button for confirming selection of calibration and returning from the calibration interface to user code. See Button options. Default hotkey: spacebar . |
settings.UI.button.val.selcal |
Toggle button to bring up or close a calibration selection menu. Only available if there multiple successful calibration are available. See Button options. Default hotkey: c . |
settings.UI.button.val.setup |
Button for returning to the setup screen. See Button options. Default hotkey: s . |
settings.UI.button.val.toggGaze |
Toggle button switching on/off an online visualization of current gaze location. See Button options. Default hotkey: g . When in dual screen mode, by default the online gaze visualization is only shown on the operator screen. To also show it on the participant screen, hold down the shift key while pressing this hotkey. |
settings.UI.button.val.toggCal |
Toggle button for switching between showing the validation output and the calibration output on the validation result screen. See Button options. Default hotkey: t . |
settings.UI.button.val.toggSpace |
Toggle button for switching between showing the validation output and the calibration output on the validation result screen in screen space or in tracker space. Only available if a different tracker space was set up using the settings.cal.pointPosTrackSpace option. See Button options. Default hotkey: x . |
settings.UI.button.val.toggPlot |
Toggle button for switching between showing the validation result screen and a screen showing timeseries plots of the data collected during validation. See Button options. Default hotkey: p . |
settings.UI.plot.bgColor |
RGB (0-255) background color for calibration/validation screen. |
settings.UI.plot.eyeColors |
Colors to use for plotting the collected validation data for the left and right eye on the validation result screen. Provide as a two-element cell array, {leftEyeColor,rightEyeColor} , where each color is RGB (0-255). |
settings.UI.plot.lineWidth |
Linewidth (pixels) used for plotting the data. |
settings.UI.plot.scrMargins |
Fraction of screen used as blank margin ([left right top bottom] ) around the plot screen. |
settings.UI.plot.panelPad |
Vertical padding between the plot panels, expressed as fraction of screen. |
settings.UI.plot.dotPosLine.color |
RGB (0-255) color of lines showing fixation point position on the time series plots. |
settings.UI.plot.dotPosLine.width |
Linewidth (pixels) of lines showing fixation point position on the time series plots. |
settings.UI.plot.ax.bgColor |
RGB (0-255) background color for plot panels. |
settings.UI.plot.ax.lineColor |
RGB (0-255) background color for plot panel axis lines. |
settings.UI.plot.ax.lineWidth |
Linewidth (pixels) of plot panel axis lines. |
settings.UI.plot.ax.tickLength |
Length of plot ticks, expressed as fraction of screen. |
settings.UI.plot.ax.highlightColor |
RGB (0-255) or RGBA (including opacity) color for highlight on plot with context indicating which data recorded during validation was used for data quality calculations. |
settings.UI.plot.ax.axisLbls.x |
X-axis label. |
settings.UI.plot.ax.axisLbls.offset |
Y-axis labels for plots without context. |
settings.UI.plot.ax.axisLbl |
Text formatting options for axis labels, see Text options. |
settings.UI.plot.ax.tickLbl |
Text formatting options for tick label values, see Text options. |
settings.UI.plot.ax.valLbl |
Text formatting options for validation instance labels atop the plots, see Text options. |
settings.UI.plot.but.exit |
Button to exit the plot view and return to the validation result screen. See Button options. Default hotkey: escape . |
settings.UI.plot.but.valSel |
Toggle button for switching between showing just the data used for data quality calculations or all the data recorded during validation. See Button options. Default hotkey: c . |
settings.UI.cal.errMsg.string |
String to display when the Tobii calibration functions inform that calibration was unsuccessful. |
settings.UI.cal.errMsg.font |
See Text options. |
settings.UI.cal.errMsg.size |
See Text options. |
settings.UI.cal.errMsg.color |
See Text options. |
settings.UI.cal.errMsg.style |
See Text options. |
settings.UI.cal.errMsg.wrapAt |
See Text options. |
settings.UI.val.eyeColors |
Colors to use for plotting the collected validation data for the left and right eye on the validation result screen. Provide as a two-element cell array, {leftEyeColor,rightEyeColor} , where each color is RGB (0-255). |
settings.UI.val.bgColor |
RGB (0-255) background color for validation result screen. |
settings.UI.val.fixBackSize |
Size (pixels) of large circle in fixation crosses denoting the validation point positions. |
settings.UI.val.fixFrontSize |
Size (pixels) of small circle in fixation cross denoting the validation point positions. |
settings.UI.val.fixBackColor |
Color (RGB, 0-255) of large circle in fixation cross denoting the validation point positions. |
settings.UI.val.fixFrontColor |
Color (RGB, 0-255) of small circle in fixation cross denoting the validation point positions. |
settings.UI.val.onlineGaze.eyeColors |
Colors to use for displaying online gaze location of the left and right eye. For format, see settings.UI.val.eyeColors . |
settings.UI.val.onlineGaze.fixBackSize |
Size (pixels) of large circle in fixation crosses shown when online gaze display is active. |
settings.UI.val.onlineGaze.fixFrontSize |
Size (pixels) of small circle in fixation cross shown when online gaze display is active. |
settings.UI.val.onlineGaze.fixBackColor |
Color (RGB, 0-255) of large circle in fixation cross shown when online gaze display is active. |
settings.UI.val.onlineGaze.fixFrontColor |
Color (RGB, 0-255) of small circle in fixation cross shown when online gaze display is active. |
settings.UI.val.avg.text.font |
Font for rendering information about validation data quality averaged over the validation points. Should be a monospaced font. |
settings.UI.val.avg.text.size |
See Text options. |
settings.UI.val.avg.text.color |
See Text options. |
settings.UI.val.avg.text.eyeColors |
Colors to use for labeling data quality for the left and right eye. For format, see settings.UI.val.eyeColors . |
settings.UI.val.avg.text.style |
See Text options. |
settings.UI.val.avg.text.vSpacing |
See Text options. |
settings.UI.val.hover.bgColor |
RGB (0-255) background color for popup that appears when hovering over a validation point. |
settings.UI.val.hover.text.font |
Font for rendering information about validation data for a specific validation point in the hover popup. Should be a monospaced font. |
settings.UI.val.hover.text.size |
See Text options. |
settings.UI.val.hover.text.color |
See Text options. |
settings.UI.val.hover.text.eyeColors |
Colors to use for labeling data quality for the left and right eye. For format, see settings.UI.val.eyeColors . |
settings.UI.val.hover.text.style |
See Text options. |
settings.UI.val.menu.bgColor |
RGB (0-255) background color for calibration selection menu. |
settings.UI.val.menu.itemColor |
RGB (0-255) background color for non-selected items in the calibration menu. |
settings.UI.val.menu.itemColorActive |
RGB (0-255) background color for selected item in the calibration menu. |
settings.UI.val.menu.text.font |
Font for rendering information about a calibration in the calibration selection menu. Should be a monospaced font. |
settings.UI.val.menu.text.eyeColors |
Colors to use for labeling data quality for the left and right eye. For format, see settings.UI.val.eyeColors . |
settings.UI.val.menu.text.size |
See Text options. |
settings.UI.val.menu.text.color |
See Text options. |
settings.UI.val.menu.text.style |
See Text options. |
settings.UI.operator.setup |
A subset of the options in settings.UI.setup that controls the look of the operator screen when running in a two-screen setup. |
settings.UI.operator.cal |
A subset of the options in settings.cal that controls the look of the operator screen when running in a two-screen setup. |
settings.UI.operator.val |
A subset of the options in settings.UI.val that controls the look of the operator screen when running in a two-screen setup. |
Texts take all or some of the below options:
Option name | Explanation |
---|---|
font |
Font in which to render the string. |
size |
Text size at which to render the string. |
color |
Color in which to render the string. |
style |
Style with which to render the string. The following can ORed together: 0=normal, 1=bold, 2=italic, 4=underline, 8=outline, 32=condense, 64=extend. |
vSpacing |
Long strings will be wrapped such that each line is no longer than this many characters. |
wrapAt |
Vertical space between lines. 1 is normal spacing. |
Each button takes the below options:
Option name | Explanation |
---|---|
accelerator |
Keyboard key to activate this buttton. |
visible |
If false, button will not be shown in the interface. The functionality remains accessible through the accelerator key (see accelerator ). |
string |
Text to be show on the button. |
fillColor |
Fill color of the button: RGB (0-255). |
edgeColor |
Edge color of the button: RGB (0-255). |
textColor |
Color of the text on the button: RGB (0-255). |
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).
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
.
Call | Inputs | Outputs | Description |
---|---|---|---|
findAllEyeTrackers() |
|
Gets the eye trackers that are connected to the system, as listed by the Tobii Pro SDK. | |
getSDKVersion() |
|
Get the version of the Tobii Pro SDK dynamic library that is used by Titta. | |
getSystemTimestamp() |
|
Get the current system time through the Tobii Pro SDK. | |
startLogging() |
|
|
Start listening to the eye tracker's log stream, store any events to buffer. |
getLog() |
|
|
Return and (optionally) remove log events from the buffer. |
stopLogging() |
Stop listening to the eye tracker's log stream. |
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()
.
The following method calls are available on a Titta
instance:
Call | Inputs | Outputs | Description |
---|---|---|---|
init() |
|
Connect the Titta class instance to the Tobii eye tracker and prepare it for use. | |
getEyeTrackerInfo() |
|
Get information about the eye tracker that the Titta instance is connected to. | |
getTrackBox() |
|
Get the track box of the connected eye tracker. | |
getDisplayArea() |
|
Get the display area of the connected eye tracker. | |
applyLicenses() |
|
|
Apply license(s) to the connected eye tracker. |
clearLicenses() |
Clear all licenses that may have been applied to the connected eye tracker. Refreshes the eye tracker's info, so use getConnectedEyeTracker() to check for any updated capabilities. |
||
hasStream() |
|
|
Check whether the connected eye tracker supports providing a data stream of a specified type. |
setIncludeEyeOpennessInGaze() |
|
|
Set whether calls to start or stop the gaze stream should also start or stop the eye openness stream. An error will be raised if set to true, but the connected eye tracker does not provide an eye openness stream. If set to true, calls to start or stop the eyeOpenness stream will also start or stop the gaze stream. |
start() |
|
|
Start streaming data of a specified type to buffer. The default initial buffer size should cover about 30 minutes of recording gaze data at 600Hz, and longer for the other streams. Growth of the buffer should cause no performance impact at all as it happens on a separate thread. To be certain, you can indicate a buffer size that is sufficient for the number of samples that you expect to record. Note that all buffers are fully in-memory. As such, ensure that the computer has enough memory to satify your needs, or you risk a recording-destroying crash. |
isRecording() |
|
|
Check if data of a specified type is being streamed to buffer. |
consumeN() |
|
|
Return and remove data of the specified type from the buffer. See the Tobii SDK documentation for a description of the fields. |
consumeTimeRange() |
|
|
Return and remove data of the specified type from the buffer. See the Tobii SDK documentation for a description of the fields. |
peekN() |
|
|
Return but do not remove data of the specified type from the buffer. See the Tobii SDK documentation for a description of the fields. |
peekTimeRange() |
|
|
Return but do not remove data of the specified type from the buffer. See the Tobii SDK documentation for a description of the fields. |
clear() |
|
Clear the buffer for data of the specified type. | |
clearTimeRange() |
|
Clear data of the specified type within specified time range from the buffer. | |
stop() |
|
|
Stop streaming data of a specified type to buffer. |
enterCalibrationMode() |
|
|
Queue request for the tracker to enter into calibration mode. |
isInCalibrationMode() |
|
|
Check whether eye tracker is in calibration mode. |
leaveCalibrationMode() |
|
|
Queue request for the tracker to leave the calibration mode. |
calibrationCollectData() |
|
Queue request for the tracker to collect gaze data for a single calibration point. | |
calibrationDiscardData() |
|
Queue request for the tracker to discard any already collected gaze data for a single calibration point. | |
calibrationComputeAndApply() |
Queue request for the tracker to compute the calibration function and start using it. | ||
calibrationGetData() |
Request retrieval of the computed calibration as an (uninterpretable) binary stream. | ||
calibrationApplyData() |
|
Apply the provided calibration data. | |
calibrationGetStatus() |
|
Get the current state of Titta's calibration mechanism. | |
calibrationRetrieveResult() |
|
Get information about tasks completed by Titta's calibration mechanism. |
The following read-only properties are available for a Titta instance:
Property | Description |
---|---|
serialNumber |
Get connected eye tracker's serial number. |
model |
Get connected eye tracker's model name. |
firmwareVersion |
Get connected eye tracker's firmware version. |
runtimeVersion |
Get connected eye tracker's runtime version. |
address |
Get connected eye tracker's address. |
capabilities |
Get connected eye tracker's exposed capabilities. |
supportedFrequencies |
Get connected eye tracker's supported sampling frequencies. |
supportedModes |
Get connected eye tracker's supported tracking modes. |
The following settable properties are available for a Titta instance:
Property | Description |
---|---|
deviceName |
Get or set connected eye tracker's device name. |
frequency |
Get or set connected eye tracker's sampling frequency. |
trackingMode |
Get or set connected eye tracker's tracking mode. |
The below method can be called on a TalkToProLab instance or on the TalkToProLab class directly.
Call | Inputs | Outputs | Description |
---|---|---|---|
makeAOITag |
|
|
Generates an AOI tag in the format expected by TalkToProLab.attachAOIToImage() . |
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. Two optional additional constructor arguments can be provided.
doCheckSync
: (defaulttrue
) determines whether clock sync between PsychToolbox and Pro Lab endpoint should be checked. Set to false if you want to useTalkToProLab
without PsychToolbox (no other part of theTalkToProLab
class uses PsychToolbox functionality), or if you want to useTalkToProLab
with a two-computer setup, where Pro Lab runs on a different machine than MATLAB. Note that in this case, you are responsible for figuring out the sync between Pro Lab your local machine yourself. This is important becauseTalkToProLab.sendStimulusEvent()
andTalkToProLab.sendCustomEvent()
take timestamps in Pro Lab time, not local time. You can use theTalkToProLab.clientClock
WebSocket interface to talk directly to Pro Lab's clock websocket service.IPorFQDN
: this is to indicate the IP or FQDN where the Pro Lab instance can be contacted. Defaults tolocalhost
for a one-computer setup.
The following method calls are available on a TalkToProLab instance
Call | Inputs | Outputs | Description |
---|---|---|---|
disconnect() |
Disconnect from Tobii Pro Lab. | ||
createParticipant() |
|
|
Create a new participant in the Tobii Pro Lab project. |
findMedia() |
|
|
Find media by name in the Tobii Pro Lab project. |
uploadMedia() |
|
|
Upload media to the Tobii Pro Lab project. |
attachAOIToImage |
|
Define an AOI for a specific media in the Pro Lab project. | |
attachAOIToVideo |
|
Define an AOI for a specific media in the Pro Lab project. | |
getExternalPresenterState() |
|
Get the state of the external presenter service in Pro Lab. | |
startRecording() |
|
|
Tell Pro Lab to start a recording. |
stopRecording() |
Stop a currently ongoing recording of Tobii Pro Lab. | ||
finalizeRecording() |
Finalize the stopped recording in Tobii Pro Lab. Note: after this call, you must still click ok in the Pro Lab user interface. | ||
discardRecording() |
Discard (remove) the stopped recording in Tobii Pro Lab. | ||
sendStimulusEvent() |
|
Inform Pro Lab when and where a media (stimulus) was shown. | |
sendCustomEvent() |
|
Add an event to Pro Lab's timeline. |
The following read-only properties are available for a TalkToProLab instance:
Property | Description |
---|---|
projectID |
The GUID indentifying the project opened in Pro Lab. |
participantID |
Filled by TalkToProLab.createParticipant() . The GUID indentifying the participant for which a recording will be created in Pro Lab. |
recordingID |
Filled by TalkToProLab.startRecording() . The GUID indentifying the current recording in Pro Lab. |
clientClock |
Websocket interface to the clock API of Tobii Pro Lab. |
clientProject |
Websocket interface to the project API of Tobii Pro Lab. |
clientEP |
Websocket interface to the external presenter API of Tobii Pro Lab. |