Streaming Gaze Data

Use device.receive_gaze_datum to receive gaze data.

gaze = device.receive_gaze_datum()

This function can return different types of gaze data (GazeDataType) depending on the device and its configuration:

• GazeData object for Pupil Invisible or Neon without "Compute eye state" enabled.
• EyestateGazeData or EyestateEyelidGazeData for Neon with "Compute eye state" enabled, depending on the version of the Neon Companion app.

See below samples for each type of gaze data.

Gaze dataWith Eye StateWith Eye State & Eye Lid

GazeData(
    x=784.0623779296875,
    y=537.4524536132812,
    worn=False,
    timestamp_unix_seconds=1744294828.3579288
)

This method exposes gaze data

GazeData

GazeData

Bases: NamedTuple

Basic gaze data with position, timestamp and indicator of glasses worn status.

Represents the 2D gaze point on the scene camera coordinates with a timestamp in nanoseconds unix epoch and an indicator of whether the glasses are being worn.

Methods:

• from_raw –

  Create a GazeData instance from raw data.

Attributes:

• datetime (datetime) –

  Get the timestamp as a datetime object.

• timestamp_unix_ns (int) –

  Get the timestamp in nanoseconds since Unix epoch.

• timestamp_unix_seconds (float) –

  Timestamp in seconds since Unix epoch.

• worn (bool) –

  Whether the glasses are being worn.

• x (float) –

  "X coordinate of the gaze point

• y (float) –

  Y coordinate of the gaze point.

datetime property

datetime: datetime

Get the timestamp as a datetime object.

timestamp_unix_ns property

timestamp_unix_ns: int

Get the timestamp in nanoseconds since Unix epoch.

timestamp_unix_seconds instance-attribute

timestamp_unix_seconds: float

Timestamp in seconds since Unix epoch.

worn instance-attribute

worn: bool

Whether the glasses are being worn.

x instance-attribute

x: float

"X coordinate of the gaze point

y instance-attribute

y: float

Y coordinate of the gaze point.

from_raw classmethod

from_raw(data: RTSPData) -> GazeData

Create a GazeData instance from raw data.

Parameters:

• data (RTSPData) –

  The raw data received from the RTSP stream.

Returns:

• GazeData ( GazeData ) –

  An instance of GazeData with the parsed values.

Source code in src/pupil_labs/realtime_api/streaming/gaze.py

@classmethod
def from_raw(cls, data: RTSPData) -> "GazeData":
    """Create a GazeData instance from raw data.

    Args:
        data (RTSPData): The raw data received from the RTSP stream.

    Returns:
        GazeData: An instance of GazeData with the parsed values.

    """
    x, y, worn = struct.unpack("!ffB", data.raw)
    return cls(x, y, worn == 255, data.timestamp_unix_seconds)

Neon +2.8.8 +1.2.0

EyestateGazeData(
    x=784.0623779296875,
    y=537.4524536132812,
    worn=False,
    pupil_diameter_left=4.306737899780273,
    eyeball_center_left_x=-29.3125,
    eyeball_center_left_y=11.6875,
    eyeball_center_left_z=-42.15625,
    optical_axis_left_x=0.09871648252010345,
    optical_axis_left_y=0.15512824058532715,
    optical_axis_left_z=0.9829498529434204,
    pupil_diameter_right=3.2171919345855713,
    eyeball_center_right_x=33.21875,
    eyeball_center_right_y=12.84375,
    eyeball_center_right_z=-45.34375,
    optical_axis_right_x=-0.20461124181747437,
    optical_axis_right_y=0.1512681096792221,
    optical_axis_right_z=0.9670844078063965,
    timestamp_unix_seconds=1744294828.3579288
)

This method exposes gaze data, pupil diameter, and eye poses.

EyestateGazeData

EyestateGazeData

Bases: NamedTuple

Gaze data with additional eye state information.

Contains gaze point, pupil diameter, eyeball center coordinates, and optical axis coordinates for both left and right eyes.

