C3D Format/en

From Visual3D Wiki Documentation
Jump to: navigation, search

<languages />

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
= 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

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
11-19 reserved for instrumented treadmills. The following are currently implemented
11= Kistler Split Belt Treadmill (split bilaterally).
12= Gaitway Treadmill (split anterior/posterior)
Type 21-29 reserved for super-structures
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.
Type 5
CHANNELS= Cz, Dz, Az, Bz, Yac, Ydc, Xab, Ybd
CALMATRIX= 6x8 matrix that scales ANALOG data from volts to Newtons.
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.
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
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
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
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.


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

  1. Point Labels
  2. most Analog Parameters
  3. all Force Platform Parameters

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.
Retrieved from ""