[geos-commits] [SCM] GEOS branch master updated. baa5f0cae661136dfa03ee3ef5ea93ccf7959192

[git at osgeo.org]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GEOS".

The branch, master has been updated
       via  baa5f0cae661136dfa03ee3ef5ea93ccf7959192 (commit)
      from  21c88492fd359612add729d09fdb45dd1bf7dd0d (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit baa5f0cae661136dfa03ee3ef5ea93ccf7959192
Author: Paul Ramsey <pramsey at cleverelephant.ca>
Date:   Tue Dec 18 09:13:48 2018 -0800

    Add some doco
    JTS 7a4b7367fd63f545c3ead99583669ab2fbd21676

diff --git a/include/geos/algorithm/Orientation.h b/include/geos/algorithm/Orientation.h
index e0ac45b..d051da2 100644
--- a/include/geos/algorithm/Orientation.h
+++ b/include/geos/algorithm/Orientation.h
@@ -27,7 +27,15 @@ namespace geos {
 namespace algorithm { // geos::algorithm
 
 /**
-* Functions to compute the orientation of points, lines and rings.
+* Functions to compute the orientation of basic geometric structures
+* including point triplets (triangles) and rings.
+* Orientation is a fundamental property of planar geometries
+* (and more generally geometry on two-dimensional manifolds).
+*
+* Orientation is notoriously subject to numerical precision errors
+* in the case of collinear or nearly collinear points.
+* JTS uses extended-precision arithmetic to increase
+* the robustness of the computation.
 *
 * @author Martin Davis
 *
@@ -46,16 +54,15 @@ public:
     };
 
     /*
-    * Returns the index of the direction of the point <code>q</code>
-    * relative to a vector specified by <code>p1-p2</code>.
-    *
-    * @param p1 the origin point of the vector
-    * @param p2 the final point of the vector
-    * @param q the point to compute the direction to
-    *
-    * @return 1 if q is counter-clockwise (left) from p1-p2
-    * @return -1 if q is clockwise (right) from p1-p2
-    * @return 0 if q is collinear with p1-p2
+    * Returns the orientation index of the direction of the point q relative to
+    * a directed infinite line specified by p1-p2.
+    * The index indicates whether the point lies to the
+    * {@link #Orientation::LEFT} or {@link #Orientation::RIGHT}
+    * of the line, or lies on it {@link #Orientation::COLLINEAR}.
+    * The index also indicates the orientation of the triangle formed
+    * by the three points
+    * ( {@link #Orientation::COUNTERCLOCKWISE},
+    * {@link #Orientation::CLOCKWISE}, or {@link #Orientation::STRAIGHT} )
     */
     static int index(const geom::Coordinate &p1,
                      const geom::Coordinate &p2, const geom::Coordinate &q);
@@ -63,11 +70,11 @@ public:
     /**
     * Computes whether a ring defined by an array of {@link Coordinate}s is
     * oriented counter-clockwise.
-    * <ul>
-    * <li>The list of points is assumed to have the first and last points equal.
-    * <li>This will handle coordinate lists which contain repeated points.
-    * </ul>
-    * This algorithm is <b>only</b> guaranteed to work with valid rings. If the
+    *
+    * - The list of points is assumed to have the first and last points equal.
+    * - This will handle coordinate lists which contain repeated points.
+    *
+    * This algorithm is *only<* guaranteed to work with valid rings. If the
     * ring is invalid (e.g. self-crosses or touches), the computed result may not
     * be correct.
     *

-----------------------------------------------------------------------

Summary of changes:
 include/geos/algorithm/Orientation.h | 39 +++++++++++++++++++++---------------
 1 file changed, 23 insertions(+), 16 deletions(-)


hooks/post-receive
-- 
GEOS