Pupil Capture, Player, and Service release

We are pleased to announce the release of Pupil Core software v3.5!

Download the latest bundle (scroll down to the end of the release notes and see Assets).

Please feel free to get in touch with feedback and questions via the #pupil channel on Discord! 😄

Overview

In Pupil v3.5, we cleaned up log messages, improved software stability, fixations are now cached between Pupil Player sessions, and we have fine tuned 3d pupil confidence.

Pupil v3.5 is the first release that supports the new macOS Monterey (with a small caveat). Read more below.

New

• Recording-specific annotation hotkeys
• Add option to filter out low-confidence values in raw data export
• Add option to disable world video recording
• macOS Monterey support

Improved

• Reduced number of user-facing log messages
• Export-in-progress file-name suffixes
• Windows: Handle exceptions during driver installation gracefully
• Windows: Option to skip automatic driver installation
• Windows: Create start menu entries and desktop shortcuts for all users on install
• Add Euler angles to headpose tracker result
• Normalize IMU pitch/roll values to [-180, 180] degrees
• Confidence adjustment for pye3d results
• Cache post-hoc fixation detector results
• Documentation

New

Recording-specific annotation hotkeys - #2170

Until now, the keyboard-shortcut setup for annotations was stored in Pupil Player's session settings. These were reset if you updated Pupil Core software to a new version.

Starting with this version, annotation keyboard shortcuts will be stored persistently within the recording.

The definitions are stored in <recording dir>/offline_data/annotation_definitions.json with the format:

{
    "version": 1,
    "definitions": {
        "<label>": "<hotkey>"
    }
}

This file can be shared between recordings.

When Pupil Player is opened, it will attempt to load the annotation definitions from the recording-specific file. If the file is not found or is invalid, Pupil Player will fallback to the session settings which contain the last known annotation definitions.

Add option to filter out low-confidence values in raw data export - #2210

Pupil Core software assigns "confidence" values to its pupil detections and gaze estimations. They indicate the quality of the measurement. For visualization and some analysis Plugins, Pupil Player hides gaze data below the "Minimum data confidence" threshold (adjustable in the general settings menu).

Prior to this release, the raw data exporter plugin exported all data, independently of its confidence. New users, therefore, often wonder why their exported data looks noisier than what they have seen in Pupil Player.

Starting with this release, users will have the option to filter out low-confidence data (i.e. below the "Minimum data confidence" threshold) in the export. The option can be enabled in the raw data exporter's menu.

Add option to disable world video recording - #2169

If you are not interested in recording the scene video, you can now disable the scene video recording in the Recorder menu of Pupil Capture's world window.

macOS Monterey support

Due to new technical limitations, Pupil Capture and Pupil Service need to be started with administrator privileges to get access to the video camera feeds. To do that, copy the applications into your /Applications folder and run the corresponding command from the terminal:

• Pupil Capture: sudo /Applications/Pupil\ Capture.app/Contents/MacOS/pupil_capture
• Pupil Service: sudo /Applications/Pupil\ Service.app/Contents/MacOS/pupil_service

Note: The terminal will prompt you for your administrator password. It will not preview any typed keys. Simply hit enter once the password has been typed.

Note: When recording with administrator privileges, the resulting folder inherits admin file permissions. Pupil Player will detect these and ask you for the administrator password to reset the file permissions. This will be only necessary once per recording.

Improved

Export-in-progress file-name suffixes - #2167, #2186

Exporting video can take a long time. Pupil Player displays the progress as a growing circle around the menu icon while writing the result incrementally to disk. Specifically, it writes the result directly to the final export location. While the export is ongoing, the video file is invalid but still available to the user. This can lead to users opening the video before it has finished exporting and then encountering playback issues.

Starting with this release, Pupil Core software changes the video exports to include a .writing file name suffix during the export. This prevents other applications from recognizing the partially exported video file as complete. Once the export is done, the suffix is removed and other applications are able to recognize the file type as video.

Reduced number of user-facing log messages - #2190

Over the years, Pupil Capture's functionality has grown and with it the number of user-facing log messages. They can be overwhelming to the point where important log messages are overlooked or ignored. For this release, we have reviewed the log messages that are being displayed in the UI during typical actions, e.g. calibration and recordings, and have reduced them significantly.

Windows: Handle exceptions during driver installation gracefully - #2173

Previously, errors during the driver installation could cause the software to crash. Now, errors will be logged to the log file and the user will be asked to install the drivers manually.

Windows: Option to skip automatic driver installation - #2207

Using the -skip-driv or --skip-driver-installation flags, one can now launch Pupil Capture and Pupil Service without running the automatic driver installation on Windows. This can be helpful to speed up the start up time or to avoid unwanted driver installations.

Windows: Create start menu entries and desktop shortcuts for all users on install - #2166

Pupil Core software is installed to C:\Program Files (x86)\Pupil-Labs by default. This directory should be accessible by all users but the start menu entry and desktop shortcut are only installed for the current user. Starting with this release, the installer will create start menu entries and desktop shortcuts for all users on install.

Add Euler angles to headpose tracker result - #2175

Next to camera poses as Rodrigues' rotation vectors, the headpose tracker now also exports the camera orientation in Euler angles.

We also fixed a typo in the exported file name.

