Press "Enter" to skip to content

Working with BTK and Mokka

Patrick Mai 3

Last updated on 25. October 2020

In biomechanical research, we often collecting motion capture (marker trajectories) and force (analog data) data to calculate joint kinematics (joint angles and joint angular velocities) and joint kinetics (joint moments and joint power). Usually, this experimental data is collected with motion capturing software such as Qualysis Track Manager or Vicon Nexus, to name only a few. Regardless of the uses software to capture the biomechanical data the C3D file extension has been established as a standard for further data processing. Although C3D-files can be opened by the Motion Capturing Software, resource-saving and open source tools are available to visualize and manipulate C3D files. In this tutorial you will learn how to

  1. Visualize C3D files using Mokka

  2. Load C3D files with BTK in Matlab

  3. Downloads

1. Visualize C3D files using Mokka

Mokka is free to use and cross-platform software to easily analyze biomechanical data. Mokka can be downloaded from the website http://biomechanical-toolkit.github.io/mokka/index.html and requires no installation.

After downloading and unpacking the Mokka version for your operating system the folder should look like figure 1. Click on Mokka and a graphical user interface (GUI) that looks like figure 2 will open. 

Figure 1: Mokka folder after unpacking the .zip file.
Figure 2: The default Mokka GUI

To load a C3D file, click on File and choose Open. Than you can chose a file that you wish to visualize. To try it out, you can download our example data

Please load Running_Example.c3d file. After that, the GUI should look similar to figure 3. Within the GUI you can explore the captured 3-dimensional experimental data.Each gray Point represents a spherical marker attached to the human body. By clicking on a specific marker, the name (often referred to as the marker label) is highlighted on the right-hand side list box (right side).

With the play button at the left lower corner of the GUI, you can see how the participant is running. Alternatively, you can use the time bar right next to the play button to inspect every frame (point in time) of your experimental data.

The chart window in the middle of the GUI can provide further information about the single components of your data. Note if the chart window is not shown go to Window ->Layout -> 3D and Charts. Now you can drag and drop labeled markers from the List box to the chart window, to see its X, Y, and Z coordinates over each instant in time.

Figure 3: The Mokka GUI after loading Running_Example.c3d

Within the list box, you can also scroll down to the force platform data (if some exist). For the provided example Force Platform #2 was used. You can expand the force platform #2 field and can visualize the force components (Forces and Moments) in the same way as the marker trajectories by drag and drop the component to the chart view. However, when having many markers attached to your participant, visual inspection of your marker trajectories can become cumbersome. Therefore loading a model fitting to your data can be helpful.

For this tutorial, we have already generated a model for our marker setup. To load the model go to Edit -> Options. Check the box Use default configuration and click on Choose Select the file we have provided named full_body_Model.mvc . After the operation has been completed the 3D view should contain different colored markers and connected segments.

Figure 4: A whole body model adapted to our marker setup

Please note that the model has been adjusted to the used marker set. When using your own experimental data, with different marker names, you need to define new segments according to your marker lables. New Segments can be generated under Tools -> Model -> New Segment.

For further data processing, it is sometimes useful to crop your C3D files. Mokka provides the ability to crop (or cut) your C3D files very easily. Within the time bar, you can use the sliders to the left and the right end of the time bar to crop the C3D file. The frames which are removed from the C3D file are marked in blue. When right-click anywhere in the time bar you can selectCrop Frame of Interest. Finally, you need to store the cropped file with File -> Save As or Save (to overwrite the existing file).

Figure 5: Cropping C3D files

Although, Mokka is useful for visualization purpose it does not allow to calculate joint kinematics and kinetics. It becomes also extraordinary time consuming when much experiental data needs to be batch processed. Within the next step, we would like to show you how to read in C3D files into Matlab.

2. Load C3D files with BTK in Matlab

For loading C3D files into your Matlab workspace you first need to download some additional, open-source functions. The biomechanical toolkit (BTK) is a frequently used cross-platform toolkit for reading, writing, and manipulating C3D files.

First, you need to download BTK from the website (https://code.google.com/archive/p/b-tk/downloads). Please ensure to download the correct version for your operating system. For us, the version btk-0.3.0_Win7_MatlabR2009b_64bit.zip works best. After downloading the toolkit you need to unpack the archive by using a standard archive converter.

Now you need to tell Matlab where all the BTK functions are located. Open Matlab and go to Home Set Path Add with Subfolders… and selected the folder (in our example btk-0.3.0_Win7_MatlabR2009b_64bit, note use the unpacked data folder and not the compressed zip archive). You can check if the Path is set correctly when typing v = btkGetVersion into your Matlab command window. If Matlab outputs a version number (for example ‘0.3.0’) the path is set correctly.

Figure 6: Ssetting the right folder path in Matlab

You can now read, manipulate, and write C3D files with Matlab. For the full list of the BTK function please refer to the following webpage http://biomechanical-toolkit.github.io/docs/Wrapping/Matlab/annotated.html

In the Download Section below, you can find all example C3D data and some example Matlab code. This code will show you how to read and add virtual markers to a C3D file (static trial). Furthermore, the code will show you how to calculate stance time based on force data and add touchdown and toe-off events to a C3D file (running trial).

3. Downloads

  1. Stephan Kirchharz Stephan Kirchharz

    This is one of the most valuable articles I’ve read in the last months. I would like to see more of this! Finally getting some understanding what my professor is talking about.

    • Patrick Mai Patrick Mai

      Dear Stephan,

      great to hear. Let me know if what kind of tutorial you are interested in.

  2. […] several dynamic trials). Further information on how to work with .c3d files can be found in the BTK and Mokka tutorial. Additionally, the library consists of data that have been processed with the OpenSim software […]

Leave a Reply

Your email address will not be published. Required fields are marked *