Methods:

• from_raw –

  Create an EyestateGazeData instance from raw data.

Attributes:

• datetime (datetime) –

  Get the timestamp as a datetime object.

• eyeball_center_left_x (float) –

  X coordinate of the eyeball center for the left eye.

• eyeball_center_left_y (float) –

  Y coordinate of the eyeball center for the left eye.

• eyeball_center_left_z (float) –

  Z coordinate of the eyeball center for the left eye.

• eyeball_center_right_x (float) –

  X coordinate of the eyeball center for the right eye.

• eyeball_center_right_y (float) –

  Y coordinate of the eyeball center for the right eye.

• eyeball_center_right_z (float) –

  Z coordinate of the eyeball center for the right eye.

• optical_axis_left_x (float) –

  X coordinate of the optical axis for the left eye.

• optical_axis_left_y (float) –

  Y coordinate of the optical axis for the left eye.

• optical_axis_left_z (float) –

  Z coordinate of the optical axis for the left eye.

• optical_axis_right_x (float) –

  X coordinate of the optical axis for the right eye.

• optical_axis_right_y (float) –

  Y coordinate of the optical axis for the right eye.

• optical_axis_right_z (float) –

  Z coordinate of the optical axis for the right eye.

• pupil_diameter_left (float) –

  Pupil diameter for the left eye.

• pupil_diameter_right (float) –

  Pupil diameter for the right eye.

• timestamp_unix_ns (int) –

  Get the timestamp in nanoseconds since Unix epoch.

• timestamp_unix_seconds (float) –

  Timestamp in seconds since Unix epoch.

• worn (bool) –

  Whether the glasses are being worn.

• x (float) –

  X coordinate of the gaze point.

• y (float) –

  Y coordinate of the gaze point.

datetime property

datetime: datetime

Get the timestamp as a datetime object.

eyeball_center_left_x instance-attribute

eyeball_center_left_x: float

X coordinate of the eyeball center for the left eye.

eyeball_center_left_y instance-attribute

eyeball_center_left_y: float

Y coordinate of the eyeball center for the left eye.

eyeball_center_left_z instance-attribute

eyeball_center_left_z: float

Z coordinate of the eyeball center for the left eye.

eyeball_center_right_x instance-attribute

eyeball_center_right_x: float

X coordinate of the eyeball center for the right eye.

eyeball_center_right_y instance-attribute

eyeball_center_right_y: float

Y coordinate of the eyeball center for the right eye.

eyeball_center_right_z instance-attribute

eyeball_center_right_z: float

Z coordinate of the eyeball center for the right eye.

optical_axis_left_x instance-attribute

optical_axis_left_x: float

X coordinate of the optical axis for the left eye.

optical_axis_left_y instance-attribute

optical_axis_left_y: float

Y coordinate of the optical axis for the left eye.

optical_axis_left_z instance-attribute

optical_axis_left_z: float

Z coordinate of the optical axis for the left eye.

optical_axis_right_x instance-attribute

optical_axis_right_x: float

X coordinate of the optical axis for the right eye.

optical_axis_right_y instance-attribute

optical_axis_right_y: float

Y coordinate of the optical axis for the right eye.

optical_axis_right_z instance-attribute

optical_axis_right_z: float

Z coordinate of the optical axis for the right eye.

pupil_diameter_left instance-attribute

pupil_diameter_left: float

Pupil diameter for the left eye.

pupil_diameter_right instance-attribute

pupil_diameter_right: float

Pupil diameter for the right eye.

timestamp_unix_ns property

timestamp_unix_ns: int

Get the timestamp in nanoseconds since Unix epoch.

timestamp_unix_seconds instance-attribute

timestamp_unix_seconds: float

Timestamp in seconds since Unix epoch.

worn instance-attribute

worn: bool

Whether the glasses are being worn.

x instance-attribute

x: float

X coordinate of the gaze point.

y instance-attribute

y: float

Y coordinate of the gaze point.

from_raw classmethod

from_raw(data: RTSPData) -> EyestateGazeData

Create an EyestateGazeData instance from raw data.

Parameters:

• data (RTSPData) –

  The raw data received from the RTSP stream.

Returns:

• EyestateGazeData ( EyestateGazeData ) –

  An instance of EyestateGazeData with the parsed values.

Source code in src/pupil_labs/realtime_api/streaming/gaze.py

@classmethod
def from_raw(cls, data: RTSPData) -> "EyestateGazeData":
    """Create an EyestateGazeData instance from raw data.

    Args:
        data (RTSPData): The raw data received from the RTSP stream.

    Returns:
        EyestateGazeData: An instance of EyestateGazeData with the parsed values.

    """
    (
        x,
        y,
        worn,
        pupil_diameter_left,
        eyeball_center_left_x,
        eyeball_center_left_y,
        eyeball_center_left_z,
        optical_axis_left_x,
        optical_axis_left_y,
        optical_axis_left_z,
        pupil_diam_right,
        eyeball_center_right_x,
        eyeball_center_right_y,
        eyeball_center_right_z,
        optical_axis_right_x,
        optical_axis_right_y,
        optical_axis_right_z,
    ) = struct.unpack("!ffBffffffffffffff", data.raw)
    return cls(
        x,
        y,
        worn == 255,
        pupil_diameter_left,
        eyeball_center_left_x,
        eyeball_center_left_y,
        eyeball_center_left_z,
        optical_axis_left_x,
        optical_axis_left_y,
        optical_axis_left_z,
        pupil_diam_right,
        eyeball_center_right_x,
        eyeball_center_right_y,
        eyeball_center_right_z,
        optical_axis_right_x,
        optical_axis_right_y,
        optical_axis_right_z,
        data.timestamp_unix_seconds,
    )

Neon +2.9.0 +1.3.6

EyestateEyelidGazeData(
    x=784.0623779296875,
    y=537.4524536132812,
    worn=False,
    pupil_diameter_left=4.306737899780273,
    eyeball_center_left_x=-29.3125,
    eyeball_center_left_y=11.6875,
    eyeball_center_left_z=-42.15625,
    optical_axis_left_x=0.09871648252010345,
    optical_axis_left_y=0.15512824058532715,
    optical_axis_left_z=0.9829498529434204,
    pupil_diameter_right=3.2171919345855713,
    eyeball_center_right_x=33.21875,
    eyeball_center_right_y=12.84375,
    eyeball_center_right_z=-45.34375,
    optical_axis_right_x=-0.20461124181747437,
    optical_axis_right_y=0.1512681096792221,
    optical_axis_right_z=0.9670844078063965,
    eyelid_angle_top_left=-1.1484375,
    eyelid_angle_bottom_left=-1.2763671875,
    eyelid_aperture_left=1.6408717632293701,
    eyelid_angle_top_right=-0.6259765625,
    eyelid_angle_bottom_right=-1.2216796875,
    eyelid_aperture_right=7.2039408683776855,
    timestamp_unix_seconds=1744294828.3579288
)

This method exposes gaze data, pupil diameter, eye poses, and eye openness data.

EyestateEyelidGazeData

EyestateEyelidGazeData

Bases: NamedTuple

Gaze data with additional eyelid state information.

Contains gaze point, pupil diameter, eyeball center coordinates, optical axis coordinates, as well as eyelid angles and aperture for both left and right eyes.

Methods:

• from_raw –

  Create an EyestateEyelidGazeData instance from raw data.

Attributes:

• datetime (datetime) –

  Get the timestamp as a datetime object.

• eyeball_center_left_x (float) –

  X coordinate of the eyeball center for the left eye.

• eyeball_center_left_y (float) –

  Y coordinate of the eyeball center for the left eye.

• eyeball_center_left_z (float) –

  Z coordinate of the eyeball center for the left eye.

• eyeball_center_right_x (float) –

  X coordinate of the eyeball center for the right eye.

