Version: Eyedid Beta

API Docs (Java)

Overview

Name	type	Description
GazeTracker	`class`	The main class that captures the user's face through the device's camera, processes it, and provides gaze data.
GazeTrackerOptions	`class`	Class for configuring various options when creating a `GazeTracker`.
GazeTrackerOptions.builder	`class`	Builder class for creating an instance of `GazeTrackerOptions`.
CameraPosition	`class`	Class for managing the physical position information of the camera.
GazeInfo	`class`	A class that contains information about gaze tracking.
FaceInfo	`class`	A class containing information about face tracking.
BlinkInfo	`class`	Represents information about eye blinking.
UserStatusInfo	`class`	Represents information about user is status
OneEuroFilterManager	`class`	The OneEuroFilterManager class manages multiple One Euro Filters.
ViewLayoutChecker	`class`	This class is used to calculate the view's offset depending on the ActionBar, StatusBar, and NavigationBar.
InitializationCallback	`interface`	Callback interface to notify the result of the `GazeTracker` initialization attempt.
TrackingCallback	`interface`	Provides all the metrics tracked by `GazeTracker` for each camera frame.
StatusCallback	`interface`	Interface callback to notify the status of the `GazeTracker`.
CalibrationCallback	`interface`	A callback class that provides the status of the calibration process.
ImageCallback	`interface`	Callback interface for receiving images from the front camera.
CalibrationModeType	`enum`	Enum representing the calibration mode types for starting calibration.
AccuracyCriteria	`enum`	Enum representing the accuracy criteria for starting calibration.
CameraPreset	`enum`	Enum representing the available camera resolution presets.
InitializationErrorType	`enum`	Enum representing the different types of initialization errors that can occur during the setup of the Gaze Tracker system.
TrackingState	`enum`	Enum representing the state of gaze tracking.
EyeMovementState	`enum`	Enum representing the state of eye movement.
ScreenState	`enum`	Enum representing the state of whether the gaze is inside or outside of the screen.
StatusErrorType	`enum`	Enum that describes the reason why gaze tracking stopped.

GazeTracker

public class GazeTracker

The main class that captures the user's face through the device's camera, processes it, and provides gaze data.

note

Requires the android.permission.CAMERA permission.

Summary

Function	Description	Return Type	Type
initGazeTracker	Initializes the GazeTracker.	`void`	Static
releaseGazeTracker	Release the GazeTracker.	`void`	Static
getVersionName	Retrieves the version name.	`String`	Static
startTracking	Starts the tracking process.	`void`	Member
stopTracking	Stops the tracking process.	`void`	Member
isTracking	Checks if tracking is active.	`boolean`	Member
hasCameraPositions	Checks if a Checks whether CameraPosition information is available.	`boolean`	Member
addCameraPosition	Adds a camera position.	`void`	Member
getCameraPosition	Retrieves the current camera position.	CameraPosition	Member
getCameraPositionList	Retrieves the list of camera positions.	`ArrayList<CameraPosition>`	Member
selectCameraPosition	Selects a specific camera position.	`void`	Member
setTrackingCallback	Sets the TrackingCallback	`void`	Member
removeTrackingCallback	Removes the TrackingCallback	`void`	Member
setStatusCallback	Sets the StatusCallback.	void	Member
removeStatusCallback	Removes the StatusCallback.	void	Member
setCalibrationCallback	Sets the CalibrationCallback.	`void`	Member
removeCalibrationCallback	Removes the CalibrationCallback.	`void`	Member
setImageCallback	Sets the ImageCallback.	`void`	Member
removeImageCallback	Removes the ImageCallback.	`void`	Member
setCallbacks	Registers multiple callbacks at once.	`void`	Member
removeCallbacks	Removes all currently set callbacks	`void`	Member
setTrackingFPS	Sets the tracking FPS.	`boolean`	Member
setCameraPreview	Sets the camera preview.	`void`	Member
removeCameraPreview	Removes the camera preview.	`void`	Member
startCalibration	Starts the calibration process.	`boolean`	Member
stopCalibration	Stops the calibration process.	`void`	Member
isCalibrating	Checks if calibration is in progress.	`boolean`	Member
startCollectSamples	Starts collecting calibration samples.	`void`	Member
setCalibrationData	Sets the calibration data.	`void`	Member
setAttentionRegion	Sets the attention region.	`void`	Member
getAttentionRegion	Retrieves the attention region.	`RectF`	Member
removeAttentionRegion	Removes the attention region.	`void`	Member

initGazeTracker

public static void initGazeTracker(Context context, String licenseKey, @NonNull InitializationCallback callback, @Nullable GazeTrackerOptions options)
public static void initGazeTracker(Context context, String licenseKey, @NonNull InitializationCallback callback)

GazeTracker construction requires authentication.

The function is asynchronous.

The created GazeTracker instance is delivered through InitializationCallback.

Parameters	Type	Description
context	`android.content.Context`	The context in which the GazeTracker will be used.
licenseKey	`String`	The license key required to activate the GazeTracker.
callback	InitializationCallback	The callback to receive initialization status.
options	GazeTrackerOptions	Optional GazeTracker configuration options.

Example

// Implement InitializationCallback
InitializationCallback initializationCallback = new InitializationCallback() {
  @Override
  public void onInitialized(GazeTracker gazeTracker, InitializationErrorType error) {
    if (gazeTracker != null) {
        // gazeTracker init success
    } else {
        // gazeTracker init fail
    }
  }
};

GazeTrackerOptions options = null;

if (useBlink) {
    options = new GazeTrackerOptions.Builder()
                                    .setUseBlink(true)
                                    .build();
}

GazeTracker.initGazeTracker(context, "YOUR_LICENSE_KEY", initializationCallback, options);

releaseGazeTracker

public static void releaseGazeTracker(GazeTracker gazeTracker)

