C3D Format

Official documentation of the c3d format can be found at [www.c3d.org]

Visual3D complies with the c3d.org but has also introduced new PARAMETER GROUPS and new DATA BLOCKS, including the new 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 Header Section

a Parameter Section,

and one or more Data Sections.

The first data section always contains ANALOG (1 DOF) and 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

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.

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:

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.

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

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

;

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.

USED	The number of Force Platforms used
ZERO	the range of frames for which a background noise level is calculated and then subtracted from each of the analog channels
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
CHANNELS	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.
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.
TYPE	types of force platform

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.

</translate>