• eyeball_center_right_y (float) –

  Y coordinate of the eyeball center for the right eye.

• eyeball_center_right_z (float) –

  Z coordinate of the eyeball center for the right eye.

• eyelid_angle_bottom_left (float) –

  Angle of the bottom eyelid for the left eye(rad).

• eyelid_angle_bottom_right (float) –

  Angle of the bottom eyelid for the right eye (rad).

• eyelid_angle_top_left (float) –

  Angle of the top eyelid for the left eye(rad).

• eyelid_angle_top_right (float) –

  Angle of the top eyelid for the right eye (rad).

• eyelid_aperture_left (float) –

  Aperture of the eyelid for the left eye (mm).

• eyelid_aperture_right (float) –

  Aperture of the eyelid for the right eye (mm).

• optical_axis_left_x (float) –

  X coordinate of the optical axis for the left eye.

• optical_axis_left_y (float) –

  Y coordinate of the optical axis for the left eye.

• optical_axis_left_z (float) –

  Z coordinate of the optical axis for the left eye.

• optical_axis_right_x (float) –

  X coordinate of the optical axis for the right eye.

• optical_axis_right_y (float) –

  Y coordinate of the optical axis for the right eye.

• optical_axis_right_z (float) –

  Z coordinate of the optical axis for the right eye.

• pupil_diameter_left (float) –

  Pupil diameter for the left eye.

• pupil_diameter_right (float) –

  Pupil diameter for the right eye.

• timestamp_unix_ns (int) –

  Get the timestamp in nanoseconds since Unix epoch.

• timestamp_unix_seconds (float) –

  Timestamp in seconds since Unix epoch.

• worn (bool) –

  Whether the glasses are being worn.

• x (float) –

  X coordinate of the gaze point.

• y (float) –

  Y coordinate of the gaze point.

datetime property

datetime: datetime

Get the timestamp as a datetime object.

eyeball_center_left_x instance-attribute

eyeball_center_left_x: float

X coordinate of the eyeball center for the left eye.

eyeball_center_left_y instance-attribute

eyeball_center_left_y: float

Y coordinate of the eyeball center for the left eye.

eyeball_center_left_z instance-attribute

eyeball_center_left_z: float

Z coordinate of the eyeball center for the left eye.

eyeball_center_right_x instance-attribute

eyeball_center_right_x: float

X coordinate of the eyeball center for the right eye.

eyeball_center_right_y instance-attribute

eyeball_center_right_y: float

Y coordinate of the eyeball center for the right eye.

eyeball_center_right_z instance-attribute

eyeball_center_right_z: float

Z coordinate of the eyeball center for the right eye.

eyelid_angle_bottom_left instance-attribute

eyelid_angle_bottom_left: float

Angle of the bottom eyelid for the left eye(rad).

eyelid_angle_bottom_right instance-attribute

eyelid_angle_bottom_right: float

Angle of the bottom eyelid for the right eye (rad).

eyelid_angle_top_left instance-attribute

eyelid_angle_top_left: float

Angle of the top eyelid for the left eye(rad).

eyelid_angle_top_right instance-attribute

eyelid_angle_top_right: float

Angle of the top eyelid for the right eye (rad).

eyelid_aperture_left instance-attribute

eyelid_aperture_left: float

Aperture of the eyelid for the left eye (mm).

eyelid_aperture_right instance-attribute

eyelid_aperture_right: float

Aperture of the eyelid for the right eye (mm).

optical_axis_left_x instance-attribute

optical_axis_left_x: float

X coordinate of the optical axis for the left eye.

optical_axis_left_y instance-attribute

optical_axis_left_y: float

Y coordinate of the optical axis for the left eye.

optical_axis_left_z instance-attribute

optical_axis_left_z: float

Z coordinate of the optical axis for the left eye.

optical_axis_right_x instance-attribute

optical_axis_right_x: float

X coordinate of the optical axis for the right eye.

