Skip to main content
Version: Eyedid Beta

API Docs (Java)

Overview

NametypeDescription
GazeTrackerclassThe main class that captures the user's face through the device's camera, processes it, and provides gaze data.
GazeTrackerOptionsclassClass for configuring various options when creating a GazeTracker.
GazeTrackerOptions.builderclassBuilder class for creating an instance of GazeTrackerOptions.
CameraPositionclassClass for managing the physical position information of the camera.
GazeInfoclassA class that contains information about gaze tracking.
FaceInfoclassA class containing information about face tracking.
BlinkInfoclassRepresents information about eye blinking.
UserStatusInfoclassRepresents information about user is status
OneEuroFilterManagerclassThe OneEuroFilterManager class manages multiple One Euro Filters.
ViewLayoutCheckerclassThis class is used to calculate the view's offset depending on the ActionBar, StatusBar, and NavigationBar.
InitializationCallbackinterfaceCallback interface to notify the result of the GazeTracker initialization attempt.
TrackingCallbackinterfaceProvides all the metrics tracked by GazeTracker for each camera frame.
StatusCallbackinterfaceInterface callback to notify the status of the GazeTracker.
CalibrationCallbackinterfaceA callback class that provides the status of the calibration process.
ImageCallbackinterfaceCallback interface for receiving images from the front camera.
CameraPresetenumEnum representing the available camera resolution presets.
InitializationErrorTypeenumEnum representing the different types of initialization errors that can occur during the setup of the Gaze Tracker system.
CalibrationModeTypeenumEnum representing the calibration mode types for starting calibration.
AccuracyCriteriaenumEnum representing the accuracy criteria for starting calibration.
TrackingStateenumEnum representing the state of gaze tracking.
EyeMovementStateenumEnum representing the state of eye movement.
ScreenStateenumEnum representing the state of whether the gaze is inside or outside of the screen.
StatusErrorTypeenumEnum 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

FunctionDescriptionReturn TypeType
initGazeTrackerInitializes the GazeTracker.voidStatic
releaseGazeTrackerRelease the GazeTracker.voidStatic
getVersionNameRetrieves the version name.StringStatic
startTrackingStarts the tracking process.voidMember
stopTrackingStops the tracking process.voidMember
isTrackingChecks if tracking is active.booleanMember
hasCameraPositionsChecks if a Checks whether CameraPosition information is available.booleanMember
addCameraPositionAdds a camera position.voidMember
getCameraPositionRetrieves the current camera position.CameraPositionMember
getCameraPositionListRetrieves the list of camera positions.ArrayList<CameraPosition>Member
selectCameraPositionSelects a specific camera position.voidMember
setTrackingCallbackSets the TrackingCallbackvoidMember
removeTrackingCallbackRemoves the TrackingCallbackvoidMember
setStatusCallbackSets the StatusCallback.voidMember
removeStatusCallbackRemoves the StatusCallback.voidMember
setCalibrationCallbackSets the CalibrationCallback.voidMember
removeCalibrationCallbackRemoves the CalibrationCallback.voidMember
setImageCallbackSets the ImageCallback.voidMember
removeImageCallbackRemoves the ImageCallback.voidMember
setCallbacksRegisters multiple callbacks at once.voidMember
removeCallbacksRemoves all currently set callbacksvoidMember
setTrackingFPSSets the tracking FPS.booleanMember
setCameraPreviewSets the camera preview.voidMember
removeCameraPreviewRemoves the camera preview.voidMember
startCalibrationStarts the calibration process.booleanMember
stopCalibrationStops the calibration process.voidMember
isCalibratingChecks if calibration is in progress.booleanMember
startCollectSamplesStarts collecting calibration samples.voidMember
setCalibrationDataSets the calibration data.voidMember
setAttentionRegionSets the attention region.voidMember
getAttentionRegionRetrieves the attention region.RectFMember
removeAttentionRegionRemoves the attention region.voidMember

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.

ParametersTypeDescription
contextandroid.content.ContextThe context in which the GazeTracker will be used.
licenseKeyStringThe license key required to activate the GazeTracker.
callbackInitializationCallbackThe callback to receive initialization status.
optionsGazeTrackerOptionsOptional 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.

ParametersTypeDescription
gazeTrackerGazeTrackerThe 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.

Return TypeDescription
stringEyedid 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 TypeDescription
booleantrue 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 TypeDescription
booleantrue 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.

ParametersTypeDescription
cameraPositionCameraPositionThe 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 TypeDescription
CameraPositionnull 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 TypeDescription
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.

ParametersTypeDescription
idxIntThe 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.

ParametersTypeDescription
callbackTrackingCallbackAn 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.

ParametersTypeDescription
callbackStatusCallbackAn 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.

ParametersTypeDescription
callbackCalibrationCallbackAn 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.

ParametersTypeDescription
callbackImageCallbackAn 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.

