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:
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.
A marker Cartesian coordinate time series for any motion. Data are a 3D numeric array: frames (rows) × markers (columns) × 3 coords.
Data in a .c3d file using the popular C3D biomechanical data format. Again markers are Cartesian coordinate time series.
Some example mm/md data in a file called bmlWalkerData.mat as well as an example .c3d file are in <PsychBench folder>/docs/element.
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>.
Default: No, repeats until a condition you set in property end.
md/C3D data only: If you set property repeat = <cd>false<cd>, ends on its own at the end of the motion data.
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).
No—runs until a condition you set in property end.
You can vary or allow the subject to adjust the following input properties of an object of this type in real time when it's running. If you need to make other properties adjustable, you can edit the element type code—see Element Type Programming Manual.
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars
(None)
(None)
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
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.
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
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).
Defaults: show at 10 deg height
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.
Defaults: facing out of screen (for standard data)
elevation is vertical angle (deg).
Order rotations applied: azimuth, elevation.
Default: no rotational velocity
Horizontal angle velocity (deg/sec).
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.
Default: normal speed
Motion speed, including reverse motion. 1 = normal, 0.5 = half speed, 2 = double speed, −1 = reverse normal, etc.
Defaults: no translation
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.
Default: repeat = repeat until a condition you set in property end
Default: breakInterval = no interval between repetitions
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 (sec). 0 = none.
Default: 0
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.
Default: dotSize = 0.2 deg
Default: nn_showMarkers = show all markers loaded from motion data
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.
Default: stickWidth = don't show sticks between markers
Default: nn_stickMarkers = body segments for standard 15-marker human motion data
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.
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.
Default: white
A 1×3 RGB vector with numbers between 0–1.
Defaults: don't invert
invertLocal inverts only marker motion.
invertGlobal inverts only mean marker positions across time.
Defaults: scramble, scrambleHorz, scrambleVert = don't scramble marker positions
Default: scrambleAreaSize = fit scrambling cylinder to veridical display
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).
Default: number of mask dots = number of markers
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).
Default: scramblePeriods = don't scramble marker periods
Default: scramblePeriodDelta = 2
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.
Default: don't scramble marker phases
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.
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).
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.
PsychBench © 2017–2023 Giles Holland
Website © 2023 Giles Holland
End user license agreement