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 custom MATLAB code to transform the image. This together with the fact that any image can be shown makes picture elements the most general and flexible vehicle for static visual stimuli.

▸ Ends on its own?

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.





No defaults

Set one of:

fileName is a string that is name of picture 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 picture 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, 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.



Default: 8

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


Default: show whole picture

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


Default: 1 px in picture = 1 px on screen

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

OR a string setting overall size of the picture on screen:

<cds>"fit"  <cds> – fit picture to window
<cds>"fitw" <cds> – fit picture width to window
<cds>"fith" <cds> – fit picture height to window
<cds>"fill" <cds> – fill window with picture
<cds>"px"   <cds> – native resolution: 1 pixel in picture = 1 pixel on screen (scaled down if you use a partial screen window)

All the fit and fill options assume the picture is centered in the window.


Default: show a color picture in color

<cd>true<cd>/<cd>false<cd>: show a color picture in grayscale.


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 original image matrix, and must contain the transformed image matrix at the end of the code. image is an m × n × 1–4 L/LA/RGB/RGBA matrix with rows and columns corresponding to pixels. Generally the image matrix will be as loaded from the file or workspace based on fileName/dataExpr above. However an important difference is that all values will have been normalized to 0–1 (as opposed to 0–255 or some other range in the source). The other exception is if you set grayscale = <cd>true<cd> above then the image matrix will have been reduced to m × n × 1–2 L/LA.

Input properties all visual elements have


Input properties all adjuster elements have


Input properties all objects have


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.