Oculomotor, Blink & Pupillometry Bench

A dual-eye video-oculography (VOG), blink morphology, and visible-light pupillometry recording bench in the experiences gallery. Rather than displaying a full-face webcam feed, it locks onto the medial and lateral canthi of both eyes, compensates head roll angle to 0 deg, and isolates only the two zoomed periocular eye scopes (OD · Right Eye and OS · Left Eye) alongside the pixel-level computer vision and electrophysiological coupling models running behind the scenes.

Open it from cloud.pieeg.com -> V -> Oculomotor, Blink & Pupillometry Bench. Registry id: oculomotor-bench. Tag: Lab / Oculomotor.

Three-tier measurement taxonomy

The bench separates direct periocular pixel readouts from geometric/kinematic estimates and experimental reflex/coupling models in both the UI (TierBadge) and exported files (OCULOMOTOR_CAVEATS):

What it is (and is not)

Live loop

1. Hidden high-resolution acquisition - getUserMedia requests 1280x720 at 30 Hz (facingMode: "user") into an offscreen <video style={{ display: "none" }}> element. The full face frame is never drawn to the screen, maximizing pixel density across the iris while keeping screen space dedicated to the two periocular instruments.
2. Bilateral canthal lock & roll rectification - DualEyeFrameSampler extracts the outer and inner canthi for the right eye (OD: landmarks 33, 133) and left eye (OS: landmarks 362, 263), computes the inter-canthal roll angle theta_roll = atan2(dy, dx), and affine-transforms each periocular region into a roll-stabilized 96x56 canvas so the palpebral fissure remains strictly horizontal even during head tilt.
3. Behind-the-scenes pixel segmentation & chord profiling - analyzeEyePatchBuffer computes red-weighted luminance I(x, y) = 0.52 R + 0.36 G + 0.12 B (which increases melanin boundary contrast in visible light), evaluates the 2D Sobel gradient magnitude |grad I|, masks specular corneal Purkinje glints above glintThresholdDn, and segments the dark pupil core against the surrounding iris stroma annulus.
4. Blink hold-last-valid & uniform 30 Hz resampling - OculomotorSignalEngine resamples non-uniform camera timestamps onto a uniform 30 Hz grid (UNIFORM_OCULO_HZ = 30), holds pupil diameter across brief eyelid closures (apertureRatio < 0.14) so blink occlusion does not inject false constriction spikes, and applies forward-backward zero-phase 2nd-order Butterworth lowpass filtering (lowpassZeroPhase).
5. Online Optical-to-Bio L2 Ridge Coupling - Concurrent PiEEG bio frames from subscribeEegSamples are interpolated onto the uniform window and fit via L2-regularized least squares against four standardized optical predictors: [eyelidClosure, eyelidVel, gazeAzimuth, gazeElevation].

Five-panel workbench layout

Behind-the-scenes pixel segmentation & chord profile

Clicking the OD or OS viewport in Panel 1 (or the Inspect OD / OS Pixels buttons in Panel 3) selects that eye for pixel-level inspection.

Three viewport pixel modes (Panel 1)

Adaptive dark-pupil threshold & iris normalization

To prevent head Z-distance movements from masquerading as pupil dilation, the bench measures the pupil diameter D_pupil relative to the visible iris diameter D_iris (11.7 mm anatomical reference):

1. Iris stroma annulus (0.58 <= r / R_iris <= 0.92): Excluding pixels above glintThresholdDn (default 232 DN) and upper/lower eyelid zones, the 60th percentile luminance estimates I_iris.
2. Dark pupil core (r / R_iris <= 0.38): The 20th percentile luminance estimates I_min.
3. Adaptive threshold (T_pupil):

   T_pupil = I_min + alpha * max(4, I_iris - I_min)
   where alpha is configurable in Panel 4 (pupilThresholdAlpha, default 0.38).
4. Iris-to-pupil contrast SNR (dB):

   SNR_contrast_dB = 10 * log10( (I_iris - I_min)^2 / Var(I_stroma) )
   When SNR_contrast_dB < minContrastSnrDb (default 3.0 dB), pupilGatedPass trips to false.
5. Combined area + chord radius: The dark-pupil radius combines the 2D segmented pixel area (sqrt(A_pupil / pi)) and the 1D horizontal chord width below T_pupil (0.6 * R_area + 0.4 * R_chord), yielding pupilIrisRatio = R_pupil / R_iris.

Oculomotor, blink & PLR algorithms

Ballistic blink kinematics (detectBlinkKinematics)

Spontaneous and voluntary blinks exhibit an asymmetric velocity profile: fast ballistic closure driven by the orbicularis oculi (dA/dt < 0) followed by slower opening driven by the levator palpebrae superioris (dA/dt > 0).

