How mayitzin/ahrs works
Purpose and Public Surface
AHRS is a pure-Python, NumPy-based library for prototyping, teaching, and validating attitude/heading estimation for moving sensor systems. It is a library rather than a service or application. Primary import surface: ahrs/__init__.py; estimator namespace: ahrs/filters/__init__.py.
Primary Estimation Pipeline
Callers provide time-series gyroscope, accelerometer, and optionally magnetometer vectors to an estimator class. The estimator computes orientation, typically as an N x 4 quaternion sequence (Q), using either reference-vector alignment (Wahba-style) or gyroscope integration with corrective fusion. Key implementations: ahrs/filters/madgwick.py, ahrs/filters/ekf.py, ahrs/filters/ukf.py.
Estimator Families
ahrs/filters/ is the central algorithm boundary and exposes interchangeable estimators with broadly consistent sensor-data inputs. It includes direct/reference-vector solvers (Davenport, QUEST, TRIAD, FLAE), complementary and gradient filters, and state estimators/Kalman variants. Representative paths: ahrs/filters/quest.py, ahrs/filters/complementary.py, ahrs/filters/fkf.py.
Orientation Representation and Linear Algebra
Shared mathematical representations isolate algorithms from rotation-conversion details. Quaternion and quaternion-array types derive from NumPy arrays; DCM operations and orientation conversions support input/output transformation, interpolation, integration, and rotation. Paths: ahrs/common/quaternion.py, ahrs/common/dcm.py, ahrs/common/orientation.py.
Coordinate Frames and Physical References
Frame transforms and physical constants establish the reference conventions consumed by estimators and geodetic utilities, including ECEF, ENU, geodetic, and attitude-frame conversions. Paths: ahrs/common/frames.py, ahrs/common/constants.py, ahrs/utils/wgs84.py.
Sensor Synthesis, Geodesy, and Magnetic Models
Utilities can generate synthetic MARG sensor streams from orientations and derive gravity/geomagnetic references. World Magnetic Model coefficient files are package data, not remote dependencies; models cover 2015, 2020, and 2025. Paths: ahrs/utils/sensors.py, ahrs/utils/wmm.py, ahrs/utils/WMM2025/WMM.COF.
Runtime, Packaging, and Delivery
Runtime requires Python 3.9+ and has NumPy as its material dependency. Package metadata/build configuration is in pyproject.toml; GitHub Actions executes the Python workflow at .github/workflows/python-app.yml. Documentation is a Sphinx project published through Read the Docs configuration: docs/source/conf.py, .readthedocs.yml.
Main entry points: filters/__init__.py Estimator namespace · quaternion.py Quaternion types · ahrs/__init__.py AHRS package · sensors.py Sensor synthesis
Components 22
Public API
- AHRS package · Primary import surface.
ahrs/__init__.py - Estimator namespace · Interchangeable estimator classes.
ahrs/filters/__init__.py - Sensor time series · Gyroscope, accelerometer, and optional magnetometer vectors.
- Quaternion sequence · Typically an N x 4 orientation sequence (Q).
Estimator Algorithms
- Reference-vector solvers · Davenport, QUEST, TRIAD, and FLAE alignment methods.
ahrs/filters/quest.py - Complementary fusion
ahrs/filters/complementary.py - Madgwick filter
ahrs/filters/madgwick.py - Kalman estimators · EKF, UKF, and fast Kalman variants.
ahrs/filters/ekf.py - Fast Kalman filter
ahrs/filters/fkf.py
Math & Frames
- Quaternion types · Quaternion and quaternion-array operations.
ahrs/common/quaternion.py - Direction cosine matrices
ahrs/common/dcm.py - Orientation conversions · Conversion, interpolation, integration, and rotation operations.
ahrs/common/orientation.py - Coordinate frames · ECEF, ENU, geodetic, and attitude-frame conversions.
ahrs/common/frames.py - Physical constants
ahrs/common/constants.py
Models & Utilities
- Sensor synthesis · Generates synthetic MARG streams from orientations.
ahrs/utils/sensors.py - WGS84 geodesy
ahrs/utils/wgs84.py - World Magnetic Model · Derives geomagnetic references from packaged coefficients.
ahrs/utils/wmm.py - WMM 2025 coefficients · Bundled magnetic-model coefficients; 2015 and 2020 are also included.
ahrs/utils/WMM2025/WMM.COF
Build & Delivery
- Package build · Python 3.9+ runtime with NumPy dependency.
pyproject.toml - Python CI
.github/workflows/python-app.yml - Sphinx documentation · Published via Read the Docs.
docs/source/conf.py - Read the Docs config
.readthedocs.yml
Connections 26
- AHRS package → Estimator namespace: exports
- Sensor time series → Estimator namespace: provided to estimators
- Estimator namespace → Reference-vector solvers: exposes
- Estimator namespace → Complementary fusion: exposes
- Estimator namespace → Madgwick filter: exposes
- Estimator namespace → Kalman estimators: exposes
- Estimator namespace → Fast Kalman filter: exposes
- Reference-vector solvers → Quaternion sequence: computes
- Complementary fusion → Quaternion sequence: computes
- Madgwick filter → Quaternion sequence: computes
- Kalman estimators → Quaternion sequence: computes
- Fast Kalman filter → Quaternion sequence: computes
- Estimator namespace → Quaternion types: uses
- Quaternion types → Direction cosine matrices: converts with
- Quaternion types → Orientation conversions: supports
- Estimator namespace → Coordinate frames: uses reference conventions
- Estimator namespace → Physical constants: uses
- Sensor synthesis → Sensor time series: generates
- Sensor synthesis → Quaternion types: uses orientations
- WGS84 geodesy → Coordinate frames: supports
- WMM 2025 coefficients → World Magnetic Model: loaded by
- World Magnetic Model → Estimator namespace: provides magnetic reference
- Package build → AHRS package: builds
- Python CI → Package build: validates
- Sphinx documentation → AHRS package: documents
- Read the Docs config → Sphinx documentation: publishes