bmlWalker

 elements

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:

mm ("motion model") data

An efficient Fourier encoding for periodic motion (e.g. walking). Repeats until a cue you set in property end occurs. Data are a 2D matrix with size [3×numMarkers+1, 1+numHarmonics×2]:

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

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

info 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") data

A marker Cartesian coordinate time series for any motion. Limited duration but by default plays indefinitely by repeating until a cue you set in property end occurs (see property repeat below). Data are a 3D numeric array: frames × markers × 3 coords.

In both data formats, the standard direction coding is person facing forward in +x and upright in +z. This maps to the screen as person facing out of the screen and upright. Four example walker data sets are included in a file called bmlWalkerData.mat in <PsychBench folder>/docs/element.
c3d data

If you have biomechanical data in a .c3d file, we recommend using ezc3d to load it in MATLAB. You can then extract and reshape a c3d data array into an md data array.

For any trial you define in an experiment script, you can make one or more 

bmlWalker

 objects using function 

bmlWalker

Object and input them to addTrial.

For any trial you define in an experiment script, you can make one or more 

bmlWalker

 objects using function 

bmlWalker

Object and input them to addTrial.

Input properties

Adjustable properties

You can allow the subject to adjust the following input properties of an object of this type during the experiment using an adjuster element. If you need to make other properties adjustable, you can copy the element type using newPbType and edit it.

nn_eyes
rotation
opacity

position
nn_eyes
rotation
opacity

(None)

(None)

fileName    
dataExpr
fps

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

These properties point to the the marker motion data to use, which is a matrix in BML mm or md format (see above). You can load the data from a file or get it from a variable in the base MATLAB workspace:

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. <cd>[]<cd> = don't load from file—get data from the base MATLAB workspace.

dataExpr is a string that is variable name and possibly indexes/field names to get to the data. Set this to load from a file containing multiple data sets or to get from the base MATLAB workspace.


e.g.

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

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

dataExpr = <cds>"myWalker"<cds>
→ variable myWalker in base MATLAB workspace

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


fps is frame rate the motion data was recorded at (frames/sec).

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 (e.g. 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).

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: Only for mm data. <cd>true<cd>/<cd>false<cd>: apply translation velocity recorded in data(end,3).

transVel: A custom translation velocity to the walker. This uses the same spatial units as the motion data (not deg or other units on screen) and time units of frames the data was recorded in (not sec), which matches the convention for translation velocity used in mm data. You can use this property with either mm or md data. For mm it is ignored if you set translate = <cd>true<cd> above.

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

dotSize
nn_showMarkers

Default: dotSize = 0.2 deg
Default: nn_showMarkers = show all markers

dotSize is dot diameter (deg). 0 = don't show dots.

If dotSize > 0, nn_showMarkers is a vector of marker numbers in the motion data to show. <cd>[]<cd> = all.

Note: Regardless of dotSize and nn_showMarkers, all markers are used for sizing, calculating dimensions of the display, etc.

stickWidth
nn_stickMarkers

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

stickWidth is stick width (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.

color

Default: white

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

repeat
breakInterval

Default: repeat = show indefinitely by repeating until a cue you set in property end
Default: breakInterval = no interval between repeats

Only for md data (mm data always repeats):

repeat = <cd>true<cd>/<cd>false<cd>: show indefinitely by repeating until a cue you set in property end occurs. If = <cd>false<cd>, the element ends on its own at end of 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 data: Start time in motion data (sec).

invert
invertLocal
invertGlobal

Defaults: don't invert

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

Only for mm data:

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

Only for mm data:

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

scrambleKernel

You can use this property to apply a specific scrambling pattern for dot positions, periods, and phase(s). Typically use this if you want to randomly scramble any of these parameters but repeat the same random pattern across multiple bmlWalker elements. To do this, first run a bmlWalker element with whatever scrambling you want and with record property scrambleKernel_r in report. Then use the value output for that property as the input in scrambleKernel for bmlWalker elements that you want to apply that pattern to (in later experiment runs). Those elements must have the same scrambling parameters as the first one.

Input properties all visual elements have

position

Input properties all adjuster elements have

adjust

Input properties all objects have

report
info

Record properties

PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results using input property report.

scrambleKernel_r

For use with input property scrambleKernel. See above.