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.

(Edge artifacts)

Minor artifacts at dot edges 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 (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 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: 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.

azimuthVel

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

translate
translationVel

Defaults: no translation

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

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

repeat
breakInterval

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

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

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

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

phase

Default: start at start of motion cycle/data

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.

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

nn_eyes
rotation
colorMask
alpha
intensity
contrastMult