@jspsych/plugin-tobii-calibration

jsPsych plugin for Tobii eye tracker calibration. Provides a visual calibration procedure with animated points, multiple grid sizes, and real-time feedback.

Installation

npm install @jspsych/plugin-tobii-calibration

Compatibility

This plugin requires jsPsych v8.0.0 or later and the @jspsych/extension-tobii extension.

Usage

import TobiiCalibrationPlugin from '@jspsych/plugin-tobii-calibration';

const trial = {
  type: TobiiCalibrationPlugin,
  calibration_points: 9,
  calibration_mode: 'view',
};

The Tobii extension must be loaded and connected before this plugin runs. See the extension documentation for setup instructions.

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | calibration_points | int | 9 | Number of calibration points. Supported values: 5, 9, 13, 15, 19, 25. | | calibration_mode | string | 'view' | Calibration mode. 'view': participant looks at each point for a fixed duration. 'click': participant clicks when ready at each point. | | point_size | int | 20 | Size of calibration points in pixels. | | point_color | string | '#ff0000' | Color of calibration points (CSS color value). | | point_duration | int | 500 | Duration to show each point before data collection begins (ms). Allows the participant to fixate. | | show_progress | boolean | true | Show a progress indicator (e.g., "Point 3 of 9"). | | custom_points | array | null | Array of custom calibration points. Each point is an object with x and y properties (normalized 0-1). Overrides calibration_points when provided. | | instructions | string | 'Look at each point as it appears on the screen. Keep your gaze fixed on each point until it disappears.' | Instructions text shown before calibration begins. | | button_text | string | 'Start Calibration' | Button text shown on the instructions screen before calibration begins. | | background_color | string | '#808080' | Background color of the calibration container. | | button_color | string | '#007bff' | Primary button color. | | button_hover_color | string | '#0056b3' | Primary button hover color. | | retry_button_color | string | '#dc3545' | Retry button color. | | retry_button_hover_color | string | '#c82333' | Retry button hover color. | | success_color | string | '#28a745' | Success message heading color. | | error_color | string | '#dc3545' | Error message heading color. | | max_retries | int | 1 | Maximum number of retry attempts allowed if calibration fails. The participant is shown a retry button on failure. Set to 0 to disable retries. | | zoom_duration | int | 300 | Duration of zoom in/out point animations in ms. | | explosion_duration | int | 400 | Duration of the explosion animation after each point is collected in ms. | | success_display_duration | int | 2000 | Duration to show the success result before auto-advancing in ms. | | instruction_display_duration | int | 3000 | Duration to show instructions before auto-advancing in view mode in ms. Has no effect in click mode. |

Data Generated

In addition to the default data collected by jsPsych plugins, this plugin collects the following data for each trial.

| Name | Type | Description | |------|------|-------------| | calibration_success | boolean | Whether the calibration was successful. | | num_points | int | Number of calibration points used. | | mode | string | Calibration mode used ('view' or 'click'). | | calibration_data | object | Full calibration result data returned by the server, including any quality metrics. | | num_attempts | int | Number of calibration attempts made (including retries). |

Calibration Point Grids

The calibration_points parameter supports these grid sizes:

• 5: Four corners + center
• 9: 3x3 grid (recommended default)
• 13: 3x3 outer grid + 4 diagonal midpoints
• 15: 5 rows x 3 columns
• 19: Symmetric 3-5-3-5-3 pattern
• 25: 5x5 full grid

All standard grids use points spanning from 0.1 to 0.9 in normalized coordinates, keeping a 10% margin from screen edges.

Examples

Basic 9-Point Calibration

const trial = {
  type: TobiiCalibrationPlugin,
  calibration_points: 9,
  calibration_mode: 'view',
};

Click Mode with Custom Styling

const trial = {
  type: TobiiCalibrationPlugin,
  calibration_points: 9,
  calibration_mode: 'click',
  point_color: '#0000ff',
  point_size: 25,
  background_color: '#333333',
  button_text: 'Begin Calibration',
};

Custom Points

const trial = {
  type: TobiiCalibrationPlugin,
  custom_points: [
    { x: 0.15, y: 0.15 },
    { x: 0.5, y: 0.15 },
    { x: 0.85, y: 0.15 },
    { x: 0.15, y: 0.5 },
    { x: 0.5, y: 0.5 },
    { x: 0.85, y: 0.5 },
    { x: 0.15, y: 0.85 },
    { x: 0.5, y: 0.85 },
    { x: 0.85, y: 0.85 },
  ],
};

With Retries Disabled

const trial = {
  type: TobiiCalibrationPlugin,
  calibration_points: 9,
  max_retries: 0,
};

Citation

If you use this plugin in your research, please cite it. See CITATION.cff.