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-basic

• 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-base

  • 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

• 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: CMake langage support for Visual Studio Code
• Doxygen Documentation Generator: Automatic Doxygen generation by typing /// + [Enter]
• Todo Tree: Show TODO, FIXME, etc. comment tags in a tree view
• Code Spell Checker: Spelling checker for source code
• Log File Highlighter: Adds color highlighting to log files to make it easier to follow the flow of log events and identify problems.
• Clang-Tidy Integrates clang-tidy into VS Code
• cmake-format Format listfiles so they don't look like crap
• mathover Render LaTeX comments on hover
• Status Bar Parameter Add selectable parameter to the status bar
• matched-line-dimmer Visually dim lines that match regex patterns.

Settings

Recommended changes to the User's settings.json (not the project .vscode/settings.json) in case you plan to contribute to the project.

"editor.formatOnType": true,
"doxdocgen.generic.authorEmail": "your.name@ins.uni-stuttgart.de",
"doxdocgen.generic.authorName": "Y. Name",

Recommended changes to the User's keybindings.json

[
    {
        "key": "f6",
        "command": "workbench.action.tasks.build",
        "when": "!inDebugMode"
    },
    {
        "key": "f8",
        "command": "-editor.action.marker.nextInFiles",
        "when": "editorFocus && !editorReadonly"
    },
    {
        "key": "f8",
        "command": "workbench.action.tasks.runTask"
    },
    {
        "key": "f7",
        "command": "workbench.action.tasks.test"
    }
]

Dependencies

• Needed:
  • cmake A cross-platform open-source make system
  • C++ compiler (clang or gcc is recommended, but others work as well) for compiling the project
• Optional:
  • Conan A distributed, open source, C/C++ package manager
  • clang-format Code formatting Tool
  • ccache Compiler cache that speeds up recompilation by caching previous compilations
  • valgrind CPU profiling & leak detection
  • kcachegrind Visualization of Performance Profiling Data
  • doxygen Documentation system for C++, C, Java, IDL and PHP
  • clang-tidy Clang-based C++ "linter" tool
• Libraries (Install yourself and change cmake link targets or let them automatically be installed by Conan):
  • spdlog Fast C++ logging library
  • fmt A modern formatting library
  • Boost Free peer-reviewed portable C++ source libraries
  • Eigen C++ template library for linear algebra: matrices, vectors, numerical solvers, and related algorithms
  • Catch2 Modern, C++-native, header-only, test framework for unit-tests, TDD and BDD
  • nlohmann_json JSON for Modern C++ parser and generator
  • unordered_dense A fast & densely stored hashmap and hashset
  • muparser Fast math parser library for C/C++
  • libssh Fulitplatform C library implementing the SSHv2 and SSHv1 protocol
  • gcem GCE-Math (Generalized Constant Expression Math) is a templated C++ library enabling compile-time computation of mathematical functions.
  • vnproglib VectorNav programming library
  • Navio2 Collection of drivers and examples for Navio 2 - autopilot shield for Raspberry Pi.
• GUI (optional):
  • Dear ImGui Bloat-free Immediate Mode Graphical User interface for C++ with minimal dependencies
  • Node Editor in ImGui An implementation of node editor with ImGui-like API.
  • ImPlot An immediate mode, GPU accelerated plotting library for Dear ImGui.
  • ImGuiFileDialog A file selection dialog built for (and using only) Dear ImGui.

Authors

• Thomas Topp, M.Sc.
• Marcel Maier, M.Sc.
• Prof. Dr. Thomas Hobiger
• Rui Wang, M.Sc.

License

This project is licensed under the MPL 2.0 License - see the LICENSE file for details.

If this license does not suit your needs, feel free to contact us for further details.