Releases the resources used by the specified GazeTracker. After this is called, do not call gazeTracker's methods.

tip

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

Parameters	Type	Description
gazeTracker	GazeTracker	The GazeTracker instance to be released.

Example

// Implement InitializationCallback
InitializationCallback initializationCallback = new InitializationCallback() {
  @Override
  public void onInitialized(GazeTracker gazeTracker, InitializationErrorType error) {
    if (gazeTracker != null) {
      // gazeTracker init success

      // you can deinit gazeTracker instance
      GazeTracker.releaseGazeTracker(gazeTracker);
      gazeTracker = null;

    } else {
      // gazeTracker init fail
    }
  }
};

GazeTracker.initGazeTracker(context, "YOUR_LICENSE_KEY", initializationCallback);

getVersionName

public static String getVersionName()

Retrieves the version name of the Eyedid SDK.

Parameters	Type	Description
versionName	`string`	Eyedid SDK Version

Example

String version = GazeTracker.getVersionName();
System.out.println("Eyedid SDK version :" + version);

startTracking

public synchronized void startTracking()

Opens the camera and starts gaze tracking.

note

On successful start, StatusCallback.onStarted() is called.

Example

private InitializationCallback initializationCallback = new InitializationCallback() {
  @Override
    public void onInitialized(GazeTracker gazeTracker, InitializationErrorType error) {
      if (gazeTracker != null) {
        // gazeTracker init success

        // set StatusCallback
        gazeTracker.setStatusCallback(statusCallback);

        // startTracking
        gazeTracker.startTracking();

      } else {
        // gazeTracker init fail
      }
  }
};

private StatusCallback statusCallback = new StatusCallback() {
  @Override
  public void onStarted() {
    // gazeTracker.startTracking() Success
  }

  @Override
  public void onStopped(final StatusErrorType error) {
    // gazeTracker.startTracking() Fail
  }
};

GazeTracker.initGazeTracker(context, "YOUR_LICENSE_KEY", initializationCallback);

stopTracking

public synchronized void stopTracking()

Closes the camera and stops gaze tracking.

note

On successful stop, StatusCallback.onStopped() is called.

Example

// Implement StatusCallback and already set callback to gazeTracker
private StatusCallback statusCallback = new StatusCallback() {
  @Override
  public void onStarted() {

  }

  @Override
  public void onStopped(final StatusErrorType error) {
    // gazeTracker.stopTracking() Success
  }
};

gazeTracker.stopTracking();

isTracking

public synchronized boolean isTracking()

Checks whether the GazeTracker is currently tracking.

Return Type	Description
`boolean`	true if gaze tracking is active.

Example

boolean isTracking = gazeTracker.isTracking();
System.out.println("Tracking state : " + isTracking);

hasCameraPosition

public boolean hasCameraPosition()

Checks whether CameraPosition information is available.

note

If false, no device information is available, and default values are set.

Return Type	Description
`boolean`	true if CameraPosition information is available.

Example

boolean hasCp = tracker.hasCameraPosition();
System.out.println("hasCameraposition " + hasCp);

addCameraPosition

public void addCameraPosition(CameraPosition cameraPosition)

Adds a CameraPosition to the GazeTracker.

Parameters	Type	Description
cameraPosition	CameraPosition	The CameraPosition instance to be added.

Example

CameraPosition cameraPosition = new CameraPosition("SM-T720", 1600f, 2560f, -72f, -4f);// galaxy tab s5e
tracker.addCameraPosition(cameraPosition);

getCameraPosition

public CameraPosition getCameraPosition()

Returns the currently set CameraPosition instance.

Return Type	Description
CameraPosition	null if no CameraPosition is set.

Example

if (tracker.hasCameraPosition()) {
  CameraPosition cameraPosition = tracker.getCameraPosition();
  System.out.println(cameraPosition.modelName + " : " + cameraPosition.screenOriginX + " : " + cameraPosition.screenOriginY);
}

getCameraPositionList

public ArrayList<CameraPosition> getCameraPositionList()

Returns the list of CameraPosition instances associated with this device in the GazeTracker.

Return Type	Description
`ArrayList<CameraPosition>`	ArrayList of `CameraPosition` of the device. A device can have multiple CameraPosition (ex. Galaxy Fold)

Example

if(tracker.hasCameraPosition()) {
  ArrayList<CameraPosition> cameraPositionList = tracker.getCameraPositionList();
  for (CameraPosition cameraPosition : cameraPositionList) {
    System.out.println(cameraPosition.modelName + " : " + cameraPosition.screenOriginX + " : " + cameraPosition.screenOriginY);
  }
}

selectCameraPosition

public void selectCameraPosition(int idx)

Sets the selected camera position from the list of available CameraPositions.

Parameters	Type	Description
idx	`Int`	The index of the camera position in the list.

Example

tracker.selectCameraPosition(0);

setTrackingCallback

public void setTrackingCallback(TrackingCallback callback)

Registers a callback to receive tracking events. This callback will be triggered during the tracking process to handle tracking-related updates.

Parameters	Type	Description
callback	TrackingCallback	An instance of TrackingCallback that will handle tracking events.

Example

//implement Tracking Callback
private TrackingCallback trackingCallback = new TrackingCallback() {
  @Override
  public void onMetrics(
      long timestamp,
      GazeInfo gazeInfo,
      FaceInfo faceInfo,
      BlinkInfo blinkInfo,
      UserStatusInfo userStatusInfo) {
    // do something
  }
};

gazeTracker.setTrackingCallback(trackingCallback);

removeTrackingCallback

public void removeTrackingCallback()

Removes the currently set TrackingCallback.

Example

gazeTracker.removeTrackingCallback();

setStatusCallback

public void setStatusCallback(StatusCallback callback)

Registers a callback to receive GazeTracker status updates. This callback is triggered when there is a change in the GazeTracker's status.

