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.

Psychtoolbox News

Psychtoolbox beta updated

kleinerm

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:

  • Psychtoolbox was built and lightly tested against Matlab R2022b and Octave 6.4.

  • OpenXR VR/AR/MR/XR eyetracking support. See above.

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 beta updated

kleinerm

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.

Compatibility changes wrt. Psychtoolbox 3.0.19.3:

  • 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 beta updated

kleinerm

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

Compatibility changes wrt. Psychtoolbox 3.0.19.2:

  • 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!

News Archive