### KDE Filter Setup

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Example of setting up the KDE Smoother filter with screen size and filter parameters.

```python
from eyetrax.filters import KDESmoother
from eyetrax.utils.screen import get_screen_size

screen_w, screen_h = get_screen_size()
smoother = KDESmoother(
    screen_w, screen_h,
    time_window=0.5,
    confidence=0.5,
    grid=(320, 200)
)
```

--------------------------------

### Environment Setup: Virtual Camera Setup (Linux)

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Instructions for setting up a virtual camera on Linux using v4l2loopback.

```bash
# Install v4l2loopback
sudo apt install v4l2loopback-dkms

# Create virtual camera
sudo modprobe v4l2loopback video_nr=10 exclusive_caps=1

# Now use eyetrax-virtualcam
eyetrax-virtualcam
```

--------------------------------

### Adaptive Calibration Workflow Examples

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Examples of configuring adaptive calibration for different scenarios.

```python
# Quick adaptive (70 total points)
run_adaptive_calibration(estimator, num_random_points=40, retrain_every=10)

# Thorough adaptive (170 total points)
run_adaptive_calibration(estimator, num_random_points=100, retrain_every=25)

# Silent adaptive (no live predictions)
run_adaptive_calibration(estimator, show_predictions=False)
```

--------------------------------

### Tiny MLP Architecture Examples

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Examples of different hidden layer sizes for the Tiny MLP architecture.

```python
# Shallow network (fast training)
{"hidden_layer_sizes": (64,)}

# Medium network (default)
{"hidden_layer_sizes": (64, 32)}

# Deep network (more capacity)
{"hidden_layer_sizes": (128, 64, 32, 16)}
```

--------------------------------

### Dense Grid Calibration Examples

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Examples of configuring dense grid calibration for different precision levels.

```python
# Fine (high precision, long calibration)
run_dense_grid_calibration(estimator, rows=8, cols=8, margin_ratio=0.05)

# Coarse (fast baseline)
run_dense_grid_calibration(estimator, rows=3, cols=3, margin_ratio=0.15)

# Standard (balanced)
run_dense_grid_calibration(estimator, rows=5, cols=5, margin_ratio=0.10)
```

--------------------------------

### Kalman Filter Setup

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Initializes a Kalman filter and smoother.

```python
from eyetrax.filters import make_kalman, KalmanSmoother

kf = make_kalman(
    state_dim=4,
    meas_dim=2,
    dt=1.0,
    process_var=50.0,
    measurement_var=0.2,
    init_state=None
)
smoother = KalmanSmoother(kf)
```

--------------------------------

### Configuration Workflow: Streaming (VirtualCam, Low Latency)

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Command-line example for setting up a streaming scenario using Eyetrack's virtual camera.

```bash
eyetrax-virtualcam \
  --model ridge \
  --calibration 9p \
  --filter kalman \
  --camera 0
```

--------------------------------

### KDE Filter Recommended Presets

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Examples of recommended presets for the KDE Smoother filter, demonstrating different configurations for contour tightness.

```python
# Tight contours (conservative)
KDESmoother(w, h, time_window=0.3, confidence=0.8)

# Balanced (default)
KDESmoother(w, h, time_window=0.5, confidence=0.5)

# Loose contours (generous)
KDESmoother(w, h, time_window=1.0, confidence=0.2)
```

--------------------------------

### CLI Configuration via Command-Line Arguments

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Example of configuring Eyetrack using command-line arguments for the demo application.

```bash
eyetrax-demo \
  --model tiny_mlp \
  --calibration dense \
  --grid-rows 7 \
  --grid-cols 7 \
  --filter kalman_ema \
  --ema-alpha 0.3 \
  --camera 0
```

--------------------------------

### Typical Demo Flow Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/03_filters_smoothers.md

Example demonstrating a typical demo flow involving GazeEstimator, calibration, and filter setup.

```python
from eyetrax import GazeEstimator, run_9_point_calibration
from eyetrax.filters import KalmanEMASmoother, make_kalman
import cv2

estimator = GazeEstimator()
run_9_point_calibration(estimator)

# Set up filter
kf = make_kalman()
smoother = KalmanEMASmoother(kf, ema_alpha=0.3)
smoother.tune(estimator)
```

--------------------------------

### Typical GazeEstimator Configurations

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Examples of typical GazeEstimator configurations for different use cases.

