pupilio.core module

class pupilio.core.Pupilio(config=None)

Bases: object

Class for interacting with the eye tracker dynamic link library (DLL). A pythonic wrapper for Pupilio library.

calibration(cali_point_id: int) → int

Perform calibration

Parameters:

cali_point_id (int) – ID of the calibration point, 0 for the first calibration point, 1 for the second, and so on.

Returns:

Result of the calibration, can be checked against ET_ReturnCode enum.

Return type:

int

calibration_draw(screen=None, validate=False, bg_color=(255, 255, 255), hands_free=False)

Draw the indicator of the face distance and the eyebrow center position. Draw the calibration UI. :param screen: The screen to draw on. You can choose pygame window or psychopy window :param validate: Whether to validate the calibration result. :type validate: bool :param bg_color: Background color, specific parameter for pygame :type bg_color: tuple :param hands_free: Whether to hands free :type hands_free: bool

clear_cache() → int

Clear the cache.

create_session(session_name: str) → int

Creates a new session and sets up related directories, log files, and the logger.

Parameters:

  • session_name – The name of the session, used to define log files and a temporary folder

  • data. (for real-time storage of eye-tracking)

  • unique (It is recommended to make the session_name)

  • the (so data can be recovered from)

  • letters (temporary folder in case of loss. The session_name must only contain)

  • digits

:param : :param or underscores without any special characters.:

Returns:

ET_ReturnCode indicating the success or failure of session creation.

Return type:

int

Notes

  1. The temporary folder is located at /Pupilio/{session_name}_{time} in the user’s home directory.

  2. If storage space runs out, you can delete this temporary folder to free up space.

estimation() → Tuple[int, ndarray, int, int]

Estimate the gaze state and position.

Returns:

A tuple containing ET_ReturnCode, eye position data, timestamp, and trigger.

Return type:

tuple[int, np.ndarray, int, int]

estimation_lr() → Tuple[int, ndarray, ndarray, int, int]

Estimate the gaze state and position for left and right eyes.

This function calls the native pupil estimation library to obtain the estimated gaze points for both the left and right eyes, as well as the timestamp of the estimation. The function returns the status of the operation, the gaze points for the left and right eyes, the timestamp, and an additional trigger value.

Returns:

  • int: Status code, where ET_ReturnCode.ET_SUCCESS indicates success.

  • np.ndarray: Estimated gaze point for the left eye. Contains 14 elements.

    left_eye_sample[0]:left eye gaze position x (0~1920) left_eye_sample[1]:left eye gaze position y (0~1920) left_eye_sample[2]:left eye pupil diameter (0~10) (mm) left_eye_sample[3]:left eye pupil position x left_eye_sample[4]:left eye pupil position y left_eye_sample[5]:left eye pupil position z left_eye_sample[6]:left eye visual angle in spherical: theta left_eye_sample[7]:left eye visual angle in spherical: phi left_eye_sample[8]:left eye visual angle in vector: x left_eye_sample[9]:left eye visual angle in vector: y left_eye_sample[10]:left eye visual angle in vector: z left_eye_sample[11]:left eye pix per degree x left_eye_sample[12]:left eye pix per degree y left_eye_sample[13]:left eye valid (0:invalid 1:valid)

  • np.ndarray: Estimated gaze point for the right eye. Contains 14 elements.

    right_eye_sample[0]:right eye gaze position x (0~1920) right_eye_sample[1]:right eye gaze position y (0~1920) right_eye_sample[2]:right eye pupil diameter (0~10) (mm) right_eye_sample[3]:right eye pupil position x right_eye_sample[4]:right eye pupil position y right_eye_sample[5]:right eye pupil position z right_eye_sample[6]:right eye visual angle in spherical: theta right_eye_sample[7]:right eye visual angle in spherical: phi right_eye_sample[8]:right eye visual angle in vector: x right_eye_sample[9]:right eye visual angle in vector: y right_eye_sample[10]:right eye visual angle in vector: z right_eye_sample[11]:right eye pix per degree x right_eye_sample[12]:right eye pix per degree y right_eye_sample[13]:right eye valid (0:invalid 1:valid)

  • int: Timestamp of the estimation (in milliseconds).

  • int: Trigger value, initialized to 0.

Return type:

Tuple[int, np.ndarray, np.ndarray, int, int]

Example

