Titta is a toolbox for using eye trackers from Tobii Pro AB with MATLAB, 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 MATLAB MEX file TittaMex
providing MATLAB Titta with connectivity to the Tobii eye trackers. This C++ wrapper can be consumed by your own C++ projects as well, or be wrapped for other programming languages (a wrapper to Python is also provided).
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 TittaMex/deps/include/
carry a different license, please refer to the Tobii License Agreement for more information.
demos/readme.m
shows a minimal example of using the toolbox's
functionality.
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. At minimum, 3.0.16 "Crowning achievement", released on 2020-05-10 is required.
Only the Titta.calibrate()
and Titta.calibrateManual()
functions and optionally the TalkToProLab
constructor use Psychtoolbox functionality, the rest of the toolbox can be used from MATLAB without having PsychToolbox installed.
Currently the toolbox is only supported on Windows (tested on Windows 10 and Windows 7), Linux support is nearly completed, and 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.
Tested on MATLAB R2015b & R2019a. The mex file builds on Octave, but Octave can currently not be supported due to this (now solved) bug that has not yet been included in a release that is also supported by PsychToolbox.
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).
- 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 and 2019 installed. This is the most likely cause of errors like "The specified module could not be found" when loading the mex 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()
participant setup and calibration interface requires PsychToolbox.
The TittaMex
C++ class and MATLAB wrapper by the same name are alternatives to the Tobii Pro MATLAB SDK for handling data streams and calibration, and can be used without making use of the Titta interface. It is used by Titta under the hood (user can access it directly through Titta.buffer
). Besides providing access to the same tracker functionality as the Tobii Pro MATLAB SDK, it has two main features: (1) more complete an 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. For the rest, other function implemented in TittaMex
provide return values that are a bit friendlier to use in MATLAB, in the author's opinion (e.g. double
s instead of single
s) and no use of MATLAB classes to just hold plain data.
The TalkToProLab
class provides an implementation of Tobii Pro Lab's External Presenter interface, allowing experiments to be created and run from MATLAB with PsychToolbox 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 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.
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. |
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. |
getFileName() |
|
|
Get filename for saving data, with optional versioning. |
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 | ||
calibrate() |
|
|
Do participant setup, calibration and validation. Issue help Titta.calibrate on the matlab command prompt for further documentation. |
calibrateManual() beta |
|
|
Do participant setup, calibration and validation using a manual procedure suitable for non-compliant subjects. Issue help Titta.calibrateManual 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. | |
saveData() |
|
|
Save data returned by collectSessionData() directly to mat file at specified location |
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, or for directly interacting with the eye tracker through the Tobii Pro SDK. 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. |
frequency |
Get or set connected eye tracker's sampling frequency. |
trackingMode |
Get or set connected eye tracker's tracking mode. |
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. |
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.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.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.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. |
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).
Call | Inputs | Outputs | Description |
---|---|---|---|
findAllEyeTrackers() |
|
Gets the eye trackers that are connected to the system, as listed by 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 TittaMex is constructed by calling TittaMex()
. 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 TittaMex.findAllEyeTrackers()
.
The following method calls are available on a TittaMex instance:
Call | Inputs | Outputs | Description |
---|---|---|---|
init() |
|
Connect to the TittaMex class instance to the Tobii eye tracker and prepare it for use. | |
getEyeTrackerInfo() |
|
Get information about the eye tracker that the TittaMex 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. |
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. |
consumeTimeRange() |
|
|
Return and remove data of the specified type from the buffer. |
peekN() |
|
|
Return but do not remove data of the specified type from the buffer. |
peekTimeRange() |
|
|
Return but do not remove data of the specified type from the buffer. |
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() |
|
|
Check whether eye tracker is in calibration mode. |
isInCalibrationMode() |
|
Queue request for the tracker to enter into 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 TittaMex's calibration mechanism. | |
calibrationRetrieveResult() |
|
Get information about tasks completed by TittaMex's calibration mechanism. |
The following read-only properties are available for a TittaMex instance:
Property | Description |
---|---|
getSDKVersion |
Get the version of the Tobii Pro SDK dynamic library that is used by TittaMex . |
getSystemTimestamp |
Get the current system time through the Tobii Pro SDK. Returns an int64 scalar denoting Tobii system time in microseconds. |
deviceName |
Get or set 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. |
frequency |
Get or set connected eye tracker's sampling frequency. |
trackingMode |
Get or set connected eye tracker's tracking mode. |
supportedFrequencies |
Get connected eye tracker's supported sampling frequencies. |
supportedModes |
Get connected eye tracker's supported tracking modes. |
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. |