Skip to main content
Version: Release

API Docs (Javascript)

SeeSo

class SeeSo

SeeSo is the class that generates GazeTracking data from the video from the device's camera.

  • usage:

      this.seeso = new SeeSo();

Version Check

getVersionName

getVersionName()

return SeeSo SDK version information.

  • return: String

  • usage:

      const version = SeeSo.getVersionName();

Construction

initialize

async initialize(licenseKey, option)

SeeSo construction process including authentication.

The initialize will return authentication result as Enum InitializationErrorType.

  • parameter

    • licenseKey

      • type: String
      • description: Key generated from SeeSo Console.
    • option(optional)

      • type: UserStatusOption
      • description: A class containing User status option information
  • return: Enum InitializationErrorType

  • usage:

      // when SDK download
    import { UserStatusOption } from '${your project path}/seeso-minjs/seeso.min';

    // when npm import
    import { UserStatusOption } from 'seeso';
    ...
    const isUseAttention = true;
    const isUseBlink = true;
    const isUseDrowsiness = true;
    const userStatusOption = new UserStatusOption(isUseAttention, isUseBlink, isUseDrowsiness);
    const errorCode = await this.seeso.initialize(
    'licenseKey', userStatusOption
    );

Destruction

deinitialize

deinitialize()

SeeSo destruction process. All API will be disabled after deinitialize.

  • return: undefined

  • usage:

      this.seeso.deinitialize();

Add/Remove Callback

addGazeCallback

addGazeCallback(callback)

Add callback function for GazeTracking data.

  • parameter

    • callback

      • type: Function onGaze
      • description: Gaze callback.
  • return: undefined

  • usage:

      this.seeso.addGazeCallback(onGaze);

removeGazeCallback

removeGazeCallback(callback)

Remove callback function for GazeTracking data.

  • parameter

    • callback

      • type: Function onGaze
      • description: Gaze callback.
  • usage:

      this.seeso.removeGazeCallback(onGaze);

addDebugCallback

addDebugCallback(callback)

Add debug callback function for GazeTracking.

  • parameter

    • callback

      • type: Function onDebug
      • description: Debug callback.
  • return: undefined

  • usage:

      this.seeso.addDebugCallback(onDebug);

removeDebugCallback

removeDebugCallback(callback)

Remove debug callback function for GazeTracking.

  • parameter

    • callback

      • type: Function onDebug
      • description: Debug callback.
  • return: undefined

  • usage:

      this.seeso.removeDebugCallback(onDebug);

addCalibrationNextPointCallback

addCalibrationNextPointCallback(callback)

Add callback function for Calibration point.

  • parameter

    • callback

      • type: Function onCalibrationNextPoint
      • description: Calibration point callback.
  • return: undefined

  • usage:

      this.seeso.addCalibrationNextPointCallback(onCalibrationNextPoint);

removeCalibrationNextPointCallback

removeCalibrationNextPointCallback(callback)

Remove callback function for Calibration point.

  • parameter

    • callback

      • type: Function onCalibrationNextPoint
      • description: Calibration point callback.
  • return: undefined

  • usage:

      this.seeso.removeCalibrationNextPointCallback(onCalibrationNextPoint);

addCalibrationProgressCallback

addCalibrationProgressCallback(callback)

Add callback function for Calibration progress.

  • parameter

    • callback

      • type: Function onCalibrationProgress
      • description: Calibration progress callback.
  • return: undefined

  • usage:

      this.seeso.addCalibrationProgressCallback(onCalibrationProgress);

removeCalibrationProgressCallback

removeCalibrationProgressCallback(callback)

Remove callback function for Calibration progress.

  • parameter

    • callback

      • type: Function onCalibrationProgress
      • description: Calibration progress callback.
  • return: undefined

  • usage:

      this.seeso.removeCalibrationProgressCallback(onCalibrationProgress);

addCalibrationFinishCallback

addCalibrationFinishCallback(callback)

Add callback function for Calibration Result.

  • parameter

    • callback

      • type: Function onCalibrationFinished
      • description: Calibration finish callback.
  • return: undefined

  • usage:

      this.seeso.addCalibrationFinishCallback(onCalibrationFinished);

removeCalibrationFinishCallback

removeCalibrationFinishCallback(callback)

Remove callback function for Calibration Result.

  • parameter

    • callback

      • type: Function onCalibrationFinished
      • description: Calibration finish callback.
  • return: undefined

  • usage:

      this.seeso.removeCalibrationFinishCallback(onCalibrationFinished);

addAttentionCallback

addAttentionCallback(callback)