status, left_eye_sample, right_eye_sample, timestamp, trigger = instance.estimation_lr() if status == ET_ReturnCode.ET_SUCCESS:

print(“Gaze estimation successful.”)

face_position() → Tuple[int, ndarray]

Get the current face position.

Returns:

A tuple containing the result code and numpy array of face position coordinates.

  • If sampling is ongoing, returns ET_FAILED and an empty list.

  • If successful, returns ET_SUCCESS and the face position coordinates.

Return type:

tuple

get_current_gaze() → Tuple[ndarray, ndarray, ndarray]

Retrieve the current gaze values for the left eye, right eye, and binocular gaze.

Example

left, right, bino = pupil_io.get_current_gaze() left_valid = left[0] right_valid = right[0] bino_valid = bino[0] left_coordinate_x, left_coordinate_y = left[1], left[2] right_coordinate_x, right_coordinate_y = right[1], right[2] bino_coordinate_x, bino_coordinate_y = bino[1], bino[2]

Returns:

A Tuple containing the left gaze, right gaze, and binocular gaze as floats.

Return type:

np.ndarray

get_preview_images()

Retrieves preview images and related eye-tracking data, including eye bounds, pupil centers, and corneal reflection (CR) centers, from the native eye-tracking library.

Returns:

A 3D array containing the left and right grayscale preview images.

Return type:

numpy.ndarray

get_sampling_status() → bool

Check the status of sampling from the pupil IO.

Returns: bool: True if sampling is active, False otherwise.

previewer_start(udp_host: str, udp_port: int)

Initialize and start the previewer.

Parameters:

  • udp_host – The UDP host address for receiving the video stream.

  • udp_port – The UDP port number for receiving the video stream.

This method first calls pupil_io_previewer_init to initialize the previewer, and then calls pupil_io_previewer_start to start the preview.

previewer_stop()

Stop the previewer.

This method calls pupil_io_previewer_stop to cease receiving and processing the video stream.

release() → int

Release the resources used by the eye tracker.

Returns:

ET_ReturnCode.ET_SUCCESS if successful.

Return type:

int

sample_subscriber_lock
sample_subscribers
save_data(path: str) → int

Save sampled data to a file.

Parameters:

path (str) – The path to save the data file.

Returns:

Return code indicating success or failure.

Return type:

int

set_filter_enable(status: bool) → int

Enable or disable the filter.

Parameters:

status (bool) – True to enable the filter, False to disable.

set_trigger(trigger: int) → int

Set the trigger.

Parameters:

trigger – The trigger to set.

start_sampling() → int

Start eye gaze sampling.

Returns:

Return code indicating success or failure.

Return type:

int

stop_sampling() → int

Stop eye gaze sampling.

Returns:

Return code indicating success or failure.

Return type:

int

subscribe_event(*args)

Subscribe a function to receive eye tracking sample.

Raises:

Exception – If any of the args are not Callable.

subscribe_sample(subscriber_func: Callable, args=(), kwargs=None)

Subscribe a function to receive eye tracking samples.

‘sample’ is an instance of dict. The format is as follows:

sample = {

“trigger”: trigger, “status”: status, “left_eye_sample”: left_eye_sample, “right_eye_sample”: right_eye_sample, “timestamp”: timestamp

}

‘left_eye_sample’ is an instance of list, which contains 14 elements as follows:

left_eye_sample[0]:left eye gaze position x (0~1920) left_eye_sample[1]:left eye gaze position y (0~1920) left_eye_sample[2]:left eye pupil diameter (0~10) (mm) left_eye_sample[3]:left eye pupil position x left_eye_sample[4]:left eye pupil position y left_eye_sample[5]:left eye pupil position z left_eye_sample[6]:left eye visual angle in spherical: theta left_eye_sample[7]:left eye visual angle in spherical: phi left_eye_sample[8]:left eye visual angle in vector: x left_eye_sample[9]:left eye visual angle in vector: y left_eye_sample[10]:left eye visual angle in vector: z left_eye_sample[11]:left eye pix per degree x left_eye_sample[12]:left eye pix per degree y left_eye_sample[13]:left eye valid (0:invalid 1:valid)

‘right_eye_sample’ is an instance of list, which contains 14 elements as follows:

