@webgazer-ts/core

Modern TypeScript rewrite of Webgazer.js - webcam eye tracking for academic research.

📚 Documentation

View Full Documentation →

• Getting Started
• API Reference
• Configuration Guide
• Examples

Features

• 🎯 Accurate Gaze Tracking - Ridge regression + Kalman filtering
• 🔧 100% API Compatible - Drop-in replacement for Webgazer.js
• 📦 TypeScript Native - Full type safety and IntelliSense
• ⚡ Modern Build - ES modules, tree-shaking, optimized bundles
• 🎨 Visual Feedback - Video preview, face overlay, gaze dot
• 💾 Data Persistence - Optional localStorage for calibration
• 🔒 Privacy First - All processing happens locally

Installation

npm install @webgazer-ts/core

Quick Start

import webgazer from '@webgazer-ts/core';

// Initialize and start tracking
await webgazer
  .setTracker('TFFacemesh')
  .setRegression('ridge')
  .begin();

// Show video preview
webgazer.showVideoPreview(true);

// Listen for gaze predictions
webgazer.setGazeListener((data, timestamp) => {
  if (data) {
    console.log(`Looking at: (${data.x}, ${data.y})`);
  }
});

Usage

ES Modules (Recommended)

import webgazer from '@webgazer-ts/core';

await webgazer.begin();

CommonJS

const webgazer = require('@webgazer-ts/core').default;

webgazer.begin();

Browser (UMD)

<script src="node_modules/@webgazer-ts/core/dist/webgazer-ts.umd.cjs"></script>
<script>
  // Available as global 'webgazer'
  webgazer.begin();
</script>

CDN

<script type="module">
  import webgazer from 'https://cdn.jsdelivr.net/npm/@webgazer-ts/core/+esm';
  await webgazer.begin();
</script>

API Overview

Lifecycle

await webgazer.begin();        // Initialize and start
await webgazer.end();          // Stop and cleanup
await webgazer.pause();        // Pause tracking
await webgazer.resume();       // Resume tracking

Configuration

webgazer
  .setTracker('TFFacemesh')              // Face tracker
  .setRegression('ridge')                 // Regression model
  .saveDataAcrossSessions(false)          // Data persistence
  .applyKalmanFilter(true)                // Smoothing
  .showVideoPreview(true)                 // Show camera
  .showFaceOverlay(true)                  // Show face mesh
  .showPredictionPoints(true)             // Show gaze dot
  .showFaceFeedbackBox(true);            // Show positioning guide

Predictions

// Listen to predictions (60 FPS)
webgazer.setGazeListener((data, timestamp) => {
  if (data) {
    console.log(`Gaze: (${data.x}, ${data.y})`);
  }
});

// Get current prediction
const prediction = webgazer.getCurrentPrediction();

Calibration

// Add calibration point
webgazer.recordScreenPosition(x, y, 'click');

// Clear calibration data
webgazer.clearData();

// Get calibration count
const count = webgazer.getCalibrationPointCount();

Mouse Events

// Enable automatic calibration from mouse
webgazer.addMouseEventListeners();

// Disable
webgazer.removeMouseEventListeners();

TypeScript

Full type definitions included:

import webgazer, { 
  GazePrediction, 
  WebgazerConfig,
  EyeFeatures 
} from '@webgazer-ts/core';

const handleGaze = (data: GazePrediction | null, timestamp: number) => {
  if (data) {
    const { x, y } = data;
    console.log(`Gaze at (${x}, ${y})`);
  }
};

webgazer.setGazeListener(handleGaze);

Configuration Options

interface WebgazerConfig {
  tracker: 'TFFacemesh';
  regressor: 'ridge' | 'ridgeThreaded' | 'ridgeWeighted';
  saveDataAcrossSessions: boolean;
  videoViewerWidth: number;
  videoViewerHeight: number;
  showVideo: boolean;
  showFaceOverlay: boolean;
  showPredictionPoints: boolean;
  showFaceFeedbackBox: boolean;
  applyKalmanFilter: boolean;
}

