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

("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

Defaults: 10 deg

Set one of height OR sizeMult:

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.

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, t2 = <cd>inf<cd> = end.

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 it within height above).

You can also use both properties if you want to use a time range for sizing and positioning and then only show a shorter range within that. In this case numbers in showTimes are relative to the time range set in times.

If you combine with maxNumLoops/breakInterval/phase below, those properties work within the part of the time series specified here.

maxNumLoops
breakInterval
phase

Default: maxNumLoops = repeat until a condition you set in property end
Default: breakInterval = no interval between loops
Default: phase = start at start of time series

maxNumLoops is a number > 0 that is number of loops through the time series or time range to show, after which the object ends. Note this number can be fractional, not just integer. <cd>inf<cd> = repeat until a condition you set in property end.

breakInterval is blank interval to show between loops, at the end of the time series or time range (sec). 0 = none.

phase is start time in the time series or time range (sec). 0 = start. phase is best used to set a starting point for a looping stimulus. If you just want to show the time series from a certain point to its end (or from a certain point to its start playing in reverse), use times/showTimes above instead with maxNumLoops set = 1.

speed

Default: normal speed

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

position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars