Parameter Format

The first byte in the parameter record is a one’s complement signed integer that stores the number of characters in the parameter name.  This can be a positive or negative number, a positive number indicates that the parameter is unlocked and any application can change it.  A negative count indicates that the parameter is locked and should not be changed without careful consideration of the consequences.  Parameter names can have from 1 to 127 ASCII characters (using the 7-bit characters A-Z, 0-9 and underscore) although four characters should generally be considered a minimum.  UTF-8 encoding is not permitted in parameter names.

A locking mechanism is implemented to provide a mechanism to limit the ability of casual users to change parameters using parameter examination and editing programs that might cause data corruption.  Any program that allows the user to modify parameters must respect the locking mechanism – editing may be permitted for applications that modify the C3D file structure but, for example, allowing a user to change the locked POINT:RATE parameter without resampling the data will corrupt the file.  The effectiveness of the locking mechanism depends on the degree to which locking is supported and the consistency with which applications that create C3D files apply the locking property.  The fact that a parameter has been locked by one application does not prevent any other application from changing it – locking simply provides a flag that may be utilized by other locking aware applications.

For example an application that resamples the C3D point data will need to update the locked POINT:RATE parameter to record the new data rate but users occasionally think that they change the C3D file sample rate by simply editing the POINT:RATE parameter - a simple edit that would corrupt the C3D file.  As a result it is strongly recommended that all applications do not normally allow users to change locked parameters – applications that permit the editing or modification of locked parameters should include a method of restricting this feature to prevent the casual user from accidentally corrupting their C3D data files.

While it is recommended that all C3D applications respect the parameter lock flag and follow procedures to preserve C3D file contents from casual changes that might corrupt the contents, this is not a strict requirement in the C3D file format.  Many modern applications set the parameter lock flag incorrectly, either leaving every parameter unlocked or occasionally locking every parameter, even parameters like POINT:DESCRIPTIONS that users may often need to update during post-collection data analysis or processing.

Figure 15 - The C3D parameter format.

The second byte in the parameter header is a signed integer that contains the parameter ID number – this is always a positive value between +1 and +127 and is used to link the parameter to a specific group.  A parameter with a positive ID value that matches a negative group ID number indicates that the parameter belongs to that group.  Note that the numeric value chosen for a group ID number is not fixed and may vary from one C3D file to another.  It is not required that group ID numbers are assigned in a contiguous sequence.  In the example below the ID number is 0x01h – indicating that this parameter belongs to the group described earlier, in fact this is the parameter POINT:DATA_START within this file.

Figure 16 - The DATA_START Parameter is locked and has a ten-character name.

The string containing the parameter name starts at the third byte in the parameter record.  While parameter names can have from 1 to 255 characters (using 7-bit ASCII character sets A-Z, 0-9 and the underscore “_” character) the choice of a new name should be concise although four (4) characters should generally be considered a minimum.

An unsigned word pointer to the next parameter record structure follows the parameter name string unless this is the last parameter in the parameter section.  The last parameter in the parameter section must always have a pointer value of 0x0000h to indicate that there are no more parameters following.

A single byte follows which defines the parameter type; character, byte, integer or floating-point.  Note that the interpretation of the data values is controlled by the processor type which is usually determined by the hardware that originally generated the C3D file.  These are DEC, Intel, and SGI/MIPS formats.  All floating-point values in a given C3D file will use the same floating-point format as recorded in the fourth byte of the parameter record header.  Signed integer data can be stored in two different ways (little endian for DEC/Intel, and big endian for MIPS).

The next byte in the parameter record is the number of dimensions in the parameter, which can be from zero (0) to a maximum of seven (7) dimensions.  A parameter with zero dimensions is a scalar.  If the parameter is a matrix then the actual parameter dimensions (e.g.  2 by 3, 6 by 6 etc.,) are stored in the next two bytes.  This is then followed by the parameter data itself.

A single byte follows the pointer to the next parameter data structure – this stores the length of the parameter description string (0-255 characters), which immediately follows this byte.  The parameter description can contain mixed case characters and is generally used to provide a human-readable description of the parameter function.

Figure 17 - A locked integer parameter (USED = 36) with an accurate description.

The parameter name is limited to a subset of ASCII characters, this is designed to be easily machine readable and should always be concise as illustrated above.  Analysis and processing of the data should always reference the name.  The description string is supported by all parameters and is supported to provide a human readable interface that support UTF-8 character sets.

In the example below, the parameter RATE in the group POINT is stored as follows:

Figure 18 - A simple parameter record stored as a floating-point value.

In this case, the RATE parameter is correctly locked (first byte describing the length of the parameter name is negative) and it belongs to the GROUP with a group ID of 1 (the second byte) which, in this file is the POINT group making this the POINT:RATE parameter.  The word following the parameter name describes the length of the rest of the parameter – effectively pointing to the start of the next parameter.  Following the parameter length word is a single byte that defines the storage format used by the parameter (in this case 4 specifying floating-point values) followed by a 0 indicating that the parameter is a scalar value.  The following 4-byte word is a single floating-point value (a scalar), followed by a single byte that describes the length of the parameter description and then the description string which in this case, is the five character string “Video” – the next parameter (if any) will start immediately following this description string.

While parameter name must be stored as ASCII characters to guarantee universal file access the parameter description, stored as UTF-8 characters, enables the parameter to be presented to users in their local language and characters.