Skip to content

Top Level API

Jump to bottom
Jeff Huang edited this page Mar 25, 2022 · 15 revisions

Here are all the functions you call to control the operation of WebGazer.

  • on include of script in body
  • webgazer namespace object introduced
  • overwrites any other webgazer data to prevent data contention
  • webgazer singleton namespace object
    • private functions
      • webgazer.computeValidationBoxSize()
        • Computes the size of the face overlay validation box depending on the size of the video preview window.
        • @returns The dimensions of the validation box as top, left, width, height.
      • checkEyesInValidationBox()
        • Checks if the pupils are in the position box on the video
      • checkCursor
        • Alerts the user of the cursor position, used for debugging & testing
      • drawCoordinates(colour, x, y)
        • This draws the point (x,y) onto the canvas in the HTML
        • @param colour: of the circle to plot
        • @param x: x-coordinate of the desired point to plot
        • @param y: y-coordinate of the desired point to plot
      • getPupilFeatures(video, canvas, width, height)
        • Gets the pupil features by following the pipeline which threads an eyes object through each call: curTracker gets eye patches -> blink detector -> pupil detection
        • @param canvas - will have the video drawn onto it
        • @param width - the width of canvas
        • @param height - the height of canvas
        • NOTE: not currently being used
      • paintCurrentFrame(canvas, width, height)
        • Gets the most current frame of video and paints it to a resized version of the canvas with width and height
      • getPrediction(regModelIndex)
        • Paints the video to a canvas and runs the prediction pipeline to get a prediction
        • @param {Number|undefined} regModelIndex - The prediction index we're looking for
      • loop()
        • Runs every available animation frame if webgazer is not paused
      • recordScreenPosition(x,y,[eventType])
        • @param {String} x - position on screen in the x axis
        • @param {String} y - position on screen in the y axis
        • @param {String} eventType [optional] - "click" or "move", as per eventTypes, defaults to click.
      • listeners
        • clickListener(event)
          • Records click data and passes it to the regression model
          • Called whenever the user clicks
        • moveListener(event)
          • Records mouse move data and passes it to the regression model
          • Called whenever the user moves the mouse
        • addMouseEventListeners
          • Add the mouse click and move listeners that add training data.
          • @return {webgazer} this
        • removeMouseEventListeners
          • Remove the mouse click and move listeners that add training data.
          • @return {webgazer} this
        • loadGlobalData()
          • Loads the global data and passes it to the regression model
        • setGlobalData()
          • Adds data to localforage
        • clearData()
          • Clears data from model and global storage
        • init(videoStream)
          • Initializes all needed dom elements and begins the loop
          • @param {URL} videoStream - The video stream to use
        • setUserMediaVariable()
          • Initializes navigator.mediaDevices.getUserMedia depending on the browser capabilities
    • control functions
      • webgazer begin()
        • begins collecting click data and activates the camera, should be called as soon as possible to improve accuracy
        • attaches window click listener
        • starts clock
        • video div attached to body
          • id = webgazerVideoFeed
          • style = invisible
        • canvas attached to body
          • id = webgazerCanvas
          • style = invisible
        • returns webgazer object
      • webgazer pause()
        • stops all webgazer data collection and predictions
        • returns webgazer object
      • webgazer resume()
        • resumes all webgazer data collection and predictions after a pause()
        • returns webgazer object
      • webgazer end()
        • stops all webgazer data collection and predictions and releases all memory being held by the webgazer object.
        • Accuracy may suffer if begin is called afterward, consider using pause and resume instead
        • IMPORTANT: saves global model data so that user’s returning to the page will have a pre-loaded model
        • returns webgazer object
    • debug functions
      • boolean detectCompatibility()
        • tests for certain browser requirements that webgazer depends on
        • checked again in begin()
        • returns true if browser meets expectations, false otherwise
      • showVideo(bool)
        • Set whether the video preview is visible or not.
      • showFaceOverlay(bool)
        • Set whether the face overlay is visible or not.
      • showFaceFeedbackBox(bool)
        • Set whether the faceFeedbackBox is visible or not.
      • webgazer showPredictionPoints(boolean)
        • if bool is true: shows a circle with the current best guess given by the prediction model
        • if bool is false: turns off the prediction circle
        • returns webgazer object
      • webgazer saveDataAcrossSessions(boolean)
        • if bool is true (default): previous calibration data (from localforage) should be loaded
        • if bool is false: each user session is independent
        • returns webgazer object
      • webgazer applyKalmanFilter(boolean)
        • if bool is true (default): Kalman filter is applied to gaze predictions (smoothing)
        • if bool is false: Kalman filter is not applied (makes best prediction at each possible moment)
        • returns webgazer object
      • setCameraConstraints(constraints)
        • Set whether the video preview is visible or not.
          • Define constraints on the video camera that is used. Useful for non-standard setups.
          • This can be set before calling webgazer.begin(), but also mid stream.
          • @param {Object} constraints Example constraints object:
          • { width: { min: 320, ideal: 1280, max: 1920 }, height: { min: 240, ideal: 720, max: 1080 }, facingMode: "user" };
          • Follows definition here: https://developer.mozilla.org/en-US/docs/Web/API/Media_Streams_API/Constraints
      • setInternalVideoBufferSizes(width, height)
        • self explanatory
      • setStaticVideo(videoLoc)
        • Set a static video file to be used instead of webcam video
        • @param {String} videoLoc - video file location
        • @return {webgazer} this
      • setVideoViewerSize(width, height)
        • set size of video viewer in px
    • setters
      • webgazer setTracker( libraryString )
        • sets which facial recognition library webgazer should use
        • libraryString - a string corresponding to one of the following
          • ‘clmtrackr’
          • ‘js_objectdetect’
          • ‘trackingjs’
        • returns webgazer object
      • webgazer setRegression( regressionString )
        • sets which regression model type webgazer should use
        • regressionString - a string corresponding to one of the following (by default)
          • ‘ridge’
          • ‘weightedRidge'
          • 'threadedRidge'
            • Currently not fully functional. Cannot load stored calibration data. Once webgazer is fully loaded, if you call webgazer.clearData() then prediction will work for session specific data only. Also look at comments within ridgeRegThreaded to find how to structure the necessary files.
        • returns webgazer object
      • webgazer addTrackerModule
        • Adds a new tracker module so that it can be used by setTracker()
        • @param {String} name - the new name of the tracker
        • @param {Function} constructor - the constructor of the curTracker object
        • @return {webgazer} this
      • webgazer addRegressionModule
        • Adds a new regression module so that it can be used by setRegression() and addRegression()
        • @param {String} name - the new name of the regression
        • @param {Function} constructor - the constructor of the regression object
      • webgazer addRegression
        • Adds a new regression module to the list of regression modules, seeding its data from the first regression module
        • @param {String} name - the string name of the regression module to add
        • @return {webgazer} this
      • webgazer setGazeListener( callback )
        • sets a callback which will be invoked every time webgazer makes a new prediction
        • only one callback can be registered at a time, so in multiple calls to setGazeListener only the last callback will remain registered
        • callback - function(gazeData, elapsedTime)
          • gazeData - object or null if prediction failed
            • x - predicted gaze x screen coordinate in pixels
            • y - predicted gaze y screen coordinate in pixels
          • elapsedTime - time in milliseconds since begin() was invoked
        • returns webgazer object
      • webgazer clearGazeListener()
        • removes the current callback
        • use this method instead of pause/resume when data should continue to be collected to improve the accuracy
        • returns webgazer object
      • setVideoElementCanvas
        • Set the video element canvas; useful if you want to run WebGazer on your own canvas (e.g., on any random image).
        • returns video element canvas
      • clearData
        • Clear data from localforage and from regs
    • getters
      • string getTracker()
        • gets the current facial recognition library
        • returns string - the string corresponding to the library
      • getRegression()
        • gets the current regression model type
        • returns string - the string corresponding to the regression model
      • {x:, y:} getCurrentPrediction()
        • request a prediction from webgazer
        • returns object or null
          • x - predicted gaze x screen coordinate in pixels
          • y - predicted gaze y screen coordinate in pixels
      • getEventTypes
        • returns the different event types that may be passed to regressions when calling regression.addData()
        • returns array of strings, where each string is an event type
      • getVideoElementCanvas
        • returns the current video element canvas that WebGazer uses internally to run its face tracker on
      • getVideoPreviewToCameraResolutionRatio
        • returns array (a,b) where a is width ratio and b is height ratio
      • getStoredPoints
        • returns the fifty most recent tracker predictions
Clone this wiki locally