QGIS/python/core/geometry/qgsgeometryutils.sip

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/geometry/qgsgeometryutils.h                                 *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/






class QgsGeometryUtils
{
%Docstring
 Contains various geometry utility functions.

.. versionadded:: 2.10
%End

%TypeHeaderCode
#include "qgsgeometryutils.h"
%End
  public:

    static QVector<QgsLineString *> extractLineStrings( const QgsAbstractGeometry *geom ) /Factory/;
%Docstring
Returns list of linestrings extracted from the passed geometry. The returned objects
have to be deleted by the caller.
%End

    static QgsPoint closestVertex( const QgsAbstractGeometry &geom, const QgsPoint &pt, QgsVertexId &id /Out/ );
%Docstring
Returns the closest vertex to a geometry for a specified point.
On error null point will be returned and "id" argument will be invalid.
%End

    static QgsPoint closestPoint( const QgsAbstractGeometry &geometry, const QgsPoint &point );
%Docstring
Returns the nearest point on a segment of a ``geometry``
for the specified ``point``. The z and m values will be linearly interpolated between
the two neighbouring vertices.
%End

    static double distanceToVertex( const QgsAbstractGeometry &geom, QgsVertexId id );
%Docstring
Returns the distance along a geometry from its first vertex to the specified vertex.

:param geom: geometry
:param id: vertex id to find distance to

:return: distance to vertex (following geometry)

.. versionadded:: 2.16
%End

    static bool verticesAtDistance( const QgsAbstractGeometry &geometry,
                                    double distance,
                                    QgsVertexId &previousVertex /Out/,
                                    QgsVertexId &nextVertex /Out/ );
%Docstring
Retrieves the vertices which are before and after the interpolated point at a specified distance along a linestring
(or polygon boundary).

:param geometry: line or polygon geometry
:param distance: distance to traverse along geometry
:param previousVertex: will be set to previous vertex ID
:param nextVertex: will be set to next vertex ID

:return: true if vertices were successfully retrieved

.. note::

   if the distance coincides exactly with a vertex, then both previousVertex and nextVertex will be set to this vertex

.. versionadded:: 3.0
%End

    static double sqrDistance2D( const QgsPoint &pt1, const QgsPoint &pt2 );
%Docstring
Returns the squared 2D distance between two points.
%End

    static double sqrDistToLine( double ptX, double ptY, double x1, double y1, double x2, double y2, double &minDistX /Out/, double &minDistY /Out/, double epsilon );
%Docstring
Returns the squared distance between a point and a line.
%End

    static bool lineIntersection( const QgsPoint &p1, QgsVector v1, const QgsPoint &p2, QgsVector v2, QgsPoint &intersection /Out/ );
%Docstring
 Compute the intersection between two lines

:param p1: Point on the first line
:param v1: Direction vector of the first line
:param p2: Point on the second line
:param v2: Direction vector of the second line
:param intersection: Output parameter, the intersection point

:return: Whether the lines intersect
%End

    static bool segmentIntersection( const QgsPoint &p1, const QgsPoint &p2, const QgsPoint &q1, const QgsPoint &q2, QgsPoint &intersectionPoint /Out/, bool &isIntersection /Out/, const double tolerance = 1e-8, bool acceptImproperIntersection = false );
%Docstring
 Compute the intersection between two segments

:param p1: First segment start point
:param p2: First segment end point
:param q1: Second segment start point
:param q2: Second segment end point
:param intersectionPoint: Output parameter, the intersection point
:param isIntersection: Output parameter, return true if an intersection is found
:param tolerance: The tolerance to use
:param acceptImproperIntersection: By default, this method returns true only if segments have proper intersection. If set true, returns also true if segments have improper intersection (end of one segment on other segment ; continuous segments).

:return:  Whether the segments intersect
* Example:
\code{.py}
ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, 0 ), QgsPoint( 0, 1 ), QgsPoint( 1, 1 ), QgsPoint( 1, 0 ) )
ret[0], ret[1].asWkt(), ret[2]
# Whether the segments intersect, the intersection point, is intersect
# (False, 'Point (0 0)', False)
ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, 0 ), QgsPoint( 0, 5 ), QgsPoint( 0, 5 ), QgsPoint( 1, 5 ) )
ret[0], ret[1].asWkt(), ret[2]
# (False, 'Point (0 5)', True)
ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, 0 ), QgsPoint( 0, 5 ), QgsPoint( 0, 5 ), QgsPoint( 1, 5 ), acceptImproperIntersection=True )
ret[0], ret[1].asWkt(), ret[2]
# (True, 'Point (0 5)', True)
ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, 0 ), QgsPoint( 0, 5 ), QgsPoint( 0, 2 ), QgsPoint( 1, 5 ) )
ret[0], ret[1].asWkt(), ret[2]
# (False, 'Point (0 2)', True)
ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, 0 ), QgsPoint( 0, 5 ), QgsPoint( 0, 2 ), QgsPoint( 1, 5 ), acceptImproperIntersection=True )
ret[0], ret[1].asWkt(), ret[2]
# (True, 'Point (0 2)', True)
ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, -5 ), QgsPoint( 0, 5 ), QgsPoint( 2, 0 ), QgsPoint( -1, 0 ) )
ret[0], ret[1].asWkt(), ret[2]
# (True, 'Point (0 0)', True)
\endcode
%End

    static QgsPoint projPointOnSegment( const QgsPoint &p, const QgsPoint &s1, const QgsPoint &s2 );
%Docstring
 Project the point on a segment

:param p: The point
:param s1: The segment start point
:param s2: The segment end point

:return: The projection of the point on the segment
%End



    static int leftOfLine( double x, double y, double x1, double y1, double x2, double y2 );
%Docstring
Returns a value < 0 if the point (``x``, ``y``) is left of the line from (``x1``, ``y1``) -> ( ``x2``, ``y2``).
A positive return value indicates the point is to the right of the line.

If the return value is 0, then the test was unsuccessful (e.g. due to testing a point exactly
on the line, or exactly in line with the segment) and the result is undefined.
%End

    static QgsPoint pointOnLineWithDistance( const QgsPoint &startPoint, const QgsPoint &directionPoint, double distance );
%Docstring
Returns a point a specified distance toward a second point.
%End

    static double ccwAngle( double dy, double dx );
%Docstring
Returns the counter clockwise angle between a line with components dx, dy and the line with dx > 0 and dy = 0
%End

    static void circleCenterRadius( const QgsPoint &pt1, const QgsPoint &pt2, const QgsPoint &pt3, double &radius /Out/,
                                    double &centerX /Out/, double &centerY /Out/ );
%Docstring
Returns radius and center of the circle through pt1, pt2, pt3
%End

    static bool circleClockwise( double angle1, double angle2, double angle3 );
%Docstring
Returns true if circle is ordered clockwise
%End

    static bool circleAngleBetween( double angle, double angle1, double angle2, bool clockwise );
%Docstring
Returns true if, in a circle, angle is between angle1 and angle2
%End

    static bool angleOnCircle( double angle, double angle1, double angle2, double angle3 );
%Docstring
Returns true if an angle is between angle1 and angle3 on a circle described by
angle1, angle2 and angle3.
%End

    static double circleLength( double x1, double y1, double x2, double y2, double x3, double y3 );
%Docstring
Length of a circular string segment defined by pt1, pt2, pt3
%End

    static double sweepAngle( double centerX, double centerY, double x1, double y1, double x2, double y2, double x3, double y3 );
%Docstring
Calculates angle of a circular string part defined by pt1, pt2, pt3
%End

    static bool segmentMidPoint( const QgsPoint &p1, const QgsPoint &p2, QgsPoint &result /Out/, double radius, const QgsPoint &mousePos );
%Docstring
Calculates midpoint on circle passing through p1 and p2, closest to given coordinate
%End

    static double circleTangentDirection( const QgsPoint &tangentPoint, const QgsPoint &cp1, const QgsPoint &cp2, const QgsPoint &cp3 );
%Docstring
Calculates the direction angle of a circle tangent (clockwise from north in radians)
%End

    static void segmentizeArc( const QgsPoint &p1, const QgsPoint &p2, const QgsPoint &p3,
                               QVector<QgsPoint>  &points /Out/, double tolerance = M_PI_2 / 90,
                               QgsAbstractGeometry::SegmentationToleranceType toleranceType = QgsAbstractGeometry::MaximumAngle,
                               bool hasZ = false, bool hasM = false );
%Docstring
Convert circular arc defined by p1, p2, p3 (p1/p3 being start resp. end point, p2 lies on the arc) into a sequence of points.

.. versionadded:: 3.0
%End

    static int segmentSide( const QgsPoint &pt1, const QgsPoint &pt3, const QgsPoint &pt2 );
%Docstring
For line defined by points pt1 and pt3, find out on which side of the line is point pt3.
Returns -1 if pt3 on the left side, 1 if pt3 is on the right side or 0 if pt3 lies on the line.

.. versionadded:: 3.0
%End

    static double interpolateArcValue( double angle, double a1, double a2, double a3, double zm1, double zm2, double zm3 );
%Docstring
Interpolate a value at given angle on circular arc given values (zm1, zm2, zm3) at three different angles (a1, a2, a3).

.. versionadded:: 3.0
%End







    static double normalizedAngle( double angle );
%Docstring
Ensures that an angle is in the range 0 <= angle < 2 pi.

:param angle: angle in radians

:return: equivalent angle within the range [0, 2 pi)
%End

    static double lineAngle( double x1, double y1, double x2, double y2 );
%Docstring
Calculates the direction of line joining two points in radians, clockwise from the north direction.

:param x1: x-coordinate of line start
:param y1: y-coordinate of line start
:param x2: x-coordinate of line end
:param y2: y-coordinate of line end

:return: angle in radians. Returned value is undefined if start and end point are the same.
%End

    static double angleBetweenThreePoints( double x1, double y1, double x2, double y2,
                                           double x3, double y3 );
%Docstring
Calculates the angle between the lines AB and BC, where AB and BC described
by points a, b and b, c.

:param x1: x-coordinate of point a
:param y1: y-coordinate of point a
:param x2: x-coordinate of point b
:param y2: y-coordinate of point b
:param x3: x-coordinate of point c
:param y3: y-coordinate of point c

:return: angle between lines in radians. Returned value is undefined if two or more points are equal.
%End

    static double linePerpendicularAngle( double x1, double y1, double x2, double y2 );
%Docstring
Calculates the perpendicular angle to a line joining two points. Returned angle is in radians,
clockwise from the north direction.

:param x1: x-coordinate of line start
:param y1: y-coordinate of line start
:param x2: x-coordinate of line end
:param y2: y-coordinate of line end

:return: angle in radians. Returned value is undefined if start and end point are the same.
%End

    static double averageAngle( double x1, double y1, double x2, double y2, double x3, double y3 );
%Docstring
Angle between two linear segments
%End

    static double averageAngle( double a1, double a2 );
%Docstring
Averages two angles, correctly handling negative angles and ensuring the result is between 0 and 2 pi.

:param a1: first angle (in radians)
:param a2: second angle (in radians)

:return: average angle (in radians)
%End



    static QgsPoint midpoint( const QgsPoint &pt1, const QgsPoint &pt2 );
%Docstring
Returns a middle point between points pt1 and pt2.
Z value is computed if one of this point have Z.
M value is computed if one of this point have M.

:param pt1: first point.
:param pt2: second point.

:return: New point at middle between points pt1 and pt2.
* Example:
.. code-block:: python

       p = QgsPoint( 4, 6 ) # 2D point
       pr = midpoint ( p, QgsPoint( 2, 2 ) )
       # pr is a 2D point: 'Point (3 4)'
       pr = midpoint ( p, QgsPoint( QgsWkbTypes.PointZ, 2, 2, 2 ) )
       # pr is a 3D point: 'PointZ (3 4 1)'
       pr = midpoint ( p, QgsPoint( QgsWkbTypes.PointM, 2, 2, 0, 2 ) )
       # pr is a 3D point: 'PointM (3 4 1)'
       pr = midpoint ( p, QgsPoint( QgsWkbTypes.PointZM, 2, 2, 2, 2 ) )
       # pr is a 3D point: 'PointZM (3 4 1 1)'

.. versionadded:: 3.0
%End

    static double gradient( const QgsPoint &pt1, const QgsPoint &pt2 );
%Docstring
Return the gradient of a line defined by points ``pt1`` and ``pt2``.

:param pt1: first point.
:param pt2: second point.

:return: The gradient of this linear entity, or infinity if vertical

.. versionadded:: 3.0
%End

    static void coefficients( const QgsPoint &pt1, const QgsPoint &pt2,
                              double &a /Out/, double &b /Out/, double &c /Out/ );
%Docstring
Return the coefficients (a, b, c for equation "ax + by + c = 0") of a line defined by points ``pt1`` and ``pt2``.

:param pt1: first point.
:param pt2: second point.
:param a: Output parameter, a coefficient of the equation.
:param b: Output parameter, b coefficient of the equation.
:param c: Output parameter, c coefficient of the equation.

.. versionadded:: 3.0
%End

    static QgsLineString perpendicularSegment( const QgsPoint &p, const QgsPoint &s1, const QgsPoint &s2 );
%Docstring
 Create a perpendicular line segment from p to segment [s1, s2]

:param p: The point
:param s1: The segment start point
:param s2: The segment end point

:return: A line (segment) from p to perpendicular point on segment [s1, s2]
%End


};

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/geometry/qgsgeometryutils.h                                 *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/