EyeTrax

To create a custom gaze-prediction model in EyeTrax, you must subclass BaseModel and implement three internal methods. BaseModel handles feature scaling (using StandardScaler) and provides high-level train, predict, save, and load methods.

When implementing your subclass, you must provide implementations for:

• _init_native(**kwargs): Initialize your model's internal state.
• _native_train(X: np.ndarray, y: np.ndarray): The core training logic using scaled features.
• _native_predict(X: np.ndarray) -> np.ndarray: The core prediction logic using scaled features.

Note that the public train and predict methods automatically apply feature scaling before calling your native implementations.

import numpy as np
from eyetrax.models.base import BaseModel

class MyCustomModel(BaseModel):
    def _init_native(self, **kwargs):
        # Initialize your specific model here
        pass

    def _native_train(self, X: np.ndarray, y: np.ndarray):
        # Implement training logic using scaled X
        pass

    def _native_predict(self, X: np.ndarray) -> np.ndarray:
        # Implement prediction logic using scaled X
        return np.zeros((len(X), 2))

# Usage
model = MyCustomModel()
model.train(X_train, y_train)
predictions = model.predict(X_test)

The GazeEstimator class is the core interface for eye tracking. You can use it to extract facial features, perform calibration, save/load models, and predict gaze coordinates from video frames.

Workflow:

1. Initialize GazeEstimator.
2. Calibrate using a routine like run_9_point_calibration(estimator).
3. (Optional) Save the model using estimator.save_model(path).
4. In a loop, capture frames and use estimator.extract_features(frame) to get features and blink status.
5. Use estimator.predict([features]) to get screen coordinates.

Example:

from eyetrax import GazeEstimator, run_9_point_calibration
import cv2

# Create estimator and calibrate
estimator = GazeEstimator()
run_9_point_calibration(estimator)

# Save model
estimator.save_model("gaze_model.pkl")

# Load model
estimator = GazeEstimator()
estimator.load_model("gaze_model.pkl")

cap = cv2.VideoCapture(0)

while True:
    # Extract features from frame
    ret, frame = cap.read()
    features, blink = estimator.extract_features(frame)

    # Predict screen coordinates
    if features is not None and not blink:
        x, y = estimator.predict([features])[0]
        print(f"Gaze: ({x:.0f}, {y:.0f})")

from eyetrax import GazeEstimator, run_9_point_calibration
import cv2

estimator = GazeEstimator()
run_9_point_calibration(estimator)

# ... later in a loop ...
features, blink = estimator.extract_features(frame)
if features is not None and not blink:
    x, y = estimator.predict([features])[0]

The eyetrax-virtualcam command streams the gaze overlay to a virtual webcam, which can be integrated into streaming software like OBS.

Available Flags:

• --filter: Smoothing filter. Options: kalman, kalman_ema, kde, none (default: none).
• --ema-alpha: (Only for kalman_ema) EMA smoothing strength (0–1, default: 0.25).
• --camera: Physical webcam index (default: 0).
• --calibration: Calibration routine. Options: 9p, 5p, lissajous, dense (default: 9p).
• --grid-rows: (Only for dense calibration) Number of rows (default: 5).
• --grid-cols: (Only for dense calibration) Number of columns (default: 5).
• --grid-margin: (Only for dense calibration) Margin ratio from edges (default: 0.10).
• --confidence: (Only for kde) Contour probability (0–1, default: 0.5).

Example:

eyetrax-virtualcam --filter kde --calibration 5p

The eyetrax-demo command runs an on-screen gaze overlay demo. It supports various smoothing filters and calibration routines via command-line flags.

Available Flags:

• --filter: Smoothing filter. Options: kalman, kalman_ema, kde, none (default: none).
• --ema-alpha: (Only for kalman_ema) EMA smoothing strength (0–1, default: 0.25).
• --camera: Physical webcam index (default: 0).
• --calibration: Calibration routine. Options: 9p, 5p, lissajous, dense (default: 9p).
• --grid-rows: (Only for dense calibration) Number of rows (default: 5).
• --grid-cols: (Only for dense calibration) Number of columns (default: 5).
• --grid-margin: (Only for dense calibration) Margin ratio from edges (default: 0.10).
• --background: (Demo only) Path to a background image.
• --confidence: (Only for kde) Contour probability (0–1, default: 0.5).

Examples:

# Run with Kalman filtering
eyetrax-demo --filter kalman

# Run with Kalman + EMA smoothing (tuned strength)
eyetrax-demo --filter kalman_ema --ema-alpha 0.5

# Run with dense grid calibration for higher spatial coverage
eyetrax-demo --calibration dense --grid-rows 7 --grid-cols 7