Class: QgsGeometryUtils¶

class qgis.core.QgsGeometryUtils¶

Bases: sip.wrapper

Contains various geometry utility functions.

New in version 2.10:

Methods

`angleBetweenThreePoints`	Calculates the angle between the lines AB and BC, where AB and BC described by points a, b and b, c.
`angleBisector`	Returns the point (`pointX`, `pointY`) forming the bisector from segment (`aX` `aY`) (`bX` `bY`) and segment (`bX`, `bY`) (`dX`, `dY`).
`angleOnCircle`	Returns `True` if an angle is between angle1 and angle3 on a circle described by angle1, angle2 and angle3.
`averageAngle`	Calculates the average angle (in radians) between the two linear segments from (`x1`, `y1`) to (`x2`, `y2`) and (`x2`, `y2`) to (`x3`, `y3`).
`bisector`	Returns the point (`pointX`, `pointY`) forming the bisector from point (`aX`, `aY`) to the segment (`bX`, `bY`) (`cX`, `cY`).
`ccwAngle`	Returns the counter clockwise angle between a line with components dx, dy and the line with dx > 0 and dy = 0
`circleAngleBetween`	Returns `True` if, in a circle, angle is between angle1 and angle2
`circleCenterRadius`	Returns radius and center of the circle through pt1, pt2, pt3
`circleCircleInnerTangents`	Calculates the inner tangent points for two circles, centered at a center1 and `center2` and with radii of `radius1` and `radius2` respectively.
`circleCircleIntersections`	Calculates the intersections points between the circle with center `center1` and radius `radius1` and the circle with center `center2` and radius `radius2`.
`circleCircleOuterTangents`	Calculates the outer tangent points for two circles, centered at `center1` and `center2` and with radii of `radius1` and `radius2` respectively.
`circleClockwise`	Returns `True` if the circle defined by three angles is ordered clockwise.
`circleLength`	Length of a circular string segment defined by pt1, pt2, pt3
`circleTangentDirection`	Calculates the direction angle of a circle tangent (clockwise from north in radians)
`closestPoint`	Returns the nearest point on a segment of a `geometry` for the specified `point`.
`closestSideOfRectangle`	Returns a number representing the closest side of a rectangle defined by /a right, `bottom`, `left`, `top` to the point at (`x`, `y`), where the point may be in the interior of the rectangle or outside it.
`closestVertex`	Returns the closest vertex to a geometry for a specified point.
`coefficients`	Returns the coefficients (a, b, c for equation "ax + by + c = 0") of a line defined by points `pt1` and `pt2`.
`distToInfiniteLine`	Returns the distance between a point and an infinite line.
`distanceToVertex`	Returns the distance along a geometry from its first vertex to the specified vertex.
`extractLineStrings`	Returns list of linestrings extracted from the passed geometry.
`gradient`	Returns the gradient of a line defined by points `pt1` and `pt2`.
`interpolateArcValue`	Interpolate a value at given angle on circular arc given values (zm1, zm2, zm3) at three different angles (a1, a2, a3).
`interpolatePointOnArc`	Interpolates a point on an arc defined by three points, `pt1`, `pt2` and `pt3`.
`interpolatePointOnLine`	Interpolates the position of a point a `fraction` of the way along the line from (`x1`, `y1`) to (`x2`, `y2`).
`interpolatePointOnLineByValue`	Interpolates the position of a point along the line from (`x1`, `y1`) to (`x2`, `y2`).
`leftOfLine`	Returns a value < 0 if the point (`x`, `y`) is left of the line from (`x1`, `y1`) -> (`x2`, `y2`).
`lineAngle`	Calculates the direction of line joining two points in radians, clockwise from the north direction.
`lineCircleIntersection`	Compute the intersection of a line and a circle.
`lineIntersection`	Computes the intersection between two lines.
`linePerpendicularAngle`	Calculates the perpendicular angle to a line joining two points.
`linesIntersection3D`	An algorithm to calculate an (approximate) intersection of two lines in 3D.
`midpoint`	Returns a middle point between points pt1 and pt2.
`normalizedAngle`	Ensures that an angle is in the range 0 <= angle < 2 pi.
`perpendicularCenterSegment`	Create a perpendicular line segment to a given segment [`segmentPoint1`,``segmentPoint2``] with its center at `centerPoint`.
`perpendicularOffsetPointAlongSegment`	Calculates a point a certain `proportion` of the way along the segment from (`x1`, `y1`) to (`x2`, `y2`), offset from the segment by the specified `offset` amount.
`perpendicularSegment`	Create a perpendicular line segment from p to segment [s1, s2]
`pointContinuesArc`	Returns `True` if point `b` is on the arc formed by points `a1`, `a2`, and `a3`, but not within that arc portion already described by `a1`, `a2` and `a3`.
`pointOnLineWithDistance`	Returns a point a specified `distance` toward a second point.
`projectPointOnSegment`	Project the point on a segment
`segmentIntersection`	Compute the intersection between two segments
`segmentMidPoint`	Calculates midpoint on circle passing through `p1` and `p2`, closest to the given coordinate `mousePos`.
`segmentMidPointFromCenter`	Calculates the midpoint on the circle passing through `p1` and `p2`, with the specified `center` coordinate.
`segmentSide`	For line defined by points pt1 and pt3, find out on which side of the line is point pt3.
`segmentizeArc`	Convert circular arc defined by p1, p2, p3 (p1/p3 being start resp.
`setZValueFromPoints`	A Z dimension is added to `point` if one of the point in the list `points` is in 3D.
`skewLinesDistance`	An algorithm to calculate the shortest distance between two skew lines.
`skewLinesProjection`	A method to project one skew line onto another.
`sqrDistToLine`	Returns the squared distance between a point and a line.
`sqrDistance2D`	Returns the squared 2D distance between two points.
`sweepAngle`	Calculates angle of a circular string part defined by pt1, pt2, pt3
`tangentPointAndCircle`	Calculates the tangent points between the circle with the specified `center` and `radius` and the point `p`.
`transferFirstMValueToPoint`	A M dimension is added to `point` if one of the points in the list `points` contains an M value.
`transferFirstZOrMValueToPoint`	A Z or M dimension is added to `point` if one of the points in the list `points` contains Z or M value.
`transferFirstZValueToPoint`	A Z dimension is added to `point` if one of the point in the list `points` is in 3D.
`triangleArea`	Returns the area of the triangle denoted by the points (`aX`, `aY`), (`bX`, `bY`) and (`cX`, `cY`).
`verticesAtDistance`	Retrieves the vertices which are before and after the interpolated point at a specified distance along a linestring (or polygon boundary).
`weightedPointInTriangle`	Returns a weighted point inside the triangle denoted by the points (`aX`, `aY`), (`bX`, `bY`) and (`cX`, `cY`).

angleBetweenThreePoints(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) → float¶

Calculates the angle between the lines AB and BC, where AB and BC described by points a, b and b, c.

Parameters:

x1 (float) – x-coordinate of point a
y1 (float) – y-coordinate of point a
x2 (float) – x-coordinate of point b
y2 (float) – y-coordinate of point b
x3 (float) – x-coordinate of point c
y3 (float) – y-coordinate of point c

Return type:

float

Returns:

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

angleBisector(aX: float, aY: float, bX: float, bY: float, cX: float, cY: float, dX: float, dY: float) → Tuple[bool, float, float, float]¶

Returns the point (pointX, pointY) forming the bisector from segment (aX aY) (bX bY) and segment (bX, bY) (dX, dY). The bisector segment of AB-CD is (point, projection of point by angle)

Parameters:

aX (float) – x-coordinate of first vertex of the segment ab
aY (float) – y-coordinate of first vertex of the segment ab
bX (float) – x-coordinate of second vertex of the segment ab
bY (float) – y-coordinate of second vertex of the segment ab
cX (float) – x-coordinate of first vertex of the segment cd
cY (float) – y-coordinate of first vertex of the segment cd
dX (float) – x-coordinate of second vertex of the segment cd
dY (float) – y-coordinate of second vertex of the segment cd

Return type:

Tuple[bool, float, float, float]

Returns:

True if the bisector exists (A B and C D are not collinear)
pointX: x-coordinate of generated point
pointY: y-coordinate of generated point
angle: angle of the bisector from pointX, pointY origin on [ab-cd]

New in version 3.18.

angleOnCircle(angle: float, angle1: float, angle2: float, angle3: float) → bool¶

Returns True if an angle is between angle1 and angle3 on a circle described by angle1, angle2 and angle3.

Parameters:

angle (float) –
angle1 (float) –
angle2 (float) –
angle3 (float) –

Return type:

bool

averageAngle(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) → float¶

Calculates the average angle (in radians) between the two linear segments from (x1, y1) to (x2, y2) and (x2, y2) to (x3, y3).

averageAngle(a1: float, a2: float) -> float Averages two angles, correctly handling negative angles and ensuring the result is between 0 and 2 pi.

Parameters:

a1 – first angle (in radians)
a2 – second angle (in radians)
x1 (float) –
y1 (float) –
x2 (float) –
y2 (float) –
x3 (float) –
y3 (float) –

Return type:

float

Returns:

average angle (in radians)

bisector(aX: float, aY: float, bX: float, bY: float, cX: float, cY: float) → Tuple[bool, float, float]¶

Returns the point (pointX, pointY) forming the bisector from point (aX, aY) to the segment (bX, bY) (cX, cY). The bisector segment of ABC is (A-point)

Parameters:

aX (float) – x-coordinate of first vertex in triangle
aY (float) – y-coordinate of first vertex in triangle
bX (float) – x-coordinate of second vertex in triangle
bY (float) – y-coordinate of second vertex in triangle
cX (float) – x-coordinate of third vertex in triangle
cY (float) – y-coordinate of third vertex in triangle

Return type:

Tuple[bool, float, float]

Returns:

True if the bisector exists (A B and C are not collinear)
pointX: x-coordinate of generated point
pointY: y-coordinate of generated point

New in version 3.18.

ccwAngle(dy: float, dx: float) → float¶

Returns the counter clockwise angle between a line with components dx, dy and the line with dx > 0 and dy = 0

Parameters:

dy (float) –
dx (float) –

Return type:

float

circleAngleBetween(angle: float, angle1: float, angle2: float, clockwise: bool) → bool¶

Returns True if, in a circle, angle is between angle1 and angle2

Parameters:

angle (float) –
angle1 (float) –
angle2 (float) –
clockwise (bool) –

Return type:

bool

circleCenterRadius(pt1: QgsPoint, pt2: QgsPoint, pt3: QgsPoint) → Tuple[float, float, float]¶

Returns radius and center of the circle through pt1, pt2, pt3

Parameters:

pt1 (QgsPoint) –
pt2 (QgsPoint) –
pt3 (QgsPoint) –

Return type:

Tuple[float, float, float]

circleCircleInnerTangents(center1: QgsPointXY, radius1: float, center2: QgsPointXY, radius2: float) → Tuple[int, QgsPointXY, QgsPointXY, QgsPointXY, QgsPointXY]¶

Calculates the inner tangent points for two circles, centered at a center1 and center2 and with radii of radius1 and radius2 respectively.

The inner tangent points correspond to the points at which the two lines which are drawn so that they are tangential to both circles and are crossing each other.

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).

