Hero image

Vision and Haptics Laboratory: PTB

Introduction

August 27th 2022: I am currently updating all of the demos and tutorials on the website so that each demo has a seperate webpage with embeded media. What you see here is the new website page. As such, until I have worked my way through all the demos (hopefully over the next week), there will be missing pages and links for a while, and also some formatting issues. To access the old version of the page with all of the code links (but no images and movies) please click here

 

The aim of these demos is to provide an introduction to how to program using Psychtoolbox (PTB). To get started you will need to have installed Matlab or Octave (a free clone version of Matlab) and followed the install instructions which are provided on the PTB website. If you have previously installed PTB I recommend you use the "UpdatePsychtoolbox" command to get the latest version. 

There are around 80 demos on this site and these are organised into sections based on learning different aspects of PTB. For all users I strongly suggest looking at sections (1) and (2) as these show essential features which will help get you up to speed coding in Matlab and PTB. If you are not clear on the essentials, you will struggle with the more difficult aspects. 

Please make sure you carefully read the comments in the code as these provide an explanation of why things are done the way they are. The demos provided as an educational resource. I provide no guarantees that the demos provide "best practice" for your specific needs.

It is strongly suggested that you have a secondary monitor connected to your computer when exploring the demos, as nearly all of the demos will open a full screen window. As such, if you have only one monitor this will cover your entire viewable screen. This is also good practice for the development of code, where the code might crash during development. It is not however good practice for running code in an experiment, as having a seperate screen for the Matlab interface will negatively impact timing. 

PTB has an active forum which can be found here. If you have problems with core PTB functionality ask questions there. PTB is now primary developed for Linux, reduced functionality and support is provided for Windows and OSX

COMING SOON: Matlab and Psychtoolbox YouTube course and Psychtoolbox Demos paper for citing this resource

(1) The Basics

The aim of the tutorials is to assume no prior experiance of programming with PTB. As such, this first set of demos starts with the complete basics to introduce you to the core principles that constitute the foundations for all that follows. If you look at the later demos you will see that virtually all of the core code is shared with these early demos. Therefore, if you have never programmed with PTB, start here. 

 

Totally Minimal Demo: This demo aims to be as minimal as possible. It opens a screen and colours it grey. Thats it. But it demonstrates pretty much the steps you will always use when starting a program i.e. opening a on-screen window.

Totally Minimal Demo #2: This is the same as "Totally Minimal Demo", except after opening the window we query numerous things about it. This demos how to get pretty much all the basic info you will need about the screen.

Accurate Timing Demo: This demo shows three basic ways in which to present a stimulus which would change on each frame. The three ways demonstrate varying degrees of potential accuracy. Please read the extensive comments in the demo closely, they are important and should not be ignored. For presenting a stimulus which is unchanging, or changes less frequently then each frame, see the next demo.

Wait Frames Demo: Here we demonstrate how to update an image on the screen at a rate different to that of the monitors refresh rate. For example, you might want to update the stimulus every second, rather then at the frame rate of your monitor, as in "Accurate Timing Demo".

Partial Window Demo: This demo demostrates how to create a PTB window which covers only part of the screen. This is useful if you are developing code on a single monitor setup as it means if your code crashes, you are not stuck with a full PTB window covering your whole screen.

Floating Window Demo: This demo demostrates is similat to Partial Window Demo, but it creates a PTB window with a window bar and standard window buttons. This window behaves much like a standard application window in that it can be moved around with the mouse etc. This is useful if you are developing code. 

Transparent Window Demo: This shows how to create full onscreen PTB window, but for this to be semi-transparent. Again, this is useful when developing code, as if you code crashes you can still see your desktop "behind" the full screen PTB window.

Screen Coordinates Demo: In this demo you can move the mouse cursor around the screen and we write text on the screen letting you know what the X and Y pixel coordinates of the cursor are (rounded to the nearest pixel). This allows you to picture how screen coordinates are defined as well as how to query the position of the mouse.

