vqf.offlineVQF

vqf.offlineVQF(ndarray gyr, ndarray acc, ndarray mag, Ts, params=None)

A Versatile Quaternion-based Filter for IMU Orientation Estimation.

This function implements the offline variant of orientation estimation filter described in the following publication:

D. Laidig and T. Seel. “VQF: Highly Accurate IMU Orientation Estimation with Bias Estimation and Magnetic Disturbance Rejection.” Information Fusion 2023, 91, 187–204. doi:10.1016/j.inffus.2022.10.014. [Accepted manuscript available at arXiv:2203.17024.]

The filter can perform simultaneous 6D (magnetometer-free) and 9D (gyr+acc+mag) sensor fusion and can also be used without magnetometer data. It performs rest detection, gyroscope bias estimation during rest and motion, and magnetic disturbance detection and rejection.

To use this offline implementation, all data must have the same sampling rate and be provided as a contiguous numpy array.

This function is a Python wrapper (implemented in Cython) for the C++ implementation of the offline variant offlineVQF(). The offline variant makes use of the fact that the whole data is available and performs acausal signal processing, i.e. future samples are used to calculate the current estimate. Depending on use case and programming language of choice, the following alternatives might be useful:

Full Version

Basic Version

Offline Version

C++

VQF

BasicVQF

offlineVQF()

Python/C++ (fast)

vqf.VQF

vqf.BasicVQF

vqf.offlineVQF (this function)

Pure Python (slow)

vqf.PyVQF

–

–

Pure Matlab (slow)

VQF.m

–

–

The output is a dictionary containing

  • quat6D – the 6D quaternion – numpy array with shape (N, 4)

  • bias – gyroscope bias estimate in rad/s – numpy array with shape (N, 3)

  • biasSigma – uncertainty of gyroscope bias estimate in rad/s – numpy array with shape (N,)

  • restDetected – rest detection state – boolean numpy array with shape (N,)

in all cases and if magnetometer data is provided additionally

  • quat9D – the 9D quaternion – numpy array with shape (N, 4)

  • delta – heading difference angle between 6D and 9D quaternion in rad – numpy array with shape (N,)

  • magDistDetected – magnetic disturbance detection state – boolean numpy array with shape (N,)

Parameters:

  • gyr – gyroscope measurement in rad/s – numpy array with shape (N, 3)

  • acc – accelerometer measurement in m/s² – numpy array with shape (N, 3)

  • mag – magnetometer measurement in arbitrary units – numpy array with shape (N, 3) or None

  • Ts – sampling time in seconds

  • params – parameters (pass {} or None to use the default parameters and see VQFParams for a full list and detailed descriptions)

Returns:

dict with entries as described above