Skip to main content
Skip table of contents

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.

Adjust Required Project Device Settings

Legacy instructions for LabMaestro 1.6.0
  • Click on the DATAPixx3, and examine the required Values associated with this template project. Click on Apply All to push the project’s required device values to the connected device, replacing the Current Values. Mismatching required and current project values are identified in red.

  • Click on the TRACKPixx3, and examine the project’s Required Values. Several values must be adjusted to ensure they conform with the device’s installation.

  • Distance: The distance, in cm, between the TRACKPixx3 camera and the eyes of the participant. In tabletop TRACKPixx3 setups, this distance is typically 60 cm.

  • Iris Expected Size: The diameter, in pixels, of the participant’s fixed iris size. Values between 140 and 160 are typical at a 60 cm tracking distance. Suitability of this value can be visually inspected from the TRACKPixx3’s Setup interface.

  • On this template project, online fixation and saccade detection thresholds were respectively set for gaze velocities below 30 dva/s for 5 ms and gaze velocity above 30 dva/s for 5 ms.

  • Save the project, and click on Apply All before continuing to the next step.

  • Finally, associate an active display to the project, and ensure that it is the Main Display. Measure and adjust the viewing distance, in centimeters. Refer to Displays for more information.

  • The TRACKPixx3 must be installed underneath this display. The TRACKPixx3 will only track gaze on this screen.

  • Save the project before continuing. The viewing distance will automatically be taken into account.

  • 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.

  • Click on the DATAPixx3, from the DATAPixx device settings, click on Apply All to push the project’s required device values to the connected device, replacing the Current Values. Mismatching required and current project values are identified in red.

image-20240522-172334.png

Screenshot from LabMaestro 1.7.0

  • Click on the TRACKPixx3, and examine the project’s Required Values. The required and current TRACKPixx3 Device Settings may need to be adjusted to reflect your installation.

  • As before, save the project, and click on Apply All before continuing to the next step.

image-20240522-172219.png

Screenshot from LabMaestro 1.7.0

  • Finally, associate the active display connected through the DATAPixx3, and ensure that it is the Main Display. Note that the TRACKPixx3 must be installed underneath this display.

  • Measure and adjust the viewing distance, in centimeters. Refer to Displays for more information.

  • Save the project before continuing. The viewing distance will automatically be taken into account to adjust some stimuli sizes, and generate the online fixation and saccade flags.

image-20240522-172719.png

Associate the active display connected through the DATAPixx3 (DATAPixx3 RX1). Screenshot from LabMaestro 1.7.0.

image-20240522-172837.png

Measure and adjust the default viewing distance for your setup, in cm. Screenshot from LabMaestro 1.7.0.

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

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

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

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

Legacy instructions for LabMaestro 1.6.0

In LabMaestro Public Beta 1.6.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.

Screenshot from LabMaestro Public Beta 1.6.0

The order of columns, from left to right, is:

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.

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

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:

  • 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

  1. Click ‘Launch Experiment’ to see the project in action.

  2. 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.

  3. 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.

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.

  • 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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.