Repository files navigation

Bioslam is a C++/MATLAB toolbox for estimation of human skeletal pose from IMU data, using robust factor-graph based global optimization techniques.

If using this software repository, please cite bioslam through the following Zenodo DOI:

If using bioslam, also please cite the following publication:

• T. McGrath and L. Stirling, “Body-Worn IMU Human Skeletal Pose Estimation Using a Factor Graph-Based Optimization Framework,”Sensors, vol. 20, no. 23, p. 6887, Dec. 2020.[link]

• T. McGrath and L. Stirling, “Body-Worn IMU-Based Human Hip and Knee Kinematics Estimation during Treadmill Walking,”Sensors, vol. 22, no. 7, p. 2544, Mar. 2022.[link]

The novel hinge joint kinematic model is based on:

• T. McGrath, R. Fineman, and L. Stirling, “An Auto-Calibrating Knee Flexion-Extension Axis Estimator Using Principal Component Analysis with Inertial Sensors,”Sensors, vol. 18, no. 6, p. 1882, Jun. 2018.[link]

The optimization backend (GTSAM) and IMU dynamics/preintegration is based on:

• L. Carlone, Z. Kira, C. Beall, V. Indelman, and F. Dellaert, “Eliminating conditionally independent sets in factor graphs: A unifying perspective based on smart factors,” inProceedings - IEEE International Conference on Robotics and Automation, 2014.[link]

• C. Forster, L. Carlone, F. Dellaert, and D. Scaramuzza, “IMU preintegration on manifold for efficient visual-inertial maximum-a-posteriori estimation,” inRobotics: Science and Systems, 2015.[link]

Bioslam is tested on the following systems:

• Ubuntu 20.04 with GCC 7, GCC 9, and Clang 9

using Boost 1.67, GTSAM 4.0.3, and Eigen 3.3.9.

On other systems, a bioslam-installed Ubuntu image can be spun up in a Docker container using a providedDockerfile.

• CMake (>= 3.17)
• boost (>= 1.65 && <1.74)
  • Ubuntu:sudo apt-get install libboost-all-dev
• Eigen 3.3.9+
• hdf5
  • Ubuntu:sudo apt-get install libhdf5-serial-dev
• gtsam 4.0.3 (note: bioslam MATLAB wrapper may have aknown compatibility issue.)
• imuDataUtils
• HighFive >= 2.3 && < 2.8
• Optional: Intel's Thread Building Blocks (TBB)
  • ubuntu:sudo apt install libtbb-dev

similar to < v1.1, but:

• no need forimuDataUtils

similar to v1.1, but:

• boost >= 1.74
• gtsam 4.2
• HighFive >= 2.7

for faster performance

• Intel MKL can offer situationally-dependent performane improvements
• NOTE: MKL is not compatible with Eigen 3.3.4 because of a bug in Eigen. Use a newer version of Eigen.

Note: if any of these three optional dependencies are installed, you must change a corresponding GTSAM flag to use them:

• GTSAM_WITH_EIGEN_MKL=ON Tells Eigen to use Intel MKL if available
• GTSAM_WITH_TBB=ON Tells GTSAM to use Intel TBB if available
• setMKL_FFTW_INCLUDE_DIR,MKL_INCLUDE_DIR,MKL_ROOT_DIR if you wanna use MKL
• setTBB_INCLUDE_DIRS,TBB_tbb_LIBRARY_RELEASE,TBB_tbbmalloc_LIBRARY_RELEASE if you wanna use TBB

Starting from the root of the repo:

mkdir buildcd buildcmake ..make install# may require root privilegesmaketest# optional, runs unit tests

make test # remember to `make install` first!

Want more verbose output (includingstd::cout) while testing?

# from build/CTEST_OUTPUT_ON_FAILURE=1 maketest

A convenientdevcontainer configuration is provided for use with VSCode'sDev Containers extension.

In thematlab/ directory there is an implementation of bioslam for MATLAB. This feature is experimental and prone to instability.

Set the appropriate CMake option in bioslam's CMakelists.txt to build the MATLAB wrapper. Then in thebuild/ folder (or wherever you build bioslam) there will be a directory calledwrap/. The contents of this directory will include a directorywrap/bioslam/+bioslam. The+bioslam/ directory must be added to your MATLAB path. Additionally, so does the filewrap/bioslam_mex/bioslam_wrapper.mexa64. These will be installed if youmake install.

• Bioinformatics Toolbox
• Deep Learning Toolbox
• Robotics System Toolbox
• Mapping Toolbox

• Depending on your system and MATLAB configuration, the version oflibstdc++ may be different between MATLAB and your system. This can cause errors. In these cases, it might be easiest to just remove the version oflibstdc++ that shipped with MATLAB, forcing MATLAB to find it on your system instead. Note: this requires it be properly added to your system environment paths (below).Related question/answer on MATLAB central
  • You can add the standard location for MATLAB withexport LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/lib/x86_64-linux-gnu/ in .bashrc
• You will need to set your system environment variables forLD_RUN_PATH andLD_LIBRARY_PATH for MATLAB to find the built libraries for GTSAM and bioslam. Add the following lines to your .bashrc:
  • export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/
  • export LD_RUN_PATH=$LD_RUN_PATH:/usr/local/lib/
• In general, if-march=native is enabled for any libraries, subsequent libraries should pass the same build flag. Make sure that the build optionBIOSLAM_BUILD_WITH_MARCH_NATIVE matches the GTSAM build optionGTSAM_BUILD_WITH_MARCH_NATIVE.

bioslam is open sourced under the MIT license. SeeLICENSE for details.