```python
# Fast baseline
est1 = GazeEstimator()  # Ridge + defaults

# Responsive (lower blink threshold)
est2 = GazeEstimator(blink_threshold_ratio=0.7)

# Custom model with parameters
est3 = GazeEstimator(
    model_name="tiny_mlp",
    model_kwargs={"hidden_layer_sizes": (128, 64)}
)

# Custom face model
est4 = GazeEstimator(
    face_landmarker_model="/path/to/face_landmarker.task"
)

# Sensitive blink detection (quick skip on blinks)
est5 = GazeEstimator(ear_history_len=20, min_history=10)
```

--------------------------------

### Tiny MLP Configuration

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Configuration for the Tiny MLP model, including its parameters and architecture examples.

```python
GazeEstimator(
    model_name="tiny_mlp",
    model_kwargs={
        "hidden_layer_sizes": (64, 32),
        "activation": "relu",
        "alpha": 1e-4,
        "learning_rate_init": 1e-3,
        "max_iter": 500,
        "early_stopping": True
    }
)
```

--------------------------------

### KalmanEMASmoother Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/03_filters_smoothers.md

Example of initializing and using the KalmanEMASmoother.

```python
smoother_heavy = KalmanEMASmoother(kf, ema_alpha=0.5)
x_smooth, y_smooth = smoother.step(100, 200)
```

--------------------------------

### KalmanEMASmoother Constructor Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/03_filters_smoothers.md

Example of initializing KalmanEMASmoother with light smoothing.

```python
from eyetrax.filters import KalmanEMASmoother, make_kalman

kf = make_kalman()

# Light smoothing (low lag)
smoother = KalmanEMASmoother(kf, ema_alpha=0.1)
```

--------------------------------

### Environment Setup: Custom Face Landmarker Model

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Steps to download a custom face landmarker model and set it as an environment variable for Eyetrack.

```bash
# Download custom model
wget -O face_landmarker.task \
  https://storage.googleapis.com/mediapipe-models/...

# Set environment variable
export EYETRAX_FACE_LANDMARKER_MODEL=/path/to/face_landmarker.task

# Use in Python
estimator = GazeEstimator()  # Automatically uses custom model
```

--------------------------------

### Kalman + EMA Filter Setup

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Initializes a Kalman filter combined with an Exponential Moving Average (EMA) smoother.

```python
from eyetrax.filters import make_kalman, KalmanEMASmoother

kf = make_kalman(process_var=50.0, measurement_var=0.2)
smoother = KalmanEMASmoother(kf, ema_alpha=0.25)
```

--------------------------------

### Configuration Workflow: High Precision (Offline Calibration)

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Python code for a high-precision scenario involving offline calibration, retraining, and custom Kalman filter setup.

```python
from eyetrax import GazeEstimator
from eyetrax.calibration import run_adaptive_calibration
from eyetrax.filters import KalmanEMASmoother, make_kalman

estimator = GazeEstimator(
    model_name="tiny_mlp",
    model_kwargs={"hidden_layer_sizes": (128, 64, 32), "max_iter": 1000}
)
run_adaptive_calibration(estimator, num_random_points=100, retrain_every=20)

kf = make_kalman()
smoother = KalmanEMASmoother(kf, ema_alpha=0.3)
smoother.tune(estimator)

estimator.save_model("precision_model.pkl")
```

--------------------------------

### CLI Configuration via Environment Variables

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Example of configuring Eyetrack using environment variables, specifically for a custom face landmarker model.

```bash
export EYETRAX_FACE_LANDMARKER_MODEL=/path/to/face_landmarker.task
eyetrax-demo
```

--------------------------------

### make_kalman Usage Examples

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/03_filters_smoothers.md

Examples showing how to create Kalman filters with different configurations using make_kalman.

```python
from eyetrax.filters import make_kalman

# Fast, responsive Kalman filter
kf_fast = make_kalman(process_var=100.0, measurement_var=0.1)

# Slow, smooth Kalman filter
kf_smooth = make_kalman(process_var=20.0, measurement_var=0.5)

# Pre-initialized with known starting position
kf_init = make_kalman(init_state=np.array([960, 540, 0, 0]))
```

--------------------------------

### Build new model from scratch

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example of building a new model from scratch.

```bash
# Build new model from scratch
eyetrax-build-model --outfile ~/my_model.pkl
```

--------------------------------

