Diagnosing C3D problems

If you are having issues with C3D files then a quick solution may be to download Mokka and the MLSviewer, two free applications from the www.c3d.org web site, and use them to open your C3D file.  Mokka will normally display the C3D marker data and analog information in a visual 3D workspace on a Windows system, while the MLSviewer will display the C3D structure and data contents in a format that makes it easy to explore both the file contents and structure.  If both applications succeed in opening and displaying the C3D file with problems in other applications then you can examine the file in detail and may be able to determine the cause of the problem by comparing the contents of the problem file with the contents of any of the test suites available from the C3D web site or the sample files supplied with the two viewer applications.

All early C3D files will have less than 32767 frames and most applications should open these files without any problems.  Files created in the early 2000’s may have frame ranges from 32767 to 65535 frames and some applications may have problems opening these files.  In recent years C3D files with more than 65535 frames have been appearing and manufacturers have invented various methods of storing the frame count that may not be understood by all applications.  In addition the increased frame count may cause internal overflow errors in some applications that were written for the clinical environment where data collections are typically less than a couple of minutes.

The Mokka application (MOtion Kinetic and Kinematic Analyzer) is an unsupported, user written application, that can be downloaded from the c3d.org web site and displays the C3D file contents in a graphical environment which makes it easy to visualize and examine the 3D and analog data contained in the C3D file.  The Mokka graphical interface makes C3D data visualization convenient but it does not provide a detailed breakdown of the C3D file contents and, as a user written application, it is unsupported and as a result it may report “errors” due to some misunderstandings about the details of the C3D file format, so any error messages displayed by Mokka may be a result of internal Mokka issues.  For example when a C3D file does not contain any force plate data and the FORCE_PLATFORM:USED parameter has been set 0 (conforming to the C3D format) Mokka may report that the force plate location parameters are missing even though the C3D file parameters have documented that there are no force plates.  So the “error” that Mokka reports may be an internal coding error, not an actual C3D file error in some cases.  As a result Mokka is mainly a convenient way to view the C3D file data and while the error logger reports may be helpful, they are not always accurate.

Since Mokka allows the user to save the C3D file after it has been opened it offers both the chance to “fix” an error or create a new error if the file is saved.

Figure 51 - The user-written Mokka application can open and display C3D file contents.

If you want to review the contents of the C3D file in detail then the MLSviewer is a good choice, it will open any C3D file format containing less than 32767 frames in a read-only mode to avoid any risk of modifying the C3D file contents.

The MLSviewer displays the contents of the C3D file in a familiar Windows display environment, interpreting the C3D file structure and displaying the file contents at a parameter and data section level with the ability to provide a detailed examination of the structure of each parameter within the C3D file.  If you are still having problems opening a file, but the MLSviewer allows you to see the file contents, then the next step is to debug the file contents using the details described in this C3D user guide as a reference for the contents and structure of the C3D file.

The MLSviewer does not support C3D files with more than 32767 3D frames and will display a message when if an attempt is made to open a larger C3D file.  It is a useful diagnostic tool because it does not write anything to the C3D file and does not modify the open C3D file in any way.

Figure 52 - The free MLSviewer allows a detailed examination of the C3D file structure.

The C3D file format is an efficient binary format that has existed for a very long time.  As a result of the binary format, writing data to the C3D file format is a little complex and it is not uncommon for new application programmers to fail to understand the format detail and capabilities.  This can result in new applications creating C3D files that they can read but other applications are unable to open or open and display incorrect values.  If you cannot get Mokka, or the MLSviewer to open the file and display the contents then you can be confident that it is either corrupt, or not a C3D file.

Figure 53 - Reviewing the C3D file header can reveal the structure of a C3D file.

The next option is to use a binary file hex editor to examine the file at a binary level – the first 512 bytes of the file form the C3D header that defines the C3D file structure and is documented byte by byte in this user guide together with all the parameter and group formats.  As a result the C3D file can be examined with a binary file editor to verify the contents.

For example, a detailed examination of the C3D file header record shown above at a binary level enables us to verify that the parameters start in the second 512 byte block, and the file stored data from twenty-six 3D points, sixteen analog channels and contains 450 frames of raw data, recorded at fifty frames/second with four samples of analog data stored with each 3D point frame sample.

While examining a C3D file byte by byte at a binary level with a hex editor can be time consuming, the documentation in this user guide allows you to verify, and even edit if necessary, individual parameters within the file at a binary level and verify the internal structure.