Skip to main content

API Docs

GazeTracker#

  @objc public class GazeTracker: NSObject

GazeTracker is the class that generates gaze tracking data from the video from the device's front camera.

Construction#

initGazeTracker#

  @objc public static func initGazeTracker(license: String,  delegate InitailizationDelegate, option: UserStatusOption? = nil)

GazeTracker constructing process includes authentication.

Function is asynchronous.

InitializationDelegate will relay constructed object.

  • parameter:

    • license:

      • type: String, NSString *
      • description: Key generated from console.seeso.io
    • delegate

      • type: InitailzationDelegate, id <InitializationDelegate>
      • description: Delegate represents initialization status
    • option

      • type: UserStatusOption
      • description: A class containing User status option information (optional)
  • return: Void

  • usage:

      GazeTracker.initGazeTracker(license: "YOUR_LICENSE_KEY", delegate: self)
      let userStatusOption = UserStatusOption()  userStatusOption.useAll()
      GazeTracker.initGazeTracker(license: "YOUR_LICENSE_KEY", delegate: self, option: userStatusOption)

Destruction#

deinitGazeTracker#

  @objc public static func deinitGazeTracker(tracker: GazeTracker?)

After the destruction, every API will be disabled.

For memory optimization, assigning nil to the destructed object is recommended.

  • parameter

    • tracker

      • type: GazeTracker?, GazeTracker *
      • description: Target GazeTracker instance of destruction
  • return: Void

  • usage:

      GazeTracker.deinitGazeTracker(tracker: tracker);  tracker = nil

Gaze Tracking#

startTracking#

@objc public func startTracking()

This is the function that should be called before starting gaze tracking.

It calls the onStarted() function in the StatusCallback object when succeeded.

  • parameter: X

  • return: Void

  • usage:

    tracker.startTracking()

stopTracking#

  @objc public func stopTracking()

his function is called to stop gaze tracking.

It calls the StatusDelegate.onStop() object when succeed.

  • parameter: X

  • return: Void

  • usage:

    tracker.stopTracking()

isTracking#

@objc public func isTracking() โ†’ Bool

This function represents the status of gaze tracking.

It returns true when gaze tracking is working, false when gaze tracking is stopped.

  • parameter: X

  • return: Bool, BOOL

  • usage:

      let isTracking = tracker.isTracking();  print("Tracking status: \(isTracking)")

isCalibrating#

  @objc public func isCalibrating() โ†’ Bool

It returns true when calibrating, false when when not calibrating.

  • parameter: X

  • return: Bool, BOOL

  • usage:

    let isCalibrating = tracker.isCalibrating();print("Calibrating status: \(isCalibrating)")

setTrackingFPS#

  @objc public func setTrackingFPS(fps: Int) โ†’ Bool

The parameter that sets the FPS of the gaze tracking source.

Its value should bigger than 0 and no more than 30.

FPS can be dropped due to device spec. The default value is 30.

If state is TrackingState.FACE_MISSING, FPS will set as 30 automatically.

  • parameter

    • fps

      • type: Int, NSIntger
      • description: Custom FPS(Frame Per Second) for gaze tracking
  • return: Bool, BOOL

  • usage:

      tracker.setTrackingFPS(fps: 20)

UserStatus Setting#

setAttentionInterval#

  @objc public func setAttentionInterval(interval : Int)

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: Int, NSInteger
      • description: Time interval for the UserStatus Attention score.
  • return: Void

  • usage:

      tracker.setAttentionInterval(interval: 30)

Get UserStatus Data#

getAttentionScore#

  @objc public func getAttentionScore() -> Double

Get current Attention score from the GazeTracker.

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: Double, double

  • usage:

      let score = tracker.getAttentionScore()

Calibration#

startCalibration#

  @objc public func  startCalibration(mode: CalibrationMode?, criteria : AccuracyCriteria?, region: CGRect?) โ†’ Bool

There are four cases at function returns. It returns true when parameters are valid.

If startCalibration() was called when the tracker is not tracking, it will return false.

If the value of mode is not defined, the function returns false.

It also returns false when the calibration region has been set outside of the device screen.

The false return will block the calibration process.

  • parameter

    • mode

      • type: CalibrationMode?
      • description: Can select calibration option. Three options โ€” DEFAULT(0), ONE_POINT(1), FIVE_POINT(5), SIX_POINT(6) โ€” are available. Default is FIVE_POINT.
      • default: DEFAULT(0)
    • region

      • type: CGRect?
      • description: Region that needs calibration. The unit is point(pt).
      • default: Full screen region of device.
    • criteria

      • type: AccuracyCriteria?
      • description: Option that manage calibration process and accuracy. Three options - DEFAULT(0), LOW(1), HIGH(2) - are available. Default is DEFAULT.
      • default: DEFAULT(0)
  • return: Bool, BOOL

  • usage:

      let startedResult = tracker.startCabliration(mode: .ONE_POINT, region: CGRect(x: 100, y: 100, width: 100, height: 100))  let startedResult2 = tracker.startCabliration(mode: .ONE_POINT)  let startedResult3 = tracker.startCabliration(region: CGRect(x: 100, y: 200, width: 300, height: 400))  let startedResult4 = tracker.startCabliration()

stopCalibration#

  @objc public func stopCalibration()
  • parameter: X

  • return: Void

  • usage:

      tracker.stopCalibration()

startCollectSamples#

  @objc public func startCollectSamples()
  - (BOOL)startCollectSamples;

This relays the coordinates of the point that should be seen when calibration is in progress at the function: CalibrationDelegate.onCalibrationNextPoint.

If startCollectionSamples calling timing went wrong, it will return false You should display coordinates on the screen and call startCollectSamples for calibration.

tip

If startCollectSamples returns false when using SwiftUI, it may be caused because of timing issue between the SwiftUI and the core logic. You may add approximately 0.5 or 1 second delay to fix the issue.

  • parameter: X

  • return: Bool, BOOL

  • usage:

      tracker.startCollectSamples()

setCalibrationData#

  @objc public func setCalibrationData(calibrationData : [Double]) -> Bool

Set existing calibration data to gazeTracker.
If setCalibrationData() was called when the tracker is not tracking, it will return false.

  • parameter

    • calibrationData

      • type: [Double], NSArray<NSNumber *> *
      • description: Calibration Data
  • return: Bool, BOOL

  • usage:

      if (tracker.setCalibrationDat(calibrationData : data)) {      print("Loading of calibration data was successful.")  }else {      pirnt("Failed to load calibration data.")  }

Camera Preview#

setCameraPreview#

  @objc public func setCameraPreview(cameraPreview: UIView)

This is a preview of the camera that GazeTracker using.

You should rotate the screen if landscape mode

  • parameter

    • cameraPreview

      • type: UIView, UIView *
      • description: UIView for camera preview.
  • return: Void

  • usage:

      tracker.setCamerapreview(preview: preview)

removeCameraPreview#

  @objc public func removeCaemraPreview()

This will remove the camera preview that set at GazeTracker.

  • parameter: X

  • return: Void

  • usage:

      tracker.removeCameraPreview();

Version Check#

getFrameworkVersion#

  @objc public static func getFrameworkVersion() โ†’ String

This will return SeeSo framework version.

This will return SeeSo framework version.

  • parameter: X

  • return: String, NSString *

  • usage:

      let version = GazeTracker.getFrameworkVersion()  print("SeeSo version: \(version)")

Delegates assistants#

setDelegates#

  @objc public func setDelegates(statusDelegate: StatusDelegate? , gazeDelegate: GazeDelegate? , calibrationDelegate: CalibrationDelegate?, imageDelegate: ImageDelegate?, userStatusDelegate: UserStatusDelegate? = nil)

Enroll all delegates that inherited GazeTrackerDelegate to GazeTracker at once.

  • parameter

    • statusDelegate

      • type: StatusDelegate?, id<StatusDelegate>
    • gazeDelegate

      • type: GazeDelegate?, id<GazeDelegate>
    • calibrationDelegate

      • type: CalibrationDelegate?, id<CalibrationDelegate>
    • imageDelegate

      • type: ImageDelegate?, id<ImageDelegate>
    • userStatusDelegate (optional)

      • type: UserStatusDelegate, id<UserStatusDelegate>
  • return: Void

  • usage:

      // parameter is nullable: attributes are selective.  tracker.setDelegates(statusDelegate: statusDelegate, gazeDelegate: self);

statusDelegate#

  @objc public weak var statusDelegate: StatusDelegate? = nil

Can enroll and remove StatusDelegate in GazeTracker easily.

  • type: StatusDelegate?, id <StatusDelegate>

  • description: StatusDelegate variable uses in GazeTracker

  • usage:

      tracker.statusDelegate = self // enroll delegate  tracker.statusDelegate = nil // remove delegate

gazeDelegate#

@objc public weak var gazeDelegate: GazeDelegate? = nil

Can enroll and remove GazeDelegate in GazeTracker easily.

  • type: GazeCallback, id<GazeCallback>

  • description: GazeDelegate variable uses in GazeTracker

  • usage:

      tracker.gazeDelegate = self // enroll delegate  tracker.gazeDelegate = nil // remove delegate

calibrationDelegate#

  @objc public weak var calibrationDelegate: CalibrationDelegate? = nil

Can enroll and remove CalibrationDelegate in GazeTracker easily.

  • type: CalibraitonDelegate, id<CalibrationDelegate

  • description: CalibrationDelegate variable uses in GazeTracker

  • usage:

      tracker.calibrationDelegate = self // enroll delegate  tracker.calibrationDelegate = nil // remove delegate

imageDelegate#

  @objc public weak var imageDelegate: ImageDelegate? = nil

Can enroll and remove ImageDelegate in GazeTracker easily.

  • type: ImageDelegate, id<ImageDelegate>>

  • description: ImageDelegate variable uses in GazeTracker

  • usage:

      tracker.imageDelegate = self // enroll delegate  tracker.imageDelegate = nil // remove delegate

userStatusDelegate#

  @objc public weak var userStatusDelegate: UserStatusDelegate? = nil

Can enroll and remove UserStatusDelegate in GazeTracker easily.

  • type: UserStatusDelegate, id<UserStatusDelegate>

  • description: UserStatusDelegate variable uses in GazeTracker

  • usage:

      tracker.userStatusDelegate = self // enroll delegate  tracker.userStatusDelegate = nil // remove delegate

Class#

UserStatusOption#

  @objc public class UserStatusOption: NSObject

The class contains User Status options information for GazeTracker

  • functions:

    • isUseAttention

      • parameter: x
      • return: Bool, BOOL
      • description: Return true if Attention flag is on, otherwise return false.
    • isUseBlink

      • parameter: x
      • return: Bool, BOOL
      • description: Return true if Blink flag is on, otherwise return false.
    • isUseDrowsiness

      • parameter: x
      • return: Bool, BOOL
      • description: Return true if Drowsiness flag is on, otherwise return false.
    • useAttention

      • parameter: x
      • return: Void
      • description: Set Attention flag.
    • useBlink

      • parameter: x
      • return: Void
      • description: Set Blink flag.
    • useDrowsiness

      • parameter: x
      • return: Void
      • description: Set Drowsiness flag.
    • useAll

      • parameter: x
      • return: Void
      • description: Set All User Status flag.

GazeInfo#

  @objc public class GazeInfo : NSObject

x#

@objc public let x : Double

x coordinate value of gaze point. Origin is device screen. The unit is pixel(pt).

y#

@objc public let y : Double

y coordinate value of gaze point. Origin is device screen. The unit is pixel(pt).

timestamp#

@objc public let timestamp : Double

Timestamp of gaze point. The unit is millisecond. The time format is UTC.

trackingState#

@objc public let trackingState : TrackingState

SUCCESS, LOW_CONFIDENCE, UNSUPPORTED, FACE_MISSING

eyemovementState#

@objc public let eyemovementState : EyeMovementState

FIXATION, SACCADE, UNKNOWN

screenState#

@objc public let screenState : ScreenState

INSIDE_OF_SCREEN, OUTSIDE_OF_SCREEN, UNKNOWN

GazeTrackerDelegate#

  @objc public protocol GazeTrackerDelegate

protocol variable uses in GazeTracker. All delegate in GazeTracker inherit GazeTrackerDelegate.

InitializationDelegate#

  @objc public protocol InitailizationDelegate: GazeTrackerDelegate

onInitialized#

  @objc public func onInitialized(tracker: GazeTracker?, error: InitializationError);

The callback function that calls when GazeTracker.init function is called.

It returns a constructed object when succeed, but nil if failed.

The error will be set by its type when construction failed.

  • parameter

    • tracker

      • type: GazeTracker?, GazeTracker *
      • description: Relay GazeTracker when construction succeed. Relay nil if failed.
    • error

      • type: InitializationError
      • description: The enum that contains error types of initGazeTracker.
  • return: Void

  • usage:

      public func onInitialized( tracker: GazeTracker?, error: InitializationError){    if (tracker != nil) {      // Take object as class property when initialzation succeed      this.tracker = tracker;    } else {      if (error == InitializationError.ERROR_INIT) {        print("Initialization failed")      } else if (error == InitializationError.ERROR_CAMERA_PERMISSION) {         ...       }    }  }

StatusDelegate#

 @objc public protocol StatusDelegate: GazeTrackerDelegate

onStarted#

  public func onStarted()

The function that automatically calls after GazeTracker.StartTracking succeed. Actions like calibration, preview, etc. are available after it.

  • parameter: X

  • return: Void

  • usage:

      public func onStarted(){   tracker.startCalibration()}

onStopped#

  public void onStopped(error: StatusError)

Error value will be StatusError.ERROR_NONE if gaze tracking stopped after GazeTracker.onStopTracking called but different values for a different statuses.

It works properly when startTracking explicitly called at the gaze tracker stopping process.

  • parameter:

    • error

      • type: StatusError
      • description: StatusError.ERROR_NONE, StatusError.ERROR_CAMERA_START, StatusError.ERROR_CAMERA_INTERRUPT are available.
  • return: Void

  • usage:

      public void onStopped(error: StatusError) {      if (error != .ERROR_NONE) {      // stopTracking() is not called    }  }

GazeDelegate#

  @objc public protocol GazeDelegate: GazeTrackerDelegate

onGaze#

  @objc public func onGaze(gazeInfo : GazeInfo)
  • parameter

    • gazeInfo

      • type: GazeInfo
  • return: void

  • usage:

      public func onGaze(gazeInfo : GazeInfo){        if ( gazeInfo.trackingState == TrackingState.SUCCESS){      // Gaze tracking succeed after calibration        }else {      // Face Missing    }  }

CalibrationDelegate#

  @objc public protocol CalibrationDelegate: GazeTrackerDelegate

CalibrationDelegate is never called on the main queue. Please use DispatchQueue.main.async when using UI.


onCalibrationNextPoint#

  @objc public func onCalibrationNextPoint(x: Double,  y: Double)

The x, y coordinate value of the gaze point that should be focused during the calibration process.

You should call startCollectSamples to keep process the calibration.

  • parameter:

    • x, y

      • type: Double, double
      • description: The x, y coordinate value of the gaze point that should be focused during the calibration process. Origin is the device screen. The unit is point(pt)
  • return: Void

  • usage:

      public func onCalibrationNextPoint(x: Double, y: Double){    // Display UI at given point    // call startCollectSamples() like below for start calibration    tracker.startCollectSamples()  }

onCalibrationProgress#

  @objc public func onCalibrationProgress(progress: Double)

Progress will be between 0.0~1.0.

The next point will be guided when the value reaches 1.0.

  • parameter:

    • progress

      • type: Double, double
      • description: Calibration progression for each point.
  • return: Void

  • usage:

      public func onCalibrationProgress(progress: Double){    progress.setProgress(progress)  }

onCalibrationFinished#

  @objc public func onCalibrationFinished(calibrationData: [Double])

Callback for notify calibration ends. When this function is called, the calibration UI will be removed. After this callback, data from GazeDelegate will be calibrated gaze data.

The calibrationData passed as a parameter has already been applied to GazeTracker,

and you can save it and load the this calibration data directly into GazeTracker without new calibration by calling setCalibrationData(calibrationData) when restarting the app etc..

  • parameter:

    • calibrationData

      • type: [Double], NSArray<NSNumber *> *
      • description: Calibration Data
  • return: Void

  • usage:

      public func onCalibrationFinished(calibrationData: [Double]) {    //Remove calibration UI    removeCalibrationUI()    //save calibration Data    self.calibrationData = calibrationData  }

ImageDelegate#

  @objc public protocol ImageDelegate: GazeTrackerDelegate

onImage#

  @objc public func onImage(timestamp: Double,  image: CMSampleBuffer)

The function that provide the image as CMSampleBuffer form.

  • parameter:

    • timestamp

      • type: Double, double
      • description: The timestamp of camera image creation. The unit is millisecond. The time format is UTC.
    • image

      • type: CMSampleBuffer, CMSampleBufferRef
      • description: CMSampleBuffer type image from camera((kCVPixelFormatType_32BGRA, AVCaptureSession.Preset.vga640x480). The direction is 90 deg rotated as CCW from portrait direction.
  • return: Void

  • usage:

      public func onImage(timestamp: Double, image: CMSampleBuffer){    // SAMPLE: save image as jpeg with proper function    if imageSave {        writeJPEGFile(image: image);    }  }

UserStatusDelegate#

  @objc public protocol UserStatusDelegate: GazeTrackerDelegate

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#

  @objc public func onAttension(timestampBegin: Int, timestampEnd: Int, score: Double)
  • parameter:

    • timestampBegin

      • type: Int, NSInteger
      • description: Beginning Timestamp of the data.
    • timestampEnd

      • type: Int, NSInteger
      • description: Ending Timestamp of the data.
    • score

      • type: Double, double
      • description: User Attention rate score between the timestamps.
  • return: Void

  • usage:

      func onAttension(timestampBegin: Int, timestampEnd: Int, score: Double) {    attentionView.text = "Attention: " + String(round(score * 10000) / 10000)  }

onBlink#

  @objc public func onBlink(timestamp: Int, isBlinkLeft: Bool, isBlinkRight: Bool, isBlink: Bool, eyeOpenness: Double)
  • parameter:

    • timestamp

      • type: Int, NSInteger
      • description: Timestamp of the data.
    • isBlinkLeft

      • type: Bool, BOOL
      • description: User Left Blink flag.
    • isBlinkRight

      • type: Bool, BOOL
      • description: User Right Blink flag.
    • isBlink

      • type: Bool, BOOL
      • description: User Blink flag.
    • eyeOpenness

      • type: Double, double
      • description: User EyeOpenness rate (not available yet).
  • return: Void

  • usage:

      func onBlink(timestamp: Int, isBlinkLeft: Bool, isBlinkRight: Bool, isBlink: Bool, eyeOpenness: Double) {    blinkView.text = "Blink: " + String(isBlink)    blinkLeftView.text = "Blink Left: " + String(isBlinkLeft)    blinkRightView.text = "Blink Right: " + String(isBlinkRight)}

onDrowsiness#

  @objc public func onDrowsiness(timestamp: Int, isDrowsiness: Bool)
  • parameter:

    • timestamp

      • type: Int, NSInteger
      • description: Timestamp of the data.
    • isDrowsiness

      • type: Bool, BOOL
      • description: User Drowsiness flag.
  • return: Void

  • usage:

      func onDrowsiness(timestamp: Int, isDrowsiness: Bool) {    drowsinessView.text = "Drowsiness: " + String(isDrowsiness)  }

ENUM#

InitializationError#

  @objc public enum InitializationError: Int

The enum that contains error types of InitializationDelegate.

Please read : Authentication for more details.

StatusError#

  @objc public enum StatusError: Int

The enum that contains error types of StatusDelegate

  • constant:

    • ERROR_NONE

      • value: 0
      • description: GazeTracker.stopTracking call succeed without error.
    • ERROR_CAMERA_START

      • value: 1
      • description: Error code occurs when GazeTracker.startTracking is called but front camera of device is not available.
    • ERROR_CAMERA_INTERRUPT

      • value: 2
      • description: Error code occurs when camera is unavailable.

TrackingState#

  @objc public enum TrackingState: Int

The enum that contains state types using at GazeDelegate.

  • constant:

    • SUCCESS

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

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

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

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

CalibrationMode#

  @objc public enum CalibrationMode: Int

The enum that contains mode types of GazeTracker.startCalibartion .

  • constants:

    • DEFAULT

      • value: 0
      • description: Default. Represent FIVE_POINT.
    • ONE_POINT

      • value: 1
      • description: One-point calibration mode.
    • FIVE_POINT

      • value: 5
      • description: Five-point calibration mode.
    • SIX_POINT

      • value: 6
      • description: Six-point calibration mode.

AccuracyCriteria#

  @objc public enum AccuracyCriteria: Int

The enum that contains accuracy criteria of GazeTracker.startCalibartion.

  • enum

    • DEFAULT

      • value: 0
      • description: Default calibration accuracy criteria.
    • LOW

      • value: 1
      • description: Low calibration accuracy criteria.
    • HIGH

      • value: 2
      • description: High calibration accuracy criteria.

EyeMovementState#

  @objc public enum EyeMovementState: Int
  • constants:

    • FIXATION

      • value: 0
    • SACCADE

      • value: 2
    • UNKNOWN

      • value: 3

ScreenState#

  @objc public enum ScreenState: Int
  • constants:

    • INSIDE_OF_SCREEN

      • value : 0
      • description: Gaze tracking is success and the gaze point is inside of device screen
    • OUTSIDE_OF_SCREEN

      • value : 1
      • description: Gaze tracking is success and the gaze point is outside of device screen
    • UNKNOWN

      • value : 2
      • description: Gaze tracking is fail