Merge pull request #34 from tmcg0/dev

Target bioslam 1.1
tmcg0 · Dec 3, 2023 · 78afe06 · 78afe06
2 parents 816c449 + 3f7af0b
commit 78afe06
Show file tree

Hide file tree

Showing 28 changed files with 785 additions and 200 deletions.
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
@@ -0,0 +1,72 @@
+# --------------------------------------------------------------------------- #
+#      bioslam (latest) development Dockerfile for Ubuntu 20.04 base image          
+# with dependencies:
+#   boost: 1.71.0 (https://packages.ubuntu.com/focal/libboost1.71-all-dev)
+#   TBB: 2020.1 (https://packages.ubuntu.com/focal/libtbb-dev)
+#   HDF5 (serial): 1.10.4 (https://packages.ubuntu.com/focal/libhdf5-dev)
+#   Eigen: 3.3.9 (https://gitlab.com/libeigen/eigen)
+#   GTSAM: 4.0.3 (https://github.com/borglab/gtsam/releases/4.0.3)
+#   HighFive: 2.8.0 (https://github.com/BlueBrain/HighFive/releases/v2.8.0)
+# build environment:
+#   git: 2.25.1 (https://packages.ubuntu.com/focal/git)
+#   cmake: 3.16.3 (https://packages.ubuntu.com/focal/cmake)
+#   g++: 9.3.0 (from build-essential: https://packages.ubuntu.com/focal/build-essential)
+#   make: 4.2.1 (from build-essential: https://packages.ubuntu.com/focal/build-essential)
+# notes:
+# - only builds the C++ library and executables, no Python/MATLAB wrappers
+# - internet connection required to download dependencies
+# --------------------------------------------------------------------------- #
+
+FROM ubuntu:20.04
+
+LABEL maintainer="Tim McGrath <[email protected]>"
+
+ARG N_JOBS=4
+
+ENV DEBIAN_FRONTEND noninteractive
+
+# install package dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    ca-certificates \
+    build-essential \
+    git \
+    cmake \
+    libhdf5-dev \
+    libboost1.71-all-dev \
+    libtbb-dev \
+    && apt-get clean
+
+# install Eigen
+WORKDIR /usr/src/
+RUN git clone --single-branch --branch 3.3.9 https://gitlab.com/libeigen/eigen eigen3
+WORKDIR /usr/src/eigen3/build/
+RUN cmake ..
+RUN make install -j${N_JOBS}
+
+# Install GTSAM
+WORKDIR /usr/src/
+RUN git clone --depth 1 --branch 4.0.3 https://github.com/borglab/gtsam.git
+WORKDIR /usr/src/gtsam/build
+RUN cmake \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DGTSAM_WITH_EIGEN_MKL=OFF \
+    -DGTSAM_BUILD_EXAMPLES_ALWAYS=OFF \
+    -DGTSAM_BUILD_TIMING_ALWAYS=OFF \
+    -DGTSAM_BUILD_TESTS=OFF \
+    -DGTSAM_BUILD_UNSTABLE=OFF \
+    -DGTSAM_UNSTABLE_BUILD_PYTHON=OFF \
+    ..
+RUN make install -j${N_JOBS} && make clean
+
+# add /usr/local/lib to LD_LIBRARY_PATH for dynamic linking
+# note: this doesn't seem to save the .bashrc file, which isn't sourced anyway when running the container
+#   if not working inside container, run export LD_LIBRARY_PATH=/usr/local/lib:LD_LIBRARY_PATH in the shell
+RUN echo 'export LD_LIBRARY_PATH=/usr/local/lib:LD_LIBRARY_PATH' >> /root/.bashrc
+
+# install HighFive v2.8.0
+WORKDIR /usr/src/
+RUN git clone --depth 1 --branch v2.8.0 https://github.com/BlueBrain/HighFive
+WORKDIR /usr/src/HighFive/build/
+RUN cmake ..
+RUN make install -j${N_JOBS}
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -0,0 +1,33 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.191.1/containers/ubuntu
+{
+	"name": "bioslam-dev-container",
+	"build": {
+		"dockerfile": "Dockerfile",
+	},
+
+	// Set *default* container specific settings.json values on container create.
+	"settings": {},
+
+	// Add the IDs of extensions you want installed when the container is created.
+	"extensions": [
+		"ms-vscode.cpptools",
+		"GitHub.copilot",
+		"jeff-hykin.better-cpp-syntax",
+		"ms-vscode.cpptools-themes",
+		"ms-vscode.cpptools-extension-pack",
+		"twxs.cmake"
+	],
+
+	// add mounts for data access
+	"mounts":[]
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "uname -a",
+
+	// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	//"remoteUser": "vscode"
+}
diff --git a/.github/workflows/build-test-linux.yml b/.github/workflows/build-test-linux.yml
@@ -28,16 +28,22 @@ jobs:
             os: ubuntu-20.04
             compiler: gcc
             version: "7"
