VisualStimulusToolbox

A lightweight Matlab toolbox for generating, storing, and plotting 2D visual stimuli related to vision and neuroscience research such as sinusoidal gratings, plaids, random dot fields, and noise.

DOI

View the project on GitHub UCI-CARL/VisualStimulusToolbox

View other projects by UCI-CARL uci-carl.github.io

Table of Contents

Overview

VisualStimulusToolbox provides a free set of MATLAB functions for vision and neuroscience research. The toolbox allows for the easy creation, manipulation, plotting, and storing of visual stimuli such as drifting sinusoidal gratings, drifting plaids, drifting bars, random dot clouds, as well as their combinations. Every stimulus can be plotted, recorded to AVI, and stored to binary.

The toolbox is a lightweight alternative to the more comprehensive Psychophysics toolbox.

VisualStimulusToolbox was originally created to provide an easy way to important visual stimuli to the CARLsim spiking network simulator. As of CARLsim 3.0, it is straightforward to convert VisualStimulus .dat files to spike trains that can serve as input to CARLsim simulations. However, the toolbox can be used independently.

If you use this code in a scholarly article, please cite as follows:

Beyeler, M. "Visual Stimulus Toolbox". Zenodo, June 22, 2016. doi:10.5281/zenodo.154061.

Installation

You can view and manage installed add-ons in MATLAB R2016a using the Add-On Manager. To open the Add-On Manager, go to the Home tab, and select Add-Ons > Manage Add-Ons.

In older MATLAB versions (before R2015b), simply add the directory VisualStimulus/VisualStimulusToolbox to your MATLAB path, and you are good to go.

Getting Started

VisualStimulusToolbox provides a number of classes for creating, plotting, and storing visual stimuli such as:

Creating Your First Stimulus

A stimulus is intantiated by passing the desired stimulus [height, width] to the constructor:

>> dot = DotStim([120 160])
    DotStim with properties:

    width: 160
    height: 120
    channels: 1
    length: 0
    stim: []
    supportedNoiseTypes: {'gaussian','localvar', 'poisson',
        'salt & pepper', 'speckle'}

Frames can then be added using the method add, by specifying drift direction (in degrees) and speed (in pixels/frame) as well as some other stimulus-specific options (e.g., dot density, dot coherence, dot size, etc.): 

>> numFrames = 10;
>> dotSpeed = 1;
>> for dirDeg=(0:7)*45
    dot.add(numFrames, dirDeg, dotSpeed);
   end
>> dot.plot;

This will create a stimulus made of a total of 80 frames, where dots drift into one of eight directions (in 45 degree increments) for 10 frames each.

During plotting, key events can be used to pause, stop, and step through the frames.

Internally, the stimulus is stored as a 4D array. For example, grayscale stimuli have one channel, and RGB stimuli have three channels. The raw data array can also be accessed directly: 

>> rawData4D = dot.stim;

Color stimuli can be created by passing a ColorSpec string to the constructor:

>> dot = DotStim([120 160], 'r')
    DotStim with properties:

    width: 160
    height: 120
    channels: 3
    length: 0
    stim: []
    supportedNoiseTypes: {'gaussian','localvar', 'poisson',
        'salt & pepper', 'speckle'}

Currently, the following color specs are supported: 'k' (black), 'b' (blue), 'g' (green), 'c' (cyan), 'r' (red), 'm' (magenta), 'y' (yellow), and 'w' (white).

A stimulus can also be converted to an AVI movie or stored as a binary file (see below).

Manipulating an Existing Stimulus

Every stimulus type also comes with a number of handy helper methods:

Combining Different Stimulus Types

Stimulus types can be combined to create compound stimuli. Use optional input arguments to the constructor for fast stimulus generation. For example, to combine 5 frames of drifting sinusoidal grating (120x180 pixels, red, drifting upwards and to the right at a 45 degree angle) with 8 frames of a drifting random dot cloud (90x120 pixels, blue, drifting rightwards at a 0 degree angle), use the following one-liner: 

>> r = GratingStim([120 180],'r',5,45) + DotStim([90 120],'b',8,0)

If the two stimuli have distinct canvas dimensions, the second stimulus will be resized to match the first stimulus' [height width]. If any of the two stimuli have more than one color channel (e.g., RGB), the result will also have more than one color channel.

Recording AVI

Every stimulus type can be converted to an AVI movie using the record method by specifying a desired file name and frame rate: 

>> dot.record('myMovie.avi', 10); % 10 frames per second

Saving / Loading

Every stimulus type can be stored to a binary file, which can be loaded at a later point:

>> dot.save('mySavedStim.dat');
>> newDot = DotStim;
>> newDot.load('mySavedStim.dat');

Make sure the two stimuli are the same:

>> assert(all(oldStim(:) == newDot.stim(:)))

Acknowledgment

Some of this code is based on scripts initially authored by Timothy Saint (saint at ncs dot nyu dot edu) and Eero P. Simoncelli (eero dot simoncelli at nyu dot edu) at NYU for generating sinusoidal gratings, plaids, and random dot clouds.

These scripts were released as part of the Motion Energy model in 2005, which was released without stating any software license restrictions. Their contributions are attributed at relevant places in the source code.