Configuring Stimuli

Opticka uses many different stimulus classes that are collected together using a metaStimulus class. The order of the stimulus in the list defines the z-index at which it is drawn (higher number gets drawn on top of lower number). Stimuli collected into a metaStimulus can then be controlled as a single object. In this code for example:

d = dotsStimulus('XPosition', 5, 'mask', true); %coherent dots
f = fixationCrossStimulus('alpha', 0.5); %fixation cross
stims = metaStimulus();
stims{1} = d; 
stims{2} = f;

We have two stimuli, and by default draw(stims) will draw both the coherent dots and the fixation cross in one single command. You can then do things like hide/show one or all stimuli:

hide(stims); % hide all stims
show(stims, 2); % set the 2nd stimulus (fixationCross) to be shown.
draw(stims); %now only 2nd stimulus will actually be drawn

These commands can be run via the stateInfo file. The GUI allows you to add and order stimuli into this metaStimulus manager.

Adding & Editing Stimuli

You can start by selecting a stimulus type from the “Stimulus” menu. You should now see a stimulus panel with individual properties on the right. For example fixationCross has a colour property which defines the disc colour and colour2 which defines the cross colour. For each stimulus in the list you can edit all these properties. When you are happy with the settings, you Add it to the stimulus list. The GUI panel on the right updates as you select different stimuli in the stimulus list. You can continue to edit all properties by selecting the stimulus in the list and editing the values.

To move stimuli up or down the list (affecting in what order the stimuli are drawn) use the ↑ and ↓ icons.

Previewing Stimuli

• ▷ Run a single stimulus in an onscreen window to preview how it will look.
• ▷⚡️ Benchmark run a single stimulus. See command window for FPS.
• ▶︎ Run all stimuli in an onscreen window to preview how they will look.
• ▶︎⚡️ Benchmark all stimuli. See command window for FPS.

Common Base Properties

All stimulus classes inherit from baseStimulus, which provides a shared set of properties. These can all be used as task variables (nVar names):

The *Out Dynamic Property System

During setup(), each public property (e.g. size) is cloned into a transient dynamic property (sizeOut). The *Out version holds the runtime, pixel-converted value. When task variables are applied, they write to the *Out properties. On reset(), these dynamic properties are removed.

This means:

• In the GUI and state info files, you set size, angle, etc. — these are the design-time values
• At runtime, sizeOut, angleOut, etc. hold the actual values being used (which may differ due to task variable changes)
• When using edit(stims, N, property, value) during a task, use the *Out version: edit(stims, 3, 'sizeOut', 2)

The xyPosition Magic Variable

When defining task variables, you can use the special name xyPosition which allows you to pass both X and Y positions in a single variable value. The value should be a cell array of [x, y] pairs:

task.nVar(1).name = 'xyPosition';
task.nVar(1).values = {[5 0], [0 5], [-5 0], [0 -5]};
task.nVar(1).stimulus = 1;

This sets both xPositionOut and yPositionOut from a single variable. You can also use the Equidistant Points button to generate these values automatically.

Stimulus Types

Opticka provides the following stimulus classes. Each has unique properties beyond the common base properties listed above. Key distinguishing properties are listed for each type.

Grating Family Properties

The grating stimuli (gratingStimulus, gaborStimulus, colourGratingStimulus, checkerboardStimulus, polarGratingStimulus, polarBoardStimulus) share these common properties:

Dots Stimulus Properties

Accessing Individual Stimuli

Use cell indexing on the metaStimulus object to access individual stimulus objects directly:

stims{1}          % first stimulus object
stims{2}.angleOut % runtime angle of second stimulus
stims{3}.filePath % image path of third stimulus
stims.n           % number of stimuli in the group

You can call methods on individual stimuli too:

stims{1}.resetTicks()          % reset frame counters
stims{3}.randomiseSelection    % randomise image selection for imageStimulus