Browser Support

Requires:

• HTTPS or localhost (for camera access)
• WebRTC support
• WebGL (for TensorFlow.js)

Supported Browsers:

• Chrome/Edge 90+
• Firefox 88+
• Safari 15+
• Mobile browsers (limited)

Migration from Webgazer.js

This package is 100% API compatible with Webgazer.js:

// This exact code works in both libraries
webgazer
  .setRegression('ridge')
  .setTracker('TFFacemesh')
  .setGazeListener((data) => console.log(data))
  .begin();

Breaking Changes in v0.2.0:

• saveDataAcrossSessions now defaults to false (privacy-first)

To keep old behavior:

webgazer.saveDataAcrossSessions(true).begin();

See Migration Guide for details.

React Integration

For React apps, use the React package:

npm install @webgazer-ts/react

import { useWebgazer } from '@webgazer-ts/react';

function App() {
  const { gazeData, isRunning, start } = useWebgazer({
    autoStart: true
  });

  return <div>Gaze: {gazeData?.x}, {gazeData?.y}</div>;
}

See @webgazer-ts/react for full React documentation.

Examples

Basic Setup

import webgazer from '@webgazer-ts/core';

await webgazer.begin();
webgazer.showVideoPreview(true);

webgazer.setGazeListener((data) => {
  if (data) {
    console.log(`Looking at (${data.x}, ${data.y})`);
  }
});

With Calibration

import webgazer from '@webgazer-ts/core';

await webgazer.begin();

// Add calibration points
document.addEventListener('click', (e) => {
  webgazer.recordScreenPosition(e.clientX, e.clientY, 'click');
  console.log('Calibration points:', webgazer.getCalibrationPointCount());
});

Custom Regression

import webgazer, { Regressor, EyeFeatures } from '@webgazer-ts/core';

class MyRegressor implements Regressor {
  predict(eyeFeatures: EyeFeatures) {
    // Your prediction logic
    return { x: 500, y: 300 };
  }
  
  addData(eyeFeatures: EyeFeatures, screenPos: [number, number], type: string) {
    // Your training logic
  }
  
  // ... implement other required methods
}

webgazer.setRegression(new MyRegressor());

Performance

• Prediction Rate: 60 FPS (16.7ms)
• Initialization: ~800ms (model loading)
• Accuracy: ±100-200px (after calibration)
• Memory: ~50MB typical
• Bundle Size: ~15KB gzipped (core only)

Privacy

• ✅ All processing happens locally in your browser
• ✅ No video or images sent to any server
• ✅ Optional localStorage (opt-in in v0.2.0+)
• ✅ User must grant camera permission
• ✅ Full control over data

Academic Use

This library is designed for academic research. Please cite the original Webgazer.js:

@inproceedings{papoutsaki2016webgazer,
  author = {Alexandra Papoutsaki and Patsorn Sangkloy and James Laskey and Nediyana Daskalova and Jeff Huang and James Hays},
  title = {WebGazer: Scalable Webcam Eye Tracking Using User Interactions},
  booktitle = {Proceedings of the 25th International Joint Conference on Artificial Intelligence (IJCAI)},
  pages = {3839--3845},
  year = {2016}
}

License

GPL-3.0-or-later

For academic research use. See LICENSE.md for details.

Credits

Based on Webgazer.js by Brown HCI Lab.

Original Authors:

• Alexandra Papoutsaki
• James Laskey
• Jeff Huang

TypeScript Rewrite:

• John Adrian Cruz

Support

• 📖 Documentation
• 💬 GitHub Discussions
• 🐛 Issue Tracker
• 📧 Email

Links

• npm Package
• GitHub Repository
• Documentation Site
• Original Webgazer.js

Made with ❤️ for academic research