MoCap DB Processing¶

Module to load motion capture data.

+mocapdb.loadNeuRaTrialData(dataDir, subjName, actName, usebuffer, prefix, removeaccbias)¶

Load data for selected movement trial

Parameters

dataDir (characters, string) – data directory path
subjName (characters, string) – subject name of trial movement
actName (characters, string) – action name of trial movement
usebuffer (Optional, boolean) – use buffer .mat if available
prefix (Optional, characters, string) – prefix to name

Returns

struct data with trial data inside

Return type

struct

+mocapdb.loadPendulumCompassMat(pendulumFName, compassFName)¶

Calculate rotation matrix of world frame with respect vicon frame from the pendulum and compass mat files generated by parseViconCSV.py

Parameters

pendulumFName – pendulum mat file name
compassFName – compass mat file name

Returns

R - rotation matrix of world in vicon frame

+mocapdb.loadRawNeuRaTrialData(dataDir, subjName, actName, ns, override, options)¶

Load data for selected movement trial

Parameters

dataDir – data directory path
subjName – subject name of trial movement
actName – action name of trial movement
ns – yaw offset calibration mode. NS1 = use yaw offset from ROM NS2 = use yaw offset from Vicon
override – [optional] override all calibration files
options – [optional] id to body mapping. By default uses the map specified in https://gait-tech.github.io/gaittoolbox/data.html.

Returns

struct data with trial data inside

+mocapdb.loadTCDTrialData(dataDir, subjName, actName, usebuffer, prefix)¶

Load data for selected movement trial

Parameters

dataDir (characters, string) – data directory path
subjName (characters, string) – subject name of trial movement
actName (characters, string) – action name of trial movement
usebuffer (boolean, optional) – use buffer .mat if available
prefix (characters, string) – prefix to name

Returns

struct data with trial data inside

Return type

struct

ViconBody¶

class +mocapdb.@ViconBody.ViconBody(varargin)¶

Bases: matlab.mixin.Copyable

Body class from Vicon csv export

LFEO = None¶: left knee position

LFEP = None¶: left hip position

LTIO = None¶: left ankle position

LTOE = None¶: left toe position

PELV = None¶: pelvis position

RFEO = None¶: right knee position

RFEP = None¶: right hip position

RTIO = None¶: right ankle position

RTOE = None¶: right toe position

ViconBody(varargin)¶

frame = None¶: data are in this frame of reference (Vicon or IMU)

fs = None¶: sampling rate

ftEndIndex = 'inf'¶: full trial end index

ftStartIndex = '1'¶: full trial start index

nSamples = None¶: number of samples

posUnit = "'mm'"¶: position unit

qLFT = None¶: left foot orientation (n x 4 OR 3 x 3 x n)

qLSK = None¶: left tibia orientation (n x 4 OR 3 x 3 x n)

qLTH = None¶: left femur orientation (n x 4 OR 3 x 3 x n)

qRFT = None¶: right foot orientation (n x 4 OR 3 x 3 x n)

qRPV = None¶: pelvis orientation (n x 4 OR 3 x 3 x n)

qRSK = None¶: right tibia orientation (n x 4 OR 3 x 3 x n)

qRTH = None¶: right femur orientation (n x 4 OR 3 x 3 x n)

srcFileName = None¶: body is loaded from this source file name

+mocapdb.@ViconBody.changeFS(obj, fs)¶

+mocapdb.@ViconBody.changePosUnit(obj, newUnit, update)¶

Change position unit of vicon body

Example:: out = obj.getSubset(5:100, segAlias);

Parameters

obj – class ViconBody (self)
newUnit – new unit
update – If true, update this vicon body, else crease new ViconBody

Returns

out - ViconBody class whose data only includes the rows in idx

+mocapdb.@ViconBody.exportCSV(obj, fname, info)¶

Export as CSV file

Parameters

obj – this ViconBody
fname – filename of file to be saved
info – additional info to be added at each csv file