NOTE: For all of the subsequent demos we aim to show best practice in terms of coding, particularly in terms of timing. Different systems have different levels of timing fidelity and PTB robustly warns the user if its initial timing tests fail. This may occur with the demos on this page. This is not a error with the code, rather it is a potential issue with the timing fidelity of your system. See this PTB help page for information. 

  

(2) Basic shapes and dots

This set of demos will show you how to draw static shapes, lines and dots. Much of the code in these demos shows the core functionality of drawing to the screen with PTB so will be a valuable start-point for understanding the material covered in latter demos.

 

Single Dot Demo: This very simple demo draws a single dot on the screen in a randomly determined position.

Dot Grid Demo: Shows you how to draw multiple dots with different properties in a single line of code. In this example a uniform grid of dots with different positions, sizes and colours.

Rectangle Demo: Shows you how to draw a rectangle and position it on the screen.

Multiple Sqaures Demo: Shows you how to draw multiple rectangles (in this case squares) with different colours simultaneously.

Different Squares Demo: Shows you how to draw multiple rectangles (in this case squares) each differing in both size and colour.

Order Of Drawing Demo: This demo explains about sequential drawing. This is key to drawing multiple objects to the screen e.g. overlapping objects.

Simultaneous Contrast Illusion Demo: This demo builds on "Order Of Drawing Demo" by drawing a simple simultaneous contrast illusion.

Random Rectangles Demo: Building on previous demos, this demo draws a large number of rectangles with random aspect ratios and random colours at random positions on the screen. 

Hermann Grid Illusion Demo: Draws a set of black squares on a white background to make the Hermann Grid Illusion.

Framed Squares Demo: Shows you how to draw multiple framed squares simultaneously.

Oval Demo: Shows you how to draw a filled in oval.

Polygon Demo: Shows you how to draw a polygon with an arbitrary number of sides.

Framed Polygon Demo: Shows you how to draw an outline of a polygon with lines (rather then filled).

Fixation Cross Demo: Illustrates how to draw multiple lines to make a fixation cross.

Checker-Board Demo: Builds on previous demos by showing how to build a multi-coloured and a black-and-white checker-board.

Semi-Transparent Squares Demo: Shows you how to make shapes semi-transparent using the "alpha" channel, so that you can partially "see through shapes" to those behind. Again, the order of operations is key.

(3) Animate basic shapes and dots

Now we have mastered drawing static stimuli to the screen, we will learn how to animate these shapes. Essentially this will allow us to translate, rotate expand and shrink objects drawn to the screen. We will also learn how to change the colour and size of objects contingent upon their movement. And finally, also learn how to interact with objects on the screen with the mouse or keyboard.

 

Moving Dot Grid Demo: Builds on "Dot Grid Demo" by animating the dot grid moving sinusoidally left and right across the screen.

Scaled Dot Grid Demo: Shows you how to expand and contract a grid of dots draw on the screen. The size of the dots also modulates contingent upon their expansion.

Moving Square Demo: Shows how to animate a square moving sinusoidally left and right across the screen.

Multiple Moving Squares Demo: Shows how to animate two squares moving sinusoidally across the screen with different colours and different lateral offsets.

Moving Colour Change Square Demo: Animates a square moving sinusoidally across the screen, with its colour being dynamically contingent on its screen position.

Moving Size Change Square Demo: Animates a square moving sinusoidally across the screen, with its size being contingent on its screen position.

Rotating Squares Demo: Animates three different coloured rotating squares using basic OpenGL commands.

Mouse In Square Demo: Shows how change the colour of a square contingent upon whether or not the mouse cursor is inside it or not.

Keyboard Contingent Square Demo: Shows how the position of a square can be interactively moved around the screen buy pressing keys on the keyboard (in this case the arrow keys). It demonstrates the use of Keyboard Queues which allow the capture of even breif keystrokes. 

Rectangle Coordinates Demo: This demo builds on "Screen Coordinates Demo" and "Square Demo" by showing you how a screen rectangle is defined by its top-left and bottom-right coordinates. Move the rectangle around the screen with the keyboard and see how the coordinates change. Also shown for information is the central coordinates of the rectangle.

