Expose QgsGeometryUtils to python bindings

Has some handy functions and there's no strong reason anymore
why these shouldn't be part of stable API

Author: nyalldawson

python/core/core.sip

@@ -356,6 +356,7 @@
 %Include geometry/qgsgeometry.sip
 %Include geometry/qgsgeometrycollection.sip
 %Include geometry/qgsgeometryengine.sip
+%Include geometry/qgsgeometryutils.sip
 %Include geometry/qgslinestring.sip
 %Include geometry/qgsmulticurve.sip
 %Include geometry/qgsmultilinestring.sip

python/core/geometry/qgsgeometryutils.sip

@@ -0,0 +1,68 @@
+class QgsGeometryUtils
+{
+%TypeHeaderCode
+#include <qgsgeometryutils.h>
+%End
+
+  public:
+
+    static QList<QgsLineString*> extractLineStrings( const QgsAbstractGeometry* geom );
+
+    static QgsPointV2 closestVertex( const QgsAbstractGeometry& geom, const QgsPointV2& pt, QgsVertexId& id /Out/ );
+
+    static double distanceToVertex( const QgsAbstractGeometry& geom, QgsVertexId id );
+
+    static bool verticesAtDistance( const QgsAbstractGeometry& geometry,
+                                    double distance,
+                                    QgsVertexId& previousVertex /Out/,
+                                    QgsVertexId& nextVertex /Out/ );
+
+    static void adjacentVertices( const QgsAbstractGeometry& geom, QgsVertexId atVertex, QgsVertexId& beforeVertex /Out/, QgsVertexId& afterVertex /Out/ );
+
+    static double sqrDistance2D( const QgsPointV2& pt1, const QgsPointV2& pt2 );
+
+    static double sqrDistToLine( double ptX, double ptY, double x1, double y1, double x2, double y2, double& minDistX /Out/, double& minDistY /Out/, double epsilon );
+
+    static bool lineIntersection( const QgsPointV2& p1, QgsVector v, const QgsPointV2& q1, QgsVector w, QgsPointV2& inter /Out/ );
+
+    static bool segmentIntersection( const QgsPointV2 &p1, const QgsPointV2 &p2, const QgsPointV2 &q1, const QgsPointV2 &q2, QgsPointV2& inter /Out/, double tolerance );
+
+    static QgsPointV2 projPointOnSegment( const QgsPointV2& p, const QgsPointV2& s1, const QgsPointV2& s2 );
+
+    static double leftOfLine( double x, double y, double x1, double y1, double x2, double y2 );
+
+    static QgsPointV2 pointOnLineWithDistance( const QgsPointV2& startPoint, const QgsPointV2& directionPoint, double distance );
+
+    static double ccwAngle( double dy, double dx );
+
+    static void circleCenterRadius( const QgsPointV2& pt1, const QgsPointV2& pt2, const QgsPointV2& pt3, double& radius /Out/,
+                                    double& centerX /Out/, double& centerY /Out/ );
+
+    static bool circleClockwise( double angle1, double angle2, double angle3 );
+
+    static bool circleAngleBetween( double angle, double angle1, double angle2, bool clockwise );
+
+    static bool angleOnCircle( double angle, double angle1, double angle2, double angle3 );
+
+    static double circleLength( double x1, double y1, double x2, double y2, double x3, double y3 );
+
+    static double sweepAngle( double centerX, double centerY, double x1, double y1, double x2, double y2, double x3, double y3 );
+
+    static bool segmentMidPoint( const QgsPointV2& p1, const QgsPointV2& p2, QgsPointV2& result /Out/, double radius, const QgsPointV2& mousePos );
+
+    static double circleTangentDirection( const QgsPointV2& tangentPoint, const QgsPointV2& cp1, const QgsPointV2& cp2, const QgsPointV2& cp3 );
+
+    static double normalizedAngle( double angle );
+
+    static double lineAngle( double x1, double y1, double x2, double y2 );
+
+    static double angleBetweenThreePoints( double x1, double y1, double x2, double y2,
+                                           double x3, double y3 );
+
+    static double linePerpendicularAngle( double x1, double y1, double x2, double y2 );
+
+    static double averageAngle( double x1, double y1, double x2, double y2, double x3, double y3 );
+
+    static double averageAngle( double a1, double a2 );
+
+};

src/core/geometry/qgsgeometryutils.h

@@ -26,8 +26,6 @@ class QgsLineString;
  * \class QgsGeometryUtils
  * \brief Contains various geometry utility functions.
  * \note added in QGIS 2.10
