Psychtoolbox interfaces between Matlab or Octave and the computer hardware. The
PTB core routines provide high performance 2D and 3D graphics with the highest
color and luminance precision, timing precision and control. This both on standard
displays, as well as with special visual stimulators, and with High Dynamic Range
displays, and with a wide variety of Virtual/Augmented Reality devices. They expose
raw OpenGL commands, support video playback and capture, as well as low-latency
precisely timed audio playback and capture. They facilitate the collection of observer
responses with high timing precision via various input modalities like keyboard, mouse,
game controllers, multi-touch touch screens, response boxes, gaze trackers, and digital /
analog i/o equipment. Ancillary helper routines support common needs like color space
transformations, calibration, and psychometric procedures like, e.g., the QUEST threshold
seeking algorithm and others.
Various 3rd party frameworks and higher level toolboxes are built on top of Psychtoolbox
to make implementation of research data collection especially easy in specific sub-domains
of neuroscience. For beginners or certain domains there also exist user friendly 3rd party
graphical user interfaces, e.g., PsyBuilder.
You can also run some of your Psychtoolbox studies online, via VPixx Labmaestro service under
https://vpixx.com/products/labmaestro-packngo.
Psychtoolbox has many active users, an active forum, and is widely
cited. The current version supports at least Matlab R2022b on Linux, Windows
and macOS, and Octave 5 and later on Linux, Octave 7.3 on Windows, and Octave 8 on macOS.
The Psychtoolbox v3.0.19.5 update “Eye to eye” was released on 17th November 2023.
As usual, the complete development history can be found in our GitHub repository.
The release tag is “3.0.19.5”, with the full tree and commit logs under the URL:
https://github.com/Psychtoolbox-3/Psychtoolbox-3/tree/3.0.19.5
This Psychtoolbox release was fully sponsored by Mathworks under the year
2023/2024 contract.
This is the last release built and tested with Matlab R2022b. Future development
and user support will immediately switch to Matlab R2023b after this announcement,
as we no longer have access to earlier Matlab releases, but Psychtoolbox is expected
to continue to work just fine on older Matlab versions.
Highlights:
-
Eye gaze tracking support for OpenXR supported devices via PsychVRHMD()
, ie.
Virtual Reality (VR) / Augmented Reality (AR) / Mixed Reality (MR) Headsets
with built in eye trackers and suitable eye tracking runtimes!
This release should support monocular “cyclops eye” eye gaze tracking on HMDs
with monocular eye trackers and binocular eye trackers (typically reporting a
fused gaze vector for noise reduction, based on sensor fusion between both
eyes tracking data) on all hardware and OpenXR runtimes which support the
XR_EXT_eye_gaze_interaction OpenXR extension. Data reporting is very limited
due to the limited functionality provided by that extension: Only a binary
confidence value (eye tracked / not tracked) and a 3D eye gaze vector aka
gaze ray aka eye position and looking direction, usable for determining the
looking direction in a 3D VR scene and hit testing with 3D scene geometry, as
well as remapped 2D pixel coordinates of where the user is looking inside the
Psychtoolbox onscreen window, both for monoscopic mode and stereoscopic mode.
Demos which demonstrate 3D gaze are VRInputStuffTest.m
if the optional
withGazeTracking
flag is set to 2, or just 2D position for flag setting 1.
2D gaze reporting is demonstrated - if the proper flags are set - by the
following demos and tests: VRHMDemo.m
- simple mono/stereo view reporting,
GazeContingentDemo.m - monoscopic display, “foveated area” is moved via gaze,
and VREyetrackingTest.m
for extensive demo and testing.
The API / how to use and description of features and limitations is in the
help PsychVRHMD
where one would expect VR/AR/MR/XR related functionality.
Setup instructions can be found under help OpenXR
.
For VR HMDs with builtin eyetrackers from HTC, e.g., HTC Vive Pro Eye, on
MS-Windows only, a second more feature rich eyetracking mechanism via use
of HTC’s proprietary Windows-only SRanipal eyetracking runtime is used. It
additionally to the above “cyclops eye” reporting allows for binocular
eyetracking, more precise gaze sample timestamps, and estimates reported for
“eye openess” aka how much are the eyelids open, and pupil diameter.
Due to lack of other equipment, time and funding, this functionality was only
tested under Microsoft Windows 10 with a rented HTC Vive Pro Eye HMD under
SteamVR 1.26, and to a lesser extent, the new SteamVR 2.0.10 runtime from
Valve. The monocular “cyclops” eye gaze tracking should work on any other HMD
with OpenXR compliant eye tracking though, also on Linux. And binocular tracking
should work on other HTC HMDs under Windows as well. Theory and practice, we
will see…
Performance and precision is reasonably good, although functionality wise there
is a lot of room for improvement. Further funding would be needed to do that
work. This OpenXR eye gaze tracking was sponsored by Mathworks as the main
new sponsored improvement under the 2023/2024 contract.
As so often though, the funding was insufficient to fully cover our costs
up to this point, so future development of this eyetracking support will be
mostly dependent on future funding or contract work from interested labs
or users.
Given that the HTC Vive Pro Eye used for developing and testing this support
is only rented, and due to the lack of funding, we will likely have to give
the HMD back before christmas, so no further debugging / refinement or
related user support can be provided after that point in time, unless some
labs or users contract and fund us for further development and support.
Therefore I urge you to test this functionality early and give timely feedback,
before it is too late for a cheap solution. That still means of course that
while constructive feedback is appreciated, no free help will be provided
for setup and first steps in general. That’s what our paid support is for.
All:
-
OpenXR VR/AR/MR/XR eyetracking support. See above.
-
PlayMoviesDemo.m: Some performance optimizations for high fps HDR movie playback.
-
CreateResolutionPyramid()
: Fix and deuglify MipMapDownsamplingShader.
-
Minor bug fixes, documentation updates and improvements.
Linux:
Windows:
-
Psychtoolbox was built and lightly tested against Matlab R2022b and Octave 7.3.
-
Additionally to OpenXR eyetracking, also SRAnipal binocular eyetracking on
suitable HTC HMDs, as tested with the HTC Vive Pro Eye.
macOS:
- Psychtoolbox was built and lightly tested against Matlab R2022b and
Octave 8.3 from HomeBrew. Octave 8.4 was also lightly tested and seems fine.
Enjoy!
Psychtoolbox 3.0.19 Beta update “Virtuality” SP4 was released at 27th October 2023.
As usual, the complete development history can be found in our GitHub repository.
The release tag is “3.0.19.4”, with the full tree and commit logs under the URL:
https://github.com/Psychtoolbox-3/Psychtoolbox-3/tree/3.0.19.4
This Psychtoolbox release was partially sponsored by Mathworks under the year
2023/2024 contract.
-
On MS-Windows, GStreamer 1.22 is now required, the latest lightly tested
version is GStreamer 1.22.5. With the older GStreamer 1.20, text rendering
with the high quality drawtext plugin will no longer work, and the fallback
GDI text renderer would be used, which is officially unsupported in case of
trouble and has lower performance/quality/features/reliability.
-
On macOS if using Octave, Octave 8.3 is now recommended and tested, but older
Octave versions back to v6.3 are expected (but not tested) to continue to work.
Highlights:
None, just a large grab bag of various minor and major fixes and improvements.
All:
-
Some Unix file permission cleanup contributed by Yaroslav from NeuroDebian.
-
CalibrateMonSpd(): Fix some fallout from previous fixes. Set cal.describe.dacsize
also if g_usebitspp is already set. Reference:
https://github.com/kleinerm/Psychtoolbox-3/issues/252
-
DegreesToRetinalEccentricityMM(): Fix typo in code that prevented replacement
of small angles by the linear approximation. Contributed by Stella Prins.
-
MakeSineImage(): Allow passing of center (0 phase) position of the sinusoid.
Contributed by David Brainard.
-
ComputePhotopigmentBleaching(): Add constants from Wyszecki and Stiles.
Contributed by David Brainard.
-
New touchscreen demo: MultiTouchPinchDemo.m, to show detection and handling of
two finger pinch gestures on touchscreens.
-
Output info message with potential troubleshooting tips if drawtext init takes
unusually long, hinting at potential fontconfig cache rebuild (problems) on
MS-Windows. May or may not help anybody, but probably doesn’t hurt. Suggested
by GitHub user @mirh.
-
DrawFormattedText(): Add new keyword ‘left’ to use for the ‘sx’ parameter. It
will left-align drawn text to the left border of an optionally provided
‘winRect’, similar to the ‘right’ keyword for right-alignment. Improvement
contributed by GitHub user @SVNKoch.
-
PsychPortAudio: Add potential workaround to deal with temperamental / weird
audio sound cards. Add a new optional parameter to the tweaking command
PsychPortAudio('EngineTunables', ...., workarounds);
, which allows to
specify a non-default (ie. non-zero) workarounds bitmask to selectively
disable or enable workarounds. The currently defined workaround bits are the
following, which modify how the Portaudio audio format test function
Pa_IsFormatSupported is handled:
+1 = Do not error abort on test failure, ie. print warnings but don’t abort.
+2 = Skip the whole test and always assume success.
Both could help if the test reports false positives (+1 to continue), or
if some hardware queries/operations themselves during the test trigger
some trouble (+2 to skip the whole test).
Also various other minor improvements to PsychPortAudio and some of the audio
demos and tests.
-
Snd(): Switch fallback method from use of sound() to use of audioplayer().
Both modern Octave and Matlab implement sound() as a wrapper around their
audioplayer() objects, so using audioplayer() directly gives us more control
for a better Snd() fallback implementation. Also use the fallback method as
new default by default. Iow. unless specified otherwise, Snd() will play
via audioplayer(). This provides good interop with other audio clients and
with Screen()’s GStreamer based movie playback engine.
-
Beeper(): Formatting/Indentation fixes, refine soundvector calculation.
-
BitsPlusIdentityClutTest: Disable encoder test if Vulkan display is used.
Current design lead to the tests running before the Vulkan backend is fully
in charge, so we display the PTB welcome screen or pixeltrash during the test,
instead of the test stims, which leads to false-positive test failure. Just
don’t offer the test option under Vulkan. DatapixxGPUDitherpatternTest is an
alternative working way to test with Vulkan at the moment.
-
PsychOpenHMDVR: Use correct ipd/2 instead of ipd for warp-mesh setup in our
OpenHMD driver.
-
Minor bug fixes, documentation updates and improvements.
Linux:
-
Psychtoolbox was built and lightly tested against Matlab R2022b.
-
RPiGPIOMex: Various bug fixes and improvements. Also merged two alternative
implementations of the file co-written by Steve Van Hooser and myself. These
reimplement functionality by using the pigpio library instead of the old and
deprecated wiringPi library. This should be more future-proof and maintainable.
For now, the original file based on wiringPi is still used though, until we
decide which of the two new variants is the better choice.
-
Fix exception handling on Octave for RaspberryPi on RaspberryPi OS, so errors
only abort the users script and don’t terminate the whole Octave application.
Windows:
-
Psychtoolbox was built and lightly tested against Matlab R2022b.
-
GStreamer 1.22 is now required, GStreamer 1.20 will have limitations.
-
Fix drawtext plugin again, so it no longer breaks under Matlab with
GStreamer 1.22 on some systems. This will now require the installation
of GStreamer 1.22, the older GStreamer 1.20 will no longer work with
the drawtext plugin.
-
Windows: Remove support for building 32-Bit mex files.
Matlab is 64-Bit only since a long time on Windows, Octave is about to
remove 32-Bit support as well. Windows-10 - the last MS 32-Bit operating
system is on the way to final retirement. Ergo, no need for 32-Bit builds
in the future anymore.
-
Make Screen(‘Openwindow’) timing startup tests and calibrations more
robust. This by disabling processor idling during the tests, ie. ACPI
C-State processor power management transitions out of C0 (active). Such
transitions can induce latency / variability in code execution timing bad
enough to affect timing tests on some setups. If and how much this helps
in practice remains to be seen. Based on investigations / measurements
by GitHub user @mirh, see GitHub isse #793 for reference. If this new
optimization causes trouble or interop problems with cpu performance
tweaking tools, e.g., the Windows tools “throttlestop”, it can be disabled
by use of the command before the first time you try to open an onscreen
window in your experiment script:
PsychTweak('DontDisableProcessorIdling', 1);
macOS:
-
Psychtoolbox was built and lightly tested against Matlab R2022b and
Octave 8.3 from HomeBrew.
-
Screen(): Add iMac20,1 and iMac20,2 aka year 2020 iMacs to timing fixup lut,
so the visual timing fixes also apply to these final Intel iMac models with
AMD Navi graphics chips. As the PsychtoolboxKernelDriver does not support AMD
Navi graphics, our visual timestamping and our diagnostic for visual timing
problems on these machines will be more limited than on older machines, but
the untested expectation is that this should fix timing on 2020 iMac internal
displays.
-
Screen(): Remove conserveVRAM flag kPsychDontCacheTextures. It was useless and
even buggy since years, so let it die.
-
Screen(): Add new conserveVRAM preference flag 2 == kPsychDontSwitchToOptimalVidMode.
May or may not help fullscreen display on connected external video splitters like the
Matrox DualHead2Go. This is based on a hunch, not on proper root causing. Cfe.
https://psychtoolbox.discourse.group/t/open-window-cant-set-to-a-specified-rect-size-on-macos-with-matrox-dualhead2go/5061
Enjoy!
Psychtoolbox 3.0.19 Beta update “Virtuality” SP3 was released at 13th July 2023.
As usual, the complete development history can be found in our GitHub repository.
The release tag is “3.0.19.3”, with the full tree and commit logs under the URL:
https://github.com/Psychtoolbox-3/Psychtoolbox-3/tree/3.0.19.3
-
Octave: Octave 7.3 is required on MS-Windows. Octave 8.2 is required on macOS,
but Octave 6.3 - 8.1 may also continue to work on macOS (assumed, but untested).
-
Recommended operating systems: Ubuntu 22.04.2-LTS Linux, MS-Windows 10 22H2, macOS 13.4
-
The macOS 10 (aka Mac OSX) OS family, macOS 11 and macOS 12 operating systems will
probably continue to work, but are now untested and officially unsupported and unsupportable.
Running Psychtoolbox on Apple Silicon Macs (M1, M2, …) is not officially supported by
this release. Visual stimulation timing will be totally broken on Apple Silicon Macs, as
well as some other features. It is our understanding that currently no vision science
toolkit exists that could provide any reliable or trustworthy operation on macOS for
Apple Silicon. On Intel based Macs, Psychtoolbox likely continues to be the only toolkit
with somewhat trustworthy visual stimulation timing on most Intel Mac configurations
if configured correctly for use with a properly installed PsychtoolboxKernelDriver.
-
Procedural shaders: Remove corrective offsets for hardware texture sampling, as
it may be no longer helpful, but harmful, due to changes in gpu hardware drivers
on all operating systems. See GitHub issue #800, reported by user @qx1147. Tests on
AMD, NVidia and Intel gpu’s under Linux, Windows and macOS suggest this is the right
thing to do now. This means that the centers of procedurally generated stimuli like
Gabor patches or sine gratings will shift by 0.5 pixels on the screen.
Highlights:
- Switch lightly tested and supported macOS version from macOS 12 Monterey to
macOS 13 Ventura. Older macOS versions are untested and unsupported from now on.
All:
-
The new OpenXR driver has now also been tested with the HTC Vive Pro Eye and the
associated “Vive Wand” hand controllers with Valve SteamVR 1.25.7 on Windows and Linux,
and with Monado on Linux with “vive” and “survive” backends as OpenXR runtimes on
(recommended going forward) Ubuntu Linux 22.04.2-LTS. Past successfull Linux tests
were on - no longer tested - Ubuntu 20.04.6-LTS. The driver now also works with
Octave 7.3 on MS-Windows.
-
DaqAInScanContinue: Try to fix live data retrieval on USB-1208FS when using more than one
analog input channel. It could cause data loss or data to channel mapping misalignment
when DaqAInScanContinue(daq, options, 1);
was used with more than one input channel.
Cfe. https://psychtoolbox.discourse.group/t/sampling-frequency-of-analogue-input/4780/10
This is untested due to lack of hardware. Unpaid work time spent trying to diagnose and
fix this: 4 hours.
-
Snd: Update help text, remove Octave specific quirks - no longer needed. Add a new function
Snd('OldStyle');
to allow selection of old style audio output path on the fly, as
addition to the former static only selection by creating a config file. Allows use of the
old output path which simply uses Matlabs or Octaves sound()
function, which is now
available also on all supported Octave 5+ versions.
-
Make CalDemo work with graphics hardware gamma lut sizes other than 256 slots. Instead
use the size of the actual luts stored in the loaded calibration file.
-
Try to fix and improve CalibrateMonSpd and related functions: It now also works on
standard display setups other than visual stimulators from CRS and VPixx. Plus tons
of bug fixes. Also it now also supports other colorimeters than the PR650. See the
following link for the mess this tries to fix:
https://psychtoolbox.discourse.group/t/single-row-entries-in-theclut-during-calibration-with-a-spectroradiometer-calmonspd/5033
-
Improve Eyelink('ImageTransfer')
: Allow to pass in image matrices from Matlab/Octave,
e.g., as read from image files via imread()
, or retrieved from PTB drawing commands
via Screen('GetImage')
, or computed in scripts. Before this, it was only possible
to load uncompressed BMP image files. Also fix the - previously broken - demos
EyelinkPictureCustomCalibration and EyeLinkPicture. Untested on actual Eyelink, only
tested in simulation due to lack of hardware.
-
Procedural shaders: Remove corrective offsets for hardware texture sampling, as
it may be no longer helpful, but harmful, due to changes in gpu hardware drivers
on all operating systems. See GitHub issue #800, reported by user @qx1147.
-
Minor bug fixes, documentation updates and improvements.
Linux:
-
Psychtoolbox was built and lightly tested against Matlab R2022b.
-
PsychOpenHMDVR: Fix crash in ‘GetTrackingState’ if VR controllers are not present or
are not supported. Also add HTC Vive Pro Eye specific undistortion shaders. Other minor
improvements.
-
Eyelink: The mex files for Linux were upgraded to now use and require the SR-Research
eyelink_core SDK and runtime version 2.0, instead of the old v1.9 runtimes. To run the
new mex files you either need to manually set a symlink for mapping the new runtime name
to the old runtime library name. Or install the recent v2 runtime from SR-Research. It is
recommended to upgrade, as the new runtime contains nice bug fixes. E.g., the runtime no
longer hangs if no Eyelink tracker hardware is connected, iow. Eyelink dummy mode fallback
can now work. The most easy way to upgrade Ubuntu or Debian to the latest SDK is from a
terminal via the following command-line:
sudo apt-key adv --fetch-keys https://apt.sr-research.com/SRResearch_key ; sudo add-apt-repository 'deb [arch=amd64] https://apt.sr-research.com S
RResearch main' ; sudo apt install eyelinkcore
or you follow the setup instructions at https://www.sr-research.com/support/docs.php?topic=linuxsoftware
Windows:
-
Psychtoolbox was built and lightly tested against Matlab R2022b.
-
The OpenXR driver now also works with Octave 7.3, in addition to Matlab.
macOS:
-
macOS Ventura (currently version 13.4.1) is the only officially lightly tested and
supported macOS operating system, and only for 64-Bit Intel Macs. Support and testing
for macOS 12 Monterey has ended, but macOS 12 is assumed to continue to work as before.
-
Upgrade to the brand new 64-Bit GNU/Octave 8.2 from HomeBrew is recommended for running
Psychtoolbox 3.0.19.3 on Octave. Other Octave versions from the Octave 6.3/6.4 and 7.x
series, Octave 8.1, or future Octave 8.x versions, may work as well, but no guarantees
for anything other than Octave 8.2 from HomeBrew.
-
Psychtoolbox was built and lightly tested against Matlab R2022b.
Enjoy!