Python¶

The Python API is provided through the eyeware.beam_eye_tracker module, which is a wrapper around the C++ API. It provides the same functionality with a Pythonic interface. All methods and types correspond directly to their C++ counterparts, but follow Python naming conventions.

Core Classes¶

API¶

class eyeware.beam_eye_tracker.API¶

Bases: pybind11_object

Main entry point for the Beam Eye Tracker SDK.

Note

See The API singleton for a high-level explanation of the API object.

Parameters¶

friendly_namestr: Application identifier displayed in the Beam Eye Tracker UI (UTF-8, max 200 bytes)
initial_viewport_geometryViewportGeometry: Initial screen viewport configuration for coordinate mapping

Raises¶

RuntimeError: If API initialization fails
ValueError: If friendly_name is invalid or exceeds size limit

See Also¶

TrackingListener : For asynchronous data reception

attempt_starting_the_beam_eye_tracker(self: eyeware.beam_eye_tracker.API) → None¶: Attempts to start the Beam Eye Tracker application and tracking output.

Note

See Launching the Beam Eye Tracker from your game or application for more information.

static compute_sim_game_camera_transform_parameters(state: eyeware.beam_eye_tracker.SimGameCameraState, eye_tracking_weight: float = 1.0, head_tracking_weight: float = 1.0) → eyeware.beam_eye_tracker.SimCameraTransform3D¶

Computes the transform you should apply to the in-game camera.

Parameters¶

stateSimGameCameraState: The current state of the in-game camera
eye_tracking_weightfloat, optional: The weight of the eye tracking component (default is 1.0)
head_tracking_weightfloat, optional: The weight of the head tracking component (default is 1.0)

Returns¶

SimCameraTransform3D: The transform parameters to apply to the in-game camera

Notes¶

Use the weight parameters to control the contributions of the eye and head tracking data. A weight of 1.0 (for both) is the default, which would apply the camera movement as configured by the user within the Beam Eye Tracker.

The weight values affect how much the eye/head tracking influences camera movement. A weight of 2.0 will make the camera move twice as much for the same head/eye movement, while 0.5 will make it move half as much.

Note

See Sensitivity/Range Sliders for more information.

get_latest_tracking_state_set(self: eyeware.beam_eye_tracker.API) → eyeware.beam_eye_tracker.TrackingStateSet¶

Returns the latest tracking state set.

Returns¶

TrackingStateSet: The latest tracking state set

Note

See The TrackingStateSet object for more information.

get_tracking_data_reception_status(self: eyeware.beam_eye_tracker.API) → eyeware.beam_eye_tracker.TrackingDataReceptionStatus¶

Returns the current status of the tracking data reception.

Returns¶

TrackingDataReceptionStatus: The current status of the tracking data reception

Note

See The TrackingDataReceptionStatus object for more information.

get_version(self: eyeware.beam_eye_tracker.API) → eyeware.beam_eye_tracker.Version¶

Get the current SDK version information.

Returns¶

Version: Structure containing major, minor, patch and build numbers

Example¶

>>> ver = api.get_version()
>>> print(f"SDK Version: {ver.major}.{ver.minor}.{ver.patch}.{ver.build}")

recenter_sim_game_camera_end(self: eyeware.beam_eye_tracker.API) → None¶: End recentering the sim game camera.

Note

See Implement the camera recentering for more information.

recenter_sim_game_camera_start(self: eyeware.beam_eye_tracker.API) → bool¶

Start recentering the sim game camera, adjusting it to current user state.

Returns¶

bool: True if the start recentering process could be queued

Note

See Implement the camera recentering for more information.

start_receiving_tracking_data_on_listener(self: eyeware.beam_eye_tracker.API, arg0: eyeware.beam_eye_tracker.TrackingListener) → int¶

Register a listener for asynchronous tracking data updates.

Parameters¶

listenerTrackingListener: A TrackingListener derived class instance

Returns¶

int: Handle for the registered listener

Warning

The listener must remain valid until unregistered

Note

See Asynchronous data access for a detailed explanation.

stop_receiving_tracking_data_on_listener(self: eyeware.beam_eye_tracker.API, arg0: int) → None¶

Deregisters the listener from receiving data from the Beam Eye Tracker application.

Parameters¶

listener_handleint: The handle to the listener to stop receiving tracking data

update_viewport_geometry(self: eyeware.beam_eye_tracker.API, arg0: eyeware.beam_eye_tracker.ViewportGeometry) → None¶

Update the viewport geometry for coordinate mapping.

Parameters¶

