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.

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.

  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.

  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

3.4 KiB Raw Blame History