[PostGIS] #5882: ST_DistanceCPA example shows output of 2D distance. Implementation returns 3D distance.

[PostGIS]

#5882: ST_DistanceCPA example shows output of 2D distance. Implementation returns
3D distance.
---------------------------+---------------------------
 Reporter:  siggyf         |      Owner:  robe
     Type:  defect         |     Status:  new
 Priority:  medium         |  Milestone:  PostGIS 3.5.3
Component:  documentation  |    Version:  3.4.x
 Keywords:  CPA            |
---------------------------+---------------------------
 There is an example that computes the closest point of approach between
 two trajectories. The example is listed at [1] and involves calling the
 function:

 `ST_DistanceCPA(a,b)`

 The example states that the result is `1.96036833151395`.
 The actual result that I get is `1.965214737762069`.

 I get the actual result by pasting the  example code listed at the line
 below [2] into postgis 3.5.2 with postgresql 16.8. I have also
 reimplemented the same routine in python. There I get `1.965214737762069`
 for 3D distances and `1.96036833151395` for 2D using the example
 trajectories.

 There are two other places where the same function is called [3] and [4].

 The three examples that I found are the following:

 - [1] -> `1.96036833151395` `ST_DistanceCPA`, I think this is incorrect,
 because I expect the 3D distance. Documentation states "This function
 supports 3d and will not drop the z-index."
 - [3] -> `1.965214737762069` `ST_DistanceCPA`, Here the correct 3D result
 is shown.
 - [4] -> `1.9603683315139542` `ST_Distance`, Here the points are found
 using interpolation of time. Here the 2D distance function is called, so
 1.960 is expected. For consistency with [3] ST_Distance could be replaced
 with ST_3DDistance, which would give 1.965.

 Because the CPA concept is also used in 3D (underwater uav's, distance
 between planes) returning 3D distance seems intuitive.

 Code of the corresponding algorithm is found in lwgeom [5].

 - [1] https://postgis.net/docs/ST_DistanceCPA.html
 - [2]
 https://github.com/postgis/postgis/blob/d8c2e69f33458eaf3200e850f58a6d8f7cc0c554/doc/reference_trajectory.xml#L195
 - [3] https://postgis.net/docs/ST_CPAWithin.html
 - [4] https://postgis.net/docs/ST_ClosestPointOfApproach.html
 - [5]
 https://github.com/postgis/postgis/blob/master/liblwgeom/lwlinearreferencing.c#L1138
-- 
Ticket URL: <https://trac.osgeo.org/postgis/ticket/5882>
PostGIS <http://trac.osgeo.org/postgis/>
The PostGIS Trac is used for bug, enhancement & task tracking, a user and developer wiki, and a view into the subversion code repository of PostGIS project.