From 6e0c18253717237fa055193fe00cb7f0700768b8 Mon Sep 17 00:00:00 2001 From: Mike Taves Date: Fri, 16 Feb 2024 09:18:43 +1300 Subject: [PATCH] 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 --- docs/source/apps/cs2cs.rst | 6 +++ .../development/reference/datatypes.rst | 3 +- .../development/reference/functions.rst | 3 +- docs/source/usage/projections.rst | 51 ++++++++++++++----- src/apps/cs2cs.cpp | 4 +- src/datums.cpp | 9 +++- test/unit/gie_self_tests.cpp | 3 +- 7 files changed, 60 insertions(+), 19 deletions(-) diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst index 4e6221dcbb..0f565d4bb1 100644 --- 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 index e8c3cd1e94..b362199eb2 100644 --- 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 index 8eea1abcd4..e7e9f6b807 100644 --- 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 index c571dc5bd4..bc0a32f0d3 100644 --- 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,18 +149,19 @@ 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 @@ -154,8 +169,8 @@ listed using with ``cs2cs -lm``. 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 index b6a1ed123b..8c91b683e3 100644 --- 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 index 7ab574cef1..b753ffb0f4 100644 --- a/src/datums.cpp +++ b/src/datums.cpp @@ -63,6 +63,11 @@ 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 */ /* -- ---------- */ @@ -70,7 +75,7 @@ static const struct PJ_PRIME_MERIDIANS pj_prime_meridians[] = { {"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 index 6650126068..a378520fca 100644 --- 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); } // ---------------------------------------------------------------------------