From 619c9867af6e1c5c29e39b3fd33d92884bdedf0c Mon Sep 17 00:00:00 2001
From: Mohamed Eyad <mooeyad@gmail.com>
Date: Tue, 9 Jun 2026 00:36:17 +0200
Subject: [PATCH] feat: add oculometrics messages for eye tracking (Blink,
 Fixation, Saccade, PupilGaze)

---
 .../derived_biosignals/oculometrics/Blink.msg |  5 +++
 .../oculometrics/Fixation.msg                 | 15 ++++++++
 .../oculometrics/Saccade.msg                  | 15 ++++++++
 .../raw_biosignals/oculometrics/PupilGaze.msg | 38 +++++++++++++++++++
 4 files changed, 73 insertions(+)
 create mode 100644 msg/biosensing/derived_biosignals/oculometrics/Blink.msg
 create mode 100644 msg/biosensing/derived_biosignals/oculometrics/Fixation.msg
 create mode 100644 msg/biosensing/derived_biosignals/oculometrics/Saccade.msg
 create mode 100644 msg/biosensing/raw_biosignals/oculometrics/PupilGaze.msg

diff --git a/msg/biosensing/derived_biosignals/oculometrics/Blink.msg b/msg/biosensing/derived_biosignals/oculometrics/Blink.msg
new file mode 100644
index 0000000..c0d354a
--- /dev/null
+++ b/msg/biosensing/derived_biosignals/oculometrics/Blink.msg
@@ -0,0 +1,5 @@
+# Blink.msg
+std_msgs/Header header
+float64 duration          # Calculated duration of the blink in seconds
+int64 start_time_ns       # Raw start time in nanoseconds
+int64 end_time_ns         # Raw end time in nanoseconds
diff --git a/msg/biosensing/derived_biosignals/oculometrics/Fixation.msg b/msg/biosensing/derived_biosignals/oculometrics/Fixation.msg
new file mode 100644
index 0000000..cc65e0a
--- /dev/null
+++ b/msg/biosensing/derived_biosignals/oculometrics/Fixation.msg
@@ -0,0 +1,15 @@
+# Fixation.msg
+std_msgs/Header header
+float64 duration              # Calculated: (end_time_ns - start_time_ns) / 1e9
+int64 start_time_ns
+int64 end_time_ns
+float64 start_gaze_x
+float64 start_gaze_y
+float64 end_gaze_x
+float64 end_gaze_y
+float64 mean_gaze_x
+float64 mean_gaze_y
+float64 amplitude_pixels
+float64 amplitude_angle_deg
+float64 mean_velocity
+float64 max_velocity
diff --git a/msg/biosensing/derived_biosignals/oculometrics/Saccade.msg b/msg/biosensing/derived_biosignals/oculometrics/Saccade.msg
new file mode 100644
index 0000000..da6a0e5
--- /dev/null
+++ b/msg/biosensing/derived_biosignals/oculometrics/Saccade.msg
@@ -0,0 +1,15 @@
+# Saccade.msg
+std_msgs/Header header
+float64 duration              # Calculated: (end_time_ns - start_time_ns) / 1e9
+int64 start_time_ns
+int64 end_time_ns
+float64 start_gaze_x
+float64 start_gaze_y
+float64 end_gaze_x
+float64 end_gaze_y
+float64 mean_gaze_x
+float64 mean_gaze_y
+float64 amplitude_pixels
+float64 amplitude_angle_deg
+float64 mean_velocity
+float64 max_velocity
diff --git a/msg/biosensing/raw_biosignals/oculometrics/PupilGaze.msg b/msg/biosensing/raw_biosignals/oculometrics/PupilGaze.msg
new file mode 100644
index 0000000..9212174
--- /dev/null
+++ b/msg/biosensing/raw_biosignals/oculometrics/PupilGaze.msg
@@ -0,0 +1,38 @@
+# PupilGaze.msg
+std_msgs/Header header
+float64 gaze_x
+float64 gaze_y
+bool worn
+
+# Pupil Diameters
+float64 pupil_diameter_left
+float64 pupil_diameter_right
+
+# 3D Eyeball Center (Left)
+float64 eyeball_center_left_x
+float64 eyeball_center_left_y
+float64 eyeball_center_left_z
+
+# 3D Optical Axis (Left)
+float64 optical_axis_left_x
+float64 optical_axis_left_y
+float64 optical_axis_left_z
+
+# 3D Eyeball Center (Right)
+float64 eyeball_center_right_x
+float64 eyeball_center_right_y
+float64 eyeball_center_right_z
+
+# 3D Optical Axis (Right)
+float64 optical_axis_right_x
+float64 optical_axis_right_y
+float64 optical_axis_right_z
+
+# Eyelid State
+float64 eyelid_angle_top_left
+float64 eyelid_angle_bottom_left
+float64 eyelid_aperture_left
+
+float64 eyelid_angle_top_right
+float64 eyelid_angle_bottom_right
+float64 eyelid_aperture_right