Pupil Labs

Use of Pupil Core

Hardware and software

Each Pupil Core kit contains the following: 

• 1 Pupil Core headset with two cameras and two orange camera extenders

• 1 Windows PC with Pupil Capture and Pupil Player installed

• 1 USB extension

• 1 backpack for carrying everything

Pupil Lab's software is free and can be accessed here . Pupil Capture is used for creating recordings, and Pupil Player is used for visualizing and exporting recorded data. 

Creating recordings in Pupil Capture

Camera placement

Under General Settings, turn on detection of whichever eye(s) you plan to capture. Eye 0 is the right eye and eye 1 is the left. Turning on eye detection will open a separate small window for each eye. This is the "eye camera window" that you interact with to establish your camera placement.

You can manipulate the placement of the cameras relative to the eye by 1) changing how the orange extenders are positioned on the headset, 2) changing how the cameras are positioned on the orange extenders, 3) rotating the cameras inwards and outwards, and 4 ) rotating the cameras up and down.

In Pupil Capture, there are several tools available to help you with placing the cameras. In the eye camera windows, under General Settings, you can switch between three different modes.

Camera Image mode.  The person wearing the headset should roll their eyes around so that the pupil detector can build up a model of the eye. The green circle should adjust to the size of the eye. The red dot in the center of the pupil and red circle around the pupil will then indicate the 3D pupil detection. The blue dot and circle will indicate the 2D pupil detection. The circles should fit the pupil precisely even if the eye moves.

ROI mode. Here you can adjust the blue circles that appear in the corners of the eye camera window in order to reduce the size of area where the pupil detector looks for a pupil. This can be useful if there is something (e.g., eyelashes or a shadow) that is being mistaken for a pupil.

Algorithm mode. The small and large red circles indicate the minimum and maximum possible pupil size values (in pixels), and are used to filter out extreme values. In normal indoor lighting conditions, you probably don't need to change them. The green circle (and blue numbers) indicate the current pupil size. If the cameras are struggling to find the pupil, you can try changing the Pupil Intensity Range (under Pupil Detector 2D in the eye camera window). You can also try going to Video Source/Sensor Settings and changing the Exposure Mode to auto. This can help if there is too much "yellow" in the camera image near the pupil (which indicates spectral reflections).

Another useful tool is the debug window, which you can access through the Pupil Detector 3D tab of the eye camera window. If the pupil is well-captured, you will see a sphere indicating the size of the eye and a turquoise circle indicating the pupil. The pupil will have a gaze vector (black line) coming from it. If the person wearing the glasses keeps their eyes still, this should be quite stable. If there is a lot of jitter in the pupil detection or the gaze vector is bouncing around, the pupil is not well-captured and the cameras should be adjusted.

Before moving on to calibration, ask the person wearing the headset to move their eyes around a little, and check that the confidence values for both eyes are "green''. If they are low (red), the camera placement needs further work. When the pupil is captured successfully, freeze the model before continuing to calibration.

Calibration

The process of calibration allows for mapping of pupil positions to gaze coordinates. You should try to calibrate whichever part of the visual field your participants are likely to use during the task. For mobile eye trackers like the Pupil Core, participants' heads are not fixed in position. Therefore, even if they will be focusing on a relatively small area (e.g., a computer screen), you might think of calibrating a larger area in case they move around.

In Pupil Capture, there are several ways to carry out a calibration. These can be accessed via the Calibration settings in the main screen. The Screen Marker Choreography is the default option. A series of visual targets will be displayed in different parts of the visual field. The participant should fixate the center of each each target without moving their head. It is possible to run this choreography using your computer screen, an external monitor, or a projector---the latter two have the benefit of calibrating more of the visual field. Also note that in order to run the calibration, the targets must be in the range of the world view camera. The camera can be tilted up or down if needed.

Pupil Capture also offers Single Marker and Natural Feature choreographies. For the Single Marker, a target is displayed in the center of the screen. The participant should fix their eyes on the target and slowly move their head around in a spiral motion. This can also be done using an offscreen target (e.g., printed out or displayed on a tablet). For the Natural Feature choreography, you select points in the world for the participant to fixate. Once the participant has fixated a point, click that location in the world view camera display. Pupil Labs recommends using about 9 points.

Regardless of the choreography, either press the "C'' on the main screen or type "c'' in order to start a calibration. Screen Marker will automatically stop when it is finished; Single Marker and Natural Feature can be stopped by pressing "c'' a second time.

Following a calibration, the accuracy and precision of the pupil capture are briefly displayed on the main screen. A good calibration will give an accuracy of around 1. You'll also be able to see an outline of the calibrated area and orange marks in the locations where samples were collected. If a few attempts do not yield a good result, you might increase the duration of the data samples (in calibration settings) and/or re-check that the pupil is captured properly.

After calibrating, you can run a validation by clicking or pressing "T''. Some more targets will be shown to the participant, who should again fixate each one. Accuracy and precision will then be displayed.

Recording

Start a new recording by clicking/pressing "R''.

Before each new recording, it is recommended to check that the pupil is well-captured and to validate the calibration (and recalibrate, if necessary). If the headset has slipped a little during the previous recording, it may be necessary to reset the pupil detection model (in the eye camera window, go to Pupil Detector 3D, unfreeze the model, reset the model, and freeze it again).

It is also recommended to keep your recordings short (up to a few minutes long, especially if the participants are moving a lot), so that slippage can be accounted for more readily.

Pupil Groups

Using more than one Pupil device simultaneously

• Load the  Pupil Groups plugin from the  General sub-menu in the GUI.
• Once the plugin is active it will show all other local network Pupil Group nodes in the GUI (Connect all the Pupil lab devices to a router to form Local area networks (LANs) )
• Furthermore, actions like starting and stopping a recording on one device will be mirrored instantly on all other devices. 

Pupil Time Sync

• The  Pupil Time Sync protocol  defines how multiple nodes can find a common clock master and synchronize their time with it
• The Pupil Time Sync plugin is able to act as clock master as well as clock follower. This means that each Pupil Capture instance can act as a clock reference for others as well as changing its own clock such that it is synchronized with another reference clock.

Synchronize motion capture systems with the Pupil Core mobile eye tracker 

Pupil labs Motion capture trigger

• Download the package from the link above, Run the python script on the clock master laptop.
• You can use the script for any other trigger device capable of sending ~5.0V TTL

Data visualization in Pupil Player

Importing and exporting

By default, Pupil Capture stores its recordings in C:/Users/username/recordings in folders organized by date. Each recording has a number of corresponding files, which are stored together in a sub-folder (eg, "001''). To view a recording, drag and drop the entire sub-folder into the Pupil Player window.

The main display shows the world view video, with gaze overlaid as a green circle with a pink center. At the bottom, there is a timeline that you can navigate. Above the timeline, you can choose to display left and right pupil diameters, pupil confidence, blinks, and other measures. Pressing "e" will export the raw data, including an mp4 video file.