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 specifiedpoint
.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
andpt2
.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
andpt2
.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 listpoints
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 specifiedpoint
. 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
andpt2
.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
andpt2
.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 afraction
< 0 or > 1, in which case the returned point is extrapolated from the supplied line.New in version 3.0.2.
See also
interpolatePointOnLine(p1: QgsPoint, p2: QgsPoint, fraction: float) -> QgsPoint Interpolates the position of a point a
fraction
of the way along the line fromp1
top2
.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 afraction
< 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.
See also
-
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 targetvalue
.New in version 3.0.2.
See also
-
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
andp2
.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
andp2
.
-
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 listpoints
is in 3D. Moreover, the Z value ofpoint
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.
-