# Pupil Invisible Recording Format
# Recording Folders
The export contains one folder per recording following this naming scheme:
<recording name>-<start of recording ID>
The files included in every folder are described in the following.
# info.json
This file contains meta-information on the recording.
| Field | Description |
|---|---|
| android_device_id | Unique identifier of the Android device used as Invisible Companion. |
| android_device_model | Model name of the Companion device. |
| android_device_name | Device name of the Companion device. |
| app_version | Version of the Companion app used to make the recording. |
| calib_version | Version of the offset correction used by the Companion app. |
| data_format_version | Version of the data format used by the Companion app. |
| duration | Duration of the recording in nanoseconds |
| gaze_offset | Gaze offset applied to this recording using the offset correction. Values are in pixels. |
| glasses_serial_number | Serial number of the Pupil Invisible glasses used for the recording. |
| pipeline_version | Version of the gaze estimation pipeline used by the Companion app. |
| recording_id | Unique identifier of the recording. |
| scene_camera_serial_number | Serial number of the scene camera used for the recording. |
| start_time | Timestamp of when the recording was started. Given as UTC timestamp in nanoseconds. |
| template_data | Data regarding the selected template for the recording as well as the response values. |
| wearer_id | Unique identifier of the wearer selected for this recording. |
| wearer_name | Name of the wearer selected for this recording. |
Scene Video
Scene video is contained in a file following the following naming scheme:
<beginning of section ID>_<section start time>-<section end time>.mp4
# scene_camera.json
This file contains the camera intrinsics of the used scene camera. The values are determined via calibration of every camera during manufacturing.
| Field | Description |
|---|---|
| camera_matrix | The camera matrix of the scene camera. |
| dist_coefs | The distortion coefficients of the scene camera. The order of the values is (k1, k2, p1, p2, k3, k4, k5, k6) following OpenCV's distortion model. |
| rotation_matrix | Extrinsic rotation matrix describing how the scene camera is positioned in relation to the eye cameras. For more details please see section III-B of the white paper. |
| serial_number | The serial number of the scene camera. This number can also be found on the back of the scene camera module. Please note that this number is different from the serial number of the frame, which can be found on the tip of the left temple of the Pupil Invisible frame. |
| version | The version of the intrinsics data format. |
# world_timestamps.csv
This file contains the timestamps of every world video frame.
| Field | Description |
|---|---|
| section id | Unique identifier of the corresponding section. |
| recording id | Unique identifier of the recording this sample belongs to. |
| timestamp [ns] | UTC timestamp in nanoseconds of the corresponding world frame. |
# events.csv
This file contains event data for all recordings. It contains both project event annotations and real-time recording events.
| Field | Description |
|---|---|
| recording id | Unique identifier of the recording this event belongs to. |
| timestamp [ns] | UTC timestamp of the event. |
| name | Name of the event. |
| type | Type of the event. Possible values: project, recording |
# gaze.csv
This file contains gaze data in world camera coordinates.
| Field | Description |
|---|---|
| section id | Unique identifier of the corresponding section. |
| recording id | Unique identifier of the recording this sample belongs to. |
| timestamp [ns] | UTC timestamp in nanoseconds of the sample. Equal to the timestamp of the original gaze sample before mapping. |
| gaze x [px] | Float value representing the x-coordinate of the mapped gaze point in world camera pixel coordinates. |
| gaze y [px] | Same as "gaze x [px]" but for the y-coordinate. |
| worn | This value indicates whether the Pupil Invisible Glasses have been worn by a subject at this point in time. 1.0 indicates that it has been worn, while 0.0 indicates that it has not been worn. Added in version 2 of this enrichment. |
| fixation id | If this gaze sample belongs to a fixation event, this is the corresponding id of the fixation. Otherwise, this field is empty. |
| blink id | If this gaze samples belongs to a blink event, this is the corresponding id of the blink. Otherwise this field is empty. |
| azimuth [deg] | The azimuth of the gaze ray in relation to the scene camera in degrees. |
| elevation [deg] | The elevation of the gaze ray in relation to the scene camera in degrees. |
# fixations.csv
This file contains fixations detected in the gaze data stream.
The corresponding gaze samples that belong to each fixation can be determined from the gaze.csv file using the fixation id field.
| Field | Description |
|---|---|
| section id | Unique identifier of the corresponding section. |
| recording id | Unique identifier of the recording this sample belongs to. |
| fixation id | Identifier of the fixation. The counter starts at the beginning of the recording. |
| start timestamp [ns] | UTC timestamp in nanoseconds of the start of the fixation. |
| end timestamp [ns] | UTC timestamp in nanoseconds of the end of the fixation. |
| duration [ms] | Duration of the fixation in milliseconds. |
| fixation x [px] | Float value representing the x-coordinate of the fixation in world camera pixel coordinates. This position is the average of all gaze samples within the fixation. |
| fixation y [px] | Same as "fixation x [px]" but for the y-coordinate. |
# blinks.csv
This file contains blinks detected in the eye video.
The corresponding gaze samples that belong to each blink can be determined from the gaze.csv file using the blink id field.
| Field | Description |
|---|---|
| section id | Unique identifier of the corresponding section. |
| recording id | Unique identifier of the recording this sample belongs to. |
| blink id | Identifier of the blink. The counter starts at the beginning of the recording. |
| start timestamp [ns] | UTC timestamp in nanoseconds of the start of the blink. |
| end timestamp [ns] | UTC timestamp in nanoseconds of the end of the blink. |
| duration [ms] | Duration of the blink in milliseconds. |
# imu.csv
This file contains data recorded by the integrated IMU (inertial measurement unit).
| Field | Description |
|---|---|
| section id | Unique identifier of the corresponding section. |
| recording id | Unique identifier of the recording this sample belongs to. |
| timestamp [ns] | UTC timestamp in nanoseconds of the sample. |
| gyro x [deg/s] gyro y [deg/s] gyro z [deg/s] | Rotation speed around x, y or z-axis respectively in degrees/s. |
| acceleration x [G] acceleration y [G] acceleration z [G] | Translational acceleration along the x, y or z-axis respectively in G. Note 1 G = 9.80665 m/s^2. |
| roll | Drift-free estimation of the roll (head tilt from side to side) in degrees. The output range is -180 to +180 degrees. Added in version 2 of this enrichment. |
| pitch | Drift-free estimation of the pitch (head tilt from front to back) in degrees. The output range is -180 to +180 degrees. Added in version 2 of this enrichment. |