Mouse Contingent Square Demo: Shows how the position of a square can be yoked to the position of the mouse.

(4) Static Textures

We now move on to textures. You can imagine a "texture" as simply a picture i.e. a pattern of pixel values showing anything at all. Textures can be pictures loaded in from file e.g. a picture of a face, or created in Matlab and/or PTB e.g. a grating or Gabor. In this section we will introduce all you will need to get a basic understanding of drawing static textures to the screen. This will include scaling and rotating textures upon drawing to any region of the screen.

 

Draw Image Demo: Shows you how to load an image into PTB and then present it on the screen for a specific amount of time. Specifically, the code presents an image for two seconds on a grey background, fills the screen green for two seconds, then finally presents the same image (now upside down) again for two seconds, this time on the green background.

Gabor Demo: This demo shows you how to draw a standard Gabor using PTB's procedural texture support. This allows one to draw many Gabors patches in an extremely efficient manner. For this demo we simply draw one Gabor in the center of the screen. There are a few specific parameters that need to be set to draw a standard Gabor. This demo shows you how to do that.

Spiral Texture Demo: Shows you how to define a texture in PTB, in this case a spiral. Then draw it to multiple positions on the screen simultaneously, whilst also modulating each drawn textures colour using PTB functionality i.e., we create a single texture but colour it in the drawing call. 

Pinwheel Texture Demo: Same as "Spiral Texture Demo", except this time with pinwheel textures.

Scaled Spiral Texture Demo: Shows how you can dynamically rescale a single texture to be different sizes when drawn to the screen.

Stacked Scaled Image Demo: Shows you how to load an image into PTB then dynamically rescale it multiple times when drawing it to the screen. The result is some quite psychodelic konijntjes.

Checkerboard Texture Demo: Exploits dynamic texture scaling to draw a checkerboard texture very efficiently using onboard filtering in PTB. The original 4 x 4 pixel texture is scaled up by 90% with nearest neighbour filtering. Also demonstrates how to rotate textures when drawing them to the screen (see the animated texture demos for more information on texture rotation).

Contrast Modulated Spiral Demo: Here we create a set of three, coloured, contrast-modulated spiral textures. We do this buy contrast modulating a noise background with a spiral texture mask. This mask is draw into the 'alpha' channel of the spiral texture.

Radial Checkerboard Demo: Displays an static radial checkerboard, as is typically used as the basis for visual field mapping in fMRI (this demo is a modified version of one coded by Keith Schneider).

Bubble Aperture Demo: This demo shows how to produce a basic "Bubbles" stimulus. We load the standard PTB konijntjes image into a texture and then view it through a mask consisting of an opaque grey layer punctuated by Gaussian apertures through which the konijntjes image can be seen. You can easily explore all the components of the stimulus e.g. try drawing only the original Gaussian mask over the image.

(5) Animated Textures

We will now focus on animating textures. This will include rotating textures, both internally and externally. As well as using translating textures to construct drifting stimuli such as gratings and Gabors. We will also look at a more complex stimulus, which involves drawing multiple drifting Gabor stimuli simultaneously. This will build on your knowledge of alpha blending gained from previous demos. Also, PTB provides a excellent range of demos showing this type of functionality. These are referenced and linked below.

 

Rotating Checkerboard Demo: In this demo we make a single 4 x 4 pixel checkerboard texture and draw it to the screen simultaneously in four separate positions. Each checkerboard is colour modulated, rescaled by 50x and rotated. This drawing can all be accomplished in a single line of code.

Internal External Texture Rotation Demo: In this demo we demonstrate the difference between "external" and "internal" texture rotation. A pinwheel texture is drawn to the screen in four positions, each colour modulated. The left two textures rotate "externally" the right two textures "internally".

Rotating Contrast Modulated Spiral Demo: In this demo we animate the alpha layer of three contrast-modulated spiral textures, to produced coloured contrast modulated rotating spirals.

