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

New Attitude Estimators

Unscented Kalman Filter attitude estimator. Including documentation and unit tests.

Fast Kalman Filter attitude estimator. Including documentation and unit tests.

New Submodules

Sensors. Including a class sensors 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)

geodesy for geodetic analysis. The world models are now inclluded here, their transformations and conversions between different coordinate systems, and many tools for geodetic calculations.

New Methods for Quaternion and QuaternionArray

slerp_nan() to fill NaNs with interpolated values.

angular_velocities() to compute angular velocities from a sequence of quaternions.

from_DCM() and parameter DCM.

from_rpy() to obtain quaternions from roll, pitch, yaw angles.

to_array() to convert to a regular NumPy array.
... and many more!

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