Bioslam: IMU-Based Human Skeletal Pose Estimation

What is Bioslam?

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

Citing Bioslam

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

Core publications

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]

Related publications

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,” in Proceedings - 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,” in Robotics: Science and Systems, 2015. [link]

Installation

Supported systems

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 provided Dockerfile.

Required Dependencies

bioslam < v1.1

• 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 a known compatibility issue.)
• imuDataUtils
• HighFive >= 2.3 && < 2.8
• Optional: Intel's Thread Building Blocks (TBB)
  • ubuntu: sudo apt install libtbb-dev

bioslam >= v1.1 && <1.2

similar to < v1.1, but:

• no need for imuDataUtils

bioslam >= 1.2

similar to v1.1, but:

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

Optional Recommended Dependencies

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
• set MKL_FFTW_INCLUDE_DIR, MKL_INCLUDE_DIR, MKL_ROOT_DIR if you wanna use MKL
• set TBB_INCLUDE_DIRS, TBB_tbb_LIBRARY_RELEASE, TBB_tbbmalloc_LIBRARY_RELEASE if you wanna use TBB

Installation Instructions

Installing library via CMake

Starting from the root of the repo:

mkdir build
cd build
cmake ..
make install # may require root privileges
make test # optional, runs unit tests

Testing

make test # remember to `make install` first!

Want more verbose output (including std::cout) while testing?

# from build/
CTEST_OUTPUT_ON_FAILURE=1 make test

Development

A convenient devcontainer configuration is provided for use with VSCode's Dev Containers extension.

Bioslam MATLAB interface

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

Building bioslam for MATLAB

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

Required MATLAB Toolboxes

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

Notes

• Depending on your system and MATLAB configuration, the version of libstdc++ may be different between MATLAB and your system. This can cause errors. In these cases, it might be easiest to just remove the version of libstdc++ 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 with export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/lib/x86_64-linux-gnu/ in .bashrc
• You will need to set your system environment variables for LD_RUN_PATH and LD_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 option BIOSLAM_BUILD_WITH_MARCH_NATIVE matches the GTSAM build option GTSAM_BUILD_WITH_MARCH_NATIVE.

Additional Information

bioslam is open sourced under the MIT license. See LICENSE for details.