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

Working with the Repository

Git (either clone or update)

Clone the repository

git clone --recurse-submodules <URL> INSTINCT
cd INSTINCT
git lfs install
git lfs pull

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

export CC=clang && export CXX=clang++
cmake -Bbuild/Release -S. -DCMAKE_BUILD_TYPE=Release -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

cmake -Bbuild/Release -S. -DCMAKE_BUILD_TYPE=Release -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

cmake -Bbuild/Release -S. -DCMAKE_BUILD_TYPE=Release -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 (=config/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/
                                        critical/off
  --file-log-level arg (=debug)         Log level to the log file (possible
                                        values: trace/debug/info/warning/error/
                                        critical/off

Development Environment Setup

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

ArchLinux

# Needed
sudo pacman -S base-devel git-lfs cmake clang glfw-x11
trizen -S conan # AUR package

# Documentation
sudo apt install -y doxygen pdf2svg texlive-most ghostscript

# Optional
sudo pacman -S ccache cppcheck

# Profiling (optional)
sudo pacman -S valgrind kcachegrind

Ubuntu 22.04

# Needed
sudo apt update
sudo apt upgrade -y
sudo apt install -y build-essential git-lfs clang clang-tidy cmake python3-pip libglfw3-dev libglfw3
pip3 install conan --user

# Documentation (Ubuntu 22.04 has too old doxygen version)
sudo apt install -y pdf2svg texlive texlive-lang-german texlive-latex-extra ghostscript
sudo apt install -y flex bison graphviz mscgen dia # Build dependencies
wget -c https://www.doxygen.nl/files/doxygen-1.9.5.src.tar.gz -O - | tar -xz
mkdir doxygen-1.9.5/build && cd doxygen-1.9.5/build
cmake -G "Unix Makefiles" .. && make && sudo make install

# Optional
sudo apt install ccache cppcheck

# Profiling (optional)
sudo apt install valgrind kcachegrind

MacOS

# Basic
xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew update

# Needed
brew install git-lfs 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 pdf2svg
# Also latex is needed to compile the formulas

# Optional
brew install ccache cppcheck

Windows 11

For development Windows Subsystem for Linux is recommended. Follow the Ubuntu instructions
For executing, INSTINCT can be compiled with MSVC

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
- cppcheck A tool for static C/C++ code analysis
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.
- 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

Version History

v1.0.0: Public Release

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.

zhihangQ/INSTINCT