Luminance-compensated pupillometry: an estimate of cognitive workload from the pupil that can be used outside the laboratory's constant lighting.
The pupil dilates with cognitive workload but reacts far more strongly to light. The tool estimates the pupil size the light reaching the eye should produce (Watson & Yellott's unified formula, with the participant's latency and pupil dynamics), and reports what is left, the ΔPD:
ΔPD(t) = measured pupil(t) − expected pupil(luminance(t))
The luminance is estimated from the eye tracker's scene video and gaze: a circle around the gaze point weighted against the rest of the view. On a headset it comes from the display's photometry; with glasses trackers, the absolute level comes from a lux sensor worn on the tracker.
The analysis app on synthetic data: a task that dilates the pupil twice while the light changes every few seconds, the ΔPD that is left once the light is accounted for, and the sensor logger's data on the same time axis: the Shimmer's ECG with the heartbeats found in it, the EmotiBit's EDA and the moving RMSSD, with the heart rate variability of the recording and of each task in the table on the left.
Documentation: https://pignonig.github.io/cognitive_analysis_tool/ covers installation, usage, the device
formats and every processing step (Processing at a glance).
Its source is in docs/.
Version 2.0 is in development. The 1.x tools are kept, for archive only, on the
legacy-*branches.
| Device | Recording | Luminance from | Support |
|---|---|---|---|
| Varjo XR-4 | Varjo Base eye tracking recorder | the display: scene capture, display photometry, participant light sensitivity | tested |
| Pupil Core | Pupil Player export | external lux sensor + scene video | tested |
| Pupil Neon | Pupil Cloud Timeseries export or native format | external lux sensor + scene video | experimental |
| Tobii Pro Glasses 3 | recording folder from the SD card | external lux sensor + scene video | experimental |
Experimental readers were written from the manufacturer's documentation and have not yet been checked on a real recording; every result from them carries a warning.
Analysis app (cwtool-gui). Open a recording folder: the scene video is analysed in the background (or loaded
from its cache), and every parameter change updates the measured and expected pupil and ΔPD plots at once. A video
preview shows the analysed areas on the scene frame at the cursor. The logger's files (the lux log, the Shimmer, the
EmotiBit) are found in its recordings folder by their time and can be shown under ΔPD; the Shimmer's ECG gives a heart
rate variability preview (beats, table, heart rate and moving RMSSD). A Set-up checklist says what is still missing
(display photometry, calibration, fits). Export writes one package for the participant: pupil, ΔPD, per-event means, lux and sensor files, the
parameters used and a manifest, all cut to an export range that leaves out a calibration, a break or a test run.
Sensor logger (cwtool-logger). Records the lux sensor, a Shimmer (ECG and more) and an EmotiBit side by side
on the computer's clock, with the phases of the experiment, one folder per recording. Live plots let you check
the signals before recording. The Shimmer's ECG can be set to a rate fit for heart rate variability, which the
analysis computes and exports with the other results.
Calibration presenter (a web page, no install). Plays the participant calibration sequence full-screen on a
display or inside a VR headset, and logs every run.
Open it or open
docs/calibration-tool/index.html from a local web server.
All screenshots use synthetic data.
Python 3.10 or newer, on Windows, macOS or Linux.
git clone -b master_v2.0 https://github.com/pignoniG/cognitive_analysis_tool.git
cd cognitive_analysis_tool
pip install -e ".[gui,logger,hrv]" # "gui" alone if you need neither the sensor logger nor heart rate variability
cwtool-gui [path/to/recording] # analysis app
cwtool path/to/recording --params participant.json --plot # command line, batch processing
cwtool-logger # sensor loggerOn macOS, start the sensor logger from Terminal when using a Shimmer (macOS ends programs that use Bluetooth unless the app that started them may); see the sensor logger page.
| Path | Content |
|---|---|
cwtool/ |
the analysis as a Python package that runs without a GUI; cwtool/gui/ is the Qt app, cwtool/logger/ the multi-sensor logger (lux, Shimmer, EmotiBit) |
tools/ |
the command-line lux sensor logger and an experiment event logger |
docs/ |
the documentation site, including the calibration presenter (a web page that plays the calibration sequence on a screen or in VR) and the screenshots in docs/images/ |
Lux Sensor/ |
firmware for the lux logger and the 3D-printable mount for the Pupil Core |
tests/ |
pytest suite with synthetic recordings for every device |
A short full-field colour sequence, shown in the headset with the calibration presenter, gives each participant's light sensitivity and channel weights, then their response latency and pupil dynamics (the pupil scale and offset stay values you set). These are saved with the participant's parameters and applied to their other recordings. The display's own photometry (black and white luminance, gamma) is kept in a separate file. For glasses with a lux sensor the same sequence, shown on a screen, fits the light sensitivity and the pupil offset. See Participant calibration.
pip install -e ".[gui,dev]"
pytest
pip install -r docs/requirements.txt && mkdocs serve # documentation previewKnown problems and decisions still open are tracked in docs/OPEN_ISSUES.md.
- Pignoni G., Komandur S., Volden F. (2021). Accounting for Effects of Variation in Luminance in Pupillometry for Field Measurements of Cognitive Workload. IEEE Sensors Journal. The lux sensor method.
- Pignoni G., Grandi F., Peruzzini M. Toward Reliable Pupillometry in Extended Reality Environments. Manuscript in preparation, not yet published. The Varjo method.
Earlier and related publications (2019–2022) are listed in the documentation's References. The tool started as part of a master's thesis in MIXD at NTNU Gjøvik (2018–2019).
MIT License, see LICENSE.md. The icons are Tabler Icons (MIT,
cwtool/gui/icons/LICENSE-tabler-icons.txt).