Some improvements to the docs for tmerc and omerc (#1281)

3 files changed, 129 insertions, 5 deletions

diff --git a/docs/source/operations/projections/omerc.rst b/docs/source/operations/projections/omerc.rst
index 7131df62..ba2edf45 100644
--- a/docs/source/operations/projections/omerc.rst
+++ b/docs/source/operations/projections/omerc.rst
@@ -4,6 +4,27 @@
 Oblique Mercator
 ********************************************************************************
 
+The Oblique Mercator projection is a cylindrical map projection that closes the
+gap between the Mercator and the Transverse Mercator projections.
+
++---------------------+----------------------------------------------------------+
+| **Classification**  | Conformal cylindrical                                    |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical and elliptical projection |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global, but reasonably accurate only within 15 degrees   |
+|                     | of the oblique central line                              |
++---------------------+----------------------------------------------------------+
+| **Alias**           | omerc                                                    |
++---------------------+----------------------------------------------------------+
+| **Domain**          | 2D                                                       |
++---------------------+----------------------------------------------------------+
+| **Input type**      | Geodetic coordinates                                     |
++---------------------+----------------------------------------------------------+
+| **Output type**     | Projected coordinates                                    |
++---------------------+----------------------------------------------------------+
+
+
 .. figure:: ./images/omerc.png
    :width: 500 px
    :align: center
@@ -11,6 +32,77 @@ Oblique Mercator
 
    proj-string: ``+proj=omerc +lat_1=45 +lat_2=55``
 
+
+Figuratively, the cylinder used for developing the Mercator projection touches
+the planet along the Equator, while that of the Transverse Mercator touches the
+planet along a meridian, i.e. along a line perpendicular to the Equator.
+
+The cylinder for the Oblique Mercator, however, touches the planet along a line
+at an arbitrary angle with the Equator. Hence, the Oblique Mercator projection
+is useful for mapping areas having their greatest extent along a direction that
+is neither north-south, nor east-west.
+
+The Mercator and the Transverse Mercator projections are both limiting forms of
+the Oblique Mercator: The Mercator projection is equivalent to an Oblique Mercator
+with central line along the Equator, while the Transverse Mercator is equivalent
+to an Oblique Mercator with central line along a meridian.
+
+For the sphere, the construction of the Oblique Mercator projection can be
+imagined as "tilting the cylinder of a plain Mercator projection",
+so the cylinder, instead of touching the equator, touches an arbitrary great circle
+on the sphere. The great circle is defined by the tilt angle of the central line,
+hence putting land masses along that great circle near the centre of the map,
+where the Equator would go in the plain Mercator case.
+
+The ellipsoidal case, developed by Hotine, and refined by Snyder  :cite:`Snyder1987`
+is more complex, involving initial steps projecting from the ellipsoid to another
+curved surface, the "aposphere", then projection from the aposphere to the skew
+uv-plane, before finally rectifying the skew uv-plane onto the map XY plane.
+
+
+Usage
+########
+
+The tilt angle (azimuth) of the central line can be given in two different ways.
+In the first case, the azimuth is given directly, using the option :option:`+alpha`
+and defining the centre of projection using the options :option:`+lonc` and
+:option:`+lat_0`.
+In the second case, the azimuth is given indirectly by specifying two points on
+the central line, using the options
+:option:`+lat_1`, :option:`+lon_1`, :option:`+lat_2`, and :option:`+lon_2`.
+
+Example: Verify that the Mercator projection is a limiting form of the Oblique
+Mercator
+
+::
+
+    $ echo 12 55 | proj +proj=merc +ellps=GRS80
+    1335833.89   7326837.71
+
+    $ echo 12 55 | proj +proj=omerc +lonc=0 +alpha=90 +ellps=GRS80
+    1335833.89   7326837.71
+
+Example: Second case - indirectly given azimuth
+
+::
+
+    $ echo 12 55 | proj +proj=omerc +lon_1=-1 +lat_1=1 +lon_2=0 +lat_2=0 +ellps=GRS80
+      349567.57   6839490.50
+
+
+Example: An approximation of the Danish "System 34" from :cite:`Rittri2012`
+
+::
+
+    $ echo 10.536498003 56.229892362 | proj +proj=omerc +axis=wnu +lonc=9.46 +lat_0=56.13333333 +x_0=-266906.229 +y_0=189617.957 +k=0.9999537 +alpha=-0.76324 +gamma=0 +ellps=GRS80
+    200000.13   199999.89
+
+The input coordinate represents the System 34 datum point "Agri Bavnehoj", with coordinates
+(200000, 200000) by definition. So at the datum point, the approximation is off by about 17 cm.
+This use case represents a datum shift from a cylinder projection on an old, slightly
+misaligned datum, to a similar projection on a modern datum.
+
+
 Parameters
 ################################################################################
 
@@ -62,7 +154,11 @@ Optional
 
 .. option:: +no_rot
 
-    Do not rotate axis.
+    No rectification (not "no rotation" as one may well assume).
+    Do not take the last step from the skew uv-plane to the map
+    XY plane.
+    
+    .. note:: This option is probably only marginally useful, but remains for (mostly) historical reasons.
 
 .. option:: +no_off
 
diff --git a/docs/source/operations/projections/tmerc.rst b/docs/source/operations/projections/tmerc.rst
index fd600001..a52e4059 100644
--- a/docs/source/operations/projections/tmerc.rst
+++ b/docs/source/operations/projections/tmerc.rst
@@ -28,7 +28,7 @@ The transverse Mercator projection in its various forms is the most widely used
 .. figure:: ./images/tmerc.png
    :width: 500 px
    :align: center
-   :alt:   Transverse Mercator  
+   :alt:   Transverse Mercator
 
    proj-string: ``+proj=tmerc``
 
@@ -79,7 +79,9 @@ Parameters
 
     .. versionadded:: 6.0.0
 
-    Use faster, less accurate algorithm for the Transverse Mercator.
+    Use the algorithm described in section "Elliptical Form" below.
+    It is faster than the default algorithm, but also diverges faster
+    as the distance from the central meridian increases.
 
 .. include:: ../options/lon_0.rst
 
@@ -98,7 +100,7 @@ Parameters
 Mathematical definition
 #######################
 
-The formulas describing the Transverse Mercator are all taken from Evenden's [Evenden2005]_.
+The formulas describing the Transverse Mercator below are quoted from Evenden's [Evenden2005]_.
 
 :math:`\phi_0` is the latitude of origin that match the center of the map. It can be set with ``+lat_0``.
 
@@ -148,6 +150,11 @@ Inverse projection
 Elliptical form
 ***************
 
+The formulas below describe the algorithm used when giving the
+:option:`+approx` option. They are originally from :cite:`Snyder1987`,
+but here quoted from :cite:`Evenden1995`.
+The default algorithm is given by Poder and Engsager in :cite:`Poder1998`
+
 Forward projection
 ==================
 
@@ -169,7 +176,7 @@ Forward projection
 
 .. math::
 
-  x &= k_0 \lambda \cos \phi \\ 
+  x &= k_0 \lambda \cos \phi \\
     &+ \frac{k_0 \lambda^3 \cos^3\phi}{3!}(1-t^2+\eta^2) \\
     &+ \frac{k_0 \lambda^5 \cos^5\phi}{5!}(5-18t^2+t^4+14\eta^2-58t^2\eta^2) \\
     &+\frac{k_0 \lambda^7 \cos^7\phi}{7!}(61-479t^2+179t^4-t^6)
diff --git a/docs/source/references.bib b/docs/source/references.bib
index 8a0de291..df1dc66c 100644
--- a/docs/source/references.bib
+++ b/docs/source/references.bib
@@ -215,6 +215,20 @@
   Url                      = {https://archive.org/details/DTIC_ADA026294}
 }
 
+@techreport{Poder1998,
+  author       = {Knud Poder and Karsten Engsager},
+  year         = {1998},
+  title        = {Some Conformal Mappings and Transformations for Geodesy
+                  and Topographic Cartography},
+  address      = {Copenhagen, Denmark},
+  institution  = {National Survey and Cadastre},
+  type         = {National Survey and Cadastre Publications},
+  series       = {4},
+  volume       = {6},
+  isbn         = {87-7866-085-8},
+  pages        = {63}
+}
+
 @Article{Patterson2015,
   Title                    = {Introducing the Patterson Cylindrical Projection},
   Author                   = {Tom Patterson, Bojan Šavrič, Bernhard Jenny},
@@ -225,6 +239,13 @@
   Doi                      = {10.14714/CP78.1270}
 }
 
+@Misc{Rittri2012,
+    author = {Mikael Rittri},
+    title  = {New omerc approximations of Denmark System 34},
+    year   = {2012},
+    url    = {https://lists.osgeo.org/pipermail/proj/2012-June/005926.html}
+}
+
 @article{Ruffhead2016,
     author = {A. C. Ruffhead},
     title = {Introduction to multiple regression equations in datum transformations and their reversibility},