geodesy.haversine_distance
==========================

.. py:module:: geodesy.haversine_distance


Attributes
----------

.. autoapisummary::

   geodesy.haversine_distance.AXIS_A
   geodesy.haversine_distance.AXIS_B
   geodesy.haversine_distance.RADIUS


Functions
---------

.. autoapisummary::

   geodesy.haversine_distance.haversine_distance


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

.. py:function:: haversine_distance(lat1: float, lon1: float, lat2: float, lon2: float) -> float

   Calculate great circle distance between two points in a sphere,
   given longitudes and latitudes https://en.wikipedia.org/wiki/Haversine_formula

   We know that the globe is "sort of" spherical, so a path between two points
   isn't exactly a straight line. We need to account for the Earth's curvature
   when calculating distance from point A to B. This effect is negligible for
   small distances but adds up as distance increases. The Haversine method treats
   the earth as a sphere which allows us to "project" the two points A and B
   onto the surface of that sphere and approximate the spherical distance between
   them. Since the Earth is not a perfect sphere, other methods which model the
   Earth's ellipsoidal nature are more accurate but a quick and modifiable
   computation like Haversine can be handy for shorter range distances.

   Args:
       * `lat1`, `lon1`: latitude and longitude of coordinate 1
       * `lat2`, `lon2`: latitude and longitude of coordinate 2
   Returns:
       geographical distance between two points in metres

   >>> from collections import namedtuple
   >>> point_2d = namedtuple("point_2d", "lat lon")
   >>> SAN_FRANCISCO = point_2d(37.774856, -122.424227)
   >>> YOSEMITE = point_2d(37.864742, -119.537521)
   >>> f"{haversine_distance(*SAN_FRANCISCO, *YOSEMITE):0,.0f} meters"
   '254,352 meters'


.. py:data:: AXIS_A
   :value: 6378137.0


.. py:data:: AXIS_B
   :value: 6356752.314245


.. py:data:: RADIUS
   :value: 6378137