Complementary Filter¶
Attitude obtained with gyroscope and accelerometermagnetometer measurements, via complementary filter.
The complementary filter is one of the simplest ways to fuse sensor data from multiple sensors. It is based on the idea that the errors from one sensor will be compensated by the other sensor, and vice versa.
The gyroscopes tend to have a lowfrequency drift, while the accelerometers and magnetometers tend to have a highfrequency noise. The complementary filter simple “combines” these two signals, yielding the benefit of eliminating the drift from the gyroscope and noise from the accelerometer.
First, the tilt angles computed from the accelerometer measurements as:
Only the roll, \(\theta_x\), and pitch, \(\theta_y\), angles are computed, leaving the yaw angle, \(\theta_z\), equal to zero.
If a magnetometer sample is available, the yaw angle, \(\theta_z\) can be computed. First compensate the measured magnetic field using the tilt:
Then \(\theta_z\) is obtained as:
Likewise, the orientation is again estimated at \(t\), but this time from a previous orientation at \(t1\), and a given angular velocity, \(\boldsymbol{\omega}=\begin{bmatrix}\omega_x & \omega_y & \omega_z\end{bmatrix}^T\), in rad/s, using the simplest numerical integration:
where \(\Delta_t\) is the time interval between the current and previous measurements, a.k.a. the sampling period or time step. This is merely the opposite of the sampling frequency: \(\Delta_t=^1/f_s\).
Finally, the estimations are merged using a complementary filter with a controlling parameter, \(\alpha\), in the range \([0, 1]\):
where \(\boldsymbol{\theta}_\omega\) is the attitude estimated from the gyroscope, \(\boldsymbol{\theta}_{am}\) is the attitude estimated from the accelerometer and the magnetometer, and \(\alpha\) is the gain of the filter.
The filter gain must be a floating value within the range \([0.0, 1.0]\). It can be seen that when \(\alpha=0\), the attitude is estimated entirely with the accelerometer and the magnetometer. When \(\alpha=1\), it is estimated solely with the gyroscope. The values within the range decide how much of each estimation is “blended” into the quaternion.

class
ahrs.filters.complementary.
Complementary
(gyr: numpy.ndarray = None, acc: numpy.ndarray = None, mag: numpy.ndarray = None, frequency: float = 100.0, gain: float = 0.9, **kwargs)¶ Complementary filter for attitude estimation as quaternion.
Parameters:  gyr (numpy.ndarray, default: None) – Nby3 array with measurements of angular velocity, in rad/s.
 acc (numpy.ndarray, default: None) – Nby3 array with measurements of acceleration, in m/s^2.
 mag (numpy.ndarray, default: None) – Nby3 array with measurements of magnetic field, in mT.
 frequency (float, default: 100.0) – Sampling frequency in Herz.
 Dt (float, default: 0.01) – Sampling step in seconds. Inverse of sampling frequency. Not required
if
frequency
value is given.  gain (float, default: 0.9) – Filter gain. Gain equal to 1 uses Angular velocities (gyroscopes) only. Gain equal to 0 uses Accelerometer, and Magnetometer if available, only. Values greater than zero and less than one blend the two estimations proportionally.
 w0 (numpy.ndarray, default: None) – Initial angular position, as rollpitchyaw angles, in radians.
 q0 (numpy.ndarray, default: None) – Initial orientation, as a versor (normalized quaternion).
 representation (str, default:
'angles'
) – Attitude representation. Options are'angles'
,'quaternion'
or'rotmat'
.
Raises: ValueError
– When dimension of input arraysacc
,gyr
, ormag
are not equal.
Q
¶ Attitudes as quaternions.
Returns: Q – Mby4 Array with all estimated quaternions, where M is the number of samples. Return type: numpy.ndarray

am_estimation
(acc: numpy.ndarray, mag: numpy.ndarray = None) → numpy.ndarray¶ Attitude estimation from an AccelerometerMagnetometer architecture.
Parameters:  acc (numpy.ndarray) – Nby3 array with measurements of gravitational acceleration.
 mag (numpy.ndarray, default: None) – Nby3 array with measurements of local geomagnetic field.
Returns: q_am – Estimated attitude.
Return type: numpy.ndarray