• Baseline: 75th percentile of binocular palpebral aperture A(t) over the analysis window.
• Closure gate: A(t) < max(0.06, 0.62 * A_baseline) with duration between 65 ms and 950 ms and peak closing speed |min(dA/dt)| > 0.35 /s.
• Reported metrics: durationMs, minApertureRatio, peakClosingVelPerSec, peakOpeningVelPerSec, and velocityRatio = |peakClosingVel| / peakOpeningVel.

Pupillary Light Reflex (PLR) step analyzer (analyzePlrAndHippus)

Clicking ⚡ Trigger PLR Flash in Panel 1 applies a 3.5 s high-luminance screen bezel step (stimulus.luminance01: 0.10 -> 0.95) and logs a plr_flash_onset marker. Across any rising stimulus step in the active window, analyzePlrAndHippus computes:

• Baseline ratio (baselineRatio): Mean D_pupil / D_iris over the 1.2 s preceding flash onset.
• Constriction latency (latencyMs): Delay from flash onset (t_flash) to the first sample (t >= t_flash + 140 ms) where pupil ratio drops by at least 0.015 and constriction velocity d(D/D_iris)/dt < -0.06 /s.
• Constriction amplitude (constrictionPct): (baselineRatio - minConstrictedRatio) / baselineRatio * 100%.
• Peak constriction velocity (maxConstrictionVelPerSec): Maximum downward slope -min(d(D/D_iris)/dt) during the constriction phase.
• Redilation recovery (recoveryT63Ms): Time after minimum constriction required to recover 63.2% (1 - 1/e) of the constriction amplitude.
• Hippus PSD: Hann-windowed discrete Fourier transform of the demeaned pupil ratio across [0.05 Hz, 1.50 Hz] at 0.025 Hz resolution.

Fixation stability (computeBceaDeg2)

Fixation dispersion is quantified by the 68% Bivariate Contour Ellipse Area (BCEA, k = 1.14) across horizontal azimuth sigma_x and vertical elevation sigma_y (in visual degrees):

BCEA_68 = 2 * k * pi * sigma_x * sigma_y * sqrt(1 - rho_xy^2)

Online Optical-to-Bio L2 Ridge Coupling (fitOpticalBioCoupling)

The corneal-retinal standing potential (~0.4 to 1.0 mV, cornea positive relative to retina) and eyelid sliding capacitance project strongly onto frontal and periocular EEG/EOG electrodes. Over the uniform 30 Hz window (N samples), the bench standardizes four optical predictors:

• x_0(t) = -zscore(apertureWave) (eyelid closure)
• x_1(t) = zscore(eyelidVelocityWave) (dA/dt)
• x_2(t) = zscore(gazeAzimuthDegWave) (horizontal gaze)
• x_3(t) = zscore(gazeElevationDegWave) (vertical gaze)

For each active PiEEG bio channel y_c(t), the bench solves the 4x4 L2-regularized normal equations via Gaussian elimination with partial pivoting:

beta_c = ( (1/N) X^T X + lambda * I_4 )^-1 * ( (1/N) X^T z_c )

where lambda is config.ridgeLambda (default 0.15). Panel 2 overlays the reconstructed ocular prediction y_hat_c(t) (in uV) directly on top of the measured bio channel y_c(t), while Panel 3 reports the explained variance R² (0 - 100%), zero-lag blink correlation r_blink, and standardized weights beta_close, beta_Az, beta_El.

Two clocks & technical validation strip

Optical frames and PiEEG bio samples are captured on independent browser arrival clocks anchored to a shared session t0Sec:

Header technical validation strip

The header continuously monitors 6 acquisition quality metrics over the trailing 120 frames:

• FPS: Measured frame rate (>= 18 Hz green).
• dt / Jitter: Mean inter-frame interval ± standard deviation in ms (jitter < 15 ms green).
• Eye Lock: Percentage of frames with bilateral canthal landmark lock (>= 85% green).
• Roll Comp: Measured head roll angle compensated to 0 deg in the dual eye viewports (|roll| < 25 deg green).
• Iris-Pupil SNR: Mean iris-to-pupil contrast SNR in dB (>= minContrastSnrDb green).
• Illumination: Stable vs. SHIFT (warns if periocular luminance shifts by more than 12% when no photic stimulus is active).

Reference validation datasets & offline reprocessing

Built-in synthetic reference datasets

Panel 4 provides three deterministic 30 Hz synthetic datasets (generateOculomotorValidationDataset), complete with synthesized 96x56 eye pixel patches and synchronized 250 Hz 4-channel bio streams (Fp1, Fp2, HEOG, Oz):

