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

(Edge artifacts)

Minor artifacts at the dot edge may be caused by the element display's default transparent background. These are usually insignificant. However, if you need to avoid them completely, you can set property backColor = <cds>"opaque"<cds> (okay if there is nothing for the element to occlude).

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

fileName
dataExpr
fps

No defaults: fileName, dataExpr
Default: fps = 120 frames/sec

Set one or both of fileName/dataExpr to specify the time series data to use. Data must be a 2×n matrix (see above).

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 which one to load. Default <cd>[]<cd> = get data from the base MATLAB workspace instead, in which case you must set dataExpr.

dataExpr is a string that is variable name and possibly indexes/field names containing a data set. You can use this to specify which one to load from a .mat file containing multiple data sets, or if the variable is in the base MATLAB workspace. Default <cd>[]<cd> = automatic if you load from a file that only contains one data set.

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 the data was recorded at (frames/sec). Note to change the speed of motion you can just use property speed 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.

OR

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.

dotSize

Default: 0.2 deg

Dot diameter (deg).

color

Default: white

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

times
showTimes

Defaults: load/show whole time series

times: A vector [t1 t2] (sec) to load only a specific time range from the time series. t1 = <cd>0<cd> = start of file, t2 = <cd>inf<cd> = end of file.

showTimes: Same but only affects what times are shown. The whole time range is still loaded and used for purposes like sizing and positioning the display (e.g. fitting data across the whole time within height above).

speed

Default: normal speed

Motion speed multiplier, including reverse. 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>: repeat 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.

position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars