Export to MAT format

Click Export on the File menu and then To MAT to export to the MAT format. The MAT file can then be opened in Matlab. You can select the data that is exported on the Matlab file export page in the Project options dialog, see chapter Matlab file export.

MAT file format

Capture data is exported to a MAT file as a single structure array (struct) with the same name as the file. In case the file name is not a proper variable name in Matlab, the name of the struct will be altered. For example, if the file name does not start with an English letter, a prefix qtm_ will be added to the name of the structure.

The fields of the structure array contain information and data of the capture. Data in a field is accessed using dot notation of the form structName.fieldName. If a field contains a structure array with multiple elements, a single element is accessed by indexing the field, for example, MyCapture.Skeletons(3).SkeletonName to access the name of the third skeleton. If a field contains a multidimensional array, data points are accessed by indexing the array, for example, MyCapture.Trajectories.Labeled.Data(3,1,134) to access the X value of frame 134 of the third labeled trajectory. For more information about accessing data in Matlab, refer to Matlab documentation.

To read data from a QTM exported MAT file into a struct with a name of your own choice, rather than the file name, copy the following function and make sure it is included in your Matlab path:

Copy 
function qtm=qtmread(fn)

% Get file name from a file dialog if not specified
if nargin==0
    [fname,pname] = uigetfile({'*.mat', '.mat files'}, 'Load QTM mat file');
    fn = [pname fname];
end

% Load the file
S=load(fn);

% Parse S
sflds=fieldnames(S);
if length(sflds)>1
    error('Only one variable (struct) is expected in a .mat file exported by QTM.')
else
    qtm=S.(sflds{1});
end

To read the exported file into a variable, for example MyVarName, run the function in Matlab:

>> MyVarName = qtmread();

or

>> MyVarName = qtmread(<file path>);

For specific information about the format of the exported structure array, see the chapters below.

Capture information

The following fields contain information about the capture.

  • FileVersion
    Version number of export format (array with 3 elements), currently 2, 0, 0.

    FileVersion is not included for versions earlier than 2, 0, 0.

  • File
    File name and directory path.

  • Timestamp
    Time when measurement was started. In date format YYYY-MM-DD, HH:MM:SS.SSS, followed by a tab character and the timestamp in seconds and ticks from when the computer was started.

    The time stamp is recalculated when trimming the file.

    The time stamps indicate the start of the capture according to the QTM software. The time stamps may not exactly correspond to the first frame of the capture and it is discouraged to use them for synchronization with data from other devices connected to the same or another synchronized computer.

  • StartFrame
    The measurement start frame number.

  • Frames
    Number of frames.

  • FrameRate
    Frame rate in frames per second.

    When using external timebase the frequency is set to the actual frequency for the Multiplier/Divisor mode and to EXT for the Edge triggered mode.

Trajectories

The field Trajectories contains the structures Labeled for labeled markers and, optionally Unidentified for unidentified markers with the following fields:

  • Count
    Number of trajectories in the window.

  • Labels
    A list of the trajectory labels.

    This field is only included in the Labeled struct array.

  • Data
    The location of the 3D points (in mm) of the trajectories in the window. The data is given in a matrix with the dimensions: Trajectories x X, Y, Z, Residual x Frames.

  • Type
    Type specification of the markers per frame. The data is given in a matrix with the dimensions: Trajectories x Frames. The types have values 0-4, which indicate: Missing=0, Measured=1, Gap-filled=2, Virtual=3, Edited=4.

  • TrajectoryType
    A list of the type for each trajectory. For information about the trajectory types see chapter Data in Trajectory info windows.

Analog/EMG

The fields Analog or EMG contain struct arrays with data from the analog devices. The analog and EMG data from integrated wireless EMGs are stored in separate struct arrays, but the structure is the same.

  • BoardName
    The name of the board that was used in the capture.

  • NrOfChannels
    The number of channels that were used in the capture.

  • ChannelNumbers
    The channel numbers that were used in the capture.

  • Labels
    An array with the names of the channels that were used on the analog board.

  • Range
    The range of the channels on the analog board.

  • NrOfFrames
    The number of exported motion capture data frames.

  • SamplingFactor
    The multiplication factor compared with the motion capture frame rate. The SamplingFactor is specified per channel in a 1 x NrOfChannels array.

  • NrOfSamples
    The number of exported analog samples per channel (1 x NrOfChannels array).

  • Frequency
    The sampling frequency of the analog data per channel (1 x NrOfChannels array).

  • Data
    Analog data per channel. The data is formatted as a matrix with the dimensions NrOfChannels x max(NrOfSamples). In case the channels have different frequencies, the shorter rows are appended with NaNs.

    For analog boards, the units of the exported data are in V. EMG data from integrated devices are exported in μV or mV, depending on the units provided by the device. For other data types from integrated devices, the units are converted to SI units associated with the data type.

Force

The field Force contains a struct array with data from the force plates. The elements of the struct array contain the data per force plate.

  • ForcePlateName
    The name of the force plate that was used in the capture.

  • NrOfFrames
    The number of channels that were used in the capture.

  • SamplingFactor
    The multiplication factor compared with the motion capture frame rate.

  • NrOfSamples
    The number of samples in the analog capture.

  • Frequency
    The frequency of the analog capture.

  • Force
    The force data in newton (N), the data is given for X, Y and Z direction.

  • Moment
    The moment data in newton meter (Nm), the data is given for X, Y and Z direction.

  • COP
    The centre of pressure on the force plate (in mm), the data is given X, Y and Z direction.

  • ForcePlateLocation
    The location of the force plate in measurement coordinate system. The corners are in the order upper left, upper right, lower right and lower left seen in the force plate coordinate system.

  • ForcePlateOrientation
    Coordinate system in which force data is expressed: 0 (local force plate coordinates), 1 (global coordinate system).

  • ForcePlateOffset
    The force plate offset values as filled in for the specific force plate. The order is the same as on each respective force plate calibration settings in Project options.

RigidBodies

The field RigidBodies contains a struct with data for the 6DOF bodies. The struct contains the data of all rigid bodies present in the file.

  • Bodies
    The number of 6DOF bodies.

  • Name
    The names of the 6DOF bodies.

  • Filter
    Struct array with information about the filter used for the respective rigid bodies.

    • Preset
      Name of the filter preset used for the rigid body.

  • CoordinateSystem
    Struct array with information about the reference coordinate system used for the respective rigid bodies.

    • Reference
      Coordinate system option used for the rigid body. The possible options are Global, Relative and Fixed.

    • ParentRigidBody
      The number of the reference rigid body used for the Relative coordinate system option. For the Global and Fixed options the number is set to zero.

    • DataOrigin
      The fixed origin (x,y,z) used for the Fixed coordinate system option. For the Global and Relative options the value is set to (0,0,0).

    • DataRotation
      The fixed rotation matrix in relation to the global coordinate system used for the Fixed coordinate system option. For the Global and Relative options the value is set to the unit matrix.

  • Positions
    The position of the origin of the measured rigid body’s local coordinate system. It is given as a matrix with the dimensions: Bodies x Coordinates (X, Y and Z) x Frames. The positions are expressed in mm relative to the origin of the used coordinate system.

  • Rotations
    The rotation matrices of the rigid bodies. It is given as a matrix with the dimensions: Bodies x Rotation matrix elements (0-8) x Frames. The elements are placed in the matrix according to the following table:

    [0]

    [3]

    [6]

    [1]

    [4]

    [7]

    [2]

    [5]

    [8]

    For information about the rotation matrix, see Rotation angle calculations in QTM.

  • RPYs
    The roll, pitch and yaw of each rigid body. It is given as a matrix with the dimensions: Bodies x Rotation angles (roll, pitch and yaw) x Frames. The rotation angles are in degrees.

    The matrix will always be called RPYs even if the definitions are changed on the Euler angles page in the Project options menu.

  • Residuals
    The residual of the rigid bodies.

Skeletons