New in version 3.6.

Parameters:

center1 (QgsPointXY) –
radius1 (float) –
center2 (QgsPointXY) –
radius2 (float) –

Return type:

Tuple[int, QgsPointXY, QgsPointXY, QgsPointXY, QgsPointXY]

circleCircleIntersections(center1: QgsPointXY, radius1: float, center2: QgsPointXY, radius2: float) → Tuple[int, QgsPointXY, QgsPointXY]¶

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 type:: Tuple[int, QgsPointXY, QgsPointXY]
Returns:: number of intersection points found.

New in version 3.2.

Parameters:

center1 (QgsPointXY) –
radius1 (float) –
center2 (QgsPointXY) –
radius2 (float) –

circleCircleOuterTangents(center1: QgsPointXY, radius1: float, center2: QgsPointXY, radius2: float) → Tuple[int, QgsPointXY, QgsPointXY, QgsPointXY, QgsPointXY]¶

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).

New in version 3.2.

Parameters:

center1 (QgsPointXY) –
radius1 (float) –
center2 (QgsPointXY) –
radius2 (float) –

Return type:

Tuple[int, QgsPointXY, QgsPointXY, QgsPointXY, QgsPointXY]

circleClockwise(angle1: float, angle2: float, angle3: float) → bool¶

Returns True if the circle defined by three angles is ordered clockwise.