+            gtsam-version: "4.0.3"
+            highfive-version: "v2.8.0"
 
           - name: ubuntu-20.04-gcc-9
             os: ubuntu-20.04
             compiler: gcc
             version: "9"
+            gtsam-version: "4.0.3"
+            highfive-version: "v2.8.0"
 
           - name: ubuntu-20.04-clang-9
             os: ubuntu-20.04
             compiler: clang
             version: "9"
+            gtsam-version: "4.0.3"
+            highfive-version: "v2.8.0"
 
     steps:
       - name: Checkout
@@ -100,34 +106,25 @@ jobs:
           ./bootstrap.sh --with-libraries=serialization,filesystem,thread,system,atomic,date_time,timer,chrono,program_options,regex
           sudo ./b2 -j$(nproc) install
 
-      - name: Install GTSAM 4.0.3
+      - name: Install GTSAM ${{ matrix.gtsam-version }}
         run: |
           cd ${{runner.workspace}} # cd to runner home
-          git clone --depth 1 --branch 4.0.3 https://github.com/borglab/gtsam.git gtsam # clone latest from dev branch. switch to GTSAM 4.1 once it's tagged.
+          git clone --depth 1 --branch ${{ matrix.gtsam-version }} https://github.com/borglab/gtsam.git gtsam
           cd gtsam && mkdir build && cd build # move into build dir for gtsam
-          cmake -DCMAKE_BUILD_TYPE=Release -DGTSAM_WITH_EIGEN_MKL=OFF -DGTSAM_BUILD_EXAMPLES_ALWAYS=OFF -DGTSAM_BUILD_TIMING_ALWAYS=OFF -DGTSAM_BUILD_TESTS=OFF -DGTSAM_BUILD_UNSTABLE=ON ..
+          cmake -DCMAKE_BUILD_TYPE=Release -DGTSAM_WITH_EIGEN_MKL=OFF -DGTSAM_BUILD_EXAMPLES_ALWAYS=OFF -DGTSAM_BUILD_TIMING_ALWAYS=OFF -DGTSAM_BUILD_TESTS=OFF -DGTSAM_BUILD_UNSTABLE=OFF -DGTSAM_UNSTABLE_BUILD_PYTHON=OFF ..
           sudo make -j$(nproc) install
 
       - name: Install hdf5
         run: sudo apt-get -y install libhdf5-serial-dev
 
-      - name: Install HighFive v2.3.1
+      - name: Install HighFive ${{ matrix.highfive-version }}
         run: |
           cd ${{runner.workspace}} # cd to runner home
-          git clone https://github.com/BlueBrain/HighFive HighFive && cd HighFive # clone HighFive
-          git checkout a01ee6be4d4a75aeeb9fd962c3b415ea8cd395f6 # checkout v2.3.1 release
-          mkdir build && cd build # move into build dir for HighFive
+          git clone --depth 1 --branch ${{ matrix.highfive-version }} https://github.com/BlueBrain/HighFive HighFive
+          cd HighFive && mkdir build && cd build # move into build dir for HighFive
           cmake -DHIGHFIVE_USE_BOOST=OFF ..
           sudo make -j$(nproc) install
 
-      - name: Install imuDataUtils
-        run: |
-          cd ${{runner.workspace}} # cd to runner home
-          git clone --depth 1 --branch master https://github.com/tmcg0/imuDataUtils imuDataUtils # clone imuDataUtils
-          cd imuDataUtils && mkdir build && cd build # move into build dir for imuDataUtils
-          cmake ..
-          sudo make -j$(nproc) install
-
       - name: Install LCov
         if: matrix.name == 'ubuntu-20.04-gcc-9' && matrix.build_type == 'Debug'
         run: sudo apt-get update -q && sudo apt-get install lcov -q -y
@@ -140,7 +137,9 @@ jobs:
           sudo make -j$(nproc) install
 
       - name: Test bioslam
-        run: make -j$(nproc) test
+        run: |
+          cd ${{github.workspace}}/build
+          make -j$(nproc) test
 
       - name: Run LCov
         if: matrix.name == 'ubuntu-20.04-gcc-9' && matrix.build_type == 'Debug'

diff --git a/.github/workflows/dockerfile-build.yml b/.github/workflows/dockerfile-build.yml
@@ -13,8 +13,8 @@ jobs:
 
     - name: Build and run docker image
       run: |
-        docker build -t bioslam -f ./docker/ubu-20.Dockerfile ./docker
+        docker build -t bioslam -f ./docker/bioslam1.0.1-gtsam4.0.3-ubu20.Dockerfile ./docker
         docker run -id --name bioslam bioslam
 
     - name: Run tests
