Calibration with TRACKPixx3
This project introduces the notion of project-based eye-tracker settings and customized calibration procedures.
Thank you for your interest in LabMaestro! The page you are trying to access is under development. We are working on comprehensive documentation to help you make the most of our software. If you require any help, please feel free to contact us via email at support@vpixx.com.
This template project was developed for the features available in LabMaestro 1.7.0 and assumes that the operator controls progression with a keyboard. This documentation also assumes that the installation of the TRACKPixx3 has been completed according to the relevant TRACKPIxx3 installation guide, that users are familiar with the Principles of TRACKPixx3 operation, and have setup their TRACKPixx3 from the Setup TRACKPixx3interface.
Download the latest template project for your LabMaestro version and open it from LabMaestro.
LabMaestro 1.6.0: TPxCalibration_TPx3_V1.lm
LabMaestro 1.7.0: TPxCalibration_TPx3_1_7_0_V1.lm
Navigate to theEnvironment from the Project Panel.
Confirm that the DATAPixx3 and TRACKPixx3 are detected and added to the project. Refer to Adding VPixx Hardware to a project for more information.
Adjust Required Project Device Settings
Once the demo project is open, navigate to theEnvironment from the Project Panel.
Confirm that the DATAPixx3 and TRACKPixx3 are detected and added to the project. Refer to Adding VPixx Hardware to a project for more information.
Understanding the Template Project Structure
The project Experiment Design is structured in two phases, implemented as two consecutiveTimelines. First, the TRACKPixx3Calibration timeline executes a customized calibration sequence and outputs some feedback about the overall accuracy of the calibration. Then, the RecordTrackerSample timeline displays real-time feedback about the overall accuracy of the calibration, and concurrently records eye tracking data for subsequent inspection.
![image-20240522-174841.png](../__attachments/41844737/image-20240522-174841.png?inst-v=6becaa68-8f40-4e9a-8aef-85bf0173396e)
Screenshot from LabMaestro 1.7.0.
TRACKPixx3Calibration Timeline
When clicking on a timeline from the project panel, a timeline tab will open, displaying the Epochs. and a preview of the visual content of the screen.
![image-20240522-175202.png](../__attachments/41844737/image-20240522-175202.png?inst-v=6becaa68-8f40-4e9a-8aef-85bf0173396e)
Screenshot from LabMaestro 1.7.0
Warning: In LabMaestro Public Beta 1 through LabMaestro 1.7, when first opening a *.lm file, the preview may not be immediately refreshed. This may occur when property fields contain Expressions, or references to custom variables defined within the property panel of Timelines. To refresh the preview, without executing the entire experiment, click on Play Timeline. Note that variables defined by Methods may have a preview option available from their own method tab.
The WelcomeScreenEpoch constructs a summary of useful information that will be used in the timeline.
![image-20240522-175618.png](../__attachments/41844737/image-20240522-175618.png?inst-v=6becaa68-8f40-4e9a-8aef-85bf0173396e)
Screenshot from LabMaestro 1.7.0.
a. RefRectangle: A 1 cm x 1 xm square drawn to scale using the Displays characteristics.
b. Acceptable threshold: A circle that provides visual feedback about the acceptable threshold currently defined in the Calibrate Tracker command. In LabMaestro Public Beta 1.6.0 through LabMaestro 1.7, this value is specified in screen-space pixels, and the default value may need to be adjusted for the viewing distance layout and accuracy criterion. In this version, the default acceptable threshold is 55 pixels, which corresponds to 1 degree of viewing angle at 57.3 cm.
c.Ref1dva and Refhalfdva : Circles with a diameter measuring 1 and 0.5 degrees of visual angle, drawn to scale using the Displays. The unit type can be toggled between degrees and pixels, from the property panel. This information should be used to adjust the acceptable threshold in the Calibration Command as desired.
d. Operator information: Summarizes the keyboard keys that will be functional in this template project, and their effect. Remember that it possible to press the Esc key at any time during a Play Timeline or Launch Experiment to force quit.
Progression in the timeline is paused until either the Space or Q keys are pressed.
After one of the valid keys are pressed, the Conditional Branch evaluates if the ‘Space’ key has been pressed, that the timeline will proceed rightward to the CalibrationEpoch, else, the timeline proceeds to SkipCalibEpoch.
In CalibrationEpoch, the customized calibration for the project in TRACKPixx3 calibration is implemented through the Calibrate Tracker command. Progression through the timeline is paused until calibration has completed.
Note on Failure Prompt
In LabMaestro Public Beta 1.7.0, if the calibration fails, the LabMaestro interface will temporarily return to the foreground, and a Calibration Failed dialog box reporting Euclidian distance to each target will appear, reporting diagnostic information about the calibration results. See Calibrate Tracker : Failure Prompt, for more details about this screen.
![image-20240418-152415.png](../__attachments/41844737/image-20240418-152415.png?inst-v=6becaa68-8f40-4e9a-8aef-85bf0173396e)
Example failure prompt dialog box which opens if calibration has failed. The columns of the Details data are, in order: Calibration target ID (n-1), left eye offset, and right eye offset. Screen capture taken from an example failed 5-point calibration, in LabMaestro 1.7.0.
When a valid calibration has been reached, or when clicking Continue from the Calibration Failed dialog box, the experiment view will continue on to the FeedbackEpoch, where the acceptable average offset with be reported, alongside with the calculated average offset for the eyes selected on the Setup TRACKPixx3 page.
RecordTrackerSample Timeline
When opening the RecordTrackerSample timeline, a short example on how to use an eye tracker recording schedule within a timeline will be displayed. This implementation is representative of expected implementations in experiments driven by Methods. In the context of this project, this timeline serves to generate a single eye tracking recording which can be examined with LabMaestro’sRecordings and Built-In Data Visualization. You can also use Data Export to obtain data files which can be manipulated and analyzed in other software.
The timeline is divided in three Epochs:
![](../__attachments/41844737/image-20231127-185744.png?inst-v=6becaa68-8f40-4e9a-8aef-85bf0173396e)
The InstructionEpoch contains the instructions which will be shown to the user, and will initiate an eye tracker recording schedule immediately after the spacebar has been pressed.
The StimulusEpoch will display a gaze follower that shows the average position of the left and right eyes. Five reference dots, each measuring one degree of visual angle, will displayed one at a time. The location of the reference dot will be updated every time the user presses the spacebar, using Set Variables commands. The (x,y) coordinates of the dot centers, in pixels, have been set to : (0,0), (-350, 350), (350, 350), (-350, -350), and (350, -350).
Finally, QuitEpoch stops the recording schedule, and displays a message reminding users that the recording will be found in the project panel, after the experiment has concluded.
To evaluate the quality of the recording, we recommend that users modify the details of the stimuli to match task requirements. For example, some may prefer to: display static Regions and instructing participants to specific locations; include a Picture Patternrepresentative of experiment stimuli; or use Expressions to implement a simple gaze control routine.
Launching the Experiment and Reviewing the Session Data
Click ‘Launch Experiment’ to see the project in action.
After the experiment session has concluded, use the Recordings and Built-In Data Visualization to see a summary of the data. Navigate to the session’s *.trk recording file.
By default, raw gaze data from each eye will be displayed: inspect whether the left and right eye traces are sufficiently close to the reference dot centers for the task requirements.
![](../__attachments/41844737/image-20231128-173246.png?inst-v=6becaa68-8f40-4e9a-8aef-85bf0173396e)
As a reminder, these locations are (0,0), (-350, 350), (350, 350), (-350, -350), and (350, -350).
The following data visualization presets present complementary detailed gaze information:
Left X vs Y (flagged) and Right X vs Y (flagged): Show gaze location, colour-coded for online-generated fixations and saccades. These views allow rapid evaluation of the suitability of online-flagged fixations and saccades thresholds.
![](../__attachments/41844737/image-20231128-173340.png?inst-v=6becaa68-8f40-4e9a-8aef-85bf0173396e)
Left Velocity and Right Velocity: Show the left or right eye velocity in degrees of visual angle over time, colour-coded for online-generated fixations and saccades. These views facilitate the choice of new fixation and saccade thresholds, if desired.
![](../__attachments/41844737/image-20231128-174049.png?inst-v=6becaa68-8f40-4e9a-8aef-85bf0173396e)