An image from an image file (jpeg, bmp, etc.) or MATLAB image array. In addition to the usual options all visual elements have, picture property imageCode allows applying any MATLAB code to transform the image(s).
You can also show multiple images, either arranged spatially or shown in a sequence across time. This is more efficient than using multiple picture elements. It also allows timing like repeating sequences, e.g. for change blindness experiments. Note you could also use this to show a sequence of images as a movie by setting interval very short (e.g. 1/30 sec for a 30 fps movie)—however, if you want to do that, typically it's more efficient to use a third party tool to render the images into a movie file and use a movie element instead.
For one image or multiple images arranged spatially: No, the sequence repeats until a condition you set in property end.
For multiple images in a sequence across time: By default no. However, if you set repeat = <cd>false<cd>, it ends on its own after one pass.
If an element can end on its own, you don't need to set end conditions for it in property end (unless you want it to maybe end earlier).
No—runs until a condition you set in property end.
You can vary or allow the subject to adjust the following input properties of an object of this type in real time when it's running. If you need to make other properties adjustable, you can edit the element type code—see Element Type Programming Manual.
fileName is a string that is name of an image file to show. Include path if the file is not in the MATLAB current folder or search path (or not the first file with that name on the search path). File can be any format MATLAB imread accepts.
dataExpr: Use this to get the image from an image matrix in the base MATLAB workspace. The matrix has dimensions height px (rows) × width px (columns) × 1, 2, 3, or 4 (1 = L, 2 = LA, 3 = RGB, 4 = RGBA). By default values should be 0–255 (i.e. 8 bits/channel), but you can change this using bitDepth below. dataExpr is a string that is the expression pointing to the data. This can be just a variable name, or it can include indexes, field names, etc.
For both you can use a string array for multiple images. In that case set either positions or interval below to arrange the images spatially or temporally, and optionally nn_images.
Or if you have multiple images in fileName/dataExpr above and need different bit depths for different images, you can use a vector.
Default: show whole image
Or if you have multiple images in fileName/dataExpr above and want different crops for different images, you can use an n×4 matrix.
Default: 1 px in image = 1 px on screen
OR a string setting overall size of the image on screen:
<cds>"fit" <cds> – fit to window
<cds>"fitw" <cds> – fit width to window
<cds>"fith" <cds> – fit height to window
<cds>"fill" <cds> – fill window
<cds>"px" <cds> – native resolution: 1 pixel in image = 1 pixel on screen (scaled down if you use a partial screen window)
All the fit and fill options assume the image is centered in the window.
Or if you have multiple images in fileName/dataExpr above and want different sizes for different images, you can use a vector, string array, or cell array of numbers and strings.
Default: show in color (for a color image)
<cd>true<cd>/<cd>false<cd>: show image in grayscale. If you have multiple images in fileName/dataExpr above, this applies to all of them.
Default: no custom transformation
image is an m × n × 1–4 L/LA/RGB/RGBA matrix:
L (luminance) = grayscale
LA (luminance alpha) = grayscale with transparency
RGB (red green blue) = color
RGBA (red green blue alpha) = color with transparency
If in doubt, you can include a <cd>size(image)<cd> statement with no semicolon in the code, quit the experiment (Ctrl+Esc), and check the output in the MATLAB command window.
If you have multiple images in fileName/dataExpr above, this applies to each of them.
Defaults: don't show multiple images
positions arranges the images spatially. This is an n×2 matrix containing [x y] positions (deg). Rows correspond to images in fileName/dataExpr, or to images in nn_images below if you set that. Positions are relative to element position, which you can set in position (default relative to screen center). Images are also layered front to back in the order you list them.
interval shows the images in a sequence across time. This is interval to show each image for (sec). Or you can use a vector for different intervals for different images—in that case numbers correspond to images in fileName/dataExpr, or to images in nn_images below if you set that.
Default: no rotation of each of multiple images
rotations doesn't apply for temporally ordered images (interval above).
Default: repeat = repeat sequence of multiple images until a condition you set in property end
Default: breakInterval = no interval between repetitions
repeat = <cd>true<cd>/<cd>false<cd>: show the sequence indefinitely by repeating until a condition you set in property end. If <cd>false<cd>, the element ends on its own at the end of the sequence.
breakInterval sets an interval between sequence repetitions (sec). 0 = none.
Default: show each image in fileName/dataExpr once and in that order
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.