Calibration

Calibration backend factory and auto-detection.

This module provides the factory function for creating calibration display objects with automatic backend detection based on installed packages and Python version.

IMPORTANT: Backend imports are LAZY to avoid conflicts between psychopy/pyglet.

pyelink.calibration.create_calibration(settings, tracker, mode='normal')[source]

Factory function to create calibration display.

Uses the tracker’s internal window (created based on settings.backend). The calibration display accesses the window via tracker.display.window.

Parameters:

settings (object) – Settings object with configuration (includes BACKEND setting)
tracker (object) – EyeLink tracker instance (with display.window)
mode (str) – Calibration mode - “normal”, “calibration-only”, or “validation-only”

Return type:

object

Returns:

CalibrationDisplay instance using tracker’s internal window

Example

>>> import pyelink as el
>>>
>>> # Configure tracker with backend
>>> settings = el.Settings(BACKEND='pygame', FULLSCREEN=True)
>>> tracker = el.EyeLink(settings)  # Creates window automatically
>>>
>>> # Create calibration (uses tracker's window)
>>> calibration = el.create_calibration(settings, tracker)
>>>
>>> # Calibrate
>>> tracker.calibrate(calibration)
>>>
>>> # Use tracker's window for experiment
>>> tracker.window.fill((128, 128, 128))
>>> tracker.flip()

Note

The calibration uses the tracker’s owned window. No separate window management needed - tracker handles window lifecycle.

pyelink.calibration.get_available_backends()[source]

Get dictionary of currently available (installed) backends.

Return type:: dict[str, object]
Returns:: Dict mapping backend name to class

pyelink.calibration.get_backend(name=None)[source]

Get calibration backend by name or auto-detect.

Parameters:

name (str | None) – Backend name (‘pygame’, ‘psychopy’, ‘pyglet’) or None for auto-detect

Return type:

object

Returns:

CalibrationDisplay class

Raises:

ImportError – If no backends available
RuntimeError – If Python version incompatible with requested backend
ValueError – If requested backend not available

Base Calibration Display

Abstract base class for calibration display backends.

This module defines the interface that all calibration backends must implement. Backends provide visualization during tracker calibration and validation.

class pyelink.calibration.base.CalibrationDisplay(settings, tracker, mode='normal')[source]

Bases: EyeLinkCustomDisplay, ABC

Abstract base class for EyeLink calibration displays.

All backend implementations must inherit from this class and implement the required abstract methods. This class defines the interface for drawing calibration targets, handling input, and displaying the eye camera view.

Parameters:

settings (object)
tracker (object)
mode (str)

__init__(settings, tracker, mode='normal')[source]

Initialize calibration display.

Parameters:

settings (object) – Settings object with configuration
tracker (object) – EyeLink tracker instance
mode (str) – Calibration mode - “normal”, “calibration-only”, or “validation-only”

Return type:

None

set_tracker(tracker)[source]

Configure tracker for calibration.

Parameters:: tracker (object) – EyeLinkDevice instance
Return type:: None

abstractmethod setup_cal_display()[source]

Initialize calibration display.

Called when entering calibration mode. Should clear the display and show any initial instructions or setup.

Return type:: None

abstractmethod exit_cal_display()[source]

Clean up calibration display.

Called when exiting calibration mode.

Return type:: None

abstractmethod clear_cal_display()[source]

Clear the calibration display.

Typically called between calibration points.

Return type:: None

abstractmethod draw_cal_target(x, y)[source]

Draw calibration target at position (x, y).

Parameters:

x (float) – X coordinate in EyeLink screen coordinates (top-left origin)
y (float) – Y coordinate in EyeLink screen coordinates (top-left origin)

Return type:

None

Note

Coordinates are in EyeLink space (top-left origin, positive Y down). Backends must convert to their native coordinate system.

Backend implementations should call _log_target_drawn(x, y) after the display has been updated, so that an EDF message is emitted when settings.log_calibration_target_messages is True.

abstractmethod erase_cal_target()[source]

Remove calibration target from display.

Called after participant has fixated the target.

Return type:: None

abstractmethod setup_image_display(width, height)[source]

Initialize camera image display.

Called before displaying the eye camera feed.

Parameters:

width (int) – Image width in pixels
height (int) – Image height in pixels

Return type:

None

image_title(text)[source]

Display title/info text on camera view.

Parameters:: text (str) – Text to display (typically pupil/CR information)
Return type:: None

getColorFromIndex(colorindex)[source]

Map pylink color constants to RGB tuples.

Parameters:: colorindex (int) – Pylink color constant
Returns:: (R, G, B) values in range 0-255
Return type:: tuple[int, int, int]

set_image_palette(r, g, b)[source]

Set color palette for camera image.

Parameters:

r (object) – Red channel values (list/array)
g (object) – Green channel values (list/array)
b (object) – Blue channel values (list/array)

Return type:

None

draw_image_line_base(width, line, totlines, buff)[source]

The EyeLink sends the camera image line-by-line. This method receives each line and accumulates them.

When line == totlines, the complete image is ready and overlays (crosshairs, etc.) are drawn.

Parameters:

width (int) – Width of the image line
line (int) – Current line number (1-indexed)
totlines (int) – Total number of lines in the image
buff (object) – Buffer containing pixel data for this line

Returns:

(image, imgstim_size) if all lines received, else (None, None)

Return type:

tuple

abstractmethod exit_image_display()[source]

Clean up camera image display.

Return type:: None

abstractmethod draw_line(x1, y1, x2, y2, colorindex)[source]

Draw line on camera view.

Called by EyeLink to draw crosshairs on pupil and corneal reflection. Backends should draw using their native drawing API for best performance.

Parameters:

x1 (float) – X coordinate of start point
y1 (float) – Y coordinate of start point
x2 (float) – X coordinate of end point
y2 (float) – Y coordinate of end point
colorindex (int) – Pylink color constant

Return type:

None

abstractmethod draw_lozenge(x, y, width, height, colorindex)[source]

Draw rectangle on camera view.

Called by EyeLink to draw pupil box and search limits. Backends should draw using their native drawing API for best performance.

Parameters:

x (float) – X coordinate of top-left corner
y (float) – Y coordinate of top-left corner
width (float) – Width of lozenge
height (float) – Height of lozenge
colorindex (int) – Pylink color constant

Return type:

None

abstractmethod get_input_key()[source]

Get keyboard input and return list of pylink.KeyInput objects.

Should poll for keyboard events and convert them to EyeLink key codes.

Commonly used keys:

Escape: pylink.ESC_KEY
Enter/Return: pylink.ENTER_KEY
Space: ord(’ ‘)
Arrow keys: pylink.CURS_UP, pylink.CURS_DOWN, pylink.CURS_LEFT, pylink.CURS_RIGHT
Page Up/Down: pylink.PAGE_UP, pylink.PAGE_DOWN
‘c’: calibrate
‘v’: validate
‘a’: auto threshold

Returns:: List of pylink.KeyInput objects, or empty list if no input
Return type:: list

abstractmethod get_mouse_state()[source]

Get mouse position and button state.

Returns:

((x, y), button_state) or None if not implemented

(x, y): Mouse position in EyeLink coordinates
button_state: 1 if button pressed, 0 otherwise

Return type:

tuple | None

static play_beep(beepid)[source]

Play audio beep for calibration feedback.

Parameters:: beepid (int) – Beep type constant from pylink: - pylink.CAL_TARG_BEEP / pylink.DC_TARG_BEEP: Target appears - pylink.CAL_GOOD_BEEP / pylink.DC_GOOD_BEEP: Calibration point accepted - pylink.CAL_ERR_BEEP / pylink.DC_ERR_BEEP: Calibration point failed
Return type:: None

static alert_printf(msg)[source]

Display alert message.

Parameters:: msg (str) – Alert message to display
Return type:: None

record_abort_hide()[source]

Handle recording abort.

Return type:: None

Calibration Targets

Calibration target generation.

This module provides functions to generate calibration targets. Supports scientific fixation targets (Thaler et al., 2013) and basic circle targets.

Target Types:

“A”: Center dot only
“B”: Outer ring only
“C”: Cross only
“AB”: Center dot + outer ring
“ABC”: Center dot + outer ring + cross (recommended)
“CIRCLE”: Basic concentric circles (pixel-based sizes)

pyelink.calibration.targets.generate_target(settings, target_type=None)[source]

Generate a calibration target image.

Parameters:

settings (object) – Settings object with screen configuration.
target_type (str | None) – Override for settings.target_type. One of: “A”, “B”, “C”, “AB”, “ABC”, “CIRCLE”, or “IMAGE”

Returns:

RGBA image of the target with transparent background.

Return type:

Image

Raises:

ValueError – If target_type is invalid or IMAGE path not provided.
FileNotFoundError – If IMAGE path doesn’t exist.

Pygame Backend

Pygame backend for EyeLink calibration display.

This module provides Pygame-based visualization for EyeLink calibration and validation.

class pyelink.calibration.pygame_backend.PygameCalibrationDisplay(settings, tracker, mode='normal')[source]

Bases: CalibrationDisplay

Pygame implementation of EyeLink calibration display.

Parameters:

settings (object)
tracker (object)
mode (str)

__init__(settings, tracker, mode='normal')[source]

Initialize pygame calibration display.

Parameters:

settings (object) – Settings object with configuration
tracker (object) – EyeLink tracker instance (with display.window attribute)
mode (str) – Calibration mode - “normal”, “calibration-only”, or “validation-only”

