HAS-Motion Software Documentation

C-Motion introduced the ROTATION data type in 2019 to handle the storage of a 4x4 Transformation matrix containing the 6 DOF information for a Sensor or Segment.

In its most straightforward use, if the origin of a segment is defined as the proximal end of a segment, the ROTATION matrix fully describes the pose (position and orientation) of that segment and no process is required to estimate the pose. The pose of a segment, therefore, is defined by one signal name, which minimizes the internal bookkeeping for keeping track of a segment.

The ROTATION group was introduced to handle C-Motion DSX results and to handle Theia Markerless Results.

The ROTATION group has since been adopted by Kinatrax , Motion Shadow , Treadmetrix and can be read by Vicon , Motion Monitor

Each signal contains a 4×4 Rotation matrix that transforms a signal from the local coordinates of the sensor/segment to the laboratory coordinates

[R]_4x4 [V_local]4x1 = [V_lab]_4x1

A good description of a 4×4 Rotation matrix can be found at Brain Voyager

The signals are stored in column major format in the C3D file, but displayed and used in Visual3D in the command row major format of Visual3D. ROTATION signals can be used to define LANDMARKS, define SEGMENTS, and to track SEGMENTS.

This section describes particular considerations for how the ROTATION data type is stored within the C3D file format.

The rules for storing and retrieving ROTATION parameters are consistent with the rules for storing and retrieving any C3D parameter.

ROTATION:USED: The number of ROTATION signals

The parameter name USED represents the number of 3D points, the number of analog channels, and the number of rotation signals in a C3D file. The three unique parameters are assigned to their own groups and referred to as POINT:USED, ANALOG:USED, and ROTATION:USED to avoid confusion.

ROTATION:DATA_START: Block number for the start of the Data Block

The ROTATION:DATA_START parameter is an unsigned 16-bit integer that points to the location of the start of the Rotation data section within the C3D file, allowing the Rotation section to start anywhere within the first 32Mb (65535*512/1024) of the C3D file.

ROTATION::RATE: Sampling Rate and ROTATION::RATIO:Ratio of ROTATION sample rate to POINT sample rate

The C3D file format is designed to store synchronized 3D Point data, analog data, and Rotation data. Rotation measurements are recorded at fixed intervals set by the ROTATION:RATE parameter. For consistency with C3D files prior to the introduction of the ROTATION group, the POINT:RATE is considered the base rate of a C3D file. If the ROTATION rate is stored at a higher, integer multiple ratio of the POINT:RATE, then ANALOG:RATIO parameter defines this multiple. Storing the RATE and RATIO is redundant, but for historical reasons both are stored.

ROTATION:FRAMES: Number of frames of data

Since the number of frames within each C3D file is stored in the C3D file parameter section as ROTATION:FRAMES, there is no need for an “end-of-data” marker - data is simply written from the first frame to the last frame. It is recommended that any unused storage in the final 512-byte block of the C3D file should be filled with 0x00h. While this might seem unnecessary in modern environments it will help debugging and fault-finding. Rotation samples can cross the 512-byte block boundaries within the C3D file.

ROTATION:LABELS: Name of each ROTATION signal

The C3D file format requires Rotation data values, defined by the ROTATION:USED parameter, to be written to the each frame within the Rotation data section in the order that they are listed in the ROTATION:LABELS parameter section. All applications that access the Rotation data must determine the storage order and identity of the Rotation signals by reading the order of the Rotation labels stored in the parameter section of each C3D file. The existence of a single point of Rotation data in only one frame of a C3D file requires that storage space for this rotation signal be allocated in every single frame of the C3D file. This can result in large C3D files with a large amount of wasted space if unused, short trajectories are preserved unnecessarily.

The purpose of the LABELS parameter is to allow applications reading data from the C3D file to search for a specific Rotation signal by referencing its LABELS value instead of looking for a specific trajectory number in a fixed list of trajectories. This allows applications to be written in a general manner so that they can process data by reference. An application written in this way will work in any environment, as it does not require that the 3D data be stored in any specific order within the C3D file.

