Settings

EyeLink tracker settings with runtime validation.

This module defines all configuration settings for EyeLink tracker operation. Settings use Pydantic for runtime validation and rich IDE support via comprehensive docstrings.

class pyelink.settings.Settings(**data)

Bases: BaseModel

EyeLink tracker configuration with runtime validation.

All settings have comprehensive docstrings visible in IDE autocomplete. Values are validated at creation and on assignment.

Example

settings = Settings() settings.n_cal_targets = 13 settings.save_to_file(“my_config.json”)

Parameters:

• filename (str)

• filepath (str)

• enable_long_filenames (bool)

• max_filename_length (int)

• sample_rate (Literal[250, 500, 1000, 2000])

• n_cal_targets (Literal[3, 5, 9, 13])

• enable_automatic_calibration (bool)

• log_calibration_target_messages (bool)

• pacing_interval (int)

• calibration_corner_scaling (float)

• validation_corner_scaling (float)

• calibration_area_proportion (tuple[float, float])

• validation_area_proportion (tuple[float, float])

• target_type (Literal['ABC', 'AB', 'A', 'B', 'C', 'CIRCLE', 'IMAGE'])

• target_image_path (str | None)

• cal_background_color (tuple[int, int, int])

• calibration_instruction_text (str)

• calibration_text_color (tuple[int, int, int])

• calibration_text_font_size (int)

• calibration_text_font_name (str)

• calibration_instruction_page_callback (Callable[[object], None] | None)

• fixation_center_diameter (float)

• fixation_outer_diameter (float)

• fixation_cross_width (float)

• fixation_center_color (tuple[int, int, int, int])

• fixation_outer_color (tuple[int, int, int, int])

• fixation_cross_color (tuple[int, int, int, int])

• circle_outer_radius (int)

• circle_inner_radius (int)

• circle_outer_color (tuple[int, int, int])

• circle_inner_color (tuple[int, int, int])

• screen_res (tuple[int, int])

• screen_width (float)

• screen_height (float)

• camera_to_screen_distance (float)

• screen_distance (float | None)

• screen_distance_top_bottom (tuple[float, float] | None)

• camera_lens_focal_length (int | None)

• backend (Literal['pygame', 'psychopy', 'pyglet'])

• fullscreen (bool)

• display_index (int)

• pupil_tracking_mode (Literal['CENTROID', 'ELLIPSE'])

• pupil_size_mode (Literal['AREA', 'DIAMETER'])

• heuristic_filter (tuple[int, int])

• set_heuristic_filter (bool)

• enable_dual_corneal_tracking (bool)

• file_event_filter (str)

• link_event_filter (str)

• link_sample_data (str)

• file_sample_data (str)

• record_samples_to_file (bool)

• record_events_to_file (bool)

• record_sample_over_link (bool)

• record_event_over_link (bool)

• enable_search_limits (bool)

• track_search_limits (bool)

• autothreshold_click (bool)

• autothreshold_repeat (bool)

• enable_camera_position_detect (bool)

• illumination_power (Literal[1, 2, 3])

• host_ip (str)

• el_configuration (Literal['MTABLER', 'BTABLER', 'RTABLER', 'RBTABLER', 'AMTABLER', 'ARTABLER', 'BTOWER'])

• eye_tracked (Literal['BOTH', 'LEFT', 'RIGHT'])

filename: str

filepath: str

enable_long_filenames: bool

max_filename_length: int

sample_rate: Literal[250, 500, 1000, 2000]

n_cal_targets: Literal[3, 5, 9, 13]

enable_automatic_calibration: bool

log_calibration_target_messages: bool

pacing_interval: int

calibration_corner_scaling: float

validation_corner_scaling: float

calibration_area_proportion: tuple[float, float]

validation_area_proportion: tuple[float, float]

target_type: Literal['ABC', 'AB', 'A', 'B', 'C', 'CIRCLE', 'IMAGE']

target_image_path: str | None

cal_background_color: tuple[int, int, int]

calibration_instruction_text: str

calibration_text_color: tuple[int, int, int]

calibration_text_font_size: int

calibration_text_font_name: str

calibration_instruction_page_callback: Callable[[object], None] | None

fixation_center_diameter: float

fixation_outer_diameter: float

fixation_cross_width: float

fixation_center_color: tuple[int, int, int, int]

fixation_outer_color: tuple[int, int, int, int]

fixation_cross_color: tuple[int, int, int, int]

circle_outer_radius: int

circle_inner_radius: int

circle_outer_color: tuple[int, int, int]

circle_inner_color: tuple[int, int, int]

screen_res: tuple[int, int]

screen_width: float

screen_height: float

camera_to_screen_distance: float

screen_distance: float | None

screen_distance_top_bottom: tuple[float, float] | None

camera_lens_focal_length: int | None

backend: Literal['pygame', 'psychopy', 'pyglet']

fullscreen: bool

display_index: int

pupil_tracking_mode: Literal['CENTROID', 'ELLIPSE']

pupil_size_mode: Literal['AREA', 'DIAMETER']

heuristic_filter: tuple[int, int]

set_heuristic_filter: bool

enable_dual_corneal_tracking: bool

file_event_filter: str

link_event_filter: str

link_sample_data: str

file_sample_data: str

record_samples_to_file: bool

record_events_to_file: bool

record_sample_over_link: bool

record_event_over_link: bool

enable_search_limits: bool

track_search_limits: bool

autothreshold_click: bool

autothreshold_repeat: bool

enable_camera_position_detect: bool

illumination_power: Literal[1, 2, 3]

host_ip: str

el_configuration: Literal['MTABLER', 'BTABLER', 'RTABLER', 'RBTABLER', 'AMTABLER', 'ARTABLER', 'BTOWER']

eye_tracked: Literal['BOTH', 'LEFT', 'RIGHT']

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'use_enum_values': True, 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_area_proportions(v)

Validate area proportions are in valid range (0, 1].

Return type:

tuple[float, float]

Parameters:

v (tuple[float, float])

classmethod validate_heuristic_filter(v)

Validate heuristic filter levels are 0-2.

Return type:

tuple[int, int]

Parameters:

v (tuple[int, int])

classmethod validate_screen_res(v)

Validate screen resolution has positive values.

Return type:

tuple[int, int]

Parameters:

v (tuple[int, int])

classmethod validate_screen_distance(v, info)

Ensure at least one screen distance measurement is provided.

Return type:

tuple[float, float] | None

Parameters:

• v (tuple[float, float] | None)

• info (ValidationInfo)

validate_file_settings()

Validate file-related settings after all fields are set.

Return type:

Settings

save_to_file(path)

Save settings to JSON file.

Parameters:

path (str) – File path (will be created/overwritten)

Return type:

None

Example

settings.save_to_file(“my_experiment_config.json”)

classmethod load_from_file(path)

Load settings from JSON file.

Parameters:

path (str) – File path to load from

Return type:

Settings

Returns:

Settings instance with validated values

Example

settings = Settings.load_from_file(“my_experiment_config.json”)

to_dict()

Convert settings to dictionary.

Return type:

dict

Returns:

Dictionary representation of all settings

classmethod from_dict(data)

Create Settings from dictionary with validation.

Parameters:

data (dict) – Dictionary with setting names and values

Return type:

Settings

Returns:

Settings instance with validated values