Eye-Tracking Calibration (Dwell)

Kind: eyetracking_calibration | Version: v1

The dwell-based eye-tracking calibration task presents 9 fixation points in randomized order. The participant follows each animated dot with their eyes while WebGazer records the camera + gaze association. After calibration completes an optional validation phase measures accuracy against a held-out centre point.

Overview

This task is an essential setup step for webcam-based eye-tracking studies using WebGazer. Calibration trains the model by associating camera frames with known screen positions. The post-calibration validation phase provides an unbiased accuracy estimate (the centre point is withheld from training), producing a calibration_validation_{taskIndex}.json artifact that the analysis pipeline uses to report accuracy_pct, mean_error_pct, and a quality_flag when accuracy falls below the configured threshold.

For studies where participants click each calibration point, see Eye-Tracking Calibration (Interaction).

Configuration Parameters

Calibration Options

Parameter	Default	Description
Iterations	1	How many full passes through the 9-point grid (max 10). More iterations = more training data.
Dwell per point (ms)	1000	How long each point is displayed before auto-advancing.
Inter-point pause (ms)	300	Blank gap between consecutive points.
Final pause (ms)	600	Brief pause after the last point before entering the validation phase (or completing, if validation is disabled).
Blink animation duration (ms)	1200	Duration of the chirp-blink animation on each dot. Should be ≤ dwell time.

Validation Phase Options

Parameter	Default	Description
Enable accuracy validation	Yes	Whether to run the post-calibration validation phase.
Settle gate (ms)	1000	How long to show the fixation cross before collecting samples, giving the participant time to find the centre point.
Sample count	30	Maximum number of gaze samples to collect.
Measure window (ms)	1500	Hard time limit on the measurement window (whichever of sample count or time limit fires first ends collection).
Acceptance radius (% diag.)	7	Radius within which a sample is counted as "within target", expressed as a percentage of the viewport diagonal.
Low-accuracy threshold (%)	60	When accuracy_pct falls below this value the artifact carries quality_flag: "low_accuracy".
Validation invite text	(default)	Optional HTML shown on the invite screen before the fixation cross appears. Leave blank for the translated default ("Look at the centre of the screen and keep still.").

Participant Experience

1. Instructions screen — the researcher's main_instructions text is shown. The participant clicks Start (or the moderator advances in strictly controlled mode).
2. Calibration — an animated dot appears at each position in the 9-point grid in randomized order. The participant follows each dot with their eyes. Dots auto-advance after the configured dwell time.
3. Validation invite (if enabled) — a brief screen asks the participant to look at the centre of the screen.
4. Validation fixation — a crosshair appears at the viewport centre; the participant holds their gaze there during the settle gate.
5. Validation measurement — a small red dot overlays the fixation cross; WebGazer gaze predictions are sampled at ~20 Hz for up to sample_count samples or measure_ms, whichever comes first.
6. Task ends — control passes to the next task in the pipeline.

Data Output

Markers

The task emits the following markers in the participation log:

Calibration phase:

Marker	Data Fields	Description
point_shown	pos, index, target_x_pct, target_y_pct	Emitted each time a calibration dot is displayed

Validation phase (when validation_enabled is true):

Marker	Data Fields	Description
validation_invite_shown	target_x_pct, target_y_pct	Invite screen shown to participant
validation_settle_start	settle_ms, target_x_pct, target_y_pct	Fixation cross displayed; settle gate started
validation_settle_complete	target_x_pct, target_y_pct	Settle gate elapsed; emitted together with validation_point_shown
validation_point_shown	target_x_pct, target_y_pct, sample_count_target, measure_ms	Measurement window opened
validation_complete	target_x_pct, target_y_pct, sample_count, acceptance_radius_pct, accuracy_pct, mean_error_pct, median_error_pct, below_threshold, accuracy_threshold_pct, sample_errors_pct	Measurement window closed; full result

The validation_complete marker carries all scalar accuracy metrics and the full sample_errors_pct array so that the event log is self-contained for timeline analysis.

Response Records

One response record is written per calibration point (after its dwell window elapses):

Field	Type	Description
pos	string	Grid position key (e.g. "top_left", "middle_middle")
index	number	Sequential position in the calibration sequence (0-based)
target_x_pct	number	Horizontal target position as % of viewport width
target_y_pct	number	Vertical target position as % of viewport height
dwell_ms	number	Configured dwell window used for this point

The validation phase does not emit response records; its results are in the validation_complete marker and the JSON artifact.

Validation Artifact

When validation is enabled the task emits calibration_validation_{taskIndex}.json:

{
  "kind": "calibration_validation",
  "task_index": 0,
  "target_x_pct": 50,
  "target_y_pct": 52,
  "sample_count": 28,
  "acceptance_radius_pct": 7,
  "accuracy_pct": 78.6,
  "mean_error_pct": 5.2,
  "median_error_pct": 4.8,
  "samples": [
    { "error_pct": 4.1 },
    { "error_pct": 6.3 }
  ],
  "quality_flag": null,
  "below_threshold": false,
  "accuracy_threshold_pct": 60
}

All error_pct values are Euclidean distance from the centre target expressed as a percentage of the viewport diagonal, making them resolution-independent. quality_flag is "low_accuracy" when accuracy_pct < accuracy_threshold_pct, otherwise null.

The analysis pipeline surfaces this artifact under eye_gaze.summary.validation.

Calibration Grid

The 9 points map onto a safe-area inset that clears browser chrome (top 12 %, sides and bottom 8 %). The validation point is always the grid centre (middle_middle, 50 % / 52 %):

Position	Left %	Top %
top_left	8	12
top_middle	50	12
top_right	92	12
middle_left	8	52
middle_middle (centre)	50	52
middle_right	92	52
bottom_left	8	92
bottom_middle	50	92
bottom_right	92	92

Design Recommendations

• Lighting: Even, frontal lighting avoids shadows that confuse the face detector.
• Distance: 50–70 cm from the screen (arm's length).
• Head stability: Remind participants to keep their head still. Head movement is the primary source of calibration error with webcam-based tracking.
• Iterations: One iteration (9 points) is sufficient for most studies. Use 2–3 iterations for tasks requiring higher gaze precision.
• Validation threshold: The default 60 % accuracy threshold at 7 % diagonal radius is a conservative gate. Raise the threshold for precision-critical tasks.

References

• Papoutsaki, A., Sangkloy, P., Laskey, J., Daskalova, N., Huang, J., & Hays, J. (2016). WebGazer: Scalable webcam eye tracking using user interactions. IJCAI 2016 (pp. 3839–3845).
• Semmelmann, K., & Weigelt, S. (2018). Online webcam-based eye tracking in cognitive science: A first look. Behavior Research Methods, 50(2), 451–465.

See Also

• Eye-Tracking Calibration (Interaction) — click-to-advance variant