Freeze hard-coded prime meridians and note they are no longer updated (…

…#4042) * Legacy hard-coded prime meridians are no longer updated * Expand docs for angular units, add another prime meridian example
OSGeo · Feb 15, 2024 · 6e0c182 · 6e0c182
1 parent 7e50b16
commit 6e0c182
Show file tree

Hide file tree

Showing 7 changed files with 60 additions and 19 deletions.
diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst
@@ -104,6 +104,12 @@ The following control parameters can appear in any order:
 
     List of all ellipsoids that can be selected with the *+ellps* parameters.
 
+.. option:: -lm
+
+    List of hard-coded prime meridians that can be selected with the *+pm*
+    parameter.  Note that this list is no longer updated,
+    and some values may conflict with other sources.
+
 .. option:: -lu
 
     List of all distance units that can be selected with the *+units* parameter.

diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst
@@ -608,7 +608,8 @@ List structures
 
 .. c:type:: PJ_PRIME_MERIDIANS
 
-    Prime meridians defined in PROJ.
+    Hard-coded prime meridians defined in PROJ. Note that the structure is
+    no longer updated, and some values may conflict with other sources.
 
     .. code-block:: C
 

diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst
@@ -667,7 +667,8 @@ Lists
 
 .. c:function:: const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void)
 
-    Get a pointer to an array of prime meridians defined in PROJ. The last
+    Get a pointer to an array of hard-coded prime meridians defined in PROJ.
+    Note that this list is no longer updated. The last
     entry of the returned array is a NULL-entry. The array is statically
     allocated and does not need to be freed after use.
 

diff --git a/docs/source/usage/projections.rst b/docs/source/usage/projections.rst
@@ -70,10 +70,10 @@ The returned coordinates are scaled by the value assigned with the ``+k_0``
 parameter. This parameter is only used by projections that mention using it,
 and its exact effect is projection dependent.
 
-Input units for angular parameters (``+lon_0``, ``+lat_0``, etc.) are
+Input units for angular parameters (``+lon_0``, ``+lat_0``, ``+pm``, etc.) are
 interpreted to be decimal degrees by convention.
 Explicit specification of input angular units can be accomplished by adding the
-appropriate ruffix to input values.
+appropriate suffix to input values.
 
 
     +----------------+---------------------+
@@ -90,10 +90,24 @@ appropriate ruffix to input values.
     | R              |                     |
     +----------------+---------------------+
 
+The sign of an angle is taken from either a ``-`` or ``+`` prefix,
+or the last character specifying a cardinal direction,
+where ``e``/``E`` (East) or ``n``/``N`` (North) are positive
+and ``w``/``W`` (West) or ``s``/``S`` (South) are negative.
+
 Example of use.  The longitude of the central meridian ``+lon_0=90``, can also be expressed more explicitly
 with units of decimal degrees as ``+lon_0=90d`` or in radian
 units as ``+lon_0=1.570796r`` (approximately).
 
+Angles can be expressed in DMS notation, using ``'`` after arcminutes
+and ``"`` after arcseconds, ending with optional cardinal direction.
+For example, ``+pm=3d41'14.55"W``, but
+character escapes ``+pm=3d41\'14.55\"W`` may be required.
+
+Degree-minute notation does not require any quotation symbols.
+All of these are equivalent values: ``+pm=-17d40``, ``+pm=17D40W``,
+``+pm=17°40w`` or ``+pm=17d40'W`` (escaped as ``+pm=17d40\'W``).
+
 
 False Easting/Northing
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -135,27 +149,28 @@ Note that ``+over`` does **not** disable ``+lon_wrap``.
 Prime Meridian
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-A prime meridian may be declared indicating the offset between the prime
-meridian of the declared coordinate system and that of greenwich.  A prime
-meridian is declared using the "pm" parameter, and may be assigned a symbolic
-name, or the longitude of the alternative prime meridian relative to greenwich.
+A prime meridian may be declared indicating the longitude offset between
+the prime meridian of the declared coordinate system and that of greenwich.
+A prime meridian is declared using the ``+pm`` parameter, and may be assigned
+an angle in DMS or decimal degrees format, or as a hard-coded name.
 
 Currently prime meridian declarations are not used by the ``pj_inv()`` and
 ``pj_fwd()`` calls.
 Consequently the user utility :program:`cs2cs` does honour prime meridians but
 the :program:`proj` user utility ignores them.
 