optical_axis_right_y instance-attribute

optical_axis_right_y: float

Y coordinate of the optical axis for the right eye.

optical_axis_right_z instance-attribute

optical_axis_right_z: float

Z coordinate of the optical axis for the right eye.

pupil_diameter_left instance-attribute

pupil_diameter_left: float

Pupil diameter for the left eye.

pupil_diameter_right instance-attribute

pupil_diameter_right: float

Pupil diameter for the right eye.

timestamp_unix_ns property

timestamp_unix_ns: int

Get the timestamp in nanoseconds since Unix epoch.

timestamp_unix_seconds instance-attribute

timestamp_unix_seconds: float

Timestamp in seconds since Unix epoch.

worn instance-attribute

worn: bool

Whether the glasses are being worn.

x instance-attribute

x: float

X coordinate of the gaze point.

y instance-attribute

y: float

Y coordinate of the gaze point.

from_raw classmethod

from_raw(data: RTSPData) -> EyestateEyelidGazeData

Create an EyestateEyelidGazeData instance from raw data.

Parameters:

• data (RTSPData) –

  The raw data received from the RTSP stream.

Returns:

• EyestateEyelidGazeData ( EyestateEyelidGazeData ) –

  An instance of EyestateEyelidGazeData with the parsed values.

Source code in src/pupil_labs/realtime_api/streaming/gaze.py

@classmethod
def from_raw(cls, data: RTSPData) -> "EyestateEyelidGazeData":
    """Create an EyestateEyelidGazeData instance from raw data.

    Args:
        data (RTSPData): The raw data received from the RTSP stream.

    Returns:
        EyestateEyelidGazeData: An instance of EyestateEyelidGazeData with the
            parsed values.

    """
    (
        x,
        y,
        worn,
        pupil_diameter_left,
        eyeball_center_left_x,
        eyeball_center_left_y,
        eyeball_center_left_z,
        optical_axis_left_x,
        optical_axis_left_y,
        optical_axis_left_z,
        pupil_diam_right,
        eyeball_center_right_x,
        eyeball_center_right_y,
        eyeball_center_right_z,
        optical_axis_right_x,
        optical_axis_right_y,
        optical_axis_right_z,
        eyelid_angle_top_left,
        eyelid_angle_bottom_left,
        eyelid_aperture_left,
        eyelid_angle_top_right,
        eyelid_angle_bottom_right,
        eyelid_aperture_right,
    ) = struct.unpack("!ffBffffffffffffffffffff", data.raw)
    return cls(
        x,
        y,
        worn == 255,
        pupil_diameter_left,
        eyeball_center_left_x,
        eyeball_center_left_y,
        eyeball_center_left_z,
        optical_axis_left_x,
        optical_axis_left_y,
        optical_axis_left_z,
        pupil_diam_right,
        eyeball_center_right_x,
        eyeball_center_right_y,
        eyeball_center_right_z,
        optical_axis_right_x,
        optical_axis_right_y,
        optical_axis_right_z,
        eyelid_angle_top_left,
        eyelid_angle_bottom_left,
        eyelid_aperture_left,
        eyelid_angle_top_right,
        eyelid_angle_bottom_right,
        eyelid_aperture_right,
        data.timestamp_unix_seconds,
    )

You can learn more about the payload in Under the Hood.

Full Code Examples

Check the whole example code here

from pupil_labs.realtime_api.simple import discover_one_device

# Look for devices. Returns as soon as it has found the first device.
print("Looking for the next best device...")
device = discover_one_device(max_search_duration_seconds=10)
if device is None:
    print("No device found.")
    raise SystemExit(-1)

# device.streaming_start()  # optional, if not called, stream is started on-demand

try:
    while True:
        print(device.receive_gaze_datum())
except KeyboardInterrupt:
    pass
finally:
    print("Stopping...")
    # device.streaming_stop()  # optional, if not called, stream is stopped on close
    device.close()  # explicitly stop auto-update