ETracker.start_recording

ETracker.start_recording(
    filename=None,
    raw_format=False,
    coordinate_units='default',
    relative_timestamps='default',
)

Begin gaze data recording session.

Initializes file structure, clears any existing buffers, and starts data collection from either the eye tracker or simulation mode. Creates HDF5 or CSV files based on filename extension.

Parameters

Name Type Description Default
filename str Output filename for gaze data. If None, generates timestamp-based name. File extension determines format (.h5/.hdf5 for HDF5, .csv for CSV, defaults to .h5). None
raw_format bool If True, preserves all original Tobii SDK column names and data (including 3D eye positions, gaze origins, etc.). If False (default), uses simplified column names and subset of columns (gaze positions, pupil diameters, validity flags only). See Data Format Options for more information. False
coordinate_units str

Target coordinate system for 2D screen positions. Default is ‘default’:

  • ‘default’: Smart defaults based on format
    • raw_format=True → ‘tobii’ (keeps 0-1 range)
    • raw_format=False → ‘pix’ (PsychoPy pixels, center origin)

Converts to PsychoPy coordinate systems where (0,0) is at screen center. Other options: ‘tobii’, ‘height’, ‘norm’, ‘cm’, ‘deg’. See Coordinate System Conversion for more information.

 'default'
relative_timestamps str or bool

Controls timestamp format. Default is ‘default’:

  • ‘default’: Smart defaults based on format
    • raw_format=True → False (absolute microseconds)
    • raw_format=False → True (relative milliseconds from 0)

Other options: True (always relative), False (always absolute). See Timestamp Format for more information.

 'default'

Details

Data Format Options

The raw_format parameter controls which columns are included in the saved data file. Raw format preserves the complete data structure from the Tobii Pro SDK, which includes both 2D screen coordinates and 3D spatial information about eye position and gaze origin in the user coordinate system. This format is useful for advanced analyses that require the full geometric relationship between the eyes and the screen, or when you need to preserve all metadata provided by the eye tracker. The simplified format extracts only the essential data needed for most eye tracking analyses: gaze positions on screen, pupil diameters, and validity flags. This results in smaller files and easier data analysis for typical gaze visualization and AOI (Area of Interest) tasks.

Coordinate System Conversion

The coordinate_units parameter determines how 2D screen coordinates are represented in the output file. By default, raw format keeps coordinates in Tobii’s Active Display Coordinate System (ADCS) where values range from 0 to 1 with the origin at the top-left corner. This normalized system is screen-independent and useful for comparing data across different display setups. The simplified format defaults to PsychoPy pixel coordinates, which place the origin at the screen center with the y-axis pointing upward. This matches PsychoPy’s coordinate system and makes it seamless to overlay gaze data on your experimental stimuli. You can override these defaults for either format. For example, you might want pixel coordinates in raw format for easier visualization, or keep Tobii coordinates in simplified format for cross-screen comparisons. When converting to other PsychoPy units like ‘height’ or ‘norm’, the coordinates will match your PsychoPy window’s unit system. Note that in raw format, only the 2D display coordinates are converted; the 3D spatial coordinates (eye positions and gaze origins) always remain in meters as provided by the Tobii SDK.

Timestamp Format

The relative_timestamps parameter controls how time is represented in your data. Absolute timestamps preserve the exact microsecond values from the Tobii system clock, which are useful when you need to synchronize eye tracking data with other recording systems or when collecting multiple data files that need to be aligned temporally. Relative timestamps convert the first sample to time zero and express all subsequent times in milliseconds relative to that starting point, making it much easier to analyze individual trials or sessions. For example, with relative timestamps you can immediately see that an event occurred at 1500ms into your recording, whereas with absolute timestamps you would need to subtract the session start time first. The default behavior chooses relative timestamps for simplified format (since most analyses focus on within-session timing) and absolute timestamps for raw format (to preserve the complete temporal information). Both gaze samples and event markers use the same timestamp format to ensure proper synchronization when analyzing your data.

Examples

Basic Usage

Standard simplified format (PsychoPy pixels, relative timestamps)

ET_controller.start_recording('data.h5')
# Creates: Left_X/Left_Y in pixels (center origin), TimeStamp from 0ms

Auto-generated timestamped filename

ET_controller.start_recording()  # Creates YYYY-MM-DD_HH-MM-SS.h5

Format Options

Raw format with defaults (Tobii coords, absolute timestamps)

ET_controller.start_recording('data.h5', raw_format=True)
# All Tobii columns, coords in 0-1 range, timestamps in microseconds

Raw format with pixel coordinates

ET_controller.start_recording('data.h5', raw_format=True, coordinate_units='pix')
# All Tobii columns, display coords in PsychoPy pixels

Timestamp Control

Raw format with relative timestamps

ET_controller.start_recording('data.h5', raw_format=True, relative_timestamps=True)
# Raw format but timestamps start at 0ms

Simplified format with absolute timestamps

ET_controller.start_recording('data.h5', relative_timestamps=False)
# Simplified format but keeps absolute microsecond timestamps

Coordinate Units

Simplified format with Tobii coordinates

ET_controller.start_recording('data.h5', coordinate_units='tobii')
# Simplified columns, coordinates in 0-1 range

Simplified format with height units

ET_controller.start_recording('data.h5', coordinate_units='height')
# Simplified columns, coordinates in height units matching window

Complete Workflows

Standard experiment workflow

# Setup and calibration
ET_controller.show_status()
ET_controller.calibrate(5)

# Start recording with defaults
ET_controller.start_recording('participant_01.h5')

# Run experiment with event markers
ET_controller.record_event('trial_1_start')
# ... present stimuli ...
ET_controller.record_event('trial_1_end')

# Stop recording
ET_controller.stop_recording()

Multi-file synchronization with absolute timestamps

# Recording multiple synchronized files
ET_controller.start_recording('session1_gaze.h5', relative_timestamps=False)
# ... run session 1 ...
ET_controller.stop_recording()

# Session 2 can be synchronized using absolute timestamps
ET_controller.start_recording('session2_gaze.h5', relative_timestamps=False)
# ... run session 2 ...
ET_controller.stop_recording()

Advanced raw data collection

# Collect all data with pixel coords and relative time
ET_controller.start_recording(
    'advanced_analysis.h5',
    raw_format=True,
    coordinate_units='pix',
    relative_timestamps=True
)
Back to top