C3D Format/pt
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 to 3 sections; a Header Section, a Parameter Section, and a Data Section containing ANALOG (1 DOF) and POINT (3 DOF) data.
| Header | Parameter | Data |
The Header block contains a summary of the data storage, including pointers to the start of the Parameter and Data blocks.
The Parameter section defines the way the data is interpreted; for example, the Force Platform Parameters. Visual3D allows the user to modify these parameters in the file.
The Data block contains the actual data itself. It is possible to modify the data that was stored in the C3D file, but we frown upon this idea, so it is very difficult to do this in Visual3D.
C3D Header Format
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 | |
| 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 |
Common POINT Parameters
Common parameters that Vicual3D 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
- Modify_Point_Parameters
- /POINT_LABELS=
- ;
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:
- Modify_Point_Parameters
- /POINT_LABELS= PT1+PT2+PT3+PT4+PT5
- ;
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:
- Modify_Point_Parameters
- /POINT_LABELS= PT1+PT2+PT3+PT4+PT5
- ;
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 another C3D 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:
- 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
In Visual3D version 4.90, we have implemented both methods of defining the number of frames.
C3D ANALOG Parameters
Common ANALOG Parameters
Common parameters that Visual3D expects to be in the ANALOG Section of the C3D File.
| 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 |
| 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. |
| USED | The number of signals containing ANALOGdata |
| LABELS | The Label Names of the ANALOGdata 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 ANALOGdata 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
- Modify_Analog_Parameters
- /ANALOG_LABELS=
- /ANALOG_GEN_SCALE=
- /ANALOG_SCALE=
- /ANALOG_OFFSET=
- /UPDATE_C3D_FILE=FALSE
;
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
- 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
;
C3D FORCE_PLATFORM Parameters
All force platform types contain the following parameters.
- ZERO= the range of frames for which a background noise level is calculated and then subtracted from each of the analog channels
- CHANNEL= an array containing the ANALOG channels associated with the force platform
- ORIGIN= The origin of the force platform in the force platform coordinate system (see the force platform manufacturer specifications.
- 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.
In addition to these Parameters Visual3D recognizes the following parameters
- 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.
- BASELINE'= 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.
There are many different force platforms, including instrumented treadmills, and super-structures attached to the force platform. The C3D parameter identifying the type is
- TYPE= types of force platform Visual3D recognizes the following force platform types.
- 1= This type is relatively uncommon. The resultant Force Vector, Center of Pressure (on the top surface of the platform), and the Free Moment (only the component perpendicular to the surface).
- 2= AMTI, Bertec, and Kyowa-Dengyo
- 3= Kistler
- 4= Equivalent to Type 2 with a CalMatrix
- 5= AMTI portable 8-channel with a CalMatrix
- 6= 12-channel (typically 4 - 3 DOF load cells
- 7= Equivalent to Type 3 with Cal-Matrix
- 1= This type is relatively uncommon. The resultant Force Vector, Center of Pressure (on the top surface of the platform), and the Free Moment (only the component perpendicular to the surface).
- 11-19 reserved for instrumented treadmills. The following are currently implemented
- 11-19 reserved for instrumented treadmills. The following are currently implemented
- 11= Kistler Split Belt Treadmill (split bilaterally).
- 12= Gaitway Treadmill (split anterior/posterior)
- 11= Kistler Split Belt Treadmill (split bilaterally).
- Type 21-29 reserved for super-structures
- Type 21-29 reserved for super-structures
- 21= AMTI-Stairs. 4 Interlocking Stairs attached to 2 treadmills
- 21= AMTI-Stairs. 4 Interlocking Stairs attached to 2 treadmills
- There are a number of parameters that are unique to each force platform type. Visual3D recognizes the following additional parameters for each type.
- Type 1
- CHANNELS= Fx, Fy, Fz, COPx, COPy, FreeMoment
- Type 2
- CHANNELS= Fx, Fy, Fz, Mx, My, Mz
- Type 3
- CHANNELS= Fx12, Fx34, Fy14, Fy23, Fz1, Fz2, Fz3, Fz4
- Type 4
- CHANNELS= Fx, Fy, Fz, Mx, My, Mz
- CALMATRIX= 6x6 matrix that scales ANALOG data from volts to Newtons and Newton-millimeters. Note that the C3D format assumes that all units are consistent. If the POINT data are stored in units of millimeters, the moment channels should be scaled to Newton-millimeters.
- CHANNELS= Fx, Fy, Fz, Mx, My, Mz
- Type 5
- CHANNELS= Cz, Dz, Az, Bz, Yac, Ydc, Xab, Ybd
- CALMATRIX= 6x8 matrix that scales ANALOG data from volts to Newtons.
- CHANNELS= Cz, Dz, Az, Bz, Yac, Ydc, Xab, Ybd
- Type 6
- CHANNELS= Fx1, Fy1, Fz1, Fx2, Fy2, Fz2, Fx3, Fy3, Fz3, Fx4, Fy4, Fz4
- CALMATRIX= 12x12 matrix that scales ANALOG data from volts to Newtons.
- CHANNELS= Fx1, Fy1, Fz1, Fx2, Fy2, Fz2, Fx3, Fy3, Fz3, Fx4, Fy4, Fz4
- Type 7
- CHANNELS= Fx12, Fx34, Fy14, Fy23, Fz1, Fz2, Fz3, Fz4
- CALMATRIX= 8x8 matrix that scales ANALOG data from volts to Newtons.
- FPCOPPOLY= 2x6 matrix containing Polynomial Correction Factors for the Center of Pressure Data
- CHANNELS= Fx12, Fx34, Fy14, Fy23, Fz1, Fz2, Fz3, Fz4
- Type 11
- CHANNELS= Fx12, Fx34, Fy14, Fy23, Fz1, Fz2, Fz3, Fz4
- CALMATRIX= 8x8 matrix that scales ANALOG data from volts to Newtons.
- FPCOPPOLY= 2x6 matrix containing Polynomial Correction Factors for the Center of Pressure Data
- FPCOPTRANS= 1x2 containing an addition translation of the COP along the surface of the platform
- FPCOPTOR= additional rotation of the center of pressure about an axis perpendicular to the surface of the force platform
- CHANNELS= Fx12, Fx34, Fy14, Fy23, Fz1, Fz2, Fz3, Fz4
- Type 12
- Note: The Gaitway treadmill has platforms place anterior/posterior on the treadmill. Visual3D expects a continuous force vector under each foot, which typically means that the force vectors should be continuous bilaterally. Each platform of the treadmill contains 4 vertical force channels. All 8 channels are defined for the force platforms. To distinguish the left and right plates the ORIGIN parameter is interpreted as the parameters a, c, d as defined in the Gaitway manual. A negative value in a means the left side is being computed.
- CHANNELS= Fz11, Fz12, Fz13, Fz14, Fz21, Fz22, Fz23, Fz24
- CALMATRIX= 8x8 matrix that scales ANALOG data from volts to Newtons.
- GAITWAY_MIDLINE= the midline for bisecting the 2 new pseudoplatforms into left and right sides
- CHANNELS= Fz11, Fz12, Fz13, Fz14, Fz21, Fz22, Fz23, Fz24
- Type 21
- CHANNELS= Fx, Fy, Fz, Mx, My, Mz
- CALMATRIX= 6x6 matrix that scales ANALOG data from volts to Newtons and Newton-millimeters. Note that the C3D format assumes that all units are consistent. If the POINT data are stored in units of millimeters, the moment channels should be scaled to Newton-millimeters.
- STEP1_CORNERS=The (x,y,z) coordinates of the first step corners in the laboratory coordinate system.
- STEP2_CORNERS=The (x,y,z) coordinates of the second step corners in the laboratory coordinate system.
- CHANNELS= Fx, Fy, Fz, Mx, My, Mz
Note que o CalMatrix pre-multiplica os sinais analógicos
- [Scaled Analog] = [CalMatrix][Analog]
Editing C3D Parameters
Visual3D has limited capacity for modifying the C3D Parameters. Visual3D is capable of modifying
C3D Parameter FORCE_PLATFORM:BASELINE
This 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.
Exporting_ C3D_File
There are two ways to export the c3d file to the Visual3D workspace.
1. Using the File Menu option "Export C3D File"
2. Using the Export_C3D_File Pipeline Command
- The equivalent data export can be achieved using the following Pipeline comand.