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 4.0+) 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]
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 the provided Dockerfile.
- CMake (>= 3.17, working through older versions now. Can confirm 3.10.2 doesn't work)
- boost (>= 1.65)
- Ubuntu:
sudo apt-get install libboost-all-dev
- Ubuntu:
- Eigen
git clone https://github.com/eigenteam/eigen-git-mirror
sudo ln -s path/to/eigen-git-mirror/Eigen /usr/local/include
- note: most software expects Eigen's include directories at
/usr/include/eigen3
- hdf5
- Ubuntu:
sudo apt-get install libhdf5-serial-dev
- Ubuntu:
- gtsam 4.0.3 (note: bioslam C++ impementation needs exactly GTSAM 4.0.3. MATLAB wrapper needs GTSAM 4.1+. I'm working to fix this known compatibility issue.)
git clone https://github.com/borglab/gtsam
cd path/to/gtsam/repo
(move to root of gtsam repo)mkdir build
cd build
cmake ..
make check
(optional, runs unit tests)make install
- imuDataUtils
- HighFive HDF5 wrapper
- Intel's Thread Building Blocks (TBB)
- ubuntu:
sudo apt install libtbb-dev
- ubuntu:
Starting from the root of the repo:
mkdir build
cd build
cmake ..
make install (may require root privileges)
make test (optional, runs unit tests)
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
for faster performance
- Intel MKL (download from https://software.intel.com/en-us/mkl)
- 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 availableGTSAM_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
In the matlab/
directory there is an implementation of 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
.
- Bioinformatics Toolbox
- Deep Learning Toolbox
- Robotics System Toolbox
- Mapping Toolbox
In the future, we'll try to make some updates to remove dependency on these expensive toolboxes
- 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 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 with
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/lib/x86_64-linux-gnu/
in .bashrc
- You can add the standard location for MATLAB with
- You will need to set your system environment variables for
LD_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. See LICENSE for details.