picture

 element objects

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.

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

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

Input properties
Record properties
picture
elements (see below)

fileName
dataExpr
bitDepth
crop
height
grayscale
imageCode
positions
interval
rotations
repeat
breakInterval
nn_images

All visual elements
position
depth

nn_eyes
rotation
flipHorz
flipVert

colorMask
alpha
intensity
contrastMult
convolution
shader
filterOrder
filterGrayscale
filterResolutionMult
filterGamma

channelResolution
backColor
addDisplay

All visual elements
position

All adjuster elements have
adjust

All elements
start
end

startBuffer
endBuffer

vary
staircase

All objects
report
info

fileName
dataExpr

No defaults

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.

OR

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 for repetition or to insert break intervals.

bitDepth

Default: automatic for most images loaded from files, else 8 bits/channel

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 (pixel channel 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 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.

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. + = right⁠/⁠down and 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.

Adjustable properties

You can vary or allow the subject to adjust the following properties of an object of this type when it's running. If you need to make other properties adjustable, you can edit the element type code—see Element Type Programming Manual.

Adjustable properties

Adjustable properties

position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars

(None)

(None)

Input properties
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 using input property report.

picture
elements (see below)

All elements
startTime
endTime
duration
n_startFrame
n_endFrame
startLatencyBufferable
endLatencyBufferable