Add callback function for User Attention Result.

  • parameter

    • callback

      • type: Function onAttention
      • description: User Status Attention callback.
  • return: undefined

  • usage:

      this.seeso.addAttentionCallback(onAttention);

removeAttentionCallback

removeAttentionCallback(callback)

Remove callback function for User Attention Result.

  • parameter

    • callback

      • type: Function onAttention
      • description: User Status Attention callback.
  • return: undefined

  • usage:

      this.seeso.removeAttentionCallback(onAttention);

addBlinkCallback

addBlinkCallback(callback)

Add callback function for User Blink Result.

  • parameter

    • callback

      • type: Function onBlink
      • description: User Status Blink callback.
  • return: undefined

  • usage:

      this.seeso.addBlinkCallback(onBlink);

removeBlinkCallback

removeBlinkCallback(callback)

Remove callback function for User Blink Result.

  • parameter

    • callback

      • type: Function onBlink
      • description: User Status Blink callback.
  • return: undefined

  • usage:

      this.seeso.removeBlinkCallback(onBlink);

addDrowsinessCallback

addDrowsinessCallback(callback)

Add callback function for User Drowsiness Result.

  • parameter

    • callback

      • type: Function onDrowsiness
      • description: User Status Drowsiness callback.
  • return: undefined

  • usage:

      this.seeso.addDrowsinessCallback(onDrowsiness);

removeDrowsinessCallback

removeDrowsinessCallback(callback)

Remove callback function for User Drowsiness Result.

  • parameter

    • callback

      • type: Function onDrowsiness
      • description: User Status Drowsiness callback.
  • return: undefined

  • usage:

      this.seeso.removeDrowsinessCallback(onDrowsiness);

Gaze Tracking

startTracking

async startTracking(stream)

Start GazeTracking process with given MeadiaStream stream.

  • parameter

    • stream

      • type: MediaStream
      • description: MediaStream object which streams video from the camera.
  • return: Boolean

  • usage:

      const stream = await navigator.mediaDevices.getUserMedia({'video': true});

    this.started = await this.seeso.startTracking(stream);

stopTracking

stopTracking()

Stop GazeTracking process.

  • return: undefined

  • usage:

      this.seeso.stopTracking();

setTrackingFPS

setTrackingFps(fps)

Set custom FPS of the GazeTracking process.

ITs value should in between 0 and 30.

FPS can be dropped due to the device spec.

  • parameter

    • fps

      • type: Number
      • description: Custom FPS(Frame Per Second) for gaze tracking.
  • return: undefined

  • usage:

      this.seeso.setTrackingFps(15);

UserStatus Setting

setAttentionInterval

 setAttentionInterval(interval)

Set time interval for the UserStatus Attention callback.

The UserStatus Attention score will be calculated for the given time interval.

The beginning and ending timestamps are passed through the onAttention callback as timestampBegin and timestampEnd.

The interval range is 10 to 60 (seconds), and the default value is 30 seconds.

  • parameter

    • interval

      • type: Number
      • description: Time interval for the UserStatus Attention score.
  • return: undefined

  • usage:

      this.seeso.setAttentionInterval(interval);

Get UserStatus Data

getAttentionScore

 getAttentionScore()

Get current Attention score from the SeeSo.

This API does not provide timestamp of the Attention score data.

Use onAttention callback, unless the Attention score is required at a specific time/location.

  • parameter: X

  • return: Number

  • usage:

      this.score = this.seeso.getAttentionScore();

Calibration

startCalibration

startCalibration(calibrationMode, criteria);

Start calibration process with CalibrationMode and Criteria.

calibrationMode is number of calibration points.

criteria is option that manage calibration process and accuracy.

GazeTracking process must be started by calling startTracking before startCalibration.

  • parameter

    • calibrationMode

      • type: Number
      • description: Calibration point option (1/5).
    • criteria

      • type: Enum CalibrationAccuracyCriteria
      • description: Calibration accuracy option.
  • return: Boolean

  • usage:

      this.result = this.seeso.startCalibration(5, CalibrationAccuracyCriteria.DEFAULT);

stopCalibration

stopCalibration()

Stop and cancel current calibration process.

  • return: Boolean

  • usage:

      this.isStop = this.seeso.stopCalibration();

startCollectSamples

startCollectSamples()

Start collect next calibration point data.

This should be called in onCalibrationProgress when need to collect new calibration point data.

The onCalibrationProgress will give progress (0 ~ 1), which represents the data collecting progress of current calibration point.

  • return: undefined

  • usage:

      if(this.calibrating){
    this.seeso.startCollectSamples();
    }

setCalibrationData

setCalibrationData(calibrationData)

Set current calibration data.

  • parameter

    • calibrationData

      • type: String
      • description: Calibration data.
  • return: undefined

  • usage:

      this.seeso.setCalibrationData(this.calibrationData);

getCalibrationData

getCalibrationData()

Get current calibration data.

  • return: String

  • usage:

      this.calibrationData = this.seeso.getCalibrationData();

fetchCalibrationData

async fetchCalibrationData(userId)

Fetch calibration data of userId from the Calibration Server DB.

If data does not exist, empty string ("") will be returned.

  • parameter

    • userId

      • type: String
      • description: User ID.
  • return: String

  • usage:

      this.calibrationData = this.seeso.fetchCalibrationData(this.userId);
    this.setCalibrationData(this.calibrationData);

uploadCalibrationData

async uploadCalibrationData(userId)

Upload calibration data of userId to the Calibration Server DB.

  • parameter

    • userId

      • type: String
      • description: User ID.
  • return: Boolean

  • usage:

      this.result = this.seeso.uploadCalibrationData(this.userId);

Camera Parameters

setMonitorSize

setMonitorSize(monitorInch)

Set current monitor size in inches.

To get better GazeTracking performance, accurate monitor size should be set by this function.

Default value is 15 inches.

  • parameter

    • monitorInch

      • type: Number
      • description: Monitor size in inches.
  • return: undefined

  • usage:

      this.seeso.setMonitorSize(15);

getMonitorSize

getMonitorSize()

Get current monitor size in inches.

  • return: Number

  • usage:

      this.monitorSize = this.seeso.getMonitorSize();

setFaceDistance

setFaceDistance(faceDistance)

Set face distance from the camera in cm.

To get better GazeTracking performance, accurate face distance should be set by this function.

Default valule is 50 cm.

  • parameter

    • faceDistance

      • type: Number
      • description: Distance between user face and camera in cm.
  • return: undefined

  • usage:

      this.seeso.setFaceDistance(50);

setCameraPosition

setCameraPosition(cameraX, isCameraOnTop)

Set relative camera position to the screen.

Default value of cameraX is screen width/2.

Default value of isCameraOnTop is true.

  • parameter

    • cameraX

      • type: Number
      • description: Horizontal camera position in pixel, between 0 to screen width.
    • isCameraOnTop

      • type: Boolean
      • description: True if the camrea is located at the top of the screen, False if located at the bottom of the screen.
  • return: undefined

  • usage:

      this.seeso.setCameraPosition(640, true);

getCameraPosition

getCameraPosition()

Get relative camera position to the screen, including cameraX and isCameraOnTop.

The return object includes cameraX and isCameraOnTop.

cameraX is Horizontal camera position in pixel, between 0 to screen width.

isCameraOnTop is True if the camrea is located at the top of the screen, False if located at the bottom of the screen.

  • return: Object

  • usage:

      this.camearPosition = this.seeso.getCameraPosition();

    this.cameraX = this.cameraPosition.cameraX;
    this.isCameraOnTop = this.cameraPosition.isCameraOnTop;

Calibration Page

openCalibrationPage

static openCalibrationPage(licenseKey, userId, redirectUrl, calibraitonPoint)

Open calibration Page with calibration device setting option.

After all calibration process are finished in calibration page, redirectUrl page will be redirected.

The result calibration data will be passed as a query parameter calibrationData.

Default calibrationPoint option is 5.

  • parameter

    • licenseKey

      • type: String
      • description: Key generated from SeeSo Console.
    • userId

      • type: String
      • description: User ID.
    • redirectUrl

      • type: String
      • description: Redirect URL used after the calibration is finished.
    • calibraitonPoint

      • type: Number
      • description: Calibration point option (1/5).
  • return: undefined

  • usage:

      SeeSo.openCalibrationPage(this.licenseKey, this.userId, "https://seeso.io/", 5);

openCalibrationPageQuickStart

static openCalibrationPageQuickStart(licenseKey, userId, redirectUrl, calibraitonPoint)

Open calibration Page without calibration device setting option.

This page will use default setting values for the calibration.

If previous setting exists, the previous setting values will be used for the calibration.

After all calibration process are finished in calibration page, redirectUrl page will be redirected.

The result calibration data will be passed as a query parameter calibrationData.

Default calibrationPoint option is 5.

  • parameter

    • licenseKey

      • type: String
      • description: Key generated from SeeSo Console.
    • userId

      • type: String
      • description: User ID.
    • redirectUrl

      • type: String
      • description: Redirect URL used after the calibration is finished.
    • calibraitonPoint

      • type: Number
      • description: Calibration point option (1/5).
  • return: undefined

  • usage:

      SeeSo.openCalibrationPageQuickStart(this.licenseKey, this.userId, "https://seeso.io/", 5);

ENUM

InitializationErrorType

Enum InitializationErrorType

The Enum containing return error types of initialize.

Please read : Authentication for more details.

CalibrationAccuracyCriteria

Enum CalibrationAccuracyCriteria

The Enum containing options that manage calibration process and accuracy.

  • elements

    • DEFAULT

      • value: 0
      • description: starts normal calibration.
    • LOW

      • value: 1
      • description: starts easy calibration, easier to pass each step (high possibility to have low accuracy).
    • HIGH

      • value: 2
      • description: starts strict calibration, harder to pass each step (high possibility to have high accuracy).

TrackingState

Enum TrackingState

The Enum containing tracking state types used in GazeInfo.

  • elements

    • SUCCESS

      • value: 0
      • description: Face alignment is in a best position (GazeTracking success, with valid x and y).
    • LOW_CONFIDENCE

      • value: 1
      • description: Face alignment is not in the best position, but can be used for tracking (GazeTracking success, with less accurate x and y).
    • UNSUPPORTED

      • value: 2
      • description: Face alignment is not suitable for tracking (GazeTracking fail, with invalid x and y).
    • FACE_MISSING

      • value: 3
      • description: Face is missing (GazeTracking fail).

EyeMovementState

Enum EyeMovementState

The Enum containing eye movement state types used in GazeInfo.

  • elements

    • FIXATION

      • value: 0
      • description: Eye movement is fixation.
    • SACCADE

      • value: 2
      • description: Eye movement is Saccade.
    • UNKNOWN

      • value: 3
      • description: Eye movement is Unknown.

Class

GazeInfo

class GazeInfo

GazeInfo callback Class used in onGaze callback.

This class is used in onGaze gaze callback.

  • elements

    • timestamp

      • type: Number
      • description: Timestamp of the data.
    • x

      • type: Number
      • description: Gaze x coordinate.
    • y

      • type: Number
      • description: Gaze y coordinate.
    • trackingState

      • type: TrackingState
      • description: Gaze tracking state.
    • eyemovementState

      • type: EyeMovementState
      • description: Gaze eye movement state.
  • usage:

      this.gazeInfo = new GazeInfo(this.timestamp, this.browser_x, this.browser_y, _trackingState, _eyeMovmentState, 0);

UserStatusOption

class UserStatusOption

The class contains User Status options information for SeeSo

  • elements

    • isUseAttention

      • type: boolean
      • description: Set Attention flag.
    • isUseBlink

      • type: boolean
      • description: Set Blink flag.
    • isUseDrowsiness

      • type: boolean
      • description: Set Drowsiness flag.
  • usage:

      const userStatusOption = new UserStatusOption(this.isUseAttention, this.isUseBlink, this.isUseDrowsiness);

GazeCallback

onGaze

onGaze(gazeInfo)

Gaze callback.

  • parameter

    • gazeInfo

      • type: Class GazeInfo
      • description: Class containing gaze tracking data.
  • return: undefined

  • usage:

      onGaze(gazeInfo){
    this.timestamp = gazeInfo.timestamp;
    this.gazeX = gazeInfo.x;
    this.gazeY = gazeInfo.y;
    this.trackingState = gazeInfo.trackingState;
    this.eyemovementState = gazeInfo.eyemovementState;
    }

DebugCallback

onDebug

onDebug(FPS, latency_min, latency_max, latency_avg)

Debug callback.

FPS is current gaze fps.

latency_min, latency_max, and latency_ave are current minimum, maximum, and average gaze latency.

  • parameter

    • FPS

      • type: Number
      • description: Current gaze fps.
    • latency_min

      • type: Number
      • description: current minimum gaze latency.
    • latency_max

      • type: Number
      • description: current maximum gaze latency.
    • latency_avg

      • type: Number
      • description: current average gaze latency.
  • return: undefined

  • usage:

      onDebug(FPS, latency_min, latency_max, latency_avg){
    this.fps = FPS;
    this.latency_min = Math.floor(latency_min);
    this.latency_max = Math.floor(latency_max);
    this.latency_avg = Math.floor(latency_avg);
    }

calibrationProcessCallback

onCalibrationNextPoint

onCalibrationNextPoint(pointX, pointY)

Next calibration point coordinate callback.

pointX and pointY are current calibration point coordinate.

(pointX, pointY) calibration point should be focused during the calibration process.

  • parameter

    • pointX

      • type: Number
      • description: X coordinate of the current calibration point.
    • pointY

      • type: Number
      • description: Y coordinate of the current calibration point.
  • return: undefined

  • usage:

      onCalibrationNextPoint(pointX, pointY){
    // Set calibration point coordinate
    this.calibrationCoord = { x: pointX, y: pointY };
    }

onCalibrationProgress

onCalibrationProgress(progress)

Calibration progress callback.

progress is the calibration progress of the current calibration point (0 ~ 1).

Next calibration point will be guided when the progress reaches 1.

startCollectSamples shuold be called to collect next calibration data.

Return 0 when start calibration progress.

Return 1 when finish calibratino progress.

  • parameter

    • progress

      • type: Number
      • description: Calibration progress of the current calibration point.
  • return: undefined

  • usage:

      onCalibrationProgress(progress){
    if(progress >= 1){
    // Collect next calibration point data
    setTimeout(()=>{
    if(this.calibrating){
    this.seeso.startCollectSamples()
    }
    }, 1500)
    } else {
    // Collect current calibration point data
    }
    }

calibrationFinishCallback

onCalibrationFinished

async onCalibrationFinished(calibrationData)

Calibration finish callback.

calibrationData is the result calibration data.

  • parameter

    • calibrationData

      • type: String
      • description: Calibration data.
  • return: undefined

  • usage:

      async onCalibrationFinished(calibrationData){
    this.calibrating = false;
    this.calibrationData = calibrationData;
    this.setCalibrationData(this.calibrationData);
    }

UserStatusCallback

The User Status includes Attention, Drowsiness, and Blink.

Attention: How much the user attention is focused on the screen content for interval time (0.0 ~ 1.0)

  • Timestamp range of the data will be passed as timestampBegin and timestampEnd in onAttention callback.
  • The default time interval is 30 seconds.
  • If the user attention level is low, score in onAttention callback will be closed to 0.0.
  • If the user attention level is high, score in onAttention callback will be closed to 1.0.

Drowsiness: If the user feel drowsiness (True/False)

  • Timestamp of the data will be passed as timestamp in onDrowsiness callback.
  • If the user feel Drowsiness, isDrowsiness in onDrowsiness callback will be true.
  • Otherwise, isDrowsiness will be false.

Blink: If the user blink eyes (left eye, right eye, general(both eyes))

  • Timestamp of the data will be passed as timestamp in onBlink callback.
  • If the user blink left eye, isBlinkLeft in onBlink callback will be true.
  • If the user blink right eye, isBlinkRight in onBlink callback will be true.
  • If the user blink eyes, isBlink in onBlink callback will be true (This is a general blink condition).
  • If the user's eyes are wide, eyeOpenness in onBlink callback will be closed to 1.0 (not available yet).
  • If the user's eyes are narrow, eyeOpenness in onBlink callback will be closed to 0.0 (not available yet).

onAttention

onAttention(timestampBegin, timestampEnd, score)
  • parameter:

    • timestampBegin

      • type: Number
      • description: Beginning Timestamp of the data.
    • timestampEnd

      • type: Number
      • description: Ending Timestamp of the data.
    • score

      • type: Number
      • description: User Attention rate score between the timestamps.
  • return: undefined

  • usage:

    onAttention(timestampBegin, timestampEnd, score) {
    this.attentionScore = score;
    }
    this.seeso.addAttentionCallback(onAttention);

onDrowsiness

onDrowsiness(timestamp, isDrowsiness)
  • parameter:

    • timestamp

      • type: Number
      • description: Timestamp of the data.
    • isDrowsiness

      • type: boolean
      • description: User Drowsiness flag.
  • return: undefined

  • usage:

    onDrowsiness(timestamp, isDrowsiness) {
    this.isDrowsiness = isDrowsiness;
    }
    this.seeso.addDrowsinessCallback(onDrowsiness);
onBlink(timestamp, isBlinkLeft, isBlinkRight, isBlink, eyeOpenness)
  • parameter:

    • timestamp

      • type: Number
      • description: Timestamp of the data.
    • isBlinkLeft

      • type: boolean
      • description: User Left Blink flag.
    • isBlinkRight

      • type: boolean
      • description: User Right Blink flag.
    • isBlink

      • type: boolean
      • description: User Blink flag.
    • eyeOpenness

      • type: Number
      • description: User EyeOpenness rate (not available yet).
  • return: undefined

  • usage:

    onBlink(timestamp, isBlinkLeft, isBlinkRight, isBlink, eyeOpenness) {
    this.isBlinkLeft = isBlinkLeft;
    this.isBlinkRight = isBlinkRight;
    this.isBlink = isBlink;
    this.eyeOpenness = eyeOpenness;
    }
    this.seeso.addBlinkCallback(onBlink);