Skip to content

# Reference frames

To implement the Core features of the SDK, it is important to understand how reference frames, such as the world coordinate system (WCS) and the viewport coordinate system, are defined by the Beam Eye Tracker SDK. This section establishes such definitions.

## Camera placement screen

The “camera placement screen” refers to the display where the user has physically placed their webcam and indicated this placement in the Beam Eye Tracker application. When the Beam Eye Tracker shows a visualization of all connected displays, users must click a camera icon on the display that matches where they mounted their webcam (typically at the top or bottom of the screen). This selected screen is therefore the “camera placement screen”.

Settings window captured from the Beam Eye Tracker application. In this two screens example, the camera placement screen is the one on the right.

Warning

The camera placement screen does not necessarily need to be the OS primary screen, or the screen where the game renders. However, users are advised to place their camera at the same screen as the game rendering screen to for better user experience.

## World Coordinate System (WCS)

The world coordinate system (WCS) is the 3D reference frame over which elements such as the head pose are expressed. It is defined as a right-handed coordinate system with the origin at the center of the Camera placement screen (xyz axes represented in red-green-blue, respectively).

## Unified Screen Coordinate System

The “unified screen coordinate system” is the 2D logical reference frame, in pixels, defined by the operating system to provide a common screen coordinate system for multiple displays. In the case of Windows the unified screen corresponds to the Virtual Screen.

## Viewport

The “viewport” is the area on screen where the game is rendering. The Beam Eye Tracker requires knowledge of its geometry for the correct functioning of features such as the In-game camera control or Dynamic HUDs. For this reason, the viewport geometry is a required argument to create the `API` object, and must be updated during gameplay with the relevant function calls.

C

See

- `EW_BET_API_Create()`

- `EW_BET_API_UpdateViewportGeometry()`

C++

See

- `eyeware::beam_eye_tracker::API::API()`

- `eyeware::beam_eye_tracker::API::update_viewport_geometry()`

The viewport geometry is specified by a pair of points, `point_00` and `point_11`, defined with respect to the Unified Screen Coordinate System and represent the mapping into the normalized corner coordinates `(0.0, 0.0)` and `(1.0, 1.0)` of the viewport.

The `point_00` and `point_11` are not necessarily the top-left and bottom-right coordinates respectively. Instead, you can define them arbitrarily as long as they are opposing corners. This allows for flexible configurations, such as in Unity, whose viewport is defined with the `(0.0, 0.0)` coordinates at the bottom-left corner of the rendering area. However, in all scenarios, the first coordinate is the horizontal coordinate, and the second is the vertical one.

Of course, non-gaming application can take advantage of defining a viewport, to conveniently received gaze data already mapped to viewport normalized coordinates.

Example of a viewport following the Unity convention, with `point_00` at the bottom-left corner of the rendering area.

Warning

Through the `API`, you should inform of changes on the viewport geometry, for example when the game window is resized or moved.

General API concepts
Core features