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

nn_eyes
rotation
colorMask
alpha
intensity
contrastMult

fileName    
dataExpr
fps
nn_markers
times

No defaults: fileName, dataExpr
Default: fps = 120 frames/sec (mm/md data), or frame rate loaded from file (C3D data)
Default: nn_markers = load all markers in the motion data
Default: times = load whole motion data

Set one or both of fileName/dataExpr to specify the marker motion data to use. Data must be in BML mm or md format or C3D format (see above).

fileName is a string that is name of a .mat file containing mm or md data, or a .c3d file. 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). For a .mat file, the file can contain multiple mm/md data sets—if so, use dataExpr below to specify which one to load. <cd>[]<cd> = get mm/md data from the base MATLAB workspace.

dataExpr is a string that is variable name and possibly indexes/field names containing an mm/md data set. You can use this to specify which one to load from a .mat file containing multiple data sets, or to get a data set from the base MATLAB workspace.

e.g.

fileName = <cds>"data.c3d"<cds>
→ data in file data.c3d

fileName = <cds>"data.mat"<cds>
→ mm/md data in file data.mat, which contains only one data set

fileName = <cds>"bmlWalkerData.mat"<cds>
dataExpr = <cds>"bmlWalkerData{2}"<cds>
→ mm/md data in cell 2 of cell array bmlWalkerData in file bmlWalkerData.mat

dataExpr = <cds>"myWalker"<cds>
→ mm/md data in variable myWalker in base MATLAB workspace

dataExpr = <cds>"bmlWalkerData{2}"<cds>
→ mm/md data in cell 2 of cell array bmlWalkerData in base MATLAB workspace

fps is frame rate the motion data was recorded at (frames/sec). <cd>[]<cd> = 120 hz for mm/md data, or read from file for C3D data. Note to change the speed of motion you can just use property speed below.

nn_markers is a row vector of marker numbers to load only specific markers from the motion data. <cd>[]<cd> = all markers.

times (md/C3D data only): This is a vector [t1 t2] (sec) to load only a specific time range in the motion data. t1 = 0 = start of file, t2 = inf = end of file.

Note for both nn_markers and times, you can also leave the property at default and use showMarkers/showTimes below instead to show only part of the motion data while still using all of it for purposes like sizing and positioning the display (e.g. fitting all markers and times within height below).

height
sizeMult

Defaults: 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 (z axis in the motion data) spanned by dots across time.

OR

sizeMult is a conversion factor from whatever distance units the motion data is in (commonly mm) to deg visual angle. i.e. the conversion factor has units deg visual angle / data distance units, and just multiplies the motion data. Note for mm data this disregards any size factor in data(end,2). sizeMult is useful when you want to preserve relative sizes between different walker data sets by setting it equal across different walker elements.

azimuth
elevation

Defaults: facing out of screen (for standard data)

azimuth is horizontal angle from +x to +y axis in the motion data (deg). For standard direction coding (see at top), that means 0 = facing out of the screen, +90 = facing right on screen, −90 = facing left on screen.

elevation is vertical angle (deg).

Order rotations applied: azimuth, elevation.

azimuthVel

Default: no rotational velocity

Horizontal angle velocity (deg/sec).

showTimes

Default: show whole motion data

A vector [t1 t2] (sec) to show only a specific time range in the motion data. t1 = 0 = start of file, t2 = inf = end of file. Note the whole data is still used for purposes like sizing and positioning the display (e.g. fitting the whole data 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.

translate
transVel

Defaults: no translation

‍translate (mm data only): <cd>true<cd>/<cd>false<cd>: apply translation velocity recorded in data(end,3).

transVel: A custom translation velocity for the walker. This uses the same spatial units as the motion data (commonly mm, not deg or other units on screen), so units are data distance units / sec. You can use this property with any data format (mm/md/C3D). For mm it is ignored if you set translate = <cd>true<cd> above.

Note for both these properties, PsychBench automatically rescales translation velocity by speed above.

repeat
breakInterval

Default: repeat = repeat until a condition you set in property end
Default: breakInterval = no interval between repeats

md/C3D data only (mm data always repeats):

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

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

phase

Default: 0

mm data: Start time in motion cycle (cycles). Or a string <cds>"r"<cds> = randomize.

md/C3D data: Start time in motion data (sec). If you also set times or showTimes above, phase is relative to start of the time range you specify there.

dotSize
nn_showMarkers

Default: dotSize = 0.2 deg
Default: nn_showMarkers = show all markers loaded from motion data

dotSize is dot diameter (deg). 0 = don't show dots (you can still show sticks between markers—see properties below).

‍nn_showMarkers is a vector of marker numbers to show. <cd>[]<cd> = all. Note nn_showMarkers only hides markers. That is, all markers in the motion data are still used for purposes of sizing the display on screen and centering it at its position. If you want to exclude markers completely, use nn_markers above instead. You can also use both properties—in this case nn_showMarkers refers to marker numbers within nn_markers.

stickWidth
nn_stickMarkers

Default: stickWidth = don't show sticks between markers
Default: nn_stickMarkers = body segments for standard 15-marker human motion data

stickWidth is width of sticks to show between markers (deg). 0 = don't show sticks.

If stickWidth > 0, nn_stickMarkers is an n×2 matrix with each row containing a set of two marker numbers to show a stick between.

showMarkerNums

Default: show dots

<cd>true<cd>/<cd>false<cd>: show marker numbers instead of dots—useful if you want to see what numbers correspond to what markers in the motion data. If = <cd>true<cd>, shows a static image of the walker data with marker numbers where dots would be. You can indirectly control number font size with dotSize above. You can also use phase to see the still image from a different time in the walker data, and nn_showMarkers to see only some marker numbers.

color

Default: white

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

invert
invertLocal
invertGlobal

Defaults: don't invert

invert = <cd>true<cd>/<cd>false<cd>: invert (flip) vertically.

Currently for mm data only:

invertLocal inverts only marker motion.

invertGlobal inverts only mean marker positions across time.

scramble
scrambleHorz
scrambleVert
scrambleAreaSize

Defaults: scramble, scrambleHorz, scrambleVert = don't scramble marker positions
Default: scrambleAreaSize = fit scrambling cylinder to veridical display

scramble = <cd>true<cd>/<cd>false<cd>: randomize mean position across time for each marker. Markers are scrambled within a cylinder. Currently if you scramble then elevation above must = 0.

You can also set scramble to a number between 0–1 for partial scrambling. This interpolates between veridical and fully scrambled mean positions. Interpolation is done in spherical coordinates centered at walker center to approximately preserve the size of the stimulus across levels, i.e. markers go from veridical to fully scrambled along arcs instead of lines. This avoids intermediate scrambling levels tending to give a scrunched walker since lines would often pass from one side of the walker to the other.

scrambleHorz and scrambleVert are like scramble but scramble only horizontally and/or vertically. They are <cd>true<cd>/<cd>false<cd> only (no partial scrambling).

If any scrambling is on, scrambleAreaSize sets size of the cylinder to scramble within. This is a number for width = height, or a vector for different [width height] (deg). Or a string <cds>"f"<cds> = scramble within a cylinder fit to the veridical display (using mean marker positions across time).

numScrambleDots

Default: number of mask dots = number of markers

You can use the motion data as the basis for a mask made of scrambled dots by enabling scrambling above and setting this to number of mask dots. Markers in the data are then replicated into the specified number of dots as evenly as possible, and randomly for the remainder. <cd>[]<cd> = number of markers in data (i.e. just a scrambled walker, not a mask).

Note that since masks are randomized and have a transparent background you can layer multiple masks on top of each other if you need one aggregate mask that has a mix of properties (e.g. some dots at one azimuth and some at another).

scramblePeriods
scramblePeriodDelta

Default: scramblePeriods = don't scramble marker periods
Default: scramblePeriodDelta = 2

Currently for mm data only:

scramblePeriods = <cd>true<cd>/<cd>false<cd>: randomize period (speed) for each marker.

If scramblePeriods = <cd>true<cd>, period will be randomized by dividing by a number between 1/scramblePeriodDelta and scramblePeriodDelta drawn from a log-uniform distribution.

scramblePhases

Default: don't scramble marker phases

<cd>true<cd>/<cd>false<cd>: randomize phase (time series offset) for each marker. For md/C3D data with repeat = <cd>false<cd> above, shifted markers will repeat across end of motion data as needed for each marker to run for the same duration.

You can also set to a number between 0–1 for partial scrambling. This interpolates between veridical and fully scrambled phases, where veridical is defined by phase above.

scrambleSeed

Default: full pseudo-randomization

You can use this property to apply a specific random pattern for scrambling and other randomization, typically if you want to repeat precisely the same pattern across multiple bmlWalker elements. To do this, set scrambleSeed to a MATLAB random number generator state as returned by the rng command, and set it to the same state for all bmlWalker elements that you want to share the pattern. The element will set the generator to that state before generating the pattern (it re-shuffles the state after so randomization elsewhere is not affected). All elements using the same seed must have the same values for all other properties that affect scrambling and randomization (including phase).

Input properties all objects have

report
info

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.