### NoSmoother Step Method Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/03_filters_smoothers.md

Example of using the NoSmoother step method.

```python
from eyetrax.filters import NoSmoother

smoother = NoSmoother()
x_out, y_out = smoother.step(100, 200)  # (100, 200)
```

--------------------------------

### eyetrax-demo Example Usage

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Examples of how to use the eyetrax-demo command with various options.

```bash
# Quick baseline (9-point calibration, no filtering)
eyetrax-demo

# Kalman smoothing with tuning
eyetrax-demo --filter kalman

# Heavy smoothing with EMA
eyetrax-demo --filter kalman_ema --ema-alpha 0.5

# Dense grid calibration for higher precision
eyetrax-demo --calibration dense --grid-rows 7 --grid-cols 7

# MLP model with KDE filtering
eyetrax-demo --model tiny_mlp --filter kde --confidence 0.6

# Use pre-trained model (no calibration)
eyetrax-demo --model-file /path/to/model.pkl

# Custom background image
eyetrax-demo --background /path/to/background.jpg

# Camera 1 instead of 0
eyetrax-demo --camera 1
```

--------------------------------

### Configuration Workflow: Fast Demo (Minimal Calibration)

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Python code for setting up a fast demo with minimal calibration using GazeEstimator and NoSmoother.

```python
from eyetrax import GazeEstimator, run_5_point_calibration
from eyetrax.filters import NoSmoother

estimator = GazeEstimator(model_name="ridge")
run_5_point_calibration(estimator)
smoother = NoSmoother()
```

--------------------------------

### KDESmoother Usage Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/03_filters_smoothers.md

Example demonstrating how to initialize and use the KDESmoother with a gaze stream.

```python
from eyetrax.filters import KDESmoother

smoother = KDESmoother(
    screen_w=1920,
    screen_h=1080,
    time_window=1.0,
    confidence=0.6,
)

for x, y in gaze_stream:
    x_smooth, y_smooth = smoother.step(x, y)
    
    # Optionally draw contours on canvas
    if smoother.debug.get("contours"):
        cv2.drawContours(canvas, smoother.debug["contours"], -1, (0, 255, 0), 2)
```

--------------------------------

### Installation from PyPI

Source: https://github.com/ck-zhang/eyetrax/blob/master/README.md

Installs the EyeTrax library using pip.

```bash
pip install eyetrax
```

--------------------------------

### Workflow 5: Camera Fallback

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example workflow demonstrating camera fallback.

```bash
eyetrax-demo --camera 1  # Use second camera if primary fails
```

--------------------------------

### eyetrax-virtualcam Example Usage

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Examples of how to use the eyetrax-virtualcam command with various options.

```bash
# Basic virtual camera stream
eyetrax-virtualcam

# With Kalman smoothing
eyetrax-virtualcam --filter kalman

# KDE filtering for visualization
eyetrax-virtualcam --filter kde --confidence 0.5

# Dense grid, KDE, MLP
eyetrax-virtualcam --calibration dense --grid-rows 7 --grid-cols 7 --model tiny_mlp --filter kde
```

--------------------------------

### Kalman Filter Recommended Presets

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Pre-configured Kalman filter settings for different responsiveness and smoothness levels.

```python
# Very responsive (low latency, noisier)
make_kalman(process_var=100.0, measurement_var=0.1)

# Balanced (default)
make_kalman(process_var=50.0, measurement_var=0.2)

# Very smooth (high latency, clean)
make_kalman(process_var=20.0, measurement_var=0.5)
```

--------------------------------

### Installation from source

Source: https://github.com/ck-zhang/eyetrax/blob/master/README.md

Clones the repository and installs EyeTrax from source using pip or uv.

```bash
git clone https://github.com/ck-zhang/eyetrax && cd eyetrax

# editable install — pick one
python -m pip install -e .
pip install uv && uv sync
```

--------------------------------

### 9-Point Calibration

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Runs a standard 9-point calibration grid.

```python
run_9_point_calibration(estimator, camera_index=0)
```

--------------------------------

### Kalman Filter Tuning Method

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Demonstrates the interactive tuning process for the Kalman filter.

```python
# After training estimator:
kf = make_kalman()
smoother = KalmanSmoother(kf)
smoother.tune(estimator, camera_index=0)  # Interactive tuning
```

--------------------------------

### CLI Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/INDEX.md

Example of a command-line interface command for eyetrax.

```bash
# Command-line examples shown with $
eyetrax-demo --filter kalman
```

--------------------------------

### 5-Point Calibration Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/02_calibration_functions.md

Example usage of the `run_5_point_calibration` function for a faster calibration.

```python
from eyetrax import GazeEstimator, run_5_point_calibration

estimator = GazeEstimator()
run_5_point_calibration(estimator)  # Faster than 9-point
```

--------------------------------

### Configuration Workflow: Custom Tuning

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Python code demonstrating custom tuning with a specific GazeEstimator model and KDESmoother filter.

```python
from eyetrax import GazeEstimator, run_dense_grid_calibration
from eyetrax.filters import KDESmoother
from eyetrax.utils.screen import get_screen_size

estimator = GazeEstimator(model_name="linear_svr")
run_dense_grid_calibration(
    estimator,
    rows=6, cols=6,
    margin_ratio=0.08,
    pulse_d=1.5,
    cd_d=1.5
)

w, h = get_screen_size()
smoother = KDESmoother(w, h, time_window=0.8, confidence=0.4)
```

--------------------------------

### TinyMLPModel Example Usage

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/04_models.md

Example of initializing a GazeEstimator with the TinyMLPModel, customizing its parameters and running a calibration.

```python
from eyetrax import GazeEstimator, run_dense_grid_calibration

estimator = GazeEstimator(
    model_name="tiny_mlp",
    model_kwargs={
        "hidden_layer_sizes": (128, 64, 32),
        "activation": "relu",
        "learning_rate_init": 5e-4,
        "max_iter": 1000,
    }
)
run_dense_grid_calibration(estimator, rows=7, cols=7)
```

--------------------------------

### Output from build_model

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example output messages from the build_model command.

```text
[build_model] Loading base model from ...
[build_model] Saved calibrated model → /path/to/model.pkl
```

--------------------------------

### Dense Grid Calibration Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/02_calibration_functions.md

Example demonstrating `run_dense_grid_calibration` with custom grid size, margins, and timings.

```python
from eyetrax import GazeEstimator
from eyetrax.calibration import run_dense_grid_calibration

estimator = GazeEstimator()

# 7x7 grid with 8% margins, slower collection (2 sec each)
run_dense_grid_calibration(
    estimator,
    rows=7,
    cols=7,
    margin_ratio=0.08,
    order="serpentine",
    pulse_d=1.0,
    cd_d=2.0,
)
```

--------------------------------

### RidgeModel Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/04_models.md

Example demonstrating how to instantiate and use the RidgeModel with GazeEstimator and run a calibration.

```python
from eyetrax import GazeEstimator, run_9_point_calibration

estimator = GazeEstimator(
    model_name="ridge",
    model_kwargs={\"alpha\": 0.5}
)
run_9_point_calibration(estimator)
```

--------------------------------

### 5-Point Calibration

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Runs a faster 5-point calibration grid (corners + center).

```python
run_5_point_calibration(estimator, camera_index=0)
```

--------------------------------

### Model Configuration Examples

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/07_types_and_constants.md

Examples of keyword arguments for different model types when instantiating GazeEstimator.

```python
# Ridge with custom alpha
{"alpha": 0.5}

# ElasticNet with L1/L2 balance
{"alpha": 0.1, "l1_ratio": 0.7}

# LinearSVR with large margin
{"C": 10.0, "epsilon": 1.0}

# Tiny MLP with deep architecture
{
    "hidden_layer_sizes": (128, 64, 32),
    "activation": "relu",
    "learning_rate_init": 5e-4,
    "max_iter": 1000,
}
```

--------------------------------

### ElasticNetModel Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/04_models.md

Example demonstrating how to instantiate the ElasticNetModel with GazeEstimator, configuring regularization parameters.

```python
from eyetrax import GazeEstimator

estimator = GazeEstimator(
    model_name="elastic_net",
    model_kwargs={\"alpha\": 0.1, \"l1_ratio\": 0.7}  # More L1 weight
)
```

--------------------------------

### Workflow 3: OBS Streaming

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example workflow for OBS streaming using a virtual camera feed.

```bash
eyetrax-virtualcam --calibration dense --grid-rows 7 --grid-cols 7 \
  --filter kde --confidence 0.6
```

--------------------------------

### KalmanSmoother Step Method Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/03_filters_smoothers.md

Example of applying Kalman filtering to smooth gaze coordinates.

```python
from eyetrax.filters import make_kalman, KalmanSmoother

kf = make_kalman(process_var=50.0, measurement_var=0.2)
smoother = KalmanSmoother(kf)

for x, y in gaze_stream:
    x_smooth, y_smooth = smoother.step(x, y)
    print(f"Smoothed: ({x_smooth}, {y_smooth})")
```

--------------------------------

### make_thumbnail example usage

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/05_utilities.md

An example demonstrating how to use the make_thumbnail function to create a bordered thumbnail from a video frame and print its shape.

```python
from eyetrax.utils.draw import make_thumbnail
import cv2

cap = cv2.VideoCapture(0)
ret, frame = cap.read()

thumb = make_thumbnail(frame, size=(320, 240), border=3, border_color=(0, 255, 0))
print(f"Thumbnail shape: {thumb.shape}")
```

--------------------------------

### KalmanSmoother Tune Method Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/03_filters_smoothers.md

Example of interactively tuning the Kalman filter's measurement noise.

```python
from eyetrax import GazeEstimator, run_9_point_calibration
from eyetrax.filters import KalmanSmoother, make_kalman

estimator = GazeEstimator()
run_9_point_calibration(estimator)

kf = make_kalman()
smoother = KalmanSmoother(kf)
smoother.tune(estimator, camera_index=0)  # Auto-tunes measurement noise
```

--------------------------------

### Example for Custom Smoother Class

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/09_module_design.md

A Python example demonstrating how to create a custom smoother by inheriting from BaseSmoother.

```python
class CustomSmoother(BaseSmoother):
    def __init__(self, param1=10):
        super().__init__()
        self.param1 = param1
    
    def step(self, x: int, y: int) -> Tuple[int, int]:
        # Your smoothing logic
        return x_filtered, y_filtered
```

--------------------------------

### Example for Custom Model Class

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/09_module_design.md

A Python example showing how to implement a new custom model by inheriting from BaseModel and registering it.

```python
class MyModel(BaseModel):
    def __init__(self, param1=1.0):
        super().__init__()
        self._init_native(param1=param1)
    
    def _init_native(self, **kw):
        self.model = SomeRegressor(**kw)
    
    def _native_train(self, X, y):
        self.model.fit(X, y)
    
    def _native_predict(self, X):
        return self.model.predict(X)

register_model("mymodel", MyModel)
```

--------------------------------

### Faster calibration, less data

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example of a faster calibration with less data.

```bash
# Faster calibration, less data
eyetrax-build-model --outfile ~/quick.pkl --random 20 --retrain-every 5
```

--------------------------------

### LinearSVRModel Example Usage

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/04_models.md

Example of initializing a GazeEstimator with the LinearSVRModel, customizing its parameters.

```python
from eyetrax import GazeEstimator

estimator = GazeEstimator(
    model_name="linear_svr",
    model_kwargs={"C": 10.0, "epsilon": 1.0}
)
```

--------------------------------

### Dense Grid Calibration

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Runs a calibration with a configurable dense grid.

```python
run_dense_grid_calibration(
    gaze_estimator,
    rows=5,
    cols=5,
    margin_ratio=0.10,
    order="serpentine",
    pulse_d=0.9,
    cd_d=0.9,
    camera_index=0,
)
```

--------------------------------

### Quick Baseline Workflow

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/04_models.md

Example of setting up a GazeEstimator with the default 'ridge' model and running a quick 5-point calibration.

```python
from eyetrax import GazeEstimator, run_5_point_calibration

estimator = GazeEstimator(model_name="ridge")  # Default
run_5_point_calibration(estimator)
estimator.save_model("quick.pkl")
```

--------------------------------

### Adaptive Calibration

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Runs an adaptive calibration that retrains based on new data.

```python
run_adaptive_calibration(
    gaze_estimator,
    num_random_points=60,
    retrain_every=10,
    show_predictions=True,
    camera_index=0,
)
```

--------------------------------

### Python Code Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/INDEX.md

Example of how to import and instantiate the GazeEstimator class.

```python
# Example code shown in Python
from eyetrax import GazeEstimator
estimator = GazeEstimator()
```

--------------------------------

### run_adaptive_calibration Example Usage

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/02_calibration_functions.md

An example demonstrating how to use the run_adaptive_calibration function with various parameters and saving the trained model.