- * \note this API is not considered stable and may change for 2.12
- * \note not available in Python bindings
  */
 class CORE_EXPORT QgsGeometryUtils
 {
@@ -116,6 +114,7 @@ class CORE_EXPORT QgsGeometryUtils
       return t < 0. ? s1 : t > 1. ? s2 : QgsPointV2( s1.x() + ( s2.x() - s1.x() ) * t, s1.y() + ( s2.y() - s1.y() ) * t );
     }
 
+    //! @note not available in Python bindings
     struct SelfIntersection
     {
       int segment1;
@@ -130,6 +129,7 @@ class CORE_EXPORT QgsGeometryUtils
      * @param ring The ring of the geometry part to check
      * @param tolerance The tolerance to use
      * @return The list of self intersections
+     * @note not available in Python bindings
      * @note added in QGIS 2.12
      */
     static QList<SelfIntersection> getSelfIntersections( const QgsAbstractGeometry* geom, int part, int ring, double tolerance );
@@ -172,17 +172,38 @@ class CORE_EXPORT QgsGeometryUtils
     static double circleTangentDirection( const QgsPointV2& tangentPoint, const QgsPointV2& cp1, const QgsPointV2& cp2, const QgsPointV2& cp3 );
 
     /** Returns a list of points contained in a WKT string.
+     * @note not available in Python bindings
      */
     static QgsPointSequence pointsFromWKT( const QString& wktCoordinateList, bool is3D, bool isMeasure );
-    //! Returns a LinearRing { uint32 numPoints; Point points[numPoints]; }
+
+    /**
+     * Returns a LinearRing { uint32 numPoints; Point points[numPoints]; }
+     * @note not available in Python bindings
+     */
     static void pointsToWKB( QgsWkbPtr &wkb, const QgsPointSequence &points, bool is3D, bool isMeasure );
-    //! Returns a WKT coordinate list
+
+    /**
+     * Returns a WKT coordinate list
+     * @note not available in Python bindings
+     */
     static QString pointsToWKT( const QgsPointSequence &points, int precision, bool is3D, bool isMeasure );
-    //! Returns a gml::coordinates DOM element
+
+    /**
+     * Returns a gml::coordinates DOM element.
+     * @note not available in Python bindings
+     */
     static QDomElement pointsToGML2( const QgsPointSequence &points, QDomDocument &doc, int precision, const QString& ns );
-    //! Returns a gml::posList DOM element
+
+    /**
+     * Returns a gml::posList DOM element.
+     * @note not available in Python bindings
+     */
     static QDomElement pointsToGML3( const QgsPointSequence &points, QDomDocument &doc, int precision, const QString& ns, bool is3D );
-    //! Returns a geoJSON coordinates string
+
+    /**
+     * Returns a geoJSON coordinates string.
+     * @note not available in Python bindings
+     */
     static QString pointsToJSON( const QgsPointSequence &points, int precision );
 
     /** Ensures that an angle is in the range 0 <= angle < 2 pi.
@@ -233,24 +254,30 @@ class CORE_EXPORT QgsGeometryUtils
      */
     static double averageAngle( double a1, double a2 );
 
-    /** Parses a WKT block of the format "TYPE( contents )" and returns a pair of geometry type to contents ("Pair(wkbType, "contents")")
+    /**
+     * Parses a WKT block of the format "TYPE( contents )" and returns a pair of geometry type to contents ("Pair(wkbType, "contents")")
+     * @note not available in Python bindings
      */
     static QPair<QgsWkbTypes::Type, QString> wktReadBlock( const QString& wkt );
 
-    /** Parses a WKT string and returns of list of blocks contained in the WKT.
+    /**
+     * Parses a WKT string and returns of list of blocks contained in the WKT.
      * @param wkt WKT string in the format "TYPE1 (contents1), TYPE2 (TYPE3 (contents3), TYPE4 (contents4))"
      * @param defaultType default geometry type for children
      * @returns list of WKT child block strings, e.g., List("TYPE1 (contents1)", "TYPE2 (TYPE3 (contents3), TYPE4 (contents4))")
+     * @note not available in Python bindings
      */
     static QStringList wktGetChildBlocks( const QString& wkt , const QString &defaultType = "" );
 
+    //! @note not available in Python bindings
     enum ComponentType
     {
       Vertex,
       Ring,
       Part
     };
 
+    //! @note not available in Python bindings
     template<class T> static double closestSegmentFromComponents( T& container, ComponentType ctype, const QgsPointV2& pt, QgsPointV2& segmentPt,  QgsVertexId& vertexAfter, bool* leftOf, double epsilon )
     {
       double minDist = std::numeric_limits<double>::max();