Skip to content

# 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

  See also

  Timestamps for more information about timestamp handling.

## Constants

beam_eye_tracker.DEFAULT_TRACKING_DATA_TIMEOUT_MS = 1000

C
C#