-      run: docker exec -i bioslam make test
+      run: docker exec -i bioslam bash -c "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib && cd /usr/src/bioslam/build && make test"
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.5)
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 # Set the version number for the library
 set (BIOSLAM_VERSION_MAJOR 1)
-set (BIOSLAM_VERSION_MINOR 0)
+set (BIOSLAM_VERSION_MINOR 1)
 set (BIOSLAM_VERSION_PATCH 0)
 math (EXPR BIOSLAM_VERSION_NUMERIC "10000 * ${BIOSLAM_VERSION_MAJOR} + 100 * ${BIOSLAM_VERSION_MINOR} + ${BIOSLAM_VERSION_PATCH}")
 set (BIOSLAM_VERSION_STRING "${BIOSLAM_VERSION_MAJOR}.${BIOSLAM_VERSION_MINOR}.${BIOSLAM_VERSION_PATCH}")
@@ -123,10 +123,6 @@ include_directories(${HDF5_INCLUDE_DIR})
 list(APPEND BIOSLAMLIBS ${HDF5_LIBRARIES})
 # --- required HighFive --- #
 find_package(HighFive REQUIRED)
-# --- find and include imuDataUtils library --- #
-find_package(ImuDataUtils REQUIRED)
-include_directories(${IMUDATAUTILS_INCLUDE_DIR})
-list(APPEND BIOSLAMLIBS ${IMUDATAUTILS_LIBRARIES})
 # --- Require GTSAM ---
 find_package(GTSAM REQUIRED)
 if (GTSAM_FOUND)
@@ -141,13 +137,11 @@ endif(GTSAM_FOUND)
 message(STATUS "proj source dir is ${PROJECT_SOURCE_DIR}")
 include_directories("${PROJECT_SOURCE_DIR}/include") # bioslam headers
 include_directories("${PROJECT_SOURCE_DIR}/include/factors") # bioslam headers for factors
-#file(GLOB SOURCES_BIOSLAM "${PROJECT_SOURCE_DIR}/src/*.cpp" "${PROJECT_SOURCE_DIR}/src/factors/*.cpp" "${PROJECT_SOURCE_DIR}/include/*.h" "${PROJECT_SOURCE_DIR}/include/factors/*.h" "imuDataUtils/include/*.h" "imuDataUtils/src/*.cpp" "wrap/example/*.h" "wrap/example/*.cpp")
+include_directories("${PROJECT_SOURCE_DIR}/include/imu") # bioslam headers for imu
 # --- add sources --- #
-# glob all stuff from imuDataUtils
-# glob headers. do I need to do this? doesn't help. what's the prob?
-file(GLOB SOURCES_BIOSLAM" ${PROJECT_SOURCE_DIR}/include/*.h" "${PROJECT_SOURCE_DIR}/include/factors/*.h")
+file(GLOB SOURCES_BIOSLAM "${PROJECT_SOURCE_DIR}/include/*.h" "${PROJECT_SOURCE_DIR}/include/factors/*.h" "${PROJECT_SOURCE_DIR}/include/imu/*.h")
 # base stuff
-list(APPEND SOURCES_BIOSLAM ${PROJECT_SOURCE_DIR}/src/lowerBodyPoseEstimator.cpp ${PROJECT_SOURCE_DIR}/src/imuPoseEstimator.cpp ${PROJECT_SOURCE_DIR}/src/imuNoiseModelHandler.cpp ${PROJECT_SOURCE_DIR}/src/VarStrToCharMap.cpp)
+list(APPEND SOURCES_BIOSLAM ${PROJECT_SOURCE_DIR}/src/lowerBodyPoseEstimator.cpp ${PROJECT_SOURCE_DIR}/src/imuPoseEstimator.cpp ${PROJECT_SOURCE_DIR}/src/imu/imuNoiseModelHandler.cpp ${PROJECT_SOURCE_DIR}/src/imu/imu.cpp ${PROJECT_SOURCE_DIR}/src/VarStrToCharMap.cpp)
 # add utilities
 list(APPEND SOURCES_BIOSLAM ${PROJECT_SOURCE_DIR}/src/gtsamutils.cpp ${PROJECT_SOURCE_DIR}/src/mathutils.cpp ${PROJECT_SOURCE_DIR}/src/testutils.cpp ${PROJECT_SOURCE_DIR}/src/bioutils.cpp)
 # add custom factors

