Supported compiler

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

MacOS X 10.3 / GCC 3.3 (PPC 32 bits)
MacOS X 10.5 / GCC 4.0 (Intel 32/64 bits)
MacOS X 10.6 / GCC 4.2 (Intel 64 bits)
Ubuntu 9.04 "Jaunty" / GCC 4.3 (Intel 32 bits)
Ubuntu 10.04 "Lucid Lynx" / GCC 4.4 (Intel 64bits)
Ubuntu 10.10 "Maverick Meerkat" / GCC 4.5 (Intel 64 bits)
Windows XP SP3 / MSVC 2008 (Intel 32 bits)
Windows XP SP3 / MSVC 2010 (Intel 32 bits)
Windows Vista SP1 / MSVC 2010 (Intel 32 bits)
Windows 7 / Windows SDK 3.5 SP1 (Intel 64 bits)

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:

Add the files in the folder Code/BasicFilters
Edit the CMakeLists.txt in the folder Code/BasicFilters

Add in the CMake variable BTKBasicFilters_SRCS, the name of the CPP file.

# Part of the file  Code/BasicFilters/CMakeLists.txt
SET(BTKBasicFilters_SRCS
     btkAcquisitionUnitConverter.cpp
     btkEventDectector.cpp # <-- New line added. Your class will be
compiled and integrated in the module BTKBasicFilters
     btkForcePlatformsExtractor.cpp
     btkForcePlatformWrenchFilter.cpp
     btkMergeAcquisitionFilter.cpp
     btkSeparateKnownVirtualMarkersFilter.cpp
     btkSpecializedPointsExtractor.cpp
     btkGroundReactionWrenchFilter.cpp
 )

ADD_LIBRARY(BTKBasicFilters ${BTK_LIBS_BUILD_TYPE} ${BTKBasicFilters_SRCS})

TARGET_LINK_LIBRARIES(BTKBasicFilters BTKCommon)
# ...

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: http://www.google.com/search?q=Test+Driven+Development

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.

CXXTEST_SUITE(C3DFileReaderTest)
{
  CXXTEST_TEST(NoFile)
  {
    btk::AcquisitionFileReader::Pointer reader = btk::AcquisitionFileReader::New();
    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
CXXTEST_SUITE_REGISTRATION(C3DFileReaderTest)
CXXTEST_TEST_REGISTRATION(C3DFileReaderTest, NoFile)

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:

_TDD.cpp contains the main function where the test runner is executed ;
_TDDBasicFilters.cpp contains the tests for the module BasicFilters ;
_TDDCommon.cpp contains the tests for the module Common ;
_TDDConfigure.h.in contains the required header to use CxxTest and the definition of the IO paths ;
_TDDIO.cpp contains the tests for the module IO ;
*.h All the tests.

Programming style

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

Coding style

All the functions/classes embedded in BTK are in the namespace btk.
The file extension used for the C++ header is .h
The file extension used for the C++ source is .cpp
Indentation with 2 spaces, no tabs ;
The comparison use the right-hand comparison (as modern compiler, at least GCC, can detect the use of the assignment operation instead of the equal operator ==) ;
Use explicitly parentheses into conditional statement or other logical expression
Private function/class finishes by the suffix _p ;
Use explicit names rather than short names ;
Use the Allman style to indent the code ;
Comments have to be written in english as it is the language that nearly all programmers in all countries can read.

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:

BTKCommon
BTKIO
BTKBasicFilters
BTKVTK

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:

List of authors (Authors1, initial(s) ; Authors2, initial(s) ; ...)
Title in italic (The name or the article.)
Name of the journal, Number (Issue), date, pages.

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:

Reference: 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.

TortoiseSVN (Windows only)
KDESvn (Linux only)
SmartSVN (Win/Mac/Linux)
XCode (MacOS X only)

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: http://b-tk.googlecode.com/svn/BTK/trunk. 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.

Update your working directory to be sure to create patch against the last revision. If it is not the case, it can create one or more conflicts in the code and finally gives errors during the compilation or worster, crash the final application.
Create a patch from the top of the sources (the root) or at least indicate from which folder you create the patch.

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

Table of contents