dotPath

elements

A dot moving on any 2-D path. Each element is based on time series data that is a 2×n matrix: x, y coordinates (rows) × images (columns). Default frame rate = 120 frames/sec. An example data set is included in a file called dotPathData.mat in <PsychBench folder>/docs/element.

Note the standard Psychtoolbox/PsychBench screen coordinate convention applies: +x = right, +y = down on screen (like reading). If your data has +y = up, just set property flipVert = <cd>true<cd>.

▸ Object ends on its own?

By default no, repeats until a condition you set in property end. However, if you set repeat = <cd>false<cd>, ends on its own at the end of the motion data.

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
fps
times

No defaults: fileName, dataExpr
Default: fps = 120 frames/sec
Default: times = load whole dot path

These properties point to the the time series data to use, which is a 2×n matrix (see above). You can load the data from a file or get it from a variable in the base MATLAB workspace:

fileName is a string that is name of a .mat file containing the data. 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). The file can contain multiple data sets—if so, use dataExpr below to specify. <cd>[]<cd> = don't load from file—get data from the base MATLAB workspace.

dataExpr is a string that is variable name and possibly indexes/field names to get to the data. Set this to load from a file containing multiple data sets or to get from the base MATLAB workspace.

e.g.

fileName = <cds>"data.mat"<cds>
-> data in file data.mat, which contains only one data set

fileName = <cds>"data.mat"<cds>
dataExpr = <cds>"dataVar{2}"<cds>
-> cell 2 of cell array dataVar in file data.mat

dataExpr = <cds>"dataVar"<cds>
-> variable dataVar in base MATLAB workspace

dataExpr = <cds>"dataVar{2}"<cds>
-> cell 2 of cell array dataVar in base MATLAB workspace

fps is frame rate of the data (frames/sec), i.e. 1/fps = time interval between points in the data. Note to change the speed of motion you can just use property speed below.

times is a vector [t1 t2] (sec) to load only a specific time range in the dot path. t1 = <cd>0<cd> = start of file, t2 = <cd>inf<cd> = end of file. Note you can also leave this property at default and use showTimes below instead to show only part of the path while still using all of it for purposes like sizing and positioning the display (e.g. fitting the whole path within height below).

height
sizeMult

Default: show at 10 deg height

Set either height (absolute size) or sizeMult (relative size):

height sets height directly (deg). Here height is the greatest vertical distance spanned by the dot across time.

sizeMult is a conversion factor from whatever distance units the data is in to deg visual angle. i.e. the conversion factor has units deg visual angle / data distance units, and just multiplies the data. sizeMult is useful when you want to preserve relative sizes between different data sets by setting it equal across different dotPath elements.

showTimes

Default: show whole dot path

A vector [t1 t2] (sec) to show only a specific time range in the dot path. t1 = <cd>0<cd> = start of file, t2 = <cd>inf<cd> = end of file. Note the whole path is still used for purposes like sizing and positioning the display (e.g. fitting the whole path within height above). To set a time range for all purposes, use times above instead.

speed

Default: normal speed

Motion speed, including reverse motion. 1 = normal, 0.5 = half speed, 2 = double speed, -1 = reverse normal, etc.

repeat
breakInterval
phase

Default: repeat = repeat until a condition you set in property end
Default: breakInterval = no interval between repetitions
Default: phase = start at start

repeat = <cd>true<cd>/<cd>false<cd>: show 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 dot path.

breakInterval sets an interval between repetitions (sec). 0 = none.

If repeat = <cd>true<cd>, you can set phase to specify a start time in the dot path (sec). 0 = start. If you also set times or showTimes above, phase is relative to start of the time range you specify there.

dotSize

Default: 0.2 deg

dotSize is dot diameter (deg). 0 = don't show dots.

color

Default: white

A 1×3 RGB vector with numbers between 0–1.

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.