+
+ +
+
+
+

API reference

+
+

C++

+
+
+class eyeware::TrackerClient
+

Class for connecting to the tracker server and retrieving its resulting tracking data.

+

It establishes communication to the tracker server (Eyeware Beam application) and provides synchronous access to the data. Those synchronous calls will return the last tracking data results received from the server.

+

A network_error_handler callback can be provided. If nullptr is used (default), the network errors are ignored and the network connection is reestablished automatically when possible by the TrackerClient class instance. If a network handler is given, it will be called in case of errors (e.g., timeout). In such case, the TrackerClient instance becomes invalid and needs to be recreated to reestablish connection.

+
+

Public Functions

+
+
+TrackerClient(std::function<void(const NetworkError&)> network_error_handler = nullptr, int network_connection_timeout_ms = DEFAULT_NETWORK_TIMEOUTS_IN_MS, int tracking_info_network_timeout_ms = DEFAULT_NETWORK_TIMEOUTS_IN_MS, int base_communication_port = DEFAULT_BASE_COMMUNICATION_PORT, const char *hostname = "127.0.0.1")
+
+
Parameters
+
    +

  • network_error_handler – An optional callback function for managing connection to the server errors.

    • +

  • network_connection_timeout_ms – The time period (in ms) for an attempt to connect to the server, after which the network connection is treated as broken.

    • +

  • tracking_info_network_timeout_ms – The time period (in ms) for an attempt to obtain tracking info from the server, after which the network connection is treated as broken.

    • +

  • base_communication_port – Base connection port to the server. The instance may use base_communication_port+1 as well.

    • +

  • hostname – The hostname of the server to obtain tracking results from. Typically the same PC, thus “127.0.0.1”.

    • +
+
+
+
+ +
+
+ScreenGazeInfo get_screen_gaze_info() const
+

Retrieves the most recent screen gaze tracking result.

+
+ +
+
+HeadPoseInfo get_head_pose_info() const
+

Retrieves the most recent head pose tracking result.

+
+ +
+
+bool connected() const
+

Whether this client is currently connected to the tracker server or not.

+

+
Since

1.1.0

+
+
+

+
+ +
+
+ +
+
+struct eyeware::HeadPoseInfo
+

Represents information of the head pose, for a given time instant.

+
+

Public Members

+
+
+AffineTransform3D transform
+

Head pose, defined at the nose tip, with respect to the World Coordinate System (WCS).

+
+ +
+
+bool is_lost = true
+

Indicates if tracking of the head is lost, i.e., if false, the user is not being tracked.

+
+ +
+
+uint64_t track_session_uid = 0
+

Indicates the ID of the session of uninterrupted consecutive tracking.

+
+ +
+
+ +
+
+struct eyeware::ScreenGazeInfo
+

Represents information of a person gaze intersection with a single screen, for a given time instant. Screen gaze coordinates are expressed in pixels with respect to the top-left corner of the screen.

+
+

Public Members

+
+
+uint32_t screen_id = 0
+

ID of the screen, to differentiate in case of a multiscreen setup.

+
+ +
+
+uint32_t x = 0
+

The horizontal screen coordinate for the gaze intersection.

+
+ +
+
+uint32_t y = 0
+

The vertical screen coordinate for the gaze intersection.

+
+ +
+
+TrackingConfidence confidence = TrackingConfidence::UNRELIABLE
+

The confidence of the tracking result.

+
+ +
+
+bool is_lost = true
+

Tracking status that tells if the other values are dependable.

+
+ +
+
+ +
+
+enum eyeware::TrackingConfidence
+

Realibility measure for obtained tracking results.

+

Values:

+
+
+enumerator UNRELIABLE
+
+ +
+
+enumerator LOW
+
+ +
+
+enumerator MEDIUM
+
+ +
+
+enumerator HIGH
+
+ +
+ +
+
+struct eyeware::AffineTransform3D
+

Representation of a 3D affine transform, composed by a rotation matrix and a translation vector as A = [R | t], where

+

R = [c_00, c_01, c_02 c_10, c_11, c_12 c_20, c_21, c_22],

+

t = [c_03, c_13, c_23].

+
+

Public Members

+
+
+Matrix3x3 rotation
+

Rotation matrix component.

+
+ +
+
+Vector3D translation
+

Translation vector component.

+
+ +
+
+ +
+
+using eyeware::Matrix3x3 = float[3][3]
+

Matrix of 3x3, implemented as an array of arrays (row-major).

+

Matrix3x3 my_matrix; // Assume a Matrix3x3 instance is available
+int row = 1;
+int col = 2;
+float coefficient = my_matrix[row][col];
+
+
+

+
+ +
+
+struct eyeware::Vector3D
+

Representation of a 3D vector or 3D point.

+
+

Public Members

+
+
+float x = 0.0f
+

