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

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.

New in version 3.0.2.

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

New in version 3.0.2.

`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 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 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 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. 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 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 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 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). Whether the segments intersect
• Example:
```ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, 0 ), QgsPoint( 0, 1 ), QgsPoint( 1, 1 ), QgsPoint( 1, 0 ) )
ret, ret.asWkt(), ret
# 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, ret.asWkt(), ret
# (False, 'Point (0 5)', True)
ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, 0 ), QgsPoint( 0, 5 ), QgsPoint( 0, 5 ), QgsPoint( 1, 5 ), acceptImproperIntersection=True )
ret, ret.asWkt(), ret
# (True, 'Point (0 5)', True)
ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, 0 ), QgsPoint( 0, 5 ), QgsPoint( 0, 2 ), QgsPoint( 1, 5 ) )
ret, ret.asWkt(), ret
# (False, 'Point (0 2)', True)
ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, 0 ), QgsPoint( 0, 5 ), QgsPoint( 0, 2 ), QgsPoint( 1, 5 ), acceptImproperIntersection=True )
ret, ret.asWkt(), ret
# (True, 'Point (0 2)', True)
ret = QgsGeometryUtils.segmentIntersection( QgsPoint( 0, -5 ), QgsPoint( 0, 5 ), QgsPoint( 2, 0 ), QgsPoint( -1, 0 ) )
ret, ret.asWkt(), ret
# (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. 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 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.