A point-light (marker) biological motion display. Or a mask based on scrambled marker positions replicated out to any number of dots. Each element is based on marker motion data in BML mm or md format, or C3D format:

mm ("motion model")

An efficient Fourier encoding for periodic motion (e.g. walking). Data are a 2D matrix with size 3×numMarkers+1 rows × 1+numHarmonics×2 columns:

Rows: [
<cd>    <cd>x coords for marker 1
<cd>    <cd>x coords for marker 2
‍<cd>    <cd>x coords for marker 3
<cd>    <cd>...
<cd>    <cd>y coords for marker 1
<cd>    <cd>...
<cd>    <cd>z coords for marker 1
<cd>    <cd>....
<cd>    <cd>info row
<cd>    <cd>]

Columns: mean marker positions, harmonic 1 cos, sin, harmonic 2 cos, sin, ...

Last row: period (frames), size factor, translation speed (data distance units/frame)

For details see Troje, N.F. (2008): Retrieving information from human movement patterns.

md ("motion data")

A marker Cartesian coordinate time series for any motion. Data are a 3D numeric array: frames (rows) × markers (columns) × 3 coords.

C3D

Data in a .c3d file using the popular C3D biomechanical data format. Again markers are Cartesian coordinate time series.

For all formats, by default data is displayed with its x axis pointing out of the screen, y right, and z up. Most commonly you may want to use property azimuth to orient it differently in the x/y directions.

Some example mm/md data in a file called bmlWalkerData.mat as well as an example .c3d file are in <><PsychBench folder><>/docs/element.

"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 (mm/md data), or frame rate loaded from file (C3D 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. 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 an mm/md 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.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). Note to change the speed of motion you can just use property speed below.

nn_markers
nn_showMarkers

Defaults: load/show all markers in the motion data

nn_markers: A vector of marker numbers to load only specific markers from the motion data.

‍nn_showMarkers: Same but only affects what markers are shown. All markers are still loaded and used for purposes like sizing and positioning the display (e.g. fitting the whole data within height below).

You can also use both properties. In this case nn_showMarkers refers to marker numbers within nn_markers.

height
sizeMult

Defaults: 10 deg

Set one of height OR sizeMult:

height sets height directly (deg). Here height is the greatest vertical distance (z axis in the motion data) spanned by dots across time.

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: no azumith and elevation → facing out of screen for standard walker data

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

elevation is display angle from +x to +z axis in the motion data (deg). For standard direction coding that means vertical on screen.

Order rotations applied: azimuth, elevation.

azimuthVelocity

Default: no angular velocity

Azimuth angular velocity (deg/sec).

dotSize

Default: 0.2 deg

Dot diameter (deg). 0 = don't show dots. You can also show sticks between markers, whether or not you show dots—see stickWidth below.

color

Default: white

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

times
showTimes

Defaults: load/show whole motion data

md/C3D data only:

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

showTimes: Same but only affects what times are shown. The difference is just that the time range in times (default whole time range) is still loaded and used for purposes like sizing and centering the display.

If you combine with maxNumLoops/breakInterval/phase below, those properties work within the part of the motion data 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 motion cycle/data

maxNumLoops is a number > 0 that is number of periods (mm data) or loops through the motion data or time range (md/C3D data) 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: md/C3D data only: Blank interval to add to end of the motion data or time range (sec). 0 = none. Generally use this if you want to have a break between loops. Note this simply adds to the length of the motion data, so for example if you set maxNumLoops = 1.5, that applies to the length including break.

phase: Start time in the motion cycle / data or time range (mm data: cycles, md/C3D data: sec). 0 = start. For md/C3D data, phase is best used to set a starting point for a looping stimulus. If you just want to show the motion data 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.

translate
translationVelocity

Defaults: no translation

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

translationVelocity: A custom translation velocity for the walker applied in the +x direction in the motion data. 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 also automatically scales translation velocity by speed above if you set it.

stickWidth
nn_stickMarkers

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

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: don't show marker numbers

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

invert

Default: don't flip

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

OR currently for mm data only: a string: <cds>"local"<cds> = invert each marker about its mean position only, <cds>"global"<cds> = invert mean positions only.

scramble
scrambleHorz
scrambleVert
scrambleAreaSize

Defaults: scramble, scrambleHorz, scrambleVert = don't randomize 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: same as number of markers in veridical display

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.

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 randomize 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 randomize marker phases

<cd>true<cd>/<cd>false<cd>: randomize phase (time offset) for each marker.

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

nn_eyes
rotation
colorMask
alpha
intensity
contrastMult