Parameters	Type	Description
callback	StatusCallback	An instance of StatusCallback that will handle status changes in the GazeTracker.

Example

//implement statusCallback
gazeTracker.setStatusCallback(statusCallback);

removeStatusCallback

public void removeStatusCallback()

Removes the currently set GazeTrackerStatusCallback.

Example

gazetracker.removeStatusCallback();

setCalibrationCallback

public void setCalibrationCallback(CalibrationCallback callback)

Registers a callback to receive calibration events. This callback will be triggered during calibration processes.

Parameters	Type	Description
callback	CalibrationCallback	An instance of CalibrationCallback that will handle calibration events.

Example

//implement calibrationCallback
private CalibrationCallback calibrationCallback = new CalibrationCallback() {

@Override
public void onCalibrationProgress(final float progress) {
  runOnUiThread(new Runnable() {
    @Override
    public void run() {
      // process calibration point UI
    }
  });
}

@Override
public void onCalibrationNextPoint(final float x, final float y) {
  runOnUiThread(new Runnable() {
    @Override
    public void run() {
      // draw calibration point to (x,y)
    }
  });
  handler.postDelayed(new Runnable() {
    @Override
    public void run() {
      // After drawing the calibration point,
      // call startCollectSamples after enough time (1,000 ms in this example) that considering user can recognize the point
      boolean isStart = gaze.startCollectSamples();
    }
  }, 1000);
}

@Override
public void onCalibrationFinished(double[] calibrationData) {
  // saveCalibration(calibrationData);
  runOnUiThread(
    new Runnable() {
      @Override
      public void run() {
        //remove calibration UI
      }
    });
  }
};

gazeTracker.setCalibrationCallback(calibrationCallback);

removeCalibrationCallback

public void removeCalibrationCallback()

Removes the currently set Calibration callback.

Example

gazeTracker.removeCalibrationCallback();

setImageCallback

public void setImageCallback(ImageCallback callback)

Registers a callback for camera buffer images. This callback is triggered when an image is captured from the camera buffer.

Parameters	Type	Description
callback	ImageCallback	An instance of ImageCallback that will handle the camera image data.

Example

//implement imageCallback
private ImageCallback imageCallback = new ImageCallback() {
  @Override
  public void onImage(long timestamp, final byte[] buffer) {
    uiHandler.post(new Runnable() {
      @Override
      public void run() {
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        YuvImage yuvImage = new YuvImage(buffer, ImageFormat.NV21, 640, 480, null);
        yuvImage.compressToJpeg(new Rect(0, 0, 640, 480), 50, out);
        byte[] imageBytes = out.toByteArray();
        Bitmap image = BitmapFactory.decodeByteArray(imageBytes, 0, imageBytes.length);
        imgBuffer.setImageBitmap(image);
      }
    });
  }
};
gazeTracker.setImageCallback(imageCallback);

removeImageCallback

public void removeImageCallback()

Removes the currently set ImageCallback callback.

Example

gazeTracker.removeImageCallback();

setCallbacks

public void setCallbacks(Object callback...)

Registers multiple callbacks at once. The method checks the type of each callback and assigns it to the appropriate field.

Parameters	Type	Description
callback	`Object`	Varargs parameter that allows passing multiple callback objects. Supported types are TrackingCallback, CalibrationCallback, ImageCallback, and StatusCallback.

Example

//implement trackingCallback, calibrationCallback, statusCallback, imageCallback, 
gazeTracker.setCallbacks(trackingCallback, calibrationCallback, statusCallback, imageCallback);

removeCallbacks

public void removeCallbacks()

Removes all currently set callbacks.

Example

gazetracker.removeCallbacks();

setTrackingFPS

public boolean setTrackingFPS(int fps)

Sets the FPS (frames per second) for gaze tracking. If the eyes cannot be detected, the FPS setting may not be applied (gaze tracking calculations are bypassed), and the actual FPS may be lower than the specified value depending on the device's performance.

Parameters	Type	Description
fps	`int`	The desired frames per second for gaze tracking.

Return Type	Description
`boolean`	true if the FPS was successfully set, false otherwise.

Example

gazeTracker.setTrackingFPS(20);

setCameraPreview

public void setCameraPreview(android.view.TextureView cameraPreview)

Sets the camera preview using the specified TextureView.

Parameters	Type	Description
cameraPreview	`android.view.TextureView`	The TextureView to be used for the camera preview.

Example

TextureView preview = findViewById(R.id.preview);
gazeTracker.setCameraPreview(preview);

removeCameraPreview

public void removeCameraPreview()

Removes the camera preview set in the GazeTracker.

Example

gazeTracker.removeCameraPreview();

startCalibration

public boolean startCalibration(CalibrationModeType mode, AccuracyCriteria criteria, float left, float top, float right, float bottom)
public boolean startCalibration(CalibrationModeType mode, float left, float top, float right, float bottom)
public boolean startCalibration(CalibrationModeType mode)
public boolean startCalibration(float left, float top, float right, float bottom)
public boolean startCalibration(AccuracyCriteria criteria)
public boolean startCalibration(CalibrationModeType mode, AccuracyCriteria criteria)
public boolean startCalibration()

Starts the calibration process.

Parameters	Type	Description
mode	CalibrationModeType	The number of points to be used for calibration.
criteria	AccuracyCriteria	The accuracy criteria to be used for calibration.
left	`float`	The left coordinate of the calibration region.
top	`float`	The top coordinate of the calibration region.
right	`float`	The right coordinate of the calibration region.
bottom	`float`	The bottom coordinate of the calibration region.

Return Type	Description
`boolean`	true if the calibration process has started successfully, false otherwise.

Example

