Data

Tools

Indexes

Applications

Experiments

Open Source Science

ahrs

Attitude and Heading Reference Systems in Python

https://github.com/mayitzin/ahrs

Science Score: 44.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ✓
    CITATION.cff file
    Found CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ○
    Committers with academic emails
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (14.2%) to scientific vocabulary

Keywords

ahrs algorithms attitude attitude-estimators earth geomagnetism gravity imu imu-sensor madgwick orientations quaternions robots wgs84 wmm
Last synced: 4 months ago · JSON representation ·

Repository

Attitude and Heading Reference Systems in Python

Basic Info
Statistics
  • Stars: 658
  • Watchers: 17
  • Forks: 101
  • Open Issues: 30
  • Releases: 3
Topics
ahrs algorithms attitude attitude-estimators earth geomagnetism gravity imu imu-sensor madgwick orientations quaternions robots wgs84 wmm
Created over 6 years ago · Last pushed 5 months ago
Metadata Files
Readme Changelog Funding License Citation

README.md

AHRS: Attitude and Heading Reference Systems

Python application docs PyPI - License PyPI - Python Version PyPI Codacy Badge PyPI Downloads

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.6 and newer.

Installation

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

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

Or using pip for the stable releases:

shell 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

shell hatch version <major, minor, patch>

Important novelties in 0.3

(Click on each topic to see more details.)

