"Ends on its own" means ends automatically at that point. 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).

position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars

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. 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>

An image matrix has dimensions height px (rows) × width px (columns) × 1/2/3/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.

For either fileName and dataExpr you can also 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 for PsychBench to run to apply custom transformation(s) to the image. The code must reference a 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

Tip: 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, image code applies to each of them independently.

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.

OR

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.

Input properties all objects have

report
info

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.