|
BTK Matlab Wrapper
0.3dev.0
Matlab bindings for the Biomechanical ToolKit library (BTK)
|
The following list gives you the steps to use BTK in Matlab.
This section is only necessary if you downloaded the sources of BTK. If you use a binary version, go directly to the tutorial Getting Started.
To simplify the way to build the Matlab support, the tool EasyInstallWithRedistributableMatlabToolbox.jar is proposed in the root of the sources.
To use this tool, we need to download the following software:
EasyInstallWithRedistributableMatlabToolbox.jar).When these software are installed, you only need to double click on the file EasyInstallWithRedistributableMatlabToolbox.jar. This tool will configure the sources, compile them and install the toolbox btk for Matlab.
Note: If your OS doesn't have Java installed (and you don't want or cannot install it), then you have again the possibility to use the tool EasyInstallWithRedistributableMatlabToolbox. For that, you have to go in the folder Batch and double clic on the file corresponding to your OS:
EasyInstallWithRedistributableMatlabToolbox_GCC_Unix.sh for Linux ;EasyInstallWithRedistributableMatlabToolbox_GCC_MacOSX.sh for MacOS X ;EasyInstallWithRedistributableMatlabToolbox_MSVC.bat for Windows.First of all, you need to add the path of the BTK toolbox in the list of the directories loaded by Matlab. Depending your OS, you will have to add the following path:
C:\Program Files\BTK\share\btk-0.1\Wrapping\Matlab\btk for Windows ;/usr/local/share/btk-0.1/Wrapping/btk for Un*x ;/Applications/BTK/share/btk-0.1/Wrapping/btk for MacOS X.To be sure that BTK is loaded in Matlab, type the command help btk in the Matlab's command window. You will see the the main documentation for the BTK toolbox. If it not the case, be sure of the path that you gave to Matlab to register the BTK toolbox.
Now, that BTK is recognized in Matlab, it comes easy to open your acquisition files. You have only to use the function btkReadAcquisition. Based on the content of your file, this function tries to open the given file and return a handle which will help you to access to the content of the acquisition.
Note: Due to the use of C++ object hidden by the handle, Matlab doesn't know the memory allocated for each acquisition. In lots of case, you don't need to manage the memory used by BTK in Matlab (for example, if you want to check the content of an acquistion or read a dozen of files to analyze gait data) as the command clear all will clear all the memory. But if you process hundred of files, then you have to use the command btkDeleteAcquisition. This command free the memory associated with the acquisition. This function can also be understood as a 'close' function.
This section presents you some possibilities to access or modify data stored in an acquisition.
An acquisition contains points (parameter with 3 components), analog channels (parameter with 1 component), events and metadata.
A point in BTK is a generic type which contains 3D data. Then markers, forces, moments, angles, powers are regrouped in this category. For example, to extract markers' trajectories you need to use the function btkGetMarkers like this:
If you load a C3D file already processed which contains kinematics or inverse dynamic (for example, by using PluginGait for the Vicon users), it is very simple to extract angles, forces, moments, powers, etc. You only have to use the corresponding function. All these functions return a structure where each field correspond to the label of the requested points.
You can also want to extract only few points from an acquisition and return then as a matrix. This can be realized by using a little script based on BTK functions.
Note: With BTK, it is not necessary to use the metadata (named group and parameter in a C3D file) TRIAL:ACTUAL_START_FIELD and TRIAL:ACTUAL_END_FIELD to determine what is the index of the first frame and the last frame. There is already some functions for this. The function btkGetFirstFrame returns the index of the first frame. The last frame will be determined by the function btkGetLastFrame which use the formula: btkGetPointFrameNumber(handle) - btkGetFirstFrame(handle) + 1.
Note: The frames extracted from the C3D correspond to the number of frames between ACTUAL_START_FIELD and ACTUAL_END_FIELD. If your acquisition start at the frame 511 and finish at the frame 8450, and you want the 1450th you only have to type extractedPoints(1450,:). However, if you want the frame #1450, then you have to substract the index of the first frame (here 511): extractedPoints(1450-btkGetFirstFrame(acq)+1,:).
If you can access to the data, you can also edit them and finally write them in a new acquisition file. It could be useful if you have your own algorithm to compute kinematic and inverse dynamic (or to compute the mean of each parameter over a gait cycle, or ...) and would like to save them in a C3D file to be used in another software like Polygon or Mokka.
The output is then a new C3D file containing the standard parameters required to be used in others softwares.
The analog channels contains all the 1D measures. All the sensors measuring voltage, angular velocity, acceleration, etc., should be stored in analog channels. From the hardware point of view, it corresponds to the sensors plugged into the analog to digital converter (ADC) card.
To extract the data related to the analog channels, the simplest is the command btkGetAnalogs. As the function btkGetPoints, it returns a structure where each field correspond to a analog channel. If you use a analog sample rate greater than the video frequency, then the number of analog frames is greater than the number of point frames. For example, using the functions btkGetPointFrequency and btkGetAnalogFrequency, you find that the video and analog frequencies are 100 Hz and 1000 Hz respectively. So it means that for 1 video frame you have 10 samples for each analog channels. This can be confirmed by the function btkGetAnalogSampleNumberPerFrame. So, for an acquisition of 10 seconds, you will have 1000 frames for the points and 10000 frames for the analog channels.
An easy way to extract the analog frame corresponding to the video frame can be realized with the following code:
An analog channel contains also of a numerical offset and a scale factor used for the analog to digital conversion or vice-versa. You can find them in the second output of the function btkGetAnalogs. These parameters are important if you want to add analog channels in your acquisition and then save it in a file. These informations should be found in your hardware system or in the configuration of your acquisition software.
To extract events, you only have to use the function btkGetEvents which sorts the events by label and by time.
events = btkGetEvents(acq)
events =
Left_Foot_Strike: [5.6300 6.6900 7.8100]
Right_Foot_Strike: [6.1600 7.3000 8.3000]
Left_Foot_Off: [6.2500 7.4500]
Right_Foot_Off: [6.9400 7.9800]
A metadata is a generic container to store the acquisition configuration. Or said differently, a metadata contains every informations which cannot be set into markers' trajectories nor analog channels' measures, nor events. For example, if you want to include subject's informations (sex, weight, height, ...) or force platform's configuration (corner's coordinates, analog channel used, ...), then the metadata are the right place to do this. In the C3D file format, the metadata are known as groups and parameters.
To access to the acquisition's metadata, you have to use the function btkGetMetaData which will all the content of the metadata from its root. The output of the function btkGetMetaData is a structure which gives you a tree with children and values. For example, if you want to access to the value of the metadata SUBJECTS:WEIGHT, you can use the following code:
If you are not sure that the metadata SUBJECTS:WEIGHT exists you can use the function btkFindMetaData.
In some case, your acquisition setup cannot record all the data by the same system and then, you have several files for one trial. This section explain you how to add a force platform into an acquistion.
A force platform is represented in BTK as a set of analog channels combined with a configuration stored in the metadata FORCE_PLATFORM and its children. This configuration is the same than the one proposed in the C3D file format (http://www.c3d.org/HTML/theforceplatformgroup.htm). To easily integrate a force platfrom, it exists the Matlab function btkAppendForcePlatformType2. This function appends an AMTI (or equivalent with FxFyFzMxMyMz measurements) force platform by adding required analog channels and the creation (or update) of its configuration.
One of the goal of BTK is also to give some tools to compute standard biomechanical parameters (kinematic, dynamic inverse, ...). All the existing tools are stored in the BasicFilters section in the help. For example, to determine the ground reaction forces (wrenches) from an acquisition containing a force platform, you only have to use the function btkGetGroundReactionWrenches. This function take into account the type of force platform (AMTI, Kistler, ...) and compute the group reaction wrench (force, moment and position). The point of application of each wrench is calculated from the formula of Shimba (1984) which also was described in Zatsiorsky (2002). Contrary to the center of pressure (COP) the point of wrench application (PWA) is calculated by using also the horizontal moments. The result is a structure with a number of elements equal to the number of force platforms.
Even if BTK is well adapted to open hundred of acquisition files and process them, there is a limitation in the mechanism used to manage memory between the C++ objects and Matlab. If you open too many acquisitions without releasing the memory, Matlab can send you an "Out of Memory" error and may crash... (see FAQ). One way to correct this problem is to use the function btkDeleteAcquisition (or btkCloseAcquisiton) which will release the memory associated to the C++ object.
1.8.5