ParametersTypeDescription
callbackObjectVarargs 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.

ParametersTypeDescription
fpsintThe desired frames per second for gaze tracking.
Return TypeDescription
booleantrue 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.

ParametersTypeDescription
cameraPreviewandroid.view.TextureViewThe 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.

ParametersTypeDescription
modeCalibrationModeTypeThe number of points to be used for calibration.
criteriaAccuracyCriteriaThe accuracy criteria to be used for calibration.
leftfloatThe left coordinate of the calibration region.
topfloatThe top coordinate of the calibration region.
rightfloatThe right coordinate of the calibration region.
bottomfloatThe bottom coordinate of the calibration region.
Return TypeDescription
booleantrue 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 TypeDescription
booleantrue 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.

ParametersTypeDescription
calibrationDatadouble[]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.

ParametersTypeDescription
leftfloatThe left coordinate of the region.(px)
topfloatThe top coordinate of the region.(px)
rightfloatThe right coordinate of the region.(px)
bottomfloatThe 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
tracker.setAttentionRegion(100, 100, 200, 200);

getAttentionRegion

public RectF getAttentionRegion()

Retrieves the attention region.

Return TypeDescription
RectFRectF 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

FunctionDescriptionReturn Type
buildBuilds the GazeTrackerOptions instance with the specified settings.GazeTrackerOptions
setCameraPresetSets the camera resolution preset to be used for gaze tracking.Builder
setMaxConcurrencySets the maximum number of concurrent threads allowed for processing.Builder
setUseBlinkSets whether to enable blink detection.Builder
setUseUserStatusSets whether to enable user status tracking (e.g., focus, drowsiness).Builder
setUseGazeFilterSets 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 TypeDescription
GazeTrackerOptionsA 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.

ParametersTypeDescription
presetCameraPresetThe camera resolution preset to use.
Return TypeDescription
BuilderThe 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.

ParametersTypeDescription
maxConcurrencyintThe maximum number of concurrent threads.
Return TypeDescription
BuilderThe Builder instance for method chaining.

example

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

public Builder setUseBlink(boolean useBlink)

Sets whether to enable blink detection.

ParametersTypeDescription
useBlinkbooleantrue to enable blink detection, false to disable it.
Return TypeDescription
BuilderThe 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).

ParametersTypeDescription
useUserStatusbooleantrue to enable user status tracking, false to disable it.
Return TypeDescription
BuilderThe 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.

ParametersTypeDescription
useGazeFilterbooleantrue to apply the gaze filter, false to disable it.
Return TypeDescription
BuilderThe 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

Variablestypedescription
modelNameStringThe name of the device model.
screenWidthfloatThe width of the screen (in pixels).
screenHeightfloatThe height of the screen (in pixels).
screenOriginXfloatThe 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.
screenOriginYfloatThe 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.
cameraOnLongerAxisbooleanBoolean 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

ParametersTypeDescription
modelNameStringThe name of the device model.
screenWidthfloatThe width of the screen (in pixels).
screenHeightfloatThe height of the screen (in pixels).
screenOriginXfloatThe x-axis distance from the camera to the top-left corner of the screen (in mm).
screenOriginYfloatThe y-axis distance from the camera to the top-left corner of the screen (in mm).
cameraOnLongerAxisbooleanA 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.

Variablestypedescription
xfloatThe x-coordinate value of the gaze point. The origin is the device screen, and the unit is pixels (px).
yfloatThe y-coordinate value of the gaze point. The origin is the device screen, and the unit is pixels (px).
fixationXfloatThe x-coordinate value of the last fixation point. The origin is the device screen, and the unit is pixels (px).
fixationYfloatThe y-coordinate value of the last fixation point. The origin is the device screen, and the unit is pixels (px).
trackingStateTrackingStateEnum indicating the tracking state of the camera image.
eyeMovementStateEyeMovementStateEnum indicating the type of eye movement.
screenStateScreenStateEnum 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.

VariablesTypeDescription
scorefloatConfidence score for facial recognition, ranging from 0.0 to 1.0.
frameSizeSizeSize of the camera frame.
leftfloatThe position of the left side of the face within the image, expressed as a relative value between 0 and 1. The four sides (left, top, right, bottom) define the face’s bounding box.
topfloatThe position of the top side of the face within the image, expressed as a relative value between 0 and 1. The four sides (left, top, right, bottom) define the face’s bounding box.
rightfloatThe position of the right side of the face within the image, expressed as a relative value between 0 and 1. The four sides (left, top, right, bottom) define the face’s bounding box.
bottomfloatThe position of the bottom side of the face within the image, expressed as a relative value between 0 and 1. The four sides (left, top, right, bottom) define the face’s bounding box.
pitchfloatPitch 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.
yawfloatYaw 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.
rollfloatRoll 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.
centerXfloatThe X-coordinate distance of the center of the face from the camera, in millimeters (mm).
centerYfloatThe Y-coordinate distance of the center of the face from the camera, in millimeters (mm).
centerZfloatThe 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.