Return type:

None

setup_cal_display()[source]

Initialize calibration display with instructions.

Return type:: None

exit_cal_display()[source]

Clean up calibration display.

Return type:: None

close_window()[source]

Close the pygame window.

Note

Must be instance method to match CalibrationDisplay interface.

Return type:: None

clear_cal_display()[source]

Clear calibration display.

Return type:: None

erase_cal_target()[source]

Remove calibration target from display.

Return type:: None

draw_cal_target(x, y)[source]

Draw calibration target at position (x, y).

Parameters:

x (float) – X coordinate in EyeLink coordinates (top-left origin)
y (float) – Y coordinate in EyeLink coordinates (top-left origin)

Return type:

None

get_input_key()[source]

Get keyboard input and convert to pylink key codes.

Filters ‘c’ and ‘v’ keys based on calibration mode: - “normal”: both ‘c’ and ‘v’ enabled - “calibration-only”: only ‘c’ enabled, ‘v’ disabled - “validation-only”: only ‘v’ enabled, ‘c’ disabled

Note

Must be instance method to match CalibrationDisplay interface.

Returns:: List of pylink.KeyInput objects
Return type:: list

setup_image_display(width, height)[source]

Initialize camera image display.

Parameters:

width (int) – Image width in pixels
height (int) – Image height in pixels

Return type:

None

draw_image_line(width, line, totlines, buff)[source]

Draw camera image line by line.

The EyeLink sends the camera image line-by-line. This method receives each line and accumulates them. When line == totlines, the complete image is ready and overlays (crosshairs, etc.) are drawn. Uses base class for accumulation and overlays, then displays using pygame.

Parameters:

width (int) – Width of the image line
line (int) – Current line number (1-indexed)
totlines (int) – Total number of lines in the image
buff (object) – Buffer containing pixel data for this line

Return type:

None

exit_image_display()[source]

Clean up camera image display.

Return type:: None

static get_mouse_state()[source]

Get mouse position and button state.

Returns:: ((x, y), button_state) or None
Return type:: tuple | None

draw_line(x1, y1, x2, y2, colorindex)[source]

Draw line on camera image.

Parameters:

x1 (float) – X coordinate of start point
y1 (float) – Y coordinate of start point
x2 (float) – X coordinate of end point
y2 (float) – Y coordinate of end point
colorindex (int) – Pylink color constant

Return type:

None

draw_lozenge(x, y, width, height, colorindex)[source]

Draw rectangle on camera image.

Parameters:

x (float) – X coordinate of top-left corner
y (float) – Y coordinate of top-left corner
width (float) – Width of rectangle
height (float) – Height of rectangle
colorindex (int) – Pylink color constant

Return type:

None

dummynote()[source]

Display message for dummy mode (no hardware connection).

Return type:: None

PsychoPy Backend

PsychoPy backend for EyeLink calibration display.

This module provides PsychoPy-based visualization for EyeLink calibration and validation.

class pyelink.calibration.psychopy_backend.PsychopyCalibrationDisplay(settings, tracker, mode='normal')[source]

Bases: CalibrationDisplay

PsychoPy implementation of EyeLink calibration display.

Parameters:

settings (object)
tracker (object)
mode (str)

__init__(settings, tracker, mode='normal')[source]

Initialize PsychoPy calibration display.

Parameters:

settings (object) – Settings object with configuration
tracker (object) – EyeLink tracker instance (with display.window attribute)
mode (str) – Calibration mode - “normal”, “calibration-only”, or “validation-only”

Return type:

None

setup_cal_display()[source]

Initialize calibration display with instructions.

Return type:: None

exit_cal_display()[source]

Clean up calibration display and restore original window color.

Return type:: None

close_window()[source]

Close the psychopy window.

Return type:: None

clear_cal_display()[source]

Clear calibration display.

Return type:: None

erase_cal_target()[source]

Remove calibration target from display.

Return type:: None

draw_cal_target(x, y)[source]

Draw calibration target at position (x, y).

Parameters:

x (float) – X coordinate in EyeLink coordinates (top-left origin)
y (float) – Y coordinate in EyeLink coordinates (top-left origin)

Return type:

None

get_input_key()[source]

Get keyboard input and convert to pylink key codes.

Filters ‘c’ and ‘v’ keys based on calibration mode: - “normal”: both ‘c’ and ‘v’ enabled - “calibration-only”: only ‘c’ enabled, ‘v’ disabled - “validation-only”: only ‘v’ enabled, ‘c’ disabled

Returns:: List of pylink.KeyInput objects
Return type:: list

setup_image_display(width, height)[source]

Initialize camera image display.

Parameters:

width (int) – Image width in pixels
height (int) – Image height in pixels

Return type:

None

draw_image_line(width, line, totlines, buff)[source]