The ROTATION:LABELS name must be 7-bit ASCII, UTF-8 encoding is only permitted in the stored array values. Rotation data are stored in the Rotation data section in the same order recorded in the ROTATION:LABELS parameter. When interpreted as an unsigned value, the ROTATION:LABELS parameter can refer to a maximum of 255 Rotation signals in a C3D data file. If the C3D file contains more Rotation signals (read the parameter ROTATION:USED to determine the actual number stored in the 3D/analog data section) than are described by ROTATION:LABELS parameters then the additional trajectories must be either referenced by number or can be defined by creating additional ROTATION parameters, for example ROTATION:LABELS2 and ROTATION:LABELS3, each supporting up to an additional 255 labels.

When multiple ROTATION:LABELS parameters are found in a file the total LABELS indexed is determined by the maximum number defined in each parameter – so a C3D file written with unsigned integers could store 255 labels in a single parameter. Individual labels must always be unique to identify each rotation in the file but there is no need to make them excessively descriptive as the ROTATION:DESCRIPTIONS parameter is provided for human intelligible descriptions.

ROTATION:DESCRIPTION: For each ROTATION:LABEL there is a ROTATION:DESCRIPTION that is simply an alternative, probably longer, explanation of the ROTATION:LABEL

The ROTATION:DESCRIPTIONS parameter is a character data array that usually consists of a short description of each Rotation referenced by the ROTATION:LABELS parameter. There should always be a one to one relationship between the number of LABELS and the number of DESCRIPTIONS although users occasionally create files with different numbers of LABELS and DESCRIPTIONS parameters.

By convention, these entries usually contain upper and lower case ASCII characters and are typically 32 characters in length. The original C3D format supported entries up to 127 characters long and, while this is now 255 characters and may use UTF-8 encoding to support localized character sets, it is recommended that the parameter size is always kept to a minimum to avoid wasting the C3D file parameter section storage space. Descriptions should always be concise because creating very long verbose or empty descriptions is a waste of space.

Although it is not strictly required, it is good practice to include a DESCRIPTIONS parameter for each point with a LABELS entry. Since this is an array of character strings, the comments in the LABELS parameter description regarding the maximum number of array entries also apply to this parameter. C3D files may contain up to 255 DESCRIPTIONS parameters, with additional descriptions stored in the additional DESCRIPTIONS2 parameter when necessary. This parameter exists to provide human readable documentation about each of the individual 3D ROTATION:LABELS, which are generally short abbreviations.

Each signal is represented by 17 float values (there is no physical meaning for scaling integer data).

The Rotation signals are written as sequential frames starting in the 512-byte block in the C3D file specified by the POINT:DATA_START parameter. Each frame contains 17 total entries:

• 16 entries for the 4×4 ROTATION matrix, stored as columns; and
• 1 entry for a reliability metric.

Rotation samples may only be stored in 32-bit floating-point format. This means that the sign of the POINT:SCALE parameter must be negative. If the POINT:UNITS parameter is mm, then the positional information in the 4×4 Rotation Matrix must be stored in mm.

Predimo has provided a MATLAB m-file for reading the c3d file that has been incorporated into their Myonardo software. Save the downloaded text on your PC as load3d.m.

You can download a sample C3D file|here.

In Visual3D, the origin (or proximal end of a segment) is defined by a vector

O_S = (0,0,0,1)_T

To locate the origin of the rotation matrix in a frame of data in lab space O_L using the ROTATION signal R, pre-multiply the origin vector O_S in local coordinates.

O_L = R O_S

In Visual3D, the distal end of the segment (D) is typically located at:

D_S = (0,0,-length,1)_T

and in lab space this is:

D_L = R D_S

Any other point on a segment P can be computed as

P_L = R P_S