riann 0.2.0

A Neural Network for attitude estimation using IMU data

RIANN (Robust IMU-based Attitude Neural Network)

RIANN is the official implementation of the model proposed in:

Weber, D.; Gühmann, C.; Seel, T. RIANN—A Robust Neural Network Outperforms Attitude Estimation Filters. AI 2021, 2(3), 444–463. https://doi.org/10.3390/ai2030028

If you use RIANN in your research, please cite the paper.

What is RIANN?

RIANN is a lightweight neural network implementation for estimating orientation (attitude) from inertial measurement unit (IMU) data. It processes accelerometer and gyroscope readings to provide quaternion-based attitude estimation, optimized for real-time applications.

Key Features

• Fast and accurate quaternion-based attitude estimation
• Optimized for real-time processing with state preservation
• Supports both batch processing and step-by-step integration
• Robust against sensor noise and motion artifacts
• Simple Python API with minimal dependencies

Installation

pip install riann

or from source

git clone https://github.com/daniel-om-weber/riann.git
cd riann
pip install -e .

Quickstart

import numpy as np
from riann.riann import RIANN

# Initialize RIANN
riann = RIANN()

# Prepare IMU data
acc = np.ones((100, 3))  # Accelerometer data (100 samples, XYZ axes)
gyr = np.zeros((100, 3)) # Gyroscope data (100 samples, XYZ axes)
fs = 200                 # Sampling rate in Hz

# Get attitude quaternions (w,x,y,z)
attitude = riann.predict(acc, gyr, fs)
print(f"Output shape: {attitude.shape}")  # (100, 4) - 100 unit quaternions

Output shape: (100, 4)

Input and output conventions

RIANN takes accelerometer and gyroscope readings from a single IMU and returns unit quaternions.

Field	Shape	Units	Notes
acc	(N, 3) (or (3,) for predict_step)	m/s²	Accelerometer, axis order x, y, z
gyr	(N, 3) (or (3,) for predict_step)	rad/s	Gyroscope, axis order x, y, z
fs	scalar	Hz	Sampling rate of the data
output	(N, 4) (or (4,))	—	Unit quaternion (w, x, y, z)

• acc and gyr must be expressed in the same sensor-fixed coordinate frame and the same axis order.
• The gyroscope is in radians per second (not deg/s); the accelerometer measures specific force in m/s², so a sensor at rest reads ≈ 9.81 along the up-axis (e.g. [0, 0, 9.81]).
• Data should be (approximately) uniformly sampled at fs.
• The output quaternion describes the orientation of the IMU relative to a fixed inertial frame whose vertical axis is aligned with gravity. Because no magnetometer is used, absolute heading (yaw) is not observable and may drift slowly; roll and pitch (inclination) are estimated robustly.

If your data is in different units or axis conventions (e.g. gyro in deg/s, or accelerometer in g), convert it before calling RIANN.

Citation

If you use RIANN in academic work, please cite:

Weber, D.; Gühmann, C.; Seel, T. RIANN—A Robust Neural Network Outperforms Attitude Estimation Filters. AI 2021, 2, 444–463. https://doi.org/10.3390/ai2030028

@article{weber2021riann,
  title   = {{RIANN}---A Robust Neural Network Outperforms Attitude Estimation Filters},
  author  = {Weber, Daniel and G{\"u}hmann, Clemens and Seel, Thomas},
  journal = {AI},
  volume  = {2},
  number  = {3},
  pages   = {444--463},
  year    = {2021},
  publisher = {MDPI},
  doi     = {10.3390/ai2030028},
  url     = {https://www.mdpi.com/2673-2688/2/3/28}
}