//implement calibrationCallback
private CalibrationCallback calibrationCallback = new TimeoutCalibrationCallback() {

@Override
public void onCalibrationProgress(final float progress) {
  runOnUiThread(new Runnable() {
    @Override
    public void run() {
      // process calibration point UI
    }
  });
}

@Override
public void onCalibrationNextPoint(final float x, final float y) {
  runOnUiThread(new Runnable() {
    @Override
    public void run() {
      // draw calibration point to (x,y)
    }
  });
  handler.postDelayed(new Runnable() {
    @Override
    public void run() {
      // After drawing the calibration point,
      // call startCollectSamples after enough time (1,000 ms in this example) that considering user can recognize the point
      gaze.startCollectSamples();
    }
  }, 1000);
}

@Override
public void onCalibrationFinished(double[] calibrationData) {
  // saveCalibration(calibrationData);
  runOnUiThread(
    new Runnable() {
      @Override
      public void run() {
        //remove calibration UI
      }
    });
  }
};

gazeTracker.setCalibrationCallback(calibrationCallback);

// Example of using overloaded functions
boolean startedResult = gazeTracker.startCabliration(CalibrationModeType.ONE_POINT, 100, 100, 1000, 1200);
boolean startedResult = gazeTracker.startCabliration(CalibrationModeType.ONE_POINT);
boolean startedResult = gazeTracker.startCabliration(100, 100, 1000, 1200);
boolean startedResult = gazeTracker.startCabliration();

stopCalibration

public void stopCalibration()

Stops the calibration process.

Example

if(tracker.isCalibrating()) {
  tracker.stopCalibration();
}

isCalibrating

public boolean isCalibrating()

Indicates whether the calibration process is currently active.

Return Type	Description
`boolean`	true if the calibration process is ongoing.

Example

System.out.println("Calibrating :" + tracker.isCalibrating);

startCollectSamples

public void startCollectSamples()

Notifies the GazeTracker that the UI has been updated with the coordinates provided by onCalibrationNextPoint and that the system is ready to start collecting user gaze data.

note

Ensure that this function is called after the UI has been updated and the user has had enough time to focus on the calibration point.

Example

