Display stimuli / integrate in experiments#

stimupy is a package which is focused on generating stimuli, separate from stimulus display, use, experimentation, etc. Hence, stimupy is designed agnostic to how stimuli are used after stimulus generation, which allows for a broad range of uses. Principally, the stimulus image is stored as a matrix of intensity values, in a bare numpy.ndarray. Thus, using a stimupy stimulus in an application just requires the possibility to input a numpy.ndarray.

PsychoPy-based display#

PsychoPy is a leading stimulus display and experiment development package for the Python ecosystem. It provides lots of functionality for running experiments, interfacing with hardware and some stimulus-drawing capabilities. Most of the stimulus-drawing is done using an OpenGL backend directly in the screen buffer. While this approach is very fast and accurate, its difficult to create complex stimulus images, such as the ones implemented in stimupy. For these kinds of stimuli, PsychoPy can display predefined digital images as a static texture using the ImageStim function:

stim = psychopy.visual.ImageStim(my_window, image=my_numpy_array)

To use stimupy stimuli in PyschoPy experiments, then, is quite straightforward and requires no e.g. additional exporting of the stimulus:

  1. Set up experiment using PsychoPy

    1. Set up the screen/window information

  2. Generate the stim using stimupy code

  3. Create the PsychoPy ImageStim from the stim["img"]-array

  4. Display the ImageStim in the PsychoPy experiment.

Warning

stimupy is designed for flexibility, robustness, and ease of use – not for speed. Some of the quality-of-life features have some processing overhead, e.g., automatic resolution resolving. As a result, stimupy stimulus functions may be slower than generating equivalent stimuli using OpenGL based rendering. If speed is of the essence, you may want to pregenerate all your stimupy stimuli before the experiment-loop, such that displaying a stimulus is just a single lookup.

PsychToolBox-based (MATLAB) display#

PsychToolBox (PTB) is the MATLAB progenitor of the PsychoPy. It provides lots of functionality for running experiments, interfacing with hardware and some stimulus-drawing capabilities. Most of the stimulus-drawing is done using an OpenGL backend directly in the screen buffer. While this approach is very fast and accurate, its difficult to create complex stimulus images, such as the ones implemented in stimupy. For these kinds of stimuli, PTB can convert a (predefined) digital image from an array to a static texture and then display it, using the Screen(‘MakeTexture’) function:

% Convert my_stim_array to a PTB texture
stim_texture = Screen('MakeTexture', my_window, my_stim_array);

% Put texture on screen
Screen('DrawTexture', my_window, stim_texture);

To use stimupy stimuli in PyschoPy experiments then requires creating the stimuli in, and exporting them from Python, and importing them into MATLAB for display:

  1. Generate the stim using stimupy code (Python)

  2. Export the stim, e.g. to .mat file (Python)

  3. Set up experiment using PTB (MATLAB)

    1. Set up the screen/window information

  4. Import the stim in MATLAB, e.g.:

    % Load from .mat file into a struct
my_stim = load('path_to_my_stim_file.mat');

  5. Create the PTB texture from the img-array:

    % Convert my_stim_array to a PTB texture
stim_texture = Screen('MakeTexture', my_window, my_stim.img);

  6. Display the texture in the PTB experiment