Commandline Usage

Overview

tobii-pytracker is a Python command-line tool for running eye-tracking experiments or continuous gaze recording using Tobii eye-trackers. The tool supports:

  • Displaying stimuli via PsychoPy GUI

  • Recording gaze positions and pupil sizes

  • Recording full raw Tobii samples

  • Voice recording

  • Integration with custom models for predictions

Installation

Install the tool via pip:

pip install tobii-pytracker

After installation, the tobii-pytracker script is available on your PATH.

Command-Line Usage

Run the tool with:

tobii-pytracker [OPTIONS]

General Options

The following command-line options are available:

  • --config_file Path to the YAML configuration file for the experiment (default: configs/config.yaml).

  • --eyetracker_config_file Path to the YAML configuration file for the Tobii eye-tracker (default: configs/eyetracker_config.yaml).

Boolean Flags

  • --enable_eyetracker Launches the Tobii eye-tracker using PsychoPy ioHub. Requires a connected device.

  • --enable_voice Records voice during trials.

  • --raw_data Records full Tobii raw samples instead of filtered gaze coordinates.

  • --disable_psychopy Runs the tool in headless mode. No PsychoPy GUI is displayed. Continuous recording of raw gaze and/or voice occurs until the process is terminated.

Other Options

  • --loop_count Number of trials or data items to display before exiting (default: 10).

  • --log_level Logging level: info, debug, warning, error, critical (default: info).

Example Usage

  1. Run a GUI experiment without eye-tracker just to test the stimuli display:

tobii-pytracker

  1. Run a GUI experiment with eye-tracker, and voice recording:

tobii-pytracker --enable_eyetracker --enable_voice

  1. Run a headless session recording raw gaze data continuously:

tobii-pytracker --enable_eyetracker --raw_data --disable_psychopy

  1. Run only voice recording with GUI disabled:

tobii-pytracker --enable_voice --disable_psychopy

  1. Run GUI experiment with mouse eyetracker emulation:

tobii-pytracker --eyetracker_config_file ./configs/mouse_eyetracker_config.yaml --enable_eyetracker

File Output

Depending on mode:

  • PsychoPy mode (`enable_psychopy=True`):

    • data.csv – contains trial-specific information:

      • screenshot_file – path to captured screenshot

      • input_data – data for trial

      • classification – ground truth label

      • user_classification – user-selected label

      • gaze_data – gaze positions or raw samples

      • objects_bboxes – prediction from custom model

      • voice_file – recorded voice filename

      • voice_start_timestamp – timestamp of voice recording start

  • Headless mode (`disable_psychopy=True`):

    • raw_stream.csv – contains timestamped raw Tobii samples.

    • voice_file.wav – if voice recording enabled.

Notes

  • Headless mode is ideal for continuous monitoring or offline data collection.

  • PsychoPy GUI mode allows interactive experiments with user responses.

  • Voice recording is threaded and synchronized with gaze sampling.