Add Tobler-Mercator projection

10 files changed, 244 insertions, 1 deletions

diff --git a/docs/plot/plotdefs.json b/docs/plot/plotdefs.json
index 9ce9ed88..daaf2ef8 100644
--- a/docs/plot/plotdefs.json
+++ b/docs/plot/plotdefs.json
@@ -1255,6 +1255,17 @@
         "type": "poly"
     },
     {
+        "filename": "tobmerc.png",
+        "latmax": 80,
+        "latmin": -80,
+        "lonmax": 180,
+        "lonmin": -180,
+        "name": "tobmerc",
+        "projstring": "+proj=tobmerc",
+        "res": "low",
+        "type": "poly"
+    },
+    {
         "filename": "tpeqd.png",
         "latmax": 90,
         "latmin": -90,
diff --git a/docs/source/operations/projections/images/tobmerc.png b/docs/source/operations/projections/images/tobmerc.png
new file mode 100644
index 00000000..291bdac9
--- /dev/null
+++ b/docs/source/operations/projections/images/tobmerc.png
diff --git a/docs/source/operations/projections/index.rst b/docs/source/operations/projections/index.rst
index c2d24449..572deb1a 100644
--- a/docs/source/operations/projections/index.rst
+++ b/docs/source/operations/projections/index.rst
@@ -125,6 +125,7 @@ Projections map the spherical 3D space to a flat 2D space.
    tcea
    tissot
    tmerc
+   tobmerc
    tpeqd
    tpers
    ups
diff --git a/docs/source/operations/projections/tobmerc.rst b/docs/source/operations/projections/tobmerc.rst
new file mode 100644
index 00000000..d9a3eb05
--- /dev/null
+++ b/docs/source/operations/projections/tobmerc.rst
@@ -0,0 +1,100 @@
+.. _tobmerc:
+
+********************************************************************************
+Tobler-Mercator
+********************************************************************************
+
+.. versionadded:: 6.0.0
+
+Equal area cylindrical projection with the same latitudinal spacing as
+Mercator projection.
+
++---------------------+----------------------------------------------------------+
+| **Classification**  | Cylindrical equal area                                   |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical only                      |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global, conventionally truncated at about 80 degrees     |
+|                     | north and south                                          |
++---------------------+----------------------------------------------------------+
+| **Alias**           | tobmerc                                                  |
++---------------------+----------------------------------------------------------+
+| **Domain**          | 2D                                                       |
++---------------------+----------------------------------------------------------+
+| **Input type**      | Geodetic coordinates                                     |
++---------------------+----------------------------------------------------------+
+| **Output type**     | Projected coordinates                                    |
++---------------------+----------------------------------------------------------+
+
+.. figure:: ./images/tobmerc.png
+   :width: 500 px
+   :align: center
+   :alt:   Tobler-Mercator
+
+   proj-string: ``+proj=tobmerc``
+
+Usage
+#####
+
+The inappropriate use of the Mercator projection has declined but still
+occasionally occurs. One method of contrasting the Mercator projection is to
+present an alternative in the form of an equal area projection. The map
+projection derived here is thus not simply a pretty Christmas tree ornament:
+it is instead a complement to Mercator's conformal navigation anamorphose
+and can be displayed as an alternative. The equations for the new map
+projection preserve the latitudinal stretching of the Mercator while
+adjusting the longitudinal spacing. This allows placement of the new map
+adjacent to that of Mercator. The surface area, while drastically warped,
+maintains the correct magnitude.
+
+Parameters
+################################################################################
+
+.. note:: All parameters for the projection are optional.
+
+.. include:: ../options/k_0.rst
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst
+
+.. include:: ../options/R.rst
+
+Mathematical definition
+#######################
+
+The formulas describing the Tobler-Mercator are taken from Waldo Tobler's
+article :cite:`Tobler2017`
+
+Spherical form
+**************
+For the spherical form of the projection we introduce the scaling factor:
+
+.. math::
+
+    k_0 = \cos^2 \phi_{ts}
+
+Forward projection
+==================
+
+.. math::
+
+    x = k_0 \lambda
+
+.. math::
+
+    y = k_0 \ln \left[ \tan \left(\frac{\pi}{4} + \frac{\phi}{2} \right) \right]
+
+
+Inverse projection
+==================
+
+.. math::
+
+    \lambda = \frac{x}{k_0}
+
+.. math::
+
+    \phi = \frac{\pi}{2} - 2 \arctan \left[ e^{-y/k_0} \right]
diff --git a/docs/source/references.bib b/docs/source/references.bib
index 0fb077ec..73898148 100644
--- a/docs/source/references.bib
+++ b/docs/source/references.bib
@@ -247,6 +247,18 @@
   Edition                  = {15th}
 }
 
