picture

elements

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.

▸ Object ends on its own?

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.

Input properties

Adjustable properties

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.

position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars

(None)

fileName
dataExpr

No defaults

Set one of:

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.

e.g.
<cds>"pictureData"<cds>
<cds>"pictures{5}"<cds>
<cds>"albums.cats(2).pic"<cds>

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.

bitDepth

Default: 8

PsychBench automatically detects this for most images loaded from files. If it can't, or if you use dataExpr above to get the image from an image array, then you can specify bits per pixel channel (e.g. R, G, B) here. Usually leave at default = 8 (values between 0–255).

Or if you have multiple images in fileName/dataExpr above and need different bit depths for different images, you can use a vector.

crop

Default: show whole image

A 1×4 vector [x_tl y_tl x_br y_br] setting part of the image to show. +x = right, +y = down, <cd>[0 0]<cd> = top left of image. Units are px in the image file (independent of your screen or the size you show the image at). For right and bottom you can use <cd>inf<cd> to mean that edge of the image, e.g. <cd>[0 0 inf inf]<cd> = show whole image. Note other properties like height below are applied after crop.

Or if you have multiple images in fileName/dataExpr above and want different crops for different images, you can use an n×4 matrix.

height

Default: 1 px in image = 1 px on screen

A number that is height on screen to show at (deg).

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.

grayscale

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.

imageCode

Default: no custom transformation

You can set this to a string that is the name of a script (or just the whole script code) for PsychBench to evaluate to apply custom transformation(s) to the image. The code must use the variable image, which will contain the image matrix loaded by fileName/dataExpr above, and possibly reduced by properties crop and grayscale. **The one difference is that all values in image will be normalized to 0 = min / 1 = max (instead of e.g. 0–255).** The same variable image must contain the transformed image matrix (also using range 0–1) at the end of the code.

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.

positions
interval

Defaults: don't show multiple images

If you have multiple images in fileName/dataExpr above, set one of these properties to determine how to show them:

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.

rotations

Default: no rotation of each of multiple images

If you have multiple images and set positions above to arrange them spatially, you can specify a rotation to apply to each of them here. This is orientation clockwise (from +x to +y screen axis) about image center (deg). You can also use a vector for different rotations for different images. Note you can still set property rotation for the whole element display.

rotations doesn't apply for temporally ordered images (interval above).

repeat
breakInterval

Default: repeat = repeat sequence of multiple images until a condition you set in property end
Default: breakInterval = no interval between repetitions

If you have multiple images and set interval above to order them temporally, you can set repeat options here:

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.

nn_images

Default: show each image in fileName/dataExpr once and in that order

If you have multiple images in fileName/dataExpr, you can set nn_images to a vector of numbers pointing to them. The images will then fill into positions and intervals above in that order. What makes this useful is that you can repeat images in the arrangement/sequence by repeating numbers in the vector. For temporally ordered images only (interval), you can also include 0's to mean breaks where nothing shows.

Record properties

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.