INSTINCT - INS Toolkit for Integrated Navigation Concepts and Training

Flow-Based Navigation Software of the Institut of Navigation (INS) of the University of Stuttgart, Germany.

Description

INSTINCT is a PNT software which implements a manifold of PNT algorithms (e.g. multi-sensor data fusion) while following the Flow-Based Programming paradigm. It can operate in real-time, interfacing to different sensors, or it can be used in post-processing mode for which data are read from files or generated from the software's own simulation tools.

The GUI provides a dataflow editor which can be used to connect Nodes (modules encapsuling functionality) and create custom-tailored applications. For performance, every Node runs in an own thread, providing parallelism out of the box.

If no GUI is required, the application can be run in --nogui mode and a .flow file can be loaded.

Getting Started

Read the documentation

Read the docs on https://unistuttgart-ins.github.io/INSTINCT/

Working with the Repository

Git (either clone or update)

• Clone the repository

  git clone --recurse-submodules <URL> INSTINCT
  cd INSTINCT
  

• Update the repository

  git pull --recurse-submodules
  # If there where changes in the submodules
  git submodule deinit -f .    # completely "unbinds" all submodules
  git submodule update --init  # makes a fresh checkout of them
  

Build & run the main program

conan install . --build=missing -s build_type=Release -s compiler.cppstd=17
# Windows needs the argument -DCMAKE_TOOLCHAIN_FILE="build/generators/conan_toolchain.cmake"
cmake -Bbuild/Release -S. -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="build/Release/generators/conan_toolchain.cmake" -DENABLE_MAIN=ON -DENABLE_TESTING=OFF -DENABLE_DOXYGEN=OFF -DENABLE_CLANG_TIDY=OFF -DENABLE_CPPCHECK=OFF -DLOG_LEVEL=INFO
cmake --build build/Release --parallel8
./build/bin/Release/instinct

Build & run the tests

conan install . --build=missing -s build_type=Release -s compiler.cppstd=17
# Windows needs the argument -DCMAKE_TOOLCHAIN_FILE="build/generators/conan_toolchain.cmake"
cmake -Bbuild/Release -S. -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="build/Release/generators/conan_toolchain.cmake" -DENABLE_MAIN=OFF -DENABLE_TESTING=ON -DENABLE_DOXYGEN=OFF -DENABLE_CLANG_TIDY=OFF -DENABLE_CPPCHECK=OFF -DLOG_LEVEL=TRACE
cmake --build build/Release --parallel8
cd build/Release
ctest --output-on-failure

Build the documentation

conan install . --build=missing -s build_type=Release -s compiler.cppstd=17
# Windows needs the argument -DCMAKE_TOOLCHAIN_FILE="build/generators/conan_toolchain.cmake"
cmake -Bbuild/Release -S. -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="build/Release/generators/conan_toolchain.cmake" -DENABLE_MAIN=OFF -DENABLE_TESTING=OFF -DENABLE_DOXYGEN=ON -DLOG_LEVEL=OFF -DENABLE_CLANG_TIDY=OFF -DENABLE_CPPCHECK=OFF -DENABLE_INCLUDE_WHAT_YOU_USE=OFF -DDOC_CHECK_CODE_DOCUMENTATION=NO
cmake --build build/Release --target doc

The doxygen main page can then be opened under build/doc/html/index.html (an online documentation is available on GitHub pages)

Help message

INSTINCT - INS Toolkit for Integrated Navigation Concepts and Training

Allowed options:
  --config arg                       List of configuration files to read
                                     parameters from
  -v [ --version ]                   Display the version number
  -h [ --help ]                      Display this help message
  --sigterm                          Programm waits for -SIGUSR1 / -SIGINT /
                                     -SIGTERM
  --duration arg (=0)                Program execution duration [sec]
  --nogui                            Launch without the gui
  --noinit                           Do not initialize flows after loading them
  -l [ --load ] arg                  Flow file to load
  --rotate-output                    Create new folders for output files
  -o [ --output-path ] arg (=logs)   Directory path for logs and output files
  -i [ --input-path ] arg (=data)    Directory path for searching input files
  -f [ --flow-path ] arg (=flow)     Directory path for searching flow files
  --implot-config arg (=implot.json) Config file to read implot settings from
  --console-log-level arg (=off)     Log level on the console  (possible
                                     values: trace/debug/info/warning/error/cri
                                     tical/off
  --file-log-level arg (=debug)      Log level to the log file (possible
                                     values: trace/debug/info/warning/error/cri
                                     tical/off
  --log-filter arg                   Filter for log messages

Development Environment Setup

Most library dependencies are managed by Conan.io, so you just need to install the basics.

ArchLinux

• Building

  sudo pacman -S --noconfirm --needed base-devel cmake clang glfw-x11
  yay -S --noconfirm --needed conan # AUR package
  conan profile detect --force
  

• Documentation

  sudo pacman -S --noconfirm --needed doxygen texlive-most pdf2svg ghostscript
  

• Optional
  • Compiler cache

    sudo pacman -S --noconfirm --needed ccache
    

  • Profiling

    sudo pacman -S --noconfirm --needed valgrind kcachegrind
    

Ubuntu 24.04

• Building

  sudo apt update
  sudo apt upgrade -y
  sudo apt install -y build-essential clang clang-format cmake pipx libglfw3-dev libglfw3
  pipx ensurepath
  # Path will be updated after reboot
  pipx install conan
  conan profile detect --force
  

• Documentation
  • TexLive for citations

    sudo apt install -y texlive texlive-lang-german texlive-latex-extra ghostscript pdf2svg
    

  • Ubuntu has too old doxygen version

    sudo apt install -y flex bison graphviz mscgen dia # Build dependencies
    wget -c https://www.doxygen.nl/files/doxygen-1.12.0.src.tar.gz -O - | tar -xz
    cd doxygen-1.12.0 && mkdir build && cd build
    cmake -G "Unix Makefiles" .. && make && sudo make install
    

• Optional
  • Static analyzer (Ubuntu 24.04 comes with clang-tidy-18, but version 19 is needed)

    sudo apt install -y clang-tidy-19
    ln -s /usr/bin/clang-tidy-19 ~/.local/bin/clang-tidy
    # Make sure that '~/.local/bin' is in your path in front of '/usr/bin'
    # Otherwise you need to link it in the system
    # sudo ln -s /usr/bin/clang-tidy-19 /usr/bin/clang-tidy
    

  • Compiler cache

    sudo apt install ccache
    

  • Profiling

    sudo apt install valgrind kcachegrind
    

MacOS

• Building

  xcode-select --install
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
  
  # Install brew first
  brew update
  brew install cmake llvm conan glfw
  ln -s "$(brew --prefix llvm)/bin/clang-format" "/usr/local/bin/clang-format"
  ln -s "$(brew --prefix llvm)/bin/clang-tidy" "/usr/local/bin/clang-tidy"
  

• Documentation

  brew install doxygen texlive pdf2svg
  

• Optional
  • Compiler cache

    brew install ccache
    

Windows 11

• For development Linux is recommended. You can try Windows Subsystem for Linux WSL.
  • Follow the VS Code WSL instructions
  • We recommend using Ubuntu inside WSL and following the Ubuntu instructions above.
• For executing, INSTINCT can be compiled with MSVC directly on Windows
  • Use the Build Tools for Visual Studio 2022 (download)
    • Install both the C++ Toolchain and Cmake through the Build Tools
  • Install the conan package manager (download)
  • Use the Developer Powershell to invoke commands and also to start VS Code
  • Windows specifies the build type at compile time, not during cmake generation. Therefore the toolchain file has a different path. See above

VSCode Configuration

Task overview

| Hotkey | Action | Default | | :------: | :------------------------------------------- | ------------- | | F5 | Debug the project | Default debug | | F6 | Run Task: DOXYGEN: Build Documentation | Default build | | F7 | Run Task: MAIN: Build & run project | Default test | | F8 | Open Task List | |

• To start the GUI, execute the Task MAIN: Build & run project
• If you have problems with the build, execute the Task CLEAN: Remove build files
• If you want to provide tests, place them in the tests directory and execute them with the task TEST: Build & run

Extensions

It is strongly recommended to use Visual Studio Code as IDE, as the needed project files are provided in the .vscode folder.

Recommended plugins for working with this project

• C/C++: C/C++ IntelliSense, debugging, and code browsing.
• [CMake](https://marketplace.visualstudio.co