right_eye_sample[0]:right eye gaze position x (0~1920) right_eye_sample[1]:right eye gaze position y (0~1920) right_eye_sample[2]:right eye pupil diameter (0~10) (mm) right_eye_sample[3]:right eye pupil position x right_eye_sample[4]:right eye pupil position y right_eye_sample[5]:right eye pupil position z right_eye_sample[6]:right eye visual angle in spherical: theta right_eye_sample[7]:right eye visual angle in spherical: phi right_eye_sample[8]:right eye visual angle in vector: x right_eye_sample[9]:right eye visual angle in vector: y right_eye_sample[10]:right eye visual angle in vector: z right_eye_sample[11]:right eye pix per degree x right_eye_sample[12]:right eye pix per degree y right_eye_sample[13]:right eye valid (0:invalid 1:valid)

Parameters:

  • subscriber_func (Callable) – The function to be called when a new eye tracking sample is available.

  • args (tuple) – Optional positional arguments to pass to the subscriber function.

  • kwargs (dict) – Optional keyword arguments to pass to the subscriber function.

Raises:

Exception – If subscriber_func is not Callable.

unsubscribe_event(*args)

Unsubscribe functions from receiving eye tracking sample.

unsubscribe_sample(subscriber_func: Callable, args=(), kwargs=None)

Unsubscribe a function from receiving eye tracking samples.

Parameters:

  • subscriber_func (Callable) – The function to be removed from subscribers.

  • args (tuple) – Positional arguments used for subscription (should match what was used during subscription).

  • kwargs (dict) – Keyword arguments used for subscription (should match what was used during subscription).

Raises:

Exception – If subscriber_func is not Callable.

pupilio.DefaultConfig module

Default configuration class containing various parameters required for program execution. Includes settings for file paths, hyperparameters, and resources like images and audio.

Filter Hyperparameters

look_ahead (int): Look-ahead steps for predicting target position.

Calibration Resources

cali_target_beep (str): Path to the beep sound used during calibration. cali_frowning_face_img (str): Path to the frowning face image used during calibration. cali_smiling_face_img (str): Path to the smiling face image used during calibration. cali_target_img (str): Path to the windmill image used as the calibration target.

Calibration Target Settings

cali_target_img_maximum_size (int): Maximum size of the calibration target image. cali_target_img_minimum_size (int): Minimum size of the calibration target image. cali_target_animation_frequency (int): Frequency of the calibration target animation (in Hz).

Calibration Mode

cali_mode (CalibrationMode): Specifies the calibration mode, default is TWO_POINTS.

Kappa Angle Verification
enable_kappa_verification (int): Verification of the kappa angle after calibration. Default is 1.

When this value is 0, the verification of the kappa angle after calibration is disabled, suitable for users with strabismus.

Debug Settings

  • enable_debug_logging (int): Toggle for enabling debug logging. Disabled by default (0).

  • log_directory (str): Directory path for storing debug logs.

Calibration Instructions

  • instruction_face_far (str): Instruction when the face is too close.

  • instruction_face_near (str): Instruction when the face is too far.

  • instruction_head_center (str): Instruction to align the head to the center of the frame.

  • instruction_enter_calibration (str): Instruction for entering calibration.

  • instruction_hands_free_calibration (str): Instruction for hands-free calibration.

Validation Instructions

  • instruction_enter_validation (str): Instruction for entering validation.

Validation Legends

  • legend_target (str): Legend for target points.

  • legend_left_eye (str): Legend for left eye gaze.

  • legend_right_eye (str): Legend for right eye gaze.

  • instruction_calibration_over (str): Instruction for continuing after validation.

  • instruction_recalibration (str): Instruction for initiating recalibration.

Calibration Previewing

  • face_previewing (int): Whether show calibration previewing,default is 1.

