Doc: add page for geoc conversion (fixes #1092)

6 files changed, 308 insertions, 5 deletions

diff --git a/docs/source/operations/conversions/cart.rst b/docs/source/operations/conversions/cart.rst
index 82a9a0ee..83328fa8 100644
--- 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
new file mode 100644
index 00000000..a9be2dfb
--- /dev/null
+++ 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.png
+   :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.png b/docs/source/operations/conversions/images/geocentric_latitude.png
new file mode 100644
index 00000000..059c4c0e
--- /dev/null
+++ b/docs/source/operations/conversions/images/geocentric_latitude.png
diff --git a/docs/source/operations/conversions/images/geocentric_latitude.svg b/docs/source/operations/conversions/images/geocentric_latitude.svg
new file mode 100644
index 00000000..2525e69d
--- /dev/null
+++ b/docs/source/operations/conversions/images/geocentric_latitude.svg
@@ -0,0 +1,222 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="140mm"
+   height="80mm"
+   viewBox="0 0 496.06299 283.46457"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.91 r13725"
+   sodipodi:docname="geocentric_latitude.svg"
+   inkscape:export-filename="/home/even/geocentric_latitude.png"
+   inkscape:export-xdpi="90"
+   inkscape:export-ydpi="90">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.4"
+     inkscape:cx="-24.364532"
+     inkscape:cy="179.59147"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1920"
+     inkscape:window-height="1004"
+     inkscape:window-x="0"
+     inkscape:window-y="24"
+     inkscape:window-maximized="1"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Calque 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-147.57144,-187.04048)">
+    <ellipse
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="path3336"
+       cx="360"
+       cy="335.21933"
+       rx="210"
+       ry="118.57143" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 150.01742,328.40826 419.30163,-0.75019"
+       id="path3338"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.96771652px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 363.32468,217.04313 0.16174,236.75597"
+       id="path3340"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 362.28019,328.82684 500.94901,247.46623"
+       id="path3342"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 444.633,218.67689 110.86424,56.316"
+       id="path3346"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 458.01752,327.77337 70.2056,-130.05715"
+       id="path3348"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 504.232,242.92055 5.05076,2.27284 -2.77792,4.79823"
+       id="path3350"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 478.21428,328.07649 c 0,0 3.34873,-9.57295 -10.49045,-17.89492"
+       id="path4172"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.71625429px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 381.31112,328.6754 c 0,0 1.06694,-7.99101 -5.65105,-7.9116"
+       id="path4172-3"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 468.62412,315.90407 -0.75761,-5.55584 5.80838,-0.25253"
+       id="path4189"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 376.70024,324.23783 0.25254,-3.78807 5.3033,-0.25254"
+       id="path4191"
+       inkscape:connector-curvature="0" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="458.19504"
+       y="341.07974"
+       id="text4193"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4195"
+         x="458.19504"
+         y="341.07974">Geodetic</tspan><tspan
+         sodipodi:role="line"
+         x="458.19504"
+         y="356.70474"
+         id="tspan4197">latitude</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:15px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="366.77863"
+       y="341.95016"
+       id="text4193-6"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4195-7"
+         x="366.77863"
+         y="341.95016"
+         style="font-size:12.5px">Geocentric</tspan><tspan
+         sodipodi:role="line"
+         x="366.77863"
+         y="357.57516"
+         id="tspan4197-5"
+         style="font-size:12.5px">latitude</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:15px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="478.72565"
+       y="317.92438"
+       id="text4220"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4222"
+         x="478.72565"
+         y="317.92438">φ</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:15px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="394.50311"
+       y="322.51547"
+       id="text4220-3"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4222-5"
+         x="394.50311"
+         y="322.51547">φ'</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="159.38527"
+       y="340.53079"
+       id="text4193-62"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         x="159.38527"
+         y="340.53079"
+         id="tspan4197-1">Equatorial plane</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="331.11118"
+       y="209.21098"
+       id="text4193-62-2"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         x="331.11118"
+         y="209.21098"
+         id="tspan4197-1-0">North pole</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:10px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="526.23138"
+       y="211.77133"
+       id="text4193-62-9"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         x="526.23138"
+         y="211.77133"
+         id="tspan4197-1-3">Normal to</tspan><tspan
+         sodipodi:role="line"
+         x="526.23138"
+         y="224.27133"
+         id="tspan4306">the ellipsoid</tspan><tspan
+         sodipodi:role="line"
+         x="526.23138"
+         y="236.77133"
+         id="tspan4308">surface</tspan></text>
+  </g>
+</svg>
diff --git a/docs/source/operations/conversions/index.rst b/docs/source/operations/conversions/index.rst
index 7d088509..6dfc0be3 100644
--- 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
index 349de216..8fab636d 100644
--- 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`.