Group Format

The first byte of a C3D group record is a one’s complement signed 8-bit integer that stores the number of characters in the group name.  Group names can have from 1 to 127 characters (using the standard ASCII character set; A-Z, underscore, and 0-9) although four characters should generally be considered a minimum and twenty characters plenty.  The group name is simple a “name” that if used to reference the associated collection of parameters, it does not have to be long and descriptive – use the group description string to document its functionality.  All group names must start with the characters A-Z. The character count is always read as a positive number regardless of the actual sign of the stored value.

Figure 11 - The format of a Group Parameter.

The second byte of the group record contains the group ID number – this is always a negative value between –1 and –127 (hence it must be read as a one’s complement signed byte) and is used to link parameters to their groups.  A parameter with a positive ID value that matches a negative group ID number “belongs” to that group.  Note that the actual 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 shown the group ID number is 0xFFh, which is read as –1 (signed integer), thus all parameters with a parameter ID of 0x01 will belong to this group.

Figure 12 - A hex dump of a typical Group record – this example defines the POINT group.

Each group name must be unique and use only 7-bit ASCII upper case, numeric or underscore characters. The string containing the group name starts at the third byte.  Group names can have from 1 to 127 characters (using the character sets A-Z and 0-9) although four (4) characters should generally be considered a minimum.  Group names should not start with a number.  The hex dump shows the format for the POINT group record with a description where the characters POINT are stored (in hex) as 0x50, 0x4F, 0x49, 0x4E, and 0x54.

A word pointer to the next parameter data structure follows the group name string unless this is the last parameter in the parameter section.  The last parameter in the parameter section always has a pointer value of 0x0000h to indicate that there are no more parameters following.  In the example shown here, the pointer has the value 0x0017h, indicating that the next parameter record starts in 23 bytes.  While a group description is not required, if you are creating a new group or parameter then it is recommended that you describe it so that other users who open the file will understand its function.

A single byte follows the pointer to the next parameter data structure – this stores the length of the group description string (0-255 characters) that immediately follows this byte.  The group description can contain mixed case characters as well as space characters and is generally used to provide a human-readable description of the group function - UTF-8 encoding is permitted in the description string.  In the example above, the description length is 0x14h – the group description “3-D point parameters” contains 20 characters, while the “POINT” group below has no description string resulting in a description length of 0x00h.

Figure 13 - A simple group record with no description string

Although the example above does not have any associated description it is strongly recommended that the description string be used at all times to provide some basic information about the parameter item and its use.  Consider this as simply good programming practice to provide some documentation about the information stored in the C3D file.