BTK  0.3dev.0
Open-source library to visualize/process biomechanical data
Developer's guide

Table of contents

Supported compiler

The code compiles without any warning nor error under the tested configurations:

If your configuration is not listed here, please send an email to the mailing list to report it.

Extend BTK

As seen in the Advanced tutorial, it is pretty easy to Write a new class using the existing classes in BTK. If you want to add your new class in the BTK source code, then you need to embed it in the CMake project. First, it is important to add your file(s) in the folder representing the module to extend.
Edit the file CMakeLists.txt found in the folder where you add your files and add the CPP file in the sources to compile. In the case where your class is only composed of header, then you don't have to add any filename in CMakeLists.txt.

For example, if you want to add the class btk::EventDetector composed of the files btkEventDetector.h and btkEventDetector.cpp in the module BasicFilters, then you have to:

For other extension (add a new wrapper, a new module, ...), please contact the developers by using the mailing list. In some case, it is possible that a developer already starts the same extension without commit it as it is not enough mature and can help you.

Test drive development

When developing a new class / function / method, it is strongly advised to write at the same time, some unit tests, or regression tests. These tests give the possibility to check if the behavior of the code corresponds to the desired results. And later, to be sure that the general behavior stays the same even if you refactor the code.

You will find more information using google:

The library used in BTK to write the unit tests is a modified version of CxxTest. This code is embedded in the Utilities folder. The source code was modified to keep only the ErrorPrinter runner (no GUI) and add macros to generate the test runner instead of using Perl or Python.

Basically, the tests are defined in a suite of tests. So it is important to start by defining a suite by using the macro CXXTEST_SUITE and then, define inside the desired tests with the macro CXXTEST_TEST.

TS_ASSERT_THROWS_EQUALS(reader->Update(), const btk::AcquisitionFileReaderException &e, e.what(), std::string("Filename must be specified"));

Even if the suite and its test are defined you have to active them into the runner. This is done by using the macro CXXTEST_SUITE_REGISTRATION and CXXTEST_TEST_REGISTRATION to register the suite and the selected test respectively.

// ... Below the suite definition

To deactivate a test, you have only to comment its registration.

In BTK, the unit tests are in the Testing/Code folder. The Testing/Data folder contains input and output files used mainly by the tests for the modules IO and BasicFilters. To stay compatible with the current design, you have to write the tests' definition in a header file. Then this file is included in the _TDD* file associated with the module where your class was added. Now, compile the code and execute it to see if all the tests pass (you need to activate the option BUILD_TESTING in CMake).

The following list describes the contents of the files in the Testing/Code folder:

Programming style

The following subsections explain how to format the syntax of the files for the code, and its documentation.

Coding style

Doxygen documentation

To keep clean the headers, it has been chosen to write the documentation into the definition part of the code (in most of the case, in the CPP file).

The Doxygen documentation uses the JavaDoc style and the Doxygen command use the arobase @ instead of the backslash \ character. For example:

 * @class Acquisition btkAcquisition.h
 * @brief Contains the data related to a biomechanical acquisition.
 * A biomechanical acquisition can contains:
 *  - 3D data (makers, points, forces, moments, ...) ;
 *  - analog channels (force platform, emg, ...) ;
 *  - events
 *  - acquisition's setup ;
 *  - subject's informations.
 * @ingroup BTKCommon

Every function / class / method or member (public and protected) must have a block of documentation with at least a description and set into a module (using the command @ingroup). The known modules are listed in Modules page and reported here:

A class must have also a brief description to be included in the Class Index page.

If you need to add references into the description, then you can add the name of the authors ans the date between parenthesis (e.g. Foo et al, 2009 ; Bar & Foo, 2010) and add a paragraph named Reference at the end of the description. This paragraph will contain the details of the reference(s). The format should be:

For example:

@par Reference
Shimba T.@n
<em>An estimation of center of gravity from force platform data</em>.@n
Journal of Biomechanics, <b>1984</b>, 17(1), 53–60.

which gives the results:

Shimba T.
An estimation of center of gravity from force platform data.
Journal of Biomechanics, 1984, 17(1), 53–60.

Using SVN for BTK development

The library BTK uses Subversion (SVN) to manage files and directories, and the changes made to them, over time. You can use the following free clients to checkout the code.

For an exhaustive list of the Subversion clients, you can check this page on Wikipedia.

The code is hosted by google and can be browsed here. It lists the trunk (the default branch) and its folder. If you prefer, you can also access to the list of changes.

Source checkout

The URL to use in the SVN client to download the latest source code for the trunk is the following: This URL gives you a read-only access to the source code. Only the members can commit into the source code.

Submitting Patch

If you add a functionality, fix a bug, add some documentation or correct it (or ...) and want to share it with the community, you can create a patch and send it to the mailing list. To create a patch, few rules must be respected to be able to apply this patch easily.

Note: For TortoiseSVN user, check this help to create patch.

Bug reports

For bug reports and feature requests, please use the issue tracker. It gives you a list of the opened issues. Check the closed issues (Select "All issues" instead of "Open issues" and click on search) before submitting a new one.

Mailing list

For the moment, it exists one mailing list where users and developers can write to each other. If necessary this mailing list could be splitted to separate user and developer discussions.

Check the mailing list BTK Users to subscribe or access to the archives