All visual elements

Visual elements include visual stimuli as well as element that use other kinds of screen-based functionality like mouse. They all have the properties below setting a range of core visual options. (Some unusual element types ignore some of these properties—if something doesn't work, see the element type documentation for if this is the case.)

Input properties all visual elements have


Default: position = screen center
Default: layer = 0 (doesn't matter if element won't overlap with other elements)

position is a vector [x y] setting element position on screen (deg). + = right⁠/⁠down (like reading), <cd>[0 0]<cd> = screen center. Typically elements center at this point, but see element type documentation for exceptions.

You can also set the element to drift or move on any time-dependent path using a string that is any MATLAB expression for PsychBench to evaluate during the experiment to return current position. The expression can use the variable t , which will contain time relative to element start (sec). If you need multiple lines of code, the string can be the name of a script that makes a variable ans containing a position. Note you can combine string syntax with non-deg units: <cd>{<cd><cds>"expr"<cds><cd>, <cd><cds>"unit"<cds><cd>}<cd>.

layer is a number setting element layering on screen. + = backward (away from viewer), − = forward (toward the viewer). Absolute values don’t matter, only relative. You can ignore layer for element displays that won’t overlap.


element.position = [2 0]

→ 2 deg right from screen center

element.position = {[-400 -400], <cdsm>"px"<cdsm>}

→ 400 px left and up from screen center

element.position = <cdsm>"[-5+mod(2*t, 10) sin(pi*t)]"<cdsm>

→ move right on a sinusoidal path and wrap around


Default: show on both eyes

If you turn on stereo display (screen object property stereo) use this property to set whether the element is on left eye (<cd>1<cd>), right eye (<cd>2<cd>), or both eyes (a vector <cd>[1 2]<cd>). The other position properties above apply as usual within each eye.


Default: no rotation

Element orientation clockwise (from +x to +y screen axis) about position (deg).


Defaults: don't flip

<cd>true<cd>/<cd>false<cd>: flip element horizontally/vertically. Note if you want to flip the whole display for the experiment, use screen object properties flipHorz, flipVert instead.


Default: normal

A number ≥ 0 multiplying the intensity (pixel values) of the element. < 1 = decrease brightness, 1 = normal, > 1 = increase brightness. Note often you can set brightness through type-specific properties like color. If so, it’s better to do it that way. This property is for when that’s inconvenient or impossible.


Default: no additional transparency

A number between 0–1 applying transparency to the element. 0 = fully transparent (invisible), 1 = no additional transparency. Note many elements have a transparent background regardless of this property.


Default: filterLevel = no blur or other convolution filter
Default: filterType = Gaussian
Default: filterKernel = no custom convolution filter
Default: filterBackColor = same as trial background color
Default: filterResolution = filter at resolution on screen

You can apply blur or some other convolution filter to an element using these properties:

filterLevel + filterType: filterLevel is a number: 0 = no filter, > 0 = increasing filter. Level sets the size of the convolution filter kernel, i.e. the size of the square averaging neighborhood around each pixel to effect the blur. Specifically what filterLevel means depends on filter type, which you can set using a string in filterType:

<cds>"box      " <cds> – filterLevel = kernel width

<cds>"disk     " <cds> – filterLevel = kernel diameter

<cds>"gaussian " <cds> – filterLevel = kernel standard deviation σ; kernel width = 4 × σ.
<cds>            <cds> or
<cds>            <cds> – filterLevel = 1×2 vector [σ, width]

In all cases filterLevel is a distance on screen, so by default it’s in deg units. The resulting kernel width will round up to an odd integer number of px on screen. If you want to specify filter level directly in px, you can do the usual <cd>{value, <cd><cds>"px"<cds><cd>}<cd>.

Note filterLevel requires the MATLAB Image Processing Toolbox.

filterKernel: If you don’t have the Image Processing Toolbox or want to use your own filter, you can specify any kernel as a 2D matrix in filterKernel instead. Filter type(s), parameters, and size are then defined directly at the pixel level by the values and dimensions of the matrix. A custom kernel must be an odd integer number of px wide and high (not necessarily square). If the kernel is separable, you can use a 1×2 cell array containing x and y kernels, which is more efficient. Note if you set filterResolution below to a value < 1 then filterKernel is in the downsampled space.

filterBackColor: If you enable a filter, PsychBench needs to fill any transparent parts of the element background with a solid color to blend with. Even if the element doesn’t have any transparent background, this can affect pixels near its edges. filterBackColor is a 1×3 RGB vector with numbers between 0–1 setting this color. Or <cd>[]<cd> = same as trial background color.

filterResolution is a number between 0–1 defining the resolution at which the filter is applied. 1 = resolution the element shows at on screen. < 1 applies the filter to a version of the element that is downsampled relative to what it will be on screen, e.g. 0.5 = half resolution, then scales the result up to show on screen. This makes the filter faster but comes at a cost of reduced image quality. Leave at default = 1 unless needed to avoid dropped frames.

Input properties all objects have


Record properties all visual elements have

PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results using input property report.