Contrast Modulated Grating Demo: This is a modified version of "DriftDemo2" included with PTB. I've modified it to draw a contrast modulated grating (second order grating) rather then a luminance modulated grating (first order grating).

Global Motion Gabor Array: This demo draws an array of drifting Gabors using procedural textures. The Gabors have randomly assigned orientations and their drift speed is assigned to be consistent with a single "2D" velocity. For details click here for the original paper introducing the stimulus. Also, see my own publications for some work which has used this type of stimulus.

Contrast Reversing Radial Checkerboard Demo: Displays an animated radial checkerboard that reverses in contrast over time (this demo is a modified version of one coded by Keith Schneider).

Windowed Radial Checkerboard Demo: Displays an animated radial checkerboard which reverses in contrast, but is viewed through a static mask which allows you to display a segment of the checkerboard pattern (this demo is a modified version of one coded by Keith Schneider).

Moving Windowed Radial Checkerboard Demo: Same as Windowed Radial Checkerboard Demo except now the checkerboard mask rotates. Note: you might perceive the mask to occasionally “jump” so that the motion no longer appears smooth, this is an illusion caused by the contrast reversal.

Fading Texture Demo: This demo loads a picture of rabbits included in the PTB distribution, conversts it to a texture and dynamically fades the texture in and out of visibility with a temporal sine wave function. It does this by changing the "alpha" value of the texture (this is called alpha blending, or compositing). The alpha value ranges between 0-1, 0 being completely invisible and 1 being completely visible. For a value of 0.5 you can see half of the image and half of the background colour (the alpha value of the texture oscillates around this value during the demo).

Scaled Image Demo: Loads an image, converts it to a texture and draws it scaled in size on each frame. Demonstrates automatic texture scaling in PTB.

(6) Text

This set of demos will show you the basics of how to draw text, position it on the screen and move it dynamically. We cover how to stereoscopically present text so that it is in a different depth plane to the screen in later demos. For these demos we will be using PTB's "DrawFormattedText" command, as this provides an versatile and straightforward to draw formatted text.

 

Basic Text Demo: This is a basic as it gets. Simply writes “Hello World” at three different screen positions, in three different colours, in three different fonts, with three different font sizes.

New Line Text Demo: In this demo we show you how to draw write multiple lines of text in a single go, how to concatenate lines of text and how to place line breaks in text.

Mirror Text Demo: Shows you how to draw mirror reversed text. This is useful if you are presenting text on a monitor viewed via a mirror e.g. when viewing a monitor in a stereoscope. The text is the same as in "Basic Text Demo", but now the top line is flipped horizontally, the middle line is flipped vertically, and bottom line is flipped both horizontally ad vertically i.e. shown upside down.

Countdown Timer Demo: This demo shows how to implement a simple countdown timer. The timer starts at 10 and counts down to 0, with the number shown on the screen updating each second. The color of the text updates randomly each time the number changes. It uses the inbuilt functionality of PTB to present a stimulus for multiple frames at a time (as in "Wait Frames Demo").

Digital Clock Demo: Shows you how to poll the current date and time with Matlab, format the returned numbers into text strings and then present them on screen like a digital clock. The code uses numerical, string and cell data so is useful in seeing how to format and index these different types of data structure. 

Analog Clock Demo (NEW: Coming Soon): This is the same as "Digital Clock Demo", but it draws an animated analog clockface instead. This demo combines text and other drawn shapes. It also used a little bit of high-school triganometry to determine the positioning on the clock hands. 

Moving Text Demo: In this demo we show you how to animate text. We write "Hello World" in different vertical positions on the screen and then oscillate the horizontal position of the text sinusoidally over time. 

Rotating Text (to texture) Demo: In this demo we show you dynamically rotate text. PTB doesn't offer a direct way in which to rotate text using the "DrawFormattedText" command. For in built text rotation see DrawFormattedText2, however it is very simple to rotate the text ourselves. We do this by drawing the text to a texture. Then drawing the texture to the screen. You can essentially treat textures like windows, as they are in some ways equivalent. Demo also shows how to poll the bounding box size of text.

(7) Sound

