Skip to content

Latest commit

 

History

History
158 lines (130 loc) · 6.66 KB

README.md

File metadata and controls

158 lines (130 loc) · 6.66 KB
Raw

etudriver-web

=============

The JavaScript library to support eye-tracking on web pages. It communicates with ETU-Driver via WebSocket using plain-text commands and receives data in JSON format. The WebSocket server can be set up by launching on a local machine the "ETU-Driver service" application with the "Tracking > WerSocket server" checked.

Features

  • streams gaze data from ETU-Driver into a web-page (see [the 'camera' and 'heatmap' examples] (https://github.com/lexasss/etudriver-web/tree/master/examples))
  • fires an event when the tracking or other ETU-Driver state changes
  • contains methods to send commands to ETU-Driver to show options window, calibrate, and toggle gaze tracking
  • embeds a panel with buttons to send these commands
  • shows gaze pointer
  • allows using head movements for the gaze pointer location correction
  • applies smoothing for the gaze pointer
  • allows selecting between raw data or fixation data in mapping gaze-to-target calculation routine
  • provides several gaze-to-target mapping algorithms
  • detects nodding head gesture
  • allows to calibrate a custom head gesture
  • uses dwell time (naive or cumulative), nodding or custom head gestures for target selection
  • displays a progress of dwell time
  • allows defining few categories of targets, each with its own method of selection and visual feedback for mapping and selection events (see [the 'targets' example] (https://github.com/lexasss/etudriver-web/tree/master/examples/targets.html))
  • allows page scrolling using 1) dedicated transparent panels to fixate on, 2) head movements (see [the 'scroller' example] (https://github.com/lexasss/etudriver-web/tree/master/examples/scroller.html))
  • contains a keyboard to display when a used selects a target of a certain category (see [the 'keyboard' example] (https://github.com/lexasss/etudriver-web/tree/master/examples))
  • allows defining custom keyboards; on a key selection, a custom scenario can be executed, this making keyboards very flexible that can be used not only for text input (see [the 'keyboardSC' example] (https://github.com/lexasss/etudriver-web/tree/master/examples))
  • calibration verification procedure; custom target presentation is allowed

Usage

See [examples] (https://github.com/lexasss/etudriver-web/tree/master/examples) to get ideas of how and for what the library can be used. See [comments] (https://github.com/lexasss/etudriver-web/blob/master/js/main.js) in the JS file for the feature-by-feature explanation of the etudriver configuration

In HTML, include only the etudriver-[version].js or etudriver-[version].min.js file, the CSS file will be loaded automatically. The library exports etudriver variable. Initialize this variable when the page DOM is loaded (DOMContentLoaded). The basic code is shown in [this] (https://github.com/lexasss/etudriver-web/blob/master/examples/simplest.html) example.

Methods

  • init (settings, callbacks): initializes the library; takes custom settings and callbacks (see the sections below for the description)
  • updateTargets (): updates targets, if they have been changed
  • calibrateCustomHeadGesture (name, callback): shows the custom head gesture calibration window; takes the detector name and a callback function that is called on closing the calibration window (arguments: 'name' the name of detector)
  • showOptions (callback): shows ETU-Driver options dialog; takes a callback function that is called when the options dialog is closed (arguments: accepted: boolean, true if a user pressed "OK" button, false otherwise)
  • calibrate (callback): calibrates the current device; takes a callback function that is called when the calibration is finished (arguments: accepted: boolean, true if a new calibration was accepted, false otherwise)
  • toggleTracking (): toggles tracking
  • getKeyboard (name): returns the keyboard object; takes the keyboard name
  • verifyCalibration (settings, callbacks): run the calibration verification procedure

Settings

to appear; meanwhile, see the js/main.js.

Callbacks

  • state: fires when ETU-Driver state changes; arguments:
    • state: current state; the object consists of:
      • isServiceRunning: connected to the service via WebSocket
      • isConnected: connected to a tracker
      • isCalibrated: the tracker is calibrated
      • isTracking: the tracker is sending data
      • isStopped: the tracker was just stopped
      • isBusy: the service is temporally unavailable (calibration is in progress, 'Options' window is shown, etc.)
      • device: name of the device, if connected
  • sample: fires when a new sample (average from both eyes) is available; arguments:
    • timestamp: data timestamp (integer)
    • x: gaze x (integer)
    • y: gaze y (integer)
    • pupil: pupil size (float)
    • ec = {xl, yl, xr, yr}: eye-camera values (float 0..1)
  • target: fires on target enter, leave and selection; arguments:
    • event: a value from etudriver.event
    • target: the target
  • keyboard: fires on a keyboard visibility change
    • keyboard: the keyboard
    • visible: the visibility flag

Example

HTML

<html>
<head>
    <script type="text/javascript" src="etudriver-0.1.1.min.js"></script>
</head>
<body>
    <div class="container">
        <div class="etud-target">left</div>
        <div class="etud-target">right</div>
    </div>
</body>
</html>

JS

document.addEventListener('DOMContentLoaded', function() {
  etudriver.init({ /* use only default settings */ }, { /* no callbacks */});
});

CSS

body {
    background-color: #CCCCCC;
}

.container {
    padding: 20px 0;
    width: 100%;
    text-align: center;
}

.container:after {
    content: '';
    display: inline-block;
    height: 90%;
    vertical-align: middle;
    width: 0;
}

.etud-target {
    display: inline-block;
    background-color: deepskyblue;
    margin: 20px 100px;
    width: 140px;
    height: 140px;
    
    border: 1px solid black;
    border-radius: 8px;
    text-align: center;
    font: 18pt arial, sans-serif;
    color: black;
    line-height: 140px;
    vertical-align: middle;
}

.etud-focused {
    background-color: tomato;
    color: white;
}        

.etud-selected {
    background-color: #CC4F39;
    color: white;
}

Known issues

Not yet discovered (check the 'Issues' section), but should be many, as the code is very raw yet.

todo's

High priority

  • none

Moderate priority

  • custom probability map
  • online recalibration
  • scrolling keyboard (by head pose)

Low priority

  • find out a way to support multiple eye trackers stream data same time