Draw camera image line by line.

Parameters:

width (int) – Width of the image line
line (int) – Current line number (1-indexed)
totlines (int) – Total number of lines in the image
buff (object) – Buffer containing pixel data for this line

Return type:

None

set_image_palette(r, g, b)[source]

Set color palette for camera image.

Parameters:

r (object) – Red channel values
g (object) – Green channel values
b (object) – Blue channel values

Return type:

None

exit_image_display()[source]

Clean up camera image display.

Return type:: None

getColorFromIndex(colorindex)[source]

Map pylink color constants to PsychoPy color values.

Parameters:: colorindex (int) – Pylink color constant
Returns:: (R, G, B) in PsychoPy color space (-1 to 1)
Return type:: tuple

get_mouse_state()[source]

Get mouse position and button state.

Return type:: tuple | None

draw_line(x1, y1, x2, y2, colorindex)[source]

Draw line on camera image.

Parameters:

x1 (float) – X coordinate of start point
y1 (float) – Y coordinate of start point
x2 (float) – X coordinate of end point
y2 (float) – Y coordinate of end point
colorindex (int) – Pylink color constant

Return type:

None

draw_lozenge(x, y, width, height, colorindex)[source]

Draw rectangle on camera image.

Parameters:

x (float) – X coordinate of top-left corner
y (float) – Y coordinate of top-left corner
width (float) – Width of rectangle
height (float) – Height of rectangle
colorindex (int) – Pylink color constant

Return type:

None

dummynote()[source]

Display message for dummy mode (no hardware connection).

Return type:: None

Pyglet Backend

Pyglet backend for EyeLink calibration display.

This module provides Pyglet-based visualization for EyeLink calibration and validation.

class pyelink.calibration.pyglet_backend.PygletCalibrationDisplay(settings, tracker, mode='normal')[source]

Bases: CalibrationDisplay

Pyglet implementation of EyeLink calibration display.

Parameters:

settings (object)
tracker (object)
mode (str)

__init__(settings, tracker, mode='normal')[source]

Initialize pyglet calibration display.

Parameters:

settings (object) – Settings object with configuration
tracker (object) – EyeLink tracker instance (with display.window attribute)
mode (str) – Calibration mode - “normal”, “calibration-only”, or “validation-only”

Return type:

None

setup_cal_display()[source]

Initialize calibration display with instructions.

Return type:: None

exit_cal_display()[source]

Clean up calibration display.

Return type:: None

close_window()[source]

Close the pyglet window.

Return type:: None

clear_cal_display()[source]

Clear calibration display.

Return type:: None

erase_cal_target()[source]

Remove calibration target from display.

Return type:: None

draw_cal_target(x, y)[source]

Draw calibration target at position (x, y).

Parameters:

x (float) – X coordinate in EyeLink coordinates (top-left origin)
y (float) – Y coordinate in EyeLink coordinates (top-left origin)

Return type:

None

get_input_key()[source]

Get keyboard input and convert to pylink key codes.

Filters ‘c’ and ‘v’ keys based on calibration mode: - “normal”: both ‘c’ and ‘v’ enabled - “calibration-only”: only ‘c’ enabled, ‘v’ disabled - “validation-only”: only ‘v’ enabled, ‘c’ disabled

Returns:: List of pylink.KeyInput objects
Return type:: list

setup_image_display(width, height)[source]

Initialize camera image display.

Parameters:

width (int) – Image width in pixels
height (int) – Image height in pixels

Return type:

None

draw_image_line(width, line, totlines, buff)[source]

Draw camera image line by line.

Parameters:

width (int) – Width of the image line
line (int) – Current line number (1-indexed)
totlines (int) – Total number of lines in the image
buff (object) – Buffer containing pixel data for this line

Return type:

None

This method uses the base class logic for accumulating image lines and drawing overlays. Backend-specific code handles conversion to pyglet image and display.

exit_image_display()[source]

Clean up camera image display.

Return type:: None

get_mouse_state()[source]

Get mouse position and button state.

Returns:: ((x, y), button_state) or None
Return type:: tuple | None

draw_line(x1, y1, x2, y2, colorindex)[source]

Draw line on camera image.

Parameters:

x1 (float) – X coordinate of start point
y1 (float) – Y coordinate of start point
x2 (float) – X coordinate of end point
y2 (float) – Y coordinate of end point
colorindex (int) – Pylink color constant

Return type:

None

draw_lozenge(x, y, width, height, colorindex)[source]

Draw rectangle on camera image.

Parameters:

x (float) – X coordinate of top-left corner
y (float) – Y coordinate of top-left corner
width (float) – Width of rectangle
height (float) – Height of rectangle
colorindex (int) – Pylink color constant

Return type:

None

dummynote()[source]

Display message for dummy mode (no hardware connection).

Return type:: None