AHRS: Attitude and Heading Reference Systems

New release 0.4 is out!

AHRS is a collection of functions and algorithms in pure Python used to estimate the orientation of mobile systems.

Orginally, an AHRS is a set of orthogonal sensors providing attitude information about an aircraft. This field has now expanded to smaller devices, like wearables, automated transportation and all kinds of systems in motion.

This package's focus is fast prototyping, education, testing and modularity. Performance is NOT the main goal. For optimized implementations there are endless resources in C/C++ or Fortran.

AHRS is compatible with Python 3.9 and newer.

Installation

The most recommended method is to install AHRS directly from this repository to get the latest version:

git clone https://github.com/Mayitzin/ahrs.git
cd ahrs
python -m pip install .

Or using pip for the stable releases:

pip install ahrs

AHRS depends merely on NumPy. More packages are avoided, to reduce its third-party dependency.

Versioning

In order to update the version, use hatch and adjust it automatically

hatch version <major, minor, patch>

Novelties in 0.4

(Click on each topic to see more details.)

<details> <summary>New Attitude Estimators</summary> <li><b><a href="https://ahrs.readthedocs.io/en/latest/filters/ukf.html">Unscented Kalman Filter</a></b> attitude estimator. Including documentation and unit tests. <li><b><a href="https://ahrs.readthedocs.io/en/latest/filters/fkf.html">Fast Kalman Filter</a></b> attitude estimator. Including documentation and unit tests. </details> <details> <summary>New Submodules</summary> <li><b><a href="https://ahrs.readthedocs.io/en/latest/sensors.html">Sensors</a></b>. Including a class <code>sensors</code> to generate synthetic MARG sensor data, based on any given orientation.

>>> sensors = Sensors(num_samples=1000)
>>> sensors.gyroscopes.shape
(1000, 3)
>>> sensors.accelerometers.shape
(1000, 3)
>>> sensors.magnetometers.shape
(1000, 3)
>>> sensors.quaternions.shape
(1000, 4)

<li><b><a href="https://ahrs.readthedocs.io/en/latest/geodesy.html">geodesy</a></b> for geodetic analysis. The world models are now inclluded here, their transformations and conversions between different coordinate systems, and many tools for geodetic calculations. </details> <details> <summary>New Methods for Quaternion and QuaternionArray</summary> <li><code>slerp_nan()</code> to fill NaNs with interpolated values. <li><code>angular_velocities()</code> to compute angular velocities from a sequence of quaternions. <li><code>from_DCM()</code> and parameter <code>DCM</code>. <li><code>from_rpy()</code> to obtain quaternions from roll, pitch, yaw angles. <li><code>to_array()</code> to convert to a regular NumPy array. <br>... and many more! </details>

• All functions and objects are Type hinted.
• Metrics are now improved to compute faster, when vectorization is possible.
• Classes Quaternion and QuaternionArray are now derived from numpy.ndarray. This allows to use them as regular NumPy arrays, with all their methods and properties.
• A whole bunch of new constant values accessed from the top level of the package.
• All estimators are tested.
• Several fixes in implementation and documentation are applied.

For a thorough list of changes, please check the CHANGELOG.

Attitude Estimators

One of the most useful parts are the attitude estimation algorithms.

All estimators are refactored to be consistent with the corresponding articles describing them. They have in-code references to the equations, so that you can follow the original articles along with the code.

These estimators are based on two main solutions:

• Wahba's Problem (WP), which finds a rotation matrix between two coordinate systems. This means we compare measurement vectors against reference vectors. Their difference is the rotation. The solution to Wahba's problem mainly compares accelerometers and magnetometers against the gravitational and geomagnetic vectors, correspondingly.
• Dead Reckoning (DR) integrating the measured local angular velocity to increasingly estimate the angular position of the sensor.

Implemented attitude estimators are:

| Algorithm | Gyroscope | Accelerometer | Magnetometer | |---------------|:---------:|:-------------:|:------------:| | AQUA | YES | YES | Optional | | Complementary | YES | YES | Optional | | Davenport's | NO | YES | YES | | EKF | YES | YES | YES | | FAMC | NO | YES | YES | | FKF | YES | YES | YES | | FLAE | NO | YES | YES | | Fourati | YES | YES | YES | | FQA | NO | YES | Optional | | Integration | YES | NO | NO | | Madgwick | YES | YES | Optional | | Mahony | YES | YES | Optional | | OLEQ | NO | YES | YES | | QUEST | NO | YES | YES | | ROLEQ | YES | YES | YES | | SAAM | NO | YES | YES | | Tilt | NO | YES | Optional | | TRIAD | NO | YES | YES | | UKF | YES | YES | Optional |

To use the sensor data to estimate the attitude simply pass the data to a desired estimator, and it will automatically estimate the quaternions with the given parameters.

>>> attitude = ahrs.filters.Madgwick(acc=acc_data, gyr=gyro_data)
>>> attitude.Q.shape
(6959, 4)

Some algorithms allow a finer tuning of its estimation with different parameters. Check their documentation to see what can be tuned.

>>> attitude = ahrs.filters.Madgwick(acc=acc_data, gyr=gyro_data, mag=mag_data, gain=0.1, frequency=100.0)

Documentation

A comprehensive documentation, with examples, is available in Read the Docs.

Note for future versions

ahrs focuses on the algorithmic parts. Submodules io and plot have been removed from the package and codebase already.