uwacan.positional.average_angle#

average_angle(angle, resolution=None)[source]#

Calculate the average angle and optionally round it to a specified resolution.

Parameters:

anglearray_like: Array of angles in degrees to be averaged.
resolutionint, str, optional: Specifies the resolution for rounding the angle. It can be an integer specifying the number of divisions (e.g., 4, 8, 16) or a string (‘4’, ‘8’, ‘16’, ‘four’, ‘eight’, ‘sixteen’).

Returns:

float or str: If resolution is None, returns the average angle in degrees. If resolution is an integer, returns the average angle rounded to this fraction of a turn. If resolution is a string, returns the closest named direction (e.g., ‘North’, ‘Southwest’).

Raises:

ValueError: If an unknown resolution specifier is provided.

Notes

The function converts the input angles to complex numbers, computes their mean, and then converts back to an angle. If a string resolution is specified, the function maps the average angle to the nearest named direction.

Examples

>>> average_angle([350, 10, 40, 40])
20.15962133607971
>>> average_angle([350, 10, 30], resolution=10)
36.0
>>> average_angle([350, 10, 30], resolution='four')
'North'
>>> average_angle([350, 10, 20], resolution='sixteen')
'North-northeast'