These demos will show you the basics of getting Psychtoolbox to produce sounds for you. We will first looks at producing sounds without any accompanying visuals, and then at synchronising sound with visuals. All of these demos will use PsychPortAudio as this offers the most robust and versatile way to present sounds in Psychtoolbox. Note: These demos produce sounds. I have use volume settings in code which produce comfortable sounds on my system, but this might not be the case for yours. Please make sure you turn your volume to a very low level before playing the demos for the first time so as to check the volume.

 

Simple Beep Demo: In this demo we simply make play a beep for one second, pause for a second, and then play another beep for a second. That’s it. However, this shows you how to setup PsychPortAudio for sound playback. You will use very similar syntax for many forms of sound playback.

Beep Text Demo: In this demo build on Simple Beep Demo by concurrently presenting visual stimui at the same time as the beeps. The screen will show "BEEP" for the duration of the beeps and "SILENCE" when a beep is not playing.

OpenAL Demo: NEW: Coming Soon.

(8) 3D stimulis without stereoscopic presentation

We will now move on to drawing 3D stimuli. In this section we will use cues such as motion, perspective and shading to define our 3D objects. This means that no special equipment is used to display the images.

 

Structure From Motion Demo: Shows how to render a 3D rotating cylinder with moving dots. Structure from motion, in this instance, is ambiguous about the depth of the cylinder, as the dots are projected orthographically onto a 2D surface (your screen). The stimulus will therefore be perceived to ‘flip’ rotation direction. In fact, the stimulus is quad-stable i.e. there are four possible stable interpretations of its depth structure.

Uniform Dot Sphere Demo (NEW: Coming Soon): This demo show you how to randomly place dots on a sphere so that they are uniformly distributed over the surface of the sphere. 

Cubes Demo: This simple demo will introduce you to 3D rendering with OpenGL. OpenGL is a powerful way in which to create stimuli and is at the heart of much of PTB, all be it behind the scenes. This demo renders an array of 3D cubes, each with a different position and rotation angle. It lights these cubes with a single light source. The scene is rendered with anti-aliasing via multi-sampling to give us nice smooth edges to the rendered objects on screen. It also demonstrates the order of operations for transforms to be applied in OpenGL.

Different Cubes Demo: This demo is the same as "Cubes Demo", but renders the cubes with different colours and sizes. Thus showing you how to apply some additional properties to each drawn object. 

Rotating Cubes Demo: This demo builds directly on "Cubes Demo" and "Different Cubes Demo" by rendering the cubes of multiple colours randomly rotating over time.

In-Out Cubes Demo: This demo builds directly on previous demos by rendering the cubes randomly moving in and out of depth (the z dimension) following a sine wave function.

Rotating Light Source Demo: In this demo we render a light source rotating around a sphere. You will be able to see how the changing light-source position effects the luminance of the spheres surface (given an assumed lighting model) We also introduce the concept of “display lists”, which can be used to speed up rendering.

Textured Surface Demo (NEW: Coming Soon): Loads an image in from file, converts it to a texture, maps that texture to a plane and then renders the plane rotated, translated and scaled using PTB.

Rotating Necker Cube Demo: Uses OpenGL commands to draw a rotating Necker Cube using Orthographic projection. This type of stimulus is in fact bistable, so perceptually the rotation direction of the Necker Cube will stochastically flip whilst watching it. 

(9) 3D stimulis with stereoscopic presentation

In the following demos you will learn how to render stereoscopic stimuli. We first start with simple demos which require no knowledge of OpenGL. We will then move onto demos which utilise OpenGL to do geometrically correct perspective projection. All demos will be set to render stereo using red-green anaglyph images, but can be switch to alternative methods by changing a single number. Note: You may experience some “ghosting” of the left and right eyes images, this is to be expected if your monitor is not calibrated to the anaglyph filters you are using and the displayed images.

