Fusion - GitLite

KO | EN

gitlite — search

#python #ai #typescript #golang #android #machine-learning #rust #deep-learning #linux #macos #windows #awesome #vue #awesome-list

Fusion

(★ 1,715)

No description available.

File Explorer

Download Latest Version (.zip)

- - main.yml
- - advanced_example.py
  - compass_vs_ahrs.py
  - sensor_data.csv
  - simple_example.py
  - test_convert.py
  - test_model.py
  - test_remap.py
- CMakeLists.txt
- Fusion.h
- FusionAhrs.c
- FusionAhrs.h
- FusionBias.c
- FusionBias.h
- FusionCompass.c
- FusionCompass.h
- FusionConfig.h
- FusionConvention.h
- FusionInline.h
- FusionMath.h
- FusionModel.h
- FusionRemap.h
- - Ahrs.h
  - AhrsFlags.h
  - AhrsInternalStates.h
  - AhrsSettings.h
  - Bias.h
  - BiasSettings.h
  - CMakeLists.txt
  - Compass.h
  - Convention.h
  - Convert.h
  - imufusion.c
  - Model.h
  - NpArray.h
  - Remap.h
- - __init__.pyi
- generate_stubs.py
.gitignore
CMakeLists.txt
LICENSE.md
MANIFEST.in
pyproject.toml
README.md
setup.py

# Installation Guide

1. Get the code

git clone https://github.com/xioTechnologies/Fusion

Downloads the entire project code from GitHub to your computer.

cd Fusion

Moves into the project folder you just downloaded.

2. CMake

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
CMake The tool used to generate build configuration.
C/C++ 컴파일러 Windows needs Visual Studio (Community edition, free), macOS needs Xcode Command Line Tools, Linux needs the gcc/g++ package.

mkdir build && cd build

Creates a folder to hold the build output and moves into it.

cmake ..

Analyzes the source code and generates build configuration files (must be run inside the build folder).

make

Compiles the code based on the generated build configuration to produce an executable.

✅ Check that an executable was created inside the build folder, then run it directly (e.g. ./build/app_name).

3. Python

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

pip install .

Installs the package published on PyPI directly — no need to clone the source.

python <실행할 파일명>.py # README에서 정확한 실행 파일명을 확인하세요

Runs the Python script (or module).

