BTK is an open-source library for biomechanical analysis. The structure of this library is inspired by the VTK and ITK projects.
This README is written for BTK version 0.1 and greater. For more information about BTK and additional resources see the web page at http://code.google.com/p/b-tk.
BTK use the generous open-source New BSD license. Yes, you can use BTK in commercial products. The complete text of the copyright follows.
/* * The Biomechanical ToolKit * Copyright (c) 2009-2013, Arnaud Barré * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * * Redistributions of source code must retain the above * copyright notice, this list of conditions and the following * disclaimer. * * Redistributions in binary form must reproduce the above * copyright notice, this list of conditions and the following * disclaimer in the documentation and/or other materials * provided with the distribution. * * Neither the name(s) of the copyright holders nor the names * of its contributors may be used to endorse or promote products * derived from this software without specific prior written * permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */
The BTK source code repository is organized into six major sections.
The BTK source code is commented and permits to construct the API documentation by using Doxygen. For more information to construct the API documentation, see the option BUILD_DOCUMENTATION_API in Configuration Options in CMake.
The Biomechanical ToolKit (BTK) was tested on 32-bit and 64-bit architectures under Windows (Windows XP, Windows Vista, Windows 7) with Microsoft Visual C++ Express (2008 and 2010), Mac OS X (Panther, Leopard, Snow Leopard) with XCode (1.5, 3.1 and 3.2.5 respectively) and Linux (Ubuntu 9.10, 10.04 and 10.10) with GCC (4.3, 4.4 and 4.5 respectively). The compilation process only requires the use of a terminal/command prompt. BTK use CMake 2.6.2 or greater to generate its build system, so it is necessary to download it from http://www.cmake.org/HTML/Download.html. The instructions below cover the basics of running CMake for BTK under the assumption that CMake is already installed. See the CMake web page for details on installing and running CMake.
Compiling BTK requires a complete BTK source tree. Running BTK regression tests (see option BUILD_TESTING in Configuration Options in CMake) requires for the first an internet connection to download data files from ftp://ftp.c3d.org.
CMake must be run to generate a build system for BTK. The build system may be placed either in the BTK source tree (an in-source build) or in a separate binary tree (an out-of-source build). The use of out-of-source builds is strongly encouraged because they make it easy to have multiple builds with different configurations sharing the same source tree. Once a single in-source build has been created it is the only build tree that can be associated with that source tree. A source tree may not be used both for an in-source build and an out-of-source build, but any number of out-of-source builds may share a source tree that does not have an in-source build. Having multiple out-of-source builds is particularly useful for installing BTK on multiple architectures using a single source tree on a shared disk.
CMake provides both a command-line tool and interactive interfaces. Advanced users may wish to use the command-line tool but here only the CMake interactive interface is documented.
make in the command prompt to compile the code. BTK is a toolkit providing a wide variety of functionality. Several configuration options are available to customize the BTK build system. These options are configured through an interactive CMake interface as described Building with CMake above. Note that not all options are available on all platforms, and some options are available only when other options are set to a particular value.
The interactive CMake interface provides brief documentation for every option. Some options have more meaning than can be described in one sentence, so additional documentation is provided here:
Add compiler flags in debug mode to be more verbose when the compiler find some warnings (available only for GCC).
Path containing the input data for the unit tests. Download BTKData-x.y.z.zip (where x.y.z corresponds to your version of BTK), unzip it (for example in the folder Testing), and set this variable to the installation path. You can also use the folder BTKData hosted on the git server. The script must find the folder "Input" otherwise most of the unit tests will fail.
Enable/Disable generation of BTK bindings in the Matlab language. In order to build the Matlab-based BTK interpreter, the target computer needs to have Matlab 7.0.4 or above installed. To turn on Matlab wrapping, set BTK_WRAP_MATLAB to ON during the configuration process.
This option is activated if BTK_WRAP_MATLAB was activated during the previous CMake configuration iteration. BTK_WRAP_MATLAB_REDISTRIBUTABLE_MEX_FILES is useful for target machines without the same compiler environment. This option forces the build system to be in Release mode with generation of static BTK libraries. BTK_WRAP_MATLAB_REDISTRIBUTABLE_MEX_FILES is not compatible with BUILD_SHARED_LIBS.
Enable/Disable generation of BTK bindings in the Octave language. In order to build the Octave-based BTK interpreter, the target computer needs to have Octave 3.2.4 or above installed. To turn on Octave wrapping, set BTK_WRAP_OCTAVE to ON during the configuration process.
Enable/Disable generation of BTK bindings in the Python language. In order to build the Pyton-based BTK interpreter, the target computer needs to have Python 2.5 or above installed, as well as SWIG 2.0 or above.
The BTK documentation is generated by Doxygen. The option BUILD_DOCUMENTATION activates by default the sub-option BUILD_DOCUMENTATION_API. You have to select the other option manually if you want to build their documentation.
This option generates the API documentation and can be found in "Documentation/API" from the the build directory. This documentation is in a HTML format. The main file is the file Readme.html.
This option forces to build the full API documentation.
Active the building of examples in the folder Examples.
Sets whether the compiled BTK libraries will be shared libraries or static libraries. When linking executables against static libraries the needed symbols will be copied from the libraries into the executables enabling them to run without access to the original libraries. When linking executables against shared libraries references to the symbols are placed into the executables. This has the advantage that many executables can share a large library without producing many copies of its code.
Shared libraries have the disadvantage that they must be found at runtime in order for an executable to run. Each operating system supporting shared libraries has a component known as the dynamic loader. This component is responsible for finding the shared libraries needed by an executable when it is run. In order to run BTK executables from the build tree when using shared libraries one may need to help the dynamic loader find the libraries (usually the bin subdirectory of the build tree).
On Windows, the dynamic loader will look for shared libraries in the directory containing the executable, in directories listed in the PATH environment variable, and in some system directories. Since BTK places all of its executables and libraries in the same directory nothing needs to be set to get them to run. However, when one builds outside projects against BTK the PATH environment variable must be set to point at the directory containing the BTK shared libraries.
On UNIX-style platforms, the dynamic loader will use an environment variable such as LD_LIBRARY_PATH (Linux and many UNIX systems) or DYLD_LIBRARY_PATH (Mac OS X) to look for shared libraries. In order to run BTK executables from the build tree one must set the appropriate environment variable to point at the directory containing the BTK shared libraries. The same environment setting must be used for running outside projects build against the shared BTK libraries.
Each BTK class has unit tests and/or regression tests to verify their functionnalities. All the tests are in the directory Testing/Code. All the required input data should be inserted in the Testing/Data/Input directory and the generated ouput data should be inserted in the Testing/Data/Output. These tests use a modified version of CxxTest embedded in the directory Utilities. This version suppress the Perl/Python dependencies and replace them by C macros. As with the regular CxxTest library, the tests are declared and implemented in a header file. A test class requires to be defined by macro CXXTEST_SUITE. All the class' methods used for tests purpose must be defined by CXXTEST_TEST. Finally, the class must be registred by using CXXTEST_SUITE_REGISTRATION and tests by CXXTEST_TEST_REGISTRATION. The header containing the suite of tests has to be included in the CXX file calling the runner.
This option updates this file (Readme.html) by using the content of the file /Documentation/Readme/Readme.dox.in from the source directory. Modify Readme.dox.in, compile the project and you'll find a new Readme.html file in the root of sources.
Utility used to generate the Java file "EasyInstallWithRedistributableMatlabToolbox.jar" in the root of this project. The activation of this option requires Java SDK not JRE.
Installing BTK from a source distribution requires first that it be compiled in a build tree. See the Compilation Compilation section above for details. Once BTK has been compiled in a build tree one may build the install target to actually put BTK in an installation tree. If BTK was built using a CMake Makefile generator then this is done by running "nmake install" or "make install" from the top of the build tree. If BTK was built using a CMake project file generator (such as Visual Studio), then building the INSTALL project from inside the IDE will install BTK. The installation process will install all files in a directory structure rooted at the directory specified by CMAKE_INSTALL_PREFIX.
nmake install to install BTK. By default CMAKE_INSTALL_PREFIX is set to "c:\Program Files\BTK")sudo make install to install BTK. the command sudo is required if your user login is not in the admin group. By default CMAKE_INSTALL_PREFIX is set to "/usr/local") For the Matlab Wrapping (see BTK_WRAP_MATLAB), a directory is generated containing the compiled MEX-Files and some copied M-Files. These M-Files contain the description of the MEX-Functions and their options. As with regular Matlab functions, use the help or doc functionname to read the function's description. You can also use the command help btk or doc btk to visualize the complete btk toolbox help.
In Matlab, the BTK project can be seen as a toolbox. You have only to add in the Matlab Path (File > Set Path...), the root of the btk toolbox. The btk toolbox path is for example "CMAKE_INSTALL_PREFIX/share/btk-0.1/Wrapping/Matlab/btk".
Regression tests in BTK required C3D files. These files are on the net to reduce the size of the BTK source package. The first time you want to build the tests (BUILD_TESTING option in CMake), CMake will download the required files from ftp://ftp.c3d.org. This download take a long time due to a check betwen EPSV and PASV mode... This problen is due to the CMake binary option build and cannot be fixed by a script.
Many tests/examples in Testing directory will be compiled if BUILD_TESTING are enable in CMake. To run these tests, just type CTest (or "c:\Program Files\CMake 2.6\bin\ctest.exe") or bin/TDD from the build directory. If you have built shared libraries, make sure the PATH environment variable (Windows) or the LD_LIBRARY_PATH (Unix) point to the shared libraries (see above documentation of the BUILD_SHARED_LIBS for details)
There are several ways to extend BTK. The simplest way is, in your own code,to create classes that inherit from the appropriate BTK classes. For example a filter/process will inherits from btk::Process until an input/output will inherit from btk::DataObject.
For general information go to the BTK web site http://code.google.com/p/b-tk
If you run into problems, your best bet is to join the BTK mailing list. Visit http://groups.google.com/group/btk-users to join the list.