Metadata-Version: 2.4
Name: riann
Version: 0.2.0
Summary: A Neural Network for attitude estimation using IMU data
Project-URL: Homepage, https://github.com/daniel-om-weber/riann
Project-URL: Documentation, https://daniel-om-weber.github.io/riann/
Project-URL: Repository, https://github.com/daniel-om-weber/riann
Author-email: Daniel Oliver Martin Weber <daniel.om.weber@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: AHRS,Attitude,IMU,Neural Network
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: onnxruntime
Description-Content-Type: text/markdown

# RIANN (Robust IMU-based Attitude Neural Network)

<p>

<a href="https://pypi.org/project/riann/"><img src="https://img.shields.io/pypi/v/riann.svg" alt="PyPI version"></a>
<a href="https://pypi.org/project/riann/"><img src="https://img.shields.io/pypi/pyversions/riann.svg" alt="Python versions"></a>
<a href="https://github.com/daniel-om-weber/riann/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
<a href="https://daniel-om-weber.github.io/riann/"><img src="https://img.shields.io/badge/docs-online-blue.svg" alt="Docs"></a>
<a href="https://doi.org/10.3390/ai2030028"><img src="https://img.shields.io/badge/DOI-10.3390%2Fai2030028-blue.svg" alt="DOI"></a>
</p>

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](#citation).

## 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

``` bash
pip install riann
```

or from source

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

## Quickstart

``` python
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

``` bibtex
@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}
}
```