The field Skeletons contains a struct array with data of the skeletons. The elements of the struct array contain the data per skeleton.

  • SkeletonName
    The name of the skeleton [char array].

  • Solver
    The type of solver used for the skeleton.

  • Scale
    The scale setting used for the skeleton. In the MAT export the scale factor is defined as the inverse ratio. For example, a Scale value of 0.8 corresponds to a scale factor of 125% in QTM.

  • Reference
    Reference used for the skeleton data. Global: all segment positions and rotations are expressed relative to the global coordinate system. Local: all segment positions and rotations except the Hips segment are relative to their respective parent segment.

  • NrOfSegments
    Number of segments of the skeleton [double].

  • SegmentLabels
    Names of the segments of the skeleton [1 x NrOfSegments cell array with char elements].

  • PositionData
    Position data (X, Y, Z) of the segments of the skeleton [3 x NrOfSegments x Frames double].

  • RotationData
    Segment rotation data in global coordinate system expressed as quaternions (QX, QY, QZ, QW) [4 x NrOfSegments x Frames double].

SMPTETimecode

The field SMPTETimecode contains a struct array with the SMPTE timestamps of the frames in the file. The elements of the struct array contain the timestamp data per frame.

  • Hour
    The hour of the timestamp.

  • Minute
    The minute of the timestamp.

  • Second
    The second of the timestamp.

  • Frame
    The SMPTE frame number of the timestamp.

  • Missing
    Indicates if the SMPTE timecode is extrapolated if the SMPTE synchronization source is lost during the measurement.

    In QTM versions 2.15 and earlier an additional field Subframe is included, representing an index of marker frames within a SMPTE frame.

    The values are represented as int64 numbers in Matlab. To use them in calculations, you may have to convert them to double precision using the double() function.

IRIGTimecode

The field IRIGTimecode contains a struct array with the IRIG timestamps of the frames in the file. The elements of the struct array contain the timestamp data per frame.

  • Year
    The year of the timestamp.

  • Day
    The day of the timestamp.

  • Hour
    The hour of the timestamp.

  • Minute
    The minute of the timestamp.

  • Second
    The second of the timestamp.

  • Tenth
    The decisecond of the timestamp.

  • Missing
    Indicates if the timecode is extrapolated if the IRIG synchronization source is lost during the measurement.

    The values are represented as int64 numbers in Matlab. To use them in calculations, you may have to convert them to double precision using the double() function.

CameraTimecode

The field CameraTimecode contains a struct array with the camera timestamps of the frames in the file. For more information about Camera time, see chapter Timestamp.

The CameraTimecode struct array is only available when the Camera time option is enabled during the capture.

The elements of the struct array contain the timestamp data per frame.

  • Tick
    Tick value of camera timestamp. This value represents the time in seconds multiplied with a factor 107.

  • Missing
    Indicates if the timecode is extrapolated if the synchronization source is lost during the measurement.

    The values are represented as int64 numbers in Matlab. To use them in calculations, you may have to convert them to double precision using the double() function.

Events

The field Events contains a struct array with a list of all the events in the file. The elements of the struct array contain the data per event.

  • Label
    The label of the event.

  • Frame
    The corresponding frame of the event. The time will be rounded to the nearest frame.

  • Time
    The time of the event.

GazeVector

The field GazeVector contains a struct array with the gaze vector data included in the capture. The elements of the struct array contain the gaze vector data per eye.

  • GazeVectorName
    The name of the gaze vector.

  • NrOfSamples
    The number of samples in the gaze vector data.

  • StartOffset
    The offset time for the first gaze vector frame. It is needed since you may not always cut the measurement range at the start of gaze vector frame. Reduce the start time of the gaze vector data with the offset so that it actually starts before the marker data.

  • Frequency
    The frequency of the gaze vector data.

  • HWSync
    Indicates if hardware sync was used for the eye tracker data or not. The values can be 0 (no hardware sync) or 1 (hardware sync).

  • Filter
    Indicates if the gaze vector data was filtered or not. The values can be 0 (not filtered) or 1 (filtered).

  • GazeVector
    Array with the gaze vector data in the following order: X Pos, Y Pos, Z Pos, X Vec, Y Vec, Z Vec. The X/Y/Z Pos values represent the origin of the gaze vector in mm, and the X/Y/Z Vec values represent the 3-dimensional normalized gaze vector.