Square In Depth Demo: This demo introduces stereoscopic presentation by rendering a random dot stereogram of a square positioned in a depth plane in front of the screen. In this simple demo we achieve this by shifting the position of dots in the left and right eyes in equal and opposite directions on the computer screen. This is not geometrically correct, but a good start for learning about rendering stereoscopic stimuli as you have direct access to the dot coordinates for each eyes image. To view the demo you will need red-green anaglyph glasses.

Square Moving in Depth Demo: This demo extends "Square in Depth Demo" by using an animation loop to render the square oscillating in depth about the plane of the monitor screen. This is acheived by moving the dots laterally (and in opposite directions) on each frame.

Slanted Surface Demo: This demo renders a random dot stereogram of a slanted surface. For this simple demo, this is achieved by laterally magnifying the positions of one eyes dots on the computer screen, so is therefore not full perspective correct projection.

Modulating Slant Demo: This demo extends "Slanted Surface Demo" by using an animation loop to render a 3D surface dynamically changing in slant over time.

Sine Wave in Depth Demo (NEW: Coming Soon): Renders a sine wave corrugated random dot surface, whereby the amplitude of the sine wave determines the depth of the points defining the surface.   

Stacked Circles Demo: Renders a random dot stereogram of a set of three "stacked" disks/circles, each progressively closer in depth. The demo shows some math related to sorting, filtering and modifying dot coordinates based upon set criteria. 

(10) Full Experiments

In this section we will use the full knowledge we have gained to code some simple experiments. This will allow you to see how to construct an experimental script and how to use standard psychophysical techniques such as the method of constant stimuli.

 

Stroop Task Demo: This page will talk you through designing a simple experiment with Psychtoolbox. We will use a standard example: the Stroop Task. Code will be provided and you will hopefully learn about how to structure a piece of experimental code.

Orientation Threshold Demo: This demo will show you how to get an orientation threshold using a two alternative forced choice experiment, with the method of constant stimuli.

Change Blindness Demo: This demo shows you a basic change blindness experiment where two pictures alternate with one another, separated by a blank screen. Either an object in the image changes colour, or disappears and reappears. Press the space bar when you see the change. The length of time it has taken you to see the change is recorded. The code file needs to be placed in the same directory as the folder of images, which can be downloaded here. This demo is a modified version of one by Krista Ehinger.

(11) Utility scripts

This set of code scripts is an assortment of useful peices of code that the lab uses. It is therefore a little eclectic in nature, but hopefully you will find some things useful.

 

Image Capture Demo: I am often asked how I go about capturing the images of PTB for this site. I use inbuilt functionality to do this. This demo shows you how.

Movie Capture Demo: I am often asked how I go about capturing the movies of PTB for this site. I use inbuilt functionality to do this. This demo shows you how. 

Gamma Correction Measurement (NEW: Coming Soon): This script demonstrates how to manually increment through full screen luminances for white, red, green and blue. The lab uses this in conjunction with a photometer to measure the gamma and luminance characteristics.

Gamma Correction Demo (NEW: Coming Soon): This script fits a Gamma curve to the data collected with the "Gamma Correction Measurement" code above. It also shows how to use the inverse of the fitted curve to linearise a monitor. Finally, it also allows one to caculate the numbers need to ensure equal luminances for different screen colours.

(12) Contributed Code

In this section I provide demos of code which has been contributed to the site. This can be either pure PTB code or code that can be used in cool ways in conjunction with PTB. All of the contributed code is free to use and modify, just as with all the other demos. In some cases, if you use the code in your own work, you should cite the academic papers on which the contributed code is based. If this is the case, it will be clearly stated in the code which has been contributed.

 

Log Gabor Filter Demo: This demo uses code contributed by Prof. Steven Dakin (University of Auckland) which implements a Log-Gabor filter (click here to download the file). The demo I've made uses Steven's code to filter a face image included in the PTB distribution. Various filter parameters are used and the original image and filtered images are displayed on the screen. The code cycles through various filtered images and displays the parameters of the filter used at the bottom of the screen. Full details of how the filter works, and the paper to cite if you use the technique, are provide in Steven's code.

Instagram image Instagram image Instagram image Instagram image Instagram image Instagram image