Visual elements include visual stimuli as well as elements that use other kinds of screen-based functionality like mouse. They all have the properties below setting a range of core visual options.
See the visual elements tutorial in <PsychBench folder>/docs/tutorials.
Default: position = screen center
Default: layer = 0 (doesn't matter if element won't overlap with other elements)
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.
To set drift or movement, you can use property vary.
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
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 color
Often you can set color directly in a type-specific property (e.g. color) instead. colorMask is useful for elements where the image(s) are read from a file or data and color can't be set directly, e.g. in picture or movie elements. Another difference is that colorMask is usually adjustable (so you can apply property vary or an adjuster element to it) whereas type-specific color properties often are not.
Default: no additional transparency
Note regardless of this property some elements have a fully transparent background and/or specific parts of their display that have some level of transparency. In general alpha applies an additional multiplication of transparency at the level of the whole element. If the element has any visible background and you want to change the transparency of that specifically, use property backColor below instead. Some elements also allow setting transparency for other parts of their display with type-specific properties—see element type documentation.
Default: normal
A number ≥ 0 multiplying the RGB intensity of the element. < 1 = decrease brightness, 1 = normal, > 1 = increase brightness. Note often you can set brightness more directly through type-specific properties setting color.
Default: normal
Or a vector [mult mean] if you want to use a different mean intensity value. Currently PsychBench cannot automatically detect actual mean intensity values for use with this property.
The transformation at each pixel is:
rgb = (rgb-mean)*mult+mean
Default: no convolution
Note if you use convolution, 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 still affects pixels near its edges since PsychBench pads the element display with this color. By default fill color is the same as trial background color. If you want to use a different color, you can set property backColor below (must be opaque).
Default: no generated kernel
type is a string <cdsm>"average"<cdsm>, <cdsm>"disk"<cdsm>, or <cdsm>"gaussian"<cdsm> to tell PsychBench to use a symmetric convolution kernel of that type. You then need to set size and other parameters in further fields below:
size is width of the symmetric kernel. Convolution is applied at the resolution the element shows at on screen. As such, kernel size is a distance on screen, so by default it’s in deg units as usual. The resulting size will round up to an odd integer number of px on screen. Note if you want to set size in px units, you can use <cdm>{value, <cdm><cdsm>"unit"<cdsm><cdm>}<cdm> form directly in the field, e.g. convolution.size = <cdm>{value, <cdm><cdsm>"px"<cdsm><cdm>}<cdm>.
sigma (type = <cdsm>"gaussian"<cdsm> only): This is standard deviation of the Gaussian. Again this is a distance on screen, by default in deg but you can specify other units like px directly in the field if you want. For type = <cdsm>"gaussian"<cdsm>, you can set either size or sigma, and the other will default such that size = 4 × sigma. You can also set both if you want a different ratio.
Note if you use filterResolutionMult below to apply the convolution at a resolution lower than screen resolution, PsychBench will automatically scale size and sigma down. So, always set them assuming convolution at screen resolution.
type requires the MATLAB Image Processing Toolbox.
Default: no custom kernel
If you don’t have the Image Processing Toolbox or want to use a different kernel than one of the above, you can directly specify any kernel as a 2D matrix in kernel instead. Specifically this is a correlation kernel like those generated by fspecial (it will be rotated 180 deg at application to implement convolution). Pixels in the kernel correspond to pixels at screen resolution. Like a MATLAB image matrix, rows correspond to height and columns to width. The kernel must be an odd integer number of px wide and high (not necessarily symmetric). If the kernel is separable, you can use a 1×2 cell array containing x and y kernels for greater efficiency.
Note if you use filterResolutionMult below to apply the convolution at a resolution lower than screen resolution, PsychBench does not scale your custom kernel down. You must set it assuming convolution at the lower resolution.
(Coming soon)
Default: same gamma decoding as rest of the experiment
See screen object property gamma for more information. See also filterGamma below.
Default: filterOrder = noise → convolution → intensity → contrastMult → gamma
Default: filterGrayscale = don't assume grayscale element display
Default: filterResolutionMult = filter at screen resolution
Default: filterGamma = apply filters to standard gamma-encoded RGB
filterGamma can be one number for simple power law gamma decoding/re-encoding (e.g. the standard 2.2). Or it can be an n×3 matrix with columns corresponding to RGB color channels, rows corresponding to input intensities (e.g. for 1024 rows: 0, 1/1024, 2/1024, ... 1), and numbers = output intensities between 0–1.
filterGamma doesn't change the gamma decoding that is actually applied to the element display—for that use element gamma above or screen object gamma. You can also mix using filterGamma with element or screen gamma. Element gamma always comes after filterGamma, and then screen gamma after that.
Default: same as experiment window
Intensity/Color resolution for the element display (bits/pixel). The most common value is 32 bits/px, corresponding to 8 bits (256 levels) per RGBA color component. Possible higher resolutions are 64 bits/px (16 bits/component) and 128 bits/px (32 bits/component). Generally you can leave this at default = same as experiment window, since pixel resolution of an element display is eventually limited by pixel resolution of the window (usually 32 bits/px). However, in unusual cases you may want to set it higher than the window to facilitate pre-window processing. Note this property has no effect for a stimulus sourced from a file with its own pixel resolution, e.g. a movie element showing a movie file.
If the element display has low dynamic range at low levels (e.g. levels 15–20 out of 256 at 32 bits/px) and you apply a filter like intensity that scales it up to e.g. 150–200, it would remain quantized into 6 levels but the quantization would then be easily visible. To fix this you could set the element's pixel resolution = 64 or 128 such that the same initial range would be quantized into 6,144 or 100,663,296 levels, which would continue to look smooth when scaled up.
Default: transparent RGBA <cd>[0 0 0 0]<cd>
In unusual cases you might want to specify an opaque background. For example, the default transparent background can cause artifacts in some element displays with antialiased edges or other transparency (see the element type documentation). You can set backColor = a string <cds>"opaque"<cds> to make it opaque matching trial background color. You can also use any custom opaque color by setting a 1×3 RGB vector with numbers between 0–1.
PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results by listing them input property report.
PsychBench © 2017–2023 Giles Holland
Website © 2023 Giles Holland
End user license agreement