KF-GINS: a readable EKF GNSS/INS implementation for learning the filter

What the software actually implements

KF-GINS is an EKF-based GNSS/INS integrated navigation system. It implements the classical integrated navigation solution combining GNSS positioning results with IMU data, and the architecture is a loosely coupled integration built on the extended Kalman filter in its error state vector form.

The feature list names the components: IMU error compensation, the inertial navigation solution, the Kalman filter, and error feedback. The error state vector has 21 dimensions, covering position errors, velocity errors, attitude errors, IMU bias errors, and IMU scale factor errors. Attitude errors use the Phi-angle model, and the velocity and position errors are defined in the navigation frame rather than the body frame.

The inertial navigation solution itself uses a two-sample mechanization algorithm based on a linear assumption, and it compensates for the second-order coning correction as well as rotational motion and sculling motion. Those three terms are the part that matters for anyone reading the code, because they are the corrections that separate a mechanisation that drifts quickly from one that holds accuracy over a minute or two of inertial-only navigation.

The project is written in C++ with CMake managing the build, and it is GPL-3.0 licensed. It comes from the Integrated and Intelligent Navigation group at the GNSS Research Center of Wuhan University, and it is described as a supporting resource for the course Inertial Navigation Principles and GNSS/INS Integrated Navigation by Prof. Xiaoji Niu and Dr. Qijin Chen. The last push to the repository was on 2026-06-10, and there are no GitHub releases, so the repository itself is the release channel.

Building on Linux and running the demo dataset

The build is managed by CMake and compiles on Linux, macOS, and Windows, with Linux recommended. Three dependency libraries are required, Eigen3, abseil-cpp, and yaml-cpp, and the project appends them as third party libraries in the ThirdParty directory, so you do not have to install them separately.

The recommended Linux environment is the g++ compiler of Ubuntu 18.04 or Ubuntu 20.04, and the build tools are installed with:

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

After that, the whole sequence from clone to running the demo dataset is:

# 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

Two details in that block matter. The configuration file is a required runtime argument, not an optional one, and the same file is needed to debug the program. And the demo dataset lives in the dataset/ directory, with the shipped configuration at dataset/kf-gins.yaml, so the first thing you can do with a working build is run a known input and read the output.

The dataset/ and config/ directories at the top level, along with the scripts/ directory, are where the input data and the run configuration live, and docs/ holds the documentation.

Windows and macOS build paths

On Windows the recommended tool is MSVC inside VSCode, and the documentation is specific about the setup. You install the MSVC compiler and VSCode with the C/C++, C/C++ Extension Pack, CMake, and CMake Tools plug-ins, then open the KF-GINS folder and drive the build from the Command Palette. The steps are: CMake: Select Kit to choose the MSVC compiler, CMake: Select Variant to pick Release, CMake: Configure, and then CMake: Build to compile the project.

Running the test dataset then uses the executable from a PowerShell or CMD terminal in the project directory:

.\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

That comment about the binary possibly landing in the .\bin\Release directory is a genuine gotcha rather than a formality, since the MSVC multi-configuration generator puts it there while the single configuration Linux build puts it directly in bin.

For macOS the tools are xcode-select and cmake, installed with:

xcode-select --install
brew install cmake

After that the build sequence is identical to the Linux one, down to the same cmake invocation with the Release build type and the same make -j8, and the same run command with ./bin/KF-GINS ./dataset/kf-gins.yaml.

For debugging under Linux the documentation asks for GDB, installed with sudo apt-get install gdb, and the repository carries a .vscode/ directory with the launch configuration for that.

The academic framing, and the citation it asks for

This is a research software release, and the project handles that explicitly.

The README asks that if you use the software for academic research, you give an acknowledgment in a specific form and cite the related document and papers, which are collected in ref.bib. The English wording is that the authors would like to acknowledge the team of Prof. Xiaoji Niu of the Integrated and Intelligent Navigation group from the GNSS Research Center of Wuhan University for providing the open-source KF-GINS software that was used in the paper, with a Chinese version of the same sentence provided alongside.

