py-smite 1.0.0

SMITE is a toolbox for using eye trackers from SMI with Python, specifically offering integration with PsychoPy.

SMITE is a toolbox for using eye trackers from SMI GmbH with Python, specifically offering integration with PsychoPy. A Matlab version that integrates with Psychtoolbox is also available from https://github.com/dcnieho/SMITE

Cite as: Niehorster, D.C., & Nyström, M., (2019). SMITE: A toolbox for creating Psychtoolbox and Psychopy experiments with SMI eye trackers. doi: 10.3758/s13428-019-01226-0.

For questions, bug reports or to check for updates, please visit www.github.com/marcus-nystrom/SMITE.

SMITE is licensed under the Creative Commons Attribution 4.0 (CC BY 4.0) license.

demos/read_me.py shows a minimal example of using the toolbox's functionality.

Tested on Windows using PsychoPy with Python 2.7. Also tested with PsychoPy3 (Python 3.6, but see issues below)

To get started

If you know what you are doing, install SMITE using: pip install py-smite or python -m pip install py-smite.

If you use a standalone PsychoPy installation, do the following steps:

1. Go to C:\Program Files\PsychoPy (or wherever you installed PsychoPy) and open a command prompt in the same folder as where you find python.exe (should be the main PsychoPy install folder). So the command prompt you have should start with something like C:\Program Files\PsychoPy>
2. Here you can then pip-install py-smite, by issuing a command like python -m pip install py-smite --upgrade.

Then run read_me.py from the 'examples' folder. Reading through read_me.py should provide a good starting point for most users of SMITE.

Usage

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

1. retrieve (default) settings for eye tracker of interest: settings = SMITE.get_defaults('trackerName'); Supported tracker Names are HiSpeed, RED, REDm, RED250mobile, REDn_Scientific, and REDn_Professional.
2. edit settings if wanted
3. initialize SMITE using this settings struct: `EThndl = SMITE(settings)

API

Methods

The following method calls are available on a SMITE instance

Call	inputs	outputs	description
get_options()		settings: module with current settings	Get settings
init()			Connect to the SMI eye tracker and initialize it according to the requested settings
is_connected()		status: SMI status code (int). For its meaning, see the iView API documentation.	Report status of the connection to the eye tracker
calibrate()	win: window pointer to PsychoPy screen where the calibration stimulus should be shown. See visual.Window()		Do participant setup, calibration and validation
start_recording()	clear_buffer: optional. Boolean indicating whether the IDF file buffer should be cleared before recording starts or not. This clears all already recorded data from the idf file, so set to true with caution		Start recording eye-movement data to idf file
start_buffer()	sample_buffer_length: optional. Size in number of samples of recording buffer.		Start recording eye-movement data into buffer for online use
send_message()	msg: Message to be written into idf file		Insert message into idf file
get_latest_sample()		sample:struct array	Get most recent data sample
consume_buffer_data()		list of samples	Get data from the online buffer. The returned samples are removed from the buffer
peek_buffer_data()		list of samples	Get data from the online buffer. The returned samples remain in the buffer
stop_buffer()	clear_buffer: optional. Boolean indicating whether the online buffer should be cleared		Stop recording data into buffer
stop_recording()			Stop recording data into idf file
save_data()	filename: filename (including path) where idf file will be stored user: optional. Indentifier that gets placed in idf file header description: optional. Description that gets placed in idf file header append_version: optional. Boolean indicating whether version numbers (_1, _2, etc) will automatically get appended to the filename if the destination file already exists		Save idf file to specified location
de_init()	close: optional. Boolean indicating whether the iView eye tracker server should be shut down		Close connection to the eye tracker and clean up
set_begaze_trial_image()	filename: filename of stimulus that is shown on this trial. Must have one of the following extentions: .png, .jpg, .jpeg, .bmp, or .avi		Put specially prepared message in idf file to notify BeGaze what stimulus image/video belongs to a trial
set_begaze_key_press()	string: string that will show up on BeGaze's event timeline. Can be name of a key, but also other arbitrary string		Put specially prepared message in idf file that shows up as keypress in BeGaze
set_begaze_mouse_click()	which: string indicating which mouse button, left or right x: horizontal pixel coordinate of mouse click y: vertical coordinate of mouse click		Put specially prepared message in idf file that shows up as mouse click in BeGaze
start_eye_image_recording()	filename: filename where recorded eye images will be saved format: format to store eye images in, must be one of: jpg, bmp, xvid, huffyuv, alpary, xmp4 duration: optional. If provided, runs eye image recording for this many seconds		Start recording eye images to file. Not supported on RED250mobile, REDn Scientific, and REDn Professional
stop_eye_image_recording()			Stop recording eye images to file
set_dummy_mode()			Enable dummy mode, which allows running the program without an eye tracker connected

ToDos (current discrepancies between the paper and the toolbox):

1. File transfer in two computer setups not implemented
2. do_flip_eye not implemented (fixes a bug in older versions of iViewX, e.g., v. 2.7.13, where left and right eyes are flipped)
3. get_options returns all settings. set_options does nothing. This means that it's currently up to the user not to use functionally that is not available during recording (for instance changing the sampling frequency of the eye tracker).
4. Images returned from the API look strange when using PsychoPy3. Affects validation screen and eye images.