maths.bearing
=============

.. py:module:: maths.bearing

.. autoapi-nested-parse::

   Initial bearing (forward azimuth) between two geographic points.

   Points are (latitude, longitude) in decimal degrees. Returns bearing in degrees
   clockwise from true north in the range [0, 360).

   Reference: https://en.wikipedia.org/wiki/Bearing_(navigation)



Functions
---------

.. autoapisummary::

   maths.bearing.initial_bearing


Module Contents
---------------

.. py:function:: initial_bearing(origin: tuple[float, float], destination: tuple[float, float]) -> float

   Compute the initial bearing from `origin` to `destination`.

   Parameters
   ----------
   origin, destination : tuple[float, float]
       (latitude, longitude) in decimal degrees.

   Returns
   -------
   float
       Initial bearing in degrees, clockwise from north in [0, 360).

   Raises
   ------
   TypeError
       If inputs are not 2-tuples of numbers.
   ValueError
       If the two points are identical (bearing undefined).

   Examples
   >>> round(initial_bearing((50.066389, -5.714722), (58.643889, -3.07)), 3)
   9.12
   >>> round(initial_bearing((0.0, 0.0), (1.0, 1.0)), 3)
   44.996
   >>> initial_bearing((0.0, 0.0), (0.0, 0.0))
   Traceback (most recent call last):
   ...
   ValueError: origin and destination are the same point; bearing is undefined