-The following predeclared prime meridian names are supported.  These can be
-listed using with ``cs2cs -lm``.
+Hard-coded prime meridians can be listed with ``cs2cs -lm``.
+Note that the following list is no longer updated, and some values
+may conflict with other sources.
 
  ===========     ================
  Meridian        Longitude
  ===========     ================
    greenwich     0dE
       lisbon     9d07'54.862"W
        paris     2d20'14.025"E
-      bogota     74d04'51.3"E
-      madrid     3d41'16.48"W
+      bogota     74d04'51.3"W
+      madrid     3d41'16.58"W
         rome     12d27'8.4"E
         bern     7d26'22.5"E
      jakarta     106d48'27.79"E
@@ -164,17 +179,27 @@ listed using with ``cs2cs -lm``.
    stockholm     18d3'29.8"E
       athens     23d42'58.815"E
         oslo     10d43'22.5"E
+  copenhagen     12d34'40.35"E
  ===========     ================
 
 Example of use.  The location ``long=0``, ``lat=0`` in the greenwich based lat/long
-coordinates is translated to lat/long coordinates with Madrid as the prime
+coordinates is translated to lat/long coordinates with Lisbon as the prime
 meridian.
 
 ::
 
-    cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid
+    cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=lisbon
     0 0
-    3d41'16.48"E    0dN 0.000
+    9d7'54.862"E	0dN 0.000
+
+Decimal degrees can also be simply specified for the prime meridian.
+
+::
+
+    echo 13d30E 45N | proj +proj=merc +pm=13.5
+    0.00    5591295.92
+
+See :ref:`projection_units` for other examples of angular inputs.
 
 
 Axis orientation

diff --git a/src/apps/cs2cs.cpp b/src/apps/cs2cs.cpp
@@ -580,8 +580,10 @@ int main(int argc, char **argv) {
                         }
                         proj_unit_list_destroy(units);
                     } else if (arg[1] == 'm') { /* list prime meridians */
+                        (void)fprintf(stderr,
+                            "This list is no longer updated, and some values may "
+                            "conflict with other sources.\n");
                         const struct PJ_PRIME_MERIDIANS *lpm;
-
                         for (lpm = proj_list_prime_meridians(); lpm->id; ++lpm)
                             (void)printf("%12s %-30s\n", lpm->id, lpm->defn);
                     } else

diff --git a/src/datums.cpp b/src/datums.cpp
@@ -63,14 +63,19 @@ static const struct PJ_DATUMS pj_datums[] = {
 
 const struct PJ_DATUMS *pj_get_datums_ref() { return pj_datums; }
 
+/*
+ * This list is no longer updated, and some values may conflict with
+ * other sources.
+ */
+
 static const struct PJ_PRIME_MERIDIANS pj_prime_meridians[] = {
     /* id        definition                         */
     /* --        ----------                         */
     {"greenwich", "0dE"},
     {"lisbon", "9d07'54.862\"W"},
     {"paris", "2d20'14.025\"E"},
     {"bogota", "74d04'51.3\"W"},
-    {"madrid", "3d41'16.58\"W"},
+    {"madrid", "3d41'16.58\"W"}, /* EPSG:8905 is 3d41'14.55"W */
     {"rome", "12d27'8.4\"E"},
     {"bern", "7d26'22.5\"E"},
     {"jakarta", "106d48'27.79\"E"},
@@ -79,7 +84,7 @@ static const struct PJ_PRIME_MERIDIANS pj_prime_meridians[] = {
     {"stockholm", "18d3'29.8\"E"},
     {"athens", "23d42'58.815\"E"},
     {"oslo", "10d43'22.5\"E"},
-    {"copenhagen", "12d34'40.35\"E"},
+    {"copenhagen", "12d34'40.35\"E"}, /* EPSG:1026 is 12d34'39.9"E */
     {nullptr, nullptr}};
 
 const PJ_PRIME_MERIDIANS *proj_list_prime_meridians(void) {

diff --git a/test/unit/gie_self_tests.cpp b/test/unit/gie_self_tests.cpp
@@ -644,7 +644,8 @@ TEST(gie, info_functions) {
     n = 0;
     for (pm_list = proj_list_prime_meridians(); pm_list->id; ++pm_list)
         n++;
-    ASSERT_NE(n, 0U);
+    /* hard-coded prime meridians are not updated; expect a fixed size */
+    EXPECT_EQ(n, 14U);
 }
 
 // ---------------------------------------------------------------------------