Offline reprocessing (reprocessOculomotorTake)

Clicking Reprocess Take in Panel 4 reconstructs the session frames and re-runs OculomotorSignalEngine with updated dark-pupil threshold alpha, glint ceiling, lowpass cutoff, SNR gate, or L2 ridge penalty lambda.

Take format oculomotor-bench-take:v1

JSON export (session_YYYYMMDD_HHMMSS.json)

{
  "format": "oculomotor-bench-take:v1",
  "metadata": {
    "sessionName": "dual_eye_plr_run01",
    "subjectId": "S01",
    "lightingCondition": "controlled_ambient",
    "notes": "",
    "createdAtIso": "2026-10-18T12:00:00.000Z",
    "algorithmVersion": "vog-core:1.0.0",
    "processingConfig": {
      "pupilThresholdAlpha": 0.38,
      "glintThresholdDn": 232,
      "windowSec": 10,
      "pupilLowpassHz": 3.5,
      "minContrastSnrDb": 3.0,
      "ridgeLambda": 0.15,
      "referenceBioChannel": 0
    }
  },
  "durationSec": 12.0,
  "caveats": [
    "[Tier 1 - Direct Optical] ...",
    "[Tier 2 - Algorithm Estimate] ...",
    "[Tier 3 - Experimental Metric] ..."
  ],
  "events": [
    { "t": 3.0, "text": "plr_flash_onset", "source": "stimulus" },
    { "t": 6.5, "text": "plr_flash_offset", "source": "stimulus" }
  ],
  "samples": [
    {
      "camT": 0.0,
      "procT": 0.0018,
      "latencyMs": 1.8,
      "eyesDetected": true,
      "trackingConfidence": 0.97,
      "headRollDeg": 0.0,
      "odApertureRatio": 0.31,
      "osApertureRatio": 0.307,
      "odPupilIrisRatio": 0.48,
      "osPupilIrisRatio": 0.482,
      "odPupilMm": 5.616,
      "osPupilMm": 5.644,
      "odGazeAzimuthDeg": 0.0,
      "odGazeElevationDeg": 0.0,
      "osGazeAzimuthDeg": 0.0,
      "osGazeElevationDeg": 0.0,
      "vergenceDeg": 0.0,
      "eyelidVelPerSec": 0.0,
      "saccadeVelDegPerSec": 0.0,
      "odContrastSnrDb": 11.4,
      "osContrastSnrDb": 11.4,
      "periocularLumaDn": 142.6,
      "stimulusProtocol": "plr_step_flash",
      "stimulusLuminance01": 0.1,
      "targetAzimuthDeg": 0,
      "targetElevationDeg": 0
    }
  ],
  "bio": {
    "sampleRate": 250,
    "channels": 4,
    "t": [0.0, 0.004, "..."],
    "ch": ["...frame-major packed uV samples"]
  }
}

CSV export (session_YYYYMMDD_HHMMSS.csv)

Each row corresponds to one optical frame with 26 columns:

• Timing & lock: cam_t_sec, proc_t_sec, latency_ms, eyes_detected, tracking_conf, head_roll_deg
• Aperture & pupillometry (T1 / T2): od_aperture_ratio, os_aperture_ratio, od_pupil_iris_ratio, os_pupil_iris_ratio, od_pupil_mm, os_pupil_mm
• Oculomotor gaze & kinematics (T2): od_gaze_azimuth_deg, od_gaze_elevation_deg, os_gaze_azimuth_deg, os_gaze_elevation_deg, vergence_deg, eyelid_vel_per_sec, saccade_vel_deg_per_sec
• Contrast & stimulus: od_contrast_snr_db, os_contrast_snr_db, periocular_luma_dn, stimulus_protocol, stimulus_luminance_01, target_azimuth_deg, target_elevation_deg

Controls

Limits

• Visible-light RGB pupillometry requires adequate pigmentation contrast between the dark pupil and iris stroma; dark brown irises under dim or oblique lighting reduce SNR_contrast_dB and trip the contrast gate (minContrastSnrDb).
• At 30 Hz webcam framing (33.3 ms frame interval), peak saccadic velocities and peak blink closing velocities are lower-bounded by temporal sampling compared to 250-1000 Hz infrared eye trackers.
• Millimeter conversions (pupilMm, apertureMm) assume standard adult anatomical constants (11.7 mm horizontal visible iris diameter, 30.0 mm palpebral canthal span); use the dimensionless ratios (pupilIrisRatio, apertureRatio) for within-subject statistical comparisons.
• Optical and PiEEG bio streams share a monotonic browser arrival clock (performance.now()) rather than a hardware trigger pulse.

Related