diff --git a/README.md b/README.md
@@ -31,13 +31,13 @@ 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]](https://www.mdpi.com/1424-8220/18/6/1882)
 
-The optimization backend ([GTSAM 4.0+](https://github.com/borglab/gtsam)) and IMU dynamics/preintegration is based on:
+The optimization backend ([GTSAM](https://github.com/borglab/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]](https://ieeexplore.ieee.org/abstract/document/6907483)
 
 - 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]](http://www.roboticsproceedings.org/rss11/p06.pdf)
 
-# Installation
+## Installation
 
 ### Supported systems
 Bioslam is tested on the following systems:
@@ -46,46 +46,62 @@ Bioslam is tested on the following systems:
 
 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](docker/Dockerfile).
+On other systems, a bioslam-installed Ubuntu image can be spun up in a Docker container using a provided [Dockerfile](docker/).
 
-## Required Dependencies
-
-* CMake (>= 3.17, _working through older versions now. Can confirm 3.10.2 doesn't work_)
-* boost (>= 1.65)
+### Required Dependencies
+#### _bioslam < v1.1_
+* CMake (>= 3.17)
+* boost (>= 1.65 && <1.74)
   * Ubuntu: `sudo apt-get install libboost-all-dev`
-* [Eigen](http://eigen.tuxfamily.org/index.php?title=Main_Page)
-  * `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`
+* [Eigen](http://eigen.tuxfamily.org/index.php?title=Main_Page) 3.3.9+
 * hdf5
   * Ubuntu: `sudo apt-get install libhdf5-serial-dev`
-* [gtsam 4.0.3](https://github.com/borglab/gtsam) (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](https://github.com/tmcg0/bioslam/issues/4).)
-  * `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`
+* [gtsam 4.0.3](https://github.com/borglab/gtsam) (note: bioslam MATLAB wrapper may have a [known compatibility issue](https://github.com/tmcg0/bioslam/issues/4).)
 * [imuDataUtils](https://github.com/tmcg0/imuDataUtils)
-* [HighFive](https://github.com/BlueBrain/HighFive) HDF5 wrapper
-* Intel's Thread Building Blocks (TBB)
+* [HighFive](https://github.com/BlueBrain/HighFive) >= 2.3 && < 2.8
+* Optional: Intel's Thread Building Blocks (TBB)
   * ubuntu: `sudo apt install libtbb-dev`
 
-## Installation Instructions
+ #### bioslam >= v1.1
+* CMake (>= 3.17)
+* boost (???)
+  * Ubuntu: `sudo apt-get install libboost-all-dev`
+* [Eigen](http://eigen.tuxfamily.org/index.php?title=Main_Page) 3.3.9+
+* hdf5
+  * Ubuntu: `sudo apt-get install libhdf5-dev`
+* [gtsam 4.2](https://github.com/borglab/gtsam) (note: bioslam MATLAB wrapper may have a [known compatibility issue](https://github.com/tmcg0/bioslam/issues/4).)
+* [HighFive](https://github.com/BlueBrain/HighFive) >= ??? (2.3.1 doesn't work, 2.8 does)
+* Notes:
+  * bioslam 1.1 [removes the dependency on the imuDataUtils library](https://github.com/tmcg0/bioslam/issues/31)
+  * Intel's TBB (optional dependency) has shown compatibility issues when installing via Ubuntu's package manager in 22.04+
+
+### Optional Recommended Dependencies
+for faster performance
+
+* [Intel MKL](https://software.intel.com/en-us/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:
 ```sh
 mkdir build
 cd build
 cmake ..
-make install (may require root privileges)
-make test (optional, runs unit tests)
+make install # may require root privileges
+make test # optional, runs unit tests
 ```
 
 ## Testing
 ```
-make test (remember to `make install` first!)
+make test # remember to `make install` first!
 ```
 
 Want more verbose output (including `std::cout`) while testing?
@@ -95,32 +111,22 @@ Want more verbose output (including `std::cout`) while testing?
 CTEST_OUTPUT_ON_FAILURE=1 make test
 ```
 
-## Optional Recommended Dependencies
-for faster performance
+## Development
 
-* 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.
+A convenient [devcontainer configuration](/.devcontainer) is provided for use with VSCode's [Dev Containers extension](https://code.visualstudio.com/docs/devcontainers/containers).
 
-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
+## Bioslam MATLAB interface
+In the `matlab/` directory there is an implementation of bioslam for MATLAB. This feature is experimental and prone to instability.
 
-# Bioslam MATLAB interface
-In the `matlab/` directory there is an implementation of bioslam for MATLAB. 
-
-## Building bioslam for MATLAB
+### 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
+#### Required MATLAB Toolboxes
 - 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*
-
 ### 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](https://www.mathworks.com/matlabcentral/answers/364543-why-does-matlab-r2017b-display-erroneous-message-about-libgiolibproxy-so-on-ubuntu-17-10)
     * You can add the standard location for MATLAB with `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/lib/x86_64-linux-gnu/` in .bashrc