✅ If it runs without errors and prints output in the terminal, it worked.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Tags](https://img.shields.io/github/v/tag/xioTechnologies/Fusion.svg)](https://github.com/xioTechnologies/Fusion/tags/)
[![Build](https://img.shields.io/github/actions/workflow/status/xioTechnologies/Fusion/main.yml?branch=main)](https://github.com/xioTechnologies/Fusion/actions/workflows/main.yml)
[![Pypi](https://img.shields.io/pypi/v/imufusion.svg)](https://pypi.org/project/imufusion/)
[![Python](https://img.shields.io/pypi/pyversions/imufusion.svg)](https://pypi.org/project/imufusion/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

# Fusion

Fusion is a sensor fusion library for Inertial Measurement Units (IMUs), optimised for embedded systems. Fusion is a C library but is also available as the Python package, [imufusion](https://pypi.org/project/imufusion/). Two example Python scripts, [simple_example.py](https://github.com/xioTechnologies/Fusion/blob/main/Examples/Python/simple_example.py) and [advanced_example.py](https://github.com/xioTechnologies/Fusion/blob/main/Examples/Python/advanced_example.py) are provided with example sensor data to demonstrate use of the package.

## AHRS algorithm

The Attitude And Heading Reference System (AHRS) algorithm combines gyroscope, accelerometer, and magnetometer data into a single measurement of orientation relative to the Earth. The algorithm also supports systems that use only a gyroscope and accelerometer, and systems that use a gyroscope and accelerometer combined with an external source of heading measurement such as GPS.

The algorithm is based on the revised AHRS algorithm presented in chapter 7 of [Madgwick's PhD thesis](https://x-io.co.uk/downloads/madgwick-phd-thesis.pdf). This is a different algorithm to the better-known initial AHRS algorithm presented in chapter 3, commonly referred to as the *Madgwick algorithm*.

The algorithm calculates the orientation as the integration of the gyroscope summed with a feedback term. The feedback term is equal to the error in the current measurement of orientation as determined by the other sensors, multiplied by a gain. The algorithm therefore functions as a complementary filter that combines high-pass filtered gyroscope measurements with low-pass filtered measurements from other sensors with a corner frequency determined by the gain. A low gain will 'trust' the gyroscope more and so be more susceptible to drift. A high gain will increase the influence of other sensors and the errors that result from accelerations and magnetic distortions. A gain of zero will ignore the other sensors so that the measurement of orientation is determined by only the gyroscope.

### Startup

Startup occurs when the algorithm starts for the first time and during overrange recovery. During startup, the acceleration and magnetic rejection features are disabled and the gain is ramped down from 10 to the final value over a 3 second period. This allows the measurement of orientation to rapidly converge from an arbitrary initial value to the value indicated by the sensors.

### Overrange recovery

Angular rates that exceed the gyroscope measurement range cannot be tracked and will trigger an overrange recovery. Overrange recovery is activated when the angular rate exceeds 98% of the gyroscope measurement range and will trigger a restart of the algorithm.

### Acceleration rejection

The acceleration rejection feature reduces the errors that result from the accelerations of linear and rotational motion. Acceleration rejection works by calculating an error as the angular difference between the instantaneous measurement of inclination indicated by the accelerometer, and the current measurement of inclination provided by the algorithm output. If the error is greater than a threshold then the accelerometer will be ignored for that algorithm update. This is equivalent to a dynamic gain that decreases as accelerations increase.

Prolonged accelerations risk an overdependency on the gyroscope and will trigger an acceleration recovery. Acceleration recovery activates when the error exceeds the threshold for more than 90% of algorithm updates over a period of *t / (0.1p - 9)*, where *t* is the recovery trigger timeout and *p* is the percentage of algorithm updates where the error exceeds the threshold. The recovery will remain active until the error exceeds the threshold for less than 90% of algorithm updates over the period *-t / (0.1p - 9)*. The accelerometer will be used by every algorithm update during recovery.

### Magnetic rejection

The magnetic rejection feature reduces the errors that result from temporary magnetic distortions. Magnetic rejection works using the same principle as acceleration rejection, operating on the magnetometer instead of the accelerometer and by comparing the measurements of heading instead of inclination.

### Algorithm outputs

The algorithm provides four outputs: quaternion, gravity, linear acceleration, and Earth acceleration. The quaternion describes the orientation of the sensor relative to the Earth. This can be converted to a rotation matrix using the `FusionQuaternionToMatrix` function or to Euler angles using the `FusionQuaternionToEuler` function. Gravity is a direction of gravity in the sensor coordinate frame. Linear acceleration is the accelerometer measurement with gravity removed. Earth acceleration is the accelerometer measurement in the Earth coordinate frame with gravity removed. The algorithm supports North-West-Up (NWU), East-North-Up (ENU), and North-East-Down (NED) axes conventions.

### Algorithm settings

The AHRS algorithm settings are defined by the `FusionAhrsSettings` structure and set using the `FusionAhrsSetSettings` function.

| Setting                 | Description                                                                                                                                                                                                                                             |
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `sampleRate`            | Sample rate (in Hz).                                                                                                                                                                                                                                    |
| `convention`            | Earth axes convention (NWU, ENU, or NED).                                                                                                                                                                                                               |
| `gain`                  | Determines the influence of the gyroscope relative to other sensors. A value of zero will disable startup and the acceleration and magnetic rejection features. A value of 0.5 is appropriate for most applications.                                    |
| `gyroscopeRange`        | Gyroscope range (in degrees per second). Overrange recovery will activate if the gyroscope measurement exceeds 98% of this value. A value of zero will disable this feature. The value should be set to the range specified in the gyroscope datasheet. |
| `accelerationRejection` | Threshold (in degrees) used by the acceleration rejection feature. A value of zero will disable this feature. A value of 10 degrees is appropriate for most applications.                                                                               |
| `magneticRejection`     | Threshold (in degrees) used by the magnetic rejection feature. A value of zero will disable the feature. A value of 10 degrees is appropriate for most applications.                                                                                    |
| `rejectionTimeout`      | Acceleration and magnetic recovery trigger timeout (in seconds). A value of zero will disable the acceleration and magnetic rejection features. A period of 5 seconds is appropriate for most applications.                                             |

### Algorithm internal states

The AHRS algorithm internal states are defined by the `FusionAhrsInternalStates` structure and obtained using the `FusionAhrsGetInternalStates` function.

| State                         | Description                                                                                                                                                                                                                                                                                             |
|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `accelerationError`           | Angular error (in degrees) of the algorithm output relative to the instantaneous measurement of inclination indicated by the accelerometer. The acceleration rejection feature will ignore the accelerometer if this value exceeds the `accelerationRejection` threshold set in the algorithm settings. |
| `accelerometerIgnored`        | `true` if the accelerometer was ignored by the previous algorithm update.                                                                                                                                                                                                                               |
| `accelerationRecoveryTrigger` | Acceleration recovery trigger value between 0.0 and 1.0. Acceleration recovery will activate when this value reaches 1.0 and then deactivate when the value reaches 0.0.                                                                                                                                |
| `magneticError`               | Angular error (in degrees) of the algorithm output relative to the instantaneous measurement of heading indicated by the magnetometer. The magnetic rejection feature will ignore the magnetometer if this value exceeds the `magneticRejection` threshold set in the algorithm settings.               |
| `magnetometerIgnored`         | `true` if the magnetometer was ignored by the previous algorithm update.                                                                                                                                                                                                                                |
| `magneticRecoveryTrigger`     | Magnetic recovery trigger value between 0.0 and 1.0. Magnetic recovery will activate when this value reaches 1.0 and then deactivate when the value reaches 0.0.                                                                                                                                        |

### Algorithm flags

The AHRS algorithm flags are defined by the `FusionAhrsFlags` structure and obtained using the `FusionAhrsGetFlags` function.

| Flag                   | Description                          |
|------------------------|--------------------------------------|
| `startup`              | `true` during algorithm startup.     |
| `overrangeRecovery`    | `true` during overrange recovery.    |
| `accelerationRecovery` | `true` during acceleration recovery. |
| `magneticRecovery`     | `true` during magnetic recovery.     |

### Sample clock errors

The `FusionAhrsSetSamplePeriod` function may be called before each algorithm update with the measured sample period to compensate for gyroscope sample clock errors. The measured sample period must approximately match `sampleRate`.

## Bias algorithm

The bias algorithm provides run-time estimation of the gyroscope offset to compensate for variations in temperature and fine-tune existing offset calibration that may already be in place. This algorithm may be used to improve gyroscope measurements before providing them to the AHRS algorithm.

The algorithm estimates the gyroscope offset by identifying the stationary periods that occur naturally in many applications. Stationary periods are detected as the gyroscope measurement remaining below a threshold for a period of time. The gyroscope offset is then updated using a high-pass filter with a very low cutoff frequency.

### Settings

The bias algorithm settings are defined by the `FusionBiasSettings` structure and are configured using the `FusionBiasSetSettings` function.

| Setting               | Description                                                                                      |
|-----------------------|--------------------------------------------------------------------------------------------------|
| `sampleRate`          | Sample rate in Hz. The default value is 100 Hz.                                                  |
| `stationaryThreshold` | Stationary detection threshold in degrees per second. The default value is 3 degrees per second. |
| `stationaryPeriod`    | Stationary detection period in seconds. The default value is 3 seconds.                          |

### Non-volatile memory

The run-time estimate of the gyroscope offset may be saved to and restored from non-volatile memory to avoid re-estimation after each power cycle. This is supported by the `FusionBiasGetOffset` and `FusionBiasSetOffset` functions.

## Sensor models

Accurate algorithm outputs require calibrated sensor measurements. The library provides sensor models for applying gyroscope, accelerometer, and magnetometer calibration parameters. The library does not provide a method to determine these parameters.

### Inertial model

The `FusionModelInertial` function applies gyroscope or accelerometer calibration parameters using the model:

$$
\mathbf{i}_c = \mathbf{M} \mathbf{s} (\mathbf{i}_u - \mathbf{b})
$$

where:

- $\mathbf{i}_c$ = Calibrated gyroscope or accelerometer (function return value)
- $\mathbf{i}_u$ = Uncalibrated gyroscope or accelerometer (`uncalibrated` function parameter)
- $\mathbf{M}$ = Misalignment matrix (`misalignment` function parameter)
- $\mathbf{s}$ = Sensitivity diagonal matrix (`sensitivity` function parameter)
- $\mathbf{b}$ = Offset vector (`offset` function parameter)

### Magnetic model

The `FusionModelMagnetic` function applies magnetometer calibration parameters using the model:

$$
\mathbf{m}_c = \mathbf{S} (\mathbf{m}_u - \mathbf{h})
$$

where:

- $\mathbf{m}_c$ = Calibrated magnetometer (function return value)
- $\mathbf{m}_u$ = Uncalibrated magnetometer (`uncalibrated` function parameter)
- $\mathbf{S}$ = Soft-iron matrix (`softIronMatrix` function parameter)
- $\mathbf{h}$ = Hard-iron offset vector (`hardIronOffset` function parameter)

## Remap sensor axes

Sensors are often mounted such that their axes are not aligned with the body axes. The library provides the `FusionRemap` function to remap sensor axes to the body frame using one of the 24 possible orthogonal axis permutations defined by `FusionRemapAlignment`.

## Optimisations

### Inline functions

The `FUSION_INLINE` macro implements either `__forceinline` or `inline __attribute__((always_inline))` to inline functions and optimise for speed at the cost of program size. This can be disabled by uncommenting the `FUSION_NO_INLINE` in [FusionConfig.h](https://github.com/xioTechnologies/Fusion/blob/main/Fusion/FusionConfig.h) or adding this as a preprocessor definition.

### Fast inverse square root

Vector and quaternion normalisation operations use [Pizer's implementation](https://pizer.wordpress.com/2008/10/12/fast-inverse-square-root/) of the [fast inverse square root](https://en.wikipedia.org/wiki/Fast_inverse_square_root) algorithm. This increases speed for devices without an FPU, at a negligible cost to accuracy. Uncommenting `FUSION_USE_NORMAL_SQRT` in [FusionConfig.h](https://github.com/xioTechnologies/Fusion/blob/main/Fusion/FusionConfig.h) or adding this as a preprocessor definition will use normal square root for all operations.