Active Eye

  • active_eye (str): Which one or two eyes you want to track.`

Simulation mode
  • simulation_mode (bool): Switch of simulation mode. If true, use your mouse to replace the eye position.

    Default is false.

pupilio.misc module

class pupilio.misc.ActiveEye(value)

Bases: IntEnum

Tracking left eye, right eye or both

BINO_EYE = 0
LEFT_EYE = -1
RIGHT_EYE = 1
class pupilio.misc.Calculator(screen_width, screen_height, physical_screen_width, physical_screen_height, *args, **kwargs)

Bases: object

Class to perform calculations related to screen dimensions. This class can calculate error metrics based on pixel values and distances.

calculate_error_by_sliding_window(gt_point, es_points, distances)

Calculate the error between ground truth pixel and estimated pixel. :param gt_point: Ground truth pixel value. :param es_points: Points of estimated pixel value, array-like. :param distances: Distance list between the pixels.

error(gt_pixel, es_pixel, distance)

Calculate the error between ground truth pixel and estimated pixel.

Parameters:

  • gt_pixel – Ground truth pixel value.

  • es_pixel – Estimated pixel value.

  • distance – Distance between the pixels.

Returns:

Error value calculated based on the provided formula.

px_2_cm(pixel_point)
class pupilio.misc.CalibrationMode(value)

Bases: IntEnum

Enum representing calibration modes

FIVE_POINTS = 5
TWO_POINTS = 2
class pupilio.misc.ET_ReturnCode(value)

Bases: IntEnum

Enum representing return codes from the eye tracker

ET_CALI_CONTINUE = 1
ET_CALI_NEXT_POINT = 2
ET_FAILED = 9
ET_SUCCESS = 0
class pupilio.misc.EventType(value)

Bases: StrEnum

END_FIXATION = 'end_fixation'
END_SACCADE = 'end_saccade'
IN_FIXATION = 'in_fixation'
IN_SACCADE = 'in_saccade'
START_FIXATION = 'start_fixation'
START_SACCADE = 'start_saccade'
UNKNOWN = 'unknown'
class pupilio.misc.LocalConfig

Bases: object

Class to handle local configuration settings. This class loads a JSON configuration file for deep configuration settings.

class pupilio.misc.Queue(cache_size=2)

Bases: object

dequeue()
empty()
enqueue(item)
full()
peek()
size()
tail()
class pupilio.misc.StrEnum(value)

Bases: str, Enum

Enum where members are unique and are also strings

class pupilio.misc.TriggerHandler

Bases: object

get()

Method to get the current marker value. :return: The current marker value or -1 if the marker is not updated.

set(trigger: int)

Method to set the marker value. :param trigger: The new marker value to be set.

pupilio.callback module

class pupilio.callback.CalibrationListener

Bases: object

A listener class to handle events during a calibration process. This class defines methods that can be overridden to perform specific actions when calibration or validation targets are presented during gaze calibration.

None
__init__()

Initializes the listener instance.

on_calibration_target_onset(point_index)

Called when a calibration target is presented.

on_validation_target_onset(point_index)

Called when a validation target is presented.

on_calibration_target_onset(point_index)

This method is called when a calibration target is presented on the screen.

Parameters:

  • point_index (int) – The index of the current calibration target. This can be used

  • calibration (to identify the target's position or other characteristics specific to the)

  • process.

This method can be overridden to define actions that should occur when a calibration target is shown (e.g., logging, updating UI, or triggering an event).

on_validation_target_onset(point_index)

This method is called when a validation target is presented on the screen.

Parameters:

  • point_index (int) – The index of the current validation target. Similar to the calibration

  • target

  • to (this can be used to identify the target's position or other properties related)

  • process. (the validation)

This method can be overridden to define actions that should occur when a validation target is shown (e.g., logging, updating UI, or triggering an event).

pupilio.annotation module

class pupilio.callback.CalibrationListener

Bases: object

A listener class to handle events during a calibration process. This class defines methods that can be overridden to perform specific actions when calibration or validation targets are presented during gaze calibration.

None
__init__()

Initializes the listener instance.

on_calibration_target_onset(point_index)

Called when a calibration target is presented.

on_validation_target_onset(point_index)

Called when a validation target is presented.

on_calibration_target_onset(point_index)

This method is called when a calibration target is presented on the screen.

Parameters:

  • point_index (int) – The index of the current calibration target. This can be used

  • calibration (to identify the target's position or other characteristics specific to the)

  • process.

This method can be overridden to define actions that should occur when a calibration target is shown (e.g., logging, updating UI, or triggering an event).

on_validation_target_onset(point_index)

This method is called when a validation target is presented on the screen.

Parameters:

  • point_index (int) – The index of the current validation target. Similar to the calibration

  • target

  • to (this can be used to identify the target's position or other properties related)

  • process. (the validation)

This method can be overridden to define actions that should occur when a validation target is shown (e.g., logging, updating UI, or triggering an event).