Camera and Light Sources
========================

Camera Model
------------

The camera is modeled as a pinhole projection system that transforms 3D world coordinates to
2D image coordinates through standard perspective projection. PyEtSimul uses OpenCV to
perform the projection with intrinsic matrix :math:`K`:

.. math::

   K = \begin{bmatrix}
   f_x & 0 & c_x \\
   0 & f_y & c_y \\
   0 & 0 & 1
   \end{bmatrix}

where :math:`(f_x, f_y)` are focal lengths in pixels and :math:`(c_x, c_y)` is the principal
point. After projection, points that fall outside the image bounds or behind the camera are
marked as invalid.

Lens Distortion
^^^^^^^^^^^^^^^

When distortion coefficients are provided, a radial-tangential distortion model is applied
with parameters :math:`(k_1, k_2, p_1, p_2, k_3)`, where :math:`k_i` are radial distortion
coefficients and :math:`p_i` are tangential distortion coefficients. This enables simulation
of real camera optics by importing calibration parameters from actual hardware. Without
distortion coefficients, the model defaults to an ideal pinhole camera.

Pupil Center Estimation
^^^^^^^^^^^^^^^^^^^^^^^

Two methods are available to estimate the pupil center from projected boundary points:

1. **Ellipse fitting** (default): An ellipse is fit to the boundary points and its geometric
   center is returned.
2. **Center of mass**: Computes the centroid from a filled polygon mask of the pupil boundary.

Camera Noise Model
^^^^^^^^^^^^^^^^^^

Measurement uncertainty is simulated by adding random perturbations to projected image
coordinates:

- **Uniform noise**: Perturbations are sampled from :math:`U(-\sigma, \sigma)` independently
  for :math:`x` and :math:`y` coordinates.
- **Gaussian noise**: Perturbations are sampled from :math:`\mathcal{N}(0, \sigma^2)`
  independently in each dimension.

Light Sources
-------------

Light sources are modeled as ideal point lights specified by position in the world frame,
where light is emitted equally in all directions. Any number of lights may be used
simultaneously. Corneal reflections are generated by geometric reflection of each light on
the corneal surface, and the resulting image locations are obtained by camera projection.

Corneal Reflection Detection Noise
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The optical model produces geometrically exact corneal reflection positions. However, in real
eye trackers, corneal reflection localization is subject to measurement uncertainty due to
factors such as limited spatial resolution, image noise, and thresholding algorithms.

Two noise modes are supported:

**Simple mode**: Independent Gaussian noise :math:`\mathcal{N}(0, \sigma^2)` or uniform noise
:math:`U(-\sigma\sqrt{3}, \sigma\sqrt{3})` is added to corneal reflection coordinates, or a
constant offset can be applied.

**Advanced mode**: Correlated bivariate Gaussian noise is specified by a mean vector
:math:`\boldsymbol{\mu} = [\mu_x, \mu_y]^T` and covariance matrix :math:`\boldsymbol{\Sigma}`:

.. math::

   \boldsymbol{\Sigma} = \begin{bmatrix}
   \sigma_x^2 & \rho\sigma_x\sigma_y \\
   \rho\sigma_x\sigma_y & \sigma_y^2
   \end{bmatrix}

This allows modeling systematic bias and correlated errors in :math:`x` and :math:`y`
directions, which can arise from asymmetric point spread functions or detection algorithms.