- head_pose_tacker_model.csv
+ head_pose_tracker_model.csv

Normalize IMU pitch/roll values to [-180, 180] - #2171

Orientation values exported by the IMU Timeline plugin will now be normalized to a range of [-180, 180] degrees.

Confidence adjustment for pye3d results - #2195

In some cases, pye3d was overestimating the confidence of its pupil detections. These were visible as noisy gaze estimations in the Pupil Core applications. This release includes an updated version of pye3d with adjusted confidence estimations. As a result, the gaze signal should look more stable during lower confidence situations, e.g. while squinting or looking down. For more information, see the Developer notes below.

Cache post-hoc fixation detector results - #2194

Post-hoc fixation detector results no longer need to be recalculated if you close and reopen a recording. Pupil Player stores the results together with the used configuration (version of the gaze data and fixation detection parameters) within the recording directory. The cached data will be restored if the Player configuration matches the configuration stored on disk. If it does not match, Player will recalculate the fixations to avoid inconsistencies.

Documentation

We have improved our documentation in several places:

• Pupillometry best practices - pupil-docs#453
• Blink detection - pupil-docs#463
• Pupil Core API - pupil-docs#455

Fixed

• Fixed typo in exported headpose tracker files - #2185
• Fix confidence graphs in Pupil Player for pre-2.0 recordings - #2191
• Use correct socket API to retrieve local IP address for Service - #2201
• Fix loading 200 Hz gaze data in Pupil Invisible recordings - #2204
• Fix loading short audio streams - #2206

Known issues

• Windows: Connecting remotely to Pupil Remote on Pupil Service does not work in some cases
• Pupil Groups: Users have reported issues with Pupil Groups connectivity when running Pupil Capture on different devices.

We are investigating these issues and will try to resolve them with an update as soon as possible.

Developer notes

Dependencies updates

Python dependencies can be updated using pip and the requirements.txt file:

python -m pip install --upgrade pip wheel
pip install -r requirements.txt

pye3d v0.2.0 and v0.3.0

Version 0.2.0 of pye3d has lowered 3d-search-result confidence by 40%. When the confidence of the input 2d pupil datum is lower than a specific threshold (0.7), pye3d attempts to reconstruct the 2d pupil ellipse based on its existing 3d eye model. We noticed that the confidence for these results was systematically overestimated given the actual detection result quality and have therefore adjusted the overall confidence assignment for them. See pye3d-detector#36 for reference.

Version 0.3.0 uses a new serialization format for the refractionizer parameters but is otherwise functionally equivalent to version 0.2.0.

pyglui v1.31.0

This new version of pyglui introduces support for multi-line thumb and icon labels.

Example:

from pyglui import ui

context = {"state": False}

ui.Icon(
    "state",
    context,
    label="Multi\nLine",
    label_offset_size=-10,  # smaller font
    label_offset_x=0,  # no horizontal adjustments
    label_offset_y=-10,  # move label upwards
    label_line_height=0.8,  # reduce line height
)

zeromq-pyre >= v0.3.4

Starting with version v0.3.4, zeromq-pyre is able to handle cases gracefully where it is not able to access any network interfaces. See #2187 for reference.

Plugin API

Easy plugin icon customization - #2196

Plugins can now overwrite the following class attributes to customize the menu icon:

• icon_pos_delta: relative positioning
• icon_size_delta: relative font resizing
• icon_line_height (multi-line icons only): line distance

Requires pyglui v1.31.0 or higher

Real-time Network API

Add surf_to_dist_img_trans and dist_img_to_surf_trans to surface events #2168

These two homographies are necessary to transform points from the surface coordinate system to the 2d image space of the scene camera, and vice versa. They have been available as part of the surface location exports in Pupil Player. With this release, they also become available to other plugins in Pupil Capture or via its Network API.

Example plugin that access the new homographies in real-time:

import numpy as np
from plugin import Plugin

class Example(Plugin):
    def recent_events(self, events):
        # access surfaces or fallback to empty list if not available
        surfaces = events.get("surfaces", [])
        for surface in surfaces:
            # access raw homography data, a list of lists
            homography = surface["surf_to_dist_img_trans"]
            # convert to a matrix
            homography = np.array(homography)
            # use homography, e.g. printing it
            print(f"{surface['name']}: {homography}")

Downloads

To open the RAR-archive on Windows, you will need to use decompression software, such as WinRAR or 7-Zip (both are available for free).

Supported operating systems

• macOS Mojave 10.14, macOS Catalina 10.15, macOS Big Sur 11
• macOS Monterey 12 requires administrator privileges to access the video cameras
• Ubuntu 16.04 or newer
• Windows 10

Checksums

$ shasum -a 256 pupil_v3.5*
41428173c33d07171bb7bf8f0c83b7debfabb66a1dfc7530d1ae302be70ccc9c  pupil_v3.5-1-g1cdbe38_windows_x64.msi.rar
608aceaf4bf450254812b3fcaf8ea553450fcf2d626ae9c2ed0404348918d6ad  pupil_v3.5-7-g651931ba_macos_x64.dmg
786feb5e937a68a21821ab6b6d86be915bcbb7c5e24c11664dbf8a95e5fcb8cc  pupil_v3.5-8-g0c019f6_linux_x64.zip