The World Magnetic Model (WMM) is fully implemented. It is a re-implementation of the Spherical Harmonics approximation used by the United States' National Geopatial-Intelligence Agency. It can be used to estimate all magnetic field elements on any given place of Earth for dates between 2015 and 2025. ```python >>> from ahrs.utils import WMM >>> wmm = WMM(latitude=10.0, longitude=-20.0, height=10.5) >>> wmm.magnetic_elements {'X': 30499.640469609083, 'Y': -5230.267158472566, 'Z': -1716.633311360368, 'H': 30944.850352270452, 'F': 30992.427998627096, 'I': -3.1751692563622993, 'D': -9.73078560629778, 'GV': -9.73078560629778} ```
The Ellipsoid model of the World Geodetic System (WGS84) is also included. The estimation of the main and derived parameters of the WGS84 using the ellipsoid model are implemented: ```python >>> from ahrs.utils import WGS >>> wgs = WGS() # Creates an ellipsoid model, using Earth's characteristics by default >>> wgs_properties = [x for x in dir(wgs) if not (hasattr(wgs.__getattribute__(x), '__call__') or x.startswith('__'))] >>> for p in wgs_properties: ... print('{:<{w}} {}'.format(p, wgs.__getattribute__(p), w=len(max(wgs_properties, key=len)))) ... a 6378137.0 arithmetic_mean_radius 6371008.771415059 aspect_ratio 0.9966471893352525 atmosphere_gravitational_constant 343591934.4 authalic_sphere_radius 6371007.1809182055 b 6356752.314245179 curvature_polar_radius 6399593.625758493 dynamic_inertial_moment_about_X 8.007921777277886e+37 dynamic_inertial_moment_about_Y 8.008074799852911e+37 dynamic_inertial_moment_about_Z 8.03430094201443e+37 dynamical_form_factor 0.0010826298213129219 equatorial_normal_gravity 9.78032533590406 equivolumetric_sphere_radius 6371000.790009159 f 0.0033528106647474805 first_eccentricity_squared 0.0066943799901413165 geometric_dynamic_ellipticity 0.003258100628533992 geometric_inertial_moment 8.046726628049449e+37 geometric_inertial_moment_about_Z 8.073029370114392e+37 gm 398600441800000.0 gravitational_constant_without_atmosphere 398600098208065.6 is_geodetic True linear_eccentricity 521854.00842338527 mass 5.972186390142457e+24 mean_normal_gravity 9.797643222256516 normal_gravity_constant 0.0034497865068408447 normal_gravity_potential 62636851.71456948 polar_normal_gravity 9.832184937863065 second_degree_zonal_harmonic -0.00048416677498482876 second_eccentricity_squared 0.006739496742276434 w 7.292115e-05 ``` It can be used, for example, to estimate the normal gravity acceleration (in m/s^2) at any location on Earth. ```python >>> wgs.normal_gravity(50.0, 1000.0) # Normal gravity at latitude = 50.0 °, 1000 m above surface 9.807617683884756 ``` Setting the fundamental parameters (`a`, `f`, `GM`, `w`) yields a different ellipsoid. For the moon, for instance, we build a new model: ```python >>> moon_a = ahrs.MOON_EQUATOR_RADIUS >>> moon_f = (ahrs.MOON_EQUATOR_RADIUS-ahrs.MOON_POLAR_RADIUS)/ahrs.MOON_EQUATOR_RADIUS >>> moon_gm = ahrs.MOON_GM >>> moon_w = ahrs.MOON_ROTATION >>> moon = WGS(a=moon_a, f=moon_f, GM=moon_gm, w=moon_w) >>> moon.normal_gravity(10.0, h=500.0) # Gravity on moon at 10° N and 500 m above surface 1.6239259827292798 >>> moon.is_geodetic # Only the Earth is geodetic False ``` A full implementation of the **Earth Gravitational Model** ([EGM2008](https://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008/egm08_wgs84.html)) using Spherical Harmonics is **NOT** available here.
The International Gravity Formula and the EU's WELMEC normal gravity reference system are also implemented. ```python >>> ahrs.utils.international_gravity(50.0) # Latitude = 50° N 9.810786421572386 >>> ahrs.utils.welmec_gravity(50.0, 500.0) # Latitude = 50° N, height above sea = 500 m 9.809152687885897 ```
New class DCM (derived from numpy.ndarray). This new class represents 3x3 Direction Cosine Matrices used to describe orientations / rotations operations. ```python >>> from ahrs import DCM >>> R = DCM(x=10.0, y=20.0, z=30.0) >>> type(R) >>> R.view() DCM([[ 0.81379768 -0.46984631 0.34202014], [ 0.54383814 0.82317294 -0.16317591], [-0.20487413 0.31879578 0.92541658]]) >>> R.inv # or R.I array([[ 0.81379768 0.54383814 -0.20487413] [-0.46984631 0.82317294 0.31879578] [ 0.34202014 -0.16317591 0.92541658]]) >>> R.log array([0.26026043, 0.29531805, 0.5473806 ]) >>> R.to_axisangle() # Axis in 3D NumPy array, and angle as radians (array([0.38601658, 0.43801381, 0.81187135]), 0.6742208510527136) >>> R.to_quaternion() array([0.94371436, 0.12767944, 0.14487813, 0.26853582]) >>> R.to_quaternion(method='itzhack', version=2) array([ 0.94371436, -0.12767944, -0.14487813, -0.26853582]) ```
New class QuaternionArray (derived from numpy.ndarray). This class can be used to simultaneously handle an array with several quaternions at once. ```python >>> Q = QuaternionArray(np.random.random((3, 4))-0.5) >>> Q.view() QuaternionArray([[ 0.31638467, 0.59313477, -0.62538687, -0.39621099], [ 0.24973118, -0.37958194, -0.67851278, -0.57721079], [-0.44643469, 0.17200957, -0.72678553, 0.49284031]]) >>> Q.w array([ 0.31638467, 0.24973118, -0.44643469]) >>> Q.to_DCM() array([[[-0.09618377, -0.49116723, -0.86573866], [-0.99258756, -0.017584 , 0.1202528 ], [-0.07428738, 0.8708878 , -0.48583519]], [[-0.58710377, 0.80339746, 0.09930598], [ 0.22680733, 0.04549051, 0.97287669], [ 0.77708918, 0.5937029 , -0.20892408]], [[-0.54221755, 0.19001389, 0.81847104], [-0.69007015, 0.45504228, -0.56279633], [-0.47937805, -0.86996048, -0.115609 ]]]) >>> Q.conjugate() array([[ 0.31638467, -0.59313477, 0.62538687, 0.39621099], [ 0.24973118, 0.37958194, 0.67851278, 0.57721079], [-0.44643469, -0.17200957, 0.72678553, -0.49284031]]) >>> Q.average() array([ 0.19537239, 0.17826049, -0.87872408, -0.39736232]) ```
  • Type hints are added.
  • NumPy is now the only third-party dependency.
  • New submodule frames to represent the position of an object in different reference frames.
  • Metrics for rotations in 3D spaces using quaternions and direction cosine matrices.
  • New operations, properties and methods for class Quaternion (now also derived from numpy.ndarray)
  • A whole bunch of new constant values (mainly for Geodesy) accessed from the top level of the package.
  • Docstrings are improved with further explanations, references and equations whenever possible.

More Attitude Estimators

One of the biggest improvements in this version is the addition of many new 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 | | 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 |

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.

```python

attitude = ahrs.filters.Madgwick(acc=accdata, gyr=gyrodata) 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.

```python

attitude = ahrs.filters.Madgwick(acc=accdata, gyr=gyrodata, mag=mag_data, gain=0.1, frequency=100.0) ```

Speaking of documentation...

Documentation

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

Note for future versions

ahrs moves away from plotting and data handling submodules to better focus in the algorithmic parts. Submodules io and plot are not built in the package anymore, and will be entirely removed from the base code in the next release.

This way you can also choose your favorite libraries for data loading and visualization. This also means, getting rid of its dependency on matplotlib too.

Owner

  • Name: Mario Garcia
  • Login: Mayitzin
  • Kind: user
  • Location: Munich
  • Company: Neeno

Citation (CITATION.cff) 

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
  - family-names: "Garcia"
    given-names: "Mario"
    orcid: "https://orcid.org/0009-0000-3927-1842"
title: "Attitude and Heading Reference Systems in Python"
date-released: 2020-01-10
url: "https://github.com/Mayitzin/ahrs"

GitHub Events

Total
  • Issues event: 14
  • Watch event: 79
  • Issue comment event: 16
  • Push event: 61
  • Pull request event: 1
  • Fork event: 10
Last Year
  • Issues event: 14
  • Watch event: 79
  • Issue comment event: 16
  • Push event: 61
  • Pull request event: 1
  • Fork event: 10

Committers

Last synced: almost 2 years ago

All Time
  • Total Commits: 545
  • Total Committers: 8
  • Avg Commits per committer: 68.125
  • Development Distribution Score (DDS): 0.018
Past Year
  • Commits: 99
  • Committers: 2
  • Avg Commits per committer: 49.5
  • Development Distribution Score (DDS): 0.01
Top Committers
Name Email Commits
Mayitzin m****n@g****m 535
Mayitzin m****o@m****m 3
jaluebbe j****2@g****m 2
Federico Ceratto f****o@d****g 1
ManuelPalermo m****o@g****m 1
petrinm p****m@g****m 1
Tim Taubner tt@d****i 1
Botond 4****d 1
Committer Domains (Top 20 + Academic)
daedalean.ai: 1 debian.org: 1 mayitzin.com: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time
  • Total issues: 88
  • Total pull requests: 11
  • Average time to close issues: 3 months
  • Average time to close pull requests: 16 days
  • Total issue authors: 74
  • Total pull request authors: 10
  • Average comments per issue: 1.84
  • Average comments per pull request: 0.45
  • Merged pull requests: 10
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 3
  • Pull requests: 1
  • Average time to close issues: 22 days
  • Average time to close pull requests: 23 days
  • Issue authors: 3
  • Pull request authors: 1
  • Average comments per issue: 1.33
  • Average comments per pull request: 0.0
  • Merged pull requests: 1
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • Mayitzin (3)
  • viatto (2)
  • anisghaoui (2)
  • 43998213 (2)
  • Yushchuk6 (2)
  • ogreyesp (2)
  • jerabaul29 (2)
  • geoKinga (2)
  • adrian-soch (2)
  • bdeming155 (2)
  • johann-petrak (2)
  • PeterBorisenko (2)
  • KomaGR (2)
  • aayushsingla (1)
  • perotom (1)
Pull Request Authors
  • jaluebbe (2)
  • eragooon (2)
  • FedericoCeratto (1)
  • lucagrementieri (1)
  • whoispo (1)
  • tokoro10g (1)
  • ManuelPalermo (1)
  • codacy-badger (1)
  • nasbotond (1)
  • timethy (1)
  • petrinm (1)
  • philipp-leibner (1)
Top Labels
Issue Labels
question (4) enhancement (4) bug (2) help wanted (2)
Pull Request Labels

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 36,119 last-month
  • Total docker downloads: 27
  • Total dependent packages: 3
  • Total dependent repositories: 8
  • Total versions: 6
  • Total maintainers: 1
pypi.org: ahrs

Attitude and Heading Reference Systems.

  • Versions: 6
  • Dependent Packages: 3
  • Dependent Repositories: 8
  • Downloads: 36,119 Last month
  • Docker Downloads: 27
Rankings
Downloads: 1.7%
Dependent packages count: 2.4%
Stargazers count: 3.0%
Average: 3.5%
Docker downloads count: 3.5%
Forks count: 5.0%
Dependent repos count: 5.2%
Maintainers (1)
Mayitzin
Last synced: 4 months ago

Dependencies

docs/source/requirements.txt pypi
  • Sphinx >=3.0
  • sphinx_rtd_theme >=0.5
requirements.txt pypi
  • docutils <0.18
  • numpy >=1.17
setup.py pypi
  • numpy *
.github/workflows/python-app.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v3 composite