The Parameter Section

All C3D files contain a parameter section that stores information about the data C3D file contents.  It stores information that describes the data stored in the file so that any user opening the file can process the contents once the parameter section has been read and the user understands the parameters.  The parameter section header records the endian format that defines the storage method for all 16-bit integers and 32-bit floating-point values stored in the C3D file, so the parameter section must be located and read before most of the C3D file header values can be interpreted.

Figure 7 - The parameter section location within the C3D file structure.


While the C3D file header describes basic information about the contents of a C3D file (the number of 3D points, analog channels and sample rates etc.) it is the information in the parameter section of the file that records the details that make the contents of the file intelligible.  For instance, the C3D header may tell you that the file contains 50 frames of data, each containing 20 3D points; however it is the parameters that may tell you that the 10th point in each frame is labeled “LTHI” and is described as the “Left Thigh Wand Marker”.

All parameters are organized into “groups” with unique ASCII group names so that related parameters (e.g., all the parameters containing information about the analog data in a C3D file) can be located and their associations identified.  All groups and parameters support an optional UTF-8 description string to document their function, allowing users worldwide to open a C3D file and understand the contents.

When described and documented, the group name and parameter name are separated by a colon (:) so that when the parameter “SCALE” belongs to the “ANALOG” group will be written as ANALOG:SCALE – the group name always precedes the parameter name.  The ability to reference parameters in this way allows similar parameters with different functions to exist in the same file without any risk of confusion.  Thus, the SCALE parameter ANALOG:SCALE is different from the parameter POINT:SCALE, the function of each parameter should be described by the associated parameter description string to help document the file contents.

All parameter or group names consist of 7-bit ASCII characters, letters A through Z, the numerals 0 through 9, and the underscore character “_”, other punctuation or printable characters may not be used and UTF-8 encoding is not permitted in group or parameter names.  All parameter and group names must start with letters A through Z.  When applications read group and parameter names, the case of the parameter or group name is not significant and punctuation characters should be ignored.  For example the label h00b00m2 must be read as H00B00M2 and the labels L.Post.Fem. and Acc_2:X must be read as LPOSTFEM and ACC_2X to guarantee universal access to the data.

For compatibility between software applications, the original C3D specification stated that when a parameter or group name is interpreted then only the first six characters of the group name and the first six characters of the parameter name are used.  It is essential that all group names, and all parameter names within each group, are unique.  The same names may only be used for two parameters if they occur in different groups, e.g. both POINT:SCALE and ANALOG:SCALE parameters are permitted; but POINT:MARKER_UNITS and POINT:MARKER_ID may cause problems because the first six characters in both parameter names are identical.

A parameter’s type determines the data that may be stored in the parameter.  Four parameter types are available; integer, floating-point, character, and byte.  An integer is normally a one's complement 16-bit signed number with a range of -32767 to +32767 although when used as a pointer, 16-bit integers are normally unsigned with a range of 1 to 65535.  32-bit floating-point numbers are written in scientific exponential representation, characters are symbols such as a letter entered from the keyboard, and a byte can contain a one’s complement 8-bit signed integer in the range -127 to +127 or an unsigned integer with a range of 0 to +255.

While C3D files contain both signed and unsigned values in the parameter section, certain items such as the parameter and group ID numbers and lengths must always be read as signed integers because the sign affects the parameter structure.  However the dimensions of a parameter define how many elements are stored in the parameter so dimensions are always positive values.  The term dimension is a programming convention - if a parameter has no dimensions then it may only hold one value of its data type, for example one dimension it is presented in the form such as PARM(4) where the 4 indicates that the parameter called PARM is capable of holding four values.  Examples of two- and three-dimensional parameter arrays are PARMA(4,5) and PARMB(3,5,7).  The first example has 4 x 5 = 20 elements, and the second parameter holds 3 x 5 x 7 = 105 entries.


Parameter header

C3D Groups and Parameters