The angles are defined counter-clockwise from the origin, i.e. using Euclidean angles as opposed to geographic “North up” angles.

Parameters:

angle1 (float) –
angle2 (float) –
angle3 (float) –

Return type:

bool

circleLength(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) → float¶

Length of a circular string segment defined by pt1, pt2, pt3

Parameters:

x1 (float) –
y1 (float) –
x2 (float) –
y2 (float) –
x3 (float) –
y3 (float) –

Return type:

float

circleTangentDirection(tangentPoint: QgsPoint, cp1: QgsPoint, cp2: QgsPoint, cp3: QgsPoint) → float¶

Calculates the direction angle of a circle tangent (clockwise from north in radians)

Parameters:

tangentPoint (QgsPoint) –
cp1 (QgsPoint) –
cp2 (QgsPoint) –
cp3 (QgsPoint) –

Return type:

float

closestPoint(geometry: QgsAbstractGeometry, point: QgsPoint) → QgsPoint¶

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.

Parameters:

geometry (QgsAbstractGeometry) –
point (QgsPoint) –

Return type:

QgsPoint

closestSideOfRectangle(right: float, bottom: float, left: float, top: float, x: float, y: float) → int¶

Returns a number representing the closest side of a rectangle defined by /a right, bottom, left, top to the point at (x, y), where the point may be in the interior of the rectangle or outside it.

The returned value may be:

Point is closest to top side of rectangle
Point is located on the top-right diagonal of rectangle, equally close to the top and right sides
Point is closest to right side of rectangle
Point is located on the bottom-right diagonal of rectangle, equally close to the bottom and right sides
Point is closest to bottom side of rectangle
Point is located on the bottom-left diagonal of rectangle, equally close to the bottom and left sides
Point is closest to left side of rectangle
Point is located on the top-left diagonal of rectangle, equally close to the top and left sides

Note

This method effectively partitions the space outside of the rectangle into Voronoi cells, so a point to the top left of the rectangle may be assigned to the left or top sides based on its position relative to the diagonal line extended from the rectangle’s top-left corner.

New in version 3.20.

Parameters:

right (float) –
bottom (float) –
left (float) –
top (float) –
x (float) –
y (float) –

Return type:

int

closestVertex(geom: QgsAbstractGeometry, pt: QgsPoint) → Tuple[QgsPoint, QgsVertexId]¶

Returns the closest vertex to a geometry for a specified point. On error null point will be returned and “id” argument will be invalid.

Parameters:

geom (QgsAbstractGeometry) –
pt (QgsPoint) –

Return type:

Tuple[QgsPoint, QgsVertexId]

coefficients(pt1: QgsPoint, pt2: QgsPoint) → Tuple[float, float, float]¶

Returns the coefficients (a, b, c for equation “ax + by + c = 0”) of a line defined by points pt1 and pt2.

Parameters:

pt1 (QgsPoint) – first point.
pt2 (QgsPoint) – second point.

Return type:

Tuple[float, float, float]

Returns:

a: Output parameter, a coefficient of the equation.
b: Output parameter, b coefficient of the equation.
c: Output parameter, c coefficient of the equation.

New in version 3.0.

distToInfiniteLine(point: QgsPoint, linePoint1: QgsPoint, linePoint2: QgsPoint, epsilon: float = 1e-07) → float¶