The primary citation is a journal paper: KF-GINS: an open-sourced software for GNSS/INS integrated navigation, by Niu, Wang, Chen, Tang, Zhang, and Zhang, published in GPS Solutions, volume 29, number 4, page 202, in October 2025, with a DOI of 10.1007/s10291-025-01967-w. The reference list behind it is the standard navigation literature, from the textbooks on strapdown inertial navigation and integrated navigation principles through Groves on multi-sensor integration and Shin's thesis on estimation techniques for low-cost inertial navigation.

The relationship to the 2014 Survey Review paper by Niu and colleagues on GNSS/INS data processing software for position and orientation systems is worth noting, since it is the earlier generation of the same group's work and the closest thing to a predecessor.

For support there is an email address for technical problems, and a QQ group for Chinese users, where joining requires providing an organisation and a name.

Why a course reference is a different kind of artefact

The point of a project like this is not that it outperforms a production navigation stack. It is that you can read the whole pipeline in one sitting.

A commercial inertial navigation system gives you a pose and hides the filter. A research implementation gives you a pose and shows you the error feedback correction, the state transition, the measurement update, and the mechanisation, with the structure following the textbook. For a student building intuition about why a 21 state vector is 21 states, that is worth more than a better answer.

There is a second benefit, which is the ability to check the implementation against an independent description. The reference list includes the 2014 software paper and the textbooks, so a reader can compare the code against the published formulation rather than taking it on trust. The two-sample mechanisation and the coning and sculling compensation are all named in the feature list, which means you can look for each one in the source.

The limitation follows from the same design. A reference implementation optimised for reading is not optimised for speed, and it does not advertise a real-time guarantee, a sensor driver, a configuration for real hardware, or an accuracy specification. The demo dataset is the entry point, and it is a dataset rather than a live sensor stream.

The other constraint is the version environment. The recommended compiler is g++ from Ubuntu 18.04 or 20.04, which is a deliberately conservative baseline for a codebase that has to build the same way in a teaching lab as in a research lab.

Against a commercial INS, and against writing the filter yourself

The realistic alternative for a project that needs navigation is a commercial inertial navigation system or an open source one such as the SLAM-based and INS-based toolkits that already exist. The difference in approach is that those deliver a working pose, and this delivers a working filter that you can read and modify. If the goal is a navigation output for a vehicle or a drone, a commercial unit with a documented accuracy figure and a support contract is the better answer, and reading KF-GINS will not change that.

The second alternative is to implement the filter yourself from the textbooks, and that is the real competition here, because a reader of this repository is almost certainly going to write the filter at some point. The difference is that a from-scratch implementation starts with the state vector and the error definitions as choices, and choosing them is where most of the difficulty lies. KF-GINS has already made those choices and names them, the 21 state error vector, the Phi-angle attitude error model, the navigation frame for position and velocity errors, and the two-sample mechanisation. Reading a decided implementation is a different pedagogical experience from making the decisions.

A third option is the other direction, using a well-known open source implementation that focuses on the interface rather than the derivation. That gives you a working system with less theory in it, which is the right trade if you need the system rather than the understanding.

The trade for a course reference is the narrowness. Loose coupling, a 21 state error vector, and one inertial mechanisation are the scope here. A project needing tight coupling, a full state error formulation with position in the earth or ECEF frame, or an alternative mechanisation would have to extend the code rather than configure it.

Editorial conclusion

Adopt KF-GINS if you are teaching or studying GNSS/INS integration and want a filter whose state vector and error feedback you can read, since the code is a course reference rather than a production navigation stack. Do not adopt it as a flight-ready inertial navigation system, because the project presents it as an open-sourced implementation for academic use. Verify first that your IMU data convention and frame match the one the configuration file expects before trusting any output.

Frequently asked questions

Official sources

1. i2Nav-WHU/KF-GINS on GitHub
2. Issues
3. License: GPL-3.0
4. README