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! 😄
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.
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
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
Recording-specific annotation hotkeys - #2170
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:
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
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:
sudo /Applications/Pupil\ Capture.app/Contents/MacOS/pupil_capture
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.
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
--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.
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.
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 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
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.
Python dependencies can be updated using
pip and the
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.
This new version of
pyglui introduces support for multi-line thumb and icon labels.
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.
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
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:
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