Gaze Mapping

Gaze estimation algorithms.

Polynomial

Polynomial gaze model eye tracker.

Pupil-CR tracker with polynomial gaze model.

class pyetsimul.gaze_mapping.polynomial.polynomial_gaze_model.PolynomialGazeModel(polynomial, **kwargs)[source]

Bases: EyeTracker

Polynomial gaze model Pupil-CR eye tracker.

Maps pupil-corneal reflection vectors to screen coordinates using polynomial functions. Supports various polynomial types from eye tracking literature.

Parameters:

polynomial (str)
kwargs (object)

__init__(polynomial, **kwargs)[source]

Initialize polynomial gaze model tracker with polynomial specification.

Sets up polynomial function and algorithm state for gaze tracking.

Parameters:

polynomial (str) – Polynomial type to use
**kwargs (object) – Arguments passed to parent EyeTracker

Return type:

None

property algorithm_name: str: Algorithm name identifier.

classmethod create(cameras, lights, calib_points, polynomial, use_refraction=True)[source]

Create polynomial gaze model eye tracker setup.

Factory method for configuring complete polynomial gaze model tracker with all components.

Parameters:

cameras (list) – List of Camera objects
lights (list) – List of Light objects
calib_points (list[Position3D]) – List of calibration target positions
polynomial (str) – Polynomial type to use
use_refraction (bool) – Whether to use refraction model (default True)

Returns:

Configured polynomial gaze model eye tracker

Return type:

PolynomialGazeModel

calibrate(calibration_measurements)[source]

Calibration function for pupil-CR polynomial gaze model.

Detects calibration plane and performs polynomial least squares calibration. Automatically handles different polynomial feature types.

Parameters:: calibration_measurements (list[EyeMeasurement]) – List of EyeMeasurement objects from calibration
Return type:: None

predict_gaze(measurement)[source]

Predict gaze from pupil-corneal reflection vectors.

Applies calibrated polynomial model to predict screen gaze coordinates. Computes P-CR vectors for all available glints and concatenates the polynomial features before applying the calibrated coefficients. Handles missing data with appropriate confidence scoring.

Parameters:: measurement (EyeMeasurement) – EyeMeasurement object containing pupil and corneal reflection data
Returns:: Structured prediction result.
Return type:: GazePrediction

serialize()[source]

Serialize eye tracker to dictionary.

Saves all eye tracker parameters, calibration data, and algorithm state for later restoration and validation.

Returns:: Complete eye tracker state including hardware configuration
Return type:: dict

classmethod deserialize(data)[source]

Deserialize eye tracker from dictionary.

Restores complete eye tracker state including calibration and hardware configuration. The restored tracker is ready to use without recalibration.

Parameters:: data (dict) – Dictionary from serialize() method
Returns:: Fully configured and calibrated eye tracker
Return type:: PolynomialGazeModel

Stampe (1993)

Gaze model from Stampe (1993): biquadratic polynomial + per-quadrant corner correction.

Thin wrapper around stampe1993_gaze_mapping.StampeModel. Calibration points are passed in HV9 paper order — first 5 inner (centre + cardinal edges), last 4 outer (corners). Layouts with fewer than 9 points fit polynomial-only.

Reference: Stampe, D. M. (1993). Heuristic filtering and reliable calibration methods for video-based pupil-tracking systems. Behavior Research Methods, 25(2), 137-142.

class pyetsimul.gaze_mapping.stampe1993.stampe1993_gaze_model.Stampe1993GazeModel(**kwargs)[source]

Bases: PolynomialGazeModel

Stampe (1993) gaze model — biquadratic polynomial with per-quadrant corner correction.

Parameters:: kwargs (object)

__init__(**kwargs)[source]

Initialise with the Stampe biquadratic polynomial.

Parameters:: kwargs (object)
Return type:: None

property algorithm_name: str: Return the name of the algorithm.

classmethod create(cameras, lights, calib_points, use_refraction=True)[source]

Create a Stampe1993GazeModel with cameras, lights, calibration points, and refraction option.

Return type:

Stampe1993GazeModel

Parameters:

cameras (list)
lights (list)
calib_points (list[Position3D])
use_refraction (bool)

calibrate(calibration_measurements)[source]

Fit StampeModel on the calibration measurements.

Inner = first 5 points (HV9 centre + cardinal edges). Outer = last 4 points (HV9 corners) when 9 points are supplied; otherwise the polynomial alone is fit and no corner correction is applied.

Return type:: None
Parameters:: calibration_measurements (list[EyeMeasurement])

predict_gaze(measurement)[source]

Predict gaze for one EyeMeasurement using the fitted StampeModel.

Return type:: GazePrediction
Parameters:: measurement (EyeMeasurement)

Homography Normalization

Homography normalization gaze estimation module.

Based on Hansen et al. (2010) “Homography Normalization for Robust Gaze Estimation in Uncalibrated Setups” (ETRA 2010).

class pyetsimul.gaze_mapping.homography_normalization.GaussianProcessErrorCorrection(length_scale=100.0, noise_level=1.0, length_scale_bounds=(10.0, 500.0), noise_level_bounds=(0.01, 10.0))[source]

Bases: object

Gaussian Process error correction using scikit-learn.

Models systematic errors by wrapping scikit-learn’s GaussianProcessRegressor. Uses a squared exponential kernel (RBF) and a noise kernel (WhiteKernel).

Parameters:

length_scale (float)
noise_level (float)
length_scale_bounds (tuple[float, float])
noise_level_bounds (tuple[float, float])

__init__(length_scale=100.0, noise_level=1.0, length_scale_bounds=(10.0, 500.0), noise_level_bounds=(0.01, 10.0))[source]

Initialize the GP error correction model.

Parameters:

length_scale (float) – Initial length scale of the RBF kernel (mm). Default 100 mm is suitable for screen-scale coordinates.
noise_level (float) – Initial noise level (mm). Default 1 mm matches typical calibration error scales.
length_scale_bounds (tuple[float, float]) – Min/max bounds for length scale optimization (mm). Default (10, 500) mm.
noise_level_bounds (tuple[float, float]) – Min/max bounds for noise level optimization (mm). Default (0.01, 10) mm.

Return type:

None

fit(X, y)[source]

Fit the GP model to the calibration residuals.

Return type:

None

Parameters:

X (ndarray)
y (ndarray)

predict(X)[source]

Predict the error correction for new gaze points.

Parameters:: X (ndarray) – Mx2 array of query screen positions.
Return type:: ndarray
Returns:: Mx2 array of predicted error vectors.

class pyetsimul.gaze_mapping.homography_normalization.HomographyNormalizationGazeModel(use_gp_correction=False, ransac_threshold=5.0, **kwargs)[source]

Bases: EyeTracker

Homography normalization gaze estimation eye tracker.

Uses 4+ glints to normalize head pose effects through projective transformations. Does not require camera or geometric calibration.

Parameters:

use_gp_correction (bool)
ransac_threshold (float)
kwargs (object)

__init__(use_gp_correction=False, ransac_threshold=5.0, **kwargs)[source]

Initialize homography gaze model tracker.

Parameters:

use_gp_correction (bool) – Whether to use Gaussian Process error correction
ransac_threshold (float) – Maximum reprojection error in pixels for RANSAC. Adjust based on camera resolution and noise. Default: 5.0 pixels
**kwargs (object) – Arguments passed to parent EyeTracker

Return type:

None

property algorithm_name: str: Algorithm name identifier.

classmethod create(cameras, lights, calib_points, use_gp_correction=False, ransac_threshold=5.0, use_refraction=True)[source]

Create homography normalization gaze model eye tracker setup.

Factory method for configuring complete homography normalization gaze model tracker.

Parameters:

cameras (list[Camera]) – List of Camera objects
lights (list[Light]) – List of Light objects (minimum 4 required)
calib_points (list[Position3D]) – List of 3D calibration points
use_gp_correction (bool) – Whether to use Gaussian Process error correction
ransac_threshold (float) – RANSAC reprojection error threshold in pixels
use_refraction (bool) – Whether to use refraction in optical calculations

Returns:

Configured homography normalization gaze model eye tracker

Return type:

HomographyNormalizationGazeModel

calibrate(calibration_measurements)[source]

Calibrate homography gaze model.

Implements Hansen et al. (2010) homography normalization calibration:

Detect calibration plane for coordinate system.
Define a canonical reference pattern for the N light sources.
For each calibration point:
- Order the detected glints and reference points.
- Compute H^n_i: glints_image → normalized space using a best-fit method.
- Normalize the pupil center: pc^n = H^n_i @ pc^i.
Solve for H^s_n: normalized_pupil → screen_coordinates.
(Optional) Train Gaussian Process on residual errors.

Return type:: None
Parameters:: calibration_measurements (list[EyeMeasurement])

predict_gaze(measurement)[source]

Predict gaze using homography normalization.

Return type:: GazePrediction
Parameters:: measurement (EyeMeasurement)

serialize()[source]

Serialize eye tracker to dictionary.

Saves all eye tracker parameters, calibration data, and algorithm state for later restoration and validation.

Returns:: Complete eye tracker state including hardware configuration
Return type:: dict

classmethod deserialize(data)[source]

Deserialize eye tracker from dictionary.

Restores complete eye tracker state including calibration and hardware configuration. The restored tracker is ready to use without recalibration.

Parameters:: data (dict) – Dictionary from serialize() method
Returns:: Fully configured and calibrated eye tracker
Return type:: HomographyNormalizationGazeModel

class pyetsimul.gaze_mapping.homography_normalization.HomographyNormalizationGazeModelState(is_calibrated=False, calibration_error=None, last_update=None, H_s_n=None, reference_glints_normalized=None, ransac_threshold=5.0, gp_model=None, calibration_errors=None)[source]

Bases: AlgorithmState

State for homography normalization gaze model.

Parameters:

is_calibrated (bool)
calibration_error (float | None)
last_update (float | None)
H_s_n (ndarray | None)
reference_glints_normalized (list[Point2D] | None)
ransac_threshold (float)
gp_model (Any | None)
calibration_errors (ndarray | None)

H_s_n: ndarray | None = None

reference_glints_normalized: list[Point2D] | None = None

ransac_threshold: float = 5.0

gp_model: Any | None = None

calibration_errors: ndarray | None = None

serialize()[source]

Serialize homography state to dictionary.

Includes GP model serialization using joblib. The GP model is serialized to bytes and encoded as base64 for JSON compatibility.

Return type:: dict

classmethod deserialize(data)[source]

Deserialize from dictionary.

Restores the GP model from base64-encoded joblib bytes if present.

Return type:: HomographyNormalizationGazeModelState
Parameters:: data (dict)