Returns the distance between a point and an infinite line.

Parameters:

point (QgsPoint) – The point to find the distance to the line
linePoint1 (QgsPoint) – The first point of the line
linePoint2 (QgsPoint) – The second point of the line
epsilon (float = 1e-07) – The tolerance to use

New in version 3.26.

Return type:: float

distanceToVertex(geom: QgsAbstractGeometry, id: QgsVertexId) → float¶

Returns the distance along a geometry from its first vertex to the specified vertex.

Parameters:

geom (QgsAbstractGeometry) – geometry
id (QgsVertexId) – vertex id to find distance to

Return type:

float

Returns:

distance to vertex (following geometry)

New in version 2.16.

extractLineStrings(geom: QgsAbstractGeometry) → List[QgsLineString]¶

Returns list of linestrings extracted from the passed geometry. The returned objects have to be deleted by the caller.

Parameters:: geom (QgsAbstractGeometry) –
Return type:: List[QgsLineString]

gradient(pt1: QgsPoint, pt2: QgsPoint) → float¶

Returns the gradient of a line defined by points pt1 and pt2.

Parameters:

pt1 (QgsPoint) – first point.
pt2 (QgsPoint) – second point.

Return type:

float

Returns:

The gradient of this linear entity, or infinity if vertical

New in version 3.0.

interpolateArcValue(angle: float, a1: float, a2: float, a3: float, zm1: float, zm2: float, zm3: float) → float¶

Interpolate a value at given angle on circular arc given values (zm1, zm2, zm3) at three different angles (a1, a2, a3).

New in version 3.0.

Parameters:

angle (float) –
a1 (float) –
a2 (float) –
a3 (float) –
zm1 (float) –
zm2 (float) –
zm3 (float) –

Return type:

float

interpolatePointOnArc(pt1: QgsPoint, pt2: QgsPoint, pt3: QgsPoint, distance: float) → QgsPoint¶

Interpolates a point on an arc defined by three points, pt1, pt2 and pt3. The arc will be interpolated by the specified distance from pt1.

Any z or m values present in the points will also be linearly interpolated in the output.

New in version 3.4.

Parameters:

pt1 (QgsPoint) –
pt2 (QgsPoint) –
pt3 (QgsPoint) –
distance (float) –

Return type:

QgsPoint

interpolatePointOnLine(x1: float, y1: float, x2: float, y2: float, fraction: float) → QgsPointXY¶

Interpolates the position of a point a fraction of the way along the line from (x1, y1) to (x2, y2).

Usually the fraction should be between 0 and 1, where 0 represents the point at the start of the line (x1, y1) and 1 represents the end of the line (x2, y2). However, it is possible to use a fraction < 0 or > 1, in which case the returned point is extrapolated from the supplied line.

See also

interpolatePointOnLineByValue()

New in version 3.0.2.

interpolatePointOnLine(p1: QgsPoint, p2: QgsPoint, fraction: float) -> QgsPoint Interpolates the position of a point a fraction of the way along the line from p1 to p2.

Usually the fraction should be between 0 and 1, where 0 represents the point at the start of the line (p1) and 1 represents the end of the line (p2). However, it is possible to use a fraction < 0 or > 1, in which case the returned point is extrapolated from the supplied line.

Any Z or M values present in the input points will also be interpolated and present in the returned point.

See also

interpolatePointOnLineByValue()

New in version 3.0.2.

Parameters:

x1 (float) –
y1 (float) –
x2 (float) –
y2 (float) –
fraction (float) –

Return type:

QgsPointXY

interpolatePointOnLineByValue(x1: float, y1: float, v1: float, x2: float, y2: float, v2: float, value: float) → QgsPointXY¶

Interpolates the position of a point along the line from (x1, y1) to (x2, y2).

The position is interpolated using a supplied target value and the value at the start of the line (v1) and end of the line (v2). The returned point will be linearly interpolated to match position corresponding to the target value.

See also

interpolatePointOnLine()

New in version 3.0.2.

Parameters:

x1 (float) –
y1 (float) –
v1 (float) –
x2 (float) –
y2 (float) –
v2 (float) –
value (float) –

Return type:

QgsPointXY

leftOfLine(x: float, y: float, x1: float, y1: float, x2: float, y2: float) → int¶

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.

leftOfLine(point: QgsPoint, p1: QgsPoint, p2: QgsPoint) -> int Returns a value < 0 if the point point is left of the line from p1 -> p2. 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.

New in version 3.6.

Parameters:

x (float) –
y (float) –
x1 (float) –
y1 (float) –
x2 (float) –
y2 (float) –

Return type:

int

lineAngle(x1: float, y1: float, x2: float, y2: float) → float¶

Calculates the direction of line joining two points in radians, clockwise from the north direction.

Parameters:

x1 (float) – x-coordinate of line start
y1 (float) – y-coordinate of line start
x2 (float) – x-coordinate of line end
y2 (float) – y-coordinate of line end

Return type:

float

Returns:

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

lineCircleIntersection(center: QgsPointXY, radius: float, linePoint1: QgsPointXY, linePoint2: QgsPointXY, intersection: QgsPointXY) → Tuple[bool, QgsPointXY]¶

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.

Parameters:

