| Title: | Read and Plot 'Tobii Pro Glasses 3' Recordings |
|---|---|
| Description: | Reads recordings made with the 'Tobii Pro Glasses 3' wearable eye tracker directly from the folder on the SD card, so 'Tobii Pro Lab' is not needed. Gaze, pupil diameter, inertial measurement unit and sync port data are read from the compressed JSON files into tibbles, along with the recording metadata. Samples can be aligned with sync port pulses and cut into epochs. Further functions fill gaps in the time series, average samples into time bins and convert gaze directions to angles. Pupil diameter and gaze position can be plotted. |
| Authors: | Massimiliano Canzi [aut, cre, cph] (ORCID: <https://orcid.org/0000-0001-6124-0321>) |
| Maintainer: | Massimiliano Canzi <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-11-17 17:13:18 UTC |
| Source: | https://github.com/mcanzi/glasses3 |
Adds the sync port state and the most recent pulse to each sample of gaze
or IMU data. With several recordings, samples are matched to the pulses
of their own recording through the recording column.
g3_add_syncport(x, events, direction = c("out", "in"))g3_add_syncport(x, events, direction = c("out", "in"))
x |
A data frame with a |
events |
Event data from |
direction |
|
x with three added columns: syncport (1 while the signal is
high, 0 otherwise), pulse (number of the most recent pulse onset, NA
before the first one) and pulse_time (seconds since that onset). If
x is a grouped tibble, the result has the same groups.
rec <- read_g3(g3_example()) gaze <- g3_add_syncport(rec$gaze, rec$events) gaze |> dplyr::filter(syncport == 1) |> dplyr::select(time, pulse, pulse_time)rec <- read_g3(g3_example()) gaze <- g3_add_syncport(rec$gaze, rec$events) gaze |> dplyr::filter(syncport == 1) |> dplyr::select(time, pulse, pulse_time)
Averages samples within bins of fixed width, for example to reduce 50 Hz data to 100 ms bins before fitting a generalised additive mixed model. Fewer samples make models faster to fit and reduce the autocorrelation the model has to account for.
g3_downsample(x, bin = 0.1, min_valid = 0.5, by = NULL)g3_downsample(x, bin = 0.1, min_valid = 0.5, by = NULL)
x |
Gaze data from |
bin |
Bin width in seconds. |
min_valid |
Proportion of samples in a bin that must have a value.
A numeric column is |
by |
Names of further columns to group by, such as a participant or condition column. They are kept in the result. |
Bins are counted from time 0, or from the pulse onset for epochs from
g3_epochs(), so that the onset falls on a bin boundary. Each bin is
labelled with its start time. Rows are grouped by the recording, pulse
and eye columns where these exist, so the function works on the output
of read_g3_gaze(), g3_epochs() and g3_pupil_long(). Columns named in
by are added to these groups, and so are the groups of a grouped tibble.
A tibble with one row per bin and group, starting with the
grouping columns. Other numeric columns hold the mean of the available
samples, and logical columns, such as valid, the proportion of TRUE
samples. samples gives the number of samples in the bin. All other
columns are dropped. A grouped tibble keeps its groups.
gaze <- read_g3_gaze(g3_example()) g3_downsample(gaze, bin = 0.1) rec <- read_g3(g3_example()) ep <- g3_epochs(rec$gaze, rec$events, before = 0.5, after = 3) g3_downsample(g3_pupil_long(ep), bin = 0.1) gaze |> dplyr::mutate(participant = "P01") |> g3_downsample(bin = 0.1, by = "participant")gaze <- read_g3_gaze(g3_example()) g3_downsample(gaze, bin = 0.1) rec <- read_g3(g3_example()) ep <- g3_epochs(rec$gaze, rec$events, before = 0.5, after = 3) g3_downsample(g3_pupil_long(ep), bin = 0.1) gaze |> dplyr::mutate(participant = "P01") |> g3_downsample(bin = 0.1, by = "participant")
Returns the samples from before seconds before to after seconds after
the onset of each sync port pulse, for example to analyse pupil responses
to stimuli whose onset was marked with a sync pulse. With several
recordings, each recording is cut at its own pulses.
g3_epochs( x, events, before = 0, after = 1, direction = c("out", "in"), pulses = NULL )g3_epochs( x, events, before = 0, after = 1, direction = c("out", "in"), pulses = NULL )
x |
A data frame with a |
events |
Event data from |
before, after
|
Seconds to keep before and after each onset. |
direction |
|
pulses |
Which pulses to use, as pulse numbers. Defaults to all. |
The selected rows of x, sorted by time within each epoch, with
added columns pulse and epoch_time (seconds relative to the pulse
onset). Samples can appear in more than one epoch if epochs overlap. If
x is a grouped tibble, the result has the same groups.
rec <- read_g3(g3_example()) ep <- g3_epochs(rec$gaze, rec$events, before = 1, after = 5) dplyr::count(ep, pulse)rec <- read_g3(g3_example()) ep <- g3_epochs(rec$gaze, rec$events, before = 1, after = 5) dplyr::count(ep, pulse)
The package includes the first 30 seconds of a Glasses 3 recording at 50 Hz. The scene video is left out, and the participant name, serial numbers, recording ID and start time are replaced with placeholders.
g3_example()g3_example()
Path to the example recording folder.
g3_example()g3_example()
The glasses write a line even for samples where they detect no gaze, so
the gaze data are usually complete. Samples can still be missing, for
example after damaged lines were skipped. g3_fill_gaps() inserts a row
for each missing sample, so that the data are evenly spaced again, as many
preprocessing methods assume. The new rows hold NA, and their validity
columns are FALSE. Values are not interpolated.
g3_fill_gaps(x, rate = NULL)g3_fill_gaps(x, rate = NULL)
x |
Gaze data from |
rate |
Sampling rate in Hz. By default it is worked out from the median interval between samples and set to 50 or 100 Hz when it is within 10% of either. |
With several recordings in x, each is filled separately. The recording
column and columns you added yourself, such as a participant column, are
copied into the new rows when they have a single value within the
recording.
x with the inserted rows, sorted by time, and a logical column
inserted that is TRUE for the new rows. If x is a grouped tibble,
the result has the same groups.
gaze <- read_g3_gaze(g3_example()) gappy <- dplyr::slice(gaze, -(100:109)) filled <- g3_fill_gaps(gappy) nrow(gappy) nrow(filled) filled |> dplyr::filter(inserted) |> dplyr::select(time, left_pupil, valid)gaze <- read_g3_gaze(g3_example()) gappy <- dplyr::slice(gaze, -(100:109)) filled <- g3_fill_gaps(gappy) nrow(gappy) nrow(filled) filled |> dplyr::filter(inserted) |> dplyr::select(time, left_pupil, valid)
Converts the gaze direction of each eye to horizontal and vertical angles and adds the vergence angle between the two eyes.
g3_gaze_angles(gaze)g3_gaze_angles(gaze)
gaze |
Gaze data from |
The glasses report gaze direction as a unit vector in a coordinate system centred on the scene camera, where x points to the wearer's left, y up and z forward (Tobii Pro Glasses 3 Developer Guide). Angles are relative to the z axis, so (0, 0) is straight ahead of the glasses.
gaze with these columns added, in degrees:
Horizontal angle, positive to the wearer's right.
Vertical angle, positive up.
Angle between the left and right gaze directions. Larger values mean the eyes converge on a closer point.
Samples without a direction for an eye get NA. The result is a tibble,
and if gaze is a grouped tibble, it has the same groups.
gaze <- g3_gaze_angles(read_g3_gaze(g3_example())) gaze |> dplyr::select(left_azimuth, left_elevation, vergence) |> summary()gaze <- g3_gaze_angles(read_g3_gaze(g3_example())) gaze |> dplyr::select(left_azimuth, left_elevation, vergence) |> summary()
Reshapes the pupil columns of gaze data to one row per sample and eye, which suits plotting and mixed-effects models.
g3_pupil_long(gaze)g3_pupil_long(gaze)
gaze |
Gaze data from |
A tibble with the non-eye columns of gaze (such as recording,
time, pulse or epoch_time, if present), plus eye ("left" or
"right") and pupil. Groups of a grouped tibble are kept if their
columns are still in the result.
gaze <- read_g3_gaze(g3_example()) g3_pupil_long(gaze)gaze <- read_g3_gaze(g3_example()) g3_pupil_long(gaze)
Turns the sync port signal changes in the event data into one row per pulse, where a pulse runs from the signal going high (1) to it going low (0) again. With several recordings, pulses are numbered within each recording.
g3_syncport(events, direction = c("out", "in"))g3_syncport(events, direction = c("out", "in"))
events |
Event data from |
direction |
|
A tibble with columns recording (if events has one), pulse
(running number), onset, offset and duration (seconds). offset
is NA if the recording ended while the signal was high. Groups of a
grouped tibble are kept if their columns are still in the result.
events <- read_g3_events(g3_example()) g3_syncport(events)events <- read_g3_events(g3_example()) g3_syncport(events)
Searches a folder, such as the root of the Glasses 3 SD card, for recording folders.
list_g3_recordings(path, recursive = TRUE)list_g3_recordings(path, recursive = TRUE)
path |
Folder to search. |
recursive |
Search subfolders. |
A tibble with one row per recording: recording (the folder
name, as used in the recording column by the readers), path, name,
participant, created and duration. Pass it to read_g3_gaze(),
read_g3_imu() or read_g3_events() to read all recordings at once.
recordings <- list_g3_recordings(dirname(g3_example())) recordings read_g3_gaze(recordings)recordings <- list_g3_recordings(dirname(g3_example())) recordings read_g3_gaze(recordings)
Plots the 2D gaze point in scene camera coordinates, with the top of the
video frame at the top of the plot. The frame shows the edges of the scene
video, and gaze points outside it are left out. With several recordings in
x, each gets its own panel.
plot_g3_gaze( x, type = c("points", "density"), from = NULL, to = NULL, bins = 40 )plot_g3_gaze( x, type = c("points", "density"), from = NULL, to = NULL, bins = 40 )
x |
Gaze data from |
type |
|
from, to
|
Time window in seconds. Defaults to all the data. For epochs, the window is in seconds from the pulse onset. |
bins |
Number of bins along the horizontal axis when
|
A ggplot object.
rec <- read_g3(g3_example()) plot_g3_gaze(rec) plot_g3_gaze(rec, type = "density")rec <- read_g3(g3_example()) plot_g3_gaze(rec) plot_g3_gaze(rec, type = "density")
Draws pupil diameter for each eye over time, with sync port pulses as
shaded areas. With several recordings in x, each gets its own panel,
with its own time axis.
plot_g3_pupil( x, events = NULL, eyes = c("left", "right"), from = NULL, to = NULL, direction = c("out", "in"), smooth = NULL ) ## S3 method for class 'g3_recording' plot(x, ...)plot_g3_pupil( x, events = NULL, eyes = c("left", "right"), from = NULL, to = NULL, direction = c("out", "in"), smooth = NULL ) ## S3 method for class 'g3_recording' plot(x, ...)
x |
Gaze data from |
events |
Optional event data from |
eyes |
Which eyes to plot. |
from, to
|
Time window in seconds. Defaults to all the data. For epochs, the window is in seconds from the pulse onset. |
direction |
Sync port direction to show; see |
smooth |
Width in seconds of a running median drawn over the raw
trace, or |
... |
Passed to |
If x comes from g3_epochs(), the time axis is the time from the pulse
onset instead. Each eye gets its own panel, with a thin line for every
pulse and a thick line for the mean across pulses.
The eye colours and the theme are described in theme_g3().
A ggplot object. The plot() method for recordings from
read_g3() draws this plot and returns the recording invisibly.
rec <- read_g3(g3_example()) plot_g3_pupil(rec) plot_g3_pupil(rec$gaze, eyes = "left", from = 5, to = 15) plot_g3_pupil(rec, smooth = 1) epochs <- g3_epochs(rec$gaze, rec$events, before = 0.2, after = 1) plot_g3_pupil(epochs)rec <- read_g3(g3_example()) plot_g3_pupil(rec) plot_g3_pupil(rec$gaze, eyes = "left", from = 5, to = 15) plot_g3_pupil(rec, smooth = 1) epochs <- g3_epochs(rec$gaze, rec$events, before = 0.2, after = 1) plot_g3_pupil(epochs)
Reads a recording folder as written to the SD card by the Tobii Pro
Glasses 3. The folder contains recording.g3, gazedata.gz,
imudata.gz, eventdata.gz and a meta folder. The scene video is not
needed.
read_g3(path, data = c("gaze", "imu", "events"))read_g3(path, data = c("gaze", "imu", "events"))
path |
Path to a recording folder. |
data |
Which data streams to read. Any of |
read_g3() reads one recording. To read several recordings into one data
frame, give their paths to read_g3_gaze(), read_g3_imu() or
read_g3_events().
An object of class g3_recording: a list with elements info
(see read_g3_info()), gaze (see read_g3_gaze()), imu (see
read_g3_imu()) and events (see read_g3_events()). Streams not
requested are NULL.
list_g3_recordings() to find recordings on an SD card.
path <- g3_example() rec <- read_g3(path) rec summary(rec) rec$gaze plot(rec)path <- g3_example() rec <- read_g3(path) rec summary(rec) rec$gaze plot(rec)
Parses eventdata.gz, which holds sync port signals and any events sent
to the glasses through the API during the recording. Lines that cannot be
parsed are skipped with a warning.
read_g3_events(path)read_g3_events(path)
path |
Path to a recording folder or directly to an |
A tibble with columns recording (see read_g3_gaze()), time
(seconds since the start of the recording), type (for example
"syncport"), direction and value (for sync port events; NA
otherwise), and data, the event payload as a JSON string, so that other
event types are kept unchanged.
read_g3_events(g3_example())read_g3_events(g3_example())
Parses gazedata.gz into one row per sample. Samples where the glasses
detected no gaze are kept, with NA values, so that the time series stays
complete. Lines that cannot be parsed, such as the cut-off last line of an
incomplete file, are skipped with a warning; see g3_fill_gaps() to
replace them with empty rows. A file whose compressed data are damaged
cannot be read and gives an error.
read_g3_gaze(path)read_g3_gaze(path)
path |
Path to a recording folder or directly to a |
A tibble with columns:
Name of the recording folder. If two recordings in
path have folders of the same name, the full path is used instead.
Seconds since the start of the recording.
Gaze point in normalised scene camera coordinates, with (0, 0) at the top left of the video frame and (1, 1) at the bottom right.
Point where the gaze of the two eyes meets, in millimetres from the scene camera.
Position of each eye in millimetres from the scene camera, and its gaze direction as a unit vector.
Pupil diameter for each eye in millimetres, the unit given in the Tobii Pro Glasses 3 Developer Guide.
Whether the glasses reported data for that eye.
Whether the sample has a gaze point. The glasses can
estimate one from a single eye, so this can be TRUE when one eye is
invalid.
See the Tobii Pro Glasses 3 Developer Guide for the coordinate systems.
The glasses record gaze at 50 or 100 Hz, in the same file format. The rate is not stored in the recording, so functions that need it work it out from the timestamps.
gaze <- read_g3_gaze(g3_example()) gaze recordings <- list_g3_recordings(dirname(g3_example())) read_g3_gaze(recordings)gaze <- read_g3_gaze(g3_example()) gaze recordings <- list_g3_recordings(dirname(g3_example())) read_g3_gaze(recordings)
Parses imudata.gz. Accelerometer and gyroscope samples and magnetometer
samples are stored on separate lines at different rates, so each row has
NA for the sensors not sampled at that time. Lines that cannot be parsed
are skipped with a warning.
read_g3_imu(path)read_g3_imu(path)
path |
Path to a recording folder or directly to an |
A tibble with columns recording (see read_g3_gaze()), time
(seconds since the start of the recording), accel_x, accel_y,
accel_z (accelerometer), gyro_x, gyro_y, gyro_z (gyroscope) and
mag_x, mag_y, mag_z (magnetometer). Following the Tobii Pro
Glasses 3 Developer Guide, acceleration is in metres per second
squared, rotation in degrees per second and the magnetic field in
microtesla.
read_g3_imu(g3_example())read_g3_imu(g3_example())
Reads recording.g3 and the files in the meta folder.
read_g3_info(path)read_g3_info(path)
path |
Path to a recording folder. |
A list of class g3_info with these elements:
name and uuid of the recording
created, the start time (POSIXct, UTC), and timezone
duration in seconds
gaze_samples and gaze_valid_samples, as counted by the glasses
participant, as entered when recording
firmware version
recording_unit and head_unit serial numbers
files, the names of the data files
scene_camera, the camera calibration
meta, all files in the meta folder as character strings
read_g3_info(g3_example())read_g3_info(g3_example())
The ggplot2 theme used by all plots in the package, for giving your own
plots the same look. It builds on ggplot2::theme_minimal() with light
grey gridlines, grey axis text, the legend at the top left and bold
left-aligned panel titles on a white background.
theme_g3(base_size = 11)theme_g3(base_size = 11)
base_size |
Base font size in points. |
In the package plots, the left eye is drawn in slate blue (#2A568C) and
the right eye in Indian red (#EE6363, R's indianred2). The pair passes
checks for lightness, chroma, contrast against white and separation under
simulated protanopia, deuteranopia and tritanopia. Means use darker steps
of the same hues (#1D4371 and indianred3).
A ggplot2 theme.
library(ggplot2) gaze <- read_g3_gaze(g3_example()) ggplot(gaze, aes(time, left_pupil)) + geom_line(colour = "#2A568C", na.rm = TRUE) + theme_g3()library(ggplot2) gaze <- read_g3_gaze(g3_example()) ggplot(gaze, aes(time, left_pupil)) + geom_line(colour = "#2A568C", na.rm = TRUE) + theme_g3()