Add Orientation Index Viewer utility

[dr-jts]

The Point-Line Orientation geometric predicate is probably the most crucial algorithm in GEOS, since it is used in many other algorithms, and is notorious for causing robustness problems. GEOS has a high-quality implementation which continues to be improved (e.g. see #1184).

Even with a state-of-the-art robust implementation, the orientation predicate behaviour for floating-point inputs can be puzzling (e.g. see #1207, and extensive discussion on #1184). To assist in understanding its characteristics, and to allow confirming expected behaviour, this PR provides a utility to compute the orientation index for particular cases, and to visualize its behaviour.

GEOS Orientation Index Viewer
Usage: orientview [ flags ] x0 y0 x1 y1 x2 y2
  -f - use FP instead of DD orientation algorithm
  -g - show grid of nearby points
  -p - compute all permutations of points
  -v - show verbose detail for each point

Example

The case in #1207 can be visualized using:

orientview -g  0 2   2 0   0.4 1.6       

The output shows:

• the inexact approximation produced for (04, 1.6) in floating-point representation
• the difference in output between DD (robust) and FP orientation algorithms
• the behaviour of the DD algorithm in a neighbour around the test point

LINESTRING ( 0 2, 2 0 )
+ DD [ 0, 0 ]  POINT ( 0.4000000000000000222 1.6000000000000000888 ) -> 1
0 FP [ 0, 0 ]  POINT ( 0.4000000000000000222 1.6000000000000000888 ) -> 0

Orientation DD
Grid: (0.39999999999999891198 1.5999999999999956479 ) - (0.40000000000000113243 1.6000000000000045297 )
Size: dX = -5.5511151231257827021e-17  dy = -2.2204460492503130808e-16
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++
--0+++++++++++++++++++++++++++++++++++++++
------0+++++++++++++++++++++++++++++++++++
----------0+++++++++++++++++++++++++++++++
--------------0+++++++++++++++++++++++++++
------------------0+++++++++++++++++++++++
----------------------0+++++++++++++++++++
--------------------------0+++++++++++++++
------------------------------0+++++++++++
----------------------------------0+++++++
--------------------------------------0+++
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------
------------------------------------------

Permutations of Input

The viewer can compute all permutations of the three input points, to visualize whether the orientation computation is consistent. In the example case, this shows that the DD implementation is consistent, whereas the FP implementation is not.

orientview -p  0 2   2 0   0.4 1.6

LINESTRING ( 0 2, 2 0 )
+ DD [ 0, 0 ]  POINT ( 0.4000000000000000222 1.6000000000000000888 ) -> 1
0 FP [ 0, 0 ]  POINT ( 0.4000000000000000222 1.6000000000000000888 ) -> 0


LINESTRING ( 2 0, 0.4000000000000000222 1.6000000000000000888 )
+ DD [ 0, 0 ]  POINT ( 0 2 ) -> 1
+ FP [ 0, 0 ]  POINT ( 0 2 ) -> 1


LINESTRING ( 0.4000000000000000222 1.6000000000000000888, 0 2 )
+ DD [ 0, 0 ]  POINT ( 2 0 ) -> 1
+ FP [ 0, 0 ]  POINT ( 2 0 ) -> 1