x coordinate.

+
+ +
+
+float y = 0.0f
+

y coordinate.

+
+ +
+
+float z = 0.0f
+

z coordinate.

+
+ +
+
+ +
+
+

Python

+
+
+class eyeware.client.TrackerClient
+

Class for connecting to the tracker server and retrieving its resulting tracking data.

+

It establishes communication to the tracker server (Eyeware Beam application) and provides synchronous access to the data. +Those synchronous calls will return the last tracking data results received from the server.

+

A network_error_handler callback can be provided. +If None is used (default), the network errors are ignored and the network connection is reestablished automatically when possible by the TrackerClient class instance. +If a network handler is given, it will be called in case of errors (e.g., timeout). +In such case, the TrackerClient instance becomes invalid and needs to be recreated to reestablish connection.

+
+
Parameters
+
    +

  • network_error_handler (Callable) – An optional callback function for managing connection to the server errors.

    • +

  • network_connection_timeout_ms (int) – The time period (in ms) for an attempt to connect to the server, after which the network connection is treated as broken.

    • +

  • tracking_info_network_timeout_ms (int) – The time period (in ms) for an attempt to obtain tracking info from the server, after which the network connection is treated as broken.

    • +

  • base_communication_port (int) – Base connection port to the server. The instance may use base_communication_port+1 as well.

    • +

  • hostname (str) – The hostname of the server to obtain tracking results from. Typically the same PC, thus “127.0.0.1”.

    • +
+
+
+
+
+property connected
+

Whether this client is currently connected to the tracker server or not.

+
+

New in version 1.1.0.

+
+
+ +
+
+get_head_pose_info(self: eyeware.client.TrackerClient) → eyeware::HeadPoseInfo
+

Retrieves the most recent head pose tracking result.

+
+ +
+
+get_screen_gaze_info(self: eyeware.client.TrackerClient) → eyeware::ScreenGazeInfo
+

Retrieves the most recent screen gaze tracking result.

+
+ +
+ +
+
+class eyeware.client.HeadPoseInfo
+

Represents information of the head pose, for a given time instant.

+
+
+property is_lost
+

Indicates if tracking of the head is lost, i.e., if False, the user is not being tracked.

+
+ +
+
+property track_session_uid
+

Indicates the ID of the session of uninterrupted consecutive tracking.

+
+ +
+
+property transform
+

Head pose, defined at the nose tip, with respect to the World Coordinate System (WCS).

+
+ +
+ +
+
+class eyeware.client.ScreenGazeInfo
+

Represents information of a person gaze intersection with a single screen, for a given time instant. +Screen gaze coordinates are expressed in pixels with respect to the top-left corner of the screen.

+
+
+property confidence
+

The confidence of the tracking result.

+
+ +
+
+property is_lost
+

Tracking status that tells if the other values are dependable.

+
+ +
+
+property screen_id
+

ID of the screen, to differentiate in case of a multiscreen setup.

+
+ +
+
+property x
+

The horizontal screen coordinate for the gaze intersection.

+
+ +
+
+property y
+

The vertical screen coordinate for the gaze intersection.

+
+ +
+ +
+
+class eyeware.client.TrackingConfidence
+
+

Realibility measure for obtained tracking results.

+
+

Members:

+
+

UNRELIABLE

+

LOW

+

MEDIUM

+

HIGH

+
+
+ +
+
+class eyeware.client.AffineTransform3D
+

Representation of a 3D affine transform, composed by a rotation matrix and a translation vector as A = [R | t], where

+

R = [c_00, c_01, c_02 c_10, c_11, c_12 c_20, c_21, c_22],

+

t = [c_03, c_13, c_23].

+
+
+property rotation
+

Rotation matrix component.

+
+ +
+
+property translation
+

Translation vector component.

+
+ +
+ +
+
+class eyeware.client.Vector3D
+

Representation of a 3D vector or 3D point.

+
+
+property x
+

x coordinate.

+
+ +
+
+property y
+

y coordinate.

+
+ +
+
+property z
+

z coordinate.

+
+ +
+ +
+

Note

+

Matrix and vector types, such as the rotation and translation properties of AffineTransform3D, can be transformed to NumPy arrays efficiently. +This is useful for using tracking data and coordinates in your application. +Example:

+
# Receive an AffineTransform3D instance
+head_pose = tracker.get_head_pose_info()
+# Transform the tracking information to standard NumPy arrays
+import numpy as np
+rotation_numpy = np.array(head_pose.rotation, copy=False)
+translation_numpy = np.array(head_pose.translation, copy=False)
+# Now we can manipulate tracking information to do several things:
+# draw tracking coordinates on the screen, save them for statistics/heatmaps,
+# perform arithmetic operations on them, trigger interactive behaviors based on thresholds, etc.
+
+
+
+
+
+ + +
+ +