+@Article{Tobler2017,
+  Author                   = {W. Tobler},
+  Title                    = {A new companion for Mercator},
+  Journal                  = {Cartography and Geographic Information Science},
+  Volume                   = {45},
+  Number                   = {3},
+  Pages                    = {284-285},
+  Publisher                = {Taylor & Francis},
+  Year                     = {2017},
+  Doi                      = {10.1080/15230406.2017.1308837},
+}
+
 @Article{Verey2017,
   Title                    = {Theoretical analysis and practical consequences of adopting a model {ATPOL} grid as a conical projection defining the conversion of plane coordinates to the {WGS} 84 ellipsoid},
   Author                   = {M. Verey},
diff --git a/src/Makefile.am b/src/Makefile.am
index eaf6bd38..359f2f28 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -53,7 +53,7 @@ libproj_la_SOURCES = \
 	PJ_cass.c PJ_cc.c PJ_cea.c PJ_eqc.c PJ_gall.c PJ_geoc.c \
 	PJ_labrd.c PJ_lsat.c PJ_misrsom.c PJ_merc.c \
 	PJ_mill.c PJ_ocea.c PJ_omerc.c PJ_somerc.c \
-	PJ_tcc.c PJ_tcea.c PJ_times.c PJ_tmerc.c \
+	PJ_tcc.c PJ_tcea.c PJ_times.c PJ_tmerc.c PJ_tobmerc.c \
 	PJ_airy.c PJ_aitoff.c PJ_august.c PJ_bacon.c \
 	PJ_bertin1953.c PJ_chamb.c PJ_hammer.c PJ_lagrng.c PJ_larr.c \
 	PJ_lask.c PJ_latlong.c PJ_nocol.c PJ_ob_tran.c PJ_oea.c \
diff --git a/src/PJ_tobmerc.c b/src/PJ_tobmerc.c
new file mode 100644
index 00000000..9c939f0b
--- /dev/null
+++ b/src/PJ_tobmerc.c
@@ -0,0 +1,51 @@
+#define PJ_LIB__
+
+#include <float.h>
+#include <math.h>
+
+#include "proj_internal.h"
+#include "proj.h"
+#include "proj_math.h"
+#include "projects.h"
+
+PROJ_HEAD(tobmerc, "Tobler-Mercator") "\n\tCyl, Sph";
+
+#define EPS10 1.e-10
+static double logtanpfpim1(double x) {       /* log(tan(x/2 + M_FORTPI)) */
+    if (fabs(x) <= DBL_EPSILON) {
+        /* tan(M_FORTPI + .5 * x) can be approximated by  1.0 + x */
+        return log1p(x);
+    }
+    return log(tan(M_FORTPI + .5 * x));
+}
+
+static XY s_forward (LP lp, PJ *P) {           /* Spheroidal, forward */
+    XY xy = {0.0, 0.0};
+    double cosphi;
+
+    if (fabs(fabs(lp.phi) - M_HALFPI) <= EPS10) {
+        proj_errno_set(P, PJD_ERR_TOLERANCE_CONDITION);
+        return xy;
+    }
+
+    cosphi = cos(lp.phi);
+    xy.x = P->k0 * lp.lam * cosphi * cosphi;
+    xy.y = P->k0 * logtanpfpim1(lp.phi);
+    return xy;
+}
+
+static LP s_inverse (XY xy, PJ *P) {           /* Spheroidal, inverse */
+    LP lp = {0.0, 0.0};
+    double cosphi;
+
+    lp.phi = atan(sinh(xy.y / P->k0));
+    cosphi = cos(lp.phi);
+    lp.lam = xy.x / P->k0 / (cosphi * cosphi);
+    return lp;
+}
+
+PJ *PROJECTION(tobmerc) {
+    P->inv = s_inverse;
+    P->fwd = s_forward;
+    return P;
+}
diff --git a/src/lib_proj.cmake b/src/lib_proj.cmake
index 3e1a17ad..6a287a43 100644
--- a/src/lib_proj.cmake
+++ b/src/lib_proj.cmake
@@ -141,6 +141,7 @@ SET(SRC_LIBPROJ_PJ
         PJ_tcea.c
         PJ_times.c
         PJ_tmerc.c
+        PJ_tobmerc.c
         PJ_tpeqd.c
         PJ_unitconvert.c
         PJ_urm5.c
diff --git a/src/pj_list.h b/src/pj_list.h
index cd19d300..8c72dd1f 100644
--- a/src/pj_list.h
+++ b/src/pj_list.h
@@ -140,6 +140,7 @@ PROJ_HEAD(tcea, "Transverse Cylindrical Equal Area")
 PROJ_HEAD(times, "Times Projection")
 PROJ_HEAD(tissot, "Tissot Conic")
 PROJ_HEAD(tmerc, "Transverse Mercator")
+PROJ_HEAD(tobmerc, "Tobler-Mercator")
 PROJ_HEAD(tpeqd, "Two Point Equidistant")
 PROJ_HEAD(tpers, "Tilted perspective")
 PROJ_HEAD(unitconvert, "Unit conversion")
diff --git a/test/gie/builtins.gie b/test/gie/builtins.gie
index 955b5b51..f4e15a77 100644
--- a/test/gie/builtins.gie
+++ b/test/gie/builtins.gie
@@ -4897,6 +4897,72 @@ expect  -0.001790493 0.000895247
 accept  -200 -100
 expect  -0.001790493 -0.000895247
 
+===============================================================================
+Tobler-Mercator
+	Cyl, Sph
+===============================================================================
+
+-------------------------------------------------------------------------------
+operation +proj=tobmerc +ellps=sphere
+-------------------------------------------------------------------------------
+tolerance 0.1 mm
+accept  2 1
+expect  222322.011656333081 111200.520030584055
+accept  2 -1
+expect  222322.011656333081 -111200.520030584463
+accept  -2 1
+expect  -222322.011656333081 111200.520030584055
+accept  -2 -1
+expect  -222322.011656333081 -111200.520030584463
+
+accept  2 75
+expect  14897.288383530242 12917766.123520378023
+accept  2 80
+expect  6705.871450149517 15521316.299485698342
+accept  -2 -75
+expect  -14897.288383530242 -12917766.123520381749
+accept  -2 -80
+expect  -6705.871450149517 -15521316.299485692754
+
+direction inverse
+accept  200 100
+expect  0.001798644059 0.000899322029
+accept  200 -100
+expect  0.001798644059 -0.000899322029
+accept  -200 100
+expect  -0.001798644059 0.000899322029
+accept  -200 -100
+expect  -0.001798644059 -0.000899322029
+
+accept  14897.288383530242 12917766.123520378023
+expect  2 75
+accept  6705.871450149517 15521316.299485698342
+expect  2 80
+accept  -14897.288383530242 -12917766.123520381749
+expect  -2 -75
+accept  -6705.871450149517 -15521316.299485692754
+expect  -2 -80
+
+-------------------------------------------------------------------------------
+operation +proj=tobmerc +R=1
+-------------------------------------------------------------------------------
+Test the numerical stability of the inverse spherical Tobler-Mercator
+-------------------------------------------------------------------------------
+tolerance   1e-15 m
+accept  0   1e-15
+expect  0   1e-15
+
+-------------------------------------------------------------------------------
+operation +proj=tobmerc +ellps=sphere
+-------------------------------------------------------------------------------
+Test expected failure at the poles:
+-------------------------------------------------------------------------------
+accept  0 90
+expect  failure errno tolerance_condition
+
+accept  0 -90
+expect  failure errno tolerance_condition
+
 
 ===============================================================================
 Two Point Equidistant