GY-63_MS5611/libraries/AverageAngle/README.md

[![Arduino CI](https://github.com/RobTillaart/AverageAngle/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
[![Arduino-lint](https://github.com/RobTillaart/AverageAngle/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/AverageAngle/actions/workflows/arduino-lint.yml)
[![JSON check](https://github.com/RobTillaart/AverageAngle/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/AverageAngle/actions/workflows/jsoncheck.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/AverageAngle/blob/master/LICENSE)
[![GitHub release](https://img.shields.io/github/release/RobTillaart/AverageAngle.svg?maxAge=3600)](https://github.com/RobTillaart/AverageAngle/releases)


# AverageAngle

Arduino library to calculate correctly the average of multiple angles.


## Description

AverageAngle is a class to calculate the average of angles.

This is especially useful when angles are around 0 degrees, 
e.g. from a compass sensor or the resultant of a track.
Example, the average angle of 359 and 1 is 0, not 179 (most of the time)

Furthermore the AverageAngle can also include the **length (weight)** of the angle as if it is a vector. 
Default this length is set to 1 so all angles are by default of equal weight.

Example: The average angle of 359 (length = 2) and 1 (length = 1) is 359.something not zero.

See also **runningAngle** class.


#### AngleType

- **enum AngleType { DEGREES, RADIANS, GRADIANS }** idem. 100 GRADIANS == 90 DEGREES.

|  value  |  name      |
|:-------:|:-----------|
|   0     |  DEGREES   |
|   1     |  RADIANS   |
|   2     |  GRADIANS  |


## Interface

- **AverageAngle(AngleType type = DEGREES)** constructor defaults to degrees.
- **uint32_t add(float alpha, float length = 1.0)** add a new angle, optional with length. 
**add()** returns the number of elements (count).
- **void reset()** clears internal buffers.
- **uint32_t count()** the amount of angles added.
- **float getAverage()** returns the average.
- **float getTotalLength()** the length of the resulting 'angle' when we see them as vectors.
- **float getAverageLength()** returns the average length of the angles added.
- **AngleType type()** returns DEGREES, RADIANS or GRADIANS.
- **void setType(AngleType type)** changes type DEGREES, RADIANS or GRADIANS.


## Gradians

Gradians a.k.a. **gon**, is a less often used unit for angles. 
There are 100 gradians in a right angle. A full circle = 400 gradians.

https://en.wikipedia.org/wiki/Gradian


## Operation

If you want to average 5 compass readings you can just add the angles and 
do not use the length parameter.
```cpp
  AA.reset();
  for (int i = 0; i < 5; i++)
  {
    AA.add(compass.readHeading());
    delay(100);    // e.g. compass read needs some time
  }
  Serial.println(AA.getAverage());
```


If you want to average a track, e.g. 5 steps North, 3 steps west etc, 
you need to include the length of each step.
```cpp
  AA.reset();
  AA.add(90, 5);     // 5 steps north
  AA.add(180, 3);    // 3 steps west
  Serial.println(AA.getAverage());
  Serial.println(AA.getTotalLength());
```


## Future

- Improve documentation.
- check if other units exist to support.
- add a USER AngleType, in which the user can map 0..360 degrees to any number.
  - float userFactor = 1.0;  (default)
  - can even be negative?
  - use cases? e.g 0..4 quadrant?
- performance measurements
  -