ETracker.calibrate

ETracker.calibrate(
    calibration_points=5,
    infant_stims=True,
    shuffle=True,
    audio=True,
    anim_type='zoom',
    stim_size='big',
    visualization_style='circles',
)

Run infant-friendly calibration procedure.

Performs eye tracker calibration using animated stimuli to engage infant participants. The calibration establishes the mapping between eye position and screen coordinates, which is essential for accurate gaze data collection. Automatically selects the appropriate calibration method based on operating mode (real eye tracker vs. mouse simulation).

Parameters

Name Type Description Default
calibration_points int or list of tuple

Calibration pattern specification.

  • Use 5 for the standard 5-point pattern (4 corners + center; default).
  • Use 9 for a comprehensive 9-point pattern (3x3 grid).
  • Alternatively, provide a list of tuples with custom points in normalized
  • coordinates [-1, 1]. Example: [(-0.4, 0.4), (0.4, 0.4), (0.0, 0.0)].
 5
infant_stims True or str or list or visual stimulus

Calibration stimulus specification. Accepts multiple formats

  • True uses built-in stimuli from the package (default);
  • False uses a default blue square;
  • a str specifies a single image file path (e.g., 'stimulus.png');
  • a list of str provides multiple image paths;
  • a PsychoPy visual stimulus (e.g., Circle, Rect, Polygon, ImageStim, ShapeStim) can be used as a single object;
  • or a list of visual stimuli may be provided. If fewer stimuli than calibration points are given, they are automatically repeated and optionally shuffled to cover all points. Supported types: ImageStim, Circle, Rect, Polygon, ShapeStim. TextStim and MovieStim are not supported.
 True
shuffle bool Whether to randomize stimulus presentation order after any necessary repetition. Helps prevent habituation to stimulus sequence. Default is True. True
audio True or False or None or psychopy.sound.Sound

Controls attention-getting audio during calibration:

-True uses the built-in looping calibration sound (default). -False or None disables audio. A psychopy.sound.Sound object may be provided for custom audio (ensure it is configured appropriately, e.g., loops=-1 for continuous looping). Audio plays when a calibration point is selected and fades out during data collection.

 True
anim_type (zoom, trill)

Animation style for calibration stimuli:

  • ‘zoom’ applies smooth size oscillation using a cosine function (default).
  • ‘trill’ uses rapid rotation with intermittent pauses.
 'zoom'
stim_size (big, small)

Size preset for calibration stimuli:

  • ‘big’ uses larger stimuli recommended for infants and children (default). -‘small’ uses smaller stimuli for adults.
 'big'
visualization_style (circles, lines)

How to display calibration results:

  • ‘circles’ shows small filled circles at each gaze sample position.
  • ‘lines’ draws lines from targets to gaze samples.
 'circles'

Returns

Name Type Description
bool True if calibration completed successfully and was accepted by the user. False if calibration was aborted (e.g., via ESC key) or failed.

Raises

Type Description
ValueError If calibration_points is not 5, 9, or a valid list of coordinate tuples; if visualization_style is not ‘circles’ or ‘lines’; or if infant_stims format is unrecognized.
TypeError If pre-loaded stimuli include unsupported types (e.g., TextStim, MovieStim).

Examples

Calibration Point Patterns

Standard 5-point calibration

    controller.calibrate(5)

Comprehensive 9-point calibration

    controller.calibrate(9)

Custom calibration points

    custom_points = [
        (0.0, 0.0),      # Center
        (-0.5, 0.5),     # Top-left
        (0.5, 0.5),      # Top-right
        (-0.5, -0.5),    # Bottom-left
        (0.5, -0.5)      # Bottom-right
    ]
    controller.calibrate(custom_points)

Stimulus Options

Single image file

    controller.calibrate(5, infant_stims='my_stimulus.png')

Multiple image files

    controller.calibrate(5, infant_stims=['stim1.png', 'stim2.png', 'stim3.png'])

Single shape stimulus

    red_square = visual.Rect(win, size=0.08, fillColor='red', units='height')
    controller.calibrate(5, infant_stims=red_square)

Multiple shape stimuli

    shapes = [
        visual.Circle(win, radius=0.04, fillColor='red', units='height'),
        visual.Rect(win, size=0.08, fillColor='blue', units='height'),
        visual.Polygon(win, edges=6, radius=0.04, fillColor='green', units='height')
    ]
    controller.calibrate(5, infant_stims=shapes, shuffle=True)

Animation and Audio

Custom audio

    from psychopy import sound
    my_sound = sound.Sound('custom_beep.wav', loops=-1)
    controller.calibrate(5, audio=my_sound)

Trill animation without audio

    controller.calibrate(5, audio=False, anim_type='trill')

Visualization Styles

Lines visualization

    controller.calibrate(5, visualization_style='lines')

Circles visualization with small stimuli

    controller.calibrate(5, stim_size='small', visualization_style='circles')

Complete Workflows

Full calibration workflow

    # Position participant
    controller.show_status()
    
    # Run calibration
    success = controller.calibrate(
        calibration_points=9,
        infant_stims=['stim1.png', 'stim2.png'],
        shuffle=True,
        audio=True,
        anim_type='zoom',
        visualization_style='circles'
    )
    
    if success:
        controller.start_recording('data.h5')
        # ... run experiment ...
        controller.stop_recording()
Back to top