new_viewport_geometryViewportGeometry: The new viewport geometry to set

Note

See Viewport for a detailed explanation.

wait_for_new_tracking_state_set(self: eyeware.beam_eye_tracker.API, last_update_timestamp: eyeware.beam_eye_tracker.Timestamp, timeout_ms: int = 1000) → bool¶

Waits until new tracking data becomes available.

This is a blocking call lasting until timeout_ms milliseconds.

Parameters¶

last_update_timestampTimestamp: On input: the timestamp of the last received frame. On output: if new data is available, updated to the timestamp of the newly received frame. Prior to the first iteration, initialize from eyeware.beam_eye_tracker.NULL_DATA_TIMESTAMP().
timeout_msint, optional: The maximum time to wait for new tracking data. Set to 0 to return immediately. Default is :py:attribute`eyeware.beam_eye_tracker.DEFAULT_TRACKING_DATA_TIMEOUT_MS`.

Returns¶

bool: True if new tracking data is available, False if the timeout was reached.

Note

See Synchronous data access and Polling data access.

TrackingStateSet¶

class eyeware.beam_eye_tracker.TrackingStateSet¶

Bases: pybind11_object

The TrackingStateSet is the key object holding tracking data for a time instant.

game_immersive_hud_state(self: eyeware.beam_eye_tracker.TrackingStateSet) → eyeware.beam_eye_tracker.GameImmersiveHUDState¶: Returns the parameters to implement an immersive HUD in your game

sim_game_camera_state(self: eyeware.beam_eye_tracker.TrackingStateSet) → eyeware.beam_eye_tracker.SimGameCameraState¶: Access the latest game camera state to implement the immersive in-game camera controls

user_state(self: eyeware.beam_eye_tracker.TrackingStateSet) → eyeware.beam_eye_tracker.UserState¶: Returns the user state including the user’s gaze on screen and head pose

TrackingListener¶

class eyeware.beam_eye_tracker.TrackingListener¶

Bases: pybind11_object

Interface class which you need to inherit and override with your own callback logic.

on_tracking_data_reception_status_changed(self: eyeware.beam_eye_tracker.TrackingListener, arg0: eyeware.beam_eye_tracker.TrackingDataReceptionStatus) → None¶: Reimplement this method to receive the status of the tracking data reception

on_tracking_state_set_update(self: eyeware.beam_eye_tracker.TrackingListener, tracking_state_set: eyeware.beam_eye_tracker.TrackingStateSet, timestamp: float) → None¶: Reimplement this method to access the latest tracking data as soon as it arrives

Enums¶

TrackingDataReceptionStatus¶

class eyeware.beam_eye_tracker.TrackingDataReceptionStatus¶

Represents the status of the tracking data reception.

Note

For explanation of the possible values, see EW_BET_TrackingDataReceptionStatus.

Members:

NOT_RECEIVING_TRACKING_DATA

RECEIVING_TRACKING_DATA

ATTEMPTING_TRACKING_AUTO_START

ATTEMPTING_TRACKING_AUTO_START = <TrackingDataReceptionStatus.ATTEMPTING_TRACKING_AUTO_START: 2>¶

NOT_RECEIVING_TRACKING_DATA = <TrackingDataReceptionStatus.NOT_RECEIVING_TRACKING_DATA: 0>¶

RECEIVING_TRACKING_DATA = <TrackingDataReceptionStatus.RECEIVING_TRACKING_DATA: 1>¶

property name¶

property value¶

TrackingConfidence¶

class eyeware.beam_eye_tracker.TrackingConfidence¶

Reliability measure for obtained tracking results.

Members:

LOST_TRACKING : The signal/data in question is unavailable and should be discarded.

LOW : Tracking is present but highly uncertain.

MEDIUM : Tracking reliability is fair.

HIGH : Tracking is as reliable as it gets.

HIGH = <TrackingConfidence.HIGH: 3>¶

LOST_TRACKING = <TrackingConfidence.LOST_TRACKING: 0>¶

LOW = <TrackingConfidence.LOW: 1>¶

MEDIUM = <TrackingConfidence.MEDIUM: 2>¶

property name¶

property value¶

Data Types¶

The Python types directly correspond to their C++ counterparts, providing a Pythonic interface while maintaining the same functionality.

Coordinates¶

class eyeware.beam_eye_tracker.Point¶

2D integer point coordinates.

Used primarily for screen coordinates in the unified coordinate system.

property x¶

X coordinate

Type:: int

property y¶

Y coordinate

Type:: int

class eyeware.beam_eye_tracker.PointF¶