+mocapdb.@ViconBody.getEndIndex(obj, untilfirstnan)¶

Get end index

Parameters

obj – this ViconBody
untilfirstnan – default False. if True, return end index at first Nan

Returns

endIdx - last index

+mocapdb.@ViconBody.getStartIndex(obj)¶

Get first valid index

Returns: startIdx - first valid index

+mocapdb.@ViconBody.getSubset(obj, idx)¶

Get subset of vicon body

Example:: out = obj.getSubset(5:100, segAlias);

Parameters

obj – class ViconBody (self)
idx – indices of data to be included in out

Returns

out ViconBody class whose data only includes the rows in idx

+mocapdb.@ViconBody.loadCSV(fname)¶

Load CSV files (opposite of exportCSV)

Parameters: fname – input file
Returns: obj - ViconBody

+mocapdb.@ViconBody.loadViconMat(fname, plugingait)¶

Load mat file generated by parseViconCSV.py and return an instance of ViconBody class

Parameters

fname – mat file name
plugingait (Optional, Boolean. Defaults to true.) – reconstruct using Vicon’s plugin gait model. If false, uses human body model that has been kinematically fit.

Returns

instance of ViconBody class.

+mocapdb.@ViconBody.toWorldFrame(obj, qR)¶

Transform BVHBody from vicon frame (default) to world frame

Parameters

obj – this ViconBody
qR – transformation quaternion (1 x 4) from vicon frame to world frame

Returns

out BVHBody in world frame.

+mocapdb.@ViconBody.togrBody(obj, idx, args)¶

Export ViconBody class to grBody class

Parameters

idx – index to be copied to grBody class
args – arguments to be passed to grBody constructor

Returns

out - instance of grBody class.

XsensBody¶

class +mocapdb.@XsensBody.XsensBody(varargin)¶

Bases: matlab.mixin.Copyable

Xsens Body class for the TCD dataset

Head = None¶: Head

Hidden()¶

L_Foot = None¶: Left foot

L_LowArm = None¶: Left low arm

L_LowLeg = None¶: Left shanks (near ankles)

L_LowLeg2 = None¶: Left shanks (middle)

L_UpArm = None¶: Left upper arm

L_UpLeg = None¶: Left thigh

Pelvis = None¶: Pelvis

R_Foot = None¶: Right foot

R_LowArm = None¶: Right low arm

R_LowLeg = None¶: Right shanks (near ankles)

R_LowLeg2 = None¶: Right shanks (middle)

R_UpArm = None¶: Right upper arm

R_UpLeg = None¶: Right thigh

Sternum = None¶: Sternum

XsensBody(varargin)¶

Class constructor

Parameters: varargin – param1 (string), val1, param2 (string), val2
Returns: instance of BVHBody class.

copyinfo()¶

frame = None¶: data are in this frame of reference (Vicon or World or Calib)

fs = '100'¶: sampling frequency

ftEndIndex = 'inf'¶: full trial end index

ftStartIndex = '1'¶: full trial start index

nSamples = None¶: number of samples

obj()¶

segList = "{'Head', 'Sternum', 'Pelvis', 'L_UpArm', 'R_UpArm', 'L_LowArm', 'R_LowArm', 'L_UpLeg', 'R_UpLeg', 'L_LowLeg', 'L_LowLeg2', 'R_LowLeg', 'R_LowLeg2', 'L_Foot', 'R_Foot'}"¶

srcFileName = None¶: body is loaded from this source file name

+mocapdb.@XsensBody.adjustFrame(obj, xb1, xb2, orionly)¶

adjust XsensBody frames by xb1.qB * obj.qB * xb2.qB

Parameters

obj – this XsensBody
qR1 – XsensBody or quaternion 1
qR2 – XsensBody or quaternion 2
orionly – calculate and return only ori values

Returns

out - XsensBody with adjusted convention.

+mocapdb.@XsensBody.calcCalibAnkleSensorW2PelvisWFromAcc(obj, idx)¶

Calculate yaw offset from accelerometer data

Run localization Kalman filter on the pelvis and ankle IMUs Assume the position vector (from origin) of each IMU should point to the same direction, and the yaw angle between vectors is the yaw offset.

Parameters

obj – this XsensBody
idx – index of data to be used

Returns

out - XsensBody class with adjustment sensor data

+mocapdb.@XsensBody.calcCalibAnkleSensorW2PelvisWFromGyroSkewness(obj, DEGRANGE)¶

Calculate yaw offset from gyro skewness on sagital plane

Parameters

obj – this XsensBody
calibS2B – XsensBody that transforms sensor frame to body frame

Returns

out - XsensBody class with adjustment sensor data

+mocapdb.@XsensBody.calcCalibAnkleSensorW2PelvisWFromROM(obj, calibS2B, DEGRANGE)¶

Calculate yaw offset from high RoM on sagital plane

Parameters

obj – this XsensBody
calibS2B – XsensBody that transforms sensor frame to body frame

Returns

out XsensBody class with adjustment sensor data

+mocapdb.@XsensBody.calcCalibAnkleSensorW2PelvisWFromVicon(obj, dataV)¶

Calculate yaw offset from vicon data

Parameters: obj – this XsensBody
Returns: out XsensBody class with adjustment sensor data

+mocapdb.@XsensBody.calcCalibSB(obj, refBody, sIdx)¶

Calculate the calibration between sensor frame to body frame from one frame (usually first frame).

Parameters

refBody – grBody class in world frame. (use data at index 1)
sIdx – index of obj to be used

Returns

out - Xsens with calibration data from sensor frame to body frame

+mocapdb.@XsensBody.calcCalibSBFromMean(obj, refBody)¶

Calculate the calibration between sensor frame to body frame by taking the mean rotation offset between obj and refBody

Return B_q_S = argmin || || :param refBody: grBody class in world frame.

Returns: out - Xsens with calibration data from sensor frame to body frame

+mocapdb.@XsensBody.calcCalibYawOffsetFromViconBody(obj, dataV)¶

Calculate yaw offset from vicon data

Parameters: obj – this XsensBody
Returns: out XsensBody class with adjustment sensor data

+mocapdb.@XsensBody.calcGfrAcc(obj)¶

Calculate ground frame acceleration (w/out gravity)

Returns: out - struct with gfrAcc of each body segment

+mocapdb.@XsensBody.calcSegMeanRot(obj, seg, roty, idx)¶

Calculate the mean rotation of selected segments

Example 1:

out = obj.calcSegMeanRot({'LTIO', 'RFEO'})

Parameters

obj (+pelib.@grBody) – this object instance
seg (cell array) – cell array string of body segments (see keys of +pelib.@XsensBody.XsensBody.segList)
roty (numeric in radians) – radian rotation in y axis. Useful in adjusting between feet and other body segment orientation
idx (integer array) – target indices. defaults to 1:obj.nSamples

Returns

out - mean rotation

Return type

length(idx) x 4

+mocapdb.@XsensBody.conj(obj)¶

Conjugate of orientation data in XsensBody. Acc, gyr, mag are removed.

Parameters: obj – this XsensBody
Returns: out - conjugate of XsensBody with adjusted convention.

+mocapdb.@XsensBody.exportCSVs(obj, fname, info)¶

Export all sensor information as CSV files

File name convension: fname-bodypart.csv Each file will contain acceleration, gyroscope, magnetometer, and quaternion data

Parameters

obj – this XsensBody or struct(‘bodypart’, table)
fname – filename of file to be saved
info – additional info to be added at each csv file

+mocapdb.@XsensBody.exportRawMeasurementAsStruct(obj, seg, segAlias)¶

Export raw xsens measurements as struct

Example:

seg = {‘Pelvis’, ‘L_LowLeg’, ‘R_LowLeg’};

segAlias = {‘PELV’, ‘LANK’, ‘RANK’};

out = obj.exportRawMeasurementAsStruct(seg, segAlias);

Parameters

obj – class XsensBody (self)
seg – cell array of sensors to be exported
segAlias – cell array of sensor aliases

Returns

out - {‘PELVAccX’: n x 1, PELVAccY: n x 1, … } for Acc, Gyr, Mag on the X, Y, Z axes

+mocapdb.@XsensBody.getMean(obj)¶

Calculate the mean

Parameters: obj (+mocapdb@XsensBody) – this object
Returns: out - XsensBody with 1 row per attribute containing mean data

+mocapdb.@XsensBody.getNonemptySeg(obj)¶

Get nonempty segment list

Parameters: obj – class XsensBody (self)
Returns: out - cell array of valid segments

+mocapdb.@XsensBody.getSegSubset(obj, segList)¶

Get segment subset of xsens measurements

Example:: segList = {‘Pelvis’, ‘L_LowLeg’, ‘R_LowLeg’} out = obj.getSegSubset(segList);

Parameters

obj – class XsensBody (self)
segList – list of segments

Returns

out - XsensBody class whose data only includes the rows in idx

+mocapdb.@XsensBody.getSubset(obj, idx)¶

Get subset of xsens measurements

Example:: out = obj.getSubset(5:100, segAlias);

Parameters

obj – class XsensBody (self)
idx – indices of data to be included in out

Returns

out - XsensBody class whose data only includes the rows in idx

+mocapdb.@XsensBody.initializetoIdentity(obj)¶

Initialize this XsensBody such that each rotation matrix is identity

Parameters: obj – this XsensBody

+mocapdb.@XsensBody.loadCSVs(fname)¶

Load CSV files (opposite of exportCSVs) Pelvis, L_UpLeg, R_UpLeg, L_LowLeg, L_LowLeg2, R_LowLeg, R_LowLeg2, L_Foot, R_Foot

This function will specifically load <fname>-Pelvis.csv to obj.Pelvis,: <fname>-L_Ankles to the obj.L_LowLeg, etc.

Parameters: fname – input filename
Returns: obj - XsensBody

+mocapdb.@XsensBody.loadCalib(fname)¶

Load calibration files (calib_*.txt)

Parameters: fname – .sensors filename
Returns: output TCDBody with calibration data

+mocapdb.@XsensBody.loadCalibCSV(fname)¶

Save calibration as CSV file

Parameters

obj – this XsensBody
fname – filename of file to be saved

+mocapdb.@XsensBody.loadCalibSensorW2V(viconFName, xsensFName, options, idx)¶

Calculate rotation matrix of sensor world frame with respect vicon frame

Parameters

viconFName – vicon calib mat file name
xsensFName – xsens MT export file name
options – XsensBody load configuration (see loadMTExport)
idx – [OPTIONAL] index of xsens ori to be used in calculation (default = 1)

Returns

obj - XsensBody class qOri world to vicon frame of each sensor ({}^V_W q)

+mocapdb.@XsensBody.loadMTExport(name, options)¶

Load exported files from XSens MT manager (v4.8) Pelvis, L_UpLeg, R_UpLeg, L_LowLeg, R_LowLeg, L_Foot, R_Foot

Example:

options = struct(‘Pelvis’, ‘00B40B91’, …: ‘L_UpLeg’, ‘00B40C45’, ‘R_UpLeg’, ‘00B40C3C’, … ‘L_LowLeg’, ‘00B40BA5’, ‘R_LowLeg’, ‘00B40C35’, … ‘L_Foot’, ‘00B40C55’, ‘R_Foot’, ‘00B40C48’);

Returns a struch with each field has a table with dimensions N x 13. The column of each row are quaternions[4], accelerometer [3], gyroscope [3], magnetometer [3]