VariablesTypeDescription
isBlinkLeftbooleanIndicates if the left eye is blinking.
isBlinkRightbooleanIndicates if the right eye is blinking.
isBlinkbooleanIndicates if both eyes are blinking.
leftOpennessfloatOpen ratio of the left eye (0.0~1.0).
rightOpennessfloatOpen 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

VariablesTypeDescription
isDrowsybooleanFlag indicating whether the user is drowsy.
drowsinessIntensityfloatIntensity level of drowsiness, ranging from 0.0 (not drowsy) to 1.0 (very drowsy).
attentionScorefloatScore 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)
ParametersTypeDescription
countintThe number of filters to use.
freqfloatThe frequency to be used by the filter (Hz).
minCutOfffloatThe minimum cutoff frequency.
betafloatThe beta value (adjusts the response speed).
dCutOfffloatThe derivative cutoff value.

Example

private OneEuroFilterManager oneEuroFilterManager = new OneEuroFilterManager(2);

Summary

FunctionDescriptionReturn Type
filterValuesFilters the given values.boolean
getFilteredValuesReturns the filtered values.float[]

filterValues

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

Filters the given values.

ParametersTypeDescription
timestamplongThe current timestamp (ms).
valfloatThe values to be filtered.
Return TypeDescription
booleantrue 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 TypeDescription
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

FunctionDescriptionReturn TypeType
getLayoutLeftTopFinds the left and top offset of the most recently obtained view.int[]static
releaseCheckerRemove the current view and interface referencevoidmember
setOverlayViewSets the overlay view to find the offset for overlay coordinates.voidmember

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 TypeDescription
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.

ParametersTypeDescription
overlayViewViewThe view that will be used to overlay coordinates.
viewLayoutListenerViewLayoutChecker.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

ParametersTypeDescription
xintleft offset
yintright 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.

ParametersTypeDescription
trackerGazeTrackerThe GazeTracker instance if initialization was successful, otherwise null.
errorInitializationErrorTypeThe 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)
ParametersTypeDescription
timestamplongThe timestamp of the frame
gazeInfoGazeInfoInformation about the gaze, including coordinates and other related data.
faceInfoFaceInfoInformation about the face, such as position, orientation, and bounding box.
blinkInfoBlinkInfoInformation about eye blinking, including whether each eye is blinking and the openness ratio.
userStatusInfoUserStatusInfoInformation 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.

ParameterstypeDescription
errorStatusErrorTypeThe 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().

ParametersTypeDescription
xfloatCalibration point x. The unit is pixel(px)
yfloatCalibration 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.

ParametersTypeDescription
progressfloatCalibration 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.

ParametersTypeDescription
calibrationDatadouble[]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.

ParametersTypeDescription
timestamplongThe timestamp when the camera frame was captured. (UTC, miliseconds)
imagebyte[]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.

NameDescription
DEFAULTDefault calibration mode, which is set to the recommended mode. In the current version, this is the five-point calibration mode.
ONE_POINTOne-point calibration mode
FIVE_POINTFive-point calibration mode

AccuracyCriteria

public enum AccuracyCriteria

Enum representing the accuracy criteria for starting calibration.

NameDescription
DEFAULTDefault calibration accuracy criteria.
LOWLow calibration accuracy criteria.
HIGHHigh calibration accuracy criteria.

CameraPreset

public enum CameraPreset

Enum representing the available camera resolution presets.

Allows the user to select a specific camera resolution.

NameDescription
VGA640X480640x480 resolution (VGA).
HD1280X7201280x720 resolution (HD).
FHD1920X10801920x1080 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

NameDescription
SUCCESSGaze tracking is successful, and both gaze and face are detected.
GAZE_MISSINGThe gaze is not detected, but the face is still tracked.
FACE_MISSINGThe face is not detected, which means gaze tracking is not possible.

EyeMovementState

public enum EyeMovementState

Enum representing the state of eye movement.

NameDescription
FIXATIONThe eye is fixated on a specific point.
SACCADEThe eye is moving rapidly between points (saccadic movement).
UNKNOWNThe 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.

NameDescription
INSIDE_OF_SCREENThe gaze is within the bounds of the screen.
OUTSIDE_OF_SCREENThe gaze is outside the bounds of the screen.
UNKNOWNThe gaze state is unknown or cannot be determined.

StatusErrorType

public enum StatusErrorType

Enum that describes the reason why gaze tracking stopped.

NameDescription
ERROR_NONENo error occurred, and gaze tracking stopped due to a stopTracking call.
ERROR_CAMERA_STARTGaze tracking stopped because an error occurred when trying to start the camera.
ERROR_CAMERA_INTERRUPTGaze tracking stopped because the camera was interrupted.