2D floating point coordinates.

Used for normalized viewport coordinates and precise positioning.

property x¶

X coordinate

Type:: float

property y¶

Y coordinate

Type:: float

class eyeware.beam_eye_tracker.Vector3D¶

Representation of a 3D vector or 3D point.

property x¶

x coordinate

Type:: float

property y¶

y coordinate

Type:: float

property z¶

z coordinate

Type:: float

Viewport Management¶

class eyeware.beam_eye_tracker.ViewportGeometry¶

Viewport geometry definition.

It is used to map from unified screen coordinates to the viewport normalized coordinates, ranging [0.0, 1.0] for a point inside the viewport rectangle.

Note

See Viewport for more information.

Parameters¶

point_00Point: Point, in unified screen coordinates, where the (0.0, 0.0) point of the viewport is. The point is inclusive, i.e., considered part of the border of the viewport rectangle.
point_11Point: Point, in unified screen coordinates, where the (1.0, 1.0) point of the viewport is. The point is inclusive, i.e., considered part of the border of the viewport rectangle.

property point_00¶

Point, in unified screen coordinates, where the (0.0, 0.0) point of the viewport is

Type:: eyeware.beam_eye_tracker.Point

property point_11¶

Point, in unified screen coordinates, where the (1.0, 1.0) point of the viewport is

Type:: eyeware.beam_eye_tracker.Point

Real-time Tracking¶

class eyeware.beam_eye_tracker.UserState¶

Complete user tracking state.

Note

See Real-time tracking for a detailed explanation.

property head_pose¶

3D head position and orientation

Type:: eyeware.beam_eye_tracker.HeadPose

property timestamp_in_seconds¶

Data timestamp

Type:: eyeware.beam_eye_tracker.Timestamp

property unified_screen_gaze¶

Gaze in screen coordinates

Type:: eyeware.beam_eye_tracker.UnifiedScreenGaze

property viewport_gaze¶

Normalized viewport gaze

Type:: eyeware.beam_eye_tracker.ViewportGaze

class eyeware.beam_eye_tracker.UnifiedScreenGaze¶

Represents information on how the user attention relates to the plugged-in displays.

Point coordinates are referred to the unified screen coordinate system. Accuracy is expected to be lower for the screens for which the eye tracking was not calibrated, and that lead to the users head to have large angles with respect to the camera, when looking at them.

property confidence¶

The confidence of the tracking result

Type:: eyeware.beam_eye_tracker.TrackingConfidence

property point_of_regard¶

Point where the user is looking at, kept within bounds of the screen(s) resolution(s)

Type:: eyeware.beam_eye_tracker.Point

property unbounded_point_of_regard¶

Point where the user is looking at, which may be outside the physical screen space

Type:: eyeware.beam_eye_tracker.Point

class eyeware.beam_eye_tracker.ViewportGaze¶

Represents gaze information in viewport coordinates.

property confidence¶

The confidence of the tracking result

Type:: eyeware.beam_eye_tracker.TrackingConfidence

property normalized_point_of_regard¶

Point where the user is looking at in normalized viewport coordinates [0,1]

Type:: eyeware.beam_eye_tracker.PointF

class eyeware.beam_eye_tracker.HeadPose¶

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

property confidence¶

The confidence of the tracking result

Type:: eyeware.beam_eye_tracker.TrackingConfidence

property rotation_from_hcs_to_wcs¶

Rotation matrix, with respect to the World Coordinate System (WCS)

Type:: numpy.ndarray[float32[3,3]]

property track_session_uid¶

ID of the session of uninterrupted consecutive tracking

Type:: int

property translation_from_hcs_to_wcs¶

Translation vector, with respect to the World Coordinate System (WCS)

Type:: eyeware.beam_eye_tracker.Vector3D

In-game Camera Control¶

class eyeware.beam_eye_tracker.SimGameCameraState¶

Holds the required data to achieve real-time immersive controls of the in-game camera.

Note

See In-game camera control for a detailed explanation.

property eye_tracking_pose_component¶

The camera transform if based solely on the eye tracking data

Type:: eyeware.beam_eye_tracker.SimCameraTransform3D

property head_tracking_pose_component¶

The camera transform if based solely on the head tracking data

Type:: eyeware.beam_eye_tracker.SimCameraTransform3D

property timestamp_in_seconds¶

The timestamp of this update, in seconds

Type:: eyeware.beam_eye_tracker.Timestamp

class eyeware.beam_eye_tracker.SimCameraTransform3D¶

Represents the 3D transform parameters to be applied to the in-game camera.

Warning

Please see Mapping to the game engine coordinate system for explanation on how to interpret the parameters.

property pitch_in_radians¶

Pitch, in radians

Type:: float

property roll_in_radians¶

Roll, in radians

Type:: float

property x_in_meters¶

X translation, in meters

Type:: float

property y_in_meters¶

Y translation, in meters

Type:: float

property yaw_in_radians¶

Yaw, in radians

Type:: float

property z_in_meters¶

Z translation, in meters

Type:: float

Immersive HUD¶

class eyeware.beam_eye_tracker.GameImmersiveHUDState¶

Represents the information needed to implement an immersive HUD in your game.

In many games, the HUD is implemented by UI elements on the 4 corners of the screen, but this struct provides values for all non-center 8 regions of the screen (corners and mid-edges).

The values are in the range [0, 1], where 0 means the user is not looking at the element, and 1 means the user is looking at the element. In most cases, you can simply map to a boolean value using 0.5 as threshold.

Note

See Ready to use “looking at HUD” signals for more information.

property looking_at_viewport_bottom_left¶

Signal of whether the user is looking at the bottom-left region

Type:: float

property looking_at_viewport_bottom_middle¶

Signal of whether the user is looking at the bottom-middle region

Type:: float

property looking_at_viewport_bottom_right¶

Signal of whether the user is looking at the bottom-right region

Type:: float

property looking_at_viewport_center_left¶

Signal of whether the user is looking at the center-left region

Type:: float

property looking_at_viewport_center_right¶

Signal of whether the user is looking at the center-right region

Type:: float

property looking_at_viewport_top_left¶

Signal of whether the user is looking at the top-left region

Type:: float

property looking_at_viewport_top_middle¶

Signal of whether the user is looking at the top-middle region

Type:: float

property looking_at_viewport_top_right¶

Signal of whether the user is looking at the top-right region

Type:: float

property timestamp_in_seconds¶

The timestamp of this update, in seconds

Type:: eyeware.beam_eye_tracker.Timestamp

Foveated rendering¶

class eyeware.beam_eye_tracker.FoveationRadii¶

Represents the radii of the foveated rendering regions.

property radius_level_1¶

Radius of the first level of foveation

Type:: float

property radius_level_2¶

Radius of the second level of foveation

Type:: float

property radius_level_3¶

Radius of the third level of foveation

Type:: float

property radius_level_4¶

Radius of the fourth level of foveation

Type:: float

class eyeware.beam_eye_tracker.FoveatedRenderingState¶

Represents the information needed to implement foveated rendering.

Note

See Foveated rendering for more information.

property normalized_foveation_center¶

The center of the foveated rendering region normalized by the viewport width and height

Type:: eyeware.beam_eye_tracker.PointF

property normalized_foveation_radii¶

The radii of the foveated rendering regions normalized by the viewport width

Type:: eyeware.beam_eye_tracker.FoveationRadii

property timestamp_in_seconds¶

The timestamp of this update, in seconds

Type:: eyeware.beam_eye_tracker.Timestamp

Other Types¶

class eyeware.beam_eye_tracker.Version¶

SDK version information

property build¶

Build number

Type:: int

property major¶

Major version number

Type:: int

property minor¶

Minor version number

Type:: int

property patch¶

Patch level

Type:: int

class eyeware.beam_eye_tracker.Timestamp¶

Timestamp type for tracking data.

Represents time in seconds since tracking started. The counter may reset when tracking is stopped and restarted.

Note

In our Python API, Timestamp is a class holding value instead of being a simple float because the API object needs to be able to modify a Timestamp being received as an argument but, in Python, floats are immutable.

Warning

Not guaranteed to be strictly monotonic due to potential tracking restarts

property value¶

Timestamp value

Type:: float

Utils¶

eyeware.beam_eye_tracker.NULL_DATA_TIMESTAMP() → eyeware.beam_eye_tracker.Timestamp¶

Returns a special timestamp value indicating invalid data.

This constant is used to initialize timestamps before the first tracking data is received, or to indicate invalid/unset timestamp values.

Returns¶

Timestamp: A timestamp instance holding the NULL_DATA_TIMESTAMP value

Example¶

>>> from eyeware.beam_eye_tracker import NULL_DATA_TIMESTAMP
>>> ts = NULL_DATA_TIMESTAMP()
>>> print(ts.value)  # Will print the invalid timestamp value

Constants¶

beam_eye_tracker.DEFAULT_TRACKING_DATA_TIMEOUT_MS = 1000¶