Subgroup: Geometry

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.
`angleOnCircle`	Returns true if an angle is between angle1 and angle3 on a circle described by angle1, angle2 and angle3.
`averageAngle`	Angle between two linear segments
`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
`circleClockwise`	Returns true if circle 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`.
`closestVertex`	Returns the closest vertex to a geometry for a specified point.
`coefficients`	Return the coefficients (a, b, c for equation “ax + by + c = 0”) of a line defined by points `pt1` and `pt2`.
`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`	Return 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).
`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.
`midpoint`	Returns a middle point between points pt1 and pt2.
`normalizedAngle`	Ensures that an angle is in the range 0 <= angle < 2 pi.
`perpendicularSegment`	Create a perpendicular line segment from p to segment [s1, s2]
`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 given 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.
`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
`verticesAtDistance`	Retrieves the vertices which are before and after the interpolated point at a specified distance along a linestring (or polygon boundary).

Signals

Attributes

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 – x-coordinate of point a y1 – y-coordinate of point a x2 – x-coordinate of point b y2 – y-coordinate of point b x3 – x-coordinate of point c y3 – y-coordinate of point c
Returns:	angle between lines in radians. Returned value is undefined if two or more points are equal.

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.

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

Angle between two linear segments

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)
Returns:	average angle (in radians)

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

circleAngleBetween(angle: float, angle1: float, angle2: float, clockwise: bool) → bool¶: Returns true if, in a circle, angle is between angle1 and angle2

circleCenterRadius(pt1: QgsPoint, pt2: QgsPoint, pt3: QgsPoint) → Tuple[float, float, float]¶: Returns radius and center of the circle through pt1, pt2, pt3

circleClockwise(angle1: float, angle2: float, angle3: float) → bool¶: Returns true if circle is ordered clockwise

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

circleTangentDirection(tangentPoint: QgsPoint, cp1: QgsPoint, cp2: QgsPoint, cp3: QgsPoint) → float¶: Calculates the direction angle of a circle tangent (clockwise from north in radians)

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.

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.

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

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

Parameters:	pt1 – first point. pt2 – second point. 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.

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

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

Parameters:	geom – geometry id – vertex id to find distance to
Returns:	distance to vertex (following geometry)

New in version 2.16.

extractLineStrings(geom: QgsAbstractGeometry) → object¶: Returns list of linestrings extracted from the passed geometry. The returned objects have to be deleted by the caller.

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

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

Parameters:	pt1 – first point. pt2 – second point.
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.

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.

New in version 3.0.2.

See also

interpolatePointOnLine()

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.

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 – x-coordinate of line start y1 – y-coordinate of line start x2 – x-coordinate of line end y2 – y-coordinate of line end
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. @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

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 – Point on the first line v1 – Direction vector of the first line p2 – Point on the second line v2 – Direction vector of the second line intersection – Output parameter, the intersection point
Returns:	Whether the lines intersect

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 – x-coordinate of line start y1 – y-coordinate of line start x2 – x-coordinate of line end y2 – y-coordinate of line end
Returns:	angle in radians. Returned value is undefined if start and end point are the same.

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 – first point. pt2 – second point.
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 – angle in radians
Returns:	equivalent angle within the range [0, 2 pi)

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

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

Parameters:	p – The point s1 – The segment start point s2 – The segment end point
Returns:	A line (segment) from p to perpendicular point on segment [s1, s2]

pointOnLineWithDistance(startPoint: QgsPoint, directionPoint: QgsPoint, distance: float) → QgsPoint¶: Returns a point a specified distance toward a second point.

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

Project the point on a segment

Parameters:	p – The point s1 – The segment start point s2 – The segment end point
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 – First segment start point
p2 – First segment end point
q1 – Second segment start point
q2 – Second segment end point
intersectionPoint – Output parameter, the intersection point
isIntersection – Output parameter, return true if an intersection is found
tolerance – The tolerance to use
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).

Returns:

Whether the segments intersect

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 given coordinate. Z dimension is supported and is retrieved from the first 3D point amongst p1 and p2.

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.

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.

setZValueFromPoints(points: object, 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.

Parameters:	points – List of points in which a 3D point is searched. point – The point to update with Z dimension and value.
Returns:	true if the point is updated, false otherwise

New in version 3.0.

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.

sqrDistance2D(pt1: QgsPoint, pt2: QgsPoint) → float¶: Returns the squared 2D distance between two points.

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

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 – line or polygon geometry distance – distance to traverse along geometry previousVertex – will be set to previous vertex ID nextVertex – will be set to next vertex ID
Returns:	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

New in version 3.0.