Accelerometer, gyroscope, magnetometer are in the sensor frame. Quaternions tell the orientation relationship between sensor and world frame.

Parameters

name – session name
options – struct (body segment <-> sensor id)

Returns

obj - XsensBody

+mocapdb.@XsensBody.loadMVNX(fname, options)¶

Load exported files from XSens MT manager (v4.8) Pelvis, L_UpLeg, R_UpLeg, L_LowLeg, R_LowLeg, L_Foot, R_Foot

Example:

options = struct(‘Pelvis’, ‘00B40B91’, …: ‘L_UpLeg’, ‘00B40C45’, ‘R_UpLeg’, ‘00B40C3C’, … ‘L_LowLeg’, ‘00B40BA5’, ‘R_LowLeg’, ‘00B40C35’, … ‘L_Foot’, ‘00B40C55’, ‘R_Foot’, ‘00B40C48’);

Returns a struch with each field has a table with dimensions N x 13. The column of each row are quaternions[4], accelerometer [3], gyroscope [3], magnetometer [3]

Accelerometer, gyroscope, magnetometer are in the sensor frame. Quaternions tell the orientation relationship between sensor and world frame.

Parameters

name – session name
options – struct (body segment <-> sensor id)

Returns

obj - XsensBody

+mocapdb.@XsensBody.loadSensorFile(fname)¶

Load .sensors file and returns struct with fields: Head, Sternum, Pelvis, L_UpArm, R_UpArm, L_LowArm, R_LowArm, L_UpLeg, R_UpLeg, L_LowLeg, R_LowLeg, L_Foot, R_Foot

Each field has a table with dimensions N x 13. The column of each row are quaternions[4], accelerometer [3], gyroscope [3], magnetometer [3]

Accelerometer, gyroscope, magnetometer are in the sensor frame. Quaternions tell the orientation relationship between sensor and world frame.

Parameters: fname – .sensors filename
Returns: obj - XsensBody

+mocapdb.@XsensBody.load_mvnx(filename)¶

Taken from MVN Studio Developer Toolkit 1.0.2 mvnx = load_mvnx(filename) loads a mvnx file

Parameters: filename – is name of file (including path)
Returns: mvnx is result struct containing all data of the mvnx file

+mocapdb.@XsensBody.normalizeAcc(obj, acc_norm)¶

Normalize acceleration

Parameters

obj (+mocapdb.@XsensBody) – this object
acc_norm (Optional, float) – magnitude of normalized acc. Defaults to 9.81

Returns

[out, bias] - XsensBody with normalized acc data and bias data

Return type

[+mocapdb.@XsensBody, +mocapdb.@XsensBody]

+mocapdb.@XsensBody.removeAccBias(obj, bias)¶

Normalize acceleration

Parameters

obj (+mocapdb.@XsensBody) – this object
bias – XsensBody containing bias information

Returns

out - XsensBody with biased remove

Return type

+mocapdb.@XsensBody

+mocapdb.@XsensBody.saveCalibCSV(obj, fname, mode)¶

Save calibration as CSV file

Parameters

obj (+mocapdb.@XsensBody) – this XsensBody
fname – filename of file to be saved
mode (Optional, integer. Defaults to 1.) – save calib mode (bit 1 = qOri, 2 = acc_bias, 3 = both)

+mocapdb.@XsensBody.toViconFrame(obj, qR)¶

Transform XsensBody from world frame (default) to vicon frame

Parameters

obj – this XsensBody
qR – XsensBody containing transformation quaternion (1 x 4) from world frame to vicon frame

Returns

out - XsensBody in vicon frame.

BVHBody¶

class +mocapdb.@BVHBody.BVHBody(varargin)¶

Bases: matlab.mixin.Copyable

a class for BVH body

Parameters

srcFileName – body is loaded from this source file name
frame – data are in this frame of reference (Vicon or IMU)

BVHBody(varargin)¶

Hips = None¶: similar to MIDPEL