center (QgsPointXY) – the center of the circle
radius (float) – the radius of the circle
linePoint1 (QgsPointXY) – a first point on the line
linePoint2 (QgsPointXY) – a second point on the line
intersection (QgsPointXY) – the initial point and the returned intersection point

Return type:

Tuple[bool, QgsPointXY]

Returns:

True if an intersection has been found

lineIntersection(p1: QgsPoint, v1: QgsVector, p2: QgsPoint, v2: QgsVector) → Tuple[bool, QgsPoint]¶

Computes the intersection between two lines. Z dimension is supported and is retrieved from the first 3D point amongst p1 and p2.

Parameters:

p1 (QgsPoint) – Point on the first line
v1 (QgsVector) – Direction vector of the first line
p2 (QgsPoint) – Point on the second line
v2 (QgsVector) – Direction vector of the second line

Return type:

Tuple[bool, QgsPoint]

Returns:

Whether the lines intersect
intersection: Output parameter, the intersection point

linePerpendicularAngle(x1: float, y1: float, x2: float, y2: float) → float¶

Calculates the perpendicular angle to a line joining two points. Returned angle is in radians, clockwise from the north direction.

Parameters:

x1 (float) – x-coordinate of line start
y1 (float) – y-coordinate of line start
x2 (float) – x-coordinate of line end
y2 (float) – y-coordinate of line end

Return type:

float

Returns:

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

linesIntersection3D(La1: QgsVector3D, La2: QgsVector3D, Lb1: QgsVector3D, Lb2: QgsVector3D) → Tuple[bool, QgsVector3D]¶

An algorithm to calculate an (approximate) intersection of two lines in 3D.

Parameters:

La1 (QgsVector3D) – is the first point on the first line,
La2 (QgsVector3D) – is the second point on the first line,
Lb1 (QgsVector3D) – is the first point on the second line,
Lb2 (QgsVector3D) – is the second point on the second line,

Return type:

Tuple[bool, QgsVector3D]

Returns:

True if the intersection can be found, False - otherwise.
intersection: is the result intersection, of it can be found.

Example¶

QgsGeometryUtils.linesIntersection3D(QgsVector3D(0,0,0), QgsVector3D(5,0,0), QgsVector3D(2,1,0), QgsVector3D(2,3,0))
# (True, PyQt5.QtGui.QgsVector3D(2.0, 0.0, 0.0))
QgsGeometryUtils.linesIntersection3D(QgsVector3D(0,0,0), QgsVector3D(5,0,0), QgsVector3D(2,1,0), QgsVector3D(2,0,0))
# (True, PyQt5.QtGui.QgsVector3D(2.0, 0.0, 0.0))
QgsGeometryUtils.linesIntersection3D(QgsVector3D(0,0,0), QgsVector3D(5,0,0), QgsVector3D(0,1,0), QgsVector3D(0,3,0))
# (True, PyQt5.QtGui.QgsVector3D(0.0, 0.0, 0.0))
QgsGeometryUtils.linesIntersection3D(QgsVector3D(0,0,0), QgsVector3D(5,0,0), QgsVector3D(0,1,0), QgsVector3D(0,0,0))
# (True, PyQt5.QtGui.QgsVector3D(0.0, 0.0, 0.0))
QgsGeometryUtils.linesIntersection3D(QgsVector3D(0,0,0), QgsVector3D(5,0,0), QgsVector3D(5,1,0), QgsVector3D(5,3,0))
# (False, PyQt5.QtGui.QgsVector3D(0.0, 0.0, 0.0))
QgsGeometryUtils.linesIntersection3D(QgsVector3D(0,0,0), QgsVector3D(5,0,0), QgsVector3D(5,1,0), QgsVector3D(5,0,0))
# (False, PyQt5.QtGui.QgsVector3D(0.0, 0.0, 0.0))
QgsGeometryUtils.linesIntersection3D(QgsVector3D(1,1,0), QgsVector3D(2,2,0), QgsVector3D(3,1,0), QgsVector3D(3,2,0))
# (True, PyQt5.QtGui.QgsVector3D(3.0, 3.0, 0.0))
QgsGeometryUtils.linesIntersection3D(QgsVector3D(1,1,0), QgsVector3D(2,2,0), QgsVector3D(3,2,0), QgsVector3D(3,1,0))
# (True, PyQt5.QtGui.QgsVector3D(3.0, 3.0, 0.0))
QgsGeometryUtils.linesIntersection3D(QgsVector3D(5,5,5), QgsVector3D(0,0,0), QgsVector3D(0,5,5), QgsVector3D(5,0,0))
# (True, PyQt5.QtGui.QgsVector3D(2.5, 2.5, 2.5))
QgsGeometryUtils.linesIntersection3D(QgsVector3D(2.5,2.5,2.5), QgsVector3D(0,5,0), QgsVector3D(2.5,2.5,2.5), QgsVector3D(5,0,0))
# (True, PyQt5.QtGui.QgsVector3D(2.5, 2.5, 2.5))
QgsGeometryUtils.linesIntersection3D(QgsVector3D(2.5,2.5,2.5), QgsVector3D(5,0,0), QgsVector3D(0,5,5), QgsVector3D(5,5,5))
# (True, PyQt5.QtGui.QgsVector3D(0.0, 5.0, 5.0))

midpoint(pt1: QgsPoint, pt2: QgsPoint) → QgsPoint¶

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.

