GazeTracking API Documentation
Welcome! This documentation covers the comprehensive API for the GazeTracking experiment platform, including advanced eye tracking features with head movement compensation and adaptive sampling.
Key Features
GazeTracking is a browser-based eye tracking experiment platform built on WebGazer.js and TensorFlow.js. It provides:
| Feature | Description | Benefit |
|---|---|---|
| Kalman Filtering | Real-time smoothing of gaze coordinates | 15-25% accuracy improvement, reduces jitter |
| Head Pose Compensation | Tracks roll, pitch, yaw from facial landmarks | Maintains accuracy during head movement |
| Outlier Detection | Rejects invalid gaze points (>500px jumps) | Eliminates tracking errors from dataset |
| Adaptive Sampling | 30-60fps based on movement speed | Optimizes performance and data quality |
| Calibration Validation | Automatic quality checks with refinement | Ensures accuracy before experiments |
| Periodic Recalibration | Quick 3-point recal every 10 trials | Maintains accuracy during long sessions |
Technical Architecture
Core Components
The system is built with several key components:
- TrialManager - Main class orchestrating experiments, trials, and data collection
- WebGazer.js - TensorFlow.js-based eye tracking engine with TFFacemesh tracker
- Kalman Filter - Signal processing for smooth gaze trajectories
- Head Pose Tracker - Facial landmark analysis for movement compensation
- LocalForage - Client-side storage for experiment data
Data Flow Pipeline
Webcam Feed → TFFacemesh (468 landmarks)
↓
Facial Analysis → Eye Region Detection
↓
Raw Gaze Prediction (x, y coordinates)
↓
Outlier Detection (reject if >500px jump or off-screen)
↓
Head Pose Calculation (roll, pitch, yaw from landmarks 1, 33, 263)
↓
Kalman Filtering (q=0.01, r=0.1 for smoothing)
↓
Adaptive Sampling (60fps fast movement, 30fps slow)
↓
Processed Gaze Data (x, y, rawX, rawY, headPose, timestamp)
↓
LocalForage Storage + JSON ExportCalibration System
The calibration system ensures accurate gaze predictions through:
- Initial Calibration: 9-10 points in predefined grid pattern
- Quality Validation: Tests 5 points, measures average error
- Automatic Refinement: Adds 3 points if quality <75%
- Periodic Recalibration: 3-point quick recal every 10 trials
Note: Calibration quality directly impacts tracking accuracy. Ensure participants follow on-screen instructions carefully and maintain consistent posture.
System Requirements
Browser Support
| Browser | Minimum Version | Notes |
|---|---|---|
| Chrome | 90+ | Recommended - best TensorFlow.js performance |
| Edge | 90+ | Full support (Chromium-based) |
| Firefox | 88+ | Supported - slightly slower |
| Safari | 14+ | Limited - may have performance issues |
Hardware Requirements
- Camera: Webcam with 720p resolution (minimum)
- Processor: Quad-core CPU (Intel i5/AMD Ryzen 5 or better)
- RAM: 8GB minimum (16GB recommended)
- Display: 1920x1080 minimum resolution
Software Dependencies
| Library | Version | Purpose |
|---|---|---|
| WebGazer.js | 3.0+ | Eye tracking engine |
| TensorFlow.js | 4.0+ | Machine learning backend |
| LocalForage | 1.10+ | Client-side data storage |
| Node.js http-server | 14.0+ | HTTPS development server |
Getting Started
Ready to start using GazeTracking? Check out our Quick Start Guide for step-by-step instructions on setting up your first experiment.
Pro Tip: Start with the TrialManager class documentation to understand the core API, then explore specific methods for your use case.
Code Example
Here's a simple example of initializing an experiment:
import { initializeExperiment } from './trialManager.js';
// Initialize the experiment when page loads
document.addEventListener('DOMContentLoaded', () => {
initializeExperiment();
console.log('Experiment initialized - press any key to start');
});
// The system will:
// 1. Prompt for participant initials
// 2. Load test images based on selected type
// 3. Initialize WebGazer with enhanced features
// 4. Run calibration with validation
// 5. Start experiment trials
// 6. Export data to JSONAPI Documentation Sections
License
Copyright 2026 Michael Ryan Hunsaker, M.Ed., Ph.D. Licensed under the Apache License, Version 2.0.