LeftFoot = None¶: similar to LTIO

LeftLeg = None¶: similar to LFEO

LeftToe = None¶: similar to LTOE

LeftUpLeg = None¶: similar to LFEP

RightFoot = None¶: similar to RTIO

RightLeg = None¶: similar to RFEO

RightToe = None¶: similar to RTOE

Spine = None¶: similar to RFEP

frame = None¶: data are in this frame of reference (Vicon or IMU)

fs = None¶: sampling frequency

nSamples = None¶: number of samples

posUnit = "'mm'"¶: position unit

qHips = None¶: hip orientation (n x 4)

qSpine = None¶

srcFileName = None¶: body is loaded from this source file name

+mocapdb.@BVHBody.adjustFootFrame2BMC(obj)¶

Adjust the foot frame from animation convention to biomechanical convention. See link for description of convention.

Parameters: obj (+mocapdb.@BVHBody) – this object instance
Returns: out - new object instance with correct foot
Return type: +mocapdb.@BVHBody

+mocapdb.@BVHBody.changePosUnit(obj, newUnit, update)¶

Change position unit of BVH body

Example:: out = obj.changePosUnit(‘m’, false);

Parameters

obj – class BVHBody (self)
newUnit – new unit
update – If true, update this bvh body, else crease new BVHBody

Returns

out - BVHBody class whose data only includes the rows in idx

+mocapdb.@BVHBody.getEndIndex(obj)¶

Get end index

Returns: endIdx - last index

+mocapdb.@BVHBody.getStartIndex(obj)¶

Get first valid index

Returns: startIdx - first valid index

+mocapdb.@BVHBody.getSubset(obj, idx)¶

Get subset of bvh body

Example:: out = obj.getSubset(5:100);

Parameters

obj – class BVHBody (self)
idx – indices of data to be included in out

Returns

out - BVHBody class whose data only includes the rows in idx

+mocapdb.@BVHBody.loadBVHFile(fname, unit)¶

Load BVH file and return an instance of BVHBody class

Parameters

fname – BVH file name
unit – data position unit (mm or inch)

Returns

instance of BVHBody class.

+mocapdb.@BVHBody.loadOriPosFile(fname_ori, fname_pos, unit)¶

Load BVH file and return an instance of BVHBody class

Parameters

fname_ori – orientation file name
fname_pos – position file name
data (unit) – position unit (mm or inch)

Returns

instance of BVHBody class.

+mocapdb.@BVHBody.loadXsensBVHFile(fname, unit)¶

Load BVH file and return an instance of BVHBody class

Parameters

fname – BVH file name
unit – data position unit (mm or inch)

Returns

instance of BVHBody class.

+mocapdb.@BVHBody.loadbvh(fname)¶

LOADBVH Load a .bvh (Biovision) file.

Loads BVH file specified by FNAME (with or without .bvh extension) and parses the file, calculating joint kinematics and storing the output in SKELETON.

Some details on the BVH file structure are given in “Motion Capture File Formats Explained”: http://www.dcs.shef.ac.uk/intranet/research/resmes/CS0111.pdf But most of it is fairly self-evident.

+mocapdb.@BVHBody.toViconBody(obj, idx, args)¶

Export BVHBody class to ViconBody class

Parameters

idx – index to be copied to grBody class
args – arguments to be passed to grBody constructor

Returns

out - instance of grBody class.

+mocapdb.@BVHBody.toWorldFrame(obj, qR)¶

Transform BVHBody from vicon frame (default) to world frame

Parameters

obj – this BVHBody
qR – transformation quaternion (1 x 4) from vicon frame to world frame

Returns

out - BVHBody in world frame.

+mocapdb.@BVHBody.togrBody(obj, idx, args)¶

Export BVHBody class to grBody class

Parameters

idx – index to be copied to grBody class
args – arguments to be passed to grBody constructor

Returns

out - instance of grBody class.