Parameters:

pt1 (QgsPoint) – first point.
pt2 (QgsPoint) – second point.

Return type:

QgsPoint

Returns:

New point at middle between points pt1 and pt2.

Example¶

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)'

New in version 3.0.

normalizedAngle(angle: float) → float¶

Ensures that an angle is in the range 0 <= angle < 2 pi.

Parameters:: angle (float) – angle in radians
Return type:: float
Returns:: equivalent angle within the range [0, 2 pi)

perpendicularCenterSegment(centerPointX: float, centerPointY: float, segmentPoint1x: float, segmentPoint1y: float, segmentPoint2x: float, segmentPoint2y: float, segmentLength: float = 0) → Tuple[float, float, float, float]¶

Create a perpendicular line segment to a given segment [segmentPoint1,``segmentPoint2``] with its center at centerPoint.

May be used to split geometries. Unless segmentLength is specified the new centered perpendicular line segment will have double the length of the input segment.

The result is a line (segment) centered in point p and perpendicular to segment [segmentPoint1, segmentPoint2].

Parameters:

centerPointX (float) – x-coordinate of the point where the center of the perpendicular should be located
centerPointY (float) – y-coordinate of the point where the center of the perpendicular should be located
segmentPoint1x (float) – : x-coordinate of segmentPoint1, the segment’s start point
segmentPoint1y (float) – : y-coordinate of segmentPoint1, the segment’s start point
segmentPoint2x (float) – : x-coordinate of segmentPoint2, the segment’s end point
segmentPoint2y (float) – : y-coordinate of segmentPoint2, the segment’s end point
perpendicularSegmentPoint1x – : x-coordinate of the perpendicularCenterSegment’s start point
perpendicularSegmentPoint1y – : y-coordinate of the perpendicularCenterSegment’s start point
perpendicularSegmentPoint2x – : x-coordinate of the perpendicularCenterSegment’s end point
perpendicularSegmentPoint2y – : y-coordinate of the perpendicularCenterSegment’s end point
segmentLength (float = 0) – (optional) Trims to given length. A segmentLength value of 0 refers to the default length which is double the length of the input segment. Set to 1 for a normalized length.

New in version 3.24.

Return type:: Tuple[float, float, float, float]

perpendicularOffsetPointAlongSegment(x1: float, y1: float, x2: float, y2: float, proportion: float, offset: float) → Tuple[float, float]¶

Calculates a point a certain proportion of the way along the segment from (x1, y1) to (x2, y2), offset from the segment by the specified offset amount.

Parameters:

x1 (float) – x-coordinate of start of segment
y1 (float) – y-coordinate of start of segment
x2 (float) – x-coordinate of end of segment
y2 (float) – y-coordinate of end of segment
proportion (float) – proportion of the segment’s length at which to place the point (between 0.0 and 1.0)
offset (float) – perpendicular offset from segment to apply to point. A negative offset shifts the point to the left of the segment, while a positive offset will shift it to the right of the segment.

Example¶

# Offset point at center of segment by 2 units to the right
x, y = QgsGeometryUtils.perpendicularOffsetPointAlongSegment( 1, 5, 11, 5, 0.5, 2 )
# (6.0, 3.0)

# Offset point at center of segment by 2 units to the left
x, y = QgsGeometryUtils.perpendicularOffsetPointAlongSegment( 1, 5, 11, 5, 0.5, -2 )
# (6.0, 7.0)

rtype:

Tuple[float, float]

return:

x: calculated point x-coordinate
y: calculated point y-coordinate

New in version 3.20.

perpendicularSegment(p: QgsPoint, s1: QgsPoint, s2: QgsPoint) → QgsLineString¶

Create a perpendicular line segment from p to segment [s1, s2]

Parameters:

p (QgsPoint) – The point
s1 (QgsPoint) – The segment start point
s2 (QgsPoint) – The segment end point

Return type:

QgsLineString

Returns:

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

pointContinuesArc(a1: QgsPoint, a2: QgsPoint, a3: QgsPoint, b: QgsPoint, distanceTolerance: float, pointSpacingAngleTolerance: float) → bool¶

Returns True if point b is on the arc formed by points a1, a2, and a3, but not within that arc portion already described by a1, a2 and a3.

The distanceTolerance specifies the maximum deviation allowed between the original location of point b and where it would fall on the candidate arc.

This method only consider a segments as continuing an arc if the points are all regularly spaced on the candidate arc. The pointSpacingAngleTolerance parameter specifies the maximum angular deviation (in radians) allowed when testing for regular point spacing.

Note

The API is considered EXPERIMENTAL and can be changed without a notice

New in version 3.14.

Parameters:

a1 (QgsPoint) –
a2 (QgsPoint) –
a3 (QgsPoint) –
b (QgsPoint) –
distanceTolerance (float) –
pointSpacingAngleTolerance (float) –

Return type:

bool

pointOnLineWithDistance(startPoint: QgsPoint, directionPoint: QgsPoint, distance: float) → QgsPoint¶

Returns a point a specified distance toward a second point.

Parameters:

startPoint (QgsPoint) –
directionPoint (QgsPoint) –
distance (float) –

Return type:

QgsPoint

projectPointOnSegment(p: QgsPoint, s1: QgsPoint, s2: QgsPoint) → QgsPoint¶

Project the point on a segment

Parameters:

p (QgsPoint) – The point
s1 (QgsPoint) – The segment start point
s2 (QgsPoint) – The segment end point

Return type:

QgsPoint

Returns:

The projection of the point on the segment

segmentIntersection(p1: QgsPoint, p2: QgsPoint, q1: QgsPoint, q2: QgsPoint, tolerance: float = 1e-08, acceptImproperIntersection: bool = False) → Tuple[bool, QgsPoint, bool]¶

Compute the intersection between two segments

Parameters:

p1 (QgsPoint) – First segment start point
p2 (QgsPoint) – First segment end point
q1 (QgsPoint) – Second segment start point
q2 (QgsPoint) – Second segment end point
tolerance (float = 1e-08) – The tolerance to use
acceptImproperIntersection (bool = False) – 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 type:

Tuple[bool, QgsPoint, bool]

Returns:

Whether the segments intersect
intersectionPoint: Output parameter, the intersection point
isIntersection: Output parameter, return True if an intersection is found

Example¶

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)

segmentMidPoint(p1: QgsPoint, p2: QgsPoint, radius: float, mousePos: QgsPoint) → Tuple[bool, QgsPoint]¶

Calculates midpoint on circle passing through p1 and p2, closest to the given coordinate mousePos. Z dimension is supported and is retrieved from the first 3D point amongst p1 and p2.

See also

segmentMidPointFromCenter()

Parameters:

p1 (QgsPoint) –
p2 (QgsPoint) –
radius (float) –
mousePos (QgsPoint) –

Return type:

Tuple[bool, QgsPoint]

segmentMidPointFromCenter(p1: QgsPoint, p2: QgsPoint, center: QgsPoint, useShortestArc: bool = True) → QgsPoint¶

Calculates the midpoint on the circle passing through p1 and p2, with the specified center coordinate.

If useShortestArc is True, then the midpoint returned will be that corresponding to the shorter arc from p1 to p2. If it is False, the longer arc from p1 to p2 will be used (i.e. winding the other way around the circle).

See also

segmentMidPoint()

New in version 3.2.

Parameters:

p1 (QgsPoint) –
p2 (QgsPoint) –
center (QgsPoint) –
useShortestArc (bool = True) –

Return type:

QgsPoint

segmentSide(pt1: QgsPoint, pt3: QgsPoint, pt2: QgsPoint) → int¶

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.

New in version 3.0.

Parameters:

pt1 (QgsPoint) –
pt3 (QgsPoint) –
pt2 (QgsPoint) –

Return type:

int

segmentizeArc(p1: QgsPoint, p2: QgsPoint, p3: QgsPoint, tolerance: float = M_PI_2 / 90, toleranceType: QgsAbstractGeometry.SegmentationToleranceType = QgsAbstractGeometry.MaximumAngle, hasZ: bool = False, hasM: bool = False) → List[QgsPoint]¶

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.

New in version 3.0.

Parameters:

p1 (QgsPoint) –
p2 (QgsPoint) –
p3 (QgsPoint) –
tolerance (float = M_PI_2/90) –
toleranceType (QgsAbstractGeometry.SegmentationToleranceType = QgsAbstractGeometry.MaximumAngle) –
hasZ (bool = False) –
hasM (bool = False) –

Return type:

List[QgsPoint]

setZValueFromPoints(points: Iterable[QgsPoint], point: QgsPoint) → bool¶

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 the first Z value found in list points even if point already contains a Z value.

Parameters:

points (Iterable[QgsPoint]) – List of points in which a 3D point is searched.
point (QgsPoint) – The point to update with Z dimension and value.

Return type:

bool

Returns:

True if the point is updated, False otherwise

Warning

This method does not copy the z value of the coordinate from the points whose z value is closest to the original x/y point, but only the first one found.

New in version 3.0.

Deprecated since version QGIS: 3.20 use transferFirstZValueToPoint( const QgsPointSequence &points, QgsPoint &point ) instead

skewLinesDistance(P1: QgsVector3D, P12: QgsVector3D, P2: QgsVector3D, P22: QgsVector3D) → float¶

An algorithm to calculate the shortest distance between two skew lines.

Parameters:

P1 (QgsVector3D) – is the first point of the first line,
P12 (QgsVector3D) – is the second point on the first line,
P2 (QgsVector3D) – is the first point on the second line,
P22 (QgsVector3D) – is the second point on the second line.

Return type:

float

Returns:

the shortest distance

skewLinesProjection(P1: QgsVector3D, P12: QgsVector3D, P2: QgsVector3D, P22: QgsVector3D, epsilon: float = 0.0001) → Tuple[bool, QgsVector3D]¶

A method to project one skew line onto another.

Parameters:

P1 (QgsVector3D) – is a first point that belonds to first skew line,
P12 (QgsVector3D) – is the second point that belongs to first skew line,
P2 (QgsVector3D) – is the first point that belongs to second skew line,
P22 (QgsVector3D) – is the second point that belongs to second skew line,
X1 – is the result projection point of line P2P22 onto line P1P12,
epsilon (float = 0.0001) – the tolerance to use.

Return type:

Tuple[bool, QgsVector3D]

Returns:

True if such point exists, False - otherwise.

sqrDistToLine(ptX: float, ptY: float, x1: float, y1: float, x2: float, y2: float, epsilon: float) → Tuple[float, float, float]¶

Returns the squared distance between a point and a line.

Parameters:

ptX (float) –
ptY (float) –
x1 (float) –
y1 (float) –
x2 (float) –
y2 (float) –
epsilon (float) –

Return type:

Tuple[float, float, float]

sqrDistance2D(pt1: QgsPoint, pt2: QgsPoint) → float¶

Returns the squared 2D distance between two points.

Parameters:

pt1 (QgsPoint) –
pt2 (QgsPoint) –

Return type:

float

sweepAngle(centerX: float, centerY: float, x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) → float¶

Calculates angle of a circular string part defined by pt1, pt2, pt3

Parameters:

centerX (float) –
centerY (float) –
x1 (float) –
y1 (float) –
x2 (float) –
y2 (float) –
x3 (float) –
y3 (float) –

Return type:

float

tangentPointAndCircle(center: QgsPointXY, radius: float, p: QgsPointXY) → Tuple[bool, QgsPointXY, QgsPointXY]¶

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.

New in version 3.2.

Parameters:

center (QgsPointXY) –
radius (float) –
p (QgsPointXY) –

Return type:

Tuple[bool, QgsPointXY, QgsPointXY]

transferFirstMValueToPoint(points: Iterable[QgsPoint], point: QgsPoint) → bool¶

A M dimension is added to point if one of the points in the list points contains an M value. Moreover, the M value of point is updated with the first M value found in list points even if point already contains a M value.

Parameters:

points (Iterable[QgsPoint]) – List of points in which a M point is searched.
point (QgsPoint) – The point to update with M dimension and value.

Return type:

bool

Returns:

True if the point is updated, False otherwise

Warning

This method does not copy the m value of the coordinate from the points whose m value is closest to the original x/y point, but only the first one found.

New in version 3.20.

transferFirstZOrMValueToPoint(points: Iterable[QgsPoint], point: QgsPoint) → bool¶

A Z or M dimension is added to point if one of the points in the list points contains Z or M value.

This method is equivalent to successively calling Z and M but avoiding looping twice over the set of points.

Parameters:

points (Iterable[QgsPoint]) – List of points in which a M point is searched.
point (QgsPoint) – The point to update with Z or M dimension and value.

Returns:

True if the point is updated, False otherwise

Warning

This method does not copy the z or m value of the coordinate from the points whose z or m value is closest to the original x/y point, but only the first one found.

New in version 3.20.

transferFirstZOrMValueToPoint(geom: QgsGeometry, point: QgsPoint) -> bool A Z or M dimension is added to point if one of the points in the list points contains Z or M value.

This method is equivalent to successively calling Z and M but avoiding looping twice over the set of points.

Parameters:

geom – geometry in which a M point is searched.
point – The point to update with Z or M dimension and value.

Return type:

bool

Returns:

True if the point is updated, False otherwise

Warning

This method does not copy the z or m value of the coordinate from the points whose z or m value is closest to the original x/y point, but only the first one found.

New in version 3.20.

transferFirstZValueToPoint(points: Iterable[QgsPoint], point: QgsPoint) → bool¶

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 the first Z value found in list points even if point already contains a Z value.

Parameters:

points (Iterable[QgsPoint]) – List of points in which a 3D point is searched.
point (QgsPoint) – The point to update with Z dimension and value.

Return type:

bool

Returns:

True if the point is updated, False otherwise

Warning

This method does not copy the z value of the coordinate from the points whose z value is closest to the original x/y point, but only the first one found.

New in version 3.20.

triangleArea(aX: float, aY: float, bX: float, bY: float, cX: float, cY: float) → float¶

Returns the area of the triangle denoted by the points (aX, aY), (bX, bY) and (cX, cY).

New in version 3.10.

Parameters:

aX (float) –
aY (float) –
bX (float) –
bY (float) –
cX (float) –
cY (float) –

Return type:

float

verticesAtDistance(geometry: QgsAbstractGeometry, distance: float) → Tuple[bool, QgsVertexId, QgsVertexId]¶

Retrieves the vertices which are before and after the interpolated point at a specified distance along a linestring (or polygon boundary).

Parameters:

geometry (QgsAbstractGeometry) – line or polygon geometry
distance (float) – distance to traverse along geometry
previousVertex – will be set to previous vertex ID

Return type:

Tuple[bool, QgsVertexId, QgsVertexId]

Returns:

True if vertices were successfully retrieved
nextVertex: will be set to next vertex ID

Note

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

New in version 3.0.

weightedPointInTriangle(aX: float, aY: float, bX: float, bY: float, cX: float, cY: float, weightB: float, weightC: float) → Tuple[float, float]¶

Returns a weighted point inside the triangle denoted by the points (aX, aY), (bX, bY) and (cX, cY).

Parameters:

aX (float) – x-coordinate of first vertex in triangle
aY (float) – y-coordinate of first vertex in triangle
bX (float) – x-coordinate of second vertex in triangle
bY (float) – y-coordinate of second vertex in triangle
cX (float) – x-coordinate of third vertex in triangle
cY (float) – y-coordinate of third vertex in triangle
weightB (float) – weighting factor along axis A-B (between 0 and 1)
weightC (float) – weighting factor along axis A-C (between 0 and 1)

Return type:

Tuple[float, float]

Returns:

pointX: x-coordinate of generated point
pointY: y-coordinate of generated point

New in version 3.10.