Merge 1faa128 into 121deeb

OSGeo · Aug 20, 2018 · 14bcbff · 14bcbff
2 parents 121deeb + 1faa128
commit 14bcbff
Show file tree

Hide file tree

Showing 5 changed files with 308 additions and 5 deletions.
diff --git a/docs/source/operations/conversions/cart.rst b/docs/source/operations/conversions/cart.rst
@@ -1,23 +1,28 @@
 .. _cart:
 
 ================================================================================
-Cartesian to geodetic conversion
+Geodetic to cartesian conversion
 ================================================================================
 
 .. versionadded:: 5.0.0
 
-Convert geodetic coordinates to cartesian coordinates.
+Convert geodetic coordinates to cartesian coordinates (in the forward path).
 
 +---------------------+--------------------------------------------------------+
 | **Alias**           | cart                                                   |
 +---------------------+--------------------------------------------------------+
 | **Domain**          | 3D                                                     |
 +---------------------+--------------------------------------------------------+
-| **Input type**      | Cartesian coordinates                                  |
+| **Input type**      | Geodetic coordinates                                   |
 +---------------------+--------------------------------------------------------+
-| **Output type**     | Cartesian coordinates                                  |
+| **Output type**     | Geocentric cartesian coordinates                       |
 +---------------------+--------------------------------------------------------+
 
+This conversion converts geodetic coordinate values (longitude, latitude,
+elevation above ellipsoid) to their geocentric (X, Y, Z) representation, where
+the first axis (X) points from the Earth centre to the point of longitude=0,
+latitude=0, the second axis (Y) points from the Earth centrer to the point of
+longitude=90, latitude=0 and the third axis (Z) points to the North pole.
 
 Parameters
 ################################################################################

diff --git a/docs/source/operations/conversions/geoc.rst b/docs/source/operations/conversions/geoc.rst
@@ -0,0 +1,75 @@
+.. _geoc:
+
+================================================================================
+Geocentric Latitude
+================================================================================
+
+.. versionadded:: 5.0.0
+
+Convert from Geodetic Latitude to Geocentric Latitude (in the forward path).
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | geoc                                                   |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 2D                                                     |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Geodetic coordinates                                   |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Geocentric angular coordinates                         |
++---------------------+--------------------------------------------------------+
+
+The geodetic (or geographic) latitude (also called planetographic latitude
+in the context of non-Earth bodies) is the angle between the equatorial plane
+and the normal (vertical) to the ellipsoid surface at the considered point.
+The geodetic latitude is what is normally used everywhere in PROJ when angular
+coordinates are expected or produced.
+
+The geocentric latitude (also called planetocentric latitude in the context of
+non-Earth bodies) is the angle between the equatorial plane and a line joining
+the body centre to the considered point.
+
+.. image:: ./images/geocentric_latitude.svg
+   :align: center
+   :scale: 100%
+   :alt:   Geocentric latitude
+
+
+.. note::
+
+    This conversion must be distinguished fom the :ref:`cart`
+    which converts geodetic coordinates to geocentric coordinates in the cartesian
+    domain.
+
+Mathematical definition
+#######################
+
+The formulas describing the conversion are taken from :cite:`Snyder1987`
+(equation 3-28)
+
+Let :math:`\phi'` to be the geocentric latitude and :math:`\phi`  the
+geodetic latitude, then
+
+.. math::
+
+  \phi' = \arctan \left[ (1 - e^2) \tan \left( \phi \right) \right]
+
+The geocentric latitude is consequently lesser (in absolute value) than the geodetic
+latitude, except at the equator and the poles where they are equal.
+
+On a sphere, they are always equal.
+
+Usage
+################################################################################
+
+Converting from geodetic latitude to geocentric latitude::
+
+    +proj=geoc +ellps=GRS80
+
+Converting from geocentric latitude to geodetic latitude::
+
+    +proj=pipeline +step +proj=geoc +inv +ellps=GRS80
+
+Parameters
+################################################################################
+
+.. include:: ../options/ellps.rst
diff --git a/docs/source/operations/conversions/images/geocentric_latitude.svg b/docs/source/operations/conversions/images/geocentric_latitude.svg
diff --git a/docs/source/operations/conversions/index.rst b/docs/source/operations/conversions/index.rst
@@ -13,5 +13,6 @@ conversions.
 
    axisswap
    cart
+   geoc
    latlon
    unitconvert
diff --git a/docs/source/operations/projections/merc.rst b/docs/source/operations/projections/merc.rst
@@ -117,7 +117,7 @@ For the elliptical form of the projection we introduce the scaling factor:
 
 .. math::
 
-    k_0 = m\left( \phi_ts \right)
+    k_0 = m\left( \phi_{ts} \right)
 
 where :math:`m\left(\phi\right)` is the parallel radius at latitude :math:`\phi`.