HAS-Motion Software Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== C3D Format ======

Official documentation of the c3d format can be found at [[http://www.c3d.org|www.c3d.org]]

Visual3D complies with the c3d.org but has also introduced new PARAMETER GROUPS and new DATA BLOCKS, including the new [[Visual3D:Documentation:C3D_Signal_Types:ROTATION_DATA_TYPE|ROTATION]] group. If other software is not aware of these additions, these additions will be ignored, but should not cause any issues.

===== C3D File Format =====

The C3D file format is a flexible binary file containing data from a single trial of data.

C-Motion considers the C3D file a repository of the UNPROCESSED data collected during an experiment. However, it is not unusual for Motion Capture manufactures to violate this concept by storing PROCESSED or ANALYZED data in the C3D file BEFORE the file gets to Visual3D. This is a bit of a nuisance because the C3D format does not contain a conventional representation of the processing history of a signal, so unfortunately valuable information can be lost.

The C3D file typically consists of 3 sections;

a [[#C3D_Header|Header Section]]
a [[#C3D_Parameter_Format|Parameter Section]],
and one or more Data Sections.
The first data section always contains [[Visual3D:Documentation:C3D_Signal_Types:ANALOG_Data_Type#ANALOG_Data_Type|ANALOG]] (1 DOF) and [[Visual3D:Documentation:C3D_Signal_Types:TARGET_Data_Type#TARGET_Data_Type|POINT]] (3 DOF) data.
==== C3D Header ====

The Header block contains a summary of the data storage, including pointers to the start of the Parameter and Data blocks. The Parameter block also contains its own independent header at the top of the memory location to further define the location of the data elements. This format is illustrated below.\\


The C3D file uses the Header block to contain the label names and times of events in the data file. The number and labels for these events in the C3D file are limited to 18 four-character names, because the Header block is restricted to one record of data (256 two-byte words).

|1       |Byte 1: location of 1st parameter record\\ Byte 2: must contain 80decimal                                                        |
|2       |Number of 3D points                                                                                                              |
|3       |Number of analog channels/video frame                                                                                            |
|4       |First frame of .SEG file transferred to .C3D file                                                                                |
|5       |Last frame of .SEG file transferred to .C3D file                                                                                 |
|6       |Maximum interpolation gap (frames)                                                                                               |
|7,8     |(REAL*4) Scale factor for converting integer 3D data to reference system units. If negative, 3D data is already in REAL*4 format.|
|9       |Starting record number for 3D point and analog data                                                                              |
|10      |Number of analog frames/video frame                                                                                              |
|11,12   |(REAL*4)Video frame rate (Hz)                                                                                                    |
|13,147  |Not used                                                                                                                         |
|148,149 |Not used                                                                                                                         |
|150     |12345decimal -- keyword to identify presence of event data                                                                       |
|151     |Number of defined time events- maximum 18.                                                                                       |
|152     |Not used                                                                                                                         |
|153->188|(REAL*4)Event times in seconds (maximum of 18)                                                                                   |
|189->198|(BYTE*1)Event display switches (0=0n,1=Off)                                                                                      |
|199->234|(CHAR)Event time labels. Each time event name is composed of 4 BYTES (characters)                                                |

\\


==== C3D Parameter Format ====

The Parameter block contains data that defines the data collection process (e.g., the number of analog channels, the sampling rate, scaling factors), specifies the location of the data (and type of data) within the file, and sometimes contains isolated annotations. There are no restrictions to the types of data in the Parameter block, provided they are compatible with the Parameter Group format.\\


|Starting BYTE|LENGTH (Bytes)|Contents                                                                                                              ||
|1            |1             |Number of characters in parameter name                                                                                ||
|2            |1             |Group number (positive) to which parameter belongs                                                                    ||
|3            |n             |Parameter Name                                                                                                        ||
|3+n          |2             |(2-byte integer) offset in bytes pointing to start of next group/parameter                                            ||
|3+n+2        |1             |Length in bytes of each data element\\ \\ = -1 for Character\\ = 1 for Byte\\ = 2 for Integer*2\\ \\ \\ = 4 for Real*4||
|3+n+3        |1             |Number of dimensions of the parameter (maximum=7)\\ = 0 if the parameter is undimensioned                             ||
|3+n+4        |d             |Parameter dimensions                                                                                                  ||
|3+n+4+d      |t             |The Parameter data                                                                                                    ||
|3+n+4+d+t    |1             |Number of characters in description                                                                                   ||
|3+n+4+d+t+1  |m             |Parameter Description                                                                                                 ||

\\
Byte 3 of the first parameter record contains the number of parameter records, and Byte 4 contains 83decimal + processor_type. Processor_type may have the value 1 (PC-DOS), 2 (DEC:VAX,PDP-11) or 3 (MIPS: SGI, SUN). The parameter data start at Byte 5 of the first parameter record.\\


Each parameter group has a set format that describes its contents:

|Starting BYTE|LENGTH (Bytes)|Contents                                                                 |
|1            |1             |Number of characters in group name                                       |
|2            |1             |Group ID number (negative)                                               |
|3            |n             |Group Name                                                               |
|3+n          |2             |(2-byte integer)offset in bytes pointing to start of next group/parameter|
|3+n+2        |1             |Number of characters in group description                                |
|3+n+3        |m             |Group Description                                                        |

\\


The 3D coordinate and analog data are written frame-sequentially starting at the beginning of the first data record. The data are packed into records such that frames may cross record boundaries. By default, the data are stored in 16-bit integer format, although 32-bit floating format (REAL*4) may be used if greater precision is required.

Storage for each frame begins with the 3D coordinate data, followed by the analog data. If 16-bit integer storage is used, then the 3D coordinate data must be multiplied by the POINT:SCALE factor to generate values expressed in the external (reference coordinate system) measurement units. If floating point format is used the scale factor is set to negative number and will not be used.

The analog data are stored sequentially, by analog channel, immediately following the 3D coordinate data. If the analog capture rate was higher than the video frame rate, the order through the channels is repeated as many times as is appropriate. In addition, the analog data are stored in the C3D file in the same unscaled form as obtained by the data capture software.

The last analog data value is the end of storage for a given frame and is followed immediately by the 3D coordinate and analog data for the next frame.

WORD Contents

4Byte 1 : cameras that measured marker (1 bit for each camera) Byte 2 : average residual for point measurement  scale factor

|1|X-Coordinate of point  scale factor|
|1|X-Coordinate of point  scale factor|
|3|Z-Coordinate of point  scale factor|

=== POINT Parameters ===

Common parameters that Visual3D expects to be in the POINT Section of the C3D File.

|**FRAMES**      |The number of frames of POINT data                                                                                                                                                                                                                                                              |
|**RATE**        |The sampling rate of the POINT data                                                                                                                                                                                                                                                             |
|**SCALE**       |The scaling factor for the POINT data. A positive number indicates that POINT and ANALOG data are stored as INTEGER values. Visual3D assumes UNSIGNED INTEGER values unless otherwise stated.                                                                                                   |
|**DATE_START**  |The block number at which the Data Section starts.                                                                                                                                                                                                                                              |
|**USED**        |The number of signals containing POINT data                                                                                                                                                                                                                                                     |
|**LABELS**      |The Label Names of the POINT data signals                                                                                                                                                                                                                                                       |
|**DESCRIPTIONS**|The Descriptions of the POINT data signals. This information is rarely used by Visual3D.                                                                                                                                                                                                        |
|**UNITS**       |The Units in which the POINT data signals are stored in the file. The default value is mm (millimeters). Note that all other PARAMETERS must be consistent with this unit. For example, if the POINT UNITS are mm, the force platform siganls should be scaled to Newtons and Newton-millimeters|

\\
Other Parameters will be read by Visual3D but only in special circumstances will they be used.

== Modify_Point_Parameters ==

<code>
Modify_Point_Parameters
/POINT_LABELS=
;
</code>

Modify the POINT LABELS (e.g. Marker Names) in the c3d file. The LABELS listed will be applied to the POINT parameters in the order listed in the c3d file. If fewer LABELS are specified in the command than exist in the c3d file, only the number of LABELS specified will be modified.

For example, to modify the first 5 Point labels:

<code>
Modify_Point_Parameters
/POINT_LABELS= PT1+PT2+PT3+PT4+PT5
;
</code>

== LONG_FRAMES ==

The C3D File format has a limit of 32K frames of data because the POINT:FRAMES parameter is traditionally a SIGNED INTEGER. Visual3D was modified in Version 3.0 to treat the POINT:FRAMES parameter as a UNSIGNED INTEGER, which increases the number of frames to 64K.

In Visual3D Beta version 3.0 we modified the C3D reader to accept a new parameter

POINT:LONG_FRAMES
The parameter is a FLOAT that contains the number of frames. If this parameter exists, it takes precedence over the POINT:FRAMES parameter.
Vicon elected to tackle the problem of more than 64K of data by introducing two parameters that are stored in the C3D TRIAL Parameter Group.

These parameters are

TRIAL:ACTUAL_START_FIELD
TRIAL:ACTUAL_END_FIELD
Each of these parameters contains 2 unsigned integer values.

These two values are combined as follows:

<code>
start_frame= actual_start_field[1]*65535 + actual_start_field[0]
end_frame= actual_end_field[1]*65535 + actual_end_field[0]
num_frames= end_frame-start_frame
</code>

In Visual3D version 4.90, we have implemented both methods of defining the number of frames.

=== ANALOG Parameters ===

Common parameters that Visual3D expects to be in the ANALOG Section of the C3D File.

|**USED**        |The number of signals containing ANALOG data                                                                                                                                                  |
|**GEN_SCALE**   |Scaling factor that is multiplied by the Analog_Scale factors that are applied to every signal                                                                                                |
|**RATE**        |The sampling rate of the ANALOG data                                                                                                                                                          |
|**RATIO**       |The ratio of the ANALOG sampling rate to the POINT sampling rate                                                                                                                              |
|**SCALE**       |A scaling factor for each signal that is multiplied by the Analog_Gen_Scale and applied to each signal.                                                                                       |
|**OFFSET**      |an offset for each signal that is subtracted from each signal before the signal is scaled.                                                                                                    |
|**LABELS**      |The Label Names of the ANALOG data signals                                                                                                                                                    |
|**DESCRIPTIONS**|The Descriptions of the ANALOG data signals. This information is rarely used by Visual3D.                                                                                                     |
|**FORMAT**      |For integer data declares 12 bit or 16 bit data                                                                                                                                               |
|**UNITS**       |The Units in which the ANALOG data signals are stored in the file. The default value is v (Volts)                                                                                             |
|**BASELINES**   |Used by Visual3D to define a baseline to be subtracted from each analog signal after the SCALE and OFFSET are applied. This value is typically computed during Real_Time streaming of the dat.|

Other Parameters will be read by Visual3D but only in special circumstances will they be used.

The **BASELINES** parameter was introduced by C-Motion to accommodate Real-time streaming data. For streaming data there is no frame number from which to define a range for the ZERO parameter. This doesn't mean that the ZERO parameter should be ignored.

In Visual3D streaming there is a button to starting the ZERO range. In order to replicate the data for post-processing these baselines need to be saved with the C3D file and the ZERO parameter set to 0,0.

== Modify_Analog_Parameters ==

<code>
Modify_Analog_Parameters
/ANALOG_LABELS=
/ANALOG_GEN_SCALE=
/ANALOG_SCALE=
/ANALOG_OFFSET=
/UPDATE_C3D_FILE=FALSE
;
</code>

This command can be used to change a selection of the ANALOG parameters in a C3D file. There must be the same number of values in the LABELS, SCALE, and OFFSET entries. The command will modify the parameters in order. For example, if two entries are specified, the first two entries in the ANALOG parameters will be modified; the remaining parameters will remain the same.

if UPDATE_C3D_FILE=TRUE the c3d file on disk will be modified automatically. If FALSE only the current workspace is modified, not the file on disk.

For example, to modify the SCALE for the first 5 Analog Signals; automatically save the file to disk. No other Analog parameters will be modified

<code>
Modify_Analog_Parameters
/ANALOG_LABELS=
/ANALOG_GEN_SCALE=
/ANALOG_SCALE= 1.0+1.0+1.0+1.0+1.0
/ANALOG_OFFSET=
/UPDATE_C3D_FILE=TRUE
;
</code>

=== ROTATION Parameters ===

Common parameters that Visual3D expects to be in the ROTATION Section of the C3D File.

ROTATION refers to a 4x4 Rotation Matrix.
The data is stored so that pre-multiplying a vector in a local coordinate system by the rotation matrix yields the vector in the laboratory reference frame.
[R4x4][VLocal4x1]=[VLab4x1]
|**USED**        |The number of signals containing ROTATION data                                        |
|**RATE**        |The sampling rate of the ROTATION data                                                |
|**RATIO**       |The ratio of the ROTATION sampling rate to the POINT sampling rate                    |
|**LABELS**      |The Label Names of the ROTATION signals                                               |
|**DESCRIPTIONS**|The Descriptions of the ROTATION signals. This information is rarely used by Visual3D.|
|**DATA_START**  |The start byte of the DATA SECTION containing the ROTATION data                       |

=== FORCE_PLATFORM Parameters ===

All force platform types contain the following parameters.

|[[Visual3D:Documentation:Pipeline:Force_Commands:FP_USED|USED]]          |The number of Force Platforms used                                                                                                                                                                                                                                                                                                                            |
|[[Visual3D:Documentation:Pipeline:Force_Commands:FP_ZERO|ZERO]]          |the range of frames for which a background noise level is calculated and then subtracted from each of the analog channels                                                                                                                                                                                                                                     |
|[[Visual3D:Documentation:Pipeline:Force_Commands:FP_ZERO|ZEROS]]         |this parameter has the same meaning as the **ZERO** parameter listed above except that it applies to each force platform individually. Visual3D leaves the **ZERO** parameter in the file for compatibility with other software                                                                                                                               |
|[[Visual3D:Documentation:Pipeline:Force_Commands:FP_CHANNELS|CHANNELS]]  |an array containing the ANALOG channels associated with the force platform                                                                                                                                                                                                                                                                                    |
|[[Visual3D:Documentation:Pipeline:Force_Commands:FP_ORIGIN|ORIGIN]]      |The origin of the force platform in the force platform coordinate system (see the force platform manufacturer specifications.                                                                                                                                                                                                                                 |
|[[Visual3D:Documentation:Pipeline:Force_Commands:FP_CORNERS|CORNERS]]    |The (x,y,z) coordinates of the force platform corners in the laboratory coordinate system. Note that there is a specific ordering of the four corners.                                                                                                                                                                                                        |
|[[Visual3D:Documentation:Pipeline:Force_Commands:FP_BASELINES|BASELINES]]|this parameter is used when capturing real-time streaming data. During streaming of the data the user can capture 10 frames in succession to be used as a baseline. These frames may never be saved to a C3D file, so the BASELINE values are included in the parameter section so that the post-processing data will be the same as the real-time processing.|
|[[Visual3D:Documentation:Pipeline:Force_Commands:FP_TYPE|TYPE]]          |types of force platform                                                                                                                                                                                                                                                                                                                                       |

=== Exporting_ C3D_File ===

There are two ways to export the c3d file to the Visual3D workspace.

1. Using the [[Visual3D:Documentation:Pipeline:File_Commands:Export_C3D_Manually|File Menu option "Export C3D File"]]


2. Using the [[Visual3D:Documentation:Pipeline:File_Commands:Export_C3DFile|Export_C3D_File Pipeline Command]]

The equivalent data export can be achieved using the following Pipeline command.
</translate>