Docs: Add new Ellipsoids page to explain ellipsoidal parameters (#2922)

Co-authored-by: Rohit <rohitpingale103@gmail.com>
Co-authored-by: Brendan Jurd <brendan.jurd@geoplex.com.au>
Co-authored-by: Mike Taves <mwtoews@gmail.com>

2 files changed, 160 insertions, 0 deletions

diff --git a/docs/source/usage/ellipsoids.rst b/docs/source/usage/ellipsoids.rst
new file mode 100644
index 00000000..cd4b0c43
--- /dev/null
+++ b/docs/source/usage/ellipsoids.rst
@@ -0,0 +1,159 @@
+.. _ellipsoids:
+
+================================================================================
+Ellipsoids
+================================================================================
+An ellipsoid is a mathematically defined surface which approximates the *geoid*:
+the surface of the Earth's gravity field, which is approximately the same as
+mean sea level.
+
+
+.. figure:: ../../images/general_ellipsoid.png
+   :width: 500 px
+   :align: center
+   :alt:   Global and local fitting of the ellipsoid
+
+   Global and local fitting of the ellipsoid
+
+
+A complete ellipsoid definition comprises a size (primary) and a shape (secondary)
+parameter.
+
+.. _ellipsoid_size_parameters:
+
+Ellipsoid size parameters
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. option:: +R=<value>
+
+   Radius of the sphere, :math:`R`.
+
+.. option:: +a=<value>
+
+   Semi-major axis of the ellipsoid, :math:`a`.
+
+.. _ellipsoid_shape_parameters:
+
+Ellipsoid shape parameters
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. option:: +rf=<value>
+
+   Reverse flattening of the ellipsoid, :math:`1/f`.
+
+.. option:: +f=<value>
+
+   Flattening of the ellipsoid, :math:`f`.
+
+.. option:: +es=<value>
+
+   Eccentricity squared, :math:`e^2`.
+
+.. option:: +e=<value>
+
+   Eccentricity, :math:`e`.
+
+.. option:: +b=<value>
+
+   Semi-minor axis, :math:`b`.
+
+The ellipsoid definition may be augmented with a spherification flag, turning
+the ellipsoid into a sphere with features defined by the ellipsoid.
+
+.. _ellipsoid_spherification_parameters:
+
+Ellipsoid spherification parameters
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. option:: +R_A=<value>
+
+   A sphere with the same surface area as the ellipsoid.
+
+.. option:: +R_V=<value>
+
+   A sphere with the same volume as the ellipsoid.
+
+.. option:: +R_a=<value>
+
+   A sphere with :math:`R = (a + b)/2` (arithmetic mean).
+
+.. option:: +R_g=<value>
+
+   A sphere with :math:`R = \sqrt{ab}` (geometric mean).
+
+.. option:: +R_h=<value>
+
+   A sphere with :math:`R = 2ab/(a+b)` (harmonic mean).
+
+.. option:: +R_lat_a=<phi>
+
+   A sphere with :math:`R` being the arithmetic mean of the corresponding
+   ellipsoid at latitude :math:`\phi`.
+
+.. option:: +R_lat_g=<phi>
+
+   A sphere with :math:`R` being the geometric mean of the corresponding
+   ellipsoid at latitude :math:`\phi`.
+
+If :option:`+R` is given as size parameter, any shape and spherification
+parameters given are ignored.
+
+.. _ellipsoid_definitions:
+
+Built-in ellipsoid definitions
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The ``ellps=xxx`` parameter provides both size and shape for a number of
+built-in ellipsoid definitions.
+
+    ============   =================================    ============================
+    ellps          Parameters                           Datum name
+    ============   =================================    ============================
+    GRS80          a=6378137.0      rf=298.257222101    GRS 1980(IUGG, 1980)
+    airy           a=6377563.396    b=6356256.910       Airy 1830
+    bessel         a=6377397.155    rf=299.1528128      Bessel 1841
+    clrk66         a=6378206.4      b=6356583.8         Clarke 1866
+    intl           a=6378388.0      rf=297.             International 1909 (Hayford)
+    WGS60          a=6378165.0      rf=298.3            WGS 60
+    WGS66          a=6378145.0      rf=298.25           WGS 66
+    WGS72          a=6378135.0      rf=298.26           WGS 72
+    WGS84          a=6378137.0      rf=298.257223563    WGS 84
+    sphere         a=6370997.0      b=6370997.0         Normal Sphere (r=6370997)
+    ============   =================================    ============================
+
+If size and shape are given as ``ellps=xxx``, later shape and size parameters
+are are taken into account as modifiers for the built-in ellipsoid definition.
+
+While this may seem strange, it is in accordance with historical PROJ
+behavior. It can e.g. be used to define coordinates on the ellipsoid
+scaled to unit semimajor axis by specifying ``+ellps=xxx +a=1``
+
+.. _ellipsoid_transformation_examples:
+
+Transformation examples
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Spherical earth with radius 7000km:
+
+::
+
+    proj=laton R=7000000
+
+Using the GRS80 ellipsoid:
+
+::
+
+    proj=laton ellps=GRS80
+
+Expressing ellipsoid by semi-major axis and reverse flattening (:math:`1/f`):
+
+::
+
+    proj=laton a=6378137.0 rf=298.25
+
+Spherical earth based on volume of ellipsoid
+
+::
+
+    proj=laton a=6378137.0 rf=298.25 +R_V
+
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
index a074b18b..4bb75121 100644
--- a/docs/source/usage/index.rst
+++ b/docs/source/usage/index.rst
@@ -15,6 +15,7 @@ command line applications or the C API that is a part of the software package.
    quickstart
    projections
    transformation
+   ellipsoids
    environmentvars
    differences
    network