Package: titta
Titta is a toolbox for using eye trackers from Tobii Pro AB with Python,
specifically offering integration withPsychoPy. A Matlab version
that integrates with PsychToolbox is also available fromhttps://github.com/dcnieho/Titta. For a similar toolbox for SMI eye trackers, please seewww.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.Cite as:Niehorster, D.C., Andersson, R. & Nystrom, M. (2020). Titta: A toolbox for creating PsychToolbox and Psychopy experiments with Tobii eye trackers. Behavior Research Methods. doi: 10.3758/s13428-020-01358-8For questions, bug reports or to check for updates, please visithttps://github.com/marcus-nystrom/Titta.To minimize the risk of missing samples, the current repository usesTittaPy(pip install TittaPy), a C++ wrapper around the Tobii SDK, to pull samples made available from the eye tracker.To get startedIf you know what you are doing, install Titta using:pip install tittaorpython -m pip install titta.If you use a standalone PsychoPy installation, do the following steps:Go toC:\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 likepython -m pip install titta --upgrade.Then runread_me.pyfrom the 'demos' folder (first change the monitor settings and the eye tracker name inread_me.py). Reading throughread_me.pyshould provide a good starting point for most users of Titta.To get started with the Tobii Pro Lab integrationOpen read_read_me_TalkToProLab.py in PsychoPy.DownloadTobii 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
theTobii Eye Tracker Managerbefore trying to use it with Titta.ContentsThe toolbox consists of two main parts:TheTitta.ConnectandTobii.MyTobiiclassesThe 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 theTitta.calibrate()participant setup and calibration interface requires PsychoPy.These modules connect to Tobii viaTittaPy. AlthoughTittaPyis located in a separate repository, documentation for it is included here since it is powering theTittaandTobiimodules here.TheTalkToProLabclassTheTalkToProLabclass provides an implementation ofTobii 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.UsageAs 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 trackerModel nameTobii Pro SpectrumTobii Pro SpectrumTobii Pro FusionTobii Pro FusionTobii Pro TX300Tobii TX300Tobii Pro T60 XLTobii T60 XLTobii Pro NanoTobii Pro NanoTobii Pro SparkTobii Pro SparkTobii Pro X3-120Tobii Pro X3-120orTobii Pro X3-120 EPUTobii Pro X2-60X2-60_CompactTobii Pro X2-30X2-30_CompactTobii Pro X60Tobii X60Tobii Pro X120Tobii X120Tobii Pro T60Tobii T60Tobii Pro T120Tobii T120Tobii 4C (Upgrade Key required)IS4_Large_PeripheralEye trackers marked inboldfont 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 callingTitta.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.APITittamoduleModule-level functionsThe below method can be called on the Titta module directly.CallInputsOutputsDescriptionget_defaults()et_name: one of the supported eye tracker model names,see abovesettings: object with all supported settings for a specific model of eyeTrackerGets all supported settings with defaulted values for the indicated eyeTracker, can be modified and used for constructing an instance of Titta. See thesupported optionssection below.ConstructionAn instance of Titta for interaction with the eye tracker (aTitta.MyTobiiinstance) is constructed by calling the module-level constructorTitta.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 fromTitta.get_defaults(), possibly with changed settings (passing the settings object unchanged is equivalent to using the eye tracker model name as input argument).Supported optionsTheget_defaults()method call returns the appropriate set of options for the indicated eye tracker.Option nameExplanationsettings.SAMPLING_RATESampling frequencyTobiimodulePropertiesThe following methods are available for an instance ofTobii.MyTobii(as created by callingTitta.Connect).PropertyDescriptionbufferInitialized by call toinit(). Returns handle to aTittaPy instancefor 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.MethodsThe following methods are available for an instance ofTobii.MyTobii(as created by callingTitta.Connect).CallInputsOutputsDescriptioninit()Connect to the Tobii eye tracker and initialize it according to the requested settings (provided optionally when callingTitta.Connect()).calibrate()win: PsychoPy window objectwin_operator: (optional) PsychoPy window object for the operator's screeneye: (optional) 'left', 'right' or 'both'. Default: 'both'.calibration_number: (optional) used to indicate if we need to wait for another calibration i.e. if 'first', then will not exit until 'second' calibration has finished. Default: 'second'Do participant setup, calibration and validation.start_recording()gaze: (optional) Default: false.time_sync: (optional) Default: false.eye_image: (optional) Default: false.notifications: (optional) Default: false.external_signal: (optional) Default: false.positioning: (optional) Default: false.Begin recording the specified kind of data. If none of the input parameters are set to true, then this method does nothing.stop_recording()gaze: (optional) Default: false.time_sync: (optional) Default: false.eye_image: (optional) Default: false.notifications: (optional) Default: false.external_signal: (optional) Default: false.positioning: (optional) Default: false.Stop recording the specified kind of data. If none of the input parameters are set to true, then this method does nothing.send_message()msg: Message to be written into data filets: (optional) timestamp of the message (in seconds, will be stored as microseconds)Store timestamped messagesave_data()filename: (optional) filename (including path) where HDF5 container will be storedappend_version: (optional) boolean indicating whether version numbers (_1,_2, etc) will automatically get appended to the filename if the destination file already exists. Default: TrueSave data to HDF5 container at specified locationcalibration_history()all_validation_results: a list, where each list entry contains the accuracy values in degrees from 0. left eye x, 1. left eye y, 2. right eye x, and 3. right eye y.  The last entry [4] tells whether the calibration was used (1) or not used (0).Get the calibration history thus far.system_info()A dictionary containing all the information included inTittaPy's properties, pluspython_version,psychopy_version,TittaPy_version, andtitta_version.Get information about the system and connected eye tracker.get_system_time_stamp()An int64 scalar denoting Tobii system time in microseconds.Get the current system time through the Tobii Pro SDK.set_sample_rate()Fs: the desired frequency valueSet the sampling rate of the connected eye tracker (if it is a supported frequency).get_sample_rate()frequency: the current frequency valueGet the sampling rate of the connected eye tracker.TittaPyclassThe TittaPy class can be used for interaction with the eye tracker's data streams. It is accessed viaTobii.MyTobii'sbufferproperty.  For instance, iftrackeris yourTobii.MyTobiiinstance, then you can retrieve the recorded samples usingtracker.buffer.consume_N(). The TittaPy methods and properties are documented in theTittaPy repository.TalkToProLabclassConstructionAn instance of TalkToProLab is constructed by callingTalkToProLab()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.MethodsThe following method calls are available on a TalkToProLab instance.  The majority of return types are theresponsedictionary, 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'.CallInputsOutputsDescriptionadd_participant()participant_name: name of the participantresponse, a dictionary containing:operation: "AddParticipant"status_codeparticipant_id: string: a unique ID for identifying the participant in the Pro Lab projectCreate a new participant in the Tobii Pro Lab project.find_participant()participant_name: name of the participantexists: a booleanFind whether a participant already exists in the Tobii Pro Lab project.list_participants()response, a dictionary containing:operation: "ListParticipants"status_codeA list of participants, with each entry being a dictionary containing:participant_name: a string: the name that was provided to Pro Lab for the participantparticipant_id: string: a unique ID for identifying the participant in the Pro Lab projectList all participants in the Tobii Pro Lab project.upload_media()media_name: name of the file to upload (including the file extension). Understood media types when a filename is provided arebmp,jpg,jpeg,png,gif,mp4andavimedia_type: 'image' or 'video'Upload media to the Tobii Pro Lab project.find_media()media_name: name of the media to find (case sensitive)exists: a boolean indicating whether the media existsFind media by name in the Tobii Pro Lab project.list_media()response, a dictionary containing:operation: "ListMedia"status_codeA list of media, with each entry being a dictionary containing:media_name: a string: the name that was provided to Pro Lab for the mediamedia_id: string: a unique ID for identifying the media in the Pro Lab projectmd5_checksum: (only present for some values) the hash value that can be used to verify the filemime_type: a string: the type of the media file, in the format "image" or "video" / file extension e.g. "image/jpeg"media_size: the size of the filewidthheightduration: 0 for imagesList all media in the Tobii Pro Lab project.add_aois_to_imagemedia_id: id of the media in Pro Lab to define an AOI foraoi_name: name of the AOIaoi_color: color in which to show the AOI in Pro Lab (RGB, 0-255)key_frame_vertices: 2xN matrix of vertices of the AOIkey_frame_active: (optional) Default: true.key_frame_seconds: (optional) Default: 0.tag_name: (optional) name of tag for identifying the AOI in Pro Lab. Default: empty string.group_name: (optional) the name of the tag group. Default: empty string.merge_mode: (optional) Default:replace_aois.response, a dictionary containing:operation: "sendAois"status_codeimported_aoi_countDefine an AOI for a specific media in the Pro Lab project.add_aois_to_videomedia_id: id of the media in Pro Lab to define an AOI foraoi_name: name of the AOIaoi_color: color in which to show the AOI in Pro Lab (RGB, 0-255)key_frame_vertices: 2xN matrix of vertices of the AOIkey_frame_active: (optional) Default: true.key_frame_seconds: (optional) Default: 0.tag_name: (optional) name of tag for identifying the AOI in Pro Lab. Default: empty string.group_name: (optional) the name of the tag group. Default: empty string.merge_mode: (optional) Default:replace_aois.response, a dictionary containing:operation: "sendAois"status_codeimported_aoi_countDefine an AOI for a specific media in the Pro Lab project.get_state()response, a dictionary containing:operation: "GetState"status_codestate: The current stateGet the state of the external presenter service in Pro Lab.start_recording()recording_name: name by which the recording will be identified in Pro Labparticipant_id: the ID (from Pro Lab) of the participant associated with this recordingscreen_width: width of the screen in pixelsscreen_height: height of the screen in pixelsscreen_latency: (optional) numeric value indicating delay between drawing commands being issued and the image actually appearing on the screen. Default: 10000.response, a dictionary containing:operation: "StartRecording"status_coderecording_id: A unique identifier for the new recordingTell Pro Lab to start a recording.stop_recording()Stop a currently ongoing recording of Tobii Pro Lab.finalize_recording()recording_id: the ID (from Pro Lab) of the recording that was just stoppedFinalize 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()recording_id: the ID (from Pro Lab) of the recordingstart_timestamp: timestamp (in seconds or microseconds) at which stimulus presentation started.end_timeStamp: (optional) timestamp (in seconds or microseconds) of when presentation of this stimulus ended. If empty, it is assumed stimulus remained on screen until start of the next stimulusmedia_id: unique identifier by which shown media stimulus is identified in Pro Labmedia_position: (optional) location of the stimulus on screen in pixels, format:[left top right bottom]background: (optional) color of background (RGB: 0-255) on top of which stimulus was shownInform Pro Lab when and where a media (stimulus) was shown.send_custom_event()recording_id: the ID (from Pro Lab) of the recordingtimestamp: (optional) timestamp (in s) at which event occured. If empty, current time is taken as event timeevent_type: string: event type namevalue: (optional) string, the value of the eventAdd an event to Pro Lab's timeline.disconnect()Disconnect from Tobii Pro Lab.