Package: glassesValidator
GlassesValidator v1.2.2Tool for automatic determination of data quality (accuracy and precision) of wearable eye tracker recordings.If you use this tool or any of the code in this repository, please cite:Niehorster, D.C., Hessels, R.S., Benjamins, J.S., Nyström, M. and Hooge, I.T.C. (2023). GlassesValidator:
A data quality tool for eye tracking glasses. Behavior Research Methods. doi: 10.3758/s13428-023-02105-5How to acquireGlassesValidator is available fromhttps://github.com/dcnieho/glassesValidator, and supports Python 3.10 and 3.11 on Windows, MacOS and Linux.For Windows users who wish to use the glassesValidator GUI, the easiest way to acquire glassesValidator is todownload
a standalone executable. The standalone executable is not
available for MacOS or Linux.For users on Windows, Mac or Linux who wish to use glassesValidator in their Python code, the easiest way to acquire
glassesValidator is to install it directly into your Python distribution using the commandpython -m pip install glassesValidator. Should that fail, this repository is pip-installable as well:python -m pip install git+https://github.com/dcnieho/glassesValidator.git#egg=glassesValidator. NB: on some platforms you may have
to replacepythonwithpython3in the above command lines.Once pip-installed in your Python distribution, there are three ways to run the GUI on any of the supported operating systems:Directly in the terminal of your operating system, typeglassesValidatorand run it.Open a Python console. From such a console, running the GUI requires only the following two lines of code:importglassesValidatorglassesValidator.GUI.run()If you run the glassesValidator's GUI from a script, make sure to wrap your script inif __name__=="__main__". This is required for correct operation from a script because the GUI uses multiprocessing functionality. Do as follows:if__name__=="__main__":importglassesValidatorglassesValidator.GUI.run()UsageThe glassesValidator validation procedure consists of two parts, 1) a poster and validation procedure that is used during a recording, and 2) Python software
for offline processing of the recording to estimate data quality measures. The glassesValidator package includes a graphical user interface (GUI)
that can be used to perform all processing. Below we describe an example workflow using the GUI. Advanced users can however opt to call all the GUI's
functionality directly from their own Python scripts without making use of the graphical user interface. The interested reader is referred to the glassesValidator
manual for further details regarding how to use the glassesValidator functionality directly from their own scripts.Workflow and example dataHere we first present an example workflow using the GUI. More detailed information aboutusing the GUI, orthe programming API, are provided
below.Before recording, the researcher printsthe posterincluded with glassesValidator on A2 paper. See the instructions inthe section about the
posterfor checking if the poster is printed correctly.Before recording, the researcher hangs the printed poster on a flat surface, such as a wall. Vertical positioning of the poster depends on the experiment
setting, but we think that a suitable default is to hang the poster such that the top row of fixation targets is at eye height for an average-length participant.The operator positions the participant in front of the glassesValidator poster. An easy method for positioning the participant is to ask them to stretch their
arm out straight forward and stand at a distance where their fist touches the poster. The operator then issues the following suggested instructions:Look at the nine fixation targets in reading order for one second each. Start with the top-left (red) target. When looking at the fixation targets, keep your head as still as possible, move only your eyes.These verbal instructions could be accompanied by pointing at the fixation targets in the desired looking order
to further help the participant to follow the instructions.To start calculating accuracy and precision, the researcher imports the recordings for which data quality should be determined into a glassesValidator project
(after anypreprocessing if required, for instance by drag-dropping a folder with recordings onto the
glassesValidator GUI window and selecting the import action.Once imported, the researcher indicates which episode(s) of each recording contain a validation using a graphical interface included with glassesValidator. When performing this step, a GUI appears for each recording, playing back the scene video with gaze overlaid. To code one or multiple validation intervals, do the following:The scene video will start playing automatically. You can perform action in the GUI using keypresses (make sure scene video GUI has focus so that the keypresses are received). All actions you can perform are listed by hovering your mouse over the(?)icon in the bottom right of the GUI.Seek in the video to the start of the validation interval. To skip forward one second in the video, pressL. For 10 seconds, pressshift+L. To go one or ten seconds backward in the video, pressHorshift+H.Pause playback, and use theJandKkeys to go forward and backward by one frame to precisely locate where the observer starts fixating the first validation target.PressFto mark this frame as the start of a validation interval.Seek in the video to the end of the validation interval. PressingPrestarts playback of the video. Once at the end of the validation interval, pause again and again useJandKto find the precise frame where the fixation on the last validation target ends.PressFto mark this frame as the end of a validation interval.If you have more validation intervals in the video, then seek further in the video to the next interval(s) and repeat the above actions to mark each.Once done, pressQto close the GUI.The recordings are then further processed automatically, and data quality is determined for validation episodes in the recording.Finally, once all recordings have been processed, the researcher exports the data quality measures from the recordings in the project into a summary Excel file.
This summary function can optionally average the data quality values over the fixation targets for each recording.Example recordings with which steps 4-7 can be practiced are included in theexample_data subfolder. This folder contains example recordings of a
participant executing the validation procedure with a Pupil Invisible and a Tobii Pro Glasses 2. You can import these recordings directly into glassesValidator.
Also included in each recordings subfolder is an exampleanalysisInterval.tsvfile for denoting where the validation interval is in the recording (step 5 above).
To use these files, after importing a recording into yourglassesValidator project(step 4 above), copy the correspondinganalysisInterval.tsvto the recording's folder in the glassesValidator project before running theCode validation intervalsaction.glassesValidator projectsThe glassesValidator GUI organizes recordings into a project folder. Each recording to be processed is imported into this project folder
and all further processing is done inside it. The source directories containing the original recordings remain untouched when running
glassesValidator. The glassesValidator project folder can furthermore contain a folder specifying the configuration of the project.
Such a configuration should be made if you used a poster different from the default (if no configuration folder is present, the default
settings are automatically used), and can be deployed with theDeploy configbutton in the GUI, or theglassesValidator.config.deploy_validation_config()call from Python.Eye trackersglassesValidator supports the following eye trackers:AdHawk MindLinkPupil CorePupil InvisiblePupil NeonSeeTrueSMI ETG 1 and ETG 2Tobii Pro Glasses 2Tobii Pro Glasses 3Pull requests or partial help implementing support for further wearable eye trackers are gladly received. To support a new eye tracker,
device support inglassesValidator.preprocessshould be implemented and the new eye tracker added to
theglassesValidator.utils.EyeTrackerEnum.Required preprocessing outside glassesValidatorFor some eye trackers, the recording delivered by the eye tracker's recording unit or software can be directly imported into
glassesValidator. Recordings from some other eye trackers however require some steps to be performed in the manufacturer's
software before they can be imported into glassesValidator. These are:Pupil Labs eye trackers: Recordings should either be preprocessed using Pupil Player (Pupil CoreandPupil Invisible) or exported
from Pupil Cloud (Pupil InvisibleandPupil Neon).Using Pupil Player (Pupil CoreandPupil Invisible): Each recording should 1) be opened in Pupil Player, and 2) an export of the
recording (ehotkey) should be run from pupil player. Make sure to disable theWorld Video Exporterin thePlugin Managerbefore exporting, as the exported video is not used by glassesValidator and takes a long time to create. Note that importing a Pupil
Player export of a Pupil Invisible export requires an internet connection, which is used to retrieve the scene camera calibration
from Pupil Lab's servers.Using Pupil Cloud (Pupil InvisibleandPupil Neon): Export the recordings using theTimeseries data + Scene videoaction.For thePupil Core, for best results you may wish to do a scene camera calibration yourself, seehttps://docs.pupil-labs.com/core/software/pupil-capture/#camera-intrinsics-estimation.
If you do not do so, a generic calibration will be used by Pupil Capture during data recording, by Pupil Player during data
analysis and by glassesValidator, which may result in incorrect accuracy values.SMI ETG: For SMI ETG recordings, access to BeGaze is required and the following steps should be performed:Export gaze data:Export->Legacy: Export Raw Data to File.In theGeneraltab, make sure you select the following:Channel: enable both eyesPoints of Regard (POR): enableGaze position,Eye position,Gaze vectorBinocular: enableGaze positionMisc Data: enableFrame counterdisable everything elseIn the Details tab, set:Decimal placesto 4Decimal separatortopointSeparatortoTabenableSingle file outputThis will create a text file with a name like<experiment name>_<participant name>_<number> Samples.txt(e.g.005-[5b82a133-6901-4e46-90bc-2a5e6f6c6ea9]_005_001 Samples.txt). Move this file/these files to the
recordings folder and rename them. If, for instance, the folder contains the files005-2-recording.avi,005-2-recording.idfand005-2-recording.wav, amongst others, for the recording you want to process,
rename the exported samples text file to005-2-recording.txt.Export the scene video:On the Dashboard, double click the scene video of the recording you want to export to open it in the scanpath tool.Right click on the video and select settings. Make the following settings in theCursortab:setGaze cursortotranslucent dotsetLine widthto 1setSizeto 1Then export the video,Export->Export Scan Path Video. In the options dialogue, make the following settings:setVideo Sizeto the maximum (e.g.(1280,960)in my case)setFrames per secondto the framerate of the scene camera (24 in my case)setEncodertoPerformance [FFmpeg]setQualitytoHighsetPlayback speedto100%disableApply watermarkenableExport stimulus audiofinally, clickSave as, navigate to the folder containing the recording, and name it in the same format as the
gaze data export file we created above but replacingrecordingwithexport, e.g.005-2-export.avi.The posterThe default poster is available 1)here, 2) from the GUI with theGet poster pdfbutton, and 3) can also be acquired from a Python script by callingglassesValidator.config.poster.deploy_default_pdf().
The default poster should be printed at A2 size, as defined
in the pdf file, and is designed to cover a reasonable field of view when participants view it at armslength (i.e., 20 x 17.5 deg
at 60 cm). In order to check that the poster was printed at the correct scale, one should measure the sides of the ArUco markers.
We strongly recommend performing this check because printers may not be calibrated. In the case of the default glassesValidator
poster, the distance between the left side of the left-most column of ArUco markers and the right side of the right-most column of
ArUco markers should be 35.6 cm (each ArUco marker should have sides that are 4.19 cm long). If the poster was printed at the wrong
scale, one must adapt the glassesValidator configuration to match the size and position of the ArUco markers and fixation targets
on your poster (see "Customizing the poster" below).Customizing the posterThe poster pdf file is generated by theLaTeX file in the same folder as the pdf.
Its looks are defined in the files in theconfig folder. As described above, this configuration can be
deployed and then edited. The edited configuration can both be used to generate a new poster with LaTeX and for performing the
data quality calculations.
Specifically, the filesmarkerPositions.csvandtargetPositions.csvdefine where the ArUco markers and fixation targets
(respectively) are placed on the poster. Each coordinate in these files is for the center of the marker or gaze target and the origin
(0,0) is in the bottom left of the poster. ThevalidationSetup.txtconfiguration filecontains the following settings for the poster:settingdefaultvaluedescriptiondistance60Viewing distance in cm, used to convert coordinates and sizes in degrees to cm. Only used whenmodeisdeg.modecmcmordeg. Sets the unit for themarkerSideandtargetDiameterbelow as well as for interpreting the coordinates in the marker and target position files.markerSide4.18945Size of ArUco markers. In cm or deg, seemodesetting.markerPosFilemarkerPositions.csvFile in the config folder where the markers to draw are specified.targetPosFiletargetPositions.csvFile in the config folder where the targets to draw are specified.targetTypeThalerType of targer to draw, can beTobii(the calibration marker used by Tobii) orThaler(layout ABC in the lower panel of Fig. 1 inThaler et al., 2013).targetDiameter1.04736Diameter of the gaze target. In cm or deg, seemodesetting. Ignored iftargetTypeisTobiianduseExactTobiiSizeis1.useExactTobiiSize00or1. If1, the gaze targets have the exact dimensions of a Tobii calibration marker (though possibly different colors). I.e., thetargetDiameterparameter is ignored. Only used iftargetTypeisTobii.showGrid00or1. If1, agridColsxgridRowsgrid is drawn behind the markers and gaze targets. The size of each grid cell is 1 cm ifmodeis cm, or 1 degree ifmodeisdeg.gridCols35.6102Number of grid columns to draw ifshowGridis1.gridRows30.3734Number of grid rows to draw ifshowGridis1.showAnnotations00or1. If1, text annotations informing about the size of grid cells and markers is printed on the poster below the marker arrangement.markerBorderBits1Setting for border thickness of ArUco markers. Used by the glassesValidator tool when deploying a configuration andglassesValidator.config.poster.deploy_marker_images()function for generating the marker images that are placed on the poster by theposter generation LaTeX file. Also used when detecting ArUco markers during recording processing.To check your custom configuration, you can generate a poster pdf usingthe steps below. Furthermore,
a png image showing the poster will be generated in the configuration folder when any of glassesValidator's processing steps are run.The above settings are furthermore used by glassesValidator when processing recordings. For instance, thedistanceparameter is
used as the assumed viewing distance when computing theviewpos_vidpos_homographydata quality type (seethe discussion in the
Advanced settings section below). Three further settings are present in thevalidationSetup.txtconfiguration
filethat are only used by the glassesValidator processing tool, and not for the poster:settingdefaultvaluedescriptionminNumMarkers3During recording processing, minimum number of detected markers required to perform estimation of homography transformation and camera pose estimation.centerTarget5The ID of the fixation target (in thetargetPosFilefile) that is the origin of the poster. The center of this marker will be (0,0) in the poster coordinate system.referencePosterWidth1920Width (in pixels) of the poster png image generated by the glassesValidator tool and stored in the config directory when loading a configuration.Steps for making your own posterDeploy the default configuration using theDeploy configbutton in the GUI, or theglassesValidator.config.deploy_validation_config()call from Python.Edit thevalidationSetup.txtconfiguration file and themarkerPositions.csvandtargetPositions.csvfiles in the
configuration folder to design the layout and look of the poster that you want. NB: if you edit themarkerBorderBitsvariable, you have to run theglassesValidator.config.poster.deploy_marker_images()to regenerate the marker images
contained in theall-markerswith the new border setting.Compile themarkerBoard/board.texLaTeX file withpdfTex, such as provided in theTeX Live
distribution.Done, you should now have a pdf file with the poster as you defined.The GUIClick the screenshot to see a full-size version.The simplest way to use glassesValidator is by means of its GUI, see above. The full workflow can be performed in the GUI.
Specifically, it supports:GlassesValidator project management, such as making new projects or opening them.Importing recordings into a glassesValidator project. Recordings can be found by glassesValidator by drag-dropping one or multiple
directories onto the GUI or by clicking theAdd recordingsbutton (not shown) and selecting one or multiple directories. The
selected directories and all their subdirectories are then searched for recordings, and the user can select which of the found
recordings should be added to the glassesValidator import. Once listed in the GUI, the import action can then be started, which
copies over data from the selected recording to the glassesValidator project folder, and transforms it to a common format.Showing a listing of the recordings in the project and several properties about them, where available. these properties currently
are:Eye tracker type (e.g. Pupil Invisible or Tobii Glasses 2)Status, indicating whether a recording has been imported, coded, analyzed)Recording nameParticipant nameProject nameRecording durationRecording start timeWorking directory for the recording inside the glassesValidator projectOriginal source directory from which the recording was importedFirmware versionGlasses serial numberRecording unit serial numberRecording software versionScene camera serial numberThe GUI can be configured to show any combination of these columns in any order, and the listing can be sorted by any of these
columns. The listing can furthermore be filtered to show only a subset of recordings by search string, eye tracker type and
status.Annotating recordings to indicate the episode(s) in the recording that contain a validation using a separate GUI.Calculating data quality (accuracy and precision) for recordings.Exporting the data quality values of multiple recordings to a summary tab-separated spreadsheet file.Deploying the default configuration to a glassesValidator project so that it can be edited (see "Customizing the poster"
above).Advanced settingsSeveral advanced settings can be made in the right bar of the glassesValidator GUI. For standard use, these are not of interest.
Each setting is explained by means of a help text that pops up when hovering over the setting. Nonetheless, the specific group
of advanced settings for configuring what type of data quality to compute is discussed here in more detail.glassesValidator can compute data quality in multiple ways. When deciding how to determine accuracy and precision, several
decisions have to be made. By default the most appropriate decisions for standard use are selected and most users can skip this
section, but another configuration might be more suited for some advanced use cases. The following decisions are made:Determining location of the participant:The researcher can assume a fixed viewing distance and provide this to glassesValidator in the project configuration. In
this mode, it is assumed that the eye is located exactly in front of the center of the poster and that the poster is
oriented perpendicularly to the line of sight from this assumed viewing position.If the scene camera is calibrated (i.e. its properties such as focal length and distortion parameters have been estimated
by a calibration procedure), it is possible to use the array of ArUco markers to estimate the position of the participant
relative to the poster at each time point during a validation.When a scene camera calibration is available, glassesValidator will by default use mode ii, otherwise mode i will be used.
Five of the six wearable eye trackers supported by glassesValidator provide the calibration of their scene camera, and
glassesValidator will by default use this calibration for these eye trackers (mode ii). Currently, only the SeeTrue does not
provide a camera calibration, and glassesValidator therefore by default uses an assumed fixed viewing distance for this eye
tracker.Transforming gaze positions from the scene camera reference frame to positions on the validation poster:Performed by means of homography.Performed using recovered camera pose and gaze direction vector, by means of intersection of gaze vector with the validation
poster plane.Mode ii is used by default. However, like for decision 1, mode ii requires that a camera calibration is available. If a camera
calibration is not available, mode i will be used instead.Which data is used for determining gaze position on the validation poster:The gaze position in the scene camera image.The gaze position in the world (often binocular gaze point).Gaze direction vectors in a head reference frame.When operating in mode i, the eye tracker's estimate of the (binocular) gaze point in the scene camera image is used. This is
the appropriate choice for most wearable eye tracking research, as it is this gaze point that is normally used for further
analysis. However, in some settings and when the eye tracker provides a (3D) gaze position in the world and/or gaze direction
vectors for the individual eyes along with their origin, a different mode of operation may be more appropriate. Specifically,
when using the wearable eye tracker's world gaze point or gaze vectors instead of the gaze point in the scene video in their
analysis, the researcher should compute the accuracy and precision of this world gaze point/gaze vectors. NB: for most of the
currently supported eye trackers, modes i and ii are equivalent (i.e., the gaze position in the camera image is simply the
gaze position in the world projected to the camera image). This is however not always the case. The AdHawk MindLink for instance
has an operating mode that corrects for parallax error in the projected gaze point using the vergence signal, which leads to
the eye tracker reporting a different gaze position in the scene video than a direct projection of gaze position in the world
to the scene camera image.Altogether, combining these decisions, the following seven types of data quality can be calculated using glassesValidator. NB: All API
names are members of theenum.EnumglassesValidator.process.DataQualityTypeName in GUIName in APIdescriptionHomography + view distanceviewpos_vidpos_homographyUse a homography tranformation to map gaze position from the scene video to the validation poster, and use an assumed viewing distance (see the project's configuration) to compute data quality measures in degrees with respect to the scene camera. In this mode, it is assumed that the eye is located exactly in front of the center of the poster and that the poster is oriented perpendicularly to the line of sight from this assumed viewing position.Default mode when no camera calibration is available.Homography + posepose_vidpos_homographyUse a homography tranformation to map gaze position from the scene video to the validation poster, and use the determined pose of the scene camera (requires a calibrated camera) to compute data quality measures in degrees with respect to the scene camera.Video ray + posepose_vidpos_rayUse camera calibration to turn gaze position from the scene video into a direction vector, and determine gaze position on the validation poster by intersecting this vector with the poster. Then, use the determined pose of the scene camera (requires a calibrated camera) to compute data quality measures in degrees. If the eye tracker provides a 3D gaze point (e.g. the Tobii Pro Glasses 2 and 3), this 3D gaze point is used in lieu of a gaze direction vector derived from the gaze position in the scene camera with respect to the scene camera.Default mode when a camera calibration is available.World gaze position + posepose_world_eyeUse the gaze position in the world provided by the eye tracker (often a binocular gaze point) to determine gaze position on the validation poster by turning it into a direction vector with respect to the scene camera and intersecting this vector with the poster. Then, use the determined pose of the scene camera (requires a calibrated camera) to compute data quality measures in degrees with respect to the scene camera.Left eye ray + posepose_left_eyeUse the gaze direction vector for the left eye provided by the eye tracker to determine gaze position on the validation poster by intersecting this vector with the poster. Then, use the determined pose of the scene camera (requires a camera calibration) to compute data quality measures in degrees with respect to the left eye.Right eye ray + posepose_right_eyeUse the gaze direction vector for the right eye provided by the eye tracker to determine gaze position on the validation poster by intersecting this vector with the poster. Then, use the determined pose of the scene camera (requires a camera calibration) to compute data quality measures in degrees with respect to the right eye.Average eye rays + posepose_left_right_avgFor each time point, take angular offset between the left and right gaze positions and the fixation target and average them to compute data quality measures in degrees. Requires 'Left eye ray + pose' and 'Right eye ray + pose' to be enabledIn summary,by defaultfor eye trackers for which a camera calibration is available the gaze position in the scene camera is
transformed to a gaze position on the validation poster by means of intersecting a camera-relative gaze direction vector with the
validation poster plane. Accuracy and precision are then computed using the angle between the vectors from the scene camera to the
fixation target and to the gaze position on the poster (glassesValidator.process.DataQualityType.pose_vidpos_ray). For eye trackers
for which no camera calibration is available, a homography transformation is used to determine gaze position on the poster and accuracy
and precision are computed using an assumed viewing distance configured in the glassesValidator project's configuration file, along
with the assumptions that the eye is located exactly in front of the center of the poster and that the poster is oriented perpendicularly
to the line of sight (glassesValidator.process.DataQualityType.viewpos_vidpos_homography). As discussed in the "Assuming a fixed
viewing distance" section of the glassesValidator paper (Niehorster et al., 2023), differences in computed values between these two
modes are generally small. Nonetheless, it is up to the researcher to decide whether the level of error introduced when operating
without a camera calibration is acceptable and whether they should perform their own camera calibration.Matching gaze data to fixation targetsThis section discusses how to decide which part of the gaze data constitutes a fixation on each of the fixation targets.
By default, to associate gaze data with fixation targets, glassesValidator first uses theI2MC fixation
classifierto classify the fixations in the gaze position data on the poster.
Then, for each fixation target, the nearest fixation in poster-space that is at least 50 ms long is selected from all the classified
fixations during the validation procedure. This matching is done in such a way that no fixation is matched to more than one fixation
target.The matching between fixations and fixation targets produced by this procedure is stored in a fileanalysisInterval.tsvin each
recording's directory in the glassesValidator project. The advanced user can provide their own matching by changing the contents of
this file.Coordinate system of dataGaze data in poster space in thegazePosterPos.tsvfile of a processed recording has its origin (0,0) at the center of the position
of the fixation target that was indicated to be the center target with thecenterTargetsetting in thevalidationSetup.txtconfiguration file. The positive x-axis points to the right and the positive y-axis
downward, which means that (-,-) coordinates are to the left and above of the poster origin, and (+,+) to the right and below.Angular accuracy values in thedataQuality.tsvfile of a processed recording use the same sign-coding as the gaze data in poster space.
That is, for the horizontal component of reported accuracy values, positive means gaze is to the right of the fixation target and
negative to the left. For the vertical component, positive means gaze is below the fixation target, and negative that it is above the
fixation target.APIAll of glassesValidator's functionality is exposed through its API. Below are all functions that are part of the
public API. Many functions share common input arguments. These are documentedhereand linked to in the API
overview below.glassesValidator.configfunctioninputsdescriptionget_validation_setup()config_dirsetup_file: filename of the validation setup file. DefaultvalidationSetup.txt.Read and parse the validation setup into a dict. If noconfig_diris provided, the default configuration is returned.get_targets()config_dirfile: filename of the target positions file. DefaulttargetPositions.csv.Read and parse the target positions file into apandas.DataFrame. If noconfig_diris provided, the target positions are returned.get_markers()config_dirfile: filename of the marker positions file. DefaultmarkerPositions.csv.Read and parse the marker positions file into apandas.DataFrame. If noconfig_diris provided, the marker positions are returned.deploy_validation_config()output_dir: Directory to deploy configuration files to.Deploy the default configuration (including poster maker, seeglassesValidator.config.poster.deploy_maker()) to the specified directory.glassesValidator.config.posterfunctioninputsdescriptiondeploy_maker()output_dir: Directory to deploy poster maker LaTeX files to.Deploy the LaTeX file for making posters (including marker images, seeglassesValidator.config.poster.deploy_marker_images()) to the specified directory.deploy_marker_images()output_dir: Directory to deploy marker images for use with the LaTeX poster maker to.Deploy the marker images (all fiducial markers incv2.aruco.DICT_4X4_250) to the specified directory.deploy_default_pdf()output_file_or_dir: Path where to store default poster pdf. If provided path is a directory and not a file, the poster is stored asposter.pdfin the provided directory.Deploy the default poster pdf to the specified path.glassesValidator.GUIfunctioninputsdescriptionrun()project_dir: Path to glassesValidator project to open.Open the glassesValidator GUI.glassesValidator.preprocessfunctioninputsdescriptionget_recording_info()source_dirdevice:glassesValidator.utils.EyeTrackerDetermine if provided path contains a recording/recordings made with the specified eye tracker (device) and if so, get info about these recordings.do_import()output_dirsource_dirdevice:glassesValidator.utils.EyeTrackerrec_infoImport the specified recording to a subdirectory ofoutput_dir. Eitherdeviceorrec_infomust be specified. Does nothing if directory does not contain a recording made with the specified eye tracker.adhawk_mindlink()output_dirsource_dirrec_infoImport an AdHawk MindLink recording to a subdirectory ofoutput_dir. Does nothing if directory does not contain an AdHawk MindLink recording.rec_infois optional.pupil_core()output_dirsource_dirrec_infoImport a Pupil Core recording to a subdirectory ofoutput_dir. Does nothing if directory does not contain a Pupil Core recording.rec_infois optional.pupil_invisible()output_dirsource_dirrec_infoImport a Pupil Invisible recording to a subdirectory ofoutput_dir. Does nothing if directory does not contain a Pupil Invisible recording.rec_infois optional.pupil_neon()output_dirsource_dirrec_infoImport a Pupil Neon recording to a subdirectory ofoutput_dir. Does nothing if directory does not contain a Pupil Neon recording.rec_infois optional.SeeTrue()output_dirsource_dirrec_infocam_cal_file: OpenCV XML file containing a camera calibration to be used when processing this recording. Optional.Import a SeeTrue recording to a subdirectory ofoutput_dir. Does nothing if directory does not contain a SeeTrue recording.rec_infois optional.SMI_ETG()output_dirsource_dirrec_infoImport a SMI ETG recording to a subdirectory ofoutput_dir. Does nothing if directory does not contain a SMI ETG 1 or 2 recording.rec_infois optional.tobii_G2()output_dirsource_dirrec_infoImport a Tobii Pro Glasses 2 recording to a subdirectory ofoutput_dir. Does nothing if directory does not contain a Tobii Pro Glasses 2 recording.rec_infois optional.tobii_G3()output_dirsource_dirrec_infoImport a Tobii Pro Glasses 3 recording to a subdirectory ofoutput_dir. Does nothing if directory does not contain a Tobii Pro Glasses 3 recording.rec_infois optional.glassesValidator.processfunctioninputs/membersdescriptiondo_coding()working_dirconfig_dirShow GUI for indicating which episode(s) in the recording contain a validation. Simplified alias ofglassesValidator.process.code_marker_interval().do_process()working_dirconfig_dirPerform all steps to compute data quality for a recording for which the validation episodes have been coded. Use the below functions instead for granular control over which steps are run.export_data_qualityrec_dirs: list of recording directories (glassesValidatorworking_dirs) that contain a data quality file and are to be included in the summary file.output_file_or_dir: Path where to store the summary file. If provided path is a directory and not a file, the summary file is stored asdataQuality.tsvin the provided directory.dq_types: list ofglassesValidator.process.DataQualityTypes to include in the export (if available). If not provided, a suitable default is chosen.targets: list of targets to include in the export (and optionally average over). If not provided, all targets are included.average_over_targets: ifTrue, all measured are averaged over the targets listed intargets, providing one value per validation episode.include_data_loss: ifTrue, data loss is also included among the computed data quality metrics (if available).Note howeverthat this data loss is computed during the episode selected for each fixation target on the validation poster. This isNOTthe data loss of the whole recording and thus not what you want to report in your paper.Export the data quality values of multiple recordings to a summary tab-separated spreadsheet file.code_marker_interval()working_dirconfig_dirshow_poster: ifTrue, also show poster with gaze overlaid on it in a second viewer.Show GUI for indicating which episode(s) of each recording contain a validation.detect_markers()working_dirconfig_dirshow_visualization: ifTrue, each frame is shown in a viewer, overlaid with info about detected markers and poster.show_rejected_markers: ifTrue, rejected ArUco marker candidates are also shown in the viewer.Detect ArUco markers on the poster in the scene video and determine camera pose with respect to the scene camera (if scene camera is calibrated) and homography to transform between scene camera and poster coordinates.gaze_to_poster()working_dirconfig_dirshow_visualization: ifTrue, each frame is shown in a viewer, overlaid with info about detected markers and poster.show_poster: ifTrue, gaze in poster space is also shown in a separate viewer.show_only_intervals: ifTrue, only the coded validation episodes (if available) are shown in the viewer while the rest of the scene video is skipped past.Transform gaze data in scene camera reference frame to positions on the poster.compute_offsets_to_targets()working_dirconfig_dirCompute offsets from each gaze sample to each target.determine_fixation_intervals()working_dirdo_global_shift: IfTrue, for each validation interval the mean position will be removed from the gaze data and the targets, removing any overall shift of the data. This improves the matching of fixations to targets when there is a significant overall offset in the data. It may fail (backfire) if there are data samples far outside the range of the validation targets, or if there is no data for some targets.max_dist_fac: Factor for determining distance limit when assigning fixation points to validation targets. If for a given target the closest fixation point is further away than<factor>*[minimum intertarget distance], then no fixation point will be assigned to this target, i.e., it will not be matched to any fixation point. Set to a large value to essentially disable.config_dirAutomatically determine usingI2MCwhich episodes during the validation constitute looks to each fixation target.calculate_data_quality()working_dirdq_types:listofglassesValidator.process.DataQualityTypes to compute.allow_dq_fallback: ifTrue, fall back to most suitable data quality type if none of the types requested indq_typesare available. If False, aRuntimeErrorerror is raised instead.include_data_loss: ifTrue, data loss is also included among the computed data quality metrics.Note howeverthat this data loss is computed during the episode selected for each fixation target on the validation poster. This isNOTthe data loss of the whole recording and thus not what you want to report in your paper.Compute data quality for all fixation targets.DataQualityTypeenum.EnumDataQualityType.viewpos_vidpos_homographyDataQualityType.pose_vidpos_homographyDataQualityType.pose_vidpos_rayDataQualityType.pose_world_eyeDataQualityType.pose_left_eyeDataQualityType.pose_right_eyeDataQualityType.pose_left_right_avgSeeAdvanced settings section in The GUI sectionabove.glassesValidator.utilsfunctioninputs/membersdescriptionmake_video()working_dirconfig_dirshow_rejected_markers: ifTrue, rejected ArUco marker candidates are also drawn on the video.add_audio_to_poster_video: ifTrue, audio is added to poster video, not only to the scene video.show_visualization: ifTrue, the generated video is shown as it is created in a viewer.Export annotated scene video showing gaze, detected ArUco markers and detected poster. Also exports a video showing gaze on the poster.EyeTrackerenum.EnumEyeTracker.Pupil_CoreEyeTracker.Pupil_InvisibleEyeTracker.Pupil_NeonEyeTracker.SMI_ETGEyeTracker.SeeTrueEyeTracker.Tobii_Glasses_2EyeTracker.Tobii_Glasses_3Recordingdataclasses.dataclassRecording.nameRecording.source_directoryRecording.proc_directory_nameRecording.start_timeRecording.durationRecording.eye_tracker:glassesValidator.utils.EyeTrackerRecording.projectRecording.participantRecording.firmware_versionRecording.glasses_serialRecording.recording_unit_serialRecording.recording_software_versionRecording.scene_camera_serialRecording.id(internal to GUI)Recording.task(internal to GUI)Information about a recordingCommon input argumentsargumentmodule(s)descriptionconfig_dirglassesValidator.configglassesValidator.processglassesValidator.utilsPath to directory containing a glassesValidator setup. IfNone, the default setup is used.source_dirglassesValidator.preprocessPath to directory containing one (or for some eye trackers potentially multiple) eye tracker recording(s) as stored by the eye tracker's recording hardware or software.output_dirglassesValidator.preprocessPath to the directory to which recordings will be imported. Each recording will be placed in a subdirectory of the specified path.working_dirglassesValidator.processglassesValidator.utilsPath to a glassesValidator recording directory.rec_infoglassesValidator.preprocessRecording info (glassesValidator.utils.Recording) or list of recording info specifying what is expected to be found in the specifiedsource_dir, so that this does not have to be rediscovered and changes can be made e.g. to the recording name that is used for auto-generating the recording'sworking_dir, or even directly specifying theworking_dirby filling theproc_directory_namefield before import.