npm package: @jspsych/plugin-tobii-calibration
Description: jsPsych plugin for Tobii eye tracker calibration
Author: Josh de Leeuw
Latest version: 0.2.1

# @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

```bash
npm install @jspsych/plugin-tobii-calibration
```

## Compatibility

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

## Usage

```javascript
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](../extension-tobii/README.md) 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](https://www.jspsych.org/latest/overview/plugins/#data-collected-by-all-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

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

### Click Mode with Custom Styling

```javascript
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

```javascript
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

```javascript
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](CITATION.cff).