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. |
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. |
CalibrationModeType | enum | Enum representing the calibration mode types for starting calibration. |
AccuracyCriteria | enum | Enum representing the accuracy criteria for starting calibration. |
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.
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.
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.
Return Type | Description |
---|---|
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.
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.
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.
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.
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) |
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 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.
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.
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, expressed as a relative value between 0 and 1. 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, expressed as a relative value between 0 and 1. 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, expressed as a relative value between 0 and 1. 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, expressed as a relative value between 0 and 1. 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). |
- 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 |
Visualizing the calibration progression with proper UI is recommended to improve UX.
onCalibrationFinished
public void onCalibrationFinished(double[] calibrationData)
Called when calibration is finished
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.
Name | Description |
---|---|
DEFAULT | Default calibration accuracy criteria. |
LOW | Low calibration accuracy criteria. |
HIGH | High 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. |