One or more images from image files (jpeg, bmp, etc.) or MATLAB image arrays. In addition to the usual options all visual elements have, picture property imageCode allows applying any MATLAB code to transform the image(s).

Often you will want to use your own images. However, some collections of standard images are available in <PsychBench folder>/materials.

To show multiple pictures in a sequence, use a sequence element. To show multiple pictures as frames of a movie, use tool images2movie in <PsychBench folder>/tools to render them into a movie file and show it using a movie element.

(Transparency artifacts)

In the unusual case that you draw multiple pictures in the same picture element and they overlap and the top ones have transparency, you need to set property backColor = <cds>"opaque"<cds> for accurate display.

No—runs until a condition you set in property end.

fileName
dataExpr

No defaults

Set one of fileName OR dataExpr:

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. [Note: imread is relatively slow and this can cause long experiment startup times in the case that you use many different large images in an experiment. One way to minimize this effect is to shrink the image files to just the sizes you need them on screen (px) beforehand, so the files imread reads are as small as possible without sacrificing final display quality.]

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. Default <cd>[]<cd> = get image using fileName instead.

Or if you use positions below to show multiple images, you can use a string or cell array for either/both of fileName and dataExpr to set different values for different images.

bitDepth

Default: automatic for images loaded from files, 8 bits/channel for images from image matrixes

If you use dataExpr above to get the image from an image array, you can specify bits per pixel channel (e.g. R, G, B) here. Usually leave at default = 8 (pixel channel values between 0–255). Ignored for images loaded from files, where PsychBench automatically detects bit depth.

Or if you use positions below to show multiple images, you can use a vector for different bit depths.

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. Other properties like height below are applied after crop. The cropped part of the image is shown centered at position.

Or if you use positions below to show multiple images, you can use an n×4 matrix for different crops.

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 use positions below to show multiple images, you can use a vector, string array, or cell array of numbers and strings for different sizes.

grayscale

Default: show in color (for a color image)

<cd>true<cd>/<cd>false<cd>: show image in grayscale. Or if you use positions below to show multiple images, you can use a 1×n array for different grayscale settings.

imageCode

Default: no custom transformation

You can set this to a string that is the name of a MATLAB 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.

Or if you use positions below to show multiple images, you can use a string or cell array for different custom code.

positions

Default: show one image centered at element position

If you want to show multiple images at the same time, you can set that here. This is more efficient than using multiple picture elements. positions is a 2-column matrix setting centers for the images, with rows corresponding to images and columns to [x y] coordinates (deg). + = right⁠/⁠down and positions are relative to element position, which you can set in position (default window center). Images are also layered front to back in the order you list them.

If you show multiple images then for each of the other properties above and below you can set one value for all of them, or different values for different images using a vector or matrix (see property).

rotations

Default: no rotation of each image

If you use positions above to show multiple images, you can apply rotation to each one here. This is rotation clockwise (from +x to +y screen axis, with +y down) about respective image center (deg). Or you can use a vector for different rotations. Note you can still use property rotation to rotate the whole element display, i.e. all the images as a set.

position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars