Home

Awesome

KF-GINS

[中]   [EN]

An EKF-Based GNSS/INS Integrated Navigation System

Introduction

We open-source KF-GINS1, an EKF-based GNSS/INS integrated navigation system. KF-GINS implements the classical integrated navigation solution of GNSS positioning results and IMU data. The KF-GINS follows the course content of "Inertial Navigation Principles and GNSS/INS Integrated Navigation" by Prof. Xiaoji Niu and Dr. Qijin Chen, as a supporting resource for the cource. The software is developed in C++ programming language, and CMake is used to manage the project.

The main features of KF-GINS are as follows:

Origanization: Integrated and Intelligent Navigation (i2Nav) Group, GNSS Research Center, Wuhan University.

Related Reference:

If you use this software for your academic research, please give acknowledgment as follows and cite our related document and papers

English version: “The authors would like to acknowledge the team of Prof. Xiaoji Niu of the Integrated and Intelligent Navigation (i2Nav) group from GNSS Research Center of Wuhan University for providing the open-source KF-GINS software that was used in the paper.”
中文模板：“本文作者感谢武汉大学卫星导航定位技术研究中心多源智能导航实验室(i2Nav)牛小骥教授团队开源的KF-GINS软件平台。”

Contacts:

1 Program Compilation and Execution

1.1 Compilation environment

KF-GINS is managed by CMake and can be compiled on all of Linux, MacOS and Windows. We recommend you choose Linux environment first.

The configuration file is used as a parameter to run KF-GINS after successfully compiling it. To debug the program, it is also required to add the configuration file as a parameter.

1.2 Dependency libraries

KF-GINS requires another three libraries, which are Eigen3, abseil-cpp, and yaml-cpp. We have appended them as the thirdparty libraries in the ThirdParty directory.

1.3 Compile under Linux

We recommend you use g++ compiler of Ubuntu18.04 or Ubuntu20.04 to compile KF-GINS. You should install the build-essential libraries following the commonds:

sudo apt-get install cmake
sudo apt-get install build-essential

After preparing your own compilation environment, you can clone the repository locally and compile KF-GINS as follows:

# Clone the repository
git clone https://github.com/i2Nav-WHU/KF-GINS.git ~/

# Build KF-GINS
cd ~/KF-GINS
mkdir build && cd build

cmake ../ -DCMAKE_BUILD_TYPE=Release 
make -j8

# Run demo dataset
cd ~/KF-GINS
./bin/KF-GINS ./dataset/kf-gins.yaml

# Wait until the program finish

1.4 Compile under Windows

The MSVC(Microsoft Visual C/C++) compiler is generally used in Windows. We recommend you to compile KF-GINS in the VSCode software.

You should first install the MSVC compiler and VScode software (including the necessary plug-ins, such as C/C++, C/C++ Extension Pack, CMake, and CMake Tools).

After preparing your own compilation environment, you can clone the repository locally and open the KF-GINS folder in VSCode:

Open a PowerShell or CMD terminal in the project directory and run the test dataset:

.\bin\KF-GINS.exe .\dataset\kf-gins.yaml
# The executable file may be generated in the '.\bin\Release' directory. Then the command is:
# .\bin\Release\KF-GINS.exe .\dataset\kf-gins.yaml

1.5 Compile under MacOS

xcode-select and cmake in MacOS. You should install these tools following the commonds:

xcode-select --install
brew install cmake

After preparing your own compilation environment, you can clone the repository locally and compile KF-GINS as follows:

# Clone the repository
git clone https://github.com/i2Nav-WHU/KF-GINS.git ~/

# Build KF-GINS
cd ~/KF-GINS
mkdir build && cd build

cmake ../ -DCMAKE_BUILD_TYPE=Release 
make -j8

# Run demo dataset
cd ~/KF-GINS
./bin/KF-GINS ./dataset/kf-gins.yaml

# Wait until the program finish

1.6 Debug by VSCode

GDB debugging tool is required to debug KF-GINS under Linux. You should install it following the command.

sudo apt-get install gdb

The debug operation is as follows:

2 Use KF-GINS

2.1 Prerequisite Knowledge

Frame defination:

Navigation state:

IMU noise model:

For more details on the algorithm, please refer to 惯性导航原理与GNSS/INS组合导航课程讲义.

2.2 Data format

ColumnsData descriptionUnits
1GNSS seconds of week$s$
2~4X-Y-Z axes incremental angles$rad$
5~7X-Y-Z axes incremental velocity$m/s$
ColumnsData descriptionUnits
1GNSS seconds of week$s$
2latitude$deg$
3longitude$deg$
4ellipsoid altitude$m$
5~7position STD (north-east-down)$m$
ColumnsData descriptionUnits
1GNSS week-
2GNSS seconds of week$s$
3latitude$deg$
4longitude$deg$
5ellipsoid altitude$m$
6~83-D velocity (north-east-down)$m/s$
9~11attitude angles (roll-pitch-yaw)$deg$
ColumnsData descriptionUnits
1GNSS seconds of week$s$
2~4X-Y-Z axes gyroscope biases$deg/h$
5~7X-Y-Z axes accelerometer biases$mGal$
8~10X-Y-Z axes gyroscope scale factors$ppm$
11~13X-Y-Z axes accelerometer scale factors$ppm$
ColumnsData descriptionUnits
1GNSS seconds of week$s$
2~43-D position STD (north-east-down)$m$
5~73-D velocity STD (north-east-down)$m/s$
8~103-D attitude STD (roll-pitch-yaw)$deg$
11~13X-Y-Z axes gyroscope bias STD$deg/h$
14~16X-Y-Z axes accelerometer bias STD$mGal$
17~19X-Y-Z axes gyroscope scale factor STD$ppm$
20~22X-Y-Z axes accelerometer scale factor STD$ppm$

2.3 Initial align

KF-GINS only supports initial alignment given all initial states currently. The initial states need to be set in the configuration file (kf-gins.yaml) before executing the program.

3 Datasets

3.1 Demo dataset

We offer a demo dataset with the configuration file, which is located in the dataset directory.

3.2 awesome-gins-datasets

Users can find our open-sourced datasets at awesome-gins-datasets.

3.3 Your own dataset

The data formats used in KF-GINS are the same as the formats defined at awesome-gins-datasets. You can follow the formats to prepare your own datasets.

4 License

The source code is released under GPLv3 license.

We are still working on improving the code reliability. For any technical issues, please contact Liqiang Wang (wlq@whu.edu.cn) or Hailiang Tang (thl@whu.edu.cn), or open an issue at this repository. For commercial usage, please contact Prof. Xiaoji Niu (xjniu@whu.edu.cn).

Footnotes

  1. We also open-sourced OB_GINS, an optimization-based GNSS/INS integrated navigation system. ↩