Transformation: no longer do vertical trasnformation when doing compound CRS to 2D CRS / add --3d to cs2cs

Previously, when computing transformation between a compound CRS and a
geographic/projected 2D CRS, the behaviour was similar to implicitly
promoting the 2D CRS to 3D CRS in the pipeline computation logic, hence
a geoid model could be applied. But note that when doing a geographic 3D
to geographic/projected 2D CRS transformation, we *did* not do this implicit
promotion and if a Helmert transformation existed between the datums, it
was done only in 2D. So this is a bit inconsistent and triggered the
comment in https://github.com/OSGeo/PROJ/issues/2318#issuecomment-1068924513

With this commit, we no longer do any vertical transformation when doing
compound CRS to the 2D CRS, but just take the transformation of the
horizontal part of the compound CRS to the 2D CRS.
Said otherwise, NAD83+NAVD88 to NAD83 will no longer lead to the
application of the geoid model. Unless you explicitly ask for the
promotion NAD83 to 3D.

Also related, in https://github.com/OSGeo/PROJ/issues/1563 that went to 6.3.0,
I changed cs2cs to automatically promote to 3D the CRS as soon as one of
them was compound, for the sake of being consistent with the past
behaviour. But it then becomes difficult to predict PROJ behaviour
depending on which level of it you consider...
This commit undoes that and adds an explicit --3d switch to cs2cs, similarly to
projinfo, to ask for promotion.

Other bug fix found in the process, when using legacy syntax, +init=epsg:4979,
(WGS 84 3D), the resulting CRS was 2D and not 3D.

2 files changed, 17 insertions, 6 deletions

diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst
index 841ce092..8f35c751 100644
--- a/docs/source/apps/cs2cs.rst
+++ b/docs/source/apps/cs2cs.rst
@@ -13,7 +13,7 @@ Synopsis
 
     | **cs2cs** [**-eEfIlrstvwW** [args]]
     |           [[--area <name_or_code>] | [--bbox <west_long,south_lat,east_long,north_lat>]]
-    |           [--authority <name>] [--no-ballpark] [--accuracy <accuracy>]
+    |           [--authority <name>] [--no-ballpark] [--accuracy <accuracy>] [--3d]
     |           ([*+opt[=arg]* ...] [+to *+opt[=arg]* ...] | {source_crs} {target_crs})
     |           file ...
 
@@ -194,6 +194,17 @@ The following control parameters can appear in any order:
 
     This option is mutually exclusive with :option:`--bbox`.
 
+.. option:: --3d
+
+    .. versionadded:: 9.1
+
+    "Promote" 2D CRS(s) to their 3D version, where the vertical axis is the
+    ellipsoidal height in metres, using the ellipsoid of the base geodetic CRS.
+    Depending on PROJ versions and the exact nature of the CRS involved,
+    especially before PROJ 9.1, a mix of 2D and 3D CRS could lead to 2D or 3D
+    transformations. Starting with PROJ 9.1, both CRS need to be 3D for vertical
+    transformation to possibly happen.
+
 .. only:: man
 
     The *+opt* run-line arguments are associated with cartographic
diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst
index 04ee7578..a19afa5b 100644
--- a/docs/source/apps/projinfo.rst
+++ b/docs/source/apps/projinfo.rst
@@ -300,12 +300,12 @@ The following control parameters can appear in any order:
 
     .. versionadded:: 6.3
 
-    "Promote" the CRS(s) to their 3D version. In the context of researching
-    available coordinate transformations, explicitly specifying this option is
-    not necessary, because when one of the source or target CRS has a vertical
-    component but not the other one, the one that has no vertical component is
-    automatically promoted to a 3D version, where its vertical axis is the
+    "Promote" 2D CRS(s) to their 3D version, where the vertical axis is the
     ellipsoidal height in metres, using the ellipsoid of the base geodetic CRS.
+    Depending on PROJ versions and the exact nature of the CRS involved,
+    especially before PROJ 9.1, a mix of 2D and 3D CRS could lead to 2D or 3D
+    transformations. Starting with PROJ 9.1, both CRS need to be 3D for vertical
+    transformation to possibly happen.
 
 .. option:: --output-id=AUTH:NAME