//implement calibrationCallback
private CalibrationCallback calibrationCallback = new TimeoutCalibrationCallback() {

@Override
public void onCalibrationProgress(final float progress) {
  ...
}

@Override
public void onCalibrationNextPoint(final float x, final float y) {
  runOnUiThread(new Runnable() {
    @Override
    public void run() {
      // draw calibration point to (x,y)
    }
  });
  handler.postDelayed(new Runnable() {
    @Override
    public void run() {
      // After drawing the calibration point,
      // call startCollectSamples after enough time (1,000 ms in this example) that considering user can recognize the point
      gaze.startCollectSamples();
    }
  }, 1000);
}

@Override
public void onCalibrationFinished(double[] calibrationData) {
  ...
};

setCalibrationData

public void setCalibrationData(double[] calibrationData)

Applies previously stored calibration data to the current GazeTracker.

Parameters	Type	Description
calibrationData	`double[]`	An array of calibration values obtained after calibration is completed.

Example

//implement calibrationCallback
private CalibrationCallback calibrationCallback = new TimeoutCalibrationCallback() {

  @Override
  public void onCalibrationFinished(double[] calibrationData) {
    // After calibration is finished, the data is automatically reflected in the current gazeTracker instance.
    // You can save it and apply the saved value to the new gazeTracker instance when you restart the app later.
    savedCalibrationData = calibrationData;
  }
};

gazeTracker.setCalibrationData(savedCalibrationData);

setAttentionRegion

public void setAttentionRegion(float left, float top, float right, float bottom)

Sets the attention region using the specified coordinates.

Parameters	Type	Description
left	`float`	The left coordinate of the region.(px)
top	`float`	The top coordinate of the region.(px)
right	`float`	The right coordinate of the region.(px)
bottom	`float`	The bottom coordinate of the region.(px)

note

Device screen region is set as default.

Example

// Set attention region that (x,y) = (100,100), (width, height) = 100,100
setattentionRegion(100, 100, 200, 200);

getAttentionRegion

public RectF getAttentionRegion()

Retrieves the attention region.

Return Type	Description
`RectF`	`RectF` object representing the attention region in screen coordinates if the ROI (Region of Interest) is set, or `null` if the region is not set.

removeAttentionRegion

public void removeAttentionRegion()

Removes the currently set attention region.

Example

gazeTracker.removeAttentionRegion();

GazeTrackerOptions

public class GazeTrackerOptions {
  public final boolean useBlink;
  public final boolean useUserStatus;
  public final boolean useGazeFilter;
  public final int maxConcurrency;
  public final CameraPreset preset;
  public static class Builder {};
}

Class for configuring various options when creating a GazeTracker. This class allows users to specify settings such as blink detection, user status tracking, gaze filtering, and more. It uses the GazeTrackerOptions.Builder pattern to create an instance.

GazeTrackerOptions.Builder

public static class Builder

Builder class for creating an instance of GazeTrackerOptions. You can configure various options and then call build to generate an instance of GazeTrackerOptions.

Summary

Function	Description	Return Type
build	Builds the GazeTrackerOptions instance with the specified settings.	GazeTrackerOptions
setCameraPreset	Sets the camera resolution preset to be used for gaze tracking.	Builder
setMaxConcurrency	Sets the maximum number of concurrent threads allowed for processing.	Builder
setUseBlink	Sets whether to enable blink detection.	Builder
setUseUserStatus	Sets whether to enable user status tracking (e.g., focus, drowsiness).	Builder
setUseGazeFilter	Sets whether to apply a gaze filter to stabilize gaze tracking data.	Builder

build

public GazeTrackerOptions build()

Builds the GazeTrackerOptions instance with the specified settings.

note

Default Values in Builder:

useBlink : false
useUserStatus: false
useGazeFilter: true
maxConcurrency: 4

Return Type	Description
GazeTrackerOptions	A new GazeTrackerOptions instance.

Example

GazeTrackerOptions options = new GazeTrackerOptions.Builder().build();

setCameraPreset

public Builder setCameraPreset(CameraPreset preset)

Sets the camera resolution preset to be used for gaze tracking.

Parameters	Type	Description
preset	CameraPreset	The camera resolution preset to use.

Return Type	Description
Builder	The Builder instance for method chaining.

Example

GazeTrackerOptions options = new GazeTrackerOptions.Builder()
    .setCameraPreset(CameraPreset.HD1280X720)
    .build();

setMaxConcurrency

public Builder setMaxConcurrency(@IntRange(from = 0) int maxConcurrency)

Sets the maximum number of concurrent threads allowed for processing.

danger

IllegalArgumentException if maxConcurrency is less than 0.

Parameters	Type	Description
maxConcurrency	`int`	The maximum number of concurrent threads.

Return Type	Description
Builder	The Builder instance for method chaining.

example

GazeTrackerOptions options = new GazeTrackerOptions.Builder()
    .setMaxConcurrency(2)
    .build();

setUseBlink

public Builder setUseBlink(boolean useBlink)

Sets whether to enable blink detection.

Parameters	Type	Description
useBlink	`boolean`	true to enable blink detection, false to disable it.

Return Type	Description
Builder	The Builder instance for method chaining.

Example

GazeTrackerOptions options = new GazeTrackerOptions.Builder()
    .setUseBlink(true)
    .build();

setUseUserStatus

public Builder setUseUserStatus(boolean useUserStatus)

Sets whether to enable user status tracking (e.g., focus, drowsiness).

Parameters	Type	Description
useUserStatus	`boolean`	true to enable user status tracking, false to disable it.

Return Type	Description
Builder	The Builder instance for method chaining.

Example

GazeTrackerOptions options = new GazeTrackerOptions.Builder()
    .setUseBlink(true)
    .setUseUserStatus(true)
    .build();

setUseGazeFilter

public Builder setUseGazeFilter(boolean useGazeFilter)

Sets whether to apply a gaze filter to stabilize gaze tracking data.

Parameters	Type	Description
useGazeFilter	`boolean`	true to apply the gaze filter, false to disable it.

Return Type	Description
Builder	The Builder instance for method chaining.

Example

GazeTrackerOptions options = new GazeTrackerOptions.Builder()
    .setUseBlink(true)
    .setUseUserStatus(true)
    .setUseGazeFilter(false)
    .build();

CameraPosition

public class CameraPosition {
  public String modelName;
  public float screenWidth;
  public float screenHeight;
  public float screenOriginX;
  public float screenOriginY;
  public boolean cameraOnLongerAxis;
}

Class for managing the physical position information of the camera.

For more information, see gaze coordinate

Summary

Variables	type	description
modelName	`String`	The name of the device model.
screenWidth	`float`	The width of the screen (in pixels).
screenHeight	`float`	The height of the screen (in pixels).
screenOriginX	`float`	The distance between the center of the camera and the top-left corner of the screen along the x-axis (in mm). Positive values represent the right direction.
screenOriginY	`float`	The distance between the center of the camera and the top-left corner of the screen along the y-axis (in mm). Positive values represent the upward direction.
cameraOnLongerAxis	`boolean`	Boolean value indicating whether the camera is located along the longer axis of the device.

Constructor

public CameraPosition(String modelName, float screenWidth, float screenHeight, float screenOriginX, float screenOriginY)
public CameraPosition(String modelName, float screenWidth, float screenHeight, float screenOriginX, float screenOriginY, boolean cameraOnLongerAxis)

Constructor to initialize the camera position

Parameters	Type	Description
`modelName`	`String`	The name of the device model.
`screenWidth`	`float`	The width of the screen (in pixels).
`screenHeight`	`float`	The height of the screen (in pixels).
`screenOriginX`	`float`	The x-axis distance from the camera to the top-left corner of the screen (in mm).
`screenOriginY`	`float`	The y-axis distance from the camera to the top-left corner of the screen (in mm).
`cameraOnLongerAxis`	`boolean`	A boolean indicating if the camera is on the longer axis of the device.

Example

CameraPosition cameraPosition = new CameraPosition("SM-T720", 1600f, 2560f, -72f, -4f);// galaxy tab

GazeInfo

public class GazeInfo {
  public final float x, y;
  public final float fixationX, fixationY;
  public final TrackingState trackingState;
  public final EyeMovementState eyeMovementState;
  public final ScreenState screenState;
}

A class that contains information about gaze tracking.

Variables	type	description
x	`float`	The x-coordinate value of the gaze point. The origin is the device screen, and the unit is pixels (px).
y	`float`	The y-coordinate value of the gaze point. The origin is the device screen, and the unit is pixels (px).
fixationX	`float`	The x-coordinate value of the last fixation point. The origin is the device screen, and the unit is pixels (px).
fixationY	`float`	The y-coordinate value of the last fixation point. The origin is the device screen, and the unit is pixels (px).
trackingState	TrackingState	Enum indicating the tracking state of the camera image.
eyeMovementState	EyeMovementState	Enum indicating the type of eye movement.
screenState	ScreenState	Enum indicating whether the gaze has moved off the screen.

FaceInfo

public class FaceInfo {
  public final float score;
  public final Size frameSize;
  public final float left, top, right, bottom;
  public final float pitch, yaw, roll;
  public final float centerX, centerY, centerZ;
}

A class containing information about face tracking.

Variables	Type	Description
`score`	`float`	Confidence score for facial recognition, ranging from 0.0 to 1.0.
`frameSize`	`Size`	Size of the camera frame.
`left`	`float`	The position of the left side of the face within the image. The four sides (left, top, right, bottom) define the face's bounding box.
`top`	`float`	The position of the top side of the face within the image. The four sides (left, top, right, bottom) define the face's bounding box.
`right`	`float`	The position of the right side of the face within the image. The four sides (left, top, right, bottom) define the face's bounding box.
`bottom`	`float`	The position of the bottom side of the face within the image. The four sides (left, top, right, bottom) define the face's bounding box.
`pitch`	`float`	Pitch refers to the rotation of the face around the X-axis. It is also known as the attitude angle, often referred to as the nose-up or nose-down angle in aviation.
`yaw`	`float`	Yaw refers to the rotation of the face around the Y-axis. It is also known as the heading angle, often referred to as the bearing or compass angle in aviation.
`roll`	`float`	Roll refers to the rotation of the face around the Z-axis. It is also known as the bank angle, often referred to as the wing-up or wing-down angle in aviation.
`centerX`	`float`	The X-coordinate distance of the center of the face from the camera, in millimeters (mm).
`centerY`	`float`	The Y-coordinate distance of the center of the face from the camera, in millimeters (mm).
`centerZ`	`float`	The Z-coordinate distance of the center of the face from the camera, in millimeters (mm).

warning

When the camera is positioned at the top, we defined it as 0 degrees. (pitch, yaw, roll)

BlinkInfo

public class BlinkInfo {
  public final boolean isBlinkLeft;
  public final boolean isBlinkRight;
  public final boolean isBlink;
  public final float leftOpenness;
  public final float rightOpenness;
}

Represents information about eye blinking.

Variables	Type	Description
`isBlinkLeft`	`boolean`	Indicates if the left eye is blinking.
`isBlinkRight`	`boolean`	Indicates if the right eye is blinking.
`isBlink`	`boolean`	Indicates if both eyes are blinking.
`leftOpenness`	`float`	Open ratio of the left eye (0.0~1.0).
`rightOpenness`	`float`	Open ratio of the right eye (0.0~1.0).

UserStatusInfo

public class UserStatusInfo {
  public final boolean isDrowsy;
  public final float drowsinessIntensity;
  public final float attentionScore;
}

Represents information about user is status

Variables	Type	Description
`isDrowsy`	`boolean`	Flag indicating whether the user is drowsy.
`drowsinessIntensity`	`float`	Intensity level of drowsiness, ranging from 0.0 (not drowsy) to 1.0 (very drowsy).
`attentionScore`	`float`	Score indicating the user's attention rate, ranging from 0.0 to 1.0.

OneEuroFilterManager

public class OneEuroFilterManager

The OneEuroFilterManager class manages multiple One Euro Filters. This filter is used to reduce noise and smooth signals (e.g., gaze tracking data). Users can retrieve the filtered values and initialize filters with various settings through this class.

Constructor

public OneEuroFilterManager(int count)
public OneEuroFilterManager(int count, float freq)
public OneEuroFilterManager(int count, float freq, float minCutOff)
public OneEuroFilterManager(int count, float freq, float minCutOff, float beta)
public OneEuroFilterManager(int count, float freq, float minCutOff, float beta, float dCutOff)

Parameters	Type	Description
`count`	`int`	The number of filters to use.
`freq`	`float`	The frequency to be used by the filter (Hz).
`minCutOff`	`float`	The minimum cutoff frequency.
`beta`	`float`	The beta value (adjusts the response speed).
`dCutOff`	`float`	The derivative cutoff value.

Example

private OneEuroFilterManager oneEuroFilterManager = new OneEuroFilterManager(2);

Summary

Function	Description	Return Type
filterValues	Filters the given values.	`boolean`
getFilteredValues	Returns the filtered values.	`float[]`

filterValues

public boolean filterValues(long timestamp, float... val)

Filters the given values.

Parameters	Type	Description
timestamp	`long`	The current timestamp (ms).
val	`float`	The values to be filtered.

Return Type	Description
`boolean`	true if filtering was successful, false otherwise.

Example

// Attempt to filter the gaze coordinates using the OneEuroFilterManager
if (oneEuroFilterManager.filterValues(timestamp, gazeInfo.x, gazeInfo.y)) {
    // If successful, notify that the values have been filtered
    System.out.println("Successfully filtered values: (" + gazeInfo.x + ", " + gazeInfo.y + ")");
} else {
    // If unsuccessful, notify that the filtering has failed
    System.out.println("Failed to filter values.");
}

getFilteredValues

public float[] getFilteredValues()

Returns the filtered values.

Return Type	Description
`float[]`	An array of filtered values.

Example

if (oneEuroFilterManager.filterValues(timestamp, gazeInfo.x, gazeInfo.y)) {
  float[] filteredPoint = oneEuroFilterManager.getFilteredValues();
  System.out.println("Filtered values: x = " + filteredPoint[0] + ", y = " + filteredPoint[1]);
}

ViewLayoutChecker

public class ViewLayoutChecker

This class is used to calculate the view's offset depending on the ActionBar, StatusBar, and NavigationBar.

Summary

Function	Description	Return Type	Type
getLayoutLeftTop	Finds the left and top offset of the most recently obtained view.	`int[]`	static
releaseChecker	Remove the current view and interface reference	`void`	member
setOverlayView	Sets the overlay view to find the offset for overlay coordinates.	`void`	member

getLayoutLeftTop

public static int[] getLayoutLeftTop()

Finds the left and top offset of the most recently obtained view. In the overlay view, it's necessary to apply this offset to the gaze coordinates so that the gaze is displayed at the correct position on the screen.

Return Type	Description
`int[]`	an array containing the offset, where index 0 = left, and index 1 = top.

Example

int[] lt = ViewLayoutChecker.getLayoutLeftTop();

releaseChecker

public void releaseChecker()

Remove the current view and interface reference.

Example

ViewLayoutChecker viewLayoutChecker = new ViewLayoutChecker();
viewLayoutChecker.setOverlayView(overlayView, new ViewLayoutListener() {
      @Override
      public void getOffset(int x, int y) {
        calibrationViewer.setOffset(x, y);
        viewLayoutChecker.releaseChecker();
      }
});

setOverlayView

public void setOverlayView(@NonNull View overlayView, @Nullable ViewLayoutListener viewLayoutListener)

Sets the overlay view to find the offset for overlay coordinates.

Parameters	Type	Description
overlayView	`View`	The view that will be used to overlay coordinates.
viewLayoutListener	ViewLayoutChecker.ViewLayoutListener	(Optional) A listener to receive callbacks when the view layout changes.

Example

ViewLayoutChecker viewLayoutChecker = new ViewLayoutChecker();
viewLayoutChecker.setOverlayView(calibrationViewer, new ViewLayoutListener() {
      @Override
      public void getOffset(int x, int y) {
        overlayView.setLayoutLeftTop(x, y);
        faceRectView.setLayoutLeftTop(x,y);
        calibrationViewer.setOffset(x, y);
        viewLayoutChecker.releaseChecker();
      }
    });

ViewLayoutChecker.ViewLayoutListener

public interface ViewLayoutListener

Listener used in ViewLayoutChecker Calls ViewLayoutListener.getOffset(int, int) when the offset of the specified view is calculated.

Summary

function
getOffset

getOffset

void getOffset(int x, int y)

Called when the set view offset is obtained

Parameters	Type	Description
x	`int`	left offset
y	`int`	right offset

InitializationCallback

public interface InitializationCallback

Callback interface to notify the result of the GazeTracker initialization attempt.

Summary

function
onInitialized

onInitialized

public void onInitialized(GazeTracker tracker, InitializationErrorType error);

Called when the GazeTracker initialization is completed. If successful, a valid GazeTracker instance is provided. If failed, the GazeTracker will be null.

See Authentication for more details.

Parameters	Type	Description
tracker	GazeTracker	The GazeTracker instance if initialization was successful, otherwise null.
error	InitializationErrorType	The type of error if initialization failed,represented by InitializationErrorType.

Example

public void onInitialized(GazeTracker tracker, InitializationErrorType error){
  if (tracker != null) {
    this.tracker = tracker;
  } else {
    switch (error) {
      case InitializationErrorType.ERROR_NONE:
        break;
      case InitializationErrorType.ERROR_INIT:
        break;

      ...
    }
  }
}

TrackingCallback

public interface TrackingCallback

Summary

Function
onMetrics

onMetrics

void onMetrics(long timestamp, GazeInfo gazeInfo, FaceInfo faceInfo, BlinkInfo blinkInfo,UserStatusInfo userStatusInfo)

Parameters	Type	Description
timestamp	`long`	The timestamp of the frame
gazeInfo	GazeInfo	Information about the gaze, including coordinates and other related data.
faceInfo	FaceInfo	Information about the face, such as position, orientation, and bounding box.
blinkInfo	BlinkInfo	Information about eye blinking, including whether each eye is blinking and the openness ratio.
userStatusInfo	UserStatusInfo	Information about the user's status, such as drowsiness and attention levels.

Example

private TrackingCallback callback = new TrackingCallback() {
  @Override
  public void onMetrics(long timestamp, GazeInfo gazeInfo, FaceInfo faceInfo, BlinkInfo blinkInfo, UserStatusInfo userStatusInfo) {
      // do sometings
  }
};

gazeTracker.setTrackingCallback(callback);

StatusCallback

public interface StatusCallback

Interface callback to notify the status of the GazeTracker.

Summary

function
onStarted
onStopped

onStarted

public void onStarted()

if Called automatically after GazeTracker.startTracking() if initialization is successful. Calibration becomes available after this point.

Example

@Override
public void onStarted() {
  gazeTracker.startCalibration();
}

onStopped

public void onStopped(StatusErrorType error)

Called automatically when the GazeTracker stops.

Parameters	type	Description
error	StatusErrorType	The reason why the GazeTracker stopped.

Example

@Override
public void onStopped(StatusErrorType error) {
  if (error != StatusCallback.ERROR_NONE) {
    // onStopped with error
  } else {
    // onStopped without error
  }
}

CalibrationCallback

public interface CalibrationCallback

A callback class that provides the status of the calibration process.

Summary

Functions
onCalibrationNextPoint
onCalibrationProgress
onCalibrationFinished

onCalibrationNextPoint

public void onCalibrationNextPoint(float x, float y)

Provides calibration points information After receiving the coordinates, it displays them on the screen and waits for a certain period to allow the user to recognize the points. Then it proceeds by calling startCollectSamples().

Parameters	Type	Description
x	`float`	Calibration point x. The unit is pixel(`px`)
y	`float`	Calibration point y. The unit is pixel(`px`)

Example

@Override
public void onCalibrationNextPoint(float x, float y) {
  // Draw Calibration Point(x,y) in view.

  // than call startCollectSamples to proceed calibration.
  gazeTracker.startCollectSamples();
}

onCalibrationProgress

public void onCalibrationProgress(float progress)

Provides calibration progress

The value increases when startCollectSamples function is called.

Parameters	Type	Description
progress	`float`	Calibration progress for each point

note

Visualizing the calibration progression with proper UI is recommended to improve UX.

onCalibrationFinished

public void onCalibrationFinished(double[] calibrationData)

Called when calibration is finished

tip

Not re-calibrating when restarting the app, by passing the stored data via GazeTracker.setCalibrationData.

Parameters	Type	Description
calibrationData	`double[]`	Calibration data

Example

public void onCalibrationFinished(double[] calibrationData) {
  // remove calibration UI, save calibration data
  removeCalibrationUI();
  saveCalibrationDataForLaterUse(calibrationData);
}

ImageCallback

public interface ImageCallback

Callback interface for receiving images from the front camera.

Summary

Functions
onImage

onImage

public void onImage(long timestamp, byte[] image)

Called when a new image frame is captured by the front camera.

Parameters	Type	Description
timestamp	`long`	The timestamp when the camera frame was captured. (UTC, miliseconds)
image	`byte[]`	The byte array representing the captured camera frame. format is YUV(NV21)

Example

@Override
public void onImage(long timestamp, byte[] image){
  try {
    File file = new File(yourJpgFilePath);
    FileOutputStream out = new FileOutputStream(file);

    int width = 640;
    int height = 480;

    YuvImage yuvImage = new YuvImage(image, ImageFormat.NV21, width, height, null);
    yuvImage.compressToJpeg(new Rect(0, 0, width, height), 50, out);
    out.flush();
    out.close();
  } catch (IOException e) {
    e.printStackTrace();
  }
}

CalibrationModeType

public enum CalibrationModeType

Enum representing the calibration mode types for starting calibration. Currently, available modes are DEFAULT, ONE_POINT, and FIVE_POINT. DEFAULT is set to the recommended mode, which is currently the five-point calibration mode.

Name	Description
`DEFAULT`	Default calibration mode, which is set to the recommended mode. In the current version, this is the five-point calibration mode.
`ONE_POINT`	One-point calibration mode
`FIVE_POINT`	Five-point calibration mode

AccuracyCriteria

public enum AccuracyCriteria

Enum representing the accuracy criteria for starting calibration.

Currently, only the DEFAULT option is available. Future versions may include additional criteria such as LOW and HIGH accuracy options, but this is not guaranteed.

Name	Description
`DEFAULT`	Default calibration accuracy criteria.

CameraPreset

public enum CameraPreset

Enum representing the available camera resolution presets.

Allows the user to select a specific camera resolution.

Name	Description
`VGA640X480`	640x480 resolution (VGA).
`HD1280X720`	1280x720 resolution (HD).
`FHD1920X1080`	1920x1080 resolution (Full HD).

InitializationErrorType

public enum InitializationErrorType

Enum representing the different types of initialization errors that can occur during the setup of the Gaze Tracker system.

See Authentication for more details.

TrackingState

public enum TrackingState

Enum representing the state of gaze tracking

Name	Description
`SUCCESS`	Gaze tracking is successful, and both gaze and face are detected.
`GAZE_MISSING`	The gaze is not detected, but the face is still tracked.
`FACE_MISSING`	The face is not detected, which means gaze tracking is not possible.

EyeMovementState

public enum EyeMovementState

Enum representing the state of eye movement.

Name	Description
`FIXATION`	The eye is fixated on a specific point.
`SACCADE`	The eye is moving rapidly between points (saccadic movement).
`UNKNOWN`	The eye movement state is unknown or cannot be determined.

ScreenState

public enum ScreenState

Enum representing the state of whether the gaze is inside or outside of the screen.

Name	Description
`INSIDE_OF_SCREEN`	The gaze is within the bounds of the screen.
`OUTSIDE_OF_SCREEN`	The gaze is outside the bounds of the screen.
`UNKNOWN`	The gaze state is unknown or cannot be determined.

StatusErrorType

public enum StatusErrorType

Enum that describes the reason why gaze tracking stopped.

Name	Description
`ERROR_NONE`	No error occurred, and gaze tracking stopped due to a stopTracking call.
`ERROR_CAMERA_START`	Gaze tracking stopped because an error occurred when trying to start the camera.
`ERROR_CAMERA_INTERRUPT`	Gaze tracking stopped because the camera was interrupted.

Overview​

GazeTracker​

Summary​

initGazeTracker​

Example​

releaseGazeTracker​

Example​

getVersionName​

Example​

startTracking​

Example​

stopTracking​

Example​

isTracking​

Example​

hasCameraPosition​

Example​

addCameraPosition​

Example​

getCameraPosition​

Example​

getCameraPositionList​

Example​

selectCameraPosition​

Example​

setTrackingCallback​

Example​

removeTrackingCallback​

Example​

setStatusCallback​

Example​

removeStatusCallback​

Example​

setCalibrationCallback​

Example​

removeCalibrationCallback​

Example​

setImageCallback​

Example​

removeImageCallback​

Example​

setCallbacks​

Example​

removeCallbacks​

Example​

setTrackingFPS​

Example​

setCameraPreview​

Example​

removeCameraPreview​

Example​

startCalibration​

Example​

stopCalibration​

Example​

isCalibrating​

Example​

startCollectSamples​

Example​

setCalibrationData​

Example​

setAttentionRegion​

Example​

getAttentionRegion​

removeAttentionRegion​

Example​

GazeTrackerOptions​

GazeTrackerOptions.Builder​

Summary​

build​

Example​

setCameraPreset​

Example​

setMaxConcurrency​

example​

setUseBlink​

Example​

setUseUserStatus​

Example​

setUseGazeFilter​

Overview

GazeTracker

Summary

initGazeTracker

Example

releaseGazeTracker

Example

getVersionName

Example

startTracking

Example

stopTracking

Example

isTracking

Example

hasCameraPosition

Example

addCameraPosition

Example

getCameraPosition

Example

getCameraPositionList

Example

selectCameraPosition

Example

setTrackingCallback

Example

removeTrackingCallback

Example

setStatusCallback

Example

removeStatusCallback

Example

setCalibrationCallback

Example

removeCalibrationCallback

Example

setImageCallback

Example

removeImageCallback

Example

setCallbacks

Example

removeCallbacks

Example

setTrackingFPS

Example

setCameraPreview

Example

removeCameraPreview

Example

startCalibration

Example

stopCalibration

Example

isCalibrating

Example

startCollectSamples

Example

setCalibrationData

Example

setAttentionRegion

Example

getAttentionRegion

removeAttentionRegion

Example

GazeTrackerOptions

GazeTrackerOptions.Builder

Summary

build

Example

setCameraPreset

Example

setMaxConcurrency

example

setUseBlink

Example

setUseUserStatus

Example

setUseGazeFilter