Quick Start Guide

Get your first gaze tracking experiment running in under 10 minutes. This guide walks through setup, configuration, and execution of a basic experiment.

Prerequisites

Required Software

Hardware Requirements

• Webcam with 720p minimum resolution
• Quad-core CPU (Intel i5/AMD Ryzen 5 or better)
• 8GB RAM minimum (16GB recommended)
• 1920x1080 display minimum

Installation Steps

Step 1: Clone Repository

git clone https://github.com/mrhunsaker/GazeTracking.git
cd GazeTracking

Step 2: Install http-server

npm install -g http-server

SSL Certificate Setup

Modern browsers require HTTPS to access webcams. Generate self-signed SSL certificates:

Generate Certificates

openssl req -nodes -new -x509 -keyout server.key -out server.cert

Certificate Generation Prompts

You can press Enter to skip all prompts, or fill them in as follows:

Country Name: US
State: [Your State]
Locality: [Your City]
Organization: Research Lab
Common Name: localhost
Email: your@email.com

Running Your First Experiment

Step 1: Start the Server

Navigate to the experiment folder and start the HTTPS server:

cd StudentFolders/2025_Students
http-server -S -C server.cert -K server.key -p 8080

You should see:

Starting up http-server, serving ./ through https
Available on:
  https://127.0.0.1:8080
  https://192.168.1.100:8080
Hit CTRL-C to stop the server

Step 2: Open in Browser

1. Open Chrome or Edge (recommended)
2. Navigate to https://localhost:8080
3. Click "Advanced" → "Proceed to localhost" (for self-signed cert)
4. Allow camera permissions when prompted

Step 3: Initialize Experiment

1. Press any key to start initialization
2. Enter participant initials (max 6 characters)
3. Select test type:
   • Shapes: 193 geometric shapes
   • Colors: 10 colored objects
   • Abstract: 403 abstract patterns
4. Select trial count (10-50)
5. Click "Start"

Step 4: Calibration

The calibration sequence will begin automatically:

1. 9-Point Calibration: Click each yellow dot that appears
   • Look directly at each dot before clicking
   • Keep your head still
   • Maintain consistent posture
2. Quality Validation: System automatically tests accuracy
3. Refinement (if needed): 3 additional points if quality < 75%

Step 5: Run Experiment

After calibration, trials begin automatically:

1. Sample Phase: One object shown for 3 seconds
2. Delay: 2-second black screen
3. Test Phase: Three objects shown for 10 seconds
   • Type 1 trials: target + 2 identical foils
   • Type 2 trials: target + 2 different foils
4. Repeat: Continues for selected trial count
5. Periodic Recalibration: 3-point recal every 10 trials

Data Export

When the experiment completes, data is automatically:

1. Saved to browser storage (IndexedDB via LocalForage)
2. Downloaded as JSON file to your Downloads folder

Data File Format

{
  "trialData": [
    {
      "trialNumber": 1,
      "type": 1,
      "startTime": 1706284843120,
      "endTime": 1706284858125,
      "object1": 45,
      "testObjects": [45, 127, 127],
      "positions": [
        {"position": "left", "objectNum": 45, "isTarget": true},
        {"position": "center", "objectNum": 127, "isTarget": false},
        {"position": "right", "objectNum": 127, "isTarget": false}
      ],
      "gazeData": [/* array of gaze points */]
    }
    // ... more trials
  ],
  "gazeData": [/* all gaze points across session */],
  "timestamp": 1706284860000,
  "totalTrials": 20
}

Gaze Data Format

{
  "x": 512.3,              // Filtered gaze X (pixels)
  "y": 384.7,              // Filtered gaze Y (pixels)
  "rawX": 515.1,           // Raw gaze X before filtering
  "rawY": 388.2,           // Raw gaze Y before filtering
  "headPose": {
    "roll": 0.05,          // Head roll angle (radians)
    "pitch": -0.02,        // Head pitch angle (radians)
    "yaw": 0.08,           // Head yaw angle (radians)
    "distance": 125.4      // Face distance metric
  },
  "time": 1706284847123,   // Absolute timestamp
  "relativeTime": 2543,    // Milliseconds since trial start
  "phase": "experiment"    // 'calibration' or 'experiment'
}

Common Issues & Solutions

Next Steps

• Learn about TrialManager class
• Explore all available methods
• Understand gaze tracking pipeline
• Calibration best practices

Example Experiment Workflow

// index.html - include libraries
<script src="webgazer.js"></script>
<script src="localforage.min.js"></script>
<script type="module">
  import { initializeExperiment } from './trialManager.js';
  
  document.addEventListener('DOMContentLoaded', () => {
    initializeExperiment();
    console.log('Press any key to begin');
  });
</script>

// Workflow automatically handles:
// 1. Participant dialog
// 2. Image loading
// 3. WebGazer init with enhanced features
// 4. 9-point calibration + validation
// 5. Trial loop with periodic recalibration
// 6. Data export to JSON + LocalForage

Support

If you encounter issues not covered here:

• Check the GitHub Issues
• Review the full API documentation
• Contact: hunsakerconsulting@gmail.com