QGIS/python/core/geometry/qgsgeometryutils.sip.in

/************************************************************************
 * 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
Computes the intersection between two lines. Z dimension is
supported and is retrieved from the first 3D point amongst ``p1`` and
``p2``.

: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-block:: python

       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)
%End

    static bool lineCircleIntersection( const QgsPointXY &center, const double radius,
                                        const QgsPointXY &linePoint1, const QgsPointXY &linePoint2,
                                        QgsPointXY &intersection /In,Out/ );
%Docstring
 Compute the intersection of a line and a circle.
If the intersection has two solutions (points),
the closest point to the initial ``intersection`` point is returned.
@param center the center of the circle
@param radius the radius of the circle
@param linePoint1 a first point on the line
@param linePoint2 a second point on the line
@param intersection the initial point and the returned intersection point
@return true if an intersection has been found
%End

    static int circleCircleIntersections( QgsPointXY center1, double radius1,
                                          QgsPointXY center2, double radius2,
                                          QgsPointXY &intersection1, QgsPointXY &intersection2 );
%Docstring
Calculates the intersections points between the circle with center ``center1`` and
radius ``radius1`` and the circle with center ``center2`` and radius ``radius2``.

If found, the intersection points will be stored in ``intersection1`` and ``intersection2``.

:return: number of intersection points found.

.. versionadded:: 3.2
%End

    static bool tangentPointAndCircle( const QgsPointXY &center, double radius,
                                       const QgsPointXY &p, QgsPointXY &pt1, QgsPointXY &pt2 );
%Docstring
Calculates the tangent points between the circle with the specified ``center`` and ``radius``
and the point ``p``.

If found, the tangent points will be stored in ``pt1`` and ``pt2``.

.. versionadded:: 3.2
%End

    static int circleCircleOuterTangents(
      const QgsPointXY &center1, double radius1, const QgsPointXY &center2, double radius2,
      QgsPointXY &line1P1, QgsPointXY &line1P2,
      QgsPointXY &line2P1, QgsPointXY &line2P2 );
%Docstring
Calculates the outer tangent points for two circles, centered at ``center1`` and
``center2`` and with radii of ``radius1`` and ``radius2`` respectively.

The outer tangent points correspond to the points at which the two lines
which are drawn so that they are tangential to both circles touch
the circles.

The first tangent line is described by the points
stored in ``line1P1`` and ``line1P2``,
and the second line is described by the points stored in ``line2P1``
and ``line2P2``.

Returns the number of tangents (either 0 or 2).

.. versionadded:: 3.2
%End

    static QgsPoint projectPointOnSegment( 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. Z dimension is supported and is retrieved from the
first 3D point amongst ``p1`` and ``p2``.
%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

    static bool setZValueFromPoints( const QgsPointSequence &points, QgsPoint &point );
%Docstring
A Z dimension is added to ``point`` if one of the point in the list
``points`` is in 3D. Moreover, the Z value of ``point`` is updated with.

:param points: List of points in which a 3D point is searched.
:param point: The point to update with Z dimension and value.

:return: true if the point is updated, false otherwise

.. versionadded:: 3.0
%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   *
 ************************************************************************/