```python
from pathlib import Path
from eyetrax import GazeEstimator
from eyetrax.calibration import run_adaptive_calibration

estimator = GazeEstimator(model_name="tiny_mlp")
run_adaptive_calibration(
    estimator,
    num_random_points=80,
    retrain_every=20,
    show_predictions=True,
)
estimator.save_model("adaptive_model.pkl")
```

--------------------------------

### run_lissajous_calibration Example Usage

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/02_calibration_functions.md

An example demonstrating how to use the run_lissajous_calibration function with a GazeEstimator instance.

```python
from eyetrax import GazeEstimator, run_lissajous_calibration

estimator = GazeEstimator()
run_lissajous_calibration(estimator)
```

--------------------------------

### Model Registration Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/09_module_design.md

Example of how model modules register themselves with the model factory upon import.

```python
# In ridge.py
register_model("ridge", RidgeModel)

# In elastic_net.py
register_model("elastic_net", ElasticNetModel)
```

--------------------------------

### create_model Example Usage

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/04_models.md

Example of using the create_model factory function to programmatically create a model instance.

```python
from eyetrax.models import create_model

# Programmatic model creation
model = create_model("tiny_mlp", hidden_layer_sizes=(128, 64))
print(f"Created: {model.__class__.__name__}")
```

--------------------------------

### Workflow 2: High-Precision Offline Calibration

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example workflow for high-precision offline calibration.

```bash
eyetrax-build-model --outfile my_calibration.pkl \
  --model tiny_mlp \
  --random 100 \
  --retrain-every 20
```

--------------------------------

### Workflow 4: Model Refinement

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example workflow for iteratively refining a model.

```bash
# Initial calibration
eyetrax-build-model --outfile base.pkl

# Later: refine with more data
eyetrax-build-model --outfile refined.pkl --base base.pkl --random 60
```

--------------------------------

### compute_grid_points Example Usage

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/02_calibration_functions.md

An example demonstrating how to use compute_grid_points to generate pixel coordinates for a 3x3 grid.

```python
from eyetrax.calibration import compute_grid_points

# 3x3 grid: corners + edges + center
order = [(0, 0), (0, 1), (0, 2), (1, 0), (1, 1), (1, 2), (2, 0), (2, 1), (2, 2)]
points = compute_grid_points(order, 1920, 1080, margin_ratio=0.1)
# points = [(192, 108), (960, 108), (1728, 108), ...]
```

--------------------------------

### Lissajous Calibration

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Runs a Lissajous curve tracing calibration.

```python
run_lissajous_calibration(gaze_estimator, camera_index=0)
```

--------------------------------

### Example Skeleton for Custom Calibration Method

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/09_module_design.md

A Python skeleton for implementing a new custom calibration method.

```python
def run_custom_calibration(gaze_estimator, camera_index=0):
    cap = open_camera(camera_index)
    # ... your calibration logic ...
    feats, targs = collect_data(cap, gaze_estimator)
    gaze_estimator.train(np.array(feats), np.array(targs))
    cap.release()
    cv2.destroyAllWindows()
```

--------------------------------

### Minimal Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/00_README.md

A basic example demonstrating how to initialize GazeEstimator, perform calibration, and predict gaze in a real-time loop.

```python
from eyetrax import GazeEstimator, run_9_point_calibration
import cv2

# Create estimator
estimator = GazeEstimator()

# Calibrate with 9-point grid
run_9_point_calibration(estimator)

# Use in real-time loop
cap = cv2.VideoCapture(0)
while True:
    ret, frame = cap.read()
    features, blink = estimator.extract_features(frame)
    
    if features is not None and not blink:
        x, y = estimator.predict([features])[0]
        print(f"Gaze at ({x:.0f}, {y:.0f})")
    
    if cv2.waitKey(1) == 27:  # ESC
        break

cap.release()
estimator.save_model("my_model.pkl")
```

--------------------------------

### Method Signature Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/INDEX.md

Example of a method signature with full type annotations and return types.

```python
def method(param: type = default) -> return_type
```

--------------------------------

### More points for higher precision

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example of building a model with more random points for higher precision.

```bash
# More points for higher precision
eyetrax-build-model --outfile ~/precise_model.pkl --random 100 --retrain-every 25
```

--------------------------------

### Use MLP instead of Ridge

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example of using the MLP model instead of Ridge.

```bash
# Use MLP instead of Ridge
eyetrax-build-model --outfile ~/mlp_model.pkl --model tiny_mlp --random 80
```

--------------------------------

### Elastic Net Configuration

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Configuration for the Elastic Net model, including its parameters and tuning guidance.

```python
GazeEstimator(
    model_name="elastic_net",
    model_kwargs={"alpha": 1.0, "l1_ratio": 0.5}
)
```

--------------------------------

### Fixed Grid Calibration Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/07_types_and_constants.md

Representation of a 9-point fixed calibration grid.

```text
(0,0)  (1,0)  (2,0)
(0,1)  (1,1)  (2,1)
(0,2)  (1,2)  (2,2)
```

--------------------------------

### Start from existing model

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/04_models.md

This snippet shows how to load an existing GazeEstimator model and then refine it with additional data using `run_adaptive_calibration`.

```python
estimator = GazeEstimator(model_name="linear_svr")
estimator.load_model("existing_model.pkl")

# Refine with additional data
run_adaptive_calibration(estimator, num_random_points=40)
estimator.save_model("refined_model.pkl")
```

--------------------------------

### Linear SVR Configuration

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Configuration for the Linear SVR model, including its parameters and tuning guidance.

```python
GazeEstimator(
    model_name="linear_svr",
    model_kwargs={
        "C": 5.0,
        "epsilon": 5.0,
        "loss": "epsilon_insensitive",
        "fit_intercept": True
    }
)
```

--------------------------------

### Refine existing model with additional data

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example of refining an existing model with additional data.

```bash
# Refine existing model with additional data
eyetrax-build-model --outfile ~/refined.pkl --base ~/my_model.pkl --random 40
```

--------------------------------

### GazeEstimator Constructor Examples

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/01_gaze_estimator.md

Demonstrates creating a GazeEstimator instance with default settings, custom model arguments, or a custom face landmarker model.

```python
from eyetrax import GazeEstimator

# Use default Ridge regression model
estimator = GazeEstimator()

# Use MLP with custom hidden layers
estimator = GazeEstimator(
    model_name="tiny_mlp",
    model_kwargs={"hidden_layer_sizes": (128, 64)}
)

# Use custom face landmarker model
estimator = GazeEstimator(
    face_landmarker_model="/path/to/face_landmarker.task"
)
```

--------------------------------

### Ridge Regression Configuration

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

Configuration for the Ridge Regression model, including its parameters and tuning guidance.

```python
GazeEstimator(
    model_name="ridge",
    model_kwargs={"alpha": 1.0}
)
```

--------------------------------

### Using CLI

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/00_README.md

Examples of using the EyeTrax command-line interface for demos, calibration, and virtual camera streaming.

```bash
# Quick demo with Kalman smoothing
eyetrax-demo --filter kalman

# High-precision offline calibration
eyetrax-build-model --outfile my_model.pkl \
  --model tiny_mlp \
  --random 100

# Stream to virtual camera
eyetrax-virtualcam --calibration dense --grid-rows 7 --grid-cols 7
```

--------------------------------

### Reusable Calibration Utilities

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/09_module_design.md

Example functions for shared calibration infrastructure, including waiting for a face and capturing features during a pulse.

```python
def wait_for_face_and_countdown(cap, estimator, sw, sh, dur):
    # Wait for face + 2-sec countdown
    # Returns True if successful, False if cancelled

def _pulse_and_capture(estimator, cap, points, sw, sh, pulse_d, cd_d):
    # For each point: pulse animation + capture loop
    # Returns (features, targets) collected
```

--------------------------------

### High-Precision Calibration Workflow

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/04_models.md

Example of configuring a GazeEstimator with the 'tiny_mlp' model for high-precision calibration using adaptive calibration.

```python
from eyetrax import GazeEstimator
from eyetrax.calibration import run_adaptive_calibration

estimator = GazeEstimator(
    model_name="tiny_mlp",
    model_kwargs={"hidden_layer_sizes": (128, 64, 32), "max_iter": 2000}
)
run_adaptive_calibration(
    estimator,
    num_random_points=100,
    retrain_every=20,
)
estimator.save_model("high_precision.pkl")
```

--------------------------------

### 9-Point Calibration Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/02_calibration_functions.md

Example usage of the `run_9_point_calibration` function to calibrate the GazeEstimator model.

```python
from eyetrax import GazeEstimator, run_9_point_calibration

estimator = GazeEstimator()
run_9_point_calibration(estimator, camera_index=0)

# Model is now trained
estimator.save_model("model.pkl")
```

--------------------------------

### Hardware Options

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Option for specifying the camera device index.

```bash
--camera 0            # Webcam device index (default 0)
```

--------------------------------

### Gaze Coordinates Example

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/07_types_and_constants.md

Example usage of gaze coordinates, showing a single point and an array of points.

```python
x, y = 1920.5, 1080.3  # Center of 4K screen
gaze_array = np.array([[960, 540], [100, 200]])  # Multiple predictions
```

--------------------------------

### draw_cursor example usage

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/05_utilities.md

An example demonstrating how to use the draw_cursor function to draw a gaze cursor on a canvas with specified parameters.

```python
from eyetrax.utils.draw import draw_cursor
import cv2
import numpy as np

canvas = np.zeros((1080, 1920, 3), dtype=np.uint8)

# Draw red cursor with white center, 60% opacity
draw_cursor(
    canvas,
    x=960,
    y=540,
    alpha=0.6,
    radius_outer=40,
    radius_inner=30,
    color_outer=(0, 0, 255),
    color_inner=(255, 255, 255),
)

cv2.imshow("Cursor", canvas)
```

--------------------------------

### Dense Grid Options

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Options for configuring the dense grid calibration.

```bash
--grid-rows 7        # Grid height (default 5)
--grid-cols 8        # Grid width (default 5)
--grid-margin 0.08   # Edge margin as fraction (default 0.10)
```

--------------------------------

### Disable live predictions (faster)

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

Example of disabling live predictions for faster calibration.

```bash
# Disable live predictions (faster)
eyetrax-build-model --outfile "model.pkl" --show-pred=false
```

--------------------------------

### Kalman + EMA Filter Formula

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

The formula used for smoothing in the Kalman + EMA filter.

```plaintext
output = ema_alpha * prev_output + (1 - ema_alpha) * kalman_output
```

--------------------------------

### Available Models

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/06_cli_reference.md

List of available models for regression.

```bash
--model ridge           # Linear regression (default, fastest)
--model elastic_net     # Ridge + Lasso combo
--model linear_svr      # Support Vector Regression
--model tiny_mlp        # Neural network (most accurate, slowest)
```

--------------------------------

### Recommended Pattern for Multi-threaded Use

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/09_module_design.md

Illustrates how to manage GazeEstimator and Smoother instances in a multi-threaded environment by creating per-thread instances.

```python
# Create per-thread instances
estimator = GazeEstimator()  # One per thread
smoother = NoSmoother()       # One per thread
```

--------------------------------

### Run on-screen gaze overlay demo

Source: https://github.com/ck-zhang/eyetrax/blob/master/README.md

Launches the demo with Kalman smoothing.

```bash
eyetrax-demo --filter kalman
```

--------------------------------

### GazeEstimator Constructor Parameters

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/08_configuration_guide.md

The GazeEstimator class constructor with its parameters and their types, defaults, ranges, and notes.

```python
GazeEstimator(
    model_name: str = "ridge",
    model_kwargs: dict | None = None,
    face_landmarker_model: str | os.PathLike[str] | None = None,
    ear_history_len: int = 50,
    blink_threshold_ratio: float = 0.8,
    min_history: int = 15,
)
```

--------------------------------

### Stream overlay to virtual webcam

Source: https://github.com/ck-zhang/eyetrax/blob/master/README.md

Starts the virtual camera stream with KDE smoothing and 5-point calibration.

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

--------------------------------

### Feature Standardization in Training

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/09_module_design.md

Example of feature standardization using StandardScaler within the BaseModel.train() method.

```python
def train(self, X, y, variable_scaling=None):
    # Step 1: Fit StandardScaler
    Xs = self.scaler.fit_transform(X)
    
    # Step 2: Optional per-feature scaling
    if variable_scaling is not None:
        Xs *= variable_scaling
    
    # Step 3: Train underlying model
    self._native_train(Xs, y)
```

--------------------------------

### Fallback Camera Index

Source: https://github.com/ck-zhang/eyetrax/blob/master/_autodocs/00_README.md

Example of trying a fallback camera index when the default camera cannot be opened.

```python
# Try fallback camera index
